@dunx/http 2.4.0 → 3.0.0

package/dist/internal.d.ts

@@ -0,0 +1,36 @@
+/**
+ * What the framework calls on itself. Every symbol here is still reachable from
+ * the package barrel, deprecated, and leaves it in 4.0.
+ *
+ * The barrel is a semver promise, and 173 of them was more than this package
+ * meant to make. What stays public is the surface an app writes against:
+ * decorators, options, contracts, errors, modules and the metadata helpers a
+ * user's own guard reads. What is here is route-table construction, the
+ * middleware fold, the relay codec and the discovery readers - things
+ * `@dunx/dashboard`, `@dunx/mcp` and `@dunx/openapi` need and an app does not.
+ *
+ * No stability promise attaches to this subpath.
+ */
+export { discoverRoutes, joinPath, type DiscoveredRoute, } from './route/discover.js';
+export { defaultStatusFor, type DefaultStatus, type RouteMeta, } from './route/marker.js';
+export { guardsOf } from './route/metadata.js';
+export { gatewaysOf, routesOf, type GatewayHandler, type GatewayNode, type RouteInputs, type RouteNode, } from './inspect.js';
+export { buildContext } from './server/context.js';
+export { preflight, withCors } from './server/cors.js';
+export { isErrorFilter, toErrorMapper } from './server/errors.js';
+export { compose } from './server/middleware.js';
+export { assertNoCollisions, assertNoGatewayCollisions, buildRoutes, withUpgradeRoutes, type BunRoutes, type GuardResolver, type RouteMethod, type ServeRoutes, } from './server/routes.js';
+export { normalizePrefix } from './static/options.js';
+export { negotiate } from './compression/negotiate.js';
+export { isCompressibleType } from './compression/options.js';
+export { buildWebSocket, type UpgradeHandler, type WebSocketRuntime, } from './ws/adapter.js';
+export { discoverGateway, discoverGateways, normalizePath, type DiscoveredGateway, type DiscoveredHandler, type Invoke, } from './ws/discover.js';
+export { decode, encode } from './ws/envelope.js';
+export { composeSocket, observe } from './ws/middleware.js';
+export { HandlerKind, isGateway, type HandlerMeta } from './ws/marker.js';
+export { defaultRelayUrl } from './ws/redis-relay.js';
+export { decodeRelay, encodeRelay, type RelayFrame, type RelayPhase, } from './ws/relay.js';
+export { buildGateways, buildRuntime, type GatewayRuntime, } from './ws/runtime.js';
+export { HiddenHealthController } from './health/controller.js';
+export { backoffDelay, executeWithRetry, isRetryableStatus, retryAfterMs, } from './client/retry.js';
+export { isJsonBody, isPlainObject, safeStringify } from './client/json.js';

package/dist/internal.js

@@ -0,0 +1,89 @@
+// @bun
+import {
+  HandlerKind,
+  HiddenHealthController,
+  assertNoCollisions,
+  assertNoGatewayCollisions,
+  backoffDelay,
+  buildContext,
+  buildGateways,
+  buildRoutes,
+  buildRuntime,
+  buildWebSocket,
+  compose,
+  composeSocket,
+  decode,
+  decodeRelay,
+  defaultRelayUrl,
+  defaultStatusFor,
+  discoverGateway,
+  discoverGateways,
+  discoverRoutes,
+  encode,
+  encodeRelay,
+  executeWithRetry,
+  gatewaysOf,
+  guardsOf,
+  isCompressibleType,
+  isErrorFilter,
+  isGateway,
+  isJsonBody,
+  isPlainObject,
+  isRetryableStatus,
+  joinPath,
+  negotiate,
+  normalizePath,
+  normalizePrefix,
+  observe,
+  preflight,
+  retryAfterMs,
+  routesOf,
+  safeStringify,
+  toErrorMapper,
+  withCors,
+  withUpgradeRoutes
+} from "./chunk-ywdpxbkf.js";
+export {
+  HandlerKind,
+  HiddenHealthController,
+  assertNoCollisions,
+  assertNoGatewayCollisions,
+  backoffDelay,
+  buildContext,
+  buildGateways,
+  buildRoutes,
+  buildRuntime,
+  buildWebSocket,
+  compose,
+  composeSocket,
+  decode,
+  decodeRelay,
+  defaultRelayUrl,
+  defaultStatusFor,
+  discoverGateway,
+  discoverGateways,
+  discoverRoutes,
+  encode,
+  encodeRelay,
+  executeWithRetry,
+  gatewaysOf,
+  guardsOf,
+  isCompressibleType,
+  isErrorFilter,
+  isGateway,
+  isJsonBody,
+  isPlainObject,
+  isRetryableStatus,
+  joinPath,
+  negotiate,
+  normalizePath,
+  normalizePrefix,
+  observe,
+  preflight,
+  retryAfterMs,
+  routesOf,
+  safeStringify,
+  toErrorMapper,
+  withCors,
+  withUpgradeRoutes
+};

