@daloyjs/core 0.7.5 → 0.8.2

package/dist/errors.d.ts

@@ -8,25 +8,81 @@
  * Production-mode rendering scrubs `detail` for 5xx responses so internal
  * messages never leak to clients (security: information disclosure).
  */
+/**
+ * RFC 9457 Problem Details document. This is the on-the-wire shape DaloyJS
+ * uses for **every** error response (the `Content-Type` is
+ * `application/problem+json`). Clients in any language can decode the same
+ * structure.
+ *
+ * Custom fields are allowed and pass through the JSON serialization
+ * unchanged — handy for correlation ids, retry hints, or business codes.
+ *
+ * @see https://www.rfc-editor.org/rfc/rfc9457.html
+ * @since 0.1.0
+ */
 export interface ProblemDetails {
+    /** URI reference identifying the problem type (dereferenceable when possible). */
     type: string;
+    /** Short, human-readable summary of the problem (stable across occurrences). */
     title: string;
+    /** HTTP status code generated by the origin server. */
     status: number;
+    /** Human-readable explanation specific to this occurrence. Scrubbed for 5xx in production. */
     detail?: string;
+    /** URI reference identifying the specific occurrence (e.g. `urn:request:abc123`). */
     instance?: string;
-    /** Validation issues, our extension. */
+    /** DaloyJS extension: structured validation issues with JSON Pointer-style paths. */
     errors?: Array<{
         path: string;
         message: string;
     }>;
+    /** Arbitrary additional members (RFC 9457 §3.2). */
     [key: string]: unknown;
 }
+/**
+ * Options for {@link HttpError.toResponse}.
+ *
+ * @since 0.1.0
+ */
 export interface ProblemRenderOptions {
-    /** When true, scrub `detail` for 5xx responses. Default: NODE_ENV === "production". */
+    /** Scrub `detail` from 5xx responses. Defaults to `process.env.NODE_ENV === "production"`. */
     production?: boolean;
-    /** Optional request id to embed for correlation. */
+    /** Request id stamped into `instance` as `urn:request:<id>` for log correlation. */
     requestId?: string;
 }
