elysia 2.0.0-beta.2 → 2.0.0-beta.21

package/dist/error.d.ts

@@ -6,13 +6,32 @@ import { MaybePromise } from "./types.js";
 declare class ElysiaError<Status extends number = number, Response extends string = string> extends Error {
   status?: Status;
   response?: Response;
-  /** RFC 9457 problem `type` slug (overridden per subclass) */
-  problemType: string;
-  /** RFC 9457 problem `title` (overridden per subclass) */
-  problemTitle?: string;
+  /**
+   * Stable machine-readable token served in the `code` member, the same
+   * contract a {@link HTTPError.id} class speaks (set per subclass)
+   */
+  readonly code?: string;
+  /**
+   * RFC 9457 problem type served in the `type` member. Mirrors `code`, or
+   * resolves to `<typeBase>/<code>` once {@link HTTPError.typeBase} is set.
+   * Defined on the prototype below
+   */
+  type?: string;
   constructor(message: string, cause?: Error);
   toResponse(headers?: Record<string, any>): globalThis.Response;
 }
+/**
+ * `type` an error slug resolves to: the slug verbatim, or `<typeBase>/<slug>`
+ * once {@link HTTPError.typeBase} is set. Shared by `ElysiaError` and every
+ * class {@link HTTPError.id} makes, so both lanes derive `type` identically
+ */
+declare function problemTypeOf(code: string | undefined): string | undefined;
+/**
+ * Problem members an `ElysiaError` serves. `title` is left to `problemBody`,
+ * which derives it from the status — so `response` is only worth serving as
+ * `detail` when it says something the title doesn't
+ */
+declare function elysiaErrorProblem(error: ElysiaError): Problem;
 /**
  * Wrap a string into a TypeBox `error` callback that overrides the default
  * validation message. Use as `t.Number({ error: validationDetail('x must be a number') })`.
@@ -21,31 +40,31 @@ declare const validationDetail: <T>(message: T) => (error: any) => any;
 declare class InternalServerError extends ElysiaError {
   response: string;
   status: 500;
-  problemType: string;
-  problemTitle: string;
+  readonly code = "internal-server-error";
   constructor(response?: string, cause?: Error);
 }
 declare class NotFound extends ElysiaError {
   response: string;
   status: 404;
-  problemType: string;
-  problemTitle: string;
+  readonly code = "not-found";
   constructor(response?: string);
 }
 declare class ParseError extends ElysiaError {
   status: 400;
   response: string;
-  problemType: string;
-  problemTitle: string;
+  readonly code = "parse";
   constructor(cause?: Error);
   toResponse(headers?: Record<string, any>): Response;
 }
+declare const MAX_ERRORS = 64;
 declare function subValueAt(value: unknown, path: unknown): any;
 declare class ValidationError extends ElysiaError {
   #private;
   type: string | undefined;
   value: unknown;
-  status: 422;
+  /** Response validation is a server error; other validation is a client error. */
+  status: 422 | 500;
+  readonly code = "validation";
   schema?: unknown;
   message: string;
   allowUnsafeValidationDetails: boolean;
@@ -57,7 +76,7 @@ declare class ValidationError extends ElysiaError {
   '~resolve'(): {
     errors: any[];
     custom: unknown;
-    message: string;
+    message: any;
   };
   errors: any[];
   get customError(): unknown;
@@ -67,116 +86,56 @@ declare class ValidationError extends ElysiaError {
     type: string;
     on: string | undefined;
     message: unknown;
-    errors?: undefined;
+    errors: any[];
   } | {
     type: string;
     on: string | undefined;
     message: unknown;
-    errors: any[];
+    errors?: undefined;
   };
   get payload(): {
-    type: string;
+    type: string | undefined;
+    code: string;
     title: string;
     status: number;
-    on?: undefined;
-    property?: undefined;
-    detail?: undefined;
-    found?: undefined;
-    expected?: undefined;
-    errors?: undefined;
   } | {
     type: string;
+    code: string;
     title: string;
     status: number;
     on: string | undefined;
     property: string;
-    detail?: undefined;
-    found?: undefined;
-    expected?: undefined;
-    errors?: undefined;
   } | {
-    type: string;
-    title: string;
-    status: number;
     detail: any;
     on: string | undefined;
     property: string;
-    found: any;
+    found: unknown;
     expected: unknown;
     errors: any[];
+    type: string | undefined;
+    code: string;
+    title: string;
+    status: number;
   };
   toResponse(headers?: Record<string, any>): Response;
 }
