@orkestrel/middleware 0.0.19 → 0.0.20

package/dist/src/server/index.d.cts

@@ -1,10 +1,10 @@
-import { Encoding } from '@orkestrel/server';
-import { FileHandle } from 'node:fs/promises';
+import type { Encoding } from '@orkestrel/server';
+import type { FileHandle } from 'node:fs/promises';
 import { HTTPError } from '@orkestrel/server';
-import { MiddlewareHandler } from '@orkestrel/server';
-import { MultipartBody } from '@orkestrel/middleware';
-import { MultipartFile } from '@orkestrel/middleware';
-import { MultipartState } from '@orkestrel/middleware';
+import type { MiddlewareHandler } from '@orkestrel/server';
+import type { MultipartBody } from '@orkestrel/middleware';
+import type { MultipartFile } from '@orkestrel/middleware';
+import type { MultipartState } from '@orkestrel/middleware';
 
 /**
  * Describes one in-memory asset representation returned by an {@link AssetSourceInterface}.
@@ -23,7 +23,7 @@ export declare interface Asset {
  * Configures `createAssets` — in-memory identity/Brotli asset serving.
  *
  * @remarks
- * - `source` — the required in-memory asset reader. It MUST answer a bounded
+ * - `source` — the required in-memory asset reader. It must answer a bounded
  *   key set and return `undefined` for every key outside it, because
  *   `createAssets` retains every successful result for the factory's lifetime
  *   and evicts nothing. A `source` that synthesizes a representation for an
@@ -40,12 +40,12 @@ export declare interface AssetOptions {
  * @remarks
  * A successful result is cached by `createAssets`; later source changes do
  * not alter that path's response. A miss may be read again on a later request.
- * `read` therefore owes a BOUNDED key set: that cache retains every
+ * `read` therefore owes a bounded key set: that cache retains every
  * successful result for the factory's lifetime and evicts nothing.
  */
 export declare interface AssetSourceInterface {
     /**
-     * Reads one asset representation.
+     * Reads one identity or Brotli asset representation for a validated relative key.
      *
      * @param path - The validated relative asset path
      * @returns The asset, or `undefined` when the path is absent
@@ -136,12 +136,11 @@ export declare function computeFileETag(size: number, mtimeMs: number): string;
 export declare function createAssets<TState>(options: AssetOptions): MiddlewareHandler<TState>;
 
 /**
- * Compresses response bodies through `node:zlib` — the node-bound sibling of
- * the core face's `CompressionStream`-feature-detected `createCompression`,
- * guaranteed available on any Node runtime rather than dependent on the
- * WHATWG `CompressionStream` global. Ships as a SEPARATE package entry point
- * (`@orkestrel/middleware/server`) from the core face's `createCompression`,
- * so the shared name is unambiguous per consumer import path.
+ * Compresses response bodies through `node:zlib`, guaranteed on any Node runtime rather
+ * than dependent on the WHATWG `CompressionStream` global. This battery is the
+ * node-bound sibling of the core face's feature-detected `createCompression`, and it
+ * ships from a separate package entry point (`@orkestrel/middleware/server`) so the
+ * shared name is unambiguous per consumer import path.
  *
  * @remarks
  * Peer-type limitation, the same one the core face carries: the shipped
@@ -178,7 +177,7 @@ export declare function createCompression<TState>(options?: NodeCompressionOptio
  * {@link MultipartError} this battery's parser throws is re-thrown as an
  * {@link HTTPError} carrying the same status/message, so `createBoundary`
  * (or any HTTPError-aware renderer) maps it correctly without depending on
- * this node face's error type. Fail-closed on the DOWNSTREAM handler too: if
+ * this node face's error type. Fail-closed on the downstream handler too: if
  * `next()` throws, every still-`'staged'` uploaded file is unlinked
  * (best-effort) before the error is re-thrown, so an unhandled downstream
  * failure never leaks temp files. A normal return leaves staged files
@@ -200,16 +199,16 @@ export declare function createCompression<TState>(options?: NodeCompressionOptio
 export declare function createMultipart<TState extends MultipartState>(options?: MultipartOptions): MiddlewareHandler<TState>;
 
 /**
- * Serves static files from `options.root` over `node:fs` — the node-bound
- * static-file battery.
+ * Serves static files from `options.root` over `node:fs` — the node-bound static-file
+ * battery, answering conditional, ranged, and SPA-fallback requests.
  *
  * @remarks
- * Containment is enforced on CANONICAL paths, not merely the lexically
+ * Containment is enforced on canonical paths, not merely the lexically
  * resolved one: `options.root` is canonicalized once (memoized) and every
  * request's candidate path is re-canonicalized (`fs.realpath`) before it is
  * served, so a symlink whose target escapes `root` is refused (falls through
  * to `next()`) even though the lexical path resolved inside `root`. A
- * symlink that resolves to a target still INSIDE `root` is unaffected and
+ * symlink that resolves to a target still inside `root` is unaffected and
  * still serves normally. A dangling symlink (`realpath` throws `ENOENT`) or
  * any other `realpath` failure is treated as a miss — this battery never
  * throws or 500s on a symlink surprise. On a streamed response (a 200 or 206
@@ -246,31 +245,31 @@ export declare function createStatic<TState>(options: StaticOptions): Middleware
  */
 export declare function createUploadedFile(input: UploadedFile): UploadedFile;
 
-/** Names the MIME type served when a file extension has no known mapping. */
+/** Names `'application/octet-stream'`, the MIME type served when a file extension has no known mapping. */
 export declare const DEFAULT_CONTENT_TYPE = "application/octet-stream";
 
-/** Holds `createMultipart`'s default maximum field-part count. */
+/** Holds `100`, `createMultipart`'s default maximum field-part count. */
 export declare const DEFAULT_MULTIPART_FIELD_COUNT = 100;
 
-/** Holds `createMultipart`'s default per-field byte-size cap. */
+/** Holds `65_536`, `createMultipart`'s default per-field byte-size cap. */
 export declare const DEFAULT_MULTIPART_FIELD_SIZE = 65536;
 
-/** Holds `createMultipart`'s default maximum file-part count. */
+/** Holds `10`, `createMultipart`'s default maximum file-part count. */
 export declare const DEFAULT_MULTIPART_FILE_COUNT = 10;
 
-/** Holds `createMultipart`'s default per-file byte-size cap. */
+/** Holds `10_485_760`, `createMultipart`'s default per-file byte-size cap. */
 export declare const DEFAULT_MULTIPART_FILE_SIZE = 10485760;
 
-/** Holds `createMultipart`'s default combined request-body byte-size cap. */
+/** Holds `52_428_800`, `createMultipart`'s default combined request-body byte-size cap. */
 export declare const DEFAULT_MULTIPART_TOTAL = 52428800;
 
-/** Names `createStatic`'s default policy for a path carrying a dotfile segment. */
+/** Names `'ignore'`, `createStatic`'s default policy for a path carrying a dotfile segment. */
 export declare const DEFAULT_STATIC_DOTFILES: NonNullable<StaticOptions['dotfiles']>;
 
-/** Names `createStatic`'s `fallback: true` default excluded path prefix. */
+/** Names `'/api'`, `createStatic`'s `fallback: true` default excluded path prefix. */
 export declare const DEFAULT_STATIC_FALLBACK_EXCLUDE = "/api";
 
-/** Names `createStatic`'s default directory-index filename. */
+/** Names `'index.html'`, `createStatic`'s default directory-index filename. */
 export declare const DEFAULT_STATIC_INDEX = "index.html";
 
 /**
@@ -316,11 +315,11 @@ export declare function extractMultipartBoundary(contentType: string | null): st
 
 /**
  * Checks whether `child` is `parent` itself or lies inside it on-disk — the
- * FILESYSTEM containment predicate `createStatic` applies to `fs.realpath`
+ * filesystem containment predicate `createStatic` applies to `fs.realpath`
  * output (never to a URL pathname — that is {@link isUnderPath}'s job).
  *
  * @remarks
- * Argument order is `(child, parent)` — deliberately the OPPOSITE conceptual
+ * Argument order is `(child, parent)` — deliberately the opposite conceptual
  * order from {@link isUnderPath}`(pathname, prefix)`, so a call site cannot
  * casually swap one predicate in for the other. Built on `path.relative`,
  * this is separator-correct on both POSIX (`/`) and win32 (`\`) — unlike a
@@ -384,7 +383,7 @@ export declare function isMultipartError(value: unknown): value is MultipartErro
  *
  * @remarks
  * Normalizes superscript digits (`¹²³` → `123`) first, strips trailing dots
- * and spaces (Windows drops them), takes the STEM before the first `.`,
+ * and spaces (Windows drops them), takes the stem before the first `.`,
  * upper-cases it, and tests it against {@link RESERVED_DEVICE_NAMES}
  * (`CON PRN AUX NUL COM1-9 LPT1-9`) — an exact-stem match only, so
  * `console.js` and `nullable.css` are never flagged.
@@ -402,7 +401,7 @@ export declare function isMultipartError(value: unknown): value is MultipartErro
 export declare function isReservedDeviceName(segment: string): boolean;
 
 /**
- * Checks whether `pathname` is `prefix` itself or lies under it on a SEGMENT
+ * Checks whether `pathname` is `prefix` itself or lies under it on a segment
  * boundary — the shared under-path test `resolveStaticPath`'s prefix strip
  * and `createStatic`'s SPA-fallback `exclude` both apply, so `exclude:
  * '/api'` matches `/api` and `/api/x` but never `/apifoo`.
@@ -476,13 +475,16 @@ export declare function moveUploadedFile(file: UploadedFile, destination: string
  */
 export declare const MULTIPART_ERROR_BRAND: unique symbol;
 
-/** Holds the maximum bytes a single multipart part's header block may occupy before it is malformed. */
+/** Holds `16_384`, the maximum bytes a single multipart part's header block may occupy before it is malformed. */
 export declare const MULTIPART_MAX_HEADER_BLOCK = 16384;
 
-/** Holds the maximum bytes scanned before the first multipart boundary is found before it is malformed. */
+/** Holds `65_536`, the maximum bytes scanned before the first multipart boundary is found before it is malformed. */
 export declare const MULTIPART_MAX_PREAMBLE = 65536;
 
-/** Holds the HTTP status `createMultipart` renders for each {@link MultipartErrorCode}. */
+/**
+ * Holds the HTTP status `createMultipart` renders for each {@link MultipartErrorCode}:
+ * `'limit'` is 413, `'malformed'` is 400, and `'rejected'` is 415.
+ */
 export declare const MULTIPART_STATUS: Readonly<Record<MultipartErrorCode, number>>;
 
 /**
@@ -520,7 +522,7 @@ export declare class MultipartError extends HTTPError {
 export declare type MultipartErrorCode = 'limit' | 'malformed' | 'rejected';
 
 /**
- * Describes the per-category size/count caps `createMultipart` enforces MID-STREAM — the
+ * Describes the per-category size/count caps `createMultipart` enforces mid-stream — the
  * effective limits, every documented default already applied.
  *
  * @remarks
@@ -576,7 +578,7 @@ export declare interface MultipartLimitsInput {
  *
  * @remarks
  * - `limits` — see {@link MultipartLimitsInput}.
- * - `allowed` — a MIME allow-list validated against SNIFFED (not merely
+ * - `allowed` — a MIME allow-list validated against sniffed (not merely
  *   declared) bytes; an empty array allows nothing. Omitted ⇒ no type
  *   rejection.
  * - `directory` — the directory staged files are written to; defaults to
@@ -589,8 +591,8 @@ export declare interface MultipartOptions {
 }
 
 /**
- * Lists the content-codings the node face's `createCompression` offers — the two
- * `node:zlib` guarantees on every Node runtime, so this face never
+ * Lists `['gzip', 'deflate']`, the content-codings the node face's `createCompression`
+ * offers — what `node:zlib` guarantees on every Node runtime, so this face never
  * feature-detects.
  */
 export declare const NODE_COMPRESSION_ENCODINGS: readonly Encoding[];
@@ -619,30 +621,30 @@ export declare interface NodeCompressionOptions {
  *
  * @remarks
  * Reads `request.body` chunk by chunk through its `ReadableStream` reader —
- * NEVER buffers the whole body — enforcing every {@link MultipartLimits} cap
+ * never buffers the whole body — enforcing every {@link MultipartLimits} cap
  * the instant it is exceeded (reading stops, every already-staged temp file
  * is deleted, throws {@link MultipartError} with code `'limit'`). Each file
  * part streams to `join(directory, randomUUID())` — the client's declared
- * filename is METADATA ONLY, never a path component. A field OR file part
+ * filename is metadata only, never a path component. A field or file part
  * named `__proto__` / `constructor` / `prototype` is silently skipped and
  * never keyed onto the returned {@link MultipartBody} (a skipped file's
  * staged temp file is unlinked immediately, since it can never be
  * referenced). A file part with an empty declared filename (`filename=""`)
- * AND a zero-byte body — the browser convention for an unselected optional
+ * and a zero-byte body — the browser convention for an unselected optional
  * `<input type="file">` — is a silent no-op: its temp file is unlinked, it is
  * never counted against the `file.count` limit, and it never runs the
  * `allowed` check. A malformed
  * structure (missing/unterminated boundary, nameless part, an oversized
  * header block, or a preamble exceeding {@link MULTIPART_MAX_PREAMBLE} before
  * the first boundary) throws with code `'malformed'`. A file is accepted
- * against the configured `allowed` MIME list iff its SNIFFED bytes detect a
+ * against the configured `allowed` MIME list exactly when its sniffed bytes detect a
  * type present in the list — sniff-authoritative, independent of whether the
  * declared `Content-Type` matches (that agreement is exposed separately as
  * `validated`); otherwise throws with code `'rejected'`. A
  * request abort mid-upload triggers the same fail-closed cleanup as a limit
  * breach. Returns `undefined` for a non-multipart request (untouched).
  *
- * Staging defaults to a process-owned directory created ONCE (lazily,
+ * Staging defaults to a process-owned directory created once (lazily,
  * memoized across calls) with `mkdtemp` under `os.tmpdir()` and locked to
  * mode `0o700`; `options.directory` overrides it.
  *
@@ -753,7 +755,7 @@ export declare function resolveMultipartLimits(limits: MultipartLimitsInput | un
  * fallback.
  *
  * @remarks
- * `GET` and `HEAD` are both eligible, and resolve the SAME shell: `HEAD` is
+ * `GET` and `HEAD` are both eligible, and resolve the same shell: `HEAD` is
  * defined as `GET` without a body (RFC 9110 §9.3.2), so a navigation probe
  * that answered `404` while its `GET` answered `200` would report a resource
  * the very next request serves.
@@ -775,14 +777,14 @@ export declare function resolveMultipartLimits(limits: MultipartLimitsInput | un
 export declare function resolveStaticFallbackPath(root: string, index: string, exclude: string, method: string, pathname: string, accept: string): string | undefined;
 
 /**
- * Resolves a request pathname to an on-disk path UNDER `root`, or `undefined`
+ * Resolves a request pathname to an on-disk path under `root`, or `undefined`
  * when it cannot — the traversal guard, whose algorithm and order are exact:
  * strip `prefix` on a segment boundary → `decodeURIComponent` (a
  * malformed escape refuses, never throws) → reject a NUL byte → strip the
- * leading path separator FIRST (so a leading `..` survives `normalize` as a
- * genuine climbing segment) → `normalize` → refuse any Windows reserved-
- * device-name segment ({@link isReservedDeviceName}) → `resolve` and require
- * the result under `root`.
+ * leading path separator first (so a leading `..` survives `normalize` as a
+ * genuine climbing segment) → `normalize` → refuse any Windows
+ * reserved-device-name segment ({@link isReservedDeviceName}) → `resolve` and
+ * require the result under `root`.
  *
  * @param root - The absolute root directory every result must resolve under
  * @param prefix - An optional URL path prefix stripped on a segment boundary
@@ -802,14 +804,14 @@ export declare function resolveStaticPath(root: string, prefix: string | undefin
  * Configures `createStatic` — node `fs`-backed static file serving.
  *
  * @remarks
- * - `root` — the directory every request resolves under, resolved once at
- *   construction. REQUIRED.
+ * - `root` — the required directory every request resolves under, resolved
+ *   once at construction.
  * - `prefix` — a URL path prefix stripped (on a segment boundary) before
  *   resolving under `root`.
  * - `index` — the filename served for a directory hit and by the SPA
  *   fallback; defaults to {@link DEFAULT_STATIC_INDEX}. The fallback serves
- *   it whatever `dotfiles` is set to, because this path is operator-
- *   configured rather than request-derived.
+ *   it whatever `dotfiles` is set to, because this path is
+ *   operator-configured rather than request-derived.
  * - `dotfiles` — the policy for a path with a dotfile segment: `'ignore'`
  *   (falls through to `next()`), `'deny'` (403), or `'allow'` (serves it);
  *   defaults to {@link DEFAULT_STATIC_DOTFILES}.
@@ -818,7 +820,7 @@ export declare function resolveStaticPath(root: string, prefix: string | undefin
  * - `fallback` — SPA fallback: `false` (default, off), `true` (on, excluding
  *   {@link DEFAULT_STATIC_FALLBACK_EXCLUDE}), or `{ exclude }` for a custom
  *   excluded prefix. An eligible `GET` or `HEAD` navigation miss answers with
- *   `index` through the SAME handle-`fstat` header block a directly requested
+ *   `index` through the same handle-`fstat` header block a directly requested
  *   file answers through, so `cache`, `etag`, conditional revalidation,
  *   `HEAD`, and ranges are identical on both routes; `index` reaches the
  *   client through this route whatever `dotfiles` is set to.
@@ -842,7 +844,7 @@ export declare interface StaticOptions {
  * response body routes through.
  *
  * @remarks
- * PULL-driven, not push-driven: the underlying node stream's async iterator
+ * Pull-driven, not push-driven: the underlying node stream's async iterator
  * is only advanced (`iterator.next()`) from inside `pull(controller)`, which
  * the web `ReadableStream` invokes exactly when its internal queue has room
  * for more data. Exactly one disk chunk is read and enqueued per `pull` —
@@ -911,13 +913,13 @@ export declare function unlinkStagedFiles(body: MultipartBody): Promise<void>;
  *
  * @remarks
  * - `field` — the multipart field name the file was submitted under.
- * - `name` — the client-declared filename (METADATA ONLY — never used to
+ * - `name` — the client-declared filename (metadata only — never used to
  *   build a filesystem path).
  * - `size` — the file's byte size.
- * - `mime` — the SNIFFED (magic-byte-detected) MIME type when a signature
+ * - `mime` — the sniffed (magic-byte-detected) MIME type when a signature
  *   matches; otherwise the part's declared `Content-Type`; otherwise
  *   {@link DEFAULT_CONTENT_TYPE}. Read `validated` to tell which.
- * - `validated` — `true` when a signature matched AND the sniffed type equals
+ * - `validated` — `true` when a signature matched and the sniffed type equals
  *   the declared `Content-Type`, so `mime` is the sniffed fact. `false` means
  *   `mime` may be the client-declared value.
  * - `status` — see {@link UploadStatus}.