.opencode/node_modules/effect/dist/unstable/http/UrlParams.d.ts

/**
 * 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.
 *
 * @since 4.0.0
 */
import * as Arr from "../../Array.ts";
import * as Equ from "../../Equivalence.ts";
import type { Inspectable } from "../../Inspectable.ts";
import * as Option from "../../Option.ts";
import type { Pipeable } from "../../Pipeable.ts";
import type { ReadonlyRecord } from "../../Record.ts";
import * as Result from "../../Result.ts";
import * as Schema from "../../Schema.ts";
declare const TypeId = "~effect/http/UrlParams";
/**
 * 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.
 *
 * @category models
 * @since 4.0.0
 */
export interface UrlParams extends Pipeable, Inspectable, Iterable<readonly [string, string]> {
    readonly [TypeId]: typeof TypeId;
    readonly params: ReadonlyArray<readonly [string, string]>;
}
/**
 * Returns `true` when a value is a `UrlParams` instance.
 *
 * @category guards
 * @since 4.0.0
 */
export declare const isUrlParams: (u: unknown) => u is UrlParams;
/**
 * 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.
 *
 * @category models
 * @since 4.0.0
 */
export type Input = CoercibleRecordInput | Iterable<readonly [string, Coercible]> | URLSearchParams;
type CoercibleRecordInput = CoercibleRecord & {
    readonly [Symbol.iterator]?: never;
};
/**
 * Primitive value that can be converted into a URL parameter string.
 *
 * **Gotchas**
 *
 * `undefined` values are skipped when constructing from input.
 *
 * @category models
 * @since 4.0.0
 */
export type Coercible = string | number | bigint | boolean | null | undefined;
/**
 * @category models
 * @since 4.0.0
 */
type CoercibleRecordField<A> = A extends Coercible ? A : A extends ReadonlyArray<infer Item> ? ReadonlyArray<Item extends Coercible ? Item : never> : A extends object ? CoercibleRecord<A> : never;
/**
 * Record input whose fields can be coerced into URL parameter values.
 *
 * **Details**
 *
 * Nested records are rendered using bracket notation, and arrays produce repeated
 * parameters.
 *
 * @category models
 * @since 4.0.0
 */
export type CoercibleRecord<A extends object = any> = {
    readonly [K in keyof A]: CoercibleRecordField<A[K]>;
};
/**
 * Creates `UrlParams` from ordered string key-value pairs.
 *
 * **Details**
 *
 * The input pairs are used as-is and are not coerced or normalized.
 *
 * @category constructors
 * @since 4.0.0
 */
export declare const make: (params: ReadonlyArray<readonly [string, string]>) => 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.
 *
 * @category constructors
 * @since 4.0.0
 */
export declare const fromInput: (input: Input) => UrlParams;
/**
 * 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.
 *
 * @category instances
 * @since 4.0.0
 */
export declare const Equivalence: Equ.Equivalence<UrlParams>;
/**
 * Schema type for `UrlParams`.
 *
 * @category schemas
 * @since 4.0.0
 */
export interface UrlParamsSchema extends Schema.declare<UrlParams, ReadonlyArray<readonly [string, string]>> {
}
/**
 * Schema for `UrlParams`.
 *
 * **Details**
 *
 * The encoded representation is an array of string key-value tuples.
 *
 * @category schemas
 * @since 4.0.0
 */
export declare const UrlParamsSchema: UrlParamsSchema;
/**
 * An empty `UrlParams` value.
 *
 * @category constructors
 * @since 4.0.0
 */
export declare const empty: UrlParams;
/**
 * Returns all values for a query parameter key in insertion order.
 *
 * **Details**
 *
 * Returns an empty array when the key is absent.
 *
 * @category combinators
 * @since 4.0.0
 */
