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

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,

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,29 @@ export interface Handlers<
 }
 
 /**
+ * Namespace containing helper types for `HttpApiBuilder` handler collections.
+ *
  * @since 4.0.0
- * @category handlers
  */
 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 +277,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 +289,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 +314,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 +331,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 +353,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 +410,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 +477,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,38 @@ 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
 
 /**
+ * Helper types used to describe generated HTTP API clients, including endpoint
+ * methods, response modes, and grouped client shapes.
+ *
  * @since 4.0.0
- * @category models
  */
 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 +109,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 +123,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 +163,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 +190,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 +417,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 +444,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 +475,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 +513,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 +562,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 +585,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