expediate 0.0.3 → 1.0.0

package/dist/misc.d.ts

@@ -0,0 +1,203 @@
+import type { RouterRequest, Middleware } from './router.js';
+/**
+ * A JSON reviver function, matching the second parameter of `JSON.parse`.
+ * Receives each key/value pair during parsing and may return a transformed
+ * value.
+ */
+type Reviver = (key: string, value: unknown) => unknown;
+/**
+ * Options shared by all body-parsing middleware factories
+ * ({@link json}, {@link formData}, {@link parseBody}).
+ */
+export interface BodyOptions {
+    /**
+     * When `true` (default), compressed request bodies (`gzip`, `deflate`) are
+     * automatically decompressed before parsing.  Set to `false` to reject
+     * compressed bodies with 415 Unsupported Media Type.
+     */
+    inflate?: boolean;
+    /**
+     * Maximum accepted body size.  Accepts a number (bytes) or a human-readable
+     * string such as `'100kb'`, `'2mb'`, or `'1gb'`.
+     * Defaults to `'100kb'` (102 400 bytes).
+     */
+    limit?: string | number;
+    /**
+     * Optional JSON reviver passed as the second argument to `JSON.parse`.
+     * Only meaningful for {@link json} and {@link parseBody} when the body is
+     * `application/json`.
+     */
+    reviver?: Reviver | null;
+    /**
+     * When `true` (default), JSON parsing is restricted to objects and arrays.
+     * Bare primitives (strings, numbers, booleans) at the top level are
+     * rejected.  Has no effect on non-JSON bodies.
+     *
+     * @remarks Currently reserved for future enforcement; not yet applied.
+     */
+    strict?: boolean;
+}
+/**
+ * Options for the {@link logger} middleware factory.
+ */
+export interface LoggerOptions {
+    /**
+     * When `true`, starts a timer per request.  If the response is not finished
+     * within {@link trackTimeout} milliseconds, a `LOST` warning line is logged.
+     * Recommended for development only — keeping a `setTimeout` per request has
+     * a non-trivial memory cost in production.
+     * Defaults to `false`.
+     */
+    track?: boolean;
+    /**
+     * Timeout in milliseconds before a tracked request is considered lost.
+     * Only used when {@link track} is `true`.
+     * Defaults to `30 000` ms (30 seconds).
+     */
+    trackTimeout?: number;
+    /**
+     * Extract a user identity string from the request for inclusion in the log
+     * line.  Receives the augmented `RouterRequest` and should return a short
+     * string (e.g. a username, session ID, or `'-'` for anonymous).
+     * Defaults to always returning `'-'`.
+     *
+     * @example
+     * ```ts
+     * user: (req) => (req as any).authUser ?? '-'
+     * ```
+     */
+    user?: (req: RouterRequest) => string;
+    /**
+     * BCP 47 locale tag used when formatting the request timestamp.
+     * Passed as the first argument to `Intl.DateTimeFormat`.
+     * Defaults to `'en-GB'`.
+     */
+    locale?: string;
+    /**
+     * Date/time format options passed as the second argument to
+     * `Intl.DateTimeFormat`.  Override this to change which fields are shown in
+     * the timestamp.
+     * Defaults to `{ month: 'short', day: '2-digit', hour: '2-digit', minute: '2-digit' }`.
+     */
+    dateFormat?: Intl.DateTimeFormatOptions;
+    /**
+     * Custom logging function.  Receives the fully-formatted log line as a
+     * single string.  Defaults to `console.log`.
+     */
+    logger?: (msg: string) => void;
+}
+/**
+ * A single part extracted from a `multipart/form-data` body.
+ */
+export interface FormPart {
+    /**
+     * Raw part headers (e.g. `Content-Disposition`, `Content-Type`).
+     * Keys are lowercased; values are trimmed.
+     */
+    headers: Record<string, string>;
+    /**
+     * Raw binary content of the part (everything after the blank header line).
+     */
+    content: Buffer;
+}
+/**
+ * Middleware factory that parses a `application/json` request body and
+ * assigns the parsed value to `req.body`.
+ *
+ * Also attaches a `res.json(data)` helper to the response object so that
+ * handlers can send JSON responses conveniently:
+ * ```ts
+ * res.json({ ok: true });
+ * ```
+ *
+ * Behaviour:
+ * - Requests without a body (`Content-Length: 0` or absent) are passed
+ *   through to `next()` without touching `req.body`.
+ * - Bodies larger than `opts.limit` receive **413 Content Too Large**.
+ * - Bodies with an unsupported `Content-Encoding` receive
+ *   **415 Unsupported Media Type**.
+ * - Bodies whose `Content-Type` is not `application/json` receive
+ *   **415 Unsupported Media Type**.
+ * - Parse errors receive **500 Internal Server Error**.
+ *
+ * @param opts - Optional configuration (see {@link BodyOptions}).
+ * @returns An Express-compatible middleware function.
+ */
+export declare function json(opts?: BodyOptions): Middleware;
+/**
+ * Middleware factory that parses a `multipart/form-data` request body and
+ * assigns an array of {@link FormPart} objects to `req.body`.
+ *
+ * Each element in `req.body` exposes:
+ * - `headers` — the part's MIME headers (e.g. `Content-Disposition`).
+ * - `content` — the raw binary content of the part as a `Buffer`.
+ *
+ * Behaviour:
+ * - Requests without a body are passed through to `next()`.
+ * - Bodies larger than `opts.limit` receive **413 Content Too Large**.
+ * - Bodies with a missing or malformed `boundary` parameter receive
+ *   **400 Bad Request**.
+ * - Parse errors receive **500 Internal Server Error**.
+ *
+ * @param opts - Optional configuration (see {@link BodyOptions}).
+ * @returns An Express-compatible middleware function.
+ */
+export declare function formData(opts?: BodyOptions): Middleware;
+/**
+ * Middleware factory that auto-detects the `Content-Type` of the request body
+ * and parses it using the appropriate parser.
+ *
+ * Supported MIME types:
+ * - `application/json`    → parsed as JSON; result is a JS value.
+ * - `multipart/form-data` → parsed as multipart; result is `FormPart[]`.
+ * - `text/plain`          → decoded as text; result is a string.
+ *
+ * Requests with an unsupported MIME type receive **415 Unsupported Media Type**.
+ * All other error conditions behave identically to {@link json} and
+ * {@link formData}.
+ *
+ * @param opts - Optional configuration (see {@link BodyOptions}).
+ * @returns An Express-compatible middleware function.
+ */
+export declare function parseBody(opts?: BodyOptions): Middleware;
+/**
+ * Middleware factory that logs one line per completed HTTP request to the
+ * console (or a custom logger function).
+ *
+ * Each log line contains:
+ * - Timestamp (formatted with `Intl.DateTimeFormat`).
+ * - HTTP status code (ANSI-coloured by status class).
+ * - HTTP method and request path.
+ * - Client IP address (honours `X-Forwarded-For`).
+ * - User identity (from `opts.user` or `'-'`).
+ * - Elapsed time in milliseconds.
+ * - Response `Content-Length` (or `'-'` when absent).
+ *
+ * **Lost-request tracking:** when `opts.track` is `true`, a timer is started
+ * for each request.  If the response is not finished within `opts.trackTimeout`
+ * milliseconds, a `LOST` warning line is emitted.  This is useful in
+ * development to surface handlers that never call `res.end()`.
+ *
+ * @param opts - Optional configuration (see {@link LoggerOptions}).
+ * @returns An Express-compatible middleware function.
+ *
+ * @example
+ * ```ts
+ * app.use('/', logger({
+ *   track:        true,
+ *   trackTimeout: 30_000,
+ *   user:         (req) => (req as any).authUser ?? '-',
+ *   locale:       'en-US',
+ *   logger:       (msg) => process.stderr.write(msg + '\n'),
+ * }));
+ * ```
+ */
+export declare function logger(opts?: LoggerOptions): Middleware;
+declare const _default: {
+    json: typeof json;
+    formData: typeof formData;
+    parseBody: typeof parseBody;
+    logger: typeof logger;
+};
+export default _default;
+//# sourceMappingURL=misc.d.ts.map

