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

package/src/unstable/httpapi/HttpApiBuilder.ts

@@ -1,4 +1,31 @@
 /**
+ * The `HttpApiBuilder` module connects declarative `HttpApi` definitions to
+ * runnable HTTP server routes.
+ *
+ * Use this module when you have described an API with `HttpApi`,
+ * `HttpApiGroup`, and `HttpApiEndpoint` values and need to provide the
+ * server-side implementation. `group` creates a layer for implementing every
+ * endpoint in one API group, `layer` registers the implemented groups with an
+ * `HttpRouter` and can expose the generated OpenAPI specification, and
+ * `endpoint` builds the effect for a single endpoint when custom composition is
+ * needed.
+ *
+ * The builder performs the runtime work implied by endpoint metadata: it decodes
+ * path parameters, headers, query parameters, and request payloads with
+ * `Schema`, applies endpoint middleware and security middleware, invokes the
+ * registered handler, and encodes successful or declared error results into
+ * `HttpServerResponse` values. Handlers can return an `HttpServerResponse`
+ * directly to bypass success encoding, and `handleRaw` can be used when payload
+ * decoding should be handled manually.
+ *
+ * A few implementation details are worth keeping in mind. Every group in the
+ * API must be provided with `HttpApiBuilder.group` before `layer` is evaluated,
+ * otherwise registration fails with a defect that names the missing group and
+ * the available group services. Payload decoding is selected by request media type;
+ * unsupported content types produce a `415` response before the handler runs.
+ * Schema failures are wrapped as `HttpApiSchemaError`, while ordinary handler
+ * failures are encoded with the endpoint's declared error schemas.
+ *
  * @since 4.0.0
  */
 import * as Context from "../../Context.ts"
@@ -46,8 +73,8 @@ import * as OpenApi from "./OpenApi.ts"
 /**
  * Register an `HttpApi` with a `HttpRouter`.
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const layer = <Id extends string, Groups extends HttpApiGroup.Any>(
   api: HttpApi.HttpApi<Id, Groups>,
@@ -101,8 +128,8 @@ export const layer = <Id extends string, Groups extends HttpApiGroup.Any>(
  *
  * You can implement endpoints using the `handlers.handle` api.
  *
- * @since 4.0.0
  * @category handlers
+ * @since 4.0.0
  */
 export const group = <
   ApiId extends string,
@@ -142,22 +169,30 @@ export const group = <
   })) as any
 
 /**
- * @since 4.0.0
+ * Type identifier symbol used to brand `Handlers` values.
+ *
  * @category handlers
+ * @since 4.0.0
  */
 export const HandlersTypeId: unique symbol = Symbol.for("@effect/platform/HttpApiBuilder/Handlers")
 
 /**
- * @since 4.0.0
+ * Type of the `Handlers` type identifier symbol.
+ *
  * @category handlers
+ * @since 4.0.0
  */
 export type HandlersTypeId = typeof HandlersTypeId
 
 /**
- * Represents a handled `HttpApi`.
+ * Mutable handler collection for one `HttpApi` group.
+ *
+ * Each call to `handle` or `handleRaw` registers an endpoint implementation and
+ * removes that endpoint from the type-level set of endpoints still requiring
+ * handlers.
  *
- * @since 4.0.0
  * @category handlers
+ * @since 4.0.0
  */
 export interface Handlers<
   R,