+/**
+ * Base class for every DaloyJS HTTP error.
+ *
+ * Throwing an `HttpError` (or any subclass) anywhere inside a handler, hook,
+ * or middleware causes DaloyJS to serialize it as RFC 9457 problem+json with
+ * the appropriate status code and (optionally) extra response headers such as
+ * `Retry-After` or `Allow`. In production mode, 5xx `detail` is scrubbed to
+ * avoid information disclosure.
+ *
+ * Prefer the dedicated subclasses (`BadRequestError`, `NotFoundError`, ...)
+ * for common statuses; instantiate `HttpError` directly only for unusual
+ * status codes or fully-custom problem documents.
+ *
+ * @example
+ * ```ts
+ * import { HttpError } from "@daloyjs/core";
+ *
+ * app.route({
+ *   method: "GET",
+ *   path: "/teapot",
+ *   responses: { 418: { description: "I'm a teapot" } },
+ *   handler: () => {
+ *     throw new HttpError(418, {
+ *       type: "https://example.com/errors/teapot",
+ *       title: "I'm a teapot",
+ *       detail: "Short and stout",
+ *     });
+ *   },
+ * });
+ * ```
+ *
+ * @since 0.1.0
+ */
 export declare class HttpError extends Error {
     readonly status: number;
     readonly problem: ProblemDetails;
@@ -34,41 +90,151 @@ export declare class HttpError extends Error {
     constructor(status: number, problem: Partial<ProblemDetails> & {
         title: string;
     }, headers?: Record<string, string>);
+    /**
+     * Render this error as a `Response` whose body is the problem+json document.
+     * Used internally by the framework; safe to call from custom `onError` hooks
+     * that want to forward additional headers.
+     *
+     * @param opts - Rendering options (production scrubbing, correlation id).
+     * @returns A `Response` with `Content-Type: application/problem+json`.
+     */
     toResponse(opts?: ProblemRenderOptions): Response;
 }
+/**
+ * `400 Bad Request` — the request is syntactically invalid or otherwise
+ * malformed in a way the client should be able to fix without retrying.
+ *
+ * @example
+ * ```ts
+ * throw new BadRequestError("`since` must be an ISO-8601 timestamp");
+ * ```
+ *
+ * @param detail - Optional human-readable explanation surfaced to the client.
+ * @since 0.1.0
+ */
 export declare class BadRequestError extends HttpError {
     constructor(detail?: string);
 }
+/**
+ * `422 Unprocessable Entity` — raised automatically when DaloyJS' request
+ * validator rejects `params`, `query`, `headers`, or `body`. The reported
+ * issues are surfaced in the `errors` member of the problem document so
+ * frontends can render field-level feedback without reparsing the message.
+ *
+ * Throw this directly only when implementing custom validation outside the
+ * declared schema.
+ *
+ * @param where - Which part of the request failed validation.
+ * @param issues - Array of `{ path, message }` records (one per failure).
+ * @since 0.1.0
+ */
 export declare class ValidationError extends HttpError {
     constructor(where: "params" | "query" | "headers" | "body", issues: Array<{
         path: string;
         message: string;
     }>);
 }
+/**
+ * `404 Not Found` — the requested resource does not exist.
+ * DaloyJS also throws this internally for routes the router did not match.
+ *
+ * @param detail - Optional human-readable explanation (e.g. resource id).
+ * @since 0.1.0
+ */
 export declare class NotFoundError extends HttpError {
     constructor(detail?: string);
 }
+/**
+ * `401 Unauthorized` — authentication is required and missing or invalid.
+ * Pair with a `WWW-Authenticate` header on the response when issuing a
+ * challenge (the built-in `bearerAuth` middleware does this for you).
+ *
+ * @param detail - Optional human-readable explanation surfaced to the client.
+ * @since 0.1.0
+ */
 export declare class UnauthorizedError extends HttpError {
     constructor(detail?: string);
 }
+/**
+ * `403 Forbidden` — the request is authenticated but not permitted.
+ * Use for authorization failures ("who you are" is fine, "what you're asking
+ * for" is not). Used by built-in CSRF and bearer-token middleware.
+ *
+ * @param detail - Optional human-readable explanation surfaced to the client.
+ * @since 0.1.0
+ */
 export declare class ForbiddenError extends HttpError {
     constructor(detail?: string);
 }
+/**
+ * `405 Method Not Allowed` — thrown automatically by the router when a path
+ * matches but no route is registered for the request method. The response
+ * carries an `Allow` header enumerating the supported methods, as required by
+ * the HTTP spec.
+ *
+ * @param allow - List of HTTP method names supported on the matched path.
+ * @since 0.1.0
+ */
 export declare class MethodNotAllowedError extends HttpError {
     constructor(allow: string[]);
 }
+/**
+ * `413 Payload Too Large` — thrown by `readBodyLimited` when an incoming
+ * request body exceeds {@link AppOptions.bodyLimitBytes} (or a tighter
+ * per-route limit). Trips both on the declared `Content-Length` (fail-fast)
+ * and on the actual streamed byte count (defence in depth).
+ *
+ * @param limit - The configured byte cap that was exceeded.
+ * @since 0.1.0
+ */
 export declare class PayloadTooLargeError extends HttpError {
     constructor(limit: number);
 }
+/**
+ * `415 Unsupported Media Type` — thrown when the request `Content-Type` is
+ * not in {@link AppOptions.allowedContentTypes} for a route that declares a
+ * body schema.
+ *
+ * @param got - The `Content-Type` value the client sent.
+ * @param expected - Allowed media types for the route.
+ * @since 0.1.0
+ */
 export declare class UnsupportedMediaTypeError extends HttpError {
     constructor(got: string, expected: string[]);
 }
+/**
+ * `429 Too Many Requests` — thrown by the built-in `rateLimit` middleware
+ * when the caller exceeds its quota. When `retryAfterSeconds` is provided the
+ * response carries a `Retry-After` header; clients should back off for that
+ * many seconds before retrying.
+ *
+ * @param retryAfterSeconds - Seconds the client should wait before retrying.
+ * @since 0.1.0
+ */
 export declare class TooManyRequestsError extends HttpError {
     constructor(retryAfterSeconds?: number);
 }
+/**
+ * `408 Request Timeout` — thrown when a handler exceeds
+ * {@link AppOptions.requestTimeoutMs}. The framework aborts the in-flight
+ * handler when this fires (handlers should respect the `AbortSignal` on
+ * `ctx.request.signal` to clean up).
+ *
+ * @param ms - The configured timeout that was exceeded.
+ * @since 0.1.0
+ */
 export declare class RequestTimeoutError extends HttpError {
     constructor(ms: number);
 }
+/**
+ * `500 Internal Server Error` — generic fallback used by the framework when
+ * a handler throws something that isn't an `HttpError`. The original error is
+ * logged at `error` level with the request id for correlation. The `detail`
+ * is automatically scrubbed in production mode.
+ *
+ * @param detail - Optional explanation; suppressed in production output.
+ * @since 0.1.0
+ */
 export declare class InternalError extends HttpError {
     constructor(detail?: string);
 }

package/dist/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,wCAAwC;IACxC,MAAM,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAClD,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,oBAAoB;IACnC,uFAAuF;IACvF,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,oDAAoD;IACpD,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,qBAAa,SAAU,SAAQ,KAAK;IAClC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAC;IACjC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;gBAGxC,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,OAAO,CAAC,cAAc,CAAC,GAAG;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,EACpD,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;IAclC,UAAU,CAAC,IAAI,GAAE,oBAAyB,GAAG,QAAQ;CAetD;AAED,qBAAa,eAAgB,SAAQ,SAAS;gBAChC,MAAM,CAAC,EAAE,MAAM;CAQ5B;AAED,qBAAa,eAAgB,SAAQ,SAAS;gBAE1C,KAAK,EAAE,QAAQ,GAAG,OAAO,GAAG,SAAS,GAAG,MAAM,EAC9C,MAAM,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;CAUnD;AAED,qBAAa,aAAc,SAAQ,SAAS;gBAC9B,MAAM,CAAC,EAAE,MAAM;CAQ5B;AAED,qBAAa,iBAAkB,SAAQ,SAAS;gBAClC,MAAM,CAAC,EAAE,MAAM;CAQ5B;AAED,qBAAa,cAAe,SAAQ,SAAS;gBAC/B,MAAM,CAAC,EAAE,MAAM;CAQ5B;AAED,qBAAa,qBAAsB,SAAQ,SAAS;gBACtC,KAAK,EAAE,MAAM,EAAE;CAW5B;AAED,qBAAa,oBAAqB,SAAQ,SAAS;gBACrC,KAAK,EAAE,MAAM;CAQ1B;AAED,qBAAa,yBAA0B,SAAQ,SAAS;gBAC1C,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE;CAQ5C;AAED,qBAAa,oBAAqB,SAAQ,SAAS;gBACrC,iBAAiB,CAAC,EAAE,MAAM;CAavC;AAED,qBAAa,mBAAoB,SAAQ,SAAS;gBACpC,EAAE,EAAE,MAAM;CAQvB;AAED,qBAAa,aAAc,SAAQ,SAAS;gBAC9B,MAAM,CAAC,EAAE,MAAM;CAQ5B"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,cAAc;IAC7B,kFAAkF;IAClF,IAAI,EAAE,MAAM,CAAC;IACb,gFAAgF;IAChF,KAAK,EAAE,MAAM,CAAC;IACd,uDAAuD;IACvD,MAAM,EAAE,MAAM,CAAC;IACf,8FAA8F;IAC9F,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,qFAAqF;IACrF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,qFAAqF;IACrF,MAAM,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAClD,oDAAoD;IACpD,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACnC,8FAA8F;IAC9F,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,oFAAoF;IACpF,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,qBAAa,SAAU,SAAQ,KAAK;IAClC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAC;IACjC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;gBAGxC,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,OAAO,CAAC,cAAc,CAAC,GAAG;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,EACpD,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;IAclC;;;;;;;OAOG;IACH,UAAU,CAAC,IAAI,GAAE,oBAAyB,GAAG,QAAQ;CAetD;AAED;;;;;;;;;;;GAWG;AACH,qBAAa,eAAgB,SAAQ,SAAS;gBAChC,MAAM,CAAC,EAAE,MAAM;CAQ5B;AAED;;;;;;;;;;;;GAYG;AACH,qBAAa,eAAgB,SAAQ,SAAS;gBAE1C,KAAK,EAAE,QAAQ,GAAG,OAAO,GAAG,SAAS,GAAG,MAAM,EAC9C,MAAM,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;CAUnD;AAED;;;;;;GAMG;AACH,qBAAa,aAAc,SAAQ,SAAS;gBAC9B,MAAM,CAAC,EAAE,MAAM;CAQ5B;AAED;;;;;;;GAOG;AACH,qBAAa,iBAAkB,SAAQ,SAAS;gBAClC,MAAM,CAAC,EAAE,MAAM;CAQ5B;AAED;;;;;;;GAOG;AACH,qBAAa,cAAe,SAAQ,SAAS;gBAC/B,MAAM,CAAC,EAAE,MAAM;CAQ5B;AAED;;;;;;;;GAQG;AACH,qBAAa,qBAAsB,SAAQ,SAAS;gBACtC,KAAK,EAAE,MAAM,EAAE;CAW5B;AAED;;;;;;;;GAQG;AACH,qBAAa,oBAAqB,SAAQ,SAAS;gBACrC,KAAK,EAAE,MAAM;CAQ1B;AAED;;;;;;;;GAQG;AACH,qBAAa,yBAA0B,SAAQ,SAAS;gBAC1C,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE;CAQ5C;AAED;;;;;;;;GAQG;AACH,qBAAa,oBAAqB,SAAQ,SAAS;gBACrC,iBAAiB,CAAC,EAAE,MAAM;CAavC;AAED;;;;;;;;GAQG;AACH,qBAAa,mBAAoB,SAAQ,SAAS;gBACpC,EAAE,EAAE,MAAM;CAQvB;AAED;;;;;;;;GAQG;AACH,qBAAa,aAAc,SAAQ,SAAS;gBAC9B,MAAM,CAAC,EAAE,MAAM;CAQ5B"}

