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

package/src/unstable/httpapi/HttpApiMiddleware.ts

@@ -1,4 +1,29 @@
 /**
+ * The `HttpApiMiddleware` module defines middleware services that can wrap
+ * `HttpApi` endpoint execution on the server and request execution in generated
+ * clients.
+ *
+ * Use this module for cross-cutting HTTP API behavior such as authentication and
+ * authorization, request logging or tracing, rate limiting, adding request-scoped
+ * services to the endpoint context, normalizing schema errors, or installing
+ * client-side request middleware for APIs that require the same concern on both
+ * sides. Middleware services carry type-level metadata describing the services
+ * they require and provide, the error schemas they may fail with, whether they
+ * implement security schemes, and whether generated clients must provide a
+ * matching client middleware.
+ *
+ * Security middleware is declared with non-empty `security` schemes and receives
+ * decoded credentials from `HttpApiSecurity`; ordinary middleware receives only
+ * endpoint and group metadata. Error declarations must be `Schema` values (or an
+ * array of them) because middleware failures are added to the endpoint error
+ * surface and must be encodable by the HTTP API builder. If a middleware turns
+ * `HttpApiSchemaError` failures into API errors, use
+ * `layerSchemaErrorTransform` and make sure the transformed error is covered by
+ * the middleware's declared schema. Client middleware installed with
+ * `layerClient` is made available through the `ForClient` marker and captures
+ * its surrounding context, so client requirements should be declared explicitly
+ * when `requiredForClient` is enabled.
+ *
  * @since 4.0.0
  */
 /** @effect-diagnostics floatingEffect:skip-file */
@@ -25,8 +50,10 @@ const TypeId = "~effect/httpapi/HttpApiMiddleware"
 const SecurityTypeId = "~effect/httpapi/HttpApiMiddleware/Security"
 
 /**
- * @since 4.0.0
+ * Returns `true` when an HTTP API middleware service is security middleware.
+ *
  * @category guards
+ * @since 4.0.0
  */
 export const isSecurity = (u: AnyService): u is AnyServiceSecurity => hasProperty(u, SecurityTypeId)
 
