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

package/dist/unstable/httpapi/HttpApiMiddleware.d.ts

@@ -1,28 +1,52 @@
 /**
- * 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.
+ * 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.
  *
  * @since 4.0.0
  */
@@ -280,7 +304,7 @@ export type ServiceClass<Self, Id extends string, Config extends {
  *
  * **When to use**
  *
- * Use the optional configuration to declare required services, provided services,
+ * Use when you 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.
  *

package/dist/unstable/httpapi/HttpApiMiddleware.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"HttpApiMiddleware.d.ts","sourceRoot":"","sources":["../../../src/unstable/httpapi/HttpApiMiddleware.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,mDAAmD;AACnD,gDAAgD;AAChD,OAAO,KAAK,OAAO,MAAM,kBAAkB,CAAA;AAC3C,OAAO,KAAK,MAAM,MAAM,iBAAiB,CAAA;AACzC,OAAO,KAAK,KAAK,MAAM,gBAAgB,CAAA;AAEvC,OAAO,KAAK,KAAK,MAAM,MAAM,iBAAiB,CAAA;AAC9C,OAAO,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAA;AACtC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAC/C,OAAO,KAAK,KAAK,eAAe,MAAM,4BAA4B,CAAA;AAClE,OAAO,KAAK,KAAK,iBAAiB,MAAM,8BAA8B,CAAA;AACtE,OAAO,KAAK,KAAK,kBAAkB,MAAM,+BAA+B,CAAA;AACxE,OAAO,KAAK,KAAK,UAAU,MAAM,uBAAuB,CAAA;AACxD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,+BAA+B,CAAA;AACvE,OAAO,KAAK,KAAK,eAAe,MAAM,sBAAsB,CAAA;AAC5D,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAA;AACtD,OAAO,KAAK,KAAK,YAAY,MAAM,mBAAmB,CAAA;AACtD,OAAO,KAAK,KAAK,eAAe,MAAM,sBAAsB,CAAA;AAE5D,QAAA,MAAM,MAAM,sCAAsC,CAAA;AAElD,QAAA,MAAM,cAAc,+CAA+C,CAAA;AAEnE;;;;;GAKG;AACH,eAAO,MAAM,UAAU,GAAI,GAAG,UAAU,KAAG,CAAC,IAAI,kBAAoD,CAAA;AAEpG,KAAK,eAAe,GAAG,MAAM,CAAC,GAAG,GAAG,aAAa,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;AAE7D,KAAK,yBAAyB,CAAC,CAAC,IAAI,CAAC,SAAS,aAAa,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,GAC/E,CAAC,SAAS,MAAM,CAAC,GAAG,GAAG,CAAC,GACxB,KAAK,CAAA;AAET;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,iBAAiB,CAAC,QAAQ,EAAE,CAAC,SAAS,eAAe,EAAE,QAAQ,IAAI,CAC7E,UAAU,EAAE,MAAM,CAAC,MAAM,CAAC,kBAAkB,EAAE,SAAS,EAAE,QAAQ,CAAC,EAClE,OAAO,EAAE;IACP,QAAQ,CAAC,QAAQ,EAAE,eAAe,CAAC,YAAY,CAAA;IAC/C,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC,YAAY,CAAA;CAC1C,KACE,MAAM,CAAC,MAAM,CAAC,kBAAkB,EAAE,SAAS,GAAG,yBAAyB,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,EAAE,QAAQ,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAA;AAExH;;;;;;;;;;GAUG;AACH,MAAM,MAAM,yBAAyB,CACnC,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,eAAe,CAAC,EAChE,QAAQ,EACR,CAAC,SAAS,eAAe,EACzB,QAAQ,IACN;IACF,QAAQ,EAAE,CAAC,IAAI,MAAM,QAAQ,GAAG,CAC9B,UAAU,EAAE,MAAM,CAAC,MAAM,CAAC,kBAAkB,EAAE,SAAS,EAAE,QAAQ,CAAC,EAClE,OAAO,EAAE;QACP,QAAQ,CAAC,UAAU,EAAE,eAAe,CAAC,eAAe,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAA;QACtE,QAAQ,CAAC,QAAQ,EAAE,eAAe,CAAC,YAAY,CAAA;QAC/C,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC,YAAY,CAAA;KAC1C,KACE,MAAM,CAAC,MAAM,CAChB,kBAAkB,EAClB,SAAS,GAAG,yBAAyB,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,EAChD,QAAQ,GAAG,UAAU,CAAC,QAAQ,CAC/B;CACF,CAAA;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,uBAAuB,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC;IAChD,CAAC,OAAO,EAAE;QACR,QAAQ,CAAC,QAAQ,EAAE,eAAe,CAAC,YAAY,CAAA;QAC/C,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC,YAAY,CAAA;QACzC,QAAQ,CAAC,OAAO,EAAE,iBAAiB,CAAC,iBAAiB,CAAA;QACrD,QAAQ,CAAC,IAAI,EAAE,CACb,OAAO,EAAE,iBAAiB,CAAC,iBAAiB,KACzC,MAAM,CAAC,MAAM,CAAC,kBAAkB,CAAC,kBAAkB,EAAE,eAAe,CAAC,eAAe,CAAC,CAAA;KAC3F,GAAG,MAAM,CAAC,MAAM,CAAC,kBAAkB,CAAC,kBAAkB,EAAE,EAAE,GAAG,eAAe,CAAC,eAAe,EAAE,CAAC,CAAC,CAAA;CAClG;AAED;;;;;GAKG;AACH,MAAM,WAAW,SAAS,CAAC,EAAE;IAC3B,QAAQ,CAAC,CAAC,EAAE,OAAO,MAAM,CAAA;IACzB,QAAQ,CAAC,EAAE,EAAE,EAAE,CAAA;CAChB;AAED;;;;;GAKG;AACH,MAAM,WAAW,UAAW,SAAQ,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,GAAG,CAAC;IACvD,QAAQ,CAAC,CAAC,MAAM,CAAC,EAAE,OAAO,MAAM,CAAA;IAChC,QAAQ,CAAC,QAAQ,EAAE,GAAG,CAAA;IACtB,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;IACvC,QAAQ,CAAC,iBAAiB,EAAE,OAAO,CAAA;IACnC,QAAQ,CAAC,cAAc,EAAE,GAAG,CAAA;CAC7B;AAED;;;;;GAKG;AACH,MAAM,WAAW,kBAAmB,SAAQ,UAAU;IACpD,QAAQ,CAAC,CAAC,cAAc,CAAC,EAAE,OAAO,cAAc,CAAA;IAChD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,eAAe,CAAC,CAAA;CACnE;AAED;;;;;GAKG;AACH,MAAM,WAAW,KAAK;IACpB,QAAQ,CAAC,CAAC,MAAM,CAAC,EAAE;QACjB,QAAQ,CAAC,QAAQ,EAAE,GAAG,CAAA;QACtB,QAAQ,CAAC,QAAQ,EAAE,GAAG,CAAA;QACtB,QAAQ,CAAC,KAAK,EAAE,eAAe,CAAA;QAC/B,QAAQ,CAAC,WAAW,EAAE,GAAG,CAAA;QACzB,QAAQ,CAAC,iBAAiB,EAAE,OAAO,CAAA;KACpC,CAAA;CACF;AAED;;;;;GAKG;AACH,MAAM,MAAM,QAAQ,CAAC,CAAC,IAAI,CAAC,SAAS;IAAE,QAAQ,CAAC,CAAC,MAAM,CAAC,EAAE;QAAE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAA;KAAE,CAAA;CAAE,GAAG,CAAC,GAAG,KAAK,CAAA;AAErG;;;;;GAKG;AACH,MAAM,MAAM,QAAQ,CAAC,CAAC,IAAI,CAAC,SAAS;IAAE,QAAQ,CAAC,CAAC,MAAM,CAAC,EAAE;QAAE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAA;KAAE,CAAA;CAAE,GAAG,CAAC,GAAG,KAAK,CAAA;AAErG;;;;;GAKG;AACH,MAAM,MAAM,aAAa,CAAC,CAAC,SAAS,KAAK,EAAE,CAAC,IAAI,OAAO,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAA;AAErF;;;;;GAKG;AACH,MAAM,MAAM,WAAW,CAAC,CAAC,IAAI,CAAC,SAAS;IAAE,QAAQ,CAAC,CAAC,MAAM,CAAC,EAAE;QAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,CAAA;KAAE,CAAA;CAAE,GAAG,yBAAyB,CAAC,CAAC,CAAC,GACpH,KAAK,CAAA;AAET;;;;;GAKG;AACH,MAAM,MAAM,KAAK,CAAC,CAAC,IAAI,WAAW,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAA;AAE7C;;;;;GAKG;AACH,MAAM,MAAM,WAAW,CAAC,CAAC,IAAI,CAAC,SAAS;IACrC,QAAQ,CAAC,CAAC,MAAM,CAAC,EAAE;QACjB,QAAQ,CAAC,WAAW,EAAE,MAAM,EAAE,CAAA;QAC9B,QAAQ,CAAC,iBAAiB,EAAE,IAAI,CAAA;KACjC,CAAA;CACF,GAAG,EAAE,GACF,KAAK,CAAA;AAET;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,CAAC,CAAC,IAAI,CAAC,SAAS;IAC1C,QAAQ,CAAC,CAAC,MAAM,CAAC,EAAE;QACjB,QAAQ,CAAC,iBAAiB,EAAE,IAAI,CAAA;KACjC,CAAA;CACF,GAAG,SAAS,CAAC,CAAC,CAAC,GACZ,KAAK,CAAA;AAET;;;;;GAKG;AACH,MAAM,MAAM,mBAAmB,CAAC,CAAC,IAAI,WAAW,CAAC,CAAC,CAAC,CAAC,kBAAkB,CAAC,CAAA;AAEvE;;;;;GAKG;AACH,MAAM,MAAM,mBAAmB,CAAC,CAAC,IAAI,WAAW,CAAC,CAAC,CAAC,CAAC,kBAAkB,CAAC,CAAA;AAEvE;;;;;;;;;;GAUG;AACH,MAAM,MAAM,YAAY,CACtB,IAAI,EACJ,EAAE,SAAS,MAAM,EACjB,MAAM,SAAS;IACb,QAAQ,EAAE,GAAG,CAAA;IACb,QAAQ,EAAE,GAAG,CAAA;IACb,KAAK,EAAE,eAAe,CAAA;IACtB,WAAW,EAAE,GAAG,CAAA;IAChB,iBAAiB,EAAE,OAAO,CAAA;IAC1B,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,eAAe,CAAC,CAAA;CAC1D,EACD,OAAO,GACL,CAAC,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,GAAG,iBAAiB,CAAC,MAAM,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC,CAAC,GAC9G,yBAAyB,CAAC,MAAM,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC,IAE3G,OAAO,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,GAC9B;IACA,KAAI,CAAC,EAAE,KAAK,GAAG,OAAO,CAAC,YAAY,CAAC,KAAK,CAAC,EAAE,EAAE,OAAO,CAAC,GAAG;QACvD,QAAQ,CAAC,CAAC,MAAM,CAAC,EAAE;YACjB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,OAAO,CAAC,CAAA;YAC/B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC,UAAU,CAAC,CAAA;YACrC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC,UAAU,CAAC,CAAA;YACrC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC,aAAa,CAAC,CAAA;YAC3C,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC,mBAAmB,CAAC,CAAA;SACxD,CAAA;KACF,CAAA;IACD,QAAQ,CAAC,CAAC,MAAM,CAAC,EAAE,OAAO,MAAM,CAAA;IAChC,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;IACvC,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC,mBAAmB,CAAC,CAAA;IACvD,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC,aAAa,CAAC,CAAA;CAC/C,GACC,CAAC,CAAC,MAAM,MAAM,CAAC,UAAU,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,GAAG,EAAE,GAAG;IACnD,QAAQ,CAAC,CAAC,cAAc,CAAC,EAAE,OAAO,cAAc,CAAA;IAChD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC,UAAU,CAAC,CAAA;CACtC,CAAC,CAAA;AAEJ;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,OAAO,GAClB,IAAI,EACJ,MAAM,SAAS;IACb,QAAQ,CAAC,EAAE,GAAG,CAAA;IACd,QAAQ,CAAC,EAAE,GAAG,CAAA;IACd,WAAW,CAAC,EAAE,GAAG,CAAA;CAClB,GAAG;IAAE,QAAQ,EAAE,KAAK,CAAC;IAAC,QAAQ,EAAE,KAAK,CAAC;IAAC,WAAW,EAAE,KAAK,CAAA;CAAE,OACzD,CACH,KAAK,CAAC,EAAE,SAAS,MAAM,EACvB,KAAK,CAAC,KAAK,SAAS,eAAe,GAAG,KAAK,EAC3C,KAAK,CAAC,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,eAAe,CAAC,GAAG,KAAK,EAC9E,iBAAiB,SAAS,OAAO,GAAG,KAAK,EAEzC,EAAE,EAAE,EAAE,EACN,OAAO,CAAC,EAAE;IACR,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,GAAG,SAAS,CAAA;IAClC,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,GAAG,SAAS,CAAA;IACxC,QAAQ,CAAC,iBAAiB,CAAC,EAAE,iBAAiB,GAAG,SAAS,CAAA;CAC3D,GAAG,SAAS,KACV,YAAY,CAAC,IAAI,EAAE,EAAE,EAAE;IAC1B,QAAQ,EAAE,UAAU,SAAS,MAAM,MAAM,GAAG,MAAM,CAAC,UAAU,CAAC,GAAG,KAAK,CAAA;IACtE,QAAQ,EAAE,UAAU,SAAS,MAAM,MAAM,GAAG,MAAM,CAAC,UAAU,CAAC,GAAG,KAAK,CAAA;IACtE,KAAK,EAAE,KAAK,CAAA;IACZ,WAAW,EAAE,aAAa,SAAS,MAAM,MAAM,GAAG,MAAM,CAAC,aAAa,CAAC,GAAG,KAAK,CAAA;IAC/E,iBAAiB,EAAE,iBAAiB,CAAA;IACpC,QAAQ,EAAE,QAAQ,CAAA;CACnB,CAiCA,CAAA;AAOD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,eAAO,MAAM,yBAAyB,GAAI,EAAE,EAAE,CAAC,SAAS,eAAe,EAAE,QAAQ,EAC/E,SAAS,OAAO,CAAC,OAAO,CAAC,EAAE,EAAE,iBAAiB,CAAC,KAAK,EAAE,CAAC,EAAE,QAAQ,CAAC,CAAC,EACnE,WAAW,CACT,KAAK,EAAE,kBAAkB,EACzB,OAAO,EAAE;IAAE,QAAQ,CAAC,QAAQ,EAAE,eAAe,CAAC,YAAY,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC,YAAY,CAAA;CAAE,KACpG,MAAM,CAAC,MAAM,CAChB,kBAAkB,EAClB,yBAAyB,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,kBAAkB,EACzD,QAAQ,GAAG,UAAU,CAAC,QAAQ,CAC/B,KACA,KAAK,CAAC,KAAK,CAAC,EAAE,CAYd,CAAA;AAEH;;;;;;;;;;GAUG;AACH,eAAO,MAAM,WAAW,GAAI,EAAE,SAAS,KAAK,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,GAAG,KAAK,EAAE,EAAE,GAAG,KAAK,EACxE,KAAK,OAAO,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC,CAAC,EACvB,SACI,uBAAuB,CAAC,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,OAAO,MAAM,CAAC,CAAC,aAAa,CAAC,EAAE,CAAC,CAAC,GACvE,MAAM,CAAC,MAAM,CACb,uBAAuB,CAAC,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,OAAO,MAAM,CAAC,CAAC,aAAa,CAAC,EAAE,CAAC,CAAC,EACvE,EAAE,EACF,EAAE,CACH,KACF,KAAK,CAAC,KAAK,CAAC,SAAS,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,GAAG,OAAO,CAAC,EAAE,EAAE,KAAK,CAAC,CAgBnD,CAAA"}
+{"version":3,"file":"HttpApiMiddleware.d.ts","sourceRoot":"","sources":["../../../src/unstable/httpapi/HttpApiMiddleware.ts"],"names":[],"mappings":"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"}

package/dist/unstable/httpapi/HttpApiMiddleware.js

@@ -1,28 +1,52 @@
 /**
- * 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.
+ * 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.
  *
  * @since 4.0.0
  */
@@ -48,7 +72,7 @@ export const isSecurity = u => hasProperty(u, SecurityTypeId);
  *
  * **When to use**
  *
- * Use the optional configuration to declare required services, provided services,
+ * Use when you 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.
  *

package/dist/unstable/httpapi/HttpApiMiddleware.js.map

@@ -1 +1 @@
-{"version":3,"file":"HttpApiMiddleware.js","names":["Context","Effect","Layer","hasProperty","Scope","HttpApiSchemaError","TypeId","SecurityTypeId","isSecurity","u","Service","id","options","Err","globalThis","Error","limit","stackTraceLimit","creationError","self","Object","defineProperty","get","stack","error","getError","requiredForClient","security","undefined","keys","length","Set","Array","isArray","layerSchemaErrorTransform","service","transform","succeed","httpEffect","catch","e","is","fail","layerClient","tag","effectContext","gen","services","context","pipe","omit","middleware","isEffect","makeUnsafe","Map","key","updateContext","requestContext","merge"],"sources":["../../../src/unstable/httpapi/HttpApiMiddleware.ts"],"sourcesContent":[null],"mappings":"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","ignoreList":[]}
+{"version":3,"file":"HttpApiMiddleware.js","names":["Context","Effect","Layer","hasProperty","Scope","HttpApiSchemaError","TypeId","SecurityTypeId","isSecurity","u","Service","id","options","Err","globalThis","Error","limit","stackTraceLimit","creationError","self","Object","defineProperty","get","stack","error","getError","requiredForClient","security","undefined","keys","length","Set","Array","isArray","layerSchemaErrorTransform","service","transform","succeed","httpEffect","catch","e","is","fail","layerClient","tag","effectContext","gen","services","context","pipe","omit","middleware","isEffect","makeUnsafe","Map","key","updateContext","requestContext","merge"],"sources":["../../../src/unstable/httpapi/HttpApiMiddleware.ts"],"sourcesContent":[null],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAoDA;AACA;AACA,OAAO,KAAKA,OAAO,MAAM,kBAAkB;AAC3C,OAAO,KAAKC,MAAM,MAAM,iBAAiB;AACzC,OAAO,KAAKC,KAAK,MAAM,gBAAgB;AACvC,SAASC,WAAW,QAAQ,oBAAoB;AAEhD,SAASC,KAAK,QAAQ,gBAAgB;AAQtC,SAASC,kBAAkB,QAAQ,mBAAmB;AAItD,MAAMC,MAAM,GAAG,mCAAmC;AAElD,MAAMC,cAAc,GAAG,4CAA4C;AAEnE;;;;;;AAMA,OAAO,MAAMC,UAAU,GAAIC,CAAa,IAA8BN,WAAW,CAACM,CAAC,EAAEF,cAAc,CAAC;AAwQpG;;;;;;;;;;;;AAYA,OAAO,MAAMG,OAAO,GAAGA,CAAA,KA2BvB,CACEC,EAAU,EACVC,OAIa,KACX;EACF,MAAMC,GAAG,GAAGC,UAAU,CAACC,KAAY;EACnC,MAAMC,KAAK,GAAGH,GAAG,CAACI,eAAe;EACjCJ,GAAG,CAACI,eAAe,GAAG,CAAC;EACvB,MAAMC,aAAa,GAAG,IAAIL,GAAG,EAAE;EAC/BA,GAAG,CAACI,eAAe,GAAGD,KAAK;EAE3B,MAAMN,OAAQ,SAAQV,OAAO,CAACU,OAAO,EAAa,CAACC,EAAE,CAAC;EACtD,MAAMQ,IAAI,GAAGT,OAAc;EAC3BU,MAAM,CAACC,cAAc,CAACX,OAAO,EAAE,OAAO,EAAE;IACtCY,GAAGA,CAAA;MACD,OAAOJ,aAAa,CAACK,KAAK;IAC5B;GACD,CAAC;EACFJ,IAAI,CAACb,MAAM,CAAC,GAAGA,MAAM;EACrBa,IAAI,CAACK,KAAK,GAAGC,QAAQ,CAACb,OAAO,EAAEY,KAAK,CAAC;EACrCL,IAAI,CAACO,iBAAiB,GAAGd,OAAO,EAAEc,iBAAiB,IAAI,KAAK;EAC5D,IAAId,OAAO,EAAEe,QAAQ,KAAKC,SAAS,EAAE;IACnC,IAAIR,MAAM,CAACS,IAAI,CAACjB,OAAO,CAACe,QAAQ,CAAC,CAACG,MAAM,KAAK,CAAC,EAAE;MAC9C,MAAM,IAAIf,KAAK,CAAC,8DAA8D,CAAC;IACjF;IACAI,IAAI,CAACZ,cAAc,CAAC,GAAGA,cAAc;IACrCY,IAAI,CAACQ,QAAQ,GAAGf,OAAO,CAACe,QAAQ;EAClC;EACA,OAAOR,IAAI;AACb,CAAC;AAED,SAASM,QAAQA,CAACD,KAAkC;EAClD,IAAIA,KAAK,KAAKI,SAAS,EAAE,OAAO,IAAIG,GAAG,EAAE;EACzC,OAAO,IAAIA,GAAG,CAACC,KAAK,CAACC,OAAO,CAACT,KAAK,CAAC,GAAGA,KAAK,GAAG,CAACA,KAAK,CAAC,CAAC;AACxD;AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAiCA,OAAO,MAAMU,yBAAyB,GAAGA,CACvCC,OAAmE,EACnEC,SAOC,KAEDlC,KAAK,CAACmC,OAAO,CACXF,OAAO,EACP,CAACG,UAAU,EAAE1B,OAAO,KAClBX,MAAM,CAACsC,KAAK,CACVD,UAAU,EACTE,CAAC,IAIGnC,kBAAkB,CAACoC,EAAE,CAACD,CAAC,CAAC,GAAGJ,SAAS,CAACI,CAAC,EAAE5B,OAAO,CAAC,GAAGX,MAAM,CAACyC,IAAI,CAACF,CAAC,CAAC,CACvE,CACJ;AAEH;;;;;;;;;;;AAWA,OAAO,MAAMG,WAAW,GAAGA,CACzBC,GAAuB,EACvBT,OAMG,KAEHjC,KAAK,CAAC2C,aAAa,CAAC5C,MAAM,CAAC6C,GAAG,CAAC,aAAS;EACtC,MAAMC,QAAQ,GAAG,CAAC,OAAO9C,MAAM,CAAC+C,OAAO,EAAa,EAAEC,IAAI,CACxDjD,OAAO,CAACkD,IAAI,CAAC9C,KAAK,CAAC,CACE;EACvB,MAAM+C,UAAU,GAAGlD,MAAM,CAACmD,QAAQ,CAACjB,OAAO,CAAC,GAAG,OAAOA,OAAO,GAAGA,OAAO;EACtE,OAAOnC,OAAO,CAACqD,UAAU,CACvB,IAAIC,GAAG,CAAC,CAAC,CACP,GAAGV,GAAG,CAACW,GAAG,SAAS,EAClB3C,OAAY,IACXX,MAAM,CAACuD,aAAa,CAClBL,UAAU,CAACvC,OAAO,CAAC,EAClB6C,cAAc,IAAKzD,OAAO,CAAC0D,KAAK,CAACX,QAAQ,EAAEU,cAAc,CAAC,CAC5D,CACJ,CAAC,CAAC,CACJ;AACH,CAAC,CAAC,CAAC","ignoreList":[]}

package/dist/unstable/httpapi/HttpApiScalar.d.ts

@@ -12,7 +12,10 @@ export type ScalarThemeId = "alternate" | "default" | "moon" | "purple" | "solar
 /**
  * Configuration passed to the embedded Scalar API reference UI.
  *
- * @see https://github.com/scalar/scalar/blob/main/documentation/configuration.md
+ * **Details**
+ *
+ * This configuration follows Scalar's API reference configuration:
+ * https://github.com/scalar/scalar/blob/main/documentation/configuration.md
  *
  * @category models
  * @since 4.0.0

package/dist/unstable/httpapi/HttpApiScalar.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"HttpApiScalar.d.ts","sourceRoot":"","sources":["../../../src/unstable/httpapi/HttpApiScalar.ts"],"names":[],"mappings":"AAuBA,OAAO,KAAK,KAAK,KAAK,MAAM,gBAAgB,CAAA;AAC5C,OAAO,KAAK,UAAU,MAAM,uBAAuB,CAAA;AAEnD,OAAO,KAAK,KAAK,OAAO,MAAM,cAAc,CAAA;AAC5C,OAAO,KAAK,KAAK,YAAY,MAAM,mBAAmB,CAAA;AAKtD;;;;;GAKG;AACH,MAAM,MAAM,aAAa,GACrB,WAAW,GACX,SAAS,GACT,MAAM,GACN,QAAQ,GACR,WAAW,GACX,YAAY,GACZ,QAAQ,GACR,QAAQ,GACR,MAAM,GACN,WAAW,GACX,WAAW,GACX,MAAM,CAAA;AAEV;;;;;;;GAOG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,+CAA+C;IAC/C,KAAK,CAAC,EAAE,aAAa,CAAA;IACrB,2CAA2C;IAC3C,MAAM,CAAC,EAAE,QAAQ,GAAG,SAAS,CAAA;IAC7B,gDAAgD;IAChD,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,kCAAkC;IAClC,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB;;;;OAIG;IACH,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB;;;;OAIG;IACH,qBAAqB,CAAC,EAAE,OAAO,CAAA;IAC/B;;;;OAIG;IACH,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB,4DAA4D;IAC5D,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,mEAAmE;IACnE,kBAAkB,CAAC,EAAE,MAAM,GAAG,OAAO,CAAA;IACrC,2CAA2C;IAC3C,kBAAkB,CAAC,EAAE,OAAO,CAAA;IAC5B;;;;;;;;;;OAUG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,yCAAyC;IACzC,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB;;;;;;;;;;;;;;;;OAgBG;IACH,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB;;;;;;;;OAQG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAA;IAC1B;;;;;OAKG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAA;IAC5B;;;;OAIG;IACH,eAAe,CAAC,EAAE,OAAO,CAAA;CAC1B,CAAA;AA4DD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,KAAK,GAAI,EAAE,SAAS,MAAM,EAAE,MAAM,SAAS,YAAY,CAAC,GAAG,EACtE,KAAK,OAAO,CAAC,OAAO,CAAC,EAAE,EAAE,MAAM,CAAC,EAChC,UAAU;IACR,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,MAAM,EAAE,GAAG,SAAS,CAAA;IACxC,QAAQ,CAAC,MAAM,CAAC,EAAE,YAAY,CAAA;CAC/B,GAAG,SAAS,KACZ,KAAK,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,EAAE,UAAU,CAAC,UAAU,CAW7C,CAAA;AAEL;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,QAAQ,GAAI,EAAE,SAAS,MAAM,EAAE,MAAM,SAAS,YAAY,CAAC,GAAG,EACzE,KAAK,OAAO,CAAC,OAAO,CAAC,EAAE,EAAE,MAAM,CAAC,EAChC,UAAU;IACR,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,MAAM,EAAE,GAAG,SAAS,CAAA;IACxC,QAAQ,CAAC,MAAM,CAAC,EAAE,YAAY,CAAA;IAC9B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CACtC,GAAG,SAAS,KACZ,KAAK,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,EAAE,UAAU,CAAC,UAAU,CAW7C,CAAA"}
+{"version":3,"file":"HttpApiScalar.d.ts","sourceRoot":"","sources":["../../../src/unstable/httpapi/HttpApiScalar.ts"],"names":[],"mappings":"AAmCA,OAAO,KAAK,KAAK,KAAK,MAAM,gBAAgB,CAAA;AAC5C,OAAO,KAAK,UAAU,MAAM,uBAAuB,CAAA;AAEnD,OAAO,KAAK,KAAK,OAAO,MAAM,cAAc,CAAA;AAC5C,OAAO,KAAK,KAAK,YAAY,MAAM,mBAAmB,CAAA;AAKtD;;;;;GAKG;AACH,MAAM,MAAM,aAAa,GACrB,WAAW,GACX,SAAS,GACT,MAAM,GACN,QAAQ,GACR,WAAW,GACX,YAAY,GACZ,QAAQ,GACR,QAAQ,GACR,MAAM,GACN,WAAW,GACX,WAAW,GACX,MAAM,CAAA;AAEV;;;;;;;;;;GAUG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,+CAA+C;IAC/C,KAAK,CAAC,EAAE,aAAa,CAAA;IACrB,2CAA2C;IAC3C,MAAM,CAAC,EAAE,QAAQ,GAAG,SAAS,CAAA;IAC7B,gDAAgD;IAChD,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,kCAAkC;IAClC,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB;;;;OAIG;IACH,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB;;;;OAIG;IACH,qBAAqB,CAAC,EAAE,OAAO,CAAA;IAC/B;;;;OAIG;IACH,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB,4DAA4D;IAC5D,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,mEAAmE;IACnE,kBAAkB,CAAC,EAAE,MAAM,GAAG,OAAO,CAAA;IACrC,2CAA2C;IAC3C,kBAAkB,CAAC,EAAE,OAAO,CAAA;IAC5B;;;;;;;;;;OAUG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,yCAAyC;IACzC,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB;;;;;;;;;;;;;;;;OAgBG;IACH,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB;;;;;;;;OAQG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAA;IAC1B;;;;;OAKG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAA;IAC5B;;;;OAIG;IACH,eAAe,CAAC,EAAE,OAAO,CAAA;CAC1B,CAAA;AA4DD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,KAAK,GAAI,EAAE,SAAS,MAAM,EAAE,MAAM,SAAS,YAAY,CAAC,GAAG,EACtE,KAAK,OAAO,CAAC,OAAO,CAAC,EAAE,EAAE,MAAM,CAAC,EAChC,UAAU;IACR,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,MAAM,EAAE,GAAG,SAAS,CAAA;IACxC,QAAQ,CAAC,MAAM,CAAC,EAAE,YAAY,CAAA;CAC/B,GAAG,SAAS,KACZ,KAAK,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,EAAE,UAAU,CAAC,UAAU,CAW7C,CAAA;AAEL;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,QAAQ,GAAI,EAAE,SAAS,MAAM,EAAE,MAAM,SAAS,YAAY,CAAC,GAAG,EACzE,KAAK,OAAO,CAAC,OAAO,CAAC,EAAE,EAAE,MAAM,CAAC,EAChC,UAAU;IACR,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,MAAM,EAAE,GAAG,SAAS,CAAA;IACxC,QAAQ,CAAC,MAAM,CAAC,EAAE,YAAY,CAAA;IAC9B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CACtC,GAAG,SAAS,KACZ,KAAK,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,EAAE,UAAU,CAAC,UAAU,CAW7C,CAAA"}

package/dist/unstable/httpapi/HttpApiScalar.js

@@ -1,22 +1,34 @@
 /**
- * The `HttpApiScalar` module mounts an interactive Scalar API reference for a
- * declarative `HttpApi`.
+ * Scalar documentation UI for declarative `HttpApi` contracts.
  *
- * 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`.
+ * Use this module to mount a browser-based API reference on an `HttpRouter`
+ * without writing or storing a separate OpenAPI file. The route renders an HTML
+ * page containing the OpenAPI document produced from the supplied `HttpApi` and
+ * boots Scalar in the browser.
  *
- * 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.
+ * ## 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
  */

package/dist/unstable/httpapi/HttpApiScalar.js.map

@@ -1 +1 @@
-{"version":3,"file":"HttpApiScalar.js","names":["Effect","HttpRouter","HttpServerResponse","Html","internal","OpenApi","makeHandler","options","spec","fromApi","api","scalarConfig","_integration","scalar","response","html","escape","info","title","description","escapeJson","source","_tag","version","succeed","layer","use","fnUntraced","router","handler","javascript","add","path","layerCdn"],"sources":["../../../src/unstable/httpapi/HttpApiScalar.ts"],"sourcesContent":[null],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;AAsBA,OAAO,KAAKA,MAAM,MAAM,iBAAiB;AAEzC,OAAO,KAAKC,UAAU,MAAM,uBAAuB;AACnD,OAAO,KAAKC,kBAAkB,MAAM,+BAA+B;AAGnE,OAAO,KAAKC,IAAI,MAAM,oBAAoB;AAC1C,OAAO,KAAKC,QAAQ,MAAM,6BAA6B;AACvD,OAAO,KAAKC,OAAO,MAAM,cAAc;AAkIvC,MAAMC,WAAW,GAAwDC,OAIxE,IAAI;EACH,MAAMC,IAAI,GAAGH,OAAO,CAACI,OAAO,CAACF,OAAO,CAACG,GAAG,CAAC;EACzC,MAAMC,YAAY,GAAG;IACnBC,YAAY,EAAE,MAAM;IACpB,GAAGL,OAAO,CAACM;GACZ;EACD,MAAMC,QAAQ,GAAGZ,kBAAkB,CAACa,IAAI,CAAC;;;;aAI9BZ,IAAI,CAACa,MAAM,CAACR,IAAI,CAACS,IAAI,CAACC,KAAK,CAAC;MAErC,CAACV,IAAI,CAACS,IAAI,CAACE,WAAW,GAClB,EAAE,GACF,qCAAqChB,IAAI,CAACa,MAAM,CAACR,IAAI,CAACS,IAAI,CAACE,WAAW,CAAC,KAC7E;MAEE,CAACX,IAAI,CAACS,IAAI,CAACE,WAAW,GAClB,EAAE,GACF,wCAAwChB,IAAI,CAACa,MAAM,CAACR,IAAI,CAACS,IAAI,CAACE,WAAW,CAAC,KAChF;;;;;;;QAOMhB,IAAI,CAACiB,UAAU,CAACZ,IAAI,CAAC;;;wFAG2DL,IAAI,CAACiB,UAAU,CAACT,YAAY,CAAC;;MAGjHJ,OAAO,CAACc,MAAM,CAACC,IAAI,KAAK,KAAK,GACzB,gBAAgB,sDAChBf,OAAO,CAACc,MAAM,CAACE,OAAO,IAAI,QAC5B,iCAAiC,yBAAyB,GACxD,WAAWhB,OAAO,CAACc,MAAM,CAACA,MAAM,WACtC;;QAEM,CAAC;EACP,OAAOrB,MAAM,CAACwB,OAAO,CAACV,QAAQ,CAAC;AACjC,CAAC;AAED;;;;;;;;;;;AAWA,OAAO,MAAMW,KAAK,GAAGA,CACnBf,GAAgC,EAChCH,OAGa,KAEbN,UAAU,CAACyB,GAAG,CAAC1B,MAAM,CAAC2B,UAAU,CAAC,WAAUC,MAAM;EAC/C,MAAMC,OAAO,GAAGvB,WAAW,CAAC;IAC1BI,GAAG;IACHW,MAAM,EAAE;MACNC,IAAI,EAAE,QAAQ;MACdD,MAAM,EAAEjB,QAAQ,CAAC0B;KAClB;IACDjB,MAAM,EAAEN,OAAO,EAAEM;GAClB,CAAC;EACF,OAAOe,MAAM,CAACG,GAAG,CAAC,KAAK,EAAExB,OAAO,EAAEyB,IAAI,IAAI,OAAO,EAAEH,OAAO,CAAC;AAC7D,CAAC,CAAC,CAAC;AAEL;;;;;;;;;;;;AAYA,OAAO,MAAMI,QAAQ,GAAGA,CACtBvB,GAAgC,EAChCH,OAIa,KAEbN,UAAU,CAACyB,GAAG,CAAC1B,MAAM,CAAC2B,UAAU,CAAC,WAAUC,MAAM;EAC/C,MAAMC,OAAO,GAAGvB,WAAW,CAAC;IAC1BI,GAAG;IACHW,MAAM,EAAE;MACNC,IAAI,EAAE,KAAK;MACXC,OAAO,EAAEhB,OAAO,EAAEgB;KACnB;IACDV,MAAM,EAAEN,OAAO,EAAEM;GAClB,CAAC;EACF,OAAOe,MAAM,CAACG,GAAG,CAAC,KAAK,EAAExB,OAAO,EAAEyB,IAAI,IAAI,OAAO,EAAEH,OAAO,CAAC;AAC7D,CAAC,CAAC,CAAC","ignoreList":[]}
+{"version":3,"file":"HttpApiScalar.js","names":["Effect","HttpRouter","HttpServerResponse","Html","internal","OpenApi","makeHandler","options","spec","fromApi","api","scalarConfig","_integration","scalar","response","html","escape","info","title","description","escapeJson","source","_tag","version","succeed","layer","use","fnUntraced","router","handler","javascript","add","path","layerCdn"],"sources":["../../../src/unstable/httpapi/HttpApiScalar.ts"],"sourcesContent":[null],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAkCA,OAAO,KAAKA,MAAM,MAAM,iBAAiB;AAEzC,OAAO,KAAKC,UAAU,MAAM,uBAAuB;AACnD,OAAO,KAAKC,kBAAkB,MAAM,+BAA+B;AAGnE,OAAO,KAAKC,IAAI,MAAM,oBAAoB;AAC1C,OAAO,KAAKC,QAAQ,MAAM,6BAA6B;AACvD,OAAO,KAAKC,OAAO,MAAM,cAAc;AAqIvC,MAAMC,WAAW,GAAwDC,OAIxE,IAAI;EACH,MAAMC,IAAI,GAAGH,OAAO,CAACI,OAAO,CAACF,OAAO,CAACG,GAAG,CAAC;EACzC,MAAMC,YAAY,GAAG;IACnBC,YAAY,EAAE,MAAM;IACpB,GAAGL,OAAO,CAACM;GACZ;EACD,MAAMC,QAAQ,GAAGZ,kBAAkB,CAACa,IAAI,CAAC;;;;aAI9BZ,IAAI,CAACa,MAAM,CAACR,IAAI,CAACS,IAAI,CAACC,KAAK,CAAC;MAErC,CAACV,IAAI,CAACS,IAAI,CAACE,WAAW,GAClB,EAAE,GACF,qCAAqChB,IAAI,CAACa,MAAM,CAACR,IAAI,CAACS,IAAI,CAACE,WAAW,CAAC,KAC7E;MAEE,CAACX,IAAI,CAACS,IAAI,CAACE,WAAW,GAClB,EAAE,GACF,wCAAwChB,IAAI,CAACa,MAAM,CAACR,IAAI,CAACS,IAAI,CAACE,WAAW,CAAC,KAChF;;;;;;;QAOMhB,IAAI,CAACiB,UAAU,CAACZ,IAAI,CAAC;;;wFAG2DL,IAAI,CAACiB,UAAU,CAACT,YAAY,CAAC;;MAGjHJ,OAAO,CAACc,MAAM,CAACC,IAAI,KAAK,KAAK,GACzB,gBAAgB,sDAChBf,OAAO,CAACc,MAAM,CAACE,OAAO,IAAI,QAC5B,iCAAiC,yBAAyB,GACxD,WAAWhB,OAAO,CAACc,MAAM,CAACA,MAAM,WACtC;;QAEM,CAAC;EACP,OAAOrB,MAAM,CAACwB,OAAO,CAACV,QAAQ,CAAC;AACjC,CAAC;AAED;;;;;;;;;;;AAWA,OAAO,MAAMW,KAAK,GAAGA,CACnBf,GAAgC,EAChCH,OAGa,KAEbN,UAAU,CAACyB,GAAG,CAAC1B,MAAM,CAAC2B,UAAU,CAAC,WAAUC,MAAM;EAC/C,MAAMC,OAAO,GAAGvB,WAAW,CAAC;IAC1BI,GAAG;IACHW,MAAM,EAAE;MACNC,IAAI,EAAE,QAAQ;MACdD,MAAM,EAAEjB,QAAQ,CAAC0B;KAClB;IACDjB,MAAM,EAAEN,OAAO,EAAEM;GAClB,CAAC;EACF,OAAOe,MAAM,CAACG,GAAG,CAAC,KAAK,EAAExB,OAAO,EAAEyB,IAAI,IAAI,OAAO,EAAEH,OAAO,CAAC;AAC7D,CAAC,CAAC,CAAC;AAEL;;;;;;;;;;;;AAYA,OAAO,MAAMI,QAAQ,GAAGA,CACtBvB,GAAgC,EAChCH,OAIa,KAEbN,UAAU,CAACyB,GAAG,CAAC1B,MAAM,CAAC2B,UAAU,CAAC,WAAUC,MAAM;EAC/C,MAAMC,OAAO,GAAGvB,WAAW,CAAC;IAC1BI,GAAG;IACHW,MAAM,EAAE;MACNC,IAAI,EAAE,KAAK;MACXC,OAAO,EAAEhB,OAAO,EAAEgB;KACnB;IACDV,MAAM,EAAEN,OAAO,EAAEM;GAClB,CAAC;EACF,OAAOe,MAAM,CAACG,GAAG,CAAC,KAAK,EAAExB,OAAO,EAAEyB,IAAI,IAAI,OAAO,EAAEH,OAAO,CAAC;AAC7D,CAAC,CAAC,CAAC","ignoreList":[]}

package/dist/unstable/httpapi/HttpApiSchema.d.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
  */
@@ -121,7 +124,7 @@ declare 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**
  *
@@ -153,8 +156,7 @@ export declare const Empty: (code: number) => Schema.Void;
 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
@@ -169,8 +171,7 @@ export declare const NoContent: NoContent;
 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
@@ -185,8 +186,7 @@ export declare const Created: Created;
 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/dist/unstable/httpapi/HttpApiSchema.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"HttpApiSchema.d.ts","sourceRoot":"","sources":["../../../src/unstable/httpapi/HttpApiSchema.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"HttpApiSchema.d.ts","sourceRoot":"","sources":["../../../src/unstable/httpapi/HttpApiSchema.ts"],"names":[],"mappings":"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"}

package/dist/unstable/httpapi/HttpApiSchema.js

@@ -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
  */
@@ -126,24 +129,21 @@ export function status(code) {
  */
 export const Empty = code => Schema.Void.pipe(status(code));
 /**
- * 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
  */
 export const NoContent = /*#__PURE__*/Empty(204);
 /**
- * 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
  */
 export const Created = /*#__PURE__*/Empty(201);
 /**
- * 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