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

package/src/unstable/httpapi/HttpApiSecurity.ts

@@ -1,4 +1,28 @@
 /**
+ * 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
+ * not change runtime decoding.
+ *
  * @since 4.0.0
  */
 import * as Context from "../../Context.ts"
@@ -10,19 +34,24 @@ import type { Covariant } from "../../Types.ts"
 const TypeId = "~effect/httpapi/HttpApiSecurity"
 
 /**
- * @since 4.0.0
+ * Union of security schemes supported by the HTTP API OpenAPI model.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type HttpApiSecurity = Bearer | ApiKey | Basic
 
 /**
+ * Helper types for HTTP API security schemes.
+ *
  * @since 4.0.0
- * @category models
  */
 export declare namespace HttpApiSecurity {
   /**
-   * @since 4.0.0
+   * Common prototype for security schemes, carrying the credential type and OpenAPI annotations.
+   *
    * @category models
+   * @since 4.0.0
    */
   export interface Proto<out A> extends Pipeable {
     readonly [TypeId]: {
@@ -32,23 +61,29 @@ export declare namespace HttpApiSecurity {
   }
 
   /**
-   * @since 4.0.0
+   * Extracts the credential type produced by a security scheme.
+   *
    * @category models
+   * @since 4.0.0
    */
   export type Type<A extends HttpApiSecurity> = A extends Proto<infer Out> ? Out : never
 }
 
 /**
- * @since 4.0.0
+ * Bearer token security scheme whose decoded credential is a redacted token.
+ *
  * @category models
+ * @since 4.0.0
  */
 export interface Bearer extends HttpApiSecurity.Proto<Redacted> {
   readonly _tag: "Bearer"
 }
 
 /**
- * @since 4.0.0
+ * API key security scheme identifying the key name and whether it is read from a header, query parameter, or cookie.
+ *
  * @category models
+ * @since 4.0.0
  */
 export interface ApiKey extends HttpApiSecurity.Proto<Redacted> {
   readonly _tag: "ApiKey"
@@ -57,16 +92,20 @@ export interface ApiKey extends HttpApiSecurity.Proto<Redacted> {
 }
 
 /**
- * @since 4.0.0
+ * HTTP Basic authentication security scheme whose decoded credential is `Credentials`.
+ *
  * @category models
+ * @since 4.0.0
  */
 export interface Basic extends HttpApiSecurity.Proto<Credentials> {
   readonly _tag: "Basic"
 }
 
 /**
- * @since 4.0.0
+ * Decoded credentials for HTTP Basic authentication.
+ *
  * @category models
+ * @since 4.0.0
  */
 export interface Credentials {
   readonly username: string
@@ -86,8 +125,8 @@ const Proto = {
  * You can implement some api middleware for this security scheme using
  * `HttpApiBuilder.middlewareSecurity`.
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const bearer: Bearer = Object.assign(Object.create(Proto), {
   _tag: "Bearer",
@@ -105,8 +144,8 @@ export const bearer: Bearer = Object.assign(Object.create(Proto), {
  *
  * The default value for `in` is "header".
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const apiKey = (options: {
   readonly key: string
@@ -120,8 +159,13 @@ export const apiKey = (options: {
   })
 
 /**
- * @since 4.0.0
+ * Creates an HTTP Basic authentication security scheme.
+ *
+ * You can implement API middleware for this security scheme with
+ * `HttpApiBuilder.middlewareSecurity`.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const basic: Basic = Object.assign(Object.create(Proto), {
   _tag: "Basic",
@@ -129,18 +173,24 @@ export const basic: Basic = Object.assign(Object.create(Proto), {
 })
 
 /**
- * @since 4.0.0
+ * Merges OpenAPI annotations into a security scheme.
+ *
  * @category annotations
+ * @since 4.0.0
  */
 export const annotateMerge: {
   /**
-   * @since 4.0.0
+   * Merges OpenAPI annotations into a security scheme.
+   *
    * @category annotations
+   * @since 4.0.0
    */
   <I>(annotations: Context.Context<I>): <A extends HttpApiSecurity>(self: A) => A
   /**
-   * @since 4.0.0
+   * Merges OpenAPI annotations into a security scheme.
+   *
    * @category annotations
+   * @since 4.0.0
    */
   <A extends HttpApiSecurity, I>(self: A, annotations: Context.Context<I>): A
 } = dual(
@@ -153,18 +203,24 @@ export const annotateMerge: {
 )
 
 /**
- * @since 4.0.0
+ * Adds an OpenAPI annotation value to a security scheme.
+ *
  * @category annotations
+ * @since 4.0.0
  */
 export const annotate: {
   /**
-   * @since 4.0.0
+   * Adds an OpenAPI annotation value to a security scheme.
+   *
    * @category annotations
+   * @since 4.0.0
    */
   <I, S>(service: Context.Key<I, S>, value: S): <A extends HttpApiSecurity>(self: A) => A
   /**
-   * @since 4.0.0
+   * Adds an OpenAPI annotation value to a security scheme.
+   *
    * @category annotations
+   * @since 4.0.0
    */
   <A extends HttpApiSecurity, I, S>(self: A, service: Context.Key<I, S>, value: S): A
 } = dual(

package/src/unstable/httpapi/HttpApiSwagger.ts

@@ -1,4 +1,23 @@
 /**
+ * Serves Swagger UI for an `HttpApi` by rendering the OpenAPI document generated
+ * from the API directly into an HTML page.
+ *
+ * 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.
+ *
+ * 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.
+ *
  * @since 4.0.0
  */
 import * as Effect from "../../Effect.ts"
@@ -43,12 +62,13 @@ const makeHandler = <Id extends string, Groups extends HttpApiGroup.Any>(options
 }
 
 /**
- * Exported layer mounting Swagger/OpenAPI documentation UI.
+ * Mounts Swagger UI for an `HttpApi`.
  *
- * @param options.path Optional mount path (default "/docs").
+ * The route serves the OpenAPI specification generated from the API at the
+ * configured path, defaulting to `/docs`.
  *
- * @since 4.0.0
  * @category layers
+ * @since 4.0.0
  */
 export const layer = <Id extends string, Groups extends HttpApiGroup.Any>(
   api: HttpApi.HttpApi<Id, Groups>,

package/src/unstable/httpapi/HttpApiTest.ts

@@ -1,4 +1,24 @@
 /**
+ * The `HttpApiTest` module provides helpers for testing `HttpApi`
+ * implementations through the generated client interface without starting an
+ * HTTP server.
+ *
+ * Use this module when a test should exercise one or more implemented API
+ * groups with the same request encoding, routing, response encoding, and client
+ * decoding used by the production `HttpApiBuilder` and `HttpApiClient`
+ * pipeline. This is useful for focused handler tests, schema round-trip checks,
+ * middleware behavior, and tests that want to call an API through its typed
+ * client while keeping all traffic in memory.
+ *
+ * The selected groups must be provided in the test environment, usually by
+ * supplying the corresponding `HttpApiBuilder.group` layers. Groups that are not
+ * selected are still present on the returned client shape, but their handlers
+ * are placeholders that die if called, which helps catch accidental calls outside
+ * the test scope. The generated client is still a real `HttpApiClient`, so
+ * endpoint middleware, client middleware, platform services, and the optional
+ * `baseUrl` used for URL construction follow the same rules as normal clients;
+ * only the HTTP transport is replaced with an in-memory router dispatch.
+ *
  * @since 4.0.0
  */
 import * as Context from "../../Context.ts"
@@ -21,8 +41,13 @@ import type * as HttpApiEndpoint from "./HttpApiEndpoint.ts"
 import type * as HttpApiGroup from "./HttpApiGroup.ts"
 
 /**
- * @since 4.0.0
+ * Creates an in-memory client for testing selected groups of an `HttpApi`.
+ *
+ * Handlers for the selected groups are taken from the environment; unselected
+ * groups are wired with placeholder handlers that fail if called.
+ *
  * @category Testing
+ * @since 4.0.0
  */
 export const groups = Effect.fnUntraced(function*<
   ApiId extends string,

package/src/unstable/httpapi/OpenApi.ts

@@ -1,4 +1,33 @@
 /**
+ * The `OpenApi` module converts declarative `HttpApi` definitions into
+ * OpenAPI 3.1 specifications and provides annotations for shaping the
+ * generated document.
+ *
+ * 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,
+ * paths, operations, parameters, request bodies, responses, security schemes,
+ * and component schemas while preserving Effect Schema metadata where OpenAPI
+ * can represent it.
+ *
+ * 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.
+ *
+ * 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.
+ *
  * @since 4.0.0
  */
 import * as Arr from "../../Array.ts"
@@ -21,88 +50,115 @@ import * as HttpApiSchema from "./HttpApiSchema.ts"
 import type { HttpApiSecurity } from "./HttpApiSecurity.ts"
 
 /**
- * @since 4.0.0
+ * OpenAPI annotation for overriding generated identifiers, including operation ids.
+ *
  * @category annotations
+ * @since 4.0.0
  */
 export class Identifier extends Context.Service<Identifier, string>()("effect/httpapi/OpenApi/Identifier") {}
 
 /**
- * @since 4.0.0
+ * OpenAPI annotation for setting the API title or group tag name.
+ *
  * @category annotations
+ * @since 4.0.0
  */
 export class Title extends Context.Service<Title, string>()("effect/httpapi/OpenApi/Title") {}
 
 /**
- * @since 4.0.0
+ * OpenAPI annotation for setting the generated API version.
+ *
  * @category annotations
+ * @since 4.0.0
  */
 export class Version extends Context.Service<Version, string>()("effect/httpapi/OpenApi/Version") {}
 
 /**
- * @since 4.0.0
+ * OpenAPI annotation for setting generated descriptions on APIs, groups, endpoints, or security schemes.
+ *
  * @category annotations
+ * @since 4.0.0
  */
 export class Description extends Context.Service<Description, string>()("effect/httpapi/OpenApi/Description") {}
 
 /**
- * @since 4.0.0
+ * OpenAPI annotation for setting the generated API license metadata.
+ *
  * @category annotations
+ * @since 4.0.0
  */
 export class License extends Context.Service<License, OpenAPISpecLicense>()("effect/httpapi/OpenApi/License") {}
 
 /**
- * @since 4.0.0
+ * OpenAPI annotation for adding external documentation metadata to groups or endpoints.
+ *
  * @category annotations
+ * @since 4.0.0
  */
 export class ExternalDocs
   extends Context.Service<ExternalDocs, OpenAPISpecExternalDocs>()("effect/httpapi/OpenApi/ExternalDocs")
 {}
 
 /**
- * @since 4.0.0
+ * OpenAPI annotation for setting the generated API server list.
+ *
  * @category annotations
+ * @since 4.0.0
  */
 export class Servers
   extends Context.Service<Servers, ReadonlyArray<OpenAPISpecServer>>()("effect/httpapi/OpenApi/Servers")
 {}
 
 /**
- * @since 4.0.0
+ * OpenAPI annotation for setting the format metadata, such as a bearer token format on security schemes.
+ *
  * @category annotations
+ * @since 4.0.0
  */
 export class Format extends Context.Service<Format, string>()("effect/httpapi/OpenApi/Format") {}
 
 /**
- * @since 4.0.0
+ * OpenAPI annotation for setting generated summary text.
+ *
  * @category annotations
+ * @since 4.0.0
  */
 export class Summary extends Context.Service<Summary, string>()("effect/httpapi/OpenApi/Summary") {}
 
 /**
- * @since 4.0.0
+ * OpenAPI annotation for marking a generated endpoint operation as deprecated.
+ *
  * @category annotations
+ * @since 4.0.0
  */
 export class Deprecated extends Context.Service<Deprecated, boolean>()("effect/httpapi/OpenApi/Deprecated") {}
 
 /**
- * @since 4.0.0
+ * OpenAPI annotation for shallowly merging additional fields into a generated OpenAPI object.
+ *
  * @category annotations
+ * @since 4.0.0
  */
 export class Override extends Context.Service<Override, Record<string, unknown>>()("effect/httpapi/OpenApi/Override") {}
 
 /**
- * @since 4.0.0
+ * OpenAPI annotation reference that excludes an annotated group or endpoint from the generated specification.
+ *
  * @category annotations
+ * @since 4.0.0
  */
 export const Exclude = Context.Reference<boolean>("effect/httpapi/OpenApi/Exclude", {
   defaultValue: constFalse
 })
 
 /**
- * Transforms the generated OpenAPI specification
+ * OpenAPI annotation for transforming a generated OpenAPI object.
+ *
+ * The function is applied during generation to the annotated API, group tag, or
+ * endpoint operation.
  *
- * @since 4.0.0
  * @category annotations
+ * @since 4.0.0
  */
 export class Transform extends Context.Service<
   Transform,
@@ -129,8 +185,10 @@ const servicesPartial = <Tags extends Record<string, Context.Key<any, any> | Con
 }
 
 /**
- * @since 4.0.0
+ * Builds a `Context` containing OpenAPI annotations from the supplied options.
+ *
  * @category annotations
+ * @since 4.0.0
  */
 export const annotations: (
   options: {
@@ -694,6 +752,8 @@ export interface OpenAPISpec {
 }
 
 /**
+ * OpenAPI `info` object generated by `fromApi`.
+ *
  * @category models
  * @since 4.0.0
  */
@@ -706,6 +766,8 @@ export interface OpenAPISpecInfo {
 }
 
 /**
+ * OpenAPI tag object generated for an HTTP API group.
+ *
  * @category models
  * @since 4.0.0
  */
@@ -716,6 +778,8 @@ export interface OpenAPISpecTag {
 }
 
 /**
+ * OpenAPI external documentation metadata.
+ *
  * @category models
  * @since 4.0.0
  */
@@ -725,6 +789,8 @@ export interface OpenAPISpecExternalDocs {
 }
 
 /**
+ * OpenAPI license metadata used in the generated `info` object.
+ *
  * @category models
  * @since 4.0.0
  */
@@ -735,6 +801,8 @@ export interface OpenAPISpecLicense {
 }
 
 /**
+ * OpenAPI server object used in the generated `servers` array.
+ *
  * @category models
  * @since 4.0.0
  */
@@ -745,6 +813,8 @@ export interface OpenAPISpecServer {
 }
 
 /**
+ * OpenAPI variable definition for templated server URLs.
+ *
  * @category models
  * @since 4.0.0
  */
@@ -755,12 +825,16 @@ export interface OpenAPISpecServerVariable {
 }
 
 /**
+ * Generated OpenAPI `paths` object, keyed by route path.
+ *
  * @category models
  * @since 4.0.0
  */
 export type OpenAPISpecPaths = Record<string, OpenAPISpecPathItem>
 
 /**
+ * Lowercase HTTP method names used as keys in generated OpenAPI path items.
+ *
  * @category models
  * @since 4.0.0
  */
@@ -775,6 +849,8 @@ export type OpenAPISpecMethodName =
   | "trace"
 
 /**
+ * Generated OpenAPI path item mapping HTTP methods to operations for a single route path.
+ *
  * @category models
  * @since 4.0.0
  */
@@ -783,6 +859,8 @@ export type OpenAPISpecPathItem = {
 }
 
 /**
+ * Generated OpenAPI parameter object for path, query, header, or cookie parameters.
+ *
  * @category models
  * @since 4.0.0
  */
@@ -795,12 +873,16 @@ export interface OpenAPISpecParameter {
 }
 
 /**
+ * Generated OpenAPI responses object, keyed by HTTP status code.
+ *
  * @category models
  * @since 4.0.0
  */
 export type OpenAPISpecResponses = Record<number, OpenApiSpecResponse>
 
 /**
+ * Generated OpenAPI content object, keyed by media type.
+ *
  * @category models
  * @since 4.0.0
  */
@@ -809,6 +891,8 @@ export type OpenApiSpecContent = {
 }
 
 /**
+ * Generated OpenAPI response object for an endpoint success or error schema.
+ *
  * @category models
  * @since 4.0.0
  */
@@ -818,6 +902,8 @@ export interface OpenApiSpecResponse {
 }
 
 /**
+ * Generated OpenAPI media type object containing the JSON Schema for a request or response body.
+ *
  * @category models
  * @since 4.0.0
  */
@@ -826,6 +912,8 @@ export interface OpenApiSpecMediaType {
 }
 
 /**
+ * Generated OpenAPI request body object for endpoint payloads.
+ *
  * @category models
  * @since 4.0.0
  */
@@ -835,6 +923,8 @@ export interface OpenAPISpecRequestBody {
 }
 
 /**
+ * Generated OpenAPI components containing shared schemas and security schemes.
+ *
  * @category models
  * @since 4.0.0
  */
@@ -844,6 +934,8 @@ export interface OpenAPIComponents {
 }
 
 /**
+ * Generated OpenAPI HTTP security scheme, such as bearer or basic authentication.
+ *
  * @category models
  * @since 4.0.0
  */
@@ -856,6 +948,8 @@ export interface OpenAPIHTTPSecurityScheme {
 }
 
 /**
+ * Generated OpenAPI API key security scheme.
+ *
  * @category models
  * @since 4.0.0
  */
@@ -867,6 +961,8 @@ export interface OpenAPIApiKeySecurityScheme {
 }
 
 /**
+ * Union of security scheme objects emitted in generated OpenAPI components.
+ *
  * @category models
  * @since 4.0.0
  */
@@ -875,12 +971,16 @@ export type OpenAPISecurityScheme =
   | OpenAPIApiKeySecurityScheme
 
 /**
+ * Generated OpenAPI security requirement, keyed by security scheme name.
+ *
  * @category models
  * @since 4.0.0
  */
 export type OpenAPISecurityRequirement = Record<string, Array<string>>
 
 /**
+ * Generated OpenAPI operation object for an HTTP API endpoint.
+ *
  * @category models
  * @since 4.0.0
  */