@@ -37,8 +64,14 @@ type ErrorSchemaFromConstraint<E> = E extends ReadonlyArray<Schema.Top> ? E[numb
   : never
 
 /**
- * @since 4.0.0
+ * Server-side middleware function for an HTTP API endpoint.
+ *
+ * It receives the endpoint response effect and endpoint/group metadata, and returns
+ * a new response effect that may require additional services and fail with the
+ * middleware's declared error schema.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type HttpApiMiddleware<Provides, E extends ErrorConstraint, Requires> = (
   httpEffect: Effect.Effect<HttpServerResponse, unhandled, Provides>,
@@ -49,8 +82,13 @@ export type HttpApiMiddleware<Provides, E extends ErrorConstraint, Requires> = (
 ) => Effect.Effect<HttpServerResponse, unhandled | ErrorSchemaFromConstraint<E>["Type"], Requires | HttpRouter.Provided>
 
 /**
- * @since 4.0.0
+ * Server-side middleware implementations for one or more security schemes.
+ *
+ * Each property handles the credential decoded for that scheme and wraps the
+ * endpoint response effect with the middleware's declared requirements and errors.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type HttpApiMiddlewareSecurity<
   Security extends Record<string, HttpApiSecurity.HttpApiSecurity>,
@@ -73,8 +111,13 @@ export type HttpApiMiddlewareSecurity<
 }
 
 /**
- * @since 4.0.0
+ * Client-side middleware function for generated HTTP API clients.
+ *
+ * It receives endpoint/group metadata, the outgoing request, and a `next` function
+ * for continuing the request pipeline.
+ *
  * @category models
+ * @since 4.0.0
  */
 export interface HttpApiMiddlewareClient<_E, CE, R> {
   (options: {
@@ -88,8 +131,10 @@ export interface HttpApiMiddlewareClient<_E, CE, R> {
 }
 
 /**
- * @since 4.0.0
+ * Client-side service marker required when a middleware declares `requiredForClient`.
+ *
  * @category models
+ * @since 4.0.0
  */
 export interface ForClient<Id> {
   readonly _: unique symbol
@@ -97,8 +142,10 @@ export interface ForClient<Id> {
 }
 
 /**
- * @since 4.0.0
+ * Base service key shape for HTTP API middleware services, including provided services, declared error schemas, and client requirements.
+ *
  * @category models
+ * @since 4.0.0
  */
 export interface AnyService extends Context.Key<any, any> {
   readonly [TypeId]: typeof TypeId
@@ -109,8 +156,10 @@ export interface AnyService extends Context.Key<any, any> {
 }
 
 /**
- * @since 4.0.0
+ * Middleware service key shape for security middleware, including the security schemes handled by the service.
+ *
  * @category models
+ * @since 4.0.0
  */
 export interface AnyServiceSecurity extends AnyService {
   readonly [SecurityTypeId]: typeof SecurityTypeId
@@ -118,8 +167,10 @@ export interface AnyServiceSecurity extends AnyService {
 }
 
 /**
- * @since 4.0.0
+ * Type-level identifier carried by middleware services to track provided services, required services, errors, client errors, and client requirements.
+ *
  * @category models
+ * @since 4.0.0
  */
 export interface AnyId {
   readonly [TypeId]: {
@@ -132,39 +183,51 @@ export interface AnyId {
 }
 
 /**
- * @since 4.0.0
+ * Extracts the services provided by a middleware identifier.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type Provides<A> = A extends { readonly [TypeId]: { readonly provides: infer P } } ? P : never
 
 /**
- * @since 4.0.0
+ * Extracts the services required to run a middleware implementation.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type Requires<A> = A extends { readonly [TypeId]: { readonly requires: infer R } } ? R : never
 
 /**
- * @since 4.0.0
+ * Applies a middleware's service changes to an existing requirement type by removing services it provides and adding services it requires.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type ApplyServices<A extends AnyId, R> = Exclude<R, Provides<A>> | Requires<A>
 
 /**
- * @since 4.0.0
+ * Extracts the schema or schema union used for errors declared by a middleware identifier.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type ErrorSchema<A> = A extends { readonly [TypeId]: { readonly error: infer E } } ? ErrorSchemaFromConstraint<E>
   : never
 
 /**
- * @since 4.0.0
+ * Extracts the decoded error type declared by a middleware identifier.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type Error<A> = ErrorSchema<A>["Type"]
 
 /**
- * @since 4.0.0
+ * Extracts the client-side error type for middleware that is required on generated clients.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type ClientError<A> = A extends {
   readonly [TypeId]: {
@@ -175,8 +238,10 @@ export type ClientError<A> = A extends {
   : never
 
 /**
- * @since 4.0.0
+ * Computes the client-side service marker required for middleware that must also run in generated clients.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type MiddlewareClient<A> = A extends {
   readonly [TypeId]: {
@@ -186,20 +251,29 @@ export type MiddlewareClient<A> = A extends {
   : never
 
 /**
- * @since 4.0.0
+ * Extracts the schema services required to encode errors declared by a middleware identifier.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type ErrorServicesEncode<A> = ErrorSchema<A>["EncodingServices"]
 
 /**
- * @since 4.0.0
+ * Extracts the schema services required to decode errors declared by a middleware identifier.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type ErrorServicesDecode<A> = ErrorSchema<A>["DecodingServices"]
 
 /**
+ * Class type produced by `Service` for an HTTP API middleware service.
+ *
+ * It combines a `Context.Service` class with the middleware metadata used by
+ * endpoints, builders, and generated clients.
+ *
+ * @category schemas
  * @since 4.0.0
- * @category Schemas
  */
 export type ServiceClass<
   Self,
@@ -238,8 +312,14 @@ export type ServiceClass<
   })
 
 /**
+ * Creates a `Context.Service` class for an HTTP API middleware implementation.
+ *
+ * Use the optional configuration to declare required services, provided services,
+ * typed error schemas, security schemes, client errors, and whether generated
+ * clients must provide a matching client middleware.
+ *
+ * @category schemas
  * @since 4.0.0
- * @category Schemas
  */
 export const Service = <
   Self,
@@ -308,7 +388,13 @@ function getError(error: ErrorConstraint | undefined): ReadonlySet<Schema.Top> {
 }
 
 /**
- * Implement a middleware Layer that transforms `SchemaError`'s.
+ * Creates a middleware layer that transforms `HttpApiSchemaError` failures.
+ *
+ * The middleware catches schema errors produced while running an endpoint and uses
+ * the supplied `transform` function to convert them into the middleware's declared
+ * error schema.
+ *
+ * **Example** (Mapping schema errors to custom errors)
  *
  * ```ts
  * import { Effect, Schema } from "effect"
@@ -329,8 +415,8 @@ function getError(error: ErrorConstraint | undefined): ReadonlySet<Schema.Top> {
  * )
  * ```
  *
- * @since 4.0.0
  * @category SchemaError transform
+ * @since 4.0.0
  */
 export const layerSchemaErrorTransform = <Id, E extends ErrorConstraint, Requires>(
   service: Context.Service<Id, HttpApiMiddleware<never, E, Requires>>,
@@ -357,8 +443,13 @@ export const layerSchemaErrorTransform = <Id, E extends ErrorConstraint, Require
   )
 
 /**
- * @since 4.0.0
+ * Provides a client-side middleware implementation for a middleware that is required by generated clients.
+ *
+ * The layer captures the surrounding services and makes the middleware available
+ * through the `ForClient` service marker used by HTTP API clients.
+ *
  * @category client
+ * @since 4.0.0
  */
 export const layerClient = <Id extends AnyId, S, R, EX = never, RX = never>(
   tag: Context.Key<Id, S>,

package/src/unstable/httpapi/HttpApiScalar.ts

@@ -1,4 +1,23 @@
 /**
+ * The `HttpApiScalar` module mounts an interactive Scalar API reference for a
+ * declarative `HttpApi`.
+ *
+ * Use this module when you want a browser-friendly documentation page for an
+ * `HttpApi` without maintaining a separate OpenAPI document. The `layer`
+ * helper registers a `GET` route on an `HttpRouter`, generates the OpenAPI
+ * specification with `OpenApi.fromApi`, embeds it into the HTML page, and loads
+ * the bundled Scalar browser script. `layerCdn` provides the same UI while
+ * loading Scalar from jsDelivr, optionally pinned with `version`.
+ *
+ * The mounted path is a documentation UI route, defaulting to `/docs`, rather
+ * than a raw JSON specification endpoint. If clients, gateways, or external
+ * documentation pipelines need the OpenAPI document directly, expose it
+ * separately with `HttpApiBuilder.layer`'s `openapiPath` option. Scalar
+ * configuration is forwarded to the page through `ScalarConfig`; values such as
+ * `proxyUrl`, theme and layout settings, and `baseServerURL` matter when
+ * enabling "Test Request", styling the docs, or rendering relative server URLs
+ * outside the browser origin.
+ *
  * @since 4.0.0
  */
 import * as Effect from "../../Effect.ts"
@@ -12,8 +31,10 @@ import * as internal from "./internal/httpApiScalar.ts"
 import * as OpenApi from "./OpenApi.ts"
 
 /**
+ * Theme preset identifier accepted by the Scalar API reference UI.
+ *
+ * @category models
  * @since 4.0.0
- * @category model
  */
 export type ScalarThemeId =
   | "alternate"
@@ -30,10 +51,12 @@ export type ScalarThemeId =
   | "none"
 
 /**
+ * Configuration passed to the embedded Scalar API reference UI.
+ *
  * @see https://github.com/scalar/scalar/blob/main/documentation/configuration.md
  *
+ * @category models
  * @since 4.0.0
- * @category model
  */
 export type ScalarConfig = {
   /** A string to use one of the color presets */
@@ -165,8 +188,13 @@ const makeHandler = <Id extends string, Groups extends HttpApiGroup.Any>(options
 }
 
 /**
- * @since 4.0.0
+ * Mounts a Scalar API reference page for an `HttpApi` using the bundled Scalar script.
+ *
+ * The route serves the OpenAPI specification generated from the API at the
+ * configured path, defaulting to `/docs`.
+ *
  * @category layers
+ * @since 4.0.0
  */
 export const layer = <Id extends string, Groups extends HttpApiGroup.Any>(
   api: HttpApi.HttpApi<Id, Groups>,
@@ -188,8 +216,14 @@ export const layer = <Id extends string, Groups extends HttpApiGroup.Any>(
   }))
 
 /**
- * @since 4.0.0
+ * Mounts a Scalar API reference page for an `HttpApi` that loads Scalar from jsDelivr.
+ *
+ * The route serves the OpenAPI specification generated from the API at the
+ * configured path, defaulting to `/docs`; `version` selects the Scalar package
+ * version loaded from the CDN.
+ *
  * @category layers
+ * @since 4.0.0
  */
 export const layerCdn = <Id extends string, Groups extends HttpApiGroup.Any>(
   api: HttpApi.HttpApi<Id, Groups>,

package/src/unstable/httpapi/HttpApiSchema.ts

@@ -1,29 +1,40 @@
 /**
- * HttpApiSchema provides helpers to annotate Effect Schema values with HTTP API metadata
- * (status codes and payload/response encodings) used by the HttpApi builder, client,
- * and OpenAPI generation.
- *
- * Mental model:
- * - A "Schema" is the base validation/encoding description from `Schema`.
- * - An "Encoding" tells HttpApi how to serialize/parse a payload or response body.
- * - A "Status" is metadata that chooses the HTTP response status code.
- * - "Empty" schemas represent responses with no body (204/201/202 or custom).
- * - "NoContent" schemas can still decode into a value via {@link asNoContent}.
- * - Multipart is a payload-only encoding for file-like form data.
- *
- * Common tasks:
- * - Set a response status on a schema -> {@link status}
- * - Declare an empty response -> {@link Empty}, {@link NoContent}, {@link Created}, {@link Accepted}
- * - Decode an empty response into a value -> {@link asNoContent}
- * - Force a specific encoding -> {@link asJson}, {@link asFormUrlEncoded}, {@link asText}, {@link asUint8Array}
- * - Mark multipart payloads -> {@link asMultipart}, {@link asMultipartStream}
- *
- * Gotchas:
- * - If you don't set an encoding, HttpApi assumes JSON by default.
- * - {@link asFormUrlEncoded} expects the schema's encoded type to be a record of strings.
- * - {@link asText} expects the encoded type to be `string`, and {@link asUint8Array} expects `Uint8Array`.
- * - Multipart encodings are intended for request payloads; response multipart is not supported.
- * - These helpers annotate schemas; they don't perform validation or IO by themselves.
+ * Helpers for attaching HTTP API metadata to Effect Schema values.
+ *
+ * This module is the schema-side bridge used by the unstable HttpApi endpoint
+ * builder, generated clients, and OpenAPI support. It does not define routes or
+ * perform IO. Instead, helpers such as {@link status}, {@link asJson},
+ * {@link asMultipart}, and {@link asNoContent} annotate schemas so downstream
+ * HTTP tooling can choose response status codes, content types, body codecs, and
+ * no-body handling while the original schema remains usable for validation and
+ * transformation.
+ *
+ * Common use cases:
+ * - Mark success or error schemas with explicit HTTP statuses using
+ *   {@link status}, {@link NoContent}, {@link Created}, {@link Accepted}, or
+ *   {@link Empty}.
+ * - Override the default JSON encoding for request payloads or responses with
+ *   {@link asFormUrlEncoded}, {@link asText}, {@link asUint8Array}, or
+ *   {@link asJson}.
+ * - Describe buffered or streaming multipart request payloads with
+ *   {@link asMultipart} and {@link asMultipartStream}.
+ * - Represent an HTTP response with no body while still decoding a client-side
+ *   value through {@link asNoContent}.
+ *
+ * Status and encoding details:
+ * - {@link status} only stores an annotation. The same annotation is interpreted
+ *   by the surrounding HttpApi context; unannotated success responses default to
+ *   `200`, and unannotated error responses default to `500`.
+ * - Missing encodings default to JSON for bodies and responses. Payload schemas
+ *   used with methods that have no request body fall back to form-url-encoded
+ *   metadata for parameter encoding.
+ * - {@link asFormUrlEncoded} expects the schema's encoded side to be a record
+ *   of strings. {@link asText} expects `string`, and {@link asUint8Array}
+ *   expects `Uint8Array`.
+ * - Multipart encodings are payload-only; response multipart is rejected when
+ *   response encoding is resolved.
+ * - These helpers attach annotations consumed by HttpApi internals. They do not
+ *   validate, encode, decode, or send data by themselves.
  *
  * @since 4.0.0
  */
@@ -175,7 +186,7 @@ export function status(code: number | StatusLiteral) {
  * Creates a void schema with the given HTTP status code.
  * This is used to represent empty responses with a specific status code.
  *
- * @see {@link asEmpty} for creating a no content response that can be decoded into a meaningful value on the client side.
+ * @see {@link NoContent} for the predefined 204 no content schema.
  *
  * @category Empty
  * @since 4.0.0
@@ -183,6 +194,9 @@ export function status(code: number | StatusLiteral) {
 export const Empty = (code: number): Schema.Void => Schema.Void.pipe(status(code))
 
 /**
+ * Type of the `NoContent` schema, a void schema annotated with HTTP status code 204.
+ *
+ * @category models
  * @since 4.0.0
  */
 export interface NoContent extends Schema.Void {}
@@ -191,12 +205,15 @@ export interface NoContent extends Schema.Void {}
  * A void schema with the HTTP status code 204.
  * This is used to represent empty responses with the status code 204.
  *
- * @since 4.0.0
  * @category Empty
+ * @since 4.0.0
  */
 export const NoContent: NoContent = Empty(204)
 
 /**
+ * Type of the `Created` schema, a void schema annotated with HTTP status code 201.
+ *
+ * @category models
  * @since 4.0.0
  */
 export interface Created extends Schema.Void {}
@@ -211,6 +228,9 @@ export interface Created extends Schema.Void {}
 export const Created: Created = Empty(201)
 
 /**
+ * Type of the `Accepted` schema, a void schema annotated with HTTP status code 202.
+ *
+ * @category models
  * @since 4.0.0
  */
 export interface Accepted extends Schema.Void {}
@@ -225,19 +245,23 @@ export interface Accepted extends Schema.Void {}
 export const Accepted: Accepted = Empty(202)
 
 /**
+ * Schema type returned by `asNoContent`, encoding as `void` while decoding to the original schema type.
+ *
+ * @category schemas
  * @since 4.0.0
  */
 export interface asNoContent<S extends Schema.Top> extends Schema.decodeTo<Schema.toType<S>, Schema.Void> {}
 
 /**
- * Marks a schema as a no content response.
+ * Marks a schema as a no-content response while preserving a decoded client value.
  *
- * The `decode` function is used to decode the response body on the client side into a meaningful value.
+ * The server encodes the response as `void`; generated clients call `decode` to
+ * produce the schema's decoded value when the response has no body.
  *
  * @see {@link NoContent} for a void schema with the status code 204.
  * @see {@link Empty} for creating a void schema with a specific status code.
  *
- * @category Encoding
+ * @category encoding
  * @since 4.0.0
  */
 export function asNoContent<S extends Schema.Top>(options: {
@@ -257,16 +281,25 @@ export function asNoContent<S extends Schema.Top>(options: {
 }
 
 /**
+ * Runtime brand key used to mark schemas as buffered multipart payloads.
+ *
+ * @category type IDs
  * @since 4.0.0
  */
 export const MultipartTypeId = "~effect/httpapi/HttpApiSchema/Multipart"
 
 /**
+ * Type-level brand identifier used by `asMultipart`.
+ *
+ * @category type IDs
  * @since 4.0.0
  */
 export type MultipartTypeId = typeof MultipartTypeId
 
 /**
+ * Schema type returned by `asMultipart` for buffered multipart payloads.
+ *
+ * @category schemas
  * @since 4.0.0
  */
 export interface asMultipart<S extends Schema.Top> extends Schema.brand<S["Rebuild"], MultipartTypeId> {}
@@ -276,7 +309,7 @@ export interface asMultipart<S extends Schema.Top> extends Schema.brand<S["Rebui
  *
  * @see {@link asMultipartStream} for a multipart stream payload.
  *
- * @category Encoding
+ * @category encoding
  * @since 4.0.0
  */
 export function asMultipart(options?: Multipart_.withLimits.Options) {
@@ -292,16 +325,25 @@ export function asMultipart(options?: Multipart_.withLimits.Options) {
 }
 
 /**
+ * Runtime brand key used to mark schemas as streaming multipart payloads.
+ *
+ * @category type IDs
  * @since 4.0.0
  */
 export const MultipartStreamTypeId = "~effect/httpapi/HttpApiSchema/MultipartStream"
 
 /**
+ * Type-level brand identifier used by `asMultipartStream`.
+ *
+ * @category type IDs
  * @since 4.0.0
  */
 export type MultipartStreamTypeId = typeof MultipartStreamTypeId
 
 /**
+ * Schema type returned by `asMultipartStream` for streaming multipart payloads.
+ *
+ * @category schemas
  * @since 4.0.0
  */
 export interface asMultipartStream<S extends Schema.Top> extends Schema.brand<S["Rebuild"], MultipartStreamTypeId> {}
@@ -311,7 +353,7 @@ export interface asMultipartStream<S extends Schema.Top> extends Schema.brand<S[
  *
  * @see {@link asMultipart} for a buffered multipart payload.
  *
- * @category Encoding
+ * @category encoding
  * @since 4.0.0
  */
 export function asMultipartStream(options?: Multipart_.withLimits.Options) {
@@ -356,7 +398,7 @@ function defaultContentType(_tag: Encoding["_tag"]): string {
 /**
  * Marks a schema as a JSON payload / response.
  *
- * @category Encoding
+ * @category encoding
  * @since 4.0.0
  */
 export function asJson(options?: {
@@ -366,11 +408,11 @@ export function asJson(options?: {
 }
 
 /**
- * Marks a schema as a URL params payload / response.
+ * Marks a schema as an `application/x-www-form-urlencoded` payload or response.
  *
- * The schema encoded side must be a record of strings.
+ * The schema's encoded side must be a record of strings.
  *
- * @category Encoding
+ * @category encoding
  * @since 4.0.0
  */
 export function asFormUrlEncoded(options?: {
@@ -386,7 +428,7 @@ export function asFormUrlEncoded(options?: {
  *
  * The schema encoded side must be a string.
  *
- * @category Encoding
+ * @category encoding
  * @since 4.0.0
  */
 export function asText(options?: {
@@ -401,7 +443,7 @@ export function asText(options?: {
  *
  * The schema encoded side must be a `Uint8Array`.
  *
- * @category Encoding
+ * @category encoding
  * @since 4.0.0
  */
 export function asUint8Array(options?: {
@@ -411,6 +453,12 @@ export function asUint8Array(options?: {
     asNonMultipartEncoding(self, { _tag: "Uint8Array", ...options })
 }
 /**
+ * Returns `true` when a schema AST represents a no-content response.
+ *
+ * The check succeeds for direct `void` schemas and schemas whose encoded or
+ * transformation target is `void`.
+ *
+ * @category predicates
  * @since 4.0.0
  */
 export const isNoContent = (ast: AST.AST): boolean => {