@dunx/http 2.5.0 → 3.0.1

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;

package/dist/server/request-id.d.ts

@@ -2,18 +2,13 @@ export declare const REQUEST_ID_HEADER = "x-request-id";
 /**
  * The request id, and the only thing that decides a request has one.
  *
- * `RequestLoggingMiddleware` sets the header on a response it returns, and a
- * failure is never one: `buildRoutes` and `buildFallback` catch outside the chain
- * and build a fresh `Response` from the error mapper. So a guard's 401, a
- * validation 400, a mapped 500 and every unmatched 404 went out with no id on
- * them, which are the responses a caller most needs in order to find the log line
- * the middleware just wrote.
+ * The logging middleware sets the header on a response it returns, and a failure
+ * is never one - the error mapper builds a fresh `Response` outside the chain. So
+ * a guard's 401, a validation 400 and every unmatched 404 went out with no id.
  *
- * Recorded against the request rather than threaded through the mapper, because
- * `ErrorMapper` is `(error, req) => Response` and an app writes its own.
- * {@link stamp} then reads back whatever {@link assign} recorded, so an app that
- * turned request logging off, or a path it told the middleware to ignore, is still
- * answered without a header: nothing minted an id, so there is none to stamp.
+ * Recorded against the request rather than threaded through the mapper, which an
+ * app writes its own of. {@link stamp} reads back what {@link assign} recorded, so
+ * a path nothing minted an id for is still answered without a header.
  */
 export declare class RequestIds {
     /**

package/dist/server/request-logging.d.ts

@@ -6,57 +6,26 @@ export interface RequestLoggingOptions {
     /** Bodies past this many characters are logged as a size. Default 2048. `0` omits them. */
     readonly maxBodyLength?: number;
     /**
-     * Log the request body. Default **`false`**.
+     * Log the request body. Default `false`, and the cost depends on whether the
+     * route declares a `body` schema: +1.9 us when it does, +28.8 us when it does
+     * not, because the logger has to `req.clone()` an unread network stream.
      *
-     * **What it costs depends on whether the route declares a `body` schema**, and by
-     * a factor of fifteen. `bun run logging:bodies` in `internal/bench`, round-robin
-     * over 3 runs against `POST /validate`:
-     *
-     * | setting                                  | us/req | vs the default |
-     * | ---------------------------------------- | -----: | -------------: |
-     * | `requestLogging: false`                  |  12.80 |      -4.45 us |
-     * | the shipped default, both bodies off     |  17.25 |              - |
-     * | **`requestBody: true`, schema route**    | **19.12** |  **+1.87 us** |
-     * | `responseBody: true`                     |  19.80 |      +2.55 us |
-     * | both bodies, schema route                |  20.03 |      +2.78 us |
-     * | **`requestBody: true`, no schema**       | **46.06** | **+28.81 us** |
-     *
-     * A route with a schema has already had its body buffered by the input reader, so
-     * the logger reads that text and nothing is cloned. A route without one leaves the
-     * logger to `req.clone()`, and cloning a request whose body is an unread network
-     * stream is the entire cost - not the second `JSON.parse`, which is 0.32 us.
-     * `raw-body.ts` has that decomposition.
-     *
-     * It is the field most likely to contain a password. Turn it on in development,
-     * where seeing the payload is the point.
+     * It is the field most likely to contain a password.
      */
     readonly requestBody?: boolean;
-    /**
-     * Log the response body. Default **`false`**, +2.55 us - see the table above.
-     *
-     * No equivalent trick here and none needed: a response is already a materialised
-     * string by the time this clones it, which is why it was never the expensive half.
-     */
+    /** Log the response body. Default `false`, +2.6 us. A response is already a
+     * materialised string by the time this clones it. */
     readonly responseBody?: boolean;
     /**
-     * Paths to skip entirely - a health check polled every second, say.
-     *
-     * **Entirely** is literal: no entry, no `x-request-id` on the response, and no
-     * `AsyncLocalStorage` scope, so anything the handler logs is uncorrelated. That
-     * is what makes it free. `correlateIgnored` buys the correlation back.
+     * Paths to skip entirely: no entry, no `x-request-id`, and no
+     * `AsyncLocalStorage` scope, so anything the handler logs is uncorrelated.
+     * `correlateIgnored` buys the correlation back.
      */
     readonly ignore?: readonly string[];
     /**
-     * Path **prefixes** to skip, for a whole mount rather than one path.
-     *
-     * `ignore` is an exact-match `Set` because that is one lookup on the hot path
-     * and a health check is one path. A mount is not: `@dunx/dashboard` at
-     * `/_dunx` polls four endpoints every five seconds and bull-board pulls a
-     * dozen assets, and listing them is both tedious and wrong the moment either
-     * grows an endpoint.
-     *
-     * Scanned only when non-empty, so an app that sets none pays nothing - the
-     * same guard `ignore` has. Keep the list short; it is a loop.
+     * Path prefixes to skip, for a whole mount rather than one path. `ignore` is an
+     * exact-match `Set`; this is a loop, so keep the list short. Scanned only when
+     * non-empty.
      *
      * ```ts
      * requestLogging: { ignorePrefix: ['/_dunx'] }
@@ -65,78 +34,37 @@ export interface RequestLoggingOptions {
     readonly ignorePrefix?: readonly string[];
     /**
      * Keep the request id and the async scope on an `ignore`d path. Default
-     * **`false`**.
-     *
-     * "Do not log the health check, but do keep its request id" is this. The path
-     * still writes no entry of its own; it gets an id - inbound or minted - on the
-     * response, and everything the handler logs carries it.
-     *
-     * It is not the default because it is not free: the ignored path pays for
-     * reading the header, `crypto.randomUUID()`, the `runWithContext` scope and the
-     * response header. On the `bun run logging` decomposition those four rows are
-     * ~2.2 µs, against ~5.4 µs for the whole default path - so it costs the half
-     * that buys correlation and not the half that builds and serialises the entry.
+     * `false`. The path still writes no entry; it gets an id on the response and
+     * everything the handler logs carries it. Costs ~2.2 us of the ~5.4 us the
+     * default path spends.
      */
     readonly correlateIgnored?: boolean;
     /**
-     * Wrap every request in an `AsyncLocalStorage` scope. Default **`true`**.
-     *
-     * The scope is what lets a service logging four frames down come out carrying
-     * `requestId` without being handed a request object. It is measured: the
-     * `runWithContext` row of `bun run logging` is **+0.91 µs**, 17% of the 5.38 µs
-     * request logging costs over `requestLogging: false`.
-     *
-     * `correlate: false` skips it. **The request entry is unchanged** - the same
-     * `requestId`, `method`, `event`, `flow` and `context` fields are written onto
-     * it directly instead of being read back out of the store. What is lost is
-     * everything *else* the request logs: those lines carry no `requestId`, and
-     * `updateContext` from a handler has nothing to update.
-     *
-     * Worth it for an app whose handlers never log, or one that passes correlation
-     * explicitly. Leave it on otherwise; correlation is most of what a request id
-     * is for.
+     * Wrap every request in an `AsyncLocalStorage` scope. Default `true`, +0.91 us.
+     * It is what lets a service four frames down log `requestId` without being
+     * handed a request. `correlate: false` skips it; this middleware's own entry is
+     * unchanged, but every other line the request writes loses its id.
      */
     readonly correlate?: boolean;
     /**
      * Adopt W3C Trace Context, so `traceId`, `spanId` and `parentSpanId` join
-     * `requestId` on every line the request writes. Default **`false`**.
-     *
-     * On, an inbound `traceparent` is honoured and this service becomes a child
-     * span of the caller's; off, nothing reads the header and nothing is minted.
-     * It costs a header read and 8 random bytes per request, which is not worth
-     * paying in a service with nothing to correlate against - and `requestId`
-     * already spans two dunx services on its own.
-     *
-     * `@dunx/http/client` sends the adopted trace upstream, so turning this on at
-     * both ends is what makes one trace cover both.
+     * `requestId`. Default `false`: it costs a header read and 8 random bytes, and
+     * `requestId` already spans two dunx services. `@dunx/http/client` sends the
+     * adopted trace upstream.
      */
     readonly trace?: boolean;
 }
 /**
  * One structured entry per request, carrying the request and its response.
+ * Installed by `HttpFactory.create` unless `requestLogging: false`, and injecting
+ * only core contracts, so it works with no logging module imported.
  *
- * Installed by `HttpFactory.create` unless `requestLogging: false`. It injects
- * `Logger` and `RequestContext` - both `@dunx/core` contracts, both bound by
- * default - so it works with no logging module imported, and picks up
- * `@arkv/logger` automatically once `@dunx/infra/logger` is.
- *
- * **One entry, not two.** A framework whose middleware cannot see the response
- * needs a middleware for the inbound half and an
- * interceptor for the outbound one, because they are different classes and the
- * interceptor cannot see what the middleware saw. Here they are the same
- * closure, so there is no pair to correlate by `requestId` to find out how a
- * call ended. A 4xx is the same line at `warn`, a 5xx at `error`.
- *
- * Everything the handler logs in between carries `requestId`, `method`, `event`
- * and `context` without being passed anything, because the whole call runs
- * inside `runWithContext` - unless `correlate: false`, which drops the scope and
- * with it that guarantee, but not the fields on this middleware's own entry.
+ * One entry rather than a middleware and an interceptor to correlate: middleware
+ * wraps `next()`, so both halves are the same closure. A 4xx logs at `warn`, a
+ * 5xx at `error`.
  *
- * **Nothing here is `async`.** Reading the request or the response body are the
- * only steps that can ever wait, both are off by default, and both are adopted
- * with `.then` rather than awaited - the same rule `input.ts` follows, for the
- * same measured reason. An `async` scope callback alone cost 0.44 µs/request
- * against a synchronous one on raw `Bun.serve`.
+ * Nothing here is `async`. The two steps that can wait are off by default and
+ * adopted with `.then`; an `async` scope callback alone cost 0.44 us/request.
  */
 export declare class RequestLoggingMiddleware implements Middleware {
     #private;

package/dist/server/routes.d.ts

@@ -39,19 +39,12 @@ export declare const assertNoGatewayCollisions: (discovered: readonly Discovered
  */
 export declare const withUpgradeRoutes: (routes: BunRoutes, gateways: ReadonlyMap<string, UpgradeHandler>) => ServeRoutes;
 /**
- * Bun answers an unmatched path itself, so nothing in the middleware chain ever
- * sees it - which makes a 404 invisible to request logging, metrics and tracing.
+ * Bun answers an unmatched path itself, so nothing in the middleware chain sees
+ * it and a 404 is invisible to request logging. This is the only `fetch` handler
+ * dunx installs and it is not a router: it runs once Bun has matched nothing.
  *
- * This is the only `fetch` handler dunx installs, and it is not a router: Bun
- * still does all the matching, and this runs only once Bun has decided nothing
- * matched. It puts the global middleware in front of a 404 in the framework's
- * own error shape.
- *
- * **The miss is a `throw`, not a returned `Response`.** `miss` raises
- * `HttpError(404)` and `compose` propagates it, so a middleware written as
- * `const response = await next(); if (response.status === 404) ...` never reaches
- * its own second line on an unmatched path - the rewrite it was written for is the
- * one case it cannot see. A middleware that means to act on a miss has to catch:
+ * The miss is a throw, not a returned `Response`, so a middleware reading
+ * `(await next()).status` never sees one and has to catch:
  *
  * ```ts
  * try {
@@ -62,13 +55,8 @@ export declare const withUpgradeRoutes: (routes: BunRoutes, gateways: ReadonlyMa
  * }
  * ```
  *
- * `ctx.get(UNMATCHED)` is the other half, and the cheaper one: it is set here and
- * by no real route, so a middleware can tell "nothing matched this path" from "a
- * handler answered 404 for a record that does not exist" **before** calling
- * `next()` at all. Only the second of those is a `Response` to inspect.
- *
- * Composed per request rather than at boot, because the context names the path
- * that missed. That allocation is on the 404 path only.
+ * `ctx.get(UNMATCHED)` is the cheaper half: set here and by no real route, so a
+ * middleware can tell a miss from a handler's own 404 before calling `next()`.
  */
 export declare const buildFallback: (middleware?: readonly Middleware[], onError?: ErrorMapper, cors?: CorsOptions, notFound?: 'guarded' | 'public') => RouteHandler;
 export declare const buildRoutes: (discovered: readonly DiscoveredRoute[], middleware?: readonly Middleware[], onError?: ErrorMapper, cors?: CorsOptions, resolve?: GuardResolver) => BunRoutes;

package/dist/server/trace-context.d.ts

@@ -27,17 +27,13 @@ export interface Trace {
 export declare class TraceContext {
     #private;
     /**
-     * The inbound `traceparent`, or a fresh trace.
+     * The inbound `traceparent`, or a fresh trace. A malformed header is discarded
+     * rather than repaired, as the standard requires. Version `ff` is invalid; a
+     * higher version keeps its first four fields, so a future format still
+     * propagates.
      *
-     * A malformed header is discarded rather than repaired, which is what the
-     * standard requires: an unparseable `traceparent` means the caller's trace is
-     * unknown, not that this request has none. Version `ff` is invalid, and a
-     * higher version keeps its first four fields and drops the rest, so a future
-     * format still propagates through this service instead of being dropped.
-     *
-     * When nothing arrives, `traceId` is the request id with its hyphens removed -
-     * a UUID is 16 bytes, which is exactly a trace id, and reusing it means one
-     * identifier in two spellings rather than a second `crypto` call per request.
+     * With nothing inbound, `traceId` is the request id minus its hyphens - a UUID
+     * is 16 bytes, exactly a trace id, so there is no second `crypto` call.
      */
     static adopt(req: Request, requestId: string): Trace;
     /** The trace adopted for this request, if one was. */

package/dist/static/files.d.ts

@@ -3,20 +3,12 @@ import type { Middleware, Next } from '../server/middleware.js';
 import type { RouteContext } from '../server/context.js';
 import { StaticOptions } from './options.js';
 /**
- * Static files, on `Bun.file`.
+ * Static files, on `Bun.file`. A `Bun.file` handed to a `Response` already
+ * streams, sets `content-type`, answers a `Range` request and uses `sendfile(2)`,
+ * so this file is a path check and a cache policy.
  *
- * Nest has `ServeStaticModule` over `serve-static`, which is Express middleware
- * doing its own `stat`, its own range parsing, its own ETag and its own MIME table.
- * None of that is needed here: `Bun.file(path)` handed to a `Response` already
- * streams, already sets `content-type` from the extension, already answers a
- * `Range` request, and does the whole thing with `sendfile(2)` rather than reading
- * into JavaScript. So this file is a **path check and a cache policy**, and that is
- * the entire justification for it existing.
- *
- * A middleware rather than routes, for the same reason the dashboard is one: the
- * file set is whatever is on disk at request time, and turning it into a
- * `Bun.serve` route table would mean walking a directory at boot and being wrong
- * the moment anything changed.
+ * A middleware rather than routes: the file set is whatever is on disk at request
+ * time, and a route table would be walked at boot and wrong thereafter.
  */
 export declare class StaticFiles implements Middleware {
     #private;

package/dist/static/module.d.ts

@@ -1,26 +1,21 @@
 import { type Deps, type DynamicModule, type FactoryProvider } from '@dunx/core';
 import { type StaticOptionsInit } from './options.js';
 /**
- * Serves a directory, the way Nest's `ServeStaticModule` does - and like the
- * dashboard, **it does not register itself**. The app does:
+ * Serves a directory. Like the dashboard, it does not register itself:
  *
  * ```ts
  * const app = await HttpFactory.create(AppModule);
  * app.use(StaticFiles);
  * ```
  *
- * Position in the chain is the decision being left to the app. Static assets
- * usually want to be *outside* an auth guard and *inside* request logging, and no
- * default can know which. Anything outside the mount falls through untouched, so
- * the app's own routes and its 404 behave exactly as before.
+ * Position in the chain is left to the app - assets usually want to be outside an
+ * auth guard and inside request logging. Anything outside the mount falls through
+ * untouched.
  *
- * There is no `index.html` fallback and no SPA rewrite: building them in would mean
- * this middleware deciding what a 404 means for paths it does not own.
- *
- * An app that wants one writes a middleware **outside** this one, and the shape
- * matters. An unmatched path is a **thrown** `HttpError(404)`, not a returned
- * `Response` - see `buildFallback` - so reading `(await next()).status` never sees a
- * miss, and `ctx.get(UNMATCHED)` is what does:
+ * There is no `index.html` fallback and no SPA rewrite, which would mean this
+ * middleware deciding what a 404 means for paths it does not own. An app that
+ * wants one writes a middleware outside this one, reading `ctx.get(UNMATCHED)`
+ * rather than a returned status, since a miss is thrown:
  *
  * ```ts
  * export class SpaFallback implements Middleware {
@@ -45,12 +40,8 @@ import { type StaticOptionsInit } from './options.js';
  * }
  * ```
  *
- * Two more things that shape where it goes in the chain. `notFound: 'guarded'` -
- * the default - reports a miss with no route metadata, so a global session guard
- * refuses it and the status is a 401 rather than a 404; an app serving a SPA wants
- * `notFound: 'public'`. And the fallback answers **before** any middleware listed
- * after the guard, so the rewrite has to sit ahead of the guard to see the miss at
- * all.
+ * `notFound: 'guarded'`, the default, reports a miss with no route metadata, so a
+ * session guard refuses it with a 401; a SPA wants `notFound: 'public'`.
  */
 export declare class StaticModule {
     static forRoot(init: StaticOptionsInit): DynamicModule;

package/dist/throttle/guard.d.ts

@@ -8,17 +8,14 @@ import { ThrottleStore } from './store.js';
 /**
  * A fixed-window rate limit, one key per subject and handler.
  *
- * **Fails open.** A store that cannot be reached allows the request and warns
- * **once per process** - a line per request would be its own outage, and refusing
- * every request because the counter is down turns a degraded dependency into a
- * dead service.
+ * Fails open: an unreachable store allows the request and warns once per process,
+ * since refusing everything because the counter is down turns a degraded
+ * dependency into a dead service.
  *
- * **List it after any session guard.** An authenticated caller should be limited by
- * user id and an anonymous one by address, and only the guard ahead of this one
- * knows which - which is what `ThrottleOptions.subject` reads.
+ * List it after any session guard - only the guard ahead knows whether to limit by
+ * user id or by address, which is what `ThrottleOptions.subject` reads.
  *
- * The 429 is thrown, never returned, so it goes through the app's own `onError` and
- * comes out in the app's error shape like every other status.
+ * The 429 is thrown, so it comes out in the app's own error shape.
  */
 export declare class ThrottleGuard implements Middleware {
     #private;

package/dist/throttle/module.d.ts

@@ -1,12 +1,11 @@
 import { type Deps, type DynamicModule, type FactoryProvider } from '@dunx/core';
 import { type ThrottleOptionsInit } from './options.js';
 /**
- * A first-class rate limit: the decorator, the guard, the counter and its options.
+ * The decorator, the guard, the counter and its options.
  *
- * `global: true`, because the guard is listed in `HttpOptions.middleware` - which
- * is the app's own list, resolved from wherever the class is declared - and a
- * non-global module would make every consumer import this one to reach a guard it
- * never names.
+ * `global: true`: the guard is listed in `HttpOptions.middleware`, the app's own
+ * list, so a non-global module would make every consumer import this one to reach
+ * a guard it never names.
  *
  * ```ts
  * ThrottleModule.forRootAsync({
@@ -22,9 +21,8 @@ import { type ThrottleOptionsInit } from './options.js';
  * HttpFactory.create(AppModule, { middleware: [SessionGuard, ThrottleGuard] });
  * ```
  *
- * Position in the chain is the app's, the same decision `StaticFiles` leaves open,
- * and for a sharper reason: ahead of a session guard the limit counts every caller
- * as an address.
+ * Position in the chain is the app's: ahead of a session guard, the limit counts
+ * every caller as an address.
  */
 export declare class ThrottleModule {
     static forRoot(init: ThrottleOptionsInit): DynamicModule;

package/dist/throttle/store.d.ts

@@ -1,15 +1,10 @@
 /**
- * The counter behind the guard.
+ * The counter behind the guard. An `abstract class` rather than an interface,
+ * since an interface at an injection site is a boot error.
  *
- * An `abstract class` rather than an interface: `@dunx/transform` records
- * constructor parameter *types*, so an interface at an injection site is a boot
- * error. Same reason `RedisConnection` and `Logger` are classes.
- *
- * **A fixed window, not a sliding one.** `hit` increments and returns the count for
- * the window the key is already in; the window starts at the first hit and ends
- * when the key expires. A sliding window needs a sorted set per subject and a
- * range trim per request, which is a different cost for an accuracy a rate limit
- * does not need.
+ * A fixed window: `hit` returns the count for the window the key is already in,
+ * which starts at the first hit and ends when the key expires. A sliding window
+ * needs a sorted set per subject and a trim per request.
  */
 export declare abstract class ThrottleStore {
     constructor();
@@ -51,17 +46,13 @@ export declare class RedisThrottleStore extends ThrottleStore {
     ttl(key: string): Promise<number | undefined>;
 }
 /**
- * The single-process counter, and the default - so an app with no Redis still
- * limits something rather than nothing.
- *
- * It is per process, which is the whole caveat: two replicas each allow the full
- * budget. `RedisThrottleStore` is the answer for more than one.
+ * The single-process counter and the default, so an app with no Redis still limits
+ * something. Per process is the caveat: two replicas each allow the full budget,
+ * and `RedisThrottleStore` is the answer for more than one.
  *
- * The map is bounded. An expired entry is dropped when its key is next touched,
- * and once the map passes `maxKeys` every expired entry is swept - so a burst
- * across many subjects cannot grow it without limit. Reaching the cap with nothing
- * expired clears it, which resets a window early rather than holding memory a
- * server does not have.
+ * The map is bounded. Expired entries are dropped on touch and swept past
+ * `maxKeys`; reaching the cap with nothing expired clears it, resetting a window
+ * early rather than holding memory.
  */
 export declare class MemoryThrottleStore extends ThrottleStore {
     #private;

package/dist/ws/middleware.d.ts

@@ -43,35 +43,26 @@ export interface SocketFrame {
  */
 export type SocketNext = () => unknown;
 /**
- * The single extension point on the socket side, shaped like {@link Middleware} on
- * the HTTP side: one method, wrapping `next()`.
+ * The socket side's single extension point, shaped like {@link Middleware}: one
+ * method wrapping `next()`. It sees every dispatched handler, and open and close
+ * arrive even for a gateway declaring neither.
  *
- * It sees every dispatched handler - open, each named message, the catch-all,
- * close, drain, ping and pong - and open and close arrive even for a gateway that
- * declares no `@OnOpen`/`@OnClose`, so a connection is never invisible to it.
+ * A throwing handler passes through here. Rethrow to leave the outcome to
+ * `SocketOptions.onError`, or return a value to answer the frame.
  *
- * A throwing or rejecting handler passes through here, which is where a guard
- * refuses and where an observer records the failure. Rethrow to leave the outcome
- * to `SocketOptions.onError`; return a value instead to answer the frame.
- *
- * Three things it cannot see, because they never reach the dispatcher: a
- * `socket.send` a handler makes itself, a `PubSub` broadcast, and the upgrade -
- * which is an HTTP request answered by the gateway's own route.
+ * It cannot see a `socket.send` a handler makes itself, a `PubSub` broadcast, or
+ * the upgrade, which is an HTTP request.
  */
 export interface SocketMiddleware {
     /**
-     * That a failure passing through here is reported somewhere. Default
-     * **`false`**.
+     * That a failure passing through here is reported somewhere. Default `false`.
      *
      * `SocketOptions.onError`'s `console.error` fallback is not installed while any
-     * socket middleware exists, because a middleware wraps the handler and would
-     * report the same failure a second time. Whether it does is something only the
-     * middleware knows: one that ignores a throw turns error reporting off for the
-     * whole server, and nothing about the wiring says so.
+     * socket middleware exists, since a middleware would report the same failure
+     * twice. Only the middleware knows whether it does, and one that ignores a throw
+     * would silently turn error reporting off for the whole server.
      *
-     * Setting it is how a middleware says it does report. Leaving it unset with no
-     * `websocket.onError` beside it is what `HttpFactory.create` warns about at
-     * boot.
+     * Unset with no `websocket.onError` beside it is what `create` warns about.
      */
     readonly reportsErrors?: boolean;
     handle(frame: SocketFrame, ctx: SocketContext, next: SocketNext): unknown;