package/dist/errors.js

@@ -8,6 +8,39 @@
  * Production-mode rendering scrubs `detail` for 5xx responses so internal
  * messages never leak to clients (security: information disclosure).
  */
+/**
+ * Base class for every DaloyJS HTTP error.
+ *
+ * Throwing an `HttpError` (or any subclass) anywhere inside a handler, hook,
+ * or middleware causes DaloyJS to serialize it as RFC 9457 problem+json with
+ * the appropriate status code and (optionally) extra response headers such as
+ * `Retry-After` or `Allow`. In production mode, 5xx `detail` is scrubbed to
+ * avoid information disclosure.
+ *
+ * Prefer the dedicated subclasses (`BadRequestError`, `NotFoundError`, ...)
+ * for common statuses; instantiate `HttpError` directly only for unusual
+ * status codes or fully-custom problem documents.
+ *
+ * @example
+ * ```ts
+ * import { HttpError } from "@daloyjs/core";
+ *
+ * app.route({
+ *   method: "GET",
+ *   path: "/teapot",
+ *   responses: { 418: { description: "I'm a teapot" } },
+ *   handler: () => {
+ *     throw new HttpError(418, {
+ *       type: "https://example.com/errors/teapot",
+ *       title: "I'm a teapot",
+ *       detail: "Short and stout",
+ *     });
+ *   },
+ * });
+ * ```
+ *
+ * @since 0.1.0
+ */
 export class HttpError extends Error {
     status;
     problem;
@@ -25,6 +58,14 @@ export class HttpError extends Error {
         if (headers)
             this.headers = headers;
     }
+    /**
+     * Render this error as a `Response` whose body is the problem+json document.
+     * Used internally by the framework; safe to call from custom `onError` hooks
+     * that want to forward additional headers.
+     *
+     * @param opts - Rendering options (production scrubbing, correlation id).
+     * @returns A `Response` with `Content-Type: application/problem+json`.
+     */
     toResponse(opts = {}) {
         const isProd = opts.production ??
             (typeof process !== "undefined" && process.env?.NODE_ENV === "production");
@@ -41,6 +82,18 @@ export class HttpError extends Error {
         return new Response(JSON.stringify(out), { status: this.status, headers });
     }
 }
+/**
+ * `400 Bad Request` — the request is syntactically invalid or otherwise
+ * malformed in a way the client should be able to fix without retrying.
+ *
+ * @example
+ * ```ts
+ * throw new BadRequestError("`since` must be an ISO-8601 timestamp");
+ * ```
+ *
+ * @param detail - Optional human-readable explanation surfaced to the client.
+ * @since 0.1.0
+ */
 export class BadRequestError extends HttpError {
     constructor(detail) {
         super(400, {
@@ -51,6 +104,19 @@ export class BadRequestError extends HttpError {
         this.name = "BadRequestError";
     }
 }
+/**
+ * `422 Unprocessable Entity` — raised automatically when DaloyJS' request
+ * validator rejects `params`, `query`, `headers`, or `body`. The reported
+ * issues are surfaced in the `errors` member of the problem document so
+ * frontends can render field-level feedback without reparsing the message.
+ *
+ * Throw this directly only when implementing custom validation outside the
+ * declared schema.
+ *
+ * @param where - Which part of the request failed validation.
+ * @param issues - Array of `{ path, message }` records (one per failure).
+ * @since 0.1.0
+ */
 export class ValidationError extends HttpError {
     constructor(where, issues) {
         super(422, {
@@ -62,6 +128,13 @@ export class ValidationError extends HttpError {
         this.name = "ValidationError";
     }
 }
+/**
+ * `404 Not Found` — the requested resource does not exist.
+ * DaloyJS also throws this internally for routes the router did not match.
+ *
+ * @param detail - Optional human-readable explanation (e.g. resource id).
+ * @since 0.1.0
+ */
 export class NotFoundError extends HttpError {
     constructor(detail) {
         super(404, {
@@ -72,6 +145,14 @@ export class NotFoundError extends HttpError {
         this.name = "NotFoundError";
     }
 }
+/**
+ * `401 Unauthorized` — authentication is required and missing or invalid.
+ * Pair with a `WWW-Authenticate` header on the response when issuing a
+ * challenge (the built-in `bearerAuth` middleware does this for you).
+ *
+ * @param detail - Optional human-readable explanation surfaced to the client.
+ * @since 0.1.0
+ */
 export class UnauthorizedError extends HttpError {
     constructor(detail) {
         super(401, {
@@ -82,6 +163,14 @@ export class UnauthorizedError extends HttpError {
         this.name = "UnauthorizedError";
     }
 }
+/**
+ * `403 Forbidden` — the request is authenticated but not permitted.
+ * Use for authorization failures ("who you are" is fine, "what you're asking
+ * for" is not). Used by built-in CSRF and bearer-token middleware.
+ *
+ * @param detail - Optional human-readable explanation surfaced to the client.
+ * @since 0.1.0
+ */
 export class ForbiddenError extends HttpError {
     constructor(detail) {
         super(403, {
@@ -92,6 +181,15 @@ export class ForbiddenError extends HttpError {
         this.name = "ForbiddenError";
     }
 }
+/**
+ * `405 Method Not Allowed` — thrown automatically by the router when a path
+ * matches but no route is registered for the request method. The response
+ * carries an `Allow` header enumerating the supported methods, as required by
+ * the HTTP spec.
+ *
+ * @param allow - List of HTTP method names supported on the matched path.
+ * @since 0.1.0
+ */
 export class MethodNotAllowedError extends HttpError {
     constructor(allow) {
         super(405, {
@@ -101,6 +199,15 @@ export class MethodNotAllowedError extends HttpError {
         this.name = "MethodNotAllowedError";
     }
 }
+/**
+ * `413 Payload Too Large` — thrown by `readBodyLimited` when an incoming
+ * request body exceeds {@link AppOptions.bodyLimitBytes} (or a tighter
+ * per-route limit). Trips both on the declared `Content-Length` (fail-fast)
+ * and on the actual streamed byte count (defence in depth).
+ *
+ * @param limit - The configured byte cap that was exceeded.
+ * @since 0.1.0
+ */
 export class PayloadTooLargeError extends HttpError {
     constructor(limit) {
         super(413, {
@@ -111,6 +218,15 @@ export class PayloadTooLargeError extends HttpError {
         this.name = "PayloadTooLargeError";
     }
 }
+/**
+ * `415 Unsupported Media Type` — thrown when the request `Content-Type` is
+ * not in {@link AppOptions.allowedContentTypes} for a route that declares a
+ * body schema.
+ *
+ * @param got - The `Content-Type` value the client sent.
+ * @param expected - Allowed media types for the route.
+ * @since 0.1.0
+ */
 export class UnsupportedMediaTypeError extends HttpError {
     constructor(got, expected) {
         super(415, {
@@ -121,6 +237,15 @@ export class UnsupportedMediaTypeError extends HttpError {
         this.name = "UnsupportedMediaTypeError";
     }
 }
+/**
+ * `429 Too Many Requests` — thrown by the built-in `rateLimit` middleware
+ * when the caller exceeds its quota. When `retryAfterSeconds` is provided the
+ * response carries a `Retry-After` header; clients should back off for that
+ * many seconds before retrying.
+ *
+ * @param retryAfterSeconds - Seconds the client should wait before retrying.
+ * @since 0.1.0
+ */
 export class TooManyRequestsError extends HttpError {
     constructor(retryAfterSeconds) {
         super(429, {
@@ -132,6 +257,15 @@ export class TooManyRequestsError extends HttpError {
         this.name = "TooManyRequestsError";
     }
 }
+/**
+ * `408 Request Timeout` — thrown when a handler exceeds
+ * {@link AppOptions.requestTimeoutMs}. The framework aborts the in-flight
+ * handler when this fires (handlers should respect the `AbortSignal` on
+ * `ctx.request.signal` to clean up).
+ *
+ * @param ms - The configured timeout that was exceeded.
+ * @since 0.1.0
+ */
 export class RequestTimeoutError extends HttpError {
     constructor(ms) {
         super(408, {
@@ -142,6 +276,15 @@ export class RequestTimeoutError extends HttpError {
         this.name = "RequestTimeoutError";
     }
 }
+/**
+ * `500 Internal Server Error` — generic fallback used by the framework when
+ * a handler throws something that isn't an `HttpError`. The original error is
+ * logged at `error` level with the request id for correlation. The `detail`
+ * is automatically scrubbed in production mode.
+ *
+ * @param detail - Optional explanation; suppressed in production output.
+ * @since 0.1.0
+ */
 export class InternalError extends HttpError {
     constructor(detail) {
         super(500, {

package/dist/errors.js.map

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

package/dist/logger.d.ts

@@ -21,6 +21,32 @@ export interface ConsoleLoggerOptions {
     /** Where to write. Defaults to process.stdout.write or console.log. */
     write?: (line: string) => void;
 }
+/**
+ * Build a structured JSON logger writing one record per line to stdout (or
+ * any sink you supply). Records always include `level`, `time`, and the
+ * caller's bindings; objects are merged shallowly and the optional `msg` is
+ * placed under the `msg` key for compatibility with downstream tools.
+ *
+ * @example
+ * ```ts
+ * import { createLogger, App } from "@daloyjs/core";
+ *
+ * const log = createLogger({ level: "info", bindings: { service: "books-api" } });
+ * const app = new App({ logger: log });
+ * log.info({ event: "boot" }, "server starting");
+ * ```
+ *
+ * @param opts - Level, bindings merged into every record, and custom sink.
+ * @returns A {@link Logger} instance.
+ * @since 0.1.0
+ */
 export declare function createLogger(opts?: ConsoleLoggerOptions): Logger;
+/**
+ * A {@link Logger} that discards every record. Used internally when the App
+ * is constructed with `{ logger: false }` and exported so tests can silence
+ * specific subsystems without monkey-patching console.
+ *
+ * @since 0.1.0
+ */
 export declare const noopLogger: Logger;
 //# sourceMappingURL=logger.d.ts.map

package/dist/logger.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,OAAO,CAAC;AAE/E,MAAM,WAAW,MAAM;IACrB,KAAK,EAAE,QAAQ,CAAC;IAChB,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAChD,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAChD,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/C,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/C,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAChD,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAChD,KAAK,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC;CAClD;AAWD,MAAM,WAAW,oBAAoB;IACnC,KAAK,CAAC,EAAE,QAAQ,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,uEAAuE;IACvE,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CAChC;AAED,wBAAgB,YAAY,CAAC,IAAI,GAAE,oBAAyB,GAAG,MAAM,CA6CpE;AAED,eAAO,MAAM,UAAU,EAAE,MAWxB,CAAC"}
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,OAAO,CAAC;AAE/E,MAAM,WAAW,MAAM;IACrB,KAAK,EAAE,QAAQ,CAAC;IAChB,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAChD,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAChD,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/C,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/C,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAChD,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAChD,KAAK,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC;CAClD;AAWD,MAAM,WAAW,oBAAoB;IACnC,KAAK,CAAC,EAAE,QAAQ,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,uEAAuE;IACvE,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CAChC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,YAAY,CAAC,IAAI,GAAE,oBAAyB,GAAG,MAAM,CA6CpE;AAED;;;;;;GAMG;AACH,eAAO,MAAM,UAAU,EAAE,MAWxB,CAAC"}

package/dist/logger.js

@@ -12,6 +12,25 @@ const LEVELS = {
     error: 50,
     fatal: 60,
 };
+/**
+ * Build a structured JSON logger writing one record per line to stdout (or
+ * any sink you supply). Records always include `level`, `time`, and the
+ * caller's bindings; objects are merged shallowly and the optional `msg` is
+ * placed under the `msg` key for compatibility with downstream tools.
+ *
+ * @example
+ * ```ts
+ * import { createLogger, App } from "@daloyjs/core";
+ *
+ * const log = createLogger({ level: "info", bindings: { service: "books-api" } });
+ * const app = new App({ logger: log });
+ * log.info({ event: "boot" }, "server starting");
+ * ```
+ *
+ * @param opts - Level, bindings merged into every record, and custom sink.
+ * @returns A {@link Logger} instance.
+ * @since 0.1.0
+ */
 export function createLogger(opts = {}) {
     const level = opts.level ?? "info";
     const threshold = LEVELS[level];
@@ -59,6 +78,13 @@ export function createLogger(opts = {}) {
     };
     return logger;
 }
+/**
+ * A {@link Logger} that discards every record. Used internally when the App
+ * is constructed with `{ logger: false }` and exported so tests can silence
+ * specific subsystems without monkey-patching console.
+ *
+ * @since 0.1.0
+ */
 export const noopLogger = {
     level: "fatal",
     trace() { },

package/dist/logger.js.map

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