effect 4.0.0-beta.66 → 4.0.0-beta.68

package/src/unstable/http/UrlParams.ts

@@ -1,4 +1,24 @@
 /**
+ * Utilities for representing, transforming, and serializing URL query
+ * parameters.
+ *
+ * This module provides an immutable `UrlParams` collection backed by ordered
+ * string key-value pairs. It is used for HTTP client request queries,
+ * URL-encoded form bodies, and server-side decoding workflows where query
+ * parameters need to be built from records, iterables, or native
+ * `URLSearchParams`, then inspected, appended, replaced, removed, converted to a
+ * URL, or decoded with schemas.
+ *
+ * Duplicate keys are preserved by the core representation and by append-style
+ * operations; use `getAll` when all values matter, and note that `set` and
+ * `setAll` replace existing values for matching keys. Serialization through
+ * `toString` and `makeUrl` delegates to the platform `URLSearchParams` / `URL`
+ * implementations, so provide decoded strings rather than pre-encoded query
+ * fragments. Record-based and schema-based conversions intentionally collapse
+ * repeated keys into string arrays and do not preserve the full global pair
+ * ordering; `schemaJsonField` reads the first matching value for the selected
+ * field.
+ *
  * @since 4.0.0
  */
 import * as Arr from "../../Array.ts"