export declare const getAll: {
    /**
     * Returns all values for a query parameter key in insertion order.
     *
     * **Details**
     *
     * Returns an empty array when the key is absent.
     *
     * @category combinators
     * @since 4.0.0
     */
    (key: string): (self: UrlParams) => ReadonlyArray<string>;
    /**
     * Returns all values for a query parameter key in insertion order.
     *
     * **Details**
     *
     * Returns an empty array when the key is absent.
     *
     * @category combinators
     * @since 4.0.0
     */
    (self: UrlParams, key: string): ReadonlyArray<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.
 *
 * @category combinators
 * @since 4.0.0
 */
export declare const getFirst: {
    /**
     * 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.
     *
     * @category combinators
     * @since 4.0.0
     */
    (key: string): (self: UrlParams) => Option.Option<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.
     *
     * @category combinators
     * @since 4.0.0
     */
    (self: UrlParams, key: string): Option.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.
 *
 * @category combinators
 * @since 4.0.0
 */
export declare const getLast: {
    /**
     * 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.
     *
     * @category combinators
     * @since 4.0.0
     */
    (key: string): (self: UrlParams) => Option.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.
     *
     * @category combinators
     * @since 4.0.0
     */
    (self: UrlParams, key: string): Option.Option<string>;
};
/**
 * 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.
 *
 * @category combinators
 * @since 4.0.0
 */
export declare const set: {
    /**
     * 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.
     *
     * @category combinators
     * @since 4.0.0
     */
    (key: string, value: Coercible): (self: UrlParams) => 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.
     *
     * @category combinators
     * @since 4.0.0
     */
    (self: UrlParams, key: string, value: Coercible): UrlParams;
};
/**
 * Transforms the underlying ordered key-value pairs of `UrlParams`.
 *
 * **Details**
 *
 * The result is wrapped in a new `UrlParams` value.
 *
 * @category combinators
 * @since 4.0.0
 */
export declare const transform: {
    /**
     * Transforms the underlying ordered key-value pairs of `UrlParams`.
     *
     * **Details**
     *
     * The result is wrapped in a new `UrlParams` value.
     *
     * @category combinators
     * @since 4.0.0
     */
    (f: (params: UrlParams["params"]) => UrlParams["params"]): (self: UrlParams) => UrlParams;
    /**
     * Transforms the underlying ordered key-value pairs of `UrlParams`.
     *
     * **Details**
     *
     * The result is wrapped in a new `UrlParams` value.
     *
     * @category combinators
     * @since 4.0.0
     */
    (self: UrlParams, f: (params: UrlParams["params"]) => UrlParams["params"]): 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.
 *
 * @category combinators
 * @since 4.0.0
 */
export declare const setAll: {
    /**
     * Sets multiple query parameters from input.
     *
     * **Details**
     *
     * Keys present in the input replace existing values for those keys, while
     * unmentioned existing parameters are preserved.
     *
     * @category combinators
     * @since 4.0.0
     */
    (input: Input): (self: UrlParams) => 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.
     *
     * @category combinators
     * @since 4.0.0
     */
    (self: UrlParams, input: Input): UrlParams;
};
/**
 * Appends a query parameter value without removing existing values for the key.
 *
 * @category combinators
 * @since 4.0.0
 */
export declare const append: {
    /**
     * Appends a query parameter value without removing existing values for the key.
     *
     * @category combinators
     * @since 4.0.0
     */
    (key: string, value: Coercible): (self: UrlParams) => UrlParams;
    /**
     * Appends a query parameter value without removing existing values for the key.
     *
     * @category combinators
     * @since 4.0.0
     */
    (self: UrlParams, key: string, value: Coercible): UrlParams;
};
/**
 * Appends all query parameters produced from the supplied input.
 *
 * **Details**
 *
 * Existing parameters are preserved.
 *
 * @category combinators
 * @since 4.0.0
 */
export declare const appendAll: {
    /**
     * Appends all query parameters produced from the supplied input.
     *
     * **Details**
     *
     * Existing parameters are preserved.
     *
     * @category combinators
     * @since 4.0.0
     */
    (input: Input): (self: UrlParams) => UrlParams;
    /**
     * Appends all query parameters produced from the supplied input.
     *
     * **Details**
     *
     * Existing parameters are preserved.
     *
     * @category combinators
     * @since 4.0.0
     */
    (self: UrlParams, input: Input): UrlParams;
};
/**
 * Removes all query parameter values for the specified key.
 *
 * @category combinators
 * @since 4.0.0
 */
export declare const remove: {
    /**
     * Removes all query parameter values for the specified key.
     *
     * @category combinators
     * @since 4.0.0
     */
    (key: string): (self: UrlParams) => UrlParams;
    /**
     * Removes all query parameter values for the specified key.
     *
     * @category combinators
     * @since 4.0.0
     */
    (self: UrlParams, key: string): UrlParams;
};
declare const UrlParamsError_base: new <A extends Record<string, any> = {}>(args: import("../../Types.ts").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("../../Cause.ts").YieldableError & {
    readonly _tag: "UrlParamsError";
} & Readonly<A>;
/**
 * Error returned when constructing a `URL` from `UrlParams` fails.
 *
 * @category errors
 * @since 4.0.0
 */
export declare class UrlParamsError extends UrlParamsError_base<{
    cause: unknown;
}> {
}
/**
 * Creates a `URL` safely by appending `UrlParams` and an optional hash to a URL string.
 *
 * **Details**
 *
 * Returns a `Result` that fails with `UrlParamsError` if the URL cannot be
 * constructed.
 *
 * @category converting
 * @since 4.0.0
 */
export declare const makeUrl: (url: string, params: UrlParams, hash: string | undefined) => Result.Result<URL, UrlParamsError>;
/**
 * Serializes `UrlParams` to a URL query string without a leading question mark.
 *
 * @category converting
 * @since 4.0.0
 */
export declare const toString: (self: UrlParams) => 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)
 *
 * **Example** (Converting parameters to a record)
 *
 * ```ts
 * import { UrlParams } from "effect/unstable/http"
 * import * as assert from "node:assert"
 *
 * const urlParams = UrlParams.fromInput({
 *   a: 1,
 *   b: true,
 *   c: "string",
 *   e: [1, 2, 3]
 * })
 * const result = UrlParams.toRecord(urlParams)
 *
 * assert.deepStrictEqual(
 *   result,
 *   { "a": "1", "b": "true", "c": "string", "e": ["1", "2", "3"] }
 * )
 * ```
 *
 * @category converting
 * @since 4.0.0
 */
export declare const toRecord: (self: UrlParams) => Record<string, string | Arr.NonEmptyArray<string>>;
/**
 * 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.
 *
 * @category converting
 * @since 4.0.0
 */
export declare const toReadonlyRecord: (self: UrlParams) => ReadonlyRecord<string, string | Arr.NonEmptyReadonlyArray<string>>;
/**
 * Schema type for decoding one URL parameter field as JSON.
 *
 * @category schemas
 * @since 4.0.0
 */
export interface schemaJsonField extends Schema.decodeTo<Schema.UnknownFromJsonString, UrlParamsSchema> {
}
/**
 * Extracts a JSON value from the first occurrence of the given `field` in the
 * `UrlParams`.
 *
 * **Example** (Decoding JSON parameter fields)
 *
 * ```ts
 * import { Schema } from "effect"
 * import { UrlParams } from "effect/unstable/http"
 *
 * const extractFoo = UrlParams.schemaJsonField("foo").pipe(
 *   Schema.decodeTo(Schema.Struct({
 *     some: Schema.String,
 *     number: Schema.Number
 *   }))
 * )
 *
 * console.log(
 *   Schema.decodeSync(extractFoo)(UrlParams.fromInput({
 *     foo: JSON.stringify({ some: "bar", number: 42 }),
 *     baz: "qux"
 *   }))
 * )
 * ```
 *
 * @category schemas
 * @since 4.0.0
 */
export declare const schemaJsonField: (field: string) => schemaJsonField;
/**
 * Extract a record of key-value pairs from the `UrlParams`.
 *
 * @category schemas
 * @since 4.0.0
 */
export interface schemaRecord extends Schema.decodeTo<Schema.$Record<Schema.String, Schema.Union<readonly [Schema.String, Schema.NonEmptyArray<Schema.String>]>>, UrlParamsSchema, never, never> {
}
/**
 * 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.
 *
 * **Example** (Decoding URL parameters to a record)
 *
 * ```ts
 * import { Schema } from "effect"
 * import { UrlParams } from "effect/unstable/http"
 *
 * const toStruct = UrlParams.schemaRecord.pipe(
 *   Schema.decodeTo(Schema.Struct({
 *     some: Schema.String,
 *     number: Schema.FiniteFromString
 *   }))
 * )
 *
 * console.log(
 *   Schema.decodeSync(toStruct)(UrlParams.fromInput({
 *     some: "value",
 *     number: 42
 *   }))
 * )
 * ```
 *
 * @category schemas
 * @since 4.0.0
 */
export declare const schemaRecord: schemaRecord;
export {};
//# sourceMappingURL=UrlParams.d.ts.map