effect 4.0.0-beta.70 → 4.0.0-beta.72

package/src/unstable/httpapi/HttpApiSchema.ts

@@ -1,40 +1,43 @@
 /**
- * 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.
+ * Attaches HTTP API metadata to Effect Schema values.
+ *
+ * This module is the schema-side bridge for HttpApi endpoint builders,
+ * generated clients, and OpenAPI support. It does not define routes or perform
+ * IO. Instead, the helpers annotate schemas so the surrounding HTTP API tooling
+ * can choose response status codes, content types, body codecs, multipart
+ * handling, and no-body response behavior.
+ *
+ * **Mental model**
+ *
+ * Keep the `Schema` as the source of validation and transformation, then add
+ * HTTP-specific annotations with helpers such as {@link status}, {@link asJson},
+ * {@link asMultipart}, and {@link asNoContent}. The same annotated schema can be
+ * read later by server builders, clients, and OpenAPI generation.
+ *
+ * **Common tasks**
+ *
+ * Use {@link status}, {@link NoContent}, {@link Created}, {@link Accepted}, or
+ * {@link Empty} to describe response statuses. Use {@link asFormUrlEncoded},
+ * {@link asText}, {@link asUint8Array}, or {@link asJson} to override the
+ * default JSON encoding. Use {@link asMultipart} or
+ * {@link asMultipartStream} for multipart request payloads. Use
+ * {@link asNoContent} when the wire response has no body but the client should
+ * decode a useful value.
+ *
+ * **Gotchas**
+ *
+ * {@link status} only stores an annotation: unannotated success responses
+ * default to `200`, and unannotated error responses default to `500` when the
+ * surrounding HttpApi context interprets them. Missing body and response
+ * encodings default to JSON, while payload schemas for methods without request
+ * bodies fall back to form-url-encoded metadata. Multipart encodings are
+ * payload-only, and response multipart is rejected when response encoding is
+ * resolved.
+ *
+ * **See also**
+ *
+ * `HttpApiEndpoint` for route contracts that consume these annotations and
+ * `HttpApi` for reflection over status and encoding metadata.
  *
  * @since 4.0.0
  */
