UrlParams unstable

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.

25 exports Since v4.0.0 Source

Combinators

append

unstable

Since v4.0.0

Appends a query parameter value without removing existing values for the key.

Signature

declare const append: {
  (key: string, value: Coercible): (self: UrlParams) => UrlParams;
  (self: UrlParams, key: string, value: Coercible): UrlParams;
}

appendAll

unstable

Since v4.0.0

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;
}

getAll

unstable

Since v4.0.0

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>;
}

getFirst

unstable

Since v4.0.0

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>;
}

getLast

unstable

Since v4.0.0

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>;
}

isRedactedName

unstable

Since v4.0.0

Checks whether a parameter name matches one of the redaction patterns.

Details

String patterns match case-insensitively; regular expressions test the name.

Signature

declare const isRedactedName: (name: string, patterns: ReadonlyArray<string | RegExp>) => boolean

redact

unstable

Since v4.0.0

Returns the parameter pairs with selected values wrapped in Redacted.

Details

Keeps Redacted values and wraps values whose names match isRedactedName, preserving order and repeated names.

Signature

declare const redact: {
  (key: string | RegExp | readonly Array<string | RegExp>): (self: UrlParams) => Array<[string, string | Redacted<string>]>;
  (self: UrlParams, key: string | RegExp | readonly Array<string | RegExp>): Array<[string, string | Redacted<string>]>;
}

redactUrl

unstable

Since v4.0.0

Redacts URL userinfo and the values of matching query parameters.

Details

Replaces userinfo with REDACTED:REDACTED and query values with REDACTED when their decoded names match isRedactedName. Preserves all other text. When names are omitted, uses the current fiber's CurrentRedactedNames, falling back to the defaults outside a fiber.

Signature

declare function redactUrl(url: string, redactedNames: readonly Array<string | RegExp>): string

Example Redacting a signed URL

import { UrlParams } from "effect/http"

const url = UrlParams.redactUrl("https://bucket.test/file?Signature=abc&size=1")
url // => "https://bucket.test/file?Signature=REDACTED&size=1"

remove

unstable

Since v4.0.0

Removes all query parameter values for the specified key.

Signature

declare const remove: {
  (key: string): (self: UrlParams) => UrlParams;
  (self: UrlParams, key: string): UrlParams;
}

set

unstable

Since v4.0.0

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;
}

setAll

unstable

Since v4.0.0

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;
}

transform

unstable

Since v4.0.0

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 | Redacted<string>]>) => readonly Array<readonly [string, string | Redacted<string>]>): (self: UrlParams) => UrlParams;
  (self: UrlParams, f: (params: readonly Array<readonly [string, string | Redacted<string>]>) => readonly Array<readonly [string, string | Redacted<string>]>): UrlParams;
}

Constructors

empty

unstable

Since v4.0.0

An empty UrlParams value.

Signature

declare const empty: UrlParams

fromInput

unstable

Since v4.0.0

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. Redacted values are kept as-is.

Signature

declare function fromInput(input: Input): UrlParams

make

unstable

Since v4.0.0

Creates UrlParams from ordered 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 | Redacted<string>]>): UrlParams

Converting

toReadonlyRecord

unstable

Since v4.0.0

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>>

toRecord

unstable

Since v4.0.0

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>>

Example Converting parameters to a record

import { UrlParams } from "effect/http"

const urlParams = UrlParams.fromInput({
  a: 1,
  b: true,
  c: "string",
  e: [1, 2, 3]
})
UrlParams.toRecord(urlParams) // => { a: "1", b: "true", c: "string", e: ["1", "2", "3"] }

toString

unstable

Since v4.0.0

Serializes UrlParams to a URL query string without a leading question mark.

Gotchas

The output contains the unwrapped values of Redacted parameters.

Signature

declare function toString(input: Input): string

Guards

isUrlParams

unstable

Since v4.0.0

Returns true when a value is a UrlParams instance.

Signature

declare function isUrlParams(u: unknown): u is UrlParams

Instances

Equivalence

unstable

Since v4.0.0

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

Coercible

type unstable

Since v4.0.0

Value that can be converted into a URL parameter string.

Details

Redacted values are stored wrapped and sent unwrapped.

Gotchas

undefined values are skipped when constructing from input.

Signature

type Coercible = string | number | bigint | boolean | null | undefined | Redacted.Redacted

CoercibleRecord

type unstable

Since v4.0.0

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

type unstable

Since v4.0.0

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

UrlParams

interface unstable

Since v4.0.0

Immutable collection of URL query parameters.

Details

Parameters are ordered key-value pairs, and a key can repeat. Each value is a string or a Redacted string, which is sent unwrapped. Inspection redacts Redacted values and values whose names match CurrentRedactedNames.

Signature

interface UrlParams extends Pipeable, Inspectable, Redactable, Iterable<readonly [string, string | Redacted.Redacted]> {
  readonly "~effect/http/UrlParams": "~effect/http/UrlParams";
  readonly params: readonly Array<readonly [string, string | Redacted<string>]>;
}

Services

CurrentRedactedNames

unstable

Since v4.0.0

Query parameter names or patterns to redact in inspection, spans and errors.

Details

Defaults include AWSAccessKeyId, Signature, sig and X-Goog-Signature. A custom list replaces the defaults. Matching uses isRedactedName. Redaction leaves request URLs and parameter values unchanged. Redacted values are redacted regardless of this list.

Signature

declare const CurrentRedactedNames: Reference<readonly Array<string | RegExp>>