-declare class ElysiaStatus<const in out Code extends number | keyof StatusMap, T = (Code extends keyof StatusMapBack ? StatusMapBack[Code] : Code), const in out Status extends (Code extends keyof StatusMap ? StatusMap[Code] : Code) = (Code extends keyof StatusMap ? StatusMap[Code] : Code)> {
-  code: Status;
+/** Default body for a status with no response. Named to keep emitted types small. */
+type StatusResponse<Code extends number | keyof StatusMap> = Code extends keyof StatusMapBack ? StatusMapBack[Code] : Code;
+declare class ElysiaStatus<const in out Code extends number | keyof StatusMap, T = StatusResponse<Code>, const in out Status extends NumericStatus<Code> = NumericStatus<Code>> {
+  /**
+   * Type-only brand, erased at runtime.
+   *
+   * `status` + `response` is a shape a handler may write by hand, so without
+   * a nominal marker a plain `{ status, response }` literal would be
+   * absorbed as a status box by response inference
+   */
+  readonly ['~status']: true;
+  status: Status;
   response: T;
   headers?: Record<string, string>;
   constructor(code: Code, res: T, headers?: Record<string, string>);
-  get status(): number;
 }
-declare const status: <const Code extends number | keyof StatusMap, const T = (Code extends keyof StatusMapBack ? StatusMapBack[Code] : Code)>(code: Code, response?: T) => ElysiaStatus<Code, T, Code extends "Continue" | "Switching Protocols" | "Processing" | "Early Hints" | "OK" | "Created" | "Accepted" | "Non-Authoritative Information" | "No Content" | "Reset Content" | "Partial Content" | "Multi-Status" | "Already Reported" | "Multiple Choices" | "Moved Permanently" | "Found" | "See Other" | "Not Modified" | "Temporary Redirect" | "Permanent Redirect" | "Bad Request" | "Unauthorized" | "Payment Required" | "Forbidden" | "Not Found" | "Method Not Allowed" | "Not Acceptable" | "Proxy Authentication Required" | "Request Timeout" | "Conflict" | "Gone" | "Length Required" | "Precondition Failed" | "Payload Too Large" | "URI Too Long" | "Unsupported Media Type" | "Range Not Satisfiable" | "Expectation Failed" | "I'm a teapot" | "Enhance Your Calm" | "Misdirected Request" | "Unprocessable Content" | "Locked" | "Failed Dependency" | "Too Early" | "Upgrade Required" | "Precondition Required" | "Too Many Requests" | "Request Header Fields Too Large" | "Unavailable For Legal Reasons" | "Internal Server Error" | "Not Implemented" | "Bad Gateway" | "Service Unavailable" | "Gateway Timeout" | "HTTP Version Not Supported" | "Variant Also Negotiates" | "Insufficient Storage" | "Loop Detected" | "Not Extended" | "Network Authentication Required" ? {
-  readonly Continue: 100;
-  readonly 'Switching Protocols': 101;
-  readonly Processing: 102;
-  readonly 'Early Hints': 103;
-  readonly OK: 200;
-  readonly Created: 201;
-  readonly Accepted: 202;
-  readonly 'Non-Authoritative Information': 203;
-  readonly 'No Content': 204;
-  readonly 'Reset Content': 205;
-  readonly 'Partial Content': 206;
-  readonly 'Multi-Status': 207;
-  readonly 'Already Reported': 208;
-  readonly 'Multiple Choices': 300;
-  readonly 'Moved Permanently': 301;
-  readonly Found: 302;
-  readonly 'See Other': 303;
-  readonly 'Not Modified': 304;
-  readonly 'Temporary Redirect': 307;
-  readonly 'Permanent Redirect': 308;
-  readonly 'Bad Request': 400;
-  readonly Unauthorized: 401;
-  readonly 'Payment Required': 402;
-  readonly Forbidden: 403;
-  readonly 'Not Found': 404;
-  readonly 'Method Not Allowed': 405;
-  readonly 'Not Acceptable': 406;
-  readonly 'Proxy Authentication Required': 407;
-  readonly 'Request Timeout': 408;
-  readonly Conflict: 409;
-  readonly Gone: 410;
-  readonly 'Length Required': 411;
-  readonly 'Precondition Failed': 412;
-  readonly 'Payload Too Large': 413;
-  readonly 'URI Too Long': 414;
-  readonly 'Unsupported Media Type': 415;
-  readonly 'Range Not Satisfiable': 416;
-  readonly 'Expectation Failed': 417;
-  readonly "I'm a teapot": 418;
-  readonly 'Enhance Your Calm': 420;
-  readonly 'Misdirected Request': 421;
-  readonly 'Unprocessable Content': 422;
-  readonly Locked: 423;
-  readonly 'Failed Dependency': 424;
-  readonly 'Too Early': 425;
-  readonly 'Upgrade Required': 426;
-  readonly 'Precondition Required': 428;
-  readonly 'Too Many Requests': 429;
-  readonly 'Request Header Fields Too Large': 431;
-  readonly 'Unavailable For Legal Reasons': 451;
-  readonly 'Internal Server Error': 500;
-  readonly 'Not Implemented': 501;
-  readonly 'Bad Gateway': 502;
-  readonly 'Service Unavailable': 503;
-  readonly 'Gateway Timeout': 504;
-  readonly 'HTTP Version Not Supported': 505;
-  readonly 'Variant Also Negotiates': 506;
-  readonly 'Insufficient Storage': 507;
-  readonly 'Loop Detected': 508;
-  readonly 'Not Extended': 510;
-  readonly 'Network Authentication Required': 511;
-}[Code] : Code>;
+declare const status: <const Code extends number | keyof StatusMap, const T = StatusResponse<Code>>(code: Code, response?: T) => ElysiaStatus<Code, T, NumericStatus<Code>>;
 declare const PROBLEM_JSON = "application/problem+json";
 /**
  * RFC 9457 Problem Details shape.
@@ -184,16 +143,36 @@ declare const PROBLEM_JSON = "application/problem+json";
  * @see https://www.rfc-editor.org/info/rfc9457/
  */
 type Problem<Code extends number | keyof StatusMap = number | keyof StatusMap, Extension extends Record<string, unknown> = {}> = {
-  /** URI (or slug) identifying the problem type. @default 'about:blank' */type?: string; /** Short, human-readable summary of the problem type */
+  /** URI (or slug) identifying the problem type. @default 'about:blank' */type?: string;
+  /**
+   * Extension member carrying a stable machine-readable token.
+   *
+   * `type` may be widened to a URI by {@link HTTPError.typeBase}, `code`
+   * never is
+   */
+  code?: string; /** Short, human-readable summary of the problem type */
   title?: string; /** HTTP status. A number or a `StatusMap` name (e.g. `'Conflict'`) */
   status?: Code; /** Human-readable explanation specific to this occurrence */
   detail?: string; /** URI identifying the specific occurrence of the problem */
   instance?: string;
 } & Extension;
+/** Numeric form of a status name or code. */
 type NumericStatus<Code extends number | keyof StatusMap> = Code extends keyof StatusMap ? StatusMap[Code] : Code;
 type ProblemStatus<P> = P extends {
   status: infer S extends number | keyof StatusMap;
 } ? NumericStatus<S> : 500;
+/** Request validation problem. Diagnostic fields are development-only. */
+type ValidationErrorResponse = {
+  type: 'validation';
+  code: 'validation';
+  title: 'Validation Error';
+  status: 422;
+  detail?: string;
+  on: string;
+  found?: unknown;
+  property?: string;
+  expected?: string;
+};
 type ProblemResponseBody<Status extends number, P> = Omit<{
   type: string;
   title: string;
@@ -235,12 +214,16 @@ declare function problem<const Code extends number | keyof StatusMap, const P ex
 declare function problem<const P extends Problem>(detail: P): ElysiaStatus<ProblemStatus<P>, ProblemResponseBody<ProblemStatus<P>, P>>;
 type CheckExcessProps<T, U> = 0 extends 1 & T ? T : U extends U ? Exclude<keyof T, keyof U> extends never ? T : { [K in keyof U]: U[K] } & { [K in Exclude<keyof T, keyof U>]: never } : never;
 type SelectiveStatus<in out Res> = <const Code extends keyof Res | StatusMapBack[Extract<keyof StatusMapBack, keyof Res>], T extends (Code extends keyof Res ? Res[Code] : Code extends keyof StatusMap ? Res[StatusMap[Code]] : never)>(code: Code, response: CheckExcessProps<T, Code extends keyof Res ? Res[Code] : Code extends keyof StatusMap ? Res[StatusMap[Code]] : never>) => ElysiaStatus<Code, T>;
+type ProblemInput<T> = T extends object ? Omit<T, 'type' | 'title' | 'status'> & { [K in keyof T as K extends 'type' | 'title' ? K : never]?: T[K] } : never;
+type ResponseOf<Res, Code> = Code extends keyof Res ? Res[Code] : Code extends keyof StatusMap ? Res[StatusMap[Code]] : never;
+type SelectiveProblem<in out Res> = <const Code extends keyof Res | StatusMapBack[Extract<keyof StatusMapBack, keyof Res>], T extends ProblemInput<ResponseOf<Res, Code>> = ProblemInput<ResponseOf<Res, Code>>>(code: Code, ...detail: {} extends ProblemInput<ResponseOf<Res, Code>> ? [detail?: CheckExcessProps<T, ProblemInput<ResponseOf<Res, Code>>>] : [detail: CheckExcessProps<T, ProblemInput<ResponseOf<Res, Code>>>]) => ElysiaStatus<NumericStatus<Code>, ResponseOf<Res, Code>>;
 /**
  * Class returned by {@link HTTPError.id}
  */
 type TaggedHTTPError<Type extends string, Annotation = {}> = {
   new (message?: string, options?: ErrorOptions): HTTPError<Type> & {
     type: Type;
+    readonly code: Type;
   } & Annotation;
   prototype: HTTPError<Type>;
 };
@@ -305,8 +288,34 @@ declare abstract class HTTPError<const in out T extends string = string> extends
   /**
    * RFC 9457 problem type served in the `type` member, a URI or a slug.
    * Doubles as the tag that discriminates one error class from another
+   *
+   * On a {@link HTTPError.id} class this mirrors `code`, or resolves to
+   * `<typeBase>/<code>` once {@link HTTPError.typeBase} is set
    */
   abstract type: T;
+  /**
+   * Stable machine-readable token served in the `code` member, set by
+   * {@link HTTPError.id} to its first argument
+   *
+   * Unlike `type` it is never widened to a URI, so it stays the value to
+   * dispatch on
+   */
+  readonly code?: string;
+  /**
+   * Absolute base for the RFC 9457 `type` URI, applied to every class made
+   * by {@link HTTPError.id} and to every built-in `ElysiaError`
+   * (`NotFound`, `ParseError`, …) both derive `type` from the same slug
+   *
+   * @example
+   * ```ts
+   * HTTPError.typeBase = 'https://example.com/errors'
+   *
+   * class OutOfCredit extends HTTPError.id('OUT_OF_CREDIT', 402) {}
+   * // → { type: 'https://example.com/errors/OUT_OF_CREDIT',
+   * //     code: 'OUT_OF_CREDIT', … }
+   * ```
+   */
+  static typeBase?: string;
   /**
    * HTTP status served when the error reaches the error pipeline,
    * as a number or a status name (`'Payment Required'`)
@@ -328,9 +337,10 @@ declare abstract class HTTPError<const in out T extends string = string> extends
    */
   detail?(): MaybePromise<unknown>;
   /**
-   * Create a concrete `HTTPError` subclass carrying `type`
+   * Create a concrete `HTTPError` subclass carrying `code`, mirrored into
+   * `type` unless {@link HTTPError.typeBase} is set
    *
-   * `type` carries no status annotation, annotate `status` in the subclass
+   * `code` carries no status annotation, annotate `status` in the subclass
    * body as a number or a status name
    *
    * @example
@@ -342,9 +352,9 @@ declare abstract class HTTPError<const in out T extends string = string> extends
    * }
    * ```
    */
-  static id<const Type extends string>(type: Type): TaggedHTTPError<Type>;
+  static id<const Type extends string>(code: Type): TaggedHTTPError<Type>;
   /**
-   * Create a concrete `HTTPError` subclass carrying `type`, annotated with
+   * Create a concrete `HTTPError` subclass carrying `code`, annotated with
    * `status` as a number or a status name
    *
    * Annotate what is served with `detail()` (problem `detail` member) or
@@ -353,16 +363,16 @@ declare abstract class HTTPError<const in out T extends string = string> extends
    * @example
    * ```ts
    * class OutOfCredit extends HTTPError.id('OUT_OF_CREDIT', 402) {}
-   * class Denied extends HTTPError.id('https://example.com/denied', 'Payment Required') {
+   * class Denied extends HTTPError.id('DENIED', 'Payment Required') {
    *     async detail() {
    *         return await describeBalance()
    *     }
    * }
    * ```
    */
-  static id<const Type extends string, const S extends number | keyof StatusMap>(type: Type, status: S): TaggedHTTPError<Type, {
+  static id<const Type extends string, const S extends number | keyof StatusMap>(code: Type, status: S): TaggedHTTPError<Type, {
     readonly status: S extends keyof StatusMap ? StatusMap[S] : S;
   }>;
 }
 //#endregion
-export { ElysiaError, ElysiaStatus, HTTPError, InternalServerError, NotFound, PROBLEM_JSON, ParseError, Problem, ProblemResponseBody, SelectiveStatus, TaggedHTTPError, ValidationError, internalServerErrorBody, internalServerErrorBodyString, internalServerErrorResponse, isProduction, problem, problemBody, problemResponse, status, subValueAt, validationDetail };
+export { ElysiaError, ElysiaStatus, HTTPError, InternalServerError, MAX_ERRORS, NotFound, NumericStatus, PROBLEM_JSON, ParseError, Problem, ProblemResponseBody, SelectiveProblem, SelectiveStatus, StatusResponse, TaggedHTTPError, ValidationError, ValidationErrorResponse, elysiaErrorProblem, internalServerErrorBody, internalServerErrorBodyString, internalServerErrorResponse, isProduction, problem, problemBody, problemResponse, problemTypeOf, status, subValueAt, validationDetail };