UrlParams
Models URL query parameters as ordered string pairs.
UrlParams is used for HTTP client query strings, URL-encoded form bodies, and server-side decoding. Values can be built from records, iterables, or native URLSearchParams, then updated, serialized, converted to a URL, or decoded with schemas.
Combinators
Signature
declare const append: {
(key: string, value: Coercible): (self: UrlParams) => UrlParams;
(self: UrlParams, key: string, value: Coercible): UrlParams;
};Appends all query parameters produced from the supplied input.
Details
Existing parameters are preserved.
Signature
declare const appendAll: {
(input: Input): (self: UrlParams) => UrlParams;
(self: UrlParams, input: Input): UrlParams;
};Returns all values for a query parameter key in insertion order.
Details
Returns an empty array when the key is absent.
Signature
declare const getAll: {
(key: string): (self: UrlParams) => readonly Array<string>;
(self: UrlParams, key: string): readonly Array<string>;
}Returns the first value for a query parameter key safely.
When to use
Use when duplicate query parameters are ordered and the first occurrence has precedence.
Details
Returns Option.none when the key is absent.
Signature
declare const getFirst: {
(key: string): (self: UrlParams) => Option<string>;
(self: UrlParams, key: string): Option<string>;
};Returns the last value for a query parameter key safely.
When to use
Use when duplicate query parameters are ordered and the last occurrence has precedence.
Details
Returns Option.none when the key is absent.
Signature
declare const getLast: {
(key: string): (self: UrlParams) => Option<string>;
(self: UrlParams, key: string): Option<string>;
};Removes all query parameter values for the specified key.
Signature
declare const remove: {
(key: string): (self: UrlParams) => UrlParams;
(self: UrlParams, key: string): UrlParams;
};Sets a query parameter to a single value.
Details
Existing values for the same key are removed, and the new value is appended to the end.
Signature
declare const set: {
(key: string, value: Coercible): (self: UrlParams) => UrlParams;
(self: UrlParams, key: string, value: Coercible): UrlParams;
};Sets multiple query parameters from input.
Details
Keys present in the input replace existing values for those keys, while unmentioned existing parameters are preserved.
Signature
declare const setAll: {
(input: Input): (self: UrlParams) => UrlParams;
(self: UrlParams, input: Input): UrlParams;
};Transforms the underlying ordered key-value pairs of UrlParams.
Details
The result is wrapped in a new UrlParams value.
Signature
declare const transform: {
(f: (params: readonly Array<readonly [string, string]>) => readonly Array<readonly [string, string]>): (self: UrlParams) => UrlParams;
(self: UrlParams, f: (params: readonly Array<readonly [string, string]>) => readonly Array<readonly [string, string]>): UrlParams;
}Constructors
An empty UrlParams value.
Signature
declare const empty: UrlParams;Creates UrlParams from a supported input shape.
Details
Primitive values are converted to strings, arrays produce repeated parameters, nested records use bracket notation, and undefined values are omitted.
Signature
declare function fromInput(input: Input): UrlParams;Creates UrlParams from ordered string key-value pairs.
Details
The input pairs are used as-is and are not coerced or normalized.
Signature
declare function make(params: readonly Array<readonly [string, string]>): UrlParamsConverting
toReadonlyRecord
Builds a readonly record from UrlParams.
Details
Keys with one value map to a string, and keys with multiple values map to a non-empty readonly array of strings.
Signature
declare const toReadonlyRecord: (
self: UrlParams,
) => ReadonlyRecord<string, string | Arr.NonEmptyReadonlyArray<string>>;Builds a Record containing all the key-value pairs in the given UrlParams as string (if only one value for a key) or a NonEmptyArray<string> (when more than one value for a key)
Signature
declare function toRecord(self: UrlParams): Record<string, string | Arr.NonEmptyArray<string>>;Serializes UrlParams to a URL query string without a leading question mark.
Signature
declare function toString(input: Input): string;Guards
isUrlParams
Returns true when a value is a UrlParams instance.
Signature
declare function isUrlParams(u: unknown): u is UrlParams;Instances
Equivalence
Provides an order-sensitive Equivalence instance for UrlParams.
Details
Two values are equivalent when they contain the same key-value pairs in the same order.
Signature
declare const Equivalence: Equ.Equivalence<UrlParams>;Models
Primitive value that can be converted into a URL parameter string.
Gotchas
undefined values are skipped when constructing from input.
Signature
type Coercible = string | number | bigint | boolean | null | undefined;CoercibleRecord type
Record input whose fields can be coerced into URL parameter values.
Details
Nested records are rendered using bracket notation, and arrays produce repeated parameters.
Signature
type CoercibleRecord<A extends object = any> = { [K in keyof A]: CoercibleRecordField<A[K]> };Input accepted when constructing UrlParams.
Details
Values can be provided as a coercible record, an iterable of key-value pairs, or a native URLSearchParams value.
Signature
type Input =
| UrlParams
| CoercibleRecordInput
| Iterable<readonly [string, Coercible]>
| URLSearchParams;Immutable collection of URL query parameters.
Details
Parameters are stored as ordered string key-value pairs and can contain multiple values for the same key.
Signature
interface UrlParams extends Pipeable, Inspectable, Iterable<readonly [string, string]> {
readonly "~effect/http/UrlParams": "~effect/http/UrlParams";
readonly params: readonly Array<readonly [string, string]>;
}Schemas
schemaJsonField
Extracts a JSON value from the first occurrence of the given field in the UrlParams.
Signature
declare const schemaJsonField: (field: string) => schemaJsonField;schemaJsonField interface
Schema type for decoding one URL parameter field as JSON.
Signature
interface schemaJsonField extends decodeTo<Schema.fromJsonString<Schema.Unknown>, UrlParamsSchema> {
constructor(_: never);
}schemaRecord
Schema that decodes UrlParams into a record of key-value pairs.
Details
Keys with one value decode to a string, and keys with multiple values decode to a non-empty readonly array of strings.
Signature
declare const schemaRecord: schemaRecord;schemaRecord interface
Extract a record of key-value pairs from the UrlParams.
Signature
interface schemaRecord extends decodeTo<
Schema.$Record<
Schema.String,
Schema.Union<readonly [Schema.String, Schema.NonEmptyArray<Schema.String>]>
>,
UrlParamsSchema,
never,
never
> {
constructor(_: never);
}UrlParamsSchema
Schema for UrlParams.
Details
The encoded representation is an array of string key-value tuples.
Signature
declare const UrlParamsSchema: UrlParamsSchema;UrlParamsSchema interface
Schema type for UrlParams.
Signature
interface UrlParamsSchema extends declare<UrlParams, ReadonlyArray<readonly [string, string]>> {
constructor(_: never);
}
Appends a query parameter value without removing existing values for the key.