package/dist/route/decorators.d.ts

@@ -1,10 +1,10 @@
 import { type RoutePath } from './marker.js';
-import type { Input, RouteSchemas } from './schema.js';
+import type { Input, Returns, RouteSchemas } from './schema.js';
 type ControllerTarget = abstract new (...args: never[]) => object;
 export declare const Controller: (prefix?: string) => <T extends ControllerTarget>(target: T) => T;
-export declare const Get: <const O extends RouteSchemas>(path?: RoutePath, options?: O) => <M extends (input: Input<O>) => unknown>(value: M, _context: ClassMethodDecoratorContext) => M;
-export declare const Post: <const O extends RouteSchemas>(path?: RoutePath, options?: O) => <M extends (input: Input<O>) => unknown>(value: M, _context: ClassMethodDecoratorContext) => M;
-export declare const Put: <const O extends RouteSchemas>(path?: RoutePath, options?: O) => <M extends (input: Input<O>) => unknown>(value: M, _context: ClassMethodDecoratorContext) => M;
-export declare const Patch: <const O extends RouteSchemas>(path?: RoutePath, options?: O) => <M extends (input: Input<O>) => unknown>(value: M, _context: ClassMethodDecoratorContext) => M;
-export declare const Delete: <const O extends RouteSchemas>(path?: RoutePath, options?: O) => <M extends (input: Input<O>) => unknown>(value: M, _context: ClassMethodDecoratorContext) => M;
+export declare const Get: <const O extends RouteSchemas>(path?: RoutePath, options?: O | undefined) => <H extends (input: Input<O>) => Returns<O, "GET">>(value: H, _context: ClassMethodDecoratorContext) => H;
+export declare const Post: <const O extends RouteSchemas>(path?: RoutePath, options?: O | undefined) => <H extends (input: Input<O>) => Returns<O, "POST">>(value: H, _context: ClassMethodDecoratorContext) => H;
+export declare const Put: <const O extends RouteSchemas>(path?: RoutePath, options?: O | undefined) => <H extends (input: Input<O>) => Returns<O, "PUT">>(value: H, _context: ClassMethodDecoratorContext) => H;
+export declare const Patch: <const O extends RouteSchemas>(path?: RoutePath, options?: O | undefined) => <H extends (input: Input<O>) => Returns<O, "PATCH">>(value: H, _context: ClassMethodDecoratorContext) => H;
+export declare const Delete: <const O extends RouteSchemas>(path?: RoutePath, options?: O | undefined) => <H extends (input: Input<O>) => Returns<O, "DELETE">>(value: H, _context: ClassMethodDecoratorContext) => H;
 export {};

package/dist/route/marker.d.ts

@@ -1,5 +1,18 @@
+import { HttpStatusCode } from '../server/status.js';
 import type { RouteSchemas } from './schema.js';
 export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+/**
+ * The success status a route answers with when `options.status` is absent.
+ * `buildRoutes` and `@dunx/openapi`'s `statusOf` both read it, so the rule is
+ * stated once rather than in each of them.
+ */
+export declare const defaultStatusFor: (method: HttpMethod) => number;
+/**
+ * The type-level twin of {@link defaultStatusFor}, derived from the same constants
+ * so the two cannot drift. `Returns` needs it to know which `response` entry a
+ * handler is being held to.
+ */
+export type DefaultStatus<M extends HttpMethod> = M extends 'POST' ? typeof HttpStatusCode.CREATED : typeof HttpStatusCode.OK;
 /**
  * A literal path, or a thunk read at **discovery** rather than at decoration.
  *

package/dist/route/metadata.d.ts

@@ -31,17 +31,14 @@ export declare const UNMATCHED: MetaKey<boolean>;
 export declare const Roles: (...roles: readonly string[]) => <F extends object>(target: F) => F;
 export declare const Public: () => <F extends object>(target: F) => F;
 /**
- * Route, but not documented. Valid on a method or on a class.
+ * Route, but not documented. Valid on a method or a class.
  *
- * The motivating case is a handler mounted on a wildcard: `@dunx/auth` routes
- * `<basePath>/*` to Better Auth's own handler, which is real and has to be
- * routed, but `*` is not an OpenAPI path template - so documenting it produced an
- * invalid entry named after an internal class, next to the 45 paths
- * `betterAuthDocument` describes properly.
+ * The motivating case is a wildcard mount: `@dunx/auth` routes `<basePath>/*` to
+ * better-auth's handler, and `*` is not an OpenAPI path template, so documenting
+ * it produced an invalid entry named after an internal class.
  *
- * It lives here rather than in `@dunx/openapi` because `@dunx/auth` must not
- * depend on the documentation package to say a route is undocumented, and this is
- * where the rest of the route metadata already is.
+ * Here rather than in `@dunx/openapi` so `@dunx/auth` need not depend on the
+ * documentation package to say a route is undocumented.
  */
 export declare const ApiHidden: () => <F extends object>(target: F) => F;
 /**

package/dist/route/schema.d.ts

@@ -1,10 +1,9 @@
 import type { BunRequest } from 'bun';
+import type { DefaultStatus, HttpMethod } from './marker.js';
 /**
- * Standard Schema v1, restated rather than depended on. The spec is an
- * *interface*, not a runtime: `@standard-schema/spec` ships nothing but these
- * declarations, so restating them costs one file and keeps `@dunx/http` at zero
- * dependencies. Zod 4, Valibot and ArkType already satisfy this shape, so any of
- * them drops straight into a route's options.
+ * Standard Schema v1, restated rather than depended on: the spec is an interface,
+ * so restating it keeps `@dunx/http` at zero dependencies. Zod 4, Valibot and
+ * ArkType all satisfy this shape already.
  */
 export interface StandardSchemaV1<In = unknown, Out = In> {
     readonly '~standard': {
@@ -34,11 +33,8 @@ export interface StandardSchemaIssue {
 /** The validated output of a schema - `InferOutput<typeof CreateNote>` is `Note`. */
 export type InferOutput<S> = S extends StandardSchemaV1<unknown, infer Out> ? Out : never;
 /**
- * A JSON Schema, as JSON. OpenAPI 3.1 embeds draft 2020-12 verbatim.
- *
- * Declared here rather than in `@dunx/openapi` because {@link RouteSchemas} names
- * it and that package depends on this one, so this is the lowest common owner.
- * `@dunx/openapi` re-exports it.
+ * A JSON Schema, as JSON. Declared here rather than in `@dunx/openapi` because
+ * {@link RouteSchemas} names it and that package depends on this one.
  */
 export type JsonSchema = Readonly<Record<string, unknown>>;
 /**
@@ -54,9 +50,7 @@ export interface RouteSchemas {
     readonly status?: number;
     /**
      * What the route answers with, keyed by status code, in the same Standard
-     * Schema the request side takes - so a response schema with a `.meta({ id })`
-     * hoists into `components/schemas` exactly as a request body does, and there is
-     * one contract for both directions.
+     * Schema the request side takes.
      *
      * ```ts
      * const one = {
@@ -65,17 +59,9 @@ export interface RouteSchemas {
      * } as const satisfies RouteSchemas;
      * ```
      *
-     * **Never validated.** It documents the response; it does not enforce it.
-     * Running a validation pass over every response body would be a per-request
-     * cost paid for a documentation feature, which is the wrong trade - the
-     * handler's own return type is what checks the answer, at compile time and for
-     * free. Nothing in the request path reads this key.
-     *
-     * A plain {@link JsonSchema} is accepted here too, and only here: a JSON Schema
-     * needs no conversion, so documenting a response costs no validator. `$id` names
-     * it, hoisting it into `components/schemas` the way `.meta({ id })` does for a
-     * zod schema. `body`, `query` and `params` still take a Standard Schema, because
-     * those are parsed.
+     * Never validated at runtime, checked at compile time against the success
+     * status. A plain {@link JsonSchema} is accepted here and only here, and `$id`
+     * hoists it into `components/schemas`.
      *
      * ```ts
      * response: {
@@ -83,14 +69,14 @@ export interface RouteSchemas {
      * }
      * ```
      */
-    readonly response?: Readonly<Record<number, StandardSchemaV1 | JsonSchema>>;
+    readonly response?: ResponseMap;
 }
+/** `response` keyed by status code. Named so {@link Returns} can constrain it. */
+export type ResponseMap = Readonly<Record<number, StandardSchemaV1 | JsonSchema>>;
 /**
  * The handler's parameter type, derived from its own options object. It has to be
- * written out - a standard method decorator can *check* a parameter's type but
- * cannot contextually type an unannotated one
- * (docs/architecture/constraints.md) - but every field type still comes from the schemas, so nothing
- * is declared twice:
+ * written out: a standard method decorator can check a parameter's type but not
+ * contextually type an unannotated one (docs/architecture/constraints.md).
  *
  * ```ts
  * const createNote = { body: CreateNote, status: HttpStatusCode.CREATED } as const;
@@ -118,6 +104,49 @@ export type Input<O extends RouteSchemas> = {
 } ? {
     readonly params: InferOutput<P>;
 } : unknown);
+/**
+ * The status a handler's return type is held to: an explicit `options.status`,
+ * else the verb's default. Widened to `number` without `as const`, which turns
+ * the check off rather than misapplying it.
+ */
+type SuccessStatus<O extends RouteSchemas, M extends HttpMethod> = O extends {
+    status: infer S extends number;
+} ? S : DefaultStatus<M>;
+/**
+ * A plain {@link JsonSchema} carries no type to infer, so it becomes `unknown` and
+ * absorbs whatever the handler returns. That is the escape hatch for a response
+ * whose shape no schema value describes.
+ */
+type Declared<S> = [InferOutput<S>] extends [never] ? unknown : Serialised<InferOutput<S>>;
+/**
+ * The declared shape as JSON will present it: the same shape with every array made
+ * readonly. `z.array()` infers a mutable `T[]`, so a method correctly returning
+ * `readonly User[]` would fail against a document it satisfies, and mutability
+ * does not survive `Response.json` anyway.
+ *
+ * Only arrays need it. The object branch reaches nested ones; functions are
+ * returned untouched, since mapping over one discards its call signature.
+ */
+type Serialised<T> = T extends readonly (infer E)[] ? readonly Serialised<E>[] : T extends (...args: never[]) => unknown ? T : T extends object ? {
+    readonly [K in keyof T]: Serialised<T[K]>;
+} : T;
+/**
+ * What a handler may return, given its options object and its verb. The return
+ * half of the guarantee `Input<O>` gives the parameter, so `response: { 200: User }`
+ * stops being documentation a handler can contradict.
+ *
+ * `Response` is always allowed, and so is a promise of either. Nothing is checked
+ * when the success status has no `response` entry.
+ */
+export type Returns<O extends RouteSchemas, M extends HttpMethod> = SuccessBody<O, M> | Response | Promise<SuccessBody<O, M> | Response>;
+/**
+ * `infer R extends ResponseMap` is required: without it the narrowed `O` is
+ * `{ response: R } & O`, whose `response` no longer satisfies `RouteSchemas`, and
+ * `SuccessStatus<O, M>` fails with `TS2344`.
+ */
+type SuccessBody<O extends RouteSchemas, M extends HttpMethod> = O extends {
+    response: infer R extends ResponseMap;
+} ? SuccessStatus<O, M> extends keyof R ? Declared<R[SuccessStatus<O, M>]> : unknown : unknown;
 /** What the framework actually hands a handler; `Input<O>` is its typed view. */
 export interface RouteInput {
     readonly req: BunRequest;
@@ -125,3 +154,4 @@ export interface RouteInput {
     readonly query?: unknown;
     readonly params?: unknown;
 }
+export {};

package/dist/server/application.d.ts

@@ -16,111 +16,62 @@ export interface HttpOptions extends AppOptions {
     /** Resolved from the container, so middleware can inject(). */
     readonly middleware?: readonly Ctor<Middleware>[];
     /**
-     * Replaces the default mapper.
-     *
-     * A bare `ErrorMapper` function, or an `ErrorFilter` **class** - which is the one
-     * to prefer, because a class is resolved from the container and can therefore
-     * inject the `Logger` or the config a real filter needs. A mapper cannot; dunx's
-     * own default has to be curried over its logger for exactly that reason.
-     *
-     * A filter with dependencies needs them bindable, the same rule `middleware`
-     * entries follow; one with none self-binds and needs no `providers` entry.
+     * Replaces the default mapper. Prefer an `ErrorFilter` class over a bare
+     * `ErrorMapper`: a class is resolved from the container and can inject.
      */
     readonly onError?: ErrorHandler;
     /**
-     * One structured entry per request, on by default. `false` removes it; an
-     * options object tunes what it records. See {@link RequestLoggingMiddleware}.
-     *
-     * It is the **outermost** middleware, ahead of anything `middleware` declares,
-     * so a request rejected by a guard is still logged with the status it got.
+     * One structured entry per request, on by default and outermost, so a request
+     * a guard rejected is still logged with the status it got.
+     * See {@link RequestLoggingMiddleware}.
      */
     readonly requestLogging?: boolean | RequestLoggingOptions;
     /**
-     * One entry at `listen()` naming every route and gateway the process serves. On
-     * by default, because it is the answer to "is my route registered" and a service
-     * that logs nothing at boot cannot answer it from production.
-     *
-     * `false` removes it. Separate from `requestLogging` rather than sharing its
-     * switch: one is per request and one is per process, and silencing the noisy one
-     * is not a reason to lose the quiet one. `@dunx/testing` defaults it off, for the
-     * same reason it defaults request logging off.
+     * One entry at `listen()` naming every route and gateway served. On by default,
+     * and switched separately from `requestLogging`: one is per process, the other
+     * per request. `@dunx/testing` defaults it off.
      */
     readonly bootLogging?: boolean;
-    /**
-     * Bun's `websocket` options, plus where a throwing handler goes. Server-wide, so
-     * they live here next to `middleware` rather than on a module: gateways
-     * themselves are declared in `@Module({ providers })`.
-     */
+    /** Bun's `websocket` options, plus where a throwing handler goes. Server-wide;
+     * gateways themselves are declared in `@Module({ providers })`. */
     readonly websocket?: SocketOptions;
     /**
-     * The socket half of `middleware`, resolved from the container the same way.
-     *
-     * Each entry wraps every dispatched gateway handler - open, each named message,
-     * the catch-all, close, drain, ping and pong - the way an HTTP middleware wraps a
-     * route. `socketLogging`'s middleware runs outermost, ahead of anything here.
+     * The socket half of `middleware`. Each entry wraps every dispatched gateway
+     * handler; `socketLogging`'s runs outermost, ahead of anything here.
      */
     readonly socketMiddleware?: readonly Ctor<SocketMiddleware>[];
     /**
-     * One structured entry per socket frame, on by default at **`debug`**. `false`
-     * removes it; an options object tunes the level per event. See
-     * {@link SocketLoggingMiddleware}.
-     *
-     * `debug` rather than request logging's `info`, because a gateway can take a
-     * frame per connection per tick. The default `ConsoleLogger` threshold is
-     * `info`, so this writes nothing until an app lowers its level or names a louder
-     * one here.
-     *
-     * Installing it also takes `SocketOptions.onError`'s `console.error` default out
-     * of the way: a middleware wraps the handler, so the failure is already reported
-     * through the `Logger` with the gateway and the event on it.
+     * One structured entry per socket frame, on by default at `debug` - a gateway
+     * can take a frame per connection per tick, so it writes nothing until an app
+     * lowers its level. See {@link SocketLoggingMiddleware}.
      */
     readonly socketLogging?: boolean | SocketLoggingOptions;
     /**
-     * Multi-node websocket fan-out. Absent - the default - means `PubSub` publishes
-     * to this process only, which is exactly Bun's native pub/sub and costs nothing.
-     *
-     * `new RedisRelay({ url })` is the batteries-included one. Anything with a
-     * `publish` and a `subscribe` fits, including `@dunx/infra`'s `RedisConnection`,
-     * which has to come out of the container and so goes through
-     * `app.get(PubSub).relayThrough(...)` instead of this option.
+     * Multi-node websocket fan-out. Absent means `PubSub` publishes to this process
+     * only. Anything with `publish` and `subscribe` fits; one that has to come out
+     * of the container goes through `app.get(PubSub).relayThrough(...)` instead.
      */
     readonly relay?: PubSubRelay;
     /** The broker channel the relay carries frames on. @default 'dunx:ws' */
     readonly relayChannel?: string;
     /**
-     * How hard to retry a subscribe that failed. Same shape as
-     * `RelayOptions.resubscribe`: bounded, doubling, and on an unref'd timer, so a
-     * broker that never comes back cannot hold the process open.
-     *
-     * Here rather than only on `relayThrough` because reaching for that to set one
-     * option means giving up `relay` above entirely - the two conflict, and the
-     * second to run throws `PubSub already relays`.
+     * How hard to retry a failed subscribe. Bounded, doubling, on an unref'd timer,
+     * so a broker that never returns cannot hold the process open.
      */
     readonly relayResubscribe?: RelayOptions['resubscribe'];
     /**
-     * What an unmatched path looks like to global middleware.
-     *
-     * `'guarded'`, the default, gives the miss no route metadata, so a global guard
-     * refuses it and an anonymous caller gets that guard's status rather than a 404.
-     * That is deliberate: a 404 on a miss while every real path answers 401 tells a
-     * prober which paths exist.
-     *
-     * `'public'` reports the miss as `@Public()`, so a guard honouring that flag
-     * passes it through to the conventional 404. The request is still logged and
-     * still gets a request id either way, which is the whole reason the fallback
-     * runs the middleware at all.
-     *
-     * A guard can discriminate under either setting: `UNMATCHED` is set on the miss
-     * and no real route ever sets it.
+     * What an unmatched path looks like to global middleware. `'guarded'` gives the
+     * miss no route metadata, so a global guard refuses it and a prober cannot tell
+     * a 404 from a 401. `'public'` reports it as `@Public()` for a conventional 404.
+     * Either way `UNMATCHED` is set, which no real route sets.
      *
      * @default 'guarded'
      */
     readonly notFound?: 'guarded' | 'public';
 }
 /**
- * Everything below `listen()` configures the route table, which is built exactly
- * once - when the server binds. Calling any of them afterwards throws rather than
- * being quietly dropped.
+ * Everything below `listen()` configures the route table, built once when the
+ * server binds. Calling any of them afterwards throws.
  */
 export interface HttpApp extends App {
     /** Prefixes every discovered route. Last call wins. */
@@ -151,23 +102,16 @@ export declare class HttpApplication implements HttpApp {
     setting<K extends keyof AppSettings>(key: K): AppSettings[K];
     enableCors(options?: CorsOptions): this;
     clientIp(req: BunRequest): string | undefined;
-    /**
-     * The one `Bun.serve` call. A gateway's upgrade is a native `GET` route in the
-     * same table, so Bun's router - not a hand-written `fetch` fallback - is what
-     * matches an upgrade, and no `fetch` handler is needed at all.
-     */
+    /** The one `Bun.serve` call. A gateway's upgrade is a native `GET` route in the
+     * same table, so Bun's router matches it and no `fetch` handler is needed. */
     listen(port?: number): Promise<string>;
-    /**
-     * Delegated unchanged: the drain is the container's phase, and `shutdown()`
-     * runs it. Public so an operator can start draining without committing to a
-     * shutdown, which is what a readiness probe wants during a rolling deploy.
-     */
+    /** Public so an operator can start draining without committing to a shutdown,
+     * which is what a readiness probe wants during a rolling deploy. */
     drain(): Promise<void>;
     /**
-     * The four phases, in order, and **none of them is skipped because an earlier
-     * one failed**. A drain hook that threw used to abort this before `server.stop()`
-     * had run, so the port stayed open and `closed` never resolved; each failure is
-     * collected now and thrown once the whole teardown is over.
+     * Four phases in order, none skipped because an earlier one failed. A throwing
+     * drain hook used to abort before `server.stop()`, leaving the port open and
+     * `closed` unresolved; failures are collected and thrown at the end.
      */
     shutdown(): Promise<void>;
     enableShutdownHooks(signals?: readonly ShutdownSignal[], options?: ShutdownHookOptions): this;

package/dist/server/client-address.d.ts

@@ -4,20 +4,13 @@ export interface AddressSource {
     readonly trustProxy: boolean | number;
 }
 /**
- * The client's address, honouring the `'trust proxy'` setting.
+ * The client's address, honouring `'trust proxy'`. The address is counted from the
+ * right of `X-Forwarded-For` by the number of trusted hops, never from the left: a
+ * client can send anything, and only the entries a proxy appended carry weight.
  *
- * With the setting on, the address is read from `X-Forwarded-For` counting from
- * the right by the number of trusted hops, never from the left. A client can put
- * anything in the header it sends; only the entries a proxy appended carry any
- * weight, and there are exactly as many of those as there are proxies in front of
- * this server.
- *
- * Bound and exported by `HttpFactory`'s global wrapper module, so injecting it in a
- * middleware or controller needs no registration and `app.clientIp(req)` is the same
- * instance. That binding is not optional under module scoping: an unbound class
- * self-binds into whichever scope asks first, so a second module injecting it was a
- * boot error naming the first, and `listen()` could attach the server to an instance
- * nothing else held.
+ * Bound by `HttpFactory`'s global wrapper, which is not optional under module
+ * scoping - an unbound class self-binds into whichever scope asks first, so a
+ * second module injecting it was a boot error.
  */
 export declare class ClientAddress {
     of(req: BunRequest): string | undefined;

package/dist/server/errors.d.ts

@@ -1,14 +1,9 @@
 import { AppError, type Ctor, type Logger } from '@dunx/core';
 export interface HttpErrorOptions extends ErrorOptions {
     /**
-     * Headers the error response carries. `Retry-After` on a 429,
-     * `WWW-Authenticate` on a 401, `Allow` on a 405 - each of them part of the
-     * status rather than an extra, and none of them expressible by a throw before
-     * this existed.
-     *
-     * {@link errorMapper} copies them onto the response. An app that replaces the
-     * mapper has to read them itself, which is the same contract `status` and
-     * `message` already have.
+     * Headers the error response carries: `Retry-After` on a 429,
+     * `WWW-Authenticate` on a 401, `Allow` on a 405. {@link errorMapper} copies them
+     * onto the response; an app replacing the mapper reads them itself.
      */
     readonly headers?: Readonly<Record<string, string>>;
 }
@@ -37,16 +32,9 @@ export declare class ValidationError extends HttpError {
 }
 export type ErrorMapper = (error: unknown, req: Request) => Response;
 /**
- * The class form of {@link ErrorMapper}, and the one to reach for in an app.
- *
- * A mapper is a function, which means it cannot inject: the interesting ones need
- * the app's config to decide how much of an error to reveal, or its `Logger` to
- * record the ones that became a 500. dunx's own default proves the point - it is
- * `errorMapper(logger)`, a curried factory, because currying was the only way to
- * hand a function a dependency.
- *
- * A filter is resolved **from the container**, exactly as `HttpOptions.middleware`
- * entries are, so it takes whatever it needs as constructor parameters:
+ * The class form of {@link ErrorMapper}, and the one to reach for in an app. A
+ * mapper is a function and cannot inject; a filter is resolved from the container
+ * exactly as `HttpOptions.middleware` entries are:
  *
  * ```ts
  * export class AppErrorFilter extends ErrorFilter {
@@ -66,60 +54,41 @@ export type ErrorMapper = (error: unknown, req: Request) => Response;
  * HttpFactory.create(root, { onError: AppErrorFilter });
  * ```
  *
- * `abstract class` rather than an interface, so it is a runtime value and therefore
- * usable as an injection token - an app that wants to swap filters by binding one
- * can. Extending it is optional: `onError` accepts any class with a matching
- * `catch`, because the check is structural.
- *
- * The method is `catch` to match the vocabulary of the thing it replaces, NestJS's
- * `ExceptionFilter.catch`. A filter that cannot handle an error should rethrow it,
- * or delegate to `defaultErrorMapper`.
+ * `abstract class` rather than an interface, so it is a runtime value and usable
+ * as an injection token. Extending it is optional: the check is structural. A
+ * filter that cannot handle an error should rethrow or delegate to
+ * `defaultErrorMapper`.
  */
 export declare abstract class ErrorFilter {
     abstract catch(error: unknown, req: Request): Response;
 }
-/**
- * What `onError` accepts. A bare mapper still works and is the cheaper thing for a
- * filter with no dependencies; a class is what an app that needs one uses.
- */
+/** What `onError` accepts. A bare mapper is cheaper where nothing is injected. */
 export type ErrorHandler = ErrorMapper | Ctor<ErrorFilter>;
 /**
- * Whether `onError` was given a class rather than a mapper.
- *
- * Both are `typeof === 'function'`, so the discriminator is the prototype carrying
- * a `catch`: a class declaration always has one, and neither an arrow function nor
- * a `function` expression ever does. Checking `prototype` alone would be wrong -
- * `function mapper() {}` has an empty one.
+ * Whether `onError` was given a class rather than a mapper. Both are functions, so
+ * the discriminator is a prototype carrying a `catch`. `prototype` alone would be
+ * wrong: `function mapper() {}` has an empty one.
  */
 export declare const isErrorFilter: (handler: ErrorHandler) => handler is Ctor<ErrorFilter>;
 /**
- * Narrows an `ErrorHandler` to the mapper the request path actually calls.
- *
- * `resolve` is typed for this one token rather than generically: the only thing ever
- * looked up here is the filter, and a `<T>(token: Ctor<T>) => T` signature makes
- * every caller - a test included - satisfy a polymorphic contract it does not need.
+ * Narrows an `ErrorHandler` to the mapper the request path calls. `resolve` is
+ * typed for this one token rather than generically, so no caller has to satisfy a
+ * polymorphic contract it does not need.
  */
 export declare const toErrorMapper: (handler: ErrorHandler, resolve: (token: Ctor<ErrorFilter>) => ErrorFilter) => ErrorMapper;
 /**
  * The mapper `HttpFactory` installs unless `onError` replaces it, built from the
- * app's **bound** `Logger` - so a service that imported `@dunx/infra/logger` gets
- * the stack as one `@arkv/logger` entry, sanitized and shaped like every other.
- *
- * An `HttpError` is not logged here at all: the status is the whole record, and
- * `RequestLoggingMiddleware` already writes the 4xx line. Only an error nothing
- * declared - the one that becomes a 500 - is worth a stack.
+ * app's bound `Logger`. An `HttpError` is not logged here: the status is the whole
+ * record and `RequestLoggingMiddleware` already wrote the line, so only an
+ * undeclared error is worth a stack.
  *
- * The error goes in as its own argument rather than as a field of an object.
- * `JSON.stringify(new Error('x'))` is `{}`, so `{ err: error }` would drop the
- * stack; every `Logger` implementation picks an `Error` argument out and
- * serialises it.
+ * The error is its own argument, not a field: `JSON.stringify(new Error('x'))` is
+ * `{}`, so `{ err: error }` would drop the stack.
  */
 export declare const errorMapper: (logger: Logger) => ErrorMapper;
 /**
  * The same mapper with no container behind it, for `buildRoutes` and
- * `buildFallback` called directly. It writes through core's `ConsoleLogger`, which
- * is one JSON line - the point being that nothing in this package ever reaches for
- * `console.error` and emits a multi-line dump a collector reads as several broken
- * records. An app gets {@link errorMapper} over its own bound logger instead.
+ * `buildFallback` called directly. Writes through core's `ConsoleLogger`, so
+ * nothing here emits a multi-line dump a collector reads as several records.
  */
 export declare const defaultErrorMapper: ErrorMapper;