effect 4.0.0-beta.65 → 4.0.0-beta.67

package/src/unstable/httpapi/HttpApiEndpoint.ts

@@ -1,4 +1,28 @@
 /**
+ * The `HttpApiEndpoint` module defines the per-route contracts used inside an
+ * `HttpApiGroup`.
+ *
+ * An endpoint couples a stable name with an HTTP method and `HttpRouter` path,
+ * plus schemas for path parameters, query parameters, headers, request payloads,
+ * success responses, and declared errors. Server builders, generated clients,
+ * and OpenAPI generation all read this metadata to decode requests, encode
+ * responses, type handler inputs, and derive client call signatures.
+ *
+ * Use this module to declare individual operations such as `get`, `post`, `put`,
+ * `patch`, `delete`, `head`, and `options`; attach endpoint-specific middleware
+ * or annotations; and model alternatives for payloads, successes, and errors
+ * with arrays of schemas.
+ *
+ * A few declaration details are worth keeping in mind. Paths use
+ * `HttpRouter.PathInput`, so route parameters come from the router and are
+ * decoded with the optional `params` schema. When codecs are enabled, params,
+ * query, and headers are transformed through string-tree codecs; body methods
+ * use JSON payload codecs by default, while no-body methods encode payloads as
+ * query-style values. `HttpApiSchema` annotations can change payload or response
+ * encodings and status codes, multipart payloads cannot be combined under the
+ * same content type, and endpoint errors are merged with middleware errors for
+ * server encoding and client decoding.
+ *
  * @since 4.0.0
  */
 import * as Arr from "../../Array.ts"