package/dist/misc.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"misc.d.ts","sourceRoot":"","sources":["../src/misc.ts"],"names":[],"mappings":"AAuBA,OAAO,KAAK,EAAE,aAAa,EAAkB,UAAU,EAAE,MAAM,aAAa,CAAC;AAM7E;;;;GAIG;AACH,KAAK,OAAO,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC;AAExD;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B;;;;OAIG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACxB;;;;OAIG;IACH,OAAO,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IACzB;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAKD;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;;;;;;;OAUG;IACH,IAAI,CAAC,EAAE,CAAC,GAAG,EAAE,aAAa,KAAK,MAAM,CAAC;IACtC;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,IAAI,CAAC,qBAAqB,CAAC;IACxC;;;OAGG;IACH,MAAM,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;CAChC;AAED;;GAEG;AACH,MAAM,WAAW,QAAQ;IACvB;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC;;OAEG;IACH,OAAO,EAAE,MAAM,CAAC;CACjB;AAuXD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,IAAI,CAAC,IAAI,CAAC,EAAE,WAAW,GAAG,UAAU,CAmBnD;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,QAAQ,CAAC,IAAI,CAAC,EAAE,WAAW,GAAG,UAAU,CAcvD;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,SAAS,CAAC,IAAI,CAAC,EAAE,WAAW,GAAG,UAAU,CAiBxD;AA4BD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,MAAM,CAAC,IAAI,CAAC,EAAE,aAAa,GAAG,UAAU,CAkDvD;;;;;;;AAED,wBAAqD"}