@@ -23,8 +43,13 @@ import * as Tuple from "../../Tuple.ts"
 const TypeId = "~effect/http/UrlParams"
 
 /**
- * @since 4.0.0
+ * Immutable collection of URL query parameters.
+ *
+ * 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
@@ -32,14 +57,21 @@ export interface UrlParams extends Pipeable, Inspectable, Iterable<readonly [str
 }
 
 /**
+ * Returns `true` when a value is a `UrlParams` instance.
+ *
+ * @category guards
  * @since 4.0.0
- * @category Guards
  */
 export const isUrlParams = (u: unknown): u is UrlParams => hasProperty(u, TypeId)
 
 /**
- * @since 4.0.0
+ * Input accepted when constructing `UrlParams`.
+ *
+ * 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
@@ -51,14 +83,18 @@ type CoercibleRecordInput = CoercibleRecord & {
 }
 
 /**
- * @since 4.0.0
+ * Primitive value that can be converted into a URL parameter string.
+ *
+ * `undefined` values are skipped when constructing from input.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type Coercible = string | number | bigint | boolean | null | undefined
 
 /**
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 type CoercibleRecordField<A> = A extends Coercible ? A
   : A extends ReadonlyArray<infer Item> ? ReadonlyArray<Item extends Coercible ? Item : never>
@@ -66,8 +102,13 @@ type CoercibleRecordField<A> = A extends Coercible ? A
   : never
 
 /**
- * @since 4.0.0
+ * Record input whose fields can be coerced into URL parameter values.
+ *
+ * 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]>
@@ -94,8 +135,12 @@ const Proto = {
 }
 
 /**
- * @since 4.0.0
+ * Creates `UrlParams` from ordered string key-value pairs.
+ *
+ * The input pairs are used as-is and are not coerced or normalized.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const make = (params: ReadonlyArray<readonly [string, string]>): UrlParams => {
   const self = Object.create(Proto)
@@ -104,8 +149,13 @@ export const make = (params: ReadonlyArray<readonly [string, string]>): UrlParam
 }
 
 /**
- * @since 4.0.0
+ * Creates `UrlParams` from a supported input shape.
+ *
+ * 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 const fromInput = (input: Input): UrlParams => {
   const parsed = fromInputNested(input)
@@ -146,8 +196,13 @@ const fromInputNested = (input: Input): Array<[string | Array<string>, any]> =>
 }
 
 /**
- * @since 4.0.0
+ * Order-sensitive equivalence for `UrlParams`.
+ *
+ * Two values are equivalent when they contain the same key-value pairs in the same
+ * order.
+ *
  * @category Equivalence
+ * @since 4.0.0
  */
 export const Equivalence: Equ.Equivalence<UrlParams> = Equ.make<UrlParams>((a, b) =>
   arrayEquivalence(a.params, b.params)
@@ -158,14 +213,20 @@ const arrayEquivalence = Arr.makeEquivalence(
 )
 
 /**
- * @since 4.0.0
+ * Schema type for `UrlParams`.
+ *
  * @category schemas
+ * @since 4.0.0
  */
 export interface UrlParamsSchema extends Schema.declare<UrlParams, ReadonlyArray<readonly [string, string]>> {}
 
 /**
- * @since 4.0.0
+ * Schema for `UrlParams`.
+ *
+ * The encoded representation is an array of string key-value tuples.
+ *
  * @category schemas
+ * @since 4.0.0
  */
 export const UrlParamsSchema: UrlParamsSchema = Schema.declare(
   isUrlParams,
@@ -193,24 +254,38 @@ export const UrlParamsSchema: UrlParamsSchema = Schema.declare(
 )
 
 /**
- * @since 4.0.0
+ * An empty `UrlParams` value.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const empty: UrlParams = make([])
 
 /**
- * @since 4.0.0
+ * Returns all values for a query parameter key in insertion order.
+ *
+ * Returns an empty array when the key is absent.
+ *
  * @category combinators
+ * @since 4.0.0
  */
 export const getAll: {
   /**
-   * @since 4.0.0
+   * Returns all values for a query parameter key in insertion order.
+   *
+   * Returns an empty array when the key is absent.
+   *
    * @category combinators
+   * @since 4.0.0
    */
   (key: string): (self: UrlParams) => ReadonlyArray<string>
   /**
-   * @since 4.0.0
+   * Returns all values for a query parameter key in insertion order.
+   *
+   * Returns an empty array when the key is absent.
+   *
    * @category combinators
+   * @since 4.0.0
    */
   (self: UrlParams, key: string): ReadonlyArray<string>
 } = dual(
@@ -225,18 +300,30 @@ export const getAll: {
 )
 
 /**
- * @since 4.0.0
+ * Returns the first value for a query parameter key.
+ *
+ * Returns `Option.none` when the key is absent.
+ *
  * @category combinators
+ * @since 4.0.0
  */
 export const getFirst: {
   /**
-   * @since 4.0.0
+   * Returns the first value for a query parameter key.
+   *
+   * Returns `Option.none` when the key is absent.
+   *
    * @category combinators
+   * @since 4.0.0
    */
   (key: string): (self: UrlParams) => Option.Option<string>
   /**
-   * @since 4.0.0
+   * Returns the first value for a query parameter key.
+   *
+   * Returns `Option.none` when the key is absent.
+   *
    * @category combinators
+   * @since 4.0.0
    */
   (self: UrlParams, key: string): Option.Option<string>
 } = dual(
@@ -248,18 +335,30 @@ export const getFirst: {
 )
 
 /**
- * @since 4.0.0
+ * Returns the last value for a query parameter key.
+ *
+ * Returns `Option.none` when the key is absent.
+ *
  * @category combinators
+ * @since 4.0.0
  */
 export const getLast: {
   /**
-   * @since 4.0.0
+   * Returns the last value for a query parameter key.
+   *
+   * Returns `Option.none` when the key is absent.
+   *
    * @category combinators
+   * @since 4.0.0
    */
   (key: string): (self: UrlParams) => Option.Option<string>
   /**
-   * @since 4.0.0
+   * Returns the last value for a query parameter key.
+   *
+   * Returns `Option.none` when the key is absent.
+   *
    * @category combinators
+   * @since 4.0.0
    */
   (self: UrlParams, key: string): Option.Option<string>
 } = dual(2, (self: UrlParams, key: string): Option.Option<string> =>
@@ -268,18 +367,33 @@ export const getLast: {
   ))
 
 /**
- * @since 4.0.0
+ * Sets a query parameter to a single value.
+ *
+ * Existing values for the same key are removed, and the new value is appended to
+ * the end.
+ *
  * @category combinators
+ * @since 4.0.0
  */
 export const set: {
   /**
-   * @since 4.0.0
+   * Sets a query parameter to a single value.
+   *
+   * 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
   /**
-   * @since 4.0.0
+   * Sets a query parameter to a single value.
+   *
+   * 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
 } = dual(3, (self: UrlParams, key: string, value: Coercible): UrlParams =>
@@ -291,18 +405,30 @@ export const set: {
   ))
 
 /**
- * @since 4.0.0
+ * Transforms the underlying ordered key-value pairs of `UrlParams`.
+ *
+ * The result is wrapped in a new `UrlParams` value.
+ *
  * @category combinators
+ * @since 4.0.0
  */
 export const transform: {
   /**
-   * @since 4.0.0
+   * Transforms the underlying ordered key-value pairs of `UrlParams`.
+   *
+   * The result is wrapped in a new `UrlParams` value.
+   *
    * @category combinators
+   * @since 4.0.0
    */
   (f: (params: UrlParams["params"]) => UrlParams["params"]): (self: UrlParams) => UrlParams
   /**
-   * @since 4.0.0
+   * Transforms the underlying ordered key-value pairs of `UrlParams`.
+   *
+   * The result is wrapped in a new `UrlParams` value.
+   *
    * @category combinators
+   * @since 4.0.0
    */
   (self: UrlParams, f: (params: UrlParams["params"]) => UrlParams["params"]): UrlParams
 } = dual(
@@ -311,18 +437,33 @@ export const transform: {
 )
 
 /**
- * @since 4.0.0
+ * Sets multiple query parameters from input.
+ *
+ * Keys present in the input replace existing values for those keys, while
+ * unmentioned existing parameters are preserved.
+ *
  * @category combinators
+ * @since 4.0.0
  */
 export const setAll: {
   /**
-   * @since 4.0.0
+   * Sets multiple query parameters from input.
+   *
+   * 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
   /**
-   * @since 4.0.0
+   * Sets multiple query parameters from input.
+   *
+   * 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
 } = dual(2, (self: UrlParams, input: Input): UrlParams => {
@@ -340,18 +481,24 @@ export const setAll: {
 })
 
 /**
- * @since 4.0.0
+ * Appends a query parameter value without removing existing values for the key.
+ *
  * @category combinators
+ * @since 4.0.0
  */
 export const append: {
   /**
-   * @since 4.0.0
+   * 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
   /**
-   * @since 4.0.0
+   * 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
 } = dual(3, (self: UrlParams, key: string, value: Coercible): UrlParams =>
@@ -361,50 +508,75 @@ export const append: {
   )))
 
 /**
- * @since 4.0.0
+ * Appends all query parameters produced from the supplied input.
+ *
+ * Existing parameters are preserved.
+ *
  * @category combinators
+ * @since 4.0.0
  */
 export const appendAll: {
   /**
-   * @since 4.0.0
+   * Appends all query parameters produced from the supplied input.
+   *
+   * Existing parameters are preserved.
+   *
    * @category combinators
+   * @since 4.0.0
    */
   (input: Input): (self: UrlParams) => UrlParams
   /**
-   * @since 4.0.0
+   * Appends all query parameters produced from the supplied input.
+   *
+   * Existing parameters are preserved.
+   *
    * @category combinators
+   * @since 4.0.0
    */
   (self: UrlParams, input: Input): UrlParams
 } = dual(2, (self: UrlParams, input: Input): UrlParams => transform(self, Arr.appendAll(fromInput(input).params)))
 
 /**
- * @since 4.0.0
+ * Removes all query parameter values for the specified key.
+ *
  * @category combinators
+ * @since 4.0.0
  */
 export const remove: {
   /**
-   * @since 4.0.0
+   * Removes all query parameter values for the specified key.
+   *
    * @category combinators
+   * @since 4.0.0
    */
   (key: string): (self: UrlParams) => UrlParams
   /**
-   * @since 4.0.0
+   * Removes all query parameter values for the specified key.
+   *
    * @category combinators
+   * @since 4.0.0
    */
   (self: UrlParams, key: string): UrlParams
 } = dual(2, (self: UrlParams, key: string): UrlParams => transform(self, Arr.filter(([k]) => k !== key)))
 
 /**
+ * Error returned when constructing a `URL` from `UrlParams` fails.
+ *
+ * @category errors
  * @since 4.0.0
- * @category Errors
  */
 export class UrlParamsError extends Data.TaggedError("UrlParamsError")<{
   cause: unknown
 }> {}
 
 /**
+ * Creates a `URL` by appending `UrlParams` and an optional hash to a URL string.
+ *
+ * Returns a `Result` that fails with `UrlParamsError` if the URL cannot be
+ * constructed.
+ *
+ * @category converting
  * @since 4.0.0
- * @category conversions
  */
 export const makeUrl = (
   url: string,
@@ -429,8 +601,10 @@ export const makeUrl = (
 }
 
 /**
+ * Serializes `UrlParams` to a URL query string without a leading question mark.
+ *
+ * @category converting
  * @since 4.0.0
- * @category conversions
  */
 export const toString = (self: UrlParams): string => new URLSearchParams(self.params as any).toString()
 
@@ -451,7 +625,7 @@ const baseUrl = (): string | undefined => {
  * as `string` (if only one value for a key) or a `NonEmptyArray<string>`
  * (when more than one value for a key)
  *
- * **Example**
+ * **Example** (Converting parameters to a record)
  *
  * ```ts
  * import { UrlParams } from "effect/unstable/http"
@@ -471,8 +645,8 @@ const baseUrl = (): string | undefined => {
  * )
  * ```
  *
+ * @category converting
  * @since 4.0.0
- * @category conversions
  */
 export const toRecord = (self: UrlParams): Record<string, string | Arr.NonEmptyArray<string>> => {
   const out: Record<string, string | Arr.NonEmptyArray<string>> = {}
@@ -490,15 +664,22 @@ export const toRecord = (self: UrlParams): Record<string, string | Arr.NonEmptyA
 }
 
 /**
+ * Builds a readonly record from `UrlParams`.
+ *
+ * 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
- * @category conversions
  */
 export const toReadonlyRecord: (self: UrlParams) => ReadonlyRecord<string, string | Arr.NonEmptyReadonlyArray<string>> =
   toRecord as any
 
 /**
+ * Schema type for decoding one URL parameter field as JSON.
+ *
+ * @category schemas
  * @since 4.0.0
- * @category Schemas
  */
 export interface schemaJsonField extends Schema.decodeTo<Schema.UnknownFromJsonString, UrlParamsSchema> {}
 
@@ -506,6 +687,8 @@ export interface schemaJsonField extends Schema.decodeTo<Schema.UnknownFromJsonS
  * Extract 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"
@@ -525,8 +708,8 @@ export interface schemaJsonField extends Schema.decodeTo<Schema.UnknownFromJsonS
  * )
  * ```
  *
+ * @category schemas
  * @since 4.0.0
- * @category Schemas
  */
 export const schemaJsonField = (field: string): schemaJsonField =>
   UrlParamsSchema.pipe(
@@ -546,8 +729,8 @@ export const schemaJsonField = (field: string): schemaJsonField =>
 /**
  * Extract a record of key-value pairs from the `UrlParams`.
  *
+ * @category schemas
  * @since 4.0.0
- * @category Schemas
  */
 export interface schemaRecord extends
   Schema.decodeTo<
@@ -559,9 +742,12 @@ export interface schemaRecord extends
 {}
 
 /**
- * Extract schema from all key-value pairs in the given `UrlParams`.
+ * Schema that decodes `UrlParams` into a record of key-value pairs.
+ *
+ * Keys with one value decode to a string, and keys with multiple values decode to
+ * a non-empty readonly array of strings.
  *
- * **Example**
+ * **Example** (Decoding URL parameters to a record)
  *
  * ```ts
  * import { Schema } from "effect"
@@ -582,8 +768,8 @@ export interface schemaRecord extends
  * )
  * ```
  *
+ * @category schemas
  * @since 4.0.0
- * @category schema
  */
 export const schemaRecord: schemaRecord = UrlParamsSchema.pipe(
   Schema.decodeTo(