effect 4.0.0-beta.78 → 4.0.0-beta.79

package/src/unstable/httpapi/HttpApi.ts

@@ -1,50 +1,10 @@
 /**
- * The `HttpApi` module defines the top-level declaration for an Effect HTTP
- * API. An {@link HttpApi} has an identifier, annotations, and a collection of
- * groups whose endpoints describe request inputs, response schemas, middleware,
- * and route metadata.
+ * Describes an Effect HTTP API as groups of endpoints.
  *
- * An `HttpApi` value is the shared contract consumed by server builders,
- * generated clients, URL builders, OpenAPI generation, and reflection tools.
- * Handler implementations are supplied later with `HttpApiBuilder.group`, and
- * the completed API is registered with `HttpApiBuilder.layer`.
- *
- * **Mental model**
- *
- * - {@link make} creates an empty API declaration with a stable identifier.
- * - Groups are added to the API declaration, and each group owns its endpoint
- *   declarations.
- * - API-level prefixes, middleware, and annotations are composition operations
- *   over the groups already present in the declaration.
- * - {@link reflect} walks the final group and endpoint metadata with merged
- *   annotations, status-indexed response schemas, and middleware errors.
- *
- * **Common tasks**
- *
- * - Create an API with {@link make}.
- * - Add groups with the `add` method, or merge another API with `addHttpApi`.
- * - Apply a shared path prefix, middleware, or annotation through the methods on
- *   {@link HttpApi}.
- * - Inspect the resulting route shape with {@link reflect}.
- * - Register extra OpenAPI component schemas through {@link AdditionalSchemas}.
- *
- * **Gotchas**
- *
- * - Group identifiers are used as keys. Adding a group with the same identifier
- *   replaces the previous group.
- * - `prefix` and `middleware` affect the groups and endpoints already present
- *   when those methods are called.
- * - `addHttpApi` merges the added API's annotations into its groups.
- * - Reflection includes middleware error schemas with endpoint errors and treats
- *   endpoints without an explicit success schema as `NoContent`.
- * - Schemas supplied through {@link AdditionalSchemas} must have an `identifier`
- *   annotation so OpenAPI generation can emit them as components.
- *
- * **See also**
- *
- * - {@link make} for constructing API declarations.
- * - {@link reflect} for inspecting groups and endpoints.
- * - {@link AdditionalSchemas} for OpenAPI component schemas.
+ * An `HttpApi` value is data: it has an identifier, annotations, and groups of
+ * endpoints that describe request inputs, responses, middleware, and route
+ * metadata. The same description can be used by server builders, generated
+ * clients, URL builders, OpenAPI generation, and reflection tools.
  *
  * @since 4.0.0
  */

package/src/unstable/httpapi/HttpApiBuilder.ts

@@ -1,44 +1,10 @@
 /**
- * Server builders for declarative `HttpApi` contracts.
+ * Builds server routes from declarative `HttpApi` contracts.
  *
- * This module is the server-side bridge between an `HttpApi` description and an
- * `HttpRouter`. It turns endpoint metadata into routes, decodes incoming
- * request parts with `Schema`, runs HTTP API middleware, invokes the registered
- * handlers, and encodes successes or declared errors back into
- * `HttpServerResponse` values.
- *
- * **Mental model**
- *
- * `HttpApi` values describe what can be served; this module supplies how it is
- * served. Implement each group with {@link group}, then register the completed
- * API with {@link layer}. The layer reads the group implementations from the
- * Effect context, adds their routes to the active `HttpRouter`, and can also
- * expose the generated OpenAPI document.
- *
- * **Common tasks**
- *
- * Use {@link group} with `handlers.handle` to implement every endpoint in one
- * API group. Use `handlers.handleRaw` when the handler needs direct access to
- * the `HttpServerRequest` or must decode the payload manually. Use
- * {@link endpoint} when composing one endpoint route by hand, and use
- * {@link securityDecode} or {@link securitySetCookie} inside security-aware
- * middleware.
- *
- * **Gotchas**
- *
- * Every group in the API must have a matching {@link group} layer before
- * {@link layer} is evaluated; otherwise registration fails with a defect naming
- * the missing group service. Payload decoding is selected from the request
- * media type, so unsupported content types return `415` before the handler
- * runs. Request decoding failures are wrapped in `HttpApiSchemaError`; handler
- * failures are encoded only when they match the endpoint or middleware error
- * schemas.
- *
- * **See also**
- *
- * `HttpApi` for the top-level contract, `HttpApiGroup` and `HttpApiEndpoint`
- * for declaration, `HttpApiMiddleware` for server and client middleware, and
- * `OpenApi` for generated specifications.
+ * This module turns an `HttpApi` description plus group handlers into
+ * `HttpRouter` routes. At runtime it decodes request parts with schemas, runs
+ * middleware and security handlers, invokes the registered endpoint handler, and
+ * encodes successes or declared errors into `HttpServerResponse` values.
  *
  * @since 4.0.0
  */