@@ -163,7 +166,7 @@ const statusCodeByLiteral = {
 export type StatusLiteral = keyof typeof statusCodeByLiteral
 
 /**
- * A convenience function to set the HTTP status code of a schema.
+ * Sets the HTTP status code of a schema.
  *
  * **Details**
  *
@@ -203,8 +206,7 @@ export const Empty = (code: number): Schema.Void => Schema.Void.pipe(status(code
 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.
+ * Schema for empty HTTP responses with status code 204.
  *
  * @category Empty
  * @since 4.0.0
@@ -220,8 +222,7 @@ export const NoContent: NoContent = Empty(204)
 export interface Created extends Schema.Void {}
 
 /**
- * A void schema with the HTTP status code 201.
- * This is used to represent empty responses with the status code 201.
+ * Schema for empty HTTP responses with status code 201.
  *
  * @category Empty
  * @since 4.0.0
@@ -237,8 +238,7 @@ export const Created: Created = Empty(201)
 export interface Accepted extends Schema.Void {}
 
 /**
- * A void schema with the HTTP status code 202.
- * This is used to represent empty responses with the status code 202.
+ * Schema for empty HTTP responses with status code 202.
  *
  * @category Empty
  * @since 4.0.0

package/src/unstable/httpapi/HttpApiSecurity.ts

@@ -1,28 +1,40 @@
 /**
- * The `HttpApiSecurity` module defines the security scheme values used by
- * declarative HTTP APIs.
- *
- * Use these constructors when an API group or endpoint needs authentication
- * middleware for bearer tokens, API keys, or HTTP Basic credentials. The values
- * are intentionally small declarations: `HttpApiMiddleware.Service` attaches
- * them to middleware, `HttpApiBuilder` decodes the matching credential shape from
- * each request, and OpenAPI generation emits the corresponding
- * `components.securitySchemes` and operation security requirements.
- *
- * Common uses include modeling `Authorization: Bearer ...` tokens, Basic
- * username/password credentials, and API keys passed through headers, query
- * parameters, or cookies. Bearer tokens and API-key values are exposed to
- * middleware as `Redacted` values; Basic credentials expose the username with a
- * redacted password. Cookie API keys can also be written to responses with
- * `HttpApiBuilder.securitySetCookie`.
- *
- * A security scheme does not authenticate by itself: middleware must reject empty
- * or invalid credentials. Bearer and Basic schemes read the `Authorization`
- * header, while API-key headers use HTTP header name normalization and API-key
- * query or cookie names are matched exactly. OpenAPI annotations such as
- * descriptions and bearer formats affect generated documentation only; they do
+ * Defines security scheme declarations for declarative HTTP APIs.
+ *
+ * Security schemes describe where credentials are read from and which credential
+ * type is passed to security middleware. They are consumed by
+ * `HttpApiMiddleware.Service`, `HttpApiBuilder`, generated clients, and OpenAPI
+ * generation, but they do not authenticate requests by themselves.
+ *
+ * **Mental model**
+ *
+ * Create a scheme with {@link bearer}, {@link apiKey}, or {@link basic}, attach
+ * it to middleware, and let the HTTP API builder decode the matching credential
+ * shape from each request. OpenAPI generation emits the same declaration as
+ * `components.securitySchemes` plus operation security requirements.
+ *
+ * **Common tasks**
+ *
+ * Use {@link bearer} for `Authorization: Bearer ...` tokens, {@link basic} for
+ * HTTP Basic username/password credentials, and {@link apiKey} for keys passed
+ * through headers, query parameters, or cookies. Use {@link annotate} or
+ * {@link annotateMerge} to add documentation metadata for generated OpenAPI
+ * descriptions.
+ *
+ * **Gotchas**
+ *
+ * Middleware must reject empty or invalid credentials. Bearer tokens and API-key
+ * values are delivered as `Redacted` values; Basic credentials expose the
+ * username and redact the password. Bearer and Basic schemes read the
+ * `Authorization` header, API-key headers use HTTP header name normalization,
+ * and API-key query or cookie names are matched exactly. OpenAPI annotations do
  * not change runtime decoding.
  *
+ * **See also**
+ *
+ * `HttpApiMiddleware` for implementing security checks and `HttpApiBuilder` for
+ * installing middleware and setting API-key cookies on responses.
+ *
  * @since 4.0.0
  */
 import * as Context from "../../Context.ts"
@@ -124,9 +136,16 @@ const Proto = {
  *
  * **When to use**
  *
+ * Use to require `Authorization: Bearer ...` credentials for an HTTP API group
+ * or endpoint.
+ *
+ * **Details**
+ *
  * Use `HttpApiBuilder.middlewareSecurity` to implement API middleware for this
  * security scheme.
  *
+ * @see {@link apiKey} for an API-key security scheme
+ * @see {@link basic} for an HTTP Basic security scheme
  * @category constructors
  * @since 4.0.0
  */
@@ -140,14 +159,19 @@ export const bearer: Bearer = Object.assign(Object.create(Proto), {
  *
  * **When to use**
  *
- * Use `HttpApiBuilder.middlewareSecurity` to implement API middleware for this
- * security scheme.
+ * Use to require API key credentials passed through a header, query parameter,
+ * or cookie.
  *
  * **Details**
  *
+ * Use `HttpApiBuilder.middlewareSecurity` to implement API middleware for this
+ * security scheme.
+ *
  * Use `HttpApiBuilder.securitySetCookie` to set the correct cookie in a
  * handler. By default, `in` is `"header"`.
  *
+ * @see {@link bearer} for a Bearer token security scheme
+ * @see {@link basic} for an HTTP Basic security scheme
  * @category constructors
  * @since 4.0.0
  */
@@ -167,9 +191,15 @@ export const apiKey = (options: {
  *
  * **When to use**
  *
+ * Use to require HTTP Basic username/password credentials.
+ *
+ * **Details**
+ *
  * Use `HttpApiBuilder.middlewareSecurity` to implement API middleware for this
  * security scheme.
  *
+ * @see {@link bearer} for a Bearer token security scheme
+ * @see {@link apiKey} for an API-key security scheme
  * @category constructors
  * @since 4.0.0
  */

package/src/unstable/httpapi/HttpApiSwagger.ts

@@ -1,22 +1,34 @@
 /**
- * Serves Swagger UI for an `HttpApi` by rendering the OpenAPI document generated
- * from the API directly into an HTML page.
+ * Swagger documentation UI for declarative `HttpApi` contracts.
  *
- * Use this module when you want a lightweight documentation route for a running
- * `HttpApi`, typically in development, staging, internal consoles, or public API
- * reference pages where Swagger UI's exploration and request-building tools are
- * preferred. The exported `layer` adds a `GET` route to an `HttpRouter`,
- * defaults the mount path to `/docs`, and leaves API implementation and server
- * wiring to `HttpApiBuilder` and the surrounding router layers.
+ * This module mounts a browser-based Swagger UI route on an `HttpRouter`. The
+ * page renders the OpenAPI document derived from the supplied `HttpApi`, so a
+ * running application can expose interactive API documentation without writing a
+ * separate OpenAPI file.
  *
- * The page is self-contained: `OpenApi.fromApi` derives the specification from
- * the API's groups, endpoints, schemas, and OpenAPI annotations, then the JSON
- * is embedded into the HTML served to the browser. No separate `/openapi.json`
- * endpoint is installed by this module, so clients or documentation pipelines
- * that need the raw spec should use `OpenApi.fromApi` directly or expose a JSON
- * route elsewhere. If the docs are public, mount the layer behind the same
- * routing, security, or environment controls you want for the UI; generated
- * server URLs and operation metadata come from the API's OpenAPI annotations.
+ * **Mental model**
+ *
+ * {@link layer} registers one `GET` route, defaulting to `/docs`. When that
+ * route is requested, the module derives the OpenAPI document with
+ * `OpenApi.fromApi`, embeds it into an HTML page, and boots the bundled Swagger
+ * UI script in the browser. API implementation, middleware, and server wiring
+ * stay with the surrounding `HttpApi` and router layers.
+ *
+ * **Common tasks**
+ *
+ * - Use {@link layer} to mount Swagger UI for an `HttpApi`
+ * - Set `path` when the documentation route should be mounted somewhere other
+ *   than `/docs`
+ * - Add OpenAPI annotations to the API definition so the generated UI has the
+ *   desired titles, descriptions, servers, security schemes, and operation
+ *   metadata
+ *
+ * **Gotchas**
+ *
+ * The mounted route serves HTML, not a raw OpenAPI JSON endpoint. Clients,
+ * gateways, and documentation pipelines that need the specification directly
+ * should derive it separately with `OpenApi.fromApi` or expose a JSON route from
+ * the surrounding API server.
  *
  * @since 4.0.0
  */

package/src/unstable/httpapi/HttpApiTest.ts

@@ -48,7 +48,7 @@ import type * as HttpApiGroup from "./HttpApiGroup.ts"
  * Handlers for the selected groups are taken from the environment; unselected
  * groups are wired with placeholder handlers that fail if called.
  *
- * @category Testing
+ * @category testing
  * @since 4.0.0
  */
 export const groups = Effect.fnUntraced(function*<

package/src/unstable/httpapi/OpenApi.ts

@@ -1,32 +1,44 @@
 /**
- * The `OpenApi` module converts declarative `HttpApi` definitions into
- * OpenAPI 3.1 specifications and provides annotations for shaping the
- * generated document.
+ * OpenAPI 3.1 generation for declarative `HttpApi` contracts.
  *
- * Use this module when you need to publish an `HttpApi` contract to tooling
- * such as Swagger UI, Scalar, client generators, API gateways, or documentation
- * pipelines. `fromApi` reflects the API's groups and endpoints into tags,
+ * This module reflects an `HttpApi` into an OpenAPI document and provides the
+ * annotations used to shape the generated output. The result can be served from
+ * `HttpApiBuilder.layer`, rendered by Swagger UI or Scalar, passed to client
+ * generators, or published through API gateway and documentation pipelines.
+ *
+ * **Mental model**
+ *
+ * {@link fromApi} walks the API's groups and endpoints and emits OpenAPI tags,
  * paths, operations, parameters, request bodies, responses, security schemes,
- * and component schemas while preserving Effect Schema metadata where OpenAPI
- * can represent it.
+ * and component schemas. Endpoint and schema metadata determine the HTTP
+ * surface; annotations such as {@link Title}, {@link Description},
+ * {@link Summary}, {@link Version}, {@link Servers}, {@link License},
+ * {@link ExternalDocs}, {@link Identifier}, {@link Deprecated}, and
+ * {@link Format} fill in OpenAPI-specific fields.
+ *
+ * **Common tasks**
+ *
+ * Use {@link fromApi} to generate the complete specification. Use
+ * {@link annotations} to attach several OpenAPI annotations at once. Use
+ * {@link Exclude} to omit a group or endpoint, {@link Override} to shallowly
+ * merge extra fields into a generated object, and {@link Transform} when the
+ * generated API, tag, or operation needs a programmatic rewrite.
  *
- * The generated specification is driven by annotations on APIs, groups,
- * endpoints, security definitions, and schemas. `Title`, `Description`,
- * `Summary`, `Version`, `Servers`, `License`, `ExternalDocs`, `Identifier`,
- * `Deprecated`, and `Format` feed the corresponding OpenAPI fields; `Exclude`
- * omits a group or endpoint; `Override` shallowly merges custom fields; and
- * `Transform` can rewrite the generated API, tag, or operation object. Schema
- * identifiers are important for stable component names, additional schemas must
- * have identifiers, and invalid OpenAPI component keys are rejected during
- * generation.
+ * **Gotchas**
  *
- * A few generation details are worth keeping in mind: `HttpApiSchema`
- * encodings choose media types and special representations for JSON,
- * form-url-encoded, text, binary, and multipart payloads; no-content schemas
- * emit responses without bodies; request and response unions are grouped by
- * status code and content type; path parameters are rendered from `:id` route
- * segments as `{id}`; and schemas are converted through the OpenAPI 3.1 JSON
- * Schema representation before being patched into the final document.
+ * Schema identifiers are used as component names; additional schemas must have
+ * identifiers, and invalid OpenAPI component keys are rejected during
+ * generation. `HttpApiSchema` encodings choose media types for JSON,
+ * form-url-encoded, text, binary, and multipart payloads. No-content schemas
+ * emit responses without bodies, request and response unions are grouped by
+ * status code and content type, and `:id` route segments are rendered as `{id}`
+ * path parameters.
+ *
+ * **See also**
+ *
+ * `HttpApi` for API composition, `HttpApiEndpoint` for endpoint metadata,
+ * `HttpApiSchema` for HTTP status and encoding annotations, and
+ * `HttpApiBuilder` for serving the generated document with an HTTP router.
  *
  * @since 4.0.0
  */
@@ -142,7 +154,13 @@ export class Deprecated extends Context.Service<Deprecated, boolean>()("effect/h
 export class Override extends Context.Service<Override, Record<string, unknown>>()("effect/httpapi/OpenApi/Override") {}
 
 /**
- * OpenAPI annotation reference that excludes an annotated group or endpoint from the generated specification.
+ * Annotation that excludes an annotated group or endpoint from the generated
+ * OpenAPI specification.
+ *
+ * **When to use**
+ *
+ * Use to hide internal, experimental, or otherwise undocumented HTTP API groups
+ * and endpoints from generated OpenAPI output.
  *
  * @category annotations
  * @since 4.0.0