@@ -210,21 +245,30 @@ export interface Handlers<
 }
 
 /**
- * @since 4.0.0
+ * Namespace containing helper types for `HttpApiBuilder` handler collections.
+ *
  * @category handlers
+ * @since 4.0.0
  */
 export declare namespace Handlers {
   /**
-   * @since 4.0.0
+   * A `Handlers` value with its context and endpoint types erased.
+   *
    * @category handlers
+   * @since 4.0.0
    */
   export interface Any {
     readonly [HandlersTypeId]: any
   }
 
   /**
-   * @since 4.0.0
+   * Record stored for a registered endpoint handler.
+   *
+   * It keeps the endpoint metadata, handler function, whether raw request handling
+   * is used, and whether the handler should run uninterruptibly.
+   *
    * @category handlers
+   * @since 4.0.0
    */
   export type Item<R> = {
     readonly endpoint: HttpApiEndpoint.AnyWithProps
@@ -234,8 +278,11 @@ export declare namespace Handlers {
   }
 
   /**
-   * @since 4.0.0
+   * Creates a handler collection for a group where every endpoint in the group is
+   * still awaiting an implementation.
+   *
    * @category handlers
+   * @since 4.0.0
    */
   export type FromGroup<Group extends HttpApiGroup.Any> = Handlers<
     never,
@@ -243,8 +290,12 @@ export declare namespace Handlers {
   >
 
   /**
-   * @since 4.0.0
+   * Validates the return value of a group handler builder, preserving successful
+   * handler collections and producing a descriptive type error when endpoints remain
+   * unhandled.
+   *
    * @category handlers
+   * @since 4.0.0
    */
   export type ValidateReturn<A> = A extends (
     | Handlers<
@@ -264,8 +315,11 @@ export declare namespace Handlers {
     `Must return the implemented handlers`
 
   /**
-   * @since 4.0.0
+   * Extracts the error channel from an effect that produces a `Handlers`
+   * collection, returning `never` for non-effectful handler collections.
+   *
    * @category handlers
+   * @since 4.0.0
    */
   export type Error<A> = A extends Effect.Effect<
     Handlers<
@@ -278,8 +332,11 @@ export declare namespace Handlers {
     never
 
   /**
-   * @since 4.0.0
+   * Extracts the services required by a handler collection, including both handler
+   * requirements and the environment required to construct the handlers.
+   *
    * @category handlers
+   * @since 4.0.0
    */
   export type Context<A> = A extends Handlers<
     infer _R,
@@ -297,8 +354,11 @@ export declare namespace Handlers {
 }
 
 /**
- * @since 4.0.0
+ * Builds the server-side HTTP effect for a single endpoint in an API group using
+ * the endpoint metadata, middleware, codecs, and supplied handler.
+ *
  * @category handlers
+ * @since 4.0.0
  */
 export const endpoint = <
   ApiId extends string,
@@ -351,8 +411,11 @@ export const endpoint = <
   })
 
 /**
- * @since 4.0.0
+ * Decodes credentials for an HTTP API security scheme from the current request,
+ * supporting bearer, API key, and basic authentication inputs.
+ *
  * @category security
+ * @since 4.0.0
  */
 export const securityDecode = <Security extends HttpApiSecurity.HttpApiSecurity>(
   self: Security
@@ -415,8 +478,11 @@ export const securityDecode = <Security extends HttpApiSecurity.HttpApiSecurity>
 }
 
 /**
- * @since 4.0.0
+ * Registers a pre-response handler that sets an API-key cookie on the outgoing
+ * response, defaulting the cookie to `secure` and `httpOnly` unless overridden.
+ *
  * @category security
+ * @since 4.0.0
  */
 export const securitySetCookie = (
   self: HttpApiSecurity.ApiKey,

package/src/unstable/httpapi/HttpApiClient.ts

@@ -1,4 +1,25 @@
 /**
+ * Builds type-safe clients and URL builders from `HttpApi` declarations.
+ *
+ * This module turns the groups and endpoints described by an `HttpApi` into
+ * callable client methods backed by an `HttpClient`. Applications commonly use
+ * `make` or `makeWith` to call a remote API with the same schema-driven contract
+ * as the server, while `group`, `endpoint`, and `urlBuilder` are useful when only
+ * part of an API or only the encoded URL is needed.
+ *
+ * Client calls encode path parameters, query values, headers, and payloads from
+ * endpoint schemas before executing the request, then decode successful responses
+ * according to the endpoint success schemas. The selected `responseMode` can
+ * return the decoded value, the raw `HttpClientResponse`, or both; the raw
+ * response mode skips success and error decoding for custom response handling.
+ *
+ * Pay attention to the endpoint schemas when shaping requests: payloads for HTTP
+ * methods without request bodies are encoded into URL parameters, multipart
+ * payloads must be supplied as `FormData`, and response decoding can fail with
+ * `SchemaError`. Declared error responses are decoded into the endpoint error
+ * type, unknown statuses fail as `HttpClientError.DecodeError`, and failures while
+ * decoding a declared error response include the original status-code failure.
+ *
  * @since 4.0.0
  */
 import * as Arr from "../../Array.ts"
@@ -28,8 +49,11 @@ import type * as HttpApiMiddleware from "./HttpApiMiddleware.ts"
 import * as HttpApiSchema from "./HttpApiSchema.ts"
 
 /**
- * @since 4.0.0
+ * The type-safe client shape generated from HTTP API groups, with non-top-level
+ * groups exposed as nested objects and top-level endpoints exposed as methods.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type Client<Groups extends HttpApiGroup.Any, E = never, R = never> = Simplify<
   & {
@@ -46,27 +70,39 @@ export type Client<Groups extends HttpApiGroup.Any, E = never, R = never> = Simp
 >
 
 /**
- * @since 4.0.0
+ * Derives the typed client interface for an `HttpApi`, preserving any additional
+ * client error and service requirements supplied by the caller.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type ForApi<Api extends HttpApi.Any, E = never, R = never> = Api extends
   HttpApi.HttpApi<infer _Id, infer Groups> ? Client<Groups, E, R> :
   never
 
 /**
- * @since 4.0.0
+ * Helper types used to describe generated HTTP API clients, including endpoint
+ * methods, response modes, and grouped client shapes.
+ *
  * @category models
+ * @since 4.0.0
  */
 export declare namespace Client {
   /**
-   * @since 4.0.0
+   * The response mode accepted by generated client methods, controlling whether a
+   * call returns the decoded success value, the raw response, or both.
+   *
    * @category models
+   * @since 4.0.0
    */
   export type ResponseMode = HttpApiEndpoint.ClientResponseMode
 
   /**
-   * @since 4.0.0
+   * Computes the value returned by a client method for a success type and response
+   * mode.
+   *
    * @category models
+   * @since 4.0.0
    */
   export type Response<Success, Mode extends ResponseMode> = [Mode] extends ["decoded-and-response"]
     ? [Success, HttpClientResponse.HttpClientResponse]
@@ -74,8 +110,11 @@ export declare namespace Client {
     : Success
 
   /**
-   * @since 4.0.0
+   * The client object for one API group, mapping each endpoint name in that group to
+   * its typed client method.
+   *
    * @category models
+   * @since 4.0.0
    */
   export type Group<Groups extends HttpApiGroup.Any, GroupName extends Groups["identifier"], E, R> =
     [HttpApiGroup.WithName<Groups, GroupName>] extends [HttpApiGroup.HttpApiGroup<infer _GroupName, infer _Endpoints>] ?
@@ -85,8 +124,12 @@ export declare namespace Client {
       never
 
   /**
-   * @since 4.0.0
+   * The typed function generated for an endpoint, accepting the endpoint request
+   * shape and returning an effect whose success, error, and service channels reflect
+   * the endpoint schemas, middleware, and selected response mode.
+   *
    * @category models
+   * @since 4.0.0
    */
   export type Method<Endpoint, E, R> = [Endpoint] extends [
     HttpApiEndpoint.HttpApiEndpoint<
@@ -121,8 +164,11 @@ export declare namespace Client {
     never
 
   /**
-   * @since 4.0.0
+   * Extracts client methods for endpoints in top-level groups so they can be exposed
+   * directly on the generated client object.
+   *
    * @category models
+   * @since 4.0.0
    */
   export type TopLevelMethods<Groups extends HttpApiGroup.Any, E, R> =
     Extract<Groups, { readonly topLevel: true }> extends
@@ -145,8 +191,11 @@ type UrlBuilderArgs<Endpoint extends HttpApiEndpoint.Any> = [UrlBuilderRequest<E
   : [request: UrlBuilderRequest<Endpoint>]
 
 /**
- * @since 4.0.0
+ * The type-safe URL builder shape for an HTTP API, mirroring the generated client
+ * layout while returning URL strings instead of executing requests.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type UrlBuilder<Api extends HttpApi.Any> = Api extends HttpApi.HttpApi<infer _ApiId, infer Groups> ? Simplify<
     & {
@@ -369,8 +418,11 @@ export const makeClient = <ApiId extends string, Groups extends HttpApiGroup.Any
   })
 
 /**
- * @since 4.0.0
+ * Constructs a type-safe client for an HTTP API using the `HttpClient` service,
+ * endpoint schemas, middleware, and optional client or response transformations.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const make = <ApiId extends string, Groups extends HttpApiGroup.Any>(
   api: HttpApi.HttpApi<ApiId, Groups>,
@@ -393,8 +445,12 @@ export const make = <ApiId extends string, Groups extends HttpApiGroup.Any>(
     }))
 
 /**
- * @since 4.0.0
+ * Constructs a type-safe client for an HTTP API from the supplied `HttpClient`,
+ * using the API metadata to encode requests, execute middleware, and decode
+ * responses.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const makeWith = <ApiId extends string, Groups extends HttpApiGroup.Any, E, R>(
   api: HttpApi.HttpApi<ApiId, Groups>,
@@ -420,8 +476,11 @@ export const makeWith = <ApiId extends string, Groups extends HttpApiGroup.Any,
 }
 
 /**
- * @since 4.0.0
+ * Builds a typed client object for a single API group from the supplied
+ * `HttpClient`, filtering the API to that group.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const group = <
   ApiId extends string,
@@ -455,8 +514,11 @@ export const group = <
 }
 
 /**
- * @since 4.0.0
+ * Builds the typed client method for one endpoint in one API group, using the
+ * supplied `HttpClient` and endpoint metadata.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const endpoint = <
   ApiId extends string,
@@ -501,7 +563,8 @@ export const endpoint = <
 /**
  * Creates a type-safe URL builder that mirrors `HttpApiClient.make`.
  *
- * @example
+ * **Example** (Building typed URLs)
+ *
  * ```ts
  * import { Schema } from "effect"
  * import { HttpApi, HttpApiClient, HttpApiEndpoint, HttpApiGroup } from "effect/unstable/httpapi"
@@ -523,8 +586,9 @@ export const endpoint = <
  * })
  * //=> "https://api.example.com/users/123"
  * ```
- * @since 4.0.0
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const urlBuilder = <Api extends HttpApi.Any>(api: Api, options?: {
   readonly baseUrl?: URL | string | undefined