package/src/unstable/httpapi/HttpApiClient.ts

@@ -1,36 +1,12 @@
 /**
- * Type-safe HTTP clients derived from `HttpApi` declarations.
+ * Builds HTTP clients from `HttpApi` declarations.
  *
- * This module turns the groups and endpoints described by an `HttpApi` into
- * callable client methods backed by an `HttpClient`. Use {@link make} or
- * {@link makeWith} to call a remote API with the same schema-driven contract as
- * the server, and use {@link group}, {@link endpoint}, or {@link urlBuilder}
- * when only part of an API or only the encoded URL is needed.
- *
- * **Mental model**
- *
- * A generated client mirrors the API structure: top-level endpoints become
- * methods on the client, and named groups become nested objects. Each call
- * encodes path parameters, query values, headers, and payloads from endpoint
- * schemas, runs client middleware, executes the request, and decodes successful
- * or declared error responses from the returned `HttpClientResponse`.
- *
- * **Common tasks**
- *
- * Use {@link make} when the `HttpClient` service should come from the Effect
- * environment. Use {@link makeWith} when a concrete or transformed client is
- * already available. Use {@link urlBuilder} to reuse endpoint path and query
- * encoding without executing a request. Select `responseMode` per call when
- * code needs the decoded value, the raw response, or both.
- *
- * **Gotchas**
- *
- * Payloads for HTTP methods without request bodies are encoded into URL
- * parameters, and multipart payloads must be supplied as `FormData`.
- * `response-only` skips success and error decoding for custom response
- * handling. Declared error responses decode into the endpoint error type;
- * unknown statuses fail as `HttpClientError.DecodeError`, and response decoding
- * can fail with `SchemaError`.
+ * The client methods are derived from the groups and endpoints in an `HttpApi`
+ * and run through an `HttpClient`. They use the same schema-driven contract as
+ * the server: request parts are encoded from endpoint schemas, client
+ * middleware is applied, the HTTP request is executed, and declared success or
+ * error responses are decoded. This module also includes helpers for building a
+ * client for only one group, one endpoint, or only the encoded URL.
  *
  * @since 4.0.0
  */
@@ -644,24 +620,25 @@ export const urlBuilder = <Api extends HttpApi.Any>(api: Api, options?: {
 
 // ----------------------------------------------------------------------------
 
-const paramsRegExp = /:(\w+)\??/g
+const paramsRegExp = /(\/?):(\w+)(\?)?/g
 
 const compilePath = (path: string) => {
-  const segments = path.split(paramsRegExp)
-  const len = segments.length
-  if (len === 1) {
+  if (!paramsRegExp.test(path)) {
     return (_: any) => path
   }
+  paramsRegExp.lastIndex = 0
   return (params: Record<string, string | undefined>) => {
-    let url = segments[0]
-    for (let i = 1; i < len; i++) {
-      if (i % 2 === 0) {
-        url += segments[i]
-      } else {
-        url += params[segments[i]]
+    paramsRegExp.lastIndex = 0
+    return path.replace(paramsRegExp, (_, slash: string, key: string, optional: string | undefined) => {
+      const value = params[key]
+      if (value === undefined) {
+        if (optional !== undefined) {
+          return ""
+        }
+        throw new Error(`Missing path parameter: ${key}`)
       }
-    }
-    return url
+      return `${slash}${encodeURIComponent(value)}`
+    })
   }
 }
 

package/src/unstable/httpapi/HttpApiEndpoint.ts

@@ -1,55 +1,13 @@
 /**
- * The `HttpApiEndpoint` module defines the route-level contracts used inside an
- * HTTP API group. An endpoint records a stable name, HTTP method, router path,
- * request schemas, response schemas, declared errors, middleware, and
- * annotations.
- *
- * Endpoint values are declarations, not handlers. Builders use them to decode
- * requests, type handler input, encode responses, generate OpenAPI metadata,
- * and derive generated-client call signatures.
- *
- * **Mental model**
- *
- * - Each {@link HttpApiEndpoint} describes one HTTP route.
- * - Method constructors such as {@link get}, {@link post}, {@link put},
- *   {@link patch}, {@link head}, and {@link options} create endpoint
- *   declarations. Use {@link make} when you need a method-specific constructor.
- * - Params, query, headers, payload, success, and error schemas determine both
- *   runtime encoding/decoding and the exported helper types such as
- *   {@link Request}, {@link ClientRequest}, {@link Success}, and {@link Error}.
- * - Endpoint middleware and annotations are stored on the declaration so server
- *   builders, clients, and OpenAPI generation can see the same route metadata.
- *
- * **Common tasks**
- *
- * - Declare operations with {@link get}, {@link post}, {@link put},
- *   {@link patch}, `delete`, {@link head}, or {@link options}.
- * - Add params, query, headers, payload, success, and error schemas in the
- *   constructor options.
- * - Attach endpoint-specific middleware or annotations with the methods on
- *   {@link HttpApiEndpoint}.
- * - Use helper types such as {@link Handler}, {@link HandlerRaw},
- *   {@link ServerServices}, and {@link ClientServices} when integrating with
- *   builders or clients.
- *
- * **Gotchas**
- *
- * - Paths use `HttpRouter.PathInput`; route parameters come from the router and
- *   are decoded by the optional `params` schema.
- * - With codecs enabled, params, query, and headers use string-tree codecs. Body
- *   methods use JSON payload codecs by default; no-body methods use string-tree
- *   payload codecs.
- * - Multiple payload schemas can share a content type only when they use the
- *   same encoding strategy. Multipart payloads cannot be combined under the same
- *   content type.
- * - Endpoint errors are merged with middleware errors for server encoding and
- *   client decoding.
- *
- * **See also**
- *
- * - {@link PayloadMap} for the payload schema map stored on endpoints.
- * - {@link Request} and {@link ClientRequest} for request helper types.
- * - {@link Handler} and {@link HandlerRaw} for server handler signatures.
+ * Defines endpoint declarations used inside an HTTP API group.
+ *
+ * An endpoint records a stable name, HTTP method, router path, request schemas,
+ * response schemas, declared errors, middleware, and annotations. Endpoint
+ * values are declarations, not handlers: builders use them to decode requests,
+ * type handler input, encode responses, generate OpenAPI metadata, and derive
+ * generated-client call signatures. This module also includes HTTP method
+ * constructors, payload and response schema helpers, and type utilities used by
+ * builders and generated clients.
  *
  * @since 4.0.0
  */

package/src/unstable/httpapi/HttpApiError.ts

@@ -3,41 +3,10 @@
  *
  * This module provides reusable `Schema.ErrorClass` values for common HTTP
  * status codes, plus `HttpApiSchemaError` for request decoding failures raised
- * by the HTTP API runtime. The status errors are ready to use in endpoint or
+ * by the HTTP API runtime. The status errors can be used in endpoint or
  * middleware error declarations and are understood by builders, generated
  * clients, reflection, and OpenAPI generation.
  *
- * **Mental model**
- *
- * Each status error carries an `httpApiStatus` schema annotation and implements
- * `HttpServerRespondable`. Declaring one as an endpoint error tells the server
- * how to encode that failure and tells generated clients how to decode it. Using
- * an instance directly as a server response produces an empty response with the
- * matching HTTP status.
- *
- * **Common tasks**
- *
- * Use classes such as {@link BadRequest}, {@link Unauthorized}, {@link NotFound},
- * or {@link InternalServerError} when an API error should have a typed body.
- * Use the matching `*NoContent` exports when the wire response intentionally has
- * no body but clients should still decode that status into a typed error value.
- * Use {@link HttpApiSchemaError} to identify failures from decoding path
- * params, headers, query values, body values, or payload values.
- *
- * **Gotchas**
- *
- * Custom error schemas need an explicit `HttpApiSchema.status` annotation when
- * they should map to a status other than `500 Internal Server Error`. Request
- * decoding failures are represented separately by {@link HttpApiSchemaError},
- * which responds as `400 Bad Request` unless middleware transforms it into a
- * declared API error.
- *
- * **See also**
- *
- * `HttpApiSchema` for status and no-content annotations, `HttpApiEndpoint` for
- * declaring endpoint errors, `HttpApiMiddleware` for middleware error schemas,
- * and `HttpApiBuilder` for server-side error encoding.
- *
  * @since 4.0.0
  */
 import * as Data from "../../Data.ts"

package/src/unstable/httpapi/HttpApiGroup.ts

@@ -1,38 +1,12 @@
 /**
- * Defines named collections of `HttpApiEndpoint`s inside an `HttpApi`.
- *
- * A group is the boundary for endpoints that belong to the same resource,
- * feature area, or domain concern. Builders, generated clients, URL builders,
- * and OpenAPI generation read the same group value, including its identifier,
- * endpoint set, annotations, and `topLevel` flag.
- *
- * **Mental model**
- *
- * Start with {@link make}, add endpoints, then apply group-wide transforms such
- * as `prefix`, `middleware`, or endpoint annotations. A regular group becomes a
- * named namespace in generated clients. A `topLevel` group exposes its endpoint
- * methods directly on the client.
- *
- * **Common tasks**
- *
- * Use this module to collect related endpoints, share a path prefix or
- * middleware across the current endpoint set, attach metadata to the group or to
- * each current endpoint, and derive group-level types for builders and generated
- * clients.
- *
- * **Gotchas**
- *
- * Adding an endpoint with the same name as an existing endpoint replaces it.
- * `prefix`, `middleware`, `annotateEndpoints`, and `annotateEndpointsMerge`
- * affect only endpoints that are already present when those APIs are called.
- * Group annotations stay on the group; use endpoint annotation helpers when
- * metadata must be attached to each endpoint.
- *
- * **See also**
- *
- * `HttpApiEndpoint` for individual route contracts, `HttpApi` for composing
- * groups into a complete API, and `HttpApiBuilder` for supplying
- * implementations.
+ * Defines named groups of HTTP API endpoints.
+ *
+ * A group collects endpoints that belong to the same resource or feature area
+ * inside an `HttpApi`. Builders, generated clients, URL builders, and OpenAPI
+ * generation read the same group value, including its identifier, endpoints,
+ * annotations, and `topLevel` flag. This module includes helpers for creating
+ * groups, adding endpoints, prefixing paths, applying middleware, annotating
+ * groups or endpoints, and deriving builder or client types.
  *
  * @since 4.0.0
  */

package/src/unstable/httpapi/HttpApiMiddleware.ts

@@ -1,52 +1,13 @@
 /**
- * The `HttpApiMiddleware` module defines middleware service keys for
- * declarative HTTP APIs. Middleware wraps endpoint execution on the server and,
- * when required by an API, can also wrap requests made by generated clients.
- *
- * Middleware is where you put cross-cutting behavior that belongs to the API
- * contract: authentication, authorization, request logging, tracing, rate
- * limiting, request-scoped services, schema-error normalization, and client
- * request decoration.
- *
- * **Mental model**
- *
- * - A middleware is declared with {@link Service}; the declaration is both a
- *   `Context.Service` key and a typed description of the middleware contract.
- * - Server implementations receive the endpoint response effect plus endpoint
- *   and group metadata. Security middleware also receives decoded credentials
- *   from the configured `HttpApiSecurity` scheme.
- * - The service metadata records provided services, required services, declared
- *   error schemas, client error types, security schemes, and whether generated
- *   clients must install a matching client middleware.
- * - Client middleware is published through the {@link ForClient} marker by
- *   {@link layerClient} and participates in the generated client's request
- *   pipeline.
- *
- * **Common tasks**
- *
- * - Declare middleware services with {@link Service}.
- * - Detect security middleware with {@link isSecurity}.
- * - Convert `HttpApiSchemaError` failures into declared API errors with
- *   {@link layerSchemaErrorTransform}.
- * - Install a generated-client middleware with {@link layerClient}.
- *
- * **Gotchas**
- *
- * - Middleware error declarations must be `Schema` values, or arrays of
- *   `Schema` values, because builders and clients encode and decode them as
- *   part of the endpoint error surface.
- * - A security middleware must declare at least one security scheme. Ordinary
- *   middleware does not receive credentials.
- * - A schema-error transform must fail with an error covered by the middleware's
- *   declared error schema.
- * - `requiredForClient` adds a client-side requirement. Provide it with
- *   {@link layerClient}; the layer captures its surrounding context.
- *
- * **See also**
- *
- * - {@link Service} for declaring middleware service keys.
- * - {@link layerSchemaErrorTransform} for mapping schema failures.
- * - {@link layerClient} for generated-client middleware.
+ * Declares middleware for schema-driven HTTP APIs.
+ *
+ * HTTP API middleware wraps endpoint execution on the server and, when the API
+ * requires it, can also wrap requests made by generated clients. It is used for
+ * cross-cutting behavior that belongs to the API contract, such as
+ * authentication, authorization, logging, tracing, rate limiting,
+ * request-scoped services, schema-error handling, and client request
+ * decoration. This module defines the middleware service keys and helpers used
+ * by `HttpApi` declarations.
  *
  * @since 4.0.0
  */

package/src/unstable/httpapi/HttpApiScalar.ts

@@ -6,30 +6,6 @@
  * page containing the OpenAPI document produced from the supplied `HttpApi` and
  * boots Scalar in the browser.
  *
- * ## Mental model
- *
- * {@link layer} serves the UI with the bundled Scalar script. {@link layerCdn}
- * serves the same UI while loading Scalar from jsDelivr, optionally pinned with
- * `version`. Both helpers register a `GET` route, defaulting to `/docs`, and
- * pass {@link ScalarConfig} through to Scalar's HTML configuration.
- *
- * ## Common tasks
- *
- * - Use {@link layer} when the application should serve the bundled Scalar
- *   assets without depending on a CDN at runtime.
- * - Use {@link layerCdn} when a CDN-loaded Scalar bundle is preferred, and pin
- *   `version` when repeatable output matters.
- * - Set `path` to mount the documentation UI somewhere other than `/docs`.
- * - Set `proxyUrl`, theme, layout, and `baseServerURL` in `ScalarConfig` for
- *   request testing, styling, and relative server URLs.
- *
- * ## Gotchas
- *
- * The mounted route is an HTML documentation page, not a raw OpenAPI JSON
- * endpoint. If clients, gateways, or documentation pipelines need the OpenAPI
- * document directly, expose it separately with `HttpApiBuilder.layer`'s
- * `openapiPath` option.
- *
  * @since 4.0.0
  */
 import * as Effect from "../../Effect.ts"

package/src/unstable/httpapi/HttpApiSchema.ts

@@ -7,38 +7,6 @@
  * 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
  */
 import { constVoid, type LazyArg } from "../../Function.ts"

package/src/unstable/httpapi/HttpApiSecurity.ts

@@ -6,35 +6,6 @@
  * `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"

package/src/unstable/httpapi/HttpApiSwagger.ts

@@ -6,30 +6,6 @@
  * running application can expose interactive API documentation without writing a
  * separate OpenAPI file.
  *
- * **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
  */
 import * as Effect from "../../Effect.ts"

package/src/unstable/httpapi/HttpApiTest.ts

@@ -1,23 +1,10 @@
 /**
- * The `HttpApiTest` module provides helpers for testing `HttpApi`
- * implementations through the generated client interface without starting an
- * HTTP server.
+ * Tests `HttpApi` implementations through an in-memory generated client.
  *
- * 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.
+ * The helpers use the same request encoding, routing, response encoding, and
+ * client decoding as the normal `HttpApiBuilder` and `HttpApiClient` pipeline,
+ * but they do not start an HTTP server. This is useful for focused handler
+ * tests, schema round trips, middleware behavior, and typed client calls.
  *
  * @since 4.0.0
  */

package/src/unstable/httpapi/OpenApi.ts

@@ -1,44 +1,10 @@
 /**
- * OpenAPI 3.1 generation for declarative `HttpApi` contracts.
- *
- * 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. 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.
- *
- * **Gotchas**
- *
- * 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.
+ * Generates OpenAPI 3.1 documents from declarative `HttpApi` contracts.
+ *
+ * The generator reads API groups, endpoints, schemas, security definitions, and
+ * annotations, then produces an OpenAPI document. This module also provides the
+ * annotations used to shape that output and the TypeScript model for the
+ * OpenAPI objects it generates.
  *
  * @since 4.0.0
  */