Skip to main content

HttpSearchParams

An extended HTTP search params object with a strictly-typed schema. Fully compatible with the built-in URLSearchParams class.

import { HttpSearchParams } from '@zimic/http';

const searchParams = new HttpSearchParams<{
  names?: string[];
  page?: `${number}`;
}>({
  names: ['user 1', 'user 2'],
  page: '1',
});

const names = searchParams.getAll('names');
console.log(names); // ['user 1', 'user 2']

const page = searchParams.get('page');
console.log(page); // '1'

constructor()​

Creates a new HttpSearchParams instance, optionally initialized with a plain object or another search params instance.

new HttpSearchParams<Schema>();
new HttpSearchParams<Schema>(init);

Arguments:

  1. init: HttpSearchParamsInit | undefined

    A URL search params string, a plain object, another search params instance, or an array of tuples with (name, value) pairs to initialize the search params with. If not provided, the created search params will be empty.

Type arguments:

  1. Schema: HttpSearchParamsSchema.Loose

    An object type whose keys are the search param names and values are the expected types of those params. This schema is used to enforce type safety when using the search params instance.

searchParams.set()​

Sets a search parameter value. If the value already exists, it will be replaced.

searchParams.set(name, value);

Arguments:

  1. name: string

    The name of the search parameter to set.

  2. value: string

    The value to set for the search parameter.

Related:

searchParams.append()​

Appends a value to a search parameter, or adds the search parameter if it does not exist.

searchParams.append(name, value);

Arguments:

  1. name: string

    The name of the search parameter to append to.

  2. value: string

    The value to append for the search parameter.

Related:

searchParams.get()​

Retrieves the value of a given search parameter. If the value of the key is an array in the schema, use searchParams.getAll() instead.

searchParams.get(name);

Arguments:

  1. name: string

    The name of the search parameter to retrieve.

Returns: string | null

The value of the search parameter, or null if it does not exist.

Related:

searchParams.getAll()​

Retrieves all values of a given search parameter. If the value of the key is not an array in the schema, use searchParams.get() instead.

searchParams.getAll(name);

Arguments:

  1. name: string

    The name of the search parameter to retrieve.

Returns: string[]

An array of values for the search parameter, or an empty array if it does not exist.

Related:

searchParams.has()​

Checks if a search parameter with the given name exists.

searchParams.has(name);
searchParams.has(name, value);

Arguments:

  1. name: string

    The name of the search parameter to check.

  2. value: string | undefined

    The value of the search parameter to check.

Returns: boolean

true if the search parameter exists, false otherwise.

Related:

searchParams.delete()​

Deletes a search parameter with the given name.

searchParams.delete(name);
searchParams.delete(name, value);

Arguments:

  1. name: string

    The name of the search parameter to delete.

  2. value: string | undefined

    The value of the search parameter to delete. If not provided, all parameters with the given name will be deleted.

Related:

searchParams.forEach()​

Executes a function for each search parameter (name, value) pair.

searchParams.forEach(callback);
searchParams.forEach(callback, thisArg);

Arguments:

  1. callback: (value: string, name: string, searchParams: HttpSearchParams) => void

    A function that will be called for each search parameter.

  2. thisArg: HttpSearchParams | undefined

    An optional value to use as this when executing the callback function.

Related:

searchParams.keys()​

searchParams.keys();

Returns: Iterator<string>

An iterator over all search parameter names.

Related:

searchParams.values()​

searchParams.values();

Returns: Iterator<string>

An iterator over all search parameter values.

Related:

searchParams.entries()​

searchParams.entries();

Returns: Iterator<[string, string]>

An iterator over all search parameter (name, value) pairs.

Related:

searchParams.equals()​

Compares an HttpSearchParams instance with another to check if they are equal. Equality is defined as having the same keys and values, regardless of the order of the keys.

searchParams.equals(otherSearchParams);

Arguments:

  1. otherSearchParams: HttpSearchParams

    Another HttpSearchParams instance to compare with.

Returns: boolean

true if the two search parameters are equal, false otherwise.

searchParams.contains()​

Checks if an HttpSearchParams instance contains all keys and values of another HttpSearchParams instance.

searchParams.contains(otherSearchParams);

Arguments:

  1. otherSearchParams: HttpSearchParams

    Another HttpSearchParams instance to check against.

Returns: boolean

true if the current search parameters contain all keys and values of the other search parameters, false otherwise.

searchParams.assign()​

Assigns another HttpSearchParams instance to the current instance, similarly to Object.assign(). Only the instance where this method is called will be modified.

searchParams.assign(otherSearchParams);

Returns: void

const searchParams = new HttpSearchParams({
  names: ['user 1'],
  page: '1',
});

const otherSearchParams = new HttpSearchParams({
  names: ['user 2'],
});

searchParams.assign(otherSearchParams);

console.log(searchParams.getAll('names')); // ['user 2']
console.log(searchParams.get('page')); // '1'

searchParams.toObject()​

Converts the HttpSearchParams instance to a plain object. This method is useful for serialization and debugging purposes.

searchParams.toObject();

Returns: Record<string, string | string[]>

A plain object representation of the search parameters. If a key has multiple values, the object will contain an array of values for that key. If the key has only one value, the object will contain its value directly, without an array, regardless of how the value was initialized when creating the search params object.

const searchParams = new HttpSearchParams({
  names: ['user 1', 'user 2'],
  page: '1',
});

const object = searchParams.toObject();
console.log(object); // { names: ['user 1', 'user 2'], page: '1' }