@@ -23,14 +47,20 @@ import * as HttpApiSchema from "./HttpApiSchema.ts"
 const TypeId = "~effect/httpapi/HttpApiEndpoint"
 
 /**
- * @since 4.0.0
+ * Returns `true` when a value is an `HttpApiEndpoint`, narrowing the value to the
+ * endpoint interface.
+ *
  * @category guards
+ * @since 4.0.0
  */
 export const isHttpApiEndpoint = (u: unknown): u is HttpApiEndpoint<any, any, any> => Predicate.hasProperty(u, TypeId)
 
 /**
- * @since 4.0.0
+ * Maps content types to the payload encoding strategy and one or more schemas that
+ * can decode or encode payloads for that content type.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type PayloadMap = ReadonlyMap<string, {
   readonly encoding: HttpApiSchema.PayloadEncoding
@@ -41,8 +71,8 @@ export type PayloadMap = ReadonlyMap<string, {
  * Represents an API endpoint. An API endpoint is mapped to a single route on
  * the underlying `HttpRouter`.
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface HttpApiEndpoint<
   out Name extends string,
@@ -183,8 +213,11 @@ export function getErrorSchemas(endpoint: AnyWithProps): Array<Schema.Top> {
 }
 
 /**
- * @since 4.0.0
+ * A widened `HttpApiEndpoint` type used when the concrete method, path, schemas,
+ * and middleware types are not needed.
+ *
  * @category models
+ * @since 4.0.0
  */
 export interface Any extends Pipeable {
   readonly [TypeId]: any
@@ -194,16 +227,21 @@ export interface Any extends Pipeable {
 }
 
 /**
- * @since 4.0.0
+ * A widened endpoint type that preserves concrete runtime properties such as
+ * method, path, schemas, annotations, and middleware sets.
+ *
  * @category models
+ * @since 4.0.0
  */
 export interface AnyWithProps
   extends HttpApiEndpoint<string, HttpMethod, string, Schema.Top, Schema.Top, Schema.Top, Schema.Top, any, any>
 {}
 
 /**
- * @since 4.0.0
+ * Extracts the name literal from an `HttpApiEndpoint`.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type Name<Endpoint> = Endpoint extends HttpApiEndpoint<
   infer _Name,
@@ -221,8 +259,10 @@ export type Name<Endpoint> = Endpoint extends HttpApiEndpoint<
   : never
 
 /**
- * @since 4.0.0
+ * Extracts the success schema associated with an endpoint.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type Success<Endpoint extends Any> = Endpoint extends HttpApiEndpoint<
   infer _Name,
@@ -240,8 +280,10 @@ export type Success<Endpoint extends Any> = Endpoint extends HttpApiEndpoint<
   : never
 
 /**
- * @since 4.0.0
+ * Extracts the error schema associated with an endpoint.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type Error<Endpoint extends Any> = Endpoint extends HttpApiEndpoint<
   infer _Name,
@@ -259,8 +301,10 @@ export type Error<Endpoint extends Any> = Endpoint extends HttpApiEndpoint<
   : never
 
 /**
- * @since 4.0.0
+ * Extracts the schema used for an endpoint's path parameters.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type Params<Endpoint extends Any> = Endpoint extends HttpApiEndpoint<
   infer _Name,
@@ -278,8 +322,10 @@ export type Params<Endpoint extends Any> = Endpoint extends HttpApiEndpoint<
   : never
 
 /**
- * @since 4.0.0
+ * Extracts the schema used for an endpoint's query parameters.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type Query<Endpoint extends Any> = Endpoint extends HttpApiEndpoint<
   infer _Name,
@@ -297,8 +343,10 @@ export type Query<Endpoint extends Any> = Endpoint extends HttpApiEndpoint<
   : never
 
 /**
- * @since 4.0.0
+ * Extracts the schema used for an endpoint's request payload.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type Payload<Endpoint extends Any> = Endpoint extends HttpApiEndpoint<
   infer _Name,
@@ -316,8 +364,10 @@ export type Payload<Endpoint extends Any> = Endpoint extends HttpApiEndpoint<
   : never
 
 /**
- * @since 4.0.0
+ * Extracts the schema used for an endpoint's request headers.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type Headers<Endpoint extends Any> = Endpoint extends HttpApiEndpoint<
   infer _Name,
@@ -335,8 +385,10 @@ export type Headers<Endpoint extends Any> = Endpoint extends HttpApiEndpoint<
   : never
 
 /**
- * @since 4.0.0
+ * Extracts the middleware identifiers attached to an endpoint.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type Middleware<Endpoint extends Any> = Endpoint extends HttpApiEndpoint<
   infer _Name,
@@ -354,26 +406,36 @@ export type Middleware<Endpoint extends Any> = Endpoint extends HttpApiEndpoint<
   : never
 
 /**
- * @since 4.0.0
+ * Computes the services provided by the middleware attached to an endpoint.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type MiddlewareProvides<Endpoint extends Any> = HttpApiMiddleware.Provides<Middleware<Endpoint>>
 
 /**
- * @since 4.0.0
+ * Computes the client-side middleware services required by an endpoint.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type MiddlewareClient<Endpoint extends Any> = HttpApiMiddleware.MiddlewareClient<Middleware<Endpoint>>
 
 /**
- * @since 4.0.0
+ * Computes the error types that can be produced by the middleware attached to an
+ * endpoint.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type MiddlewareError<Endpoint extends Any> = HttpApiMiddleware.Error<Middleware<Endpoint>>
 
 /**
- * @since 4.0.0
+ * Computes the full error value union for an endpoint, including the endpoint
+ * error schema's type and errors introduced by middleware.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type Errors<Endpoint extends Any> = Endpoint extends HttpApiEndpoint<
   infer _Name,
@@ -391,8 +453,11 @@ export type Errors<Endpoint extends Any> = Endpoint extends HttpApiEndpoint<
   : never
 
 /**
- * @since 4.0.0
+ * Computes the services required to encode an endpoint's error responses,
+ * including services required by middleware error encoders.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type ErrorServicesEncode<Endpoint extends Any> = Endpoint extends HttpApiEndpoint<
   infer _Name,
@@ -410,8 +475,12 @@ export type ErrorServicesEncode<Endpoint extends Any> = Endpoint extends HttpApi
   : never
 
 /**
- * @since 4.0.0
+ * Builds the decoded request shape passed to a normal endpoint handler, including
+ * available params, query, payload, headers, the raw request, endpoint, and group.
+ * Multipart stream payloads are exposed as streams of parts.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type Request<Endpoint extends Any> = Endpoint extends HttpApiEndpoint<
   infer _Name,
@@ -441,8 +510,12 @@ export type Request<Endpoint extends Any> = Endpoint extends HttpApiEndpoint<
   : {}
 
 /**
- * @since 4.0.0
+ * Builds the request shape passed to a raw endpoint handler, including decoded
+ * params, query, and headers plus the raw request, endpoint, and group, while
+ * leaving payload handling to the raw request.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type RequestRaw<Endpoint extends Any> = Endpoint extends HttpApiEndpoint<
   infer _Name,
@@ -468,8 +541,12 @@ export type RequestRaw<Endpoint extends Any> = Endpoint extends HttpApiEndpoint<
   : {}
 
 /**
- * @since 4.0.0
+ * Builds the request object accepted by a generated client method, including only
+ * the params, query, headers, payload, and response mode fields required by the
+ * endpoint. Multipart payloads are supplied as `FormData`.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type ClientRequest<
   Params extends Schema.Top,
@@ -492,14 +569,20 @@ export type ClientRequest<
   void
 
 /**
- * @since 4.0.0
+ * Controls what a generated client method returns: the decoded success value,
+ * the decoded value paired with the raw response, or only the raw response.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type ClientResponseMode = "decoded-only" | "decoded-and-response" | "response-only"
 
 /**
- * @since 4.0.0
+ * Computes the services required on the server to decode endpoint inputs and
+ * encode endpoint success, error, and middleware error responses.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type ServerServices<Endpoint> = Endpoint extends HttpApiEndpoint<
   infer _Name,
@@ -524,8 +607,11 @@ export type ServerServices<Endpoint> = Endpoint extends HttpApiEndpoint<
   : never
 
 /**
- * @since 4.0.0
+ * Computes the services required on the client to encode endpoint requests and
+ * decode endpoint success or error responses.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type ClientServices<Endpoint> = Endpoint extends HttpApiEndpoint<
   infer _Name,
@@ -549,8 +635,10 @@ export type ClientServices<Endpoint> = Endpoint extends HttpApiEndpoint<
   : never
 
 /**
- * @since 4.0.0
+ * Extracts the additional services required by middleware applied to an endpoint.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type MiddlewareServices<Endpoint> = Endpoint extends HttpApiEndpoint<
   infer _Name,
@@ -568,8 +656,11 @@ export type MiddlewareServices<Endpoint> = Endpoint extends HttpApiEndpoint<
   : never
 
 /**
- * @since 4.0.0
+ * Computes the services required to decode an endpoint's error responses,
+ * including services required by middleware error decoders.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type ErrorServicesDecode<Endpoint> = Endpoint extends HttpApiEndpoint<
   infer _Name,
@@ -587,36 +678,49 @@ export type ErrorServicesDecode<Endpoint> = Endpoint extends HttpApiEndpoint<
   : never
 
 /**
- * @since 4.0.0
+ * The normal server handler for an endpoint, accepting the decoded request shape
+ * and returning either the endpoint success value or a custom `HttpServerResponse`.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type Handler<Endpoint extends Any, E, R> = (
   request: Types.Simplify<Request<Endpoint>>
 ) => Effect<Endpoint["~Success"]["Type"] | HttpServerResponse, Endpoint["~Error"]["Type"] | E, R>
 
 /**
- * @since 4.0.0
+ * The raw server handler for an endpoint, receiving a request shape without a
+ * decoded payload so the handler can read the raw `HttpServerRequest` directly.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type HandlerRaw<Endpoint extends Any, E, R> = (
   request: Types.Simplify<RequestRaw<Endpoint>>
 ) => Effect<Endpoint["~Success"]["Type"] | HttpServerResponse, Endpoint["~Error"]["Type"] | E, R>
 
 /**
- * @since 4.0.0
+ * Selects the endpoint with the specified name from a union of endpoints.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type WithName<Endpoints extends Any, Name extends string> = Extract<Endpoints, { readonly name: Name }>
 
 /**
- * @since 4.0.0
+ * Removes endpoints with the specified name from a union of endpoints.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type ExcludeName<Endpoints extends Any, Name extends string> = Exclude<Endpoints, { readonly name: Name }>
 
 /**
- * @since 4.0.0
+ * Derives the normal handler type for the endpoint with the specified name in an
+ * endpoint union.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type HandlerWithName<Endpoints extends Any, Name extends string, E, R> = Handler<
   WithName<Endpoints, Name>,
@@ -625,8 +729,11 @@ export type HandlerWithName<Endpoints extends Any, Name extends string, E, R> =
 >
 
 /**
- * @since 4.0.0
+ * Derives the raw handler type for the endpoint with the specified name in an
+ * endpoint union.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type HandlerRawWithName<Endpoints extends Any, Name extends string, E, R> = HandlerRaw<
   WithName<Endpoints, Name>,
@@ -635,44 +742,62 @@ export type HandlerRawWithName<Endpoints extends Any, Name extends string, E, R>
 >
 
 /**
- * @since 4.0.0
+ * Extracts the decoded success value type for the endpoint with the specified name
+ * in an endpoint union.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type SuccessWithName<Endpoints extends Any, Name extends string> = Success<
   WithName<Endpoints, Name>
 >["Type"]
 
 /**
- * @since 4.0.0
+ * Computes the full error value union for the endpoint with the specified name in
+ * an endpoint union.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type ErrorsWithName<Endpoints extends Any, Name extends string> = Errors<WithName<Endpoints, Name>>
 
 /**
- * @since 4.0.0
+ * Computes the server-side service requirements for the endpoint with the
+ * specified name in an endpoint union.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type ServerServicesWithName<Endpoints extends Any, Name extends string> = ServerServices<
   WithName<Endpoints, Name>
 >
 
 /**
- * @since 4.0.0
+ * Extracts the middleware identifiers for the endpoint with the specified name in
+ * an endpoint union.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type MiddlewareWithName<Endpoints extends Any, Name extends string> = Middleware<WithName<Endpoints, Name>>
 
 /**
- * @since 4.0.0
+ * Extracts the middleware service requirements for the endpoint with the specified
+ * name in an endpoint union.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type MiddlewareServicesWithName<Endpoints extends Any, Name extends string> = MiddlewareServices<
   WithName<Endpoints, Name>
 >
 
 /**
- * @since 4.0.0
+ * Removes services provided by the HTTP router and the named endpoint's middleware
+ * from a service requirement union.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type ExcludeProvidedWithName<Endpoints extends Any, Name extends string, R> = ExcludeProvided<
   WithName<Endpoints, Name>,
@@ -680,8 +805,11 @@ export type ExcludeProvidedWithName<Endpoints extends Any, Name extends string,
 >
 
 /**
- * @since 4.0.0
+ * Removes services provided by the HTTP router and endpoint middleware from a
+ * service requirement union.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type ExcludeProvided<Endpoint extends Any, R> = Exclude<
   R,
@@ -690,8 +818,11 @@ export type ExcludeProvided<Endpoint extends Any, R> = Exclude<
 >
 
 /**
- * @since 4.0.0
+ * Returns an endpoint type with the supplied path prefix prepended while
+ * preserving the endpoint's schemas, method, errors, and middleware.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type AddPrefix<Endpoint extends Any, Prefix extends HttpRouter.PathInput> = Endpoint extends HttpApiEndpoint<
   infer _Name,
@@ -721,8 +852,11 @@ export type AddPrefix<Endpoint extends Any, Prefix extends HttpRouter.PathInput>
   never
 
 /**
- * @since 4.0.0
+ * Returns an endpoint type with an additional error schema added to the endpoint's
+ * existing error schema union.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type AddError<Endpoint extends Any, E extends Schema.Top> = Endpoint extends HttpApiEndpoint<
   infer _Name,
@@ -752,8 +886,11 @@ export type AddError<Endpoint extends Any, E extends Schema.Top> = Endpoint exte
   never
 
 /**
- * @since 4.0.0
+ * Returns an endpoint type with additional middleware applied and the endpoint's
+ * middleware service requirements updated accordingly.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type AddMiddleware<Endpoint extends Any, M extends HttpApiMiddleware.AnyId> = Endpoint extends HttpApiEndpoint<
   infer _Name,
@@ -854,24 +991,33 @@ function makeProto<
 }
 
 /**
- * @since 4.0.0
+ * Constraint for path parameter schemas: each parameter must encode to
+ * `string | undefined`, or the schema must encode to a record of those values.
+ *
  * @category constraints
+ * @since 4.0.0
  */
 export type ParamsConstraint =
   | Record<string, Schema.Encoder<string | undefined, unknown>>
   | Schema.Encoder<Record<string, string | undefined>, unknown>
 
 /**
- * @since 4.0.0
+ * Constraint for header schemas: each header must encode to `string | undefined`,
+ * or the schema must encode to a record of those values.
+ *
  * @category constraints
+ * @since 4.0.0
  */
 export type HeadersConstraint =
   | Record<string, Schema.Encoder<string | undefined, unknown>>
   | Schema.Encoder<Record<string, string | undefined>, unknown>
 
 /**
- * @since 4.0.0
+ * Constraint for query schemas: each field must encode to `string`, an array of
+ * strings, or `undefined`, or the schema must encode to a record of those values.
+ *
  * @category constraints
+ * @since 4.0.0
  */
 export type QueryConstraint =
   | Record<string, Schema.Encoder<string | ReadonlyArray<string> | undefined, unknown>>
@@ -885,8 +1031,8 @@ export type QueryConstraint =
  * - for body methods, payload may be any `Schema.Top` (or content-type keyed
  *   schemas) and OpenAPI uses `requestBody` instead of `parameters`
  *
- * @since 4.0.0
  * @category constraints
+ * @since 4.0.0
  */
 export type PayloadConstraint<Method extends HttpMethod> = Method extends HttpMethod.NoBody ? Record<
     string,
@@ -895,28 +1041,43 @@ export type PayloadConstraint<Method extends HttpMethod> = Method extends HttpMe
   SuccessConstraint
 
 /**
- * @since 4.0.0
+ * Payload constraint used when automatic codecs are enabled: no-body methods
+ * accept field records for query-style encoding, while body methods accept one or
+ * more schemas.
+ *
  * @category constraints
+ * @since 4.0.0
  */
 export type PayloadConstraintCodecs<Method extends HttpMethod> = Method extends HttpMethod.NoBody ?
   Record<string, Schema.Top> :
   Schema.Top | ReadonlyArray<Schema.Top>
 
 /**
- * @since 4.0.0
+ * Constraint for success response schemas, allowing either a single schema or a
+ * readonly array of schemas.
+ *
  * @category constraints
+ * @since 4.0.0
  */
 export type SuccessConstraint = Schema.Top | ReadonlyArray<Schema.Top>
 
 /**
- * @since 4.0.0
+ * Constraint for error response schemas, allowing either a single schema or a
+ * readonly array of schemas.
+ *
  * @category constraints
+ * @since 4.0.0
  */
 export type ErrorConstraint = Schema.Top | ReadonlyArray<Schema.Top>
 
 /**
- * @since 4.0.0
+ * Creates endpoint constructors for a specific HTTP method. The resulting
+ * constructor builds an `HttpApiEndpoint` from a name, path, and optional request
+ * and response schemas, applying automatic JSON or string-tree codecs unless
+ * `disableCodecs` is enabled.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const make = <Method extends HttpMethod>(method: Method): {
   <
@@ -1042,16 +1203,22 @@ type ExtractSchemaOrArray<S extends Schema.Struct.Fields | Schema.Top | Readonly
   : S
 
 /**
- * @since 4.0.0
+ * A schema codec that decodes and encodes the schema's value type through JSON
+ * transport values.
+ *
  * @category Codecs
+ * @since 4.0.0
  */
 export interface Json<S extends Schema.Top>
   extends Schema.Codec<S["Type"], Schema.Json, S["DecodingServices"], S["EncodingServices"]>
 {}
 
 /**
- * @since 4.0.0
+ * A schema codec that decodes and encodes the schema's value type through
+ * `Schema.StringTree` transport values.
+ *
  * @category Codecs
+ * @since 4.0.0
  */
 export interface StringTree<S extends Schema.Top> extends
   Schema.Codec<
@@ -1141,26 +1308,34 @@ function transformPayload(schema: Schema.Top, method: HttpMethod): Schema.Top {
 }
 
 /**
- * @since 4.0.0
+ * Creates a `GET` endpoint declaration.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const get = make("GET")
 
 /**
- * @since 4.0.0
+ * Creates a `POST` endpoint declaration.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const post = make("POST")
 
 /**
- * @since 4.0.0
+ * Creates a `PUT` endpoint declaration.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const put = make("PUT")
 
 /**
- * @since 4.0.0
+ * Creates a `PATCH` endpoint declaration.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const patch = make("PATCH")
 
@@ -1168,20 +1343,24 @@ const del = make("DELETE")
 
 export {
   /**
-   * @since 4.0.0
    * @category constructors
+   * @since 4.0.0
    */
   del as delete
 }
 
 /**
- * @since 4.0.0
+ * Creates a `HEAD` endpoint declaration.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const head = make("HEAD")
 
 /**
- * @since 4.0.0
+ * Creates an `OPTIONS` endpoint declaration.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const options = make("OPTIONS")