effect 4.0.0-beta.66 → 4.0.0-beta.67

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
 }
 
 /**
- * @since 4.0.0
+ * Returns `true` when a value is a `UrlParams` instance.
+ *
  * @category Guards
+ * @since 4.0.0
  */
 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)))
 
 /**
- * @since 4.0.0
+ * Error returned when constructing a `URL` from `UrlParams` fails.
+ *
  * @category Errors
+ * @since 4.0.0
  */
 export class UrlParamsError extends Data.TaggedError("UrlParamsError")<{
   cause: unknown
 }> {}
 
 /**
- * @since 4.0.0
+ * 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 conversions
+ * @since 4.0.0
  */
 export const makeUrl = (
   url: string,
@@ -429,8 +601,10 @@ export const makeUrl = (
 }
 
 /**
- * @since 4.0.0
+ * Serializes `UrlParams` to a URL query string without a leading question mark.
+ *
  * @category conversions
+ * @since 4.0.0
  */
 export const toString = (self: UrlParams): string => new URLSearchParams(self.params as any).toString()
 
@@ -471,8 +645,8 @@ const baseUrl = (): string | undefined => {
  * )
  * ```
  *
- * @since 4.0.0
  * @category conversions
+ * @since 4.0.0
  */
 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
 }
 
 /**
- * @since 4.0.0
+ * 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 conversions
+ * @since 4.0.0
  */
 export const toReadonlyRecord: (self: UrlParams) => ReadonlyRecord<string, string | Arr.NonEmptyReadonlyArray<string>> =
   toRecord as any
 
 /**
- * @since 4.0.0
+ * 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> {}
 
@@ -525,8 +706,8 @@ export interface schemaJsonField extends Schema.decodeTo<Schema.UnknownFromJsonS
  * )
  * ```
  *
- * @since 4.0.0
  * @category Schemas
+ * @since 4.0.0
  */
 export const schemaJsonField = (field: string): schemaJsonField =>
   UrlParamsSchema.pipe(
@@ -546,8 +727,8 @@ export const schemaJsonField = (field: string): schemaJsonField =>
 /**
  * Extract a record of key-value pairs from the `UrlParams`.
  *
- * @since 4.0.0
  * @category Schemas
+ * @since 4.0.0
  */
 export interface schemaRecord extends
   Schema.decodeTo<
@@ -559,7 +740,10 @@ 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**
  *
@@ -582,8 +766,8 @@ export interface schemaRecord extends
  * )
  * ```
  *
- * @since 4.0.0
  * @category schema
+ * @since 4.0.0
  */
 export const schemaRecord: schemaRecord = UrlParamsSchema.pipe(
   Schema.decodeTo(

package/src/unstable/httpapi/HttpApi.ts

@@ -1,4 +1,27 @@
 /**
+ * The `HttpApi` module defines the top-level contract for an Effect HTTP API.
+ * An `HttpApi` names an API and collects one or more `HttpApiGroup`s, whose
+ * endpoints describe the request inputs, response schemas, middleware, and
+ * annotations that later drive server builders, clients, and OpenAPI
+ * generation.
+ *
+ * Use this module when you want to compose a domain API from endpoint groups,
+ * combine APIs from multiple modules, apply a shared path prefix or middleware,
+ * attach annotations, or reflect over the final route shape. Implementations are
+ * provided separately with `HttpApiBuilder.group`, and the completed API is
+ * registered with `HttpApiBuilder.layer`.
+ *
+ * A few composition details are worth keeping in mind: group identifiers are
+ * used as keys, so adding another group with the same identifier replaces the
+ * previous one; `prefix` and `middleware` are applied to the groups and
+ * endpoints already present when they are called; and `addHttpApi` merges the
+ * added API's annotations into its groups. During reflection, success and error
+ * schemas are grouped by the HTTP status recorded on their `HttpApiSchema`
+ * annotations, endpoints without an explicit success schema default to
+ * `NoContent`, and middleware error schemas are included with endpoint errors.
+ * Extra schemas supplied through `AdditionalSchemas` must have an `identifier`
+ * annotation so they can be emitted as OpenAPI components.
+ *
  * @since 4.0.0
  */
 import type { NonEmptyReadonlyArray } from "../../Array.ts"
@@ -18,19 +41,22 @@ import * as HttpApiSchema from "./HttpApiSchema.ts"
 const TypeId = "~effect/httpapi/HttpApi"
 
 /**
- * @since 4.0.0
+ * Returns `true` when a value is an `HttpApi`.
+ *
  * @category guards
+ * @since 4.0.0
  */
 export const isHttpApi = (u: unknown): u is Any => Predicate.hasProperty(u, TypeId)
 
 /**
- * An `HttpApi` is a collection of `HttpApiEndpoint`s. You can use an `HttpApi` to
- * represent a portion of your domain.
+ * An `HttpApi` is a collection of HTTP API groups and endpoints that represents a
+ * portion of your domain.
  *
- * The endpoints can be implemented later using the `HttpApiBuilder.make` api.
+ * Endpoint implementations can be provided with `HttpApiBuilder.group`, and the
+ * completed API can be registered with `HttpApiBuilder.layer`.
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface HttpApi<
   out Id extends string,
@@ -82,16 +108,21 @@ export interface HttpApi<
 }
 
 /**
- * @since 4.0.0
+ * An `HttpApi` value with its identifier and group types erased.
+ *
  * @category models
+ * @since 4.0.0
  */
 export interface Any {
   readonly [TypeId]: typeof TypeId
 }
 
 /**
- * @since 4.0.0
+ * An `HttpApi` with broad identifier and group types while retaining the concrete
+ * runtime properties used by implementation helpers.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type AnyWithProps = HttpApi<string, HttpApiGroup.AnyWithProps>
 
@@ -175,14 +206,13 @@ const makeProto = <Id extends string, Groups extends HttpApiGroup.Any>(
 }
 
 /**
- * An `HttpApi` is a collection of `HttpApiEndpoint`s. You can use an `HttpApi` to
- * represent a portion of your domain.
+ * Creates an empty `HttpApi` with the supplied identifier.
  *
- * You can then use `HttpApiBuilder.layer(api)` to implement the endpoints of the
- * `HttpApi`.
+ * Add groups with `add` or `addHttpApi`, provide endpoint implementations with
+ * `HttpApiBuilder.group`, and register the API with `HttpApiBuilder.layer`.
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const make = <const Id extends string>(identifier: Id): HttpApi<Id, never> =>
   makeProto({
@@ -192,8 +222,13 @@ export const make = <const Id extends string>(identifier: Id): HttpApi<Id, never
   })
 
 /**
- * @since 4.0.0
+ * Walks the groups and endpoints in an `HttpApi`.
+ *
+ * The callbacks receive each group or endpoint with merged annotations, endpoint
+ * middleware, and response schemas grouped by HTTP status.
+ *
  * @category Reflection
+ * @since 4.0.0
  */
 export const reflect = <Id extends string, Groups extends HttpApiGroup.Any>(
   self: HttpApi<Id, Groups>,
@@ -280,8 +315,8 @@ const extractResponseContent = (
  * Adds additional schemas to components/schemas.
  * The provided schemas must have a `identifier` annotation.
  *
- * @since 4.0.0
  * @category tags
+ * @since 4.0.0
  */
 export class AdditionalSchemas extends Context.Service<
   AdditionalSchemas,