@web-ts-toolkit/http-errors 0.1.0 → 0.3.0

package/LICENSE

@@ -1,4 +1,3 @@
-
                                  Apache License
                            Version 2.0, January 2004
                         http://www.apache.org/licenses/
@@ -187,7 +186,7 @@
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright © 2017, Province of British Columbia, Canada.
+   Copyright Junmin Ahn
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

package/README.md

@@ -8,9 +8,12 @@ HTTP error classes for backend APIs, including 4xx client errors and 5xx server
 npm install @web-ts-toolkit/http-errors
 ```
 
-## Usage
+## Documentation
 
-### Basic TypeScript usage
+- Full package documentation lives in `website/docs/packages/http-errors.md`.
+- Use the Docusaurus site in `website` for the complete hierarchy, payload helpers, and Express examples.
+
+## Minimal Example
 
 ```ts
 import { HttpError, UnauthorizedError, ServiceUnavailableError } from '@web-ts-toolkit/http-errors';
@@ -23,233 +26,3 @@ throw new HttpError(503, 'please try again later');
 
 throw new ServiceUnavailableError();
 ```
-
-### Use a specific 4xx error
-
-```ts
-import { BadRequestError } from '@web-ts-toolkit/http-errors';
-
-function parseLimit(value: string | undefined): number {
-  const limit = Number(value);
-
-  if (!Number.isInteger(limit) || limit <= 0) {
-    throw new BadRequestError('limit must be a positive integer');
-  }
-
-  return limit;
-}
-```
-
-### Use the category base classes
-
-```ts
-import { ClientError, ServerError } from '@web-ts-toolkit/http-errors';
-
-throw new ClientError(403, 'forbidden project access');
-throw new ServerError(503, 'search index is rebuilding');
-```
-
-### Attach a cause
-
-```ts
-import { ServiceUnavailableError } from '@web-ts-toolkit/http-errors';
-
-try {
-  await fetch('https://api.example.com/health');
-} catch (cause) {
-  throw new ServiceUnavailableError('upstream API is unavailable', { cause });
-}
-```
-
-### Add machine-readable error metadata
-
-```ts
-import { BadRequestError } from '@web-ts-toolkit/http-errors';
-
-throw new BadRequestError('invalid email', {
-  reason: 'INVALID_EMAIL',
-  domain: 'api.example.com',
-  metadata: {
-    field: 'email',
-  },
-  details: [
-    {
-      type: 'help',
-      links: [
-        {
-          description: 'Validation guide',
-          url: 'https://api.example.com/docs/errors/invalid-email',
-        },
-      ],
-    },
-  ],
-  errors: [
-    {
-      field: 'email',
-      description: 'Email must be a valid address.',
-    },
-  ],
-});
-```
-
-The base `HttpError` now carries optional structured fields that are useful when building AIP-193-style error payloads:
-
-- `statusCode`: HTTP status code
-- `status`: canonical status string for common HTTP codes, otherwise `UNKNOWN`
-- `reason`: application-specific machine-readable identifier
-- `domain`: logical error domain such as `api.example.com`
-- `metadata`: stringified key-value metadata
-- `details`: structured detail entries
-- `errors`: validation or field-level error payloads
-
-### Convert an error to an AIP-193-style payload
-
-```ts
-import { BadRequestError, toAip193ErrorPayload } from '@web-ts-toolkit/http-errors';
-
-const error = new BadRequestError('invalid email', {
-  reason: 'INVALID_EMAIL',
-  domain: 'api.example.com',
-  metadata: {
-    field: 'email',
-  },
-});
-
-const payload = toAip193ErrorPayload(error);
-```
-
-### Express route example
-
-```ts
-import express from 'express';
-import { BadRequestError, ForbiddenError, NotFoundError } from '@web-ts-toolkit/http-errors';
-
-type User = {
-  id: string;
-  role: 'admin' | 'member';
-};
-
-type Project = {
-  id: string;
-  ownerId: string;
-  name: string;
-};
-
-const app = express();
-
-const projects = new Map<string, Project>([['project-1', { id: 'project-1', ownerId: 'user-1', name: 'Toolkit' }]]);
-
-app.use(express.json());
-
-app.put('/projects/:id', (req, res) => {
-  const user = req.user as User | undefined;
-  const project = projects.get(req.params.id);
-
-  if (!user) {
-    throw new ForbiddenError('authentication required');
-  }
-
-  if (!project) {
-    throw new NotFoundError('project was not found');
-  }
-
-  if (project.ownerId !== user.id && user.role !== 'admin') {
-    throw new ForbiddenError('you cannot update this project');
-  }
-
-  if (typeof req.body.name !== 'string' || req.body.name.trim() === '') {
-    throw new BadRequestError('name is required');
-  }
-
-  project.name = req.body.name.trim();
-  res.json(project);
-});
-```
-
-### Express error middleware example
-
-```ts
-import type { NextFunction, Request, Response } from 'express';
-import express from 'express';
-import { HttpError, InternalServerError } from '@web-ts-toolkit/http-errors';
-
-const app = express();
-
-app.use((err: unknown, _req: Request, res: Response, _next: NextFunction) => {
-  if (err instanceof HttpError) {
-    return res.status(err.statusCode).json({
-      error: {
-        name: err.name,
-        message: err.message,
-        statusCode: err.statusCode,
-      },
-    });
-  }
-
-  const fallback = new InternalServerError('unexpected server error');
-
-  return res.status(fallback.statusCode).json({
-    error: {
-      name: fallback.name,
-      message: fallback.message,
-      statusCode: fallback.statusCode,
-    },
-  });
-});
-```
-
-## Error Hierarchy
-
-`HttpError` is the neutral base class for HTTP responses.
-
-`ClientError` is the base class for 4xx responses.
-
-`ServerError` is the base class for 5xx responses.
-
-## Client Errors
-
-| Code | Description                     | Class Name                        | Default Message                                                                                            |
-| ---- | ------------------------------- | --------------------------------- | ---------------------------------------------------------------------------------------------------------- |
-| 400  | Bad Request                     | BadRequestError                   | The server cannot process the request due to a client error                                                |
-| 401  | Unauthorized                    | UnauthorizedError                 | The user is not authorized                                                                                 |
-| 403  | Forbidden                       | ForbiddenError                    | The server refused to authorize the request                                                                |
-| 404  | Not Found                       | NotFoundError                     | The server did not find a current representation for the target resource                                   |
-| 405  | Method Not Allowed              | MethodNotAllowedError             | The method received is not allowed                                                                         |
-| 406  | Not Acceptable                  | NotAcceptableError                | The request is not acceptable to the user agent                                                            |
-| 407  | Proxy Authentication Required   | ProxyAuthRequiredError            | The client needs to authenticate itself in order to use a proxy                                            |
-| 408  | Request Timeout                 | RequestTimeoutError               | The request was not completed in the expected time                                                         |
-| 409  | Conflict                        | ConflictError                     | The request was not completed due to a conflict with the target resource                                   |
-| 410  | Gone                            | GoneError                         | The target resource is no longer available at the origin server                                            |
-| 411  | Length Required                 | LengthRequiredError               | The server refuses to accept the request without a defined Content-Length                                  |
-| 412  | Precondition Failed             | PreconditionFailedError           | One or more conditions given in the request header fields evaluated to false                               |
-| 413  | Payload Too Large               | PayloadTooLargeError              | The request payload is too large                                                                           |
-| 414  | URI Too Long                    | UriTooLongError                   | The request target is too long                                                                             |
-| 415  | Unsupported Media Type          | UnsupportedMediaTypeError         | The payload is in a format not supported                                                                   |
-| 416  | Requested Range Not Satisfiable | RequestedRangeNotSatisfiableError | None of the ranges in the request's Range header field overlap the current extent of the selected resource |
-| 417  | Expectation Failed              | ExpectationFailedError            | The expectation given in the request's Expect header field could not be met                                |
-| 418  | I'm a teapot                    | TeapotError                       | I'm a teapot                                                                                               |
-| 421  | Misdirected Request             | MisdirectedRequestError           | The request was directed at a server that is not able to produce a response                                |
-| 422  | Unprocessable Entity            | UnprocessableEntityError          | The server is unable to process the request                                                                |
-| 423  | Locked                          | LockedError                       | The source or destination resource of a method is locked                                                   |
-| 424  | Failed Dependency               | FailedDependencyError             | The requested action depended on another action                                                            |
-| 426  | Upgrade Required                | UpgradeRequiredError              | This service requires use of a different protocol                                                          |
-| 428  | Precondition Required           | PreconditionRequiredError         | This request is required to be conditional                                                                 |
-| 429  | Too Many Requests               | TooManyRequestsError              | The user has sent too many requests in a given amount of time                                              |
-| 431  | Request Header Fields Too Large | RequestHeaderFieldsTooLargeError  | Request header fields too large                                                                            |
-| 451  | Unavailable For Legal Reasons   | UnavailableForLegalReasonsError   | Denied access due to a consequence of a legal demand                                                       |
-
-## Server Errors
-
-| Code | Description                     | Class Name                         | Default Message                                                                 |
-| ---- | ------------------------------- | ---------------------------------- | ------------------------------------------------------------------------------- |
-| 500  | Internal Server Error           | InternalServerError                | The server encountered an unexpected condition                                  |
-| 501  | Not Implemented                 | NotImplementedError                | The server does not support the functionality required to fulfill the request   |
-| 502  | Bad Gateway                     | BadGatewayError                    | The server received an invalid response from an upstream server                 |
-| 503  | Service Unavailable             | ServiceUnavailableError            | The server is temporarily unable to handle the request                          |
-| 504  | Gateway Timeout                 | GatewayTimeoutError                | The server did not receive a timely response from an upstream server            |
-| 505  | HTTP Version Not Supported      | HttpVersionNotSupportedError       | The server does not support the HTTP protocol version used in the request       |
-| 506  | Variant Also Negotiates         | VariantAlsoNegotiatesError         | The server has an internal configuration error                                  |
-| 507  | Insufficient Storage            | InsufficientStorageError           | The server is unable to store the representation needed to complete the request |
-| 508  | Loop Detected                   | LoopDetectedError                  | The server detected an infinite loop while processing the request               |
-| 510  | Not Extended                    | NotExtendedError                   | Further extensions to the request are required for the server to fulfill it     |
-| 511  | Network Authentication Required | NetworkAuthenticationRequiredError | The client needs to authenticate to gain network access                         |

package/index.d.mts

@@ -1,5 +1,10 @@
 type HttpErrorMetadataValue = string | number | boolean | bigint | null | undefined;
-type HttpErrorOptions = ErrorOptions & {
+type HttpErrorProblemFields = {
+    type?: string;
+    title?: string;
+    instance?: string;
+};
+type HttpErrorOptions = ErrorOptions & HttpErrorProblemFields & {
     status?: string;
     reason?: string;
     domain?: string;
@@ -7,7 +12,7 @@ type HttpErrorOptions = ErrorOptions & {
     details?: unknown[];
     errors?: unknown;
 };
-type HttpErrorShape = {
+type HttpErrorShape = HttpErrorProblemFields & {
     statusCode: number;
     status?: string;
     message: string;
@@ -31,6 +36,20 @@ type Aip193ErrorPayload = {
         details?: unknown[];
     };
 };
+type Rfc9457ErrorPayload<TError = unknown> = {
+    type?: string;
+    title?: string;
+    status?: number;
+    detail?: string;
+    instance?: string;
+    errors?: TError[];
+};
+type Rfc9457ValidationError = {
+    detail: string;
+    pointer?: string;
+    parameter?: string;
+    header?: string;
+};
 
 declare const canonicalStatusByHttpStatus: {
     readonly 400: "INVALID_ARGUMENT";
@@ -46,9 +65,12 @@ declare const canonicalStatusByHttpStatus: {
     readonly 504: "DEADLINE_EXCEEDED";
 };
 declare const getCanonicalStatus: (statusCode: number) => string;
+declare const getStatusTitle: (statusCode: number) => string;
 
 declare const createAip193ErrorInfoDetail: (reason: string, domain: string, metadata?: Record<string, string>) => Aip193ErrorInfoDetail;
 declare const toAip193ErrorPayload: (error: HttpErrorShape, fallbackDomain?: string) => Aip193ErrorPayload;
+declare const toRfc9457ErrorPayload: <TError = unknown>(error: HttpErrorShape) => Rfc9457ErrorPayload<TError>;
+declare const toRfc9457ValidationErrorPayload: (error: HttpErrorShape) => Rfc9457ErrorPayload<Rfc9457ValidationError>;
 
 declare class HttpError extends Error {
     readonly statusCode: number;
@@ -59,6 +81,9 @@ declare class HttpError extends Error {
     readonly metadata?: Record<string, string>;
     readonly details?: unknown[];
     readonly errors?: unknown;
+    readonly type?: string;
+    readonly title?: string;
+    readonly instance?: string;
     constructor(statusCode?: number, message?: string, options?: HttpErrorOptions);
 }
 declare class ClientError extends HttpError {
@@ -184,4 +209,4 @@ declare class NetworkAuthenticationRequiredError extends ServerError {
     constructor(message?: string, options?: HttpErrorOptions);
 }
 
-export { type Aip193ErrorInfoDetail, type Aip193ErrorPayload, BadGatewayError, BadRequestError, ClientError, ConflictError, ExpectationFailedError, FailedDependencyError, ForbiddenError, GatewayTimeoutError, GoneError, HttpError, type HttpErrorMetadataValue, type HttpErrorOptions, type HttpErrorShape, HttpVersionNotSupportedError, InsufficientStorageError, InternalServerError, LengthRequiredError, LockedError, LoopDetectedError, MethodNotAllowedError, MisdirectedRequestError, NetworkAuthenticationRequiredError, NotAcceptableError, NotExtendedError, NotFoundError, NotImplementedError, PayloadTooLargeError, PreconditionFailedError, PreconditionRequiredError, ProxyAuthRequiredError, RequestHeaderFieldsTooLargeError, RequestTimeoutError, RequestedRangeNotSatisfiableError, ServerError, ServiceUnavailableError, TeapotError, TooManyRequestsError, UnauthorizedError, UnavailableForLegalReasonsError, UnprocessableEntityError, UnsupportedMediaTypeError, UpgradeRequiredError, UriTooLongError, VariantAlsoNegotiatesError, canonicalStatusByHttpStatus, createAip193ErrorInfoDetail, getCanonicalStatus, toAip193ErrorPayload };
+export { type Aip193ErrorInfoDetail, type Aip193ErrorPayload, BadGatewayError, BadRequestError, ClientError, ConflictError, ExpectationFailedError, FailedDependencyError, ForbiddenError, GatewayTimeoutError, GoneError, HttpError, type HttpErrorMetadataValue, type HttpErrorOptions, type HttpErrorProblemFields, type HttpErrorShape, HttpVersionNotSupportedError, InsufficientStorageError, InternalServerError, LengthRequiredError, LockedError, LoopDetectedError, MethodNotAllowedError, MisdirectedRequestError, NetworkAuthenticationRequiredError, NotAcceptableError, NotExtendedError, NotFoundError, NotImplementedError, PayloadTooLargeError, PreconditionFailedError, PreconditionRequiredError, ProxyAuthRequiredError, RequestHeaderFieldsTooLargeError, RequestTimeoutError, RequestedRangeNotSatisfiableError, type Rfc9457ErrorPayload, type Rfc9457ValidationError, ServerError, ServiceUnavailableError, TeapotError, TooManyRequestsError, UnauthorizedError, UnavailableForLegalReasonsError, UnprocessableEntityError, UnsupportedMediaTypeError, UpgradeRequiredError, UriTooLongError, VariantAlsoNegotiatesError, canonicalStatusByHttpStatus, createAip193ErrorInfoDetail, getCanonicalStatus, getStatusTitle, toAip193ErrorPayload, toRfc9457ErrorPayload, toRfc9457ValidationErrorPayload };

package/index.d.ts

@@ -1,5 +1,10 @@
 type HttpErrorMetadataValue = string | number | boolean | bigint | null | undefined;
-type HttpErrorOptions = ErrorOptions & {
+type HttpErrorProblemFields = {
+    type?: string;
+    title?: string;
+    instance?: string;
+};
+type HttpErrorOptions = ErrorOptions & HttpErrorProblemFields & {
     status?: string;
     reason?: string;
     domain?: string;
@@ -7,7 +12,7 @@ type HttpErrorOptions = ErrorOptions & {
     details?: unknown[];
     errors?: unknown;
 };
-type HttpErrorShape = {
+type HttpErrorShape = HttpErrorProblemFields & {
     statusCode: number;
     status?: string;
     message: string;
@@ -31,6 +36,20 @@ type Aip193ErrorPayload = {
         details?: unknown[];
     };
 };
+type Rfc9457ErrorPayload<TError = unknown> = {
+    type?: string;
+    title?: string;
+    status?: number;
+    detail?: string;
+    instance?: string;
+    errors?: TError[];
+};
+type Rfc9457ValidationError = {
+    detail: string;
+    pointer?: string;
+    parameter?: string;
+    header?: string;
+};
 
 declare const canonicalStatusByHttpStatus: {
     readonly 400: "INVALID_ARGUMENT";
@@ -46,9 +65,12 @@ declare const canonicalStatusByHttpStatus: {
     readonly 504: "DEADLINE_EXCEEDED";
 };
 declare const getCanonicalStatus: (statusCode: number) => string;
+declare const getStatusTitle: (statusCode: number) => string;
 
 declare const createAip193ErrorInfoDetail: (reason: string, domain: string, metadata?: Record<string, string>) => Aip193ErrorInfoDetail;
 declare const toAip193ErrorPayload: (error: HttpErrorShape, fallbackDomain?: string) => Aip193ErrorPayload;
+declare const toRfc9457ErrorPayload: <TError = unknown>(error: HttpErrorShape) => Rfc9457ErrorPayload<TError>;
+declare const toRfc9457ValidationErrorPayload: (error: HttpErrorShape) => Rfc9457ErrorPayload<Rfc9457ValidationError>;
 
 declare class HttpError extends Error {
     readonly statusCode: number;
@@ -59,6 +81,9 @@ declare class HttpError extends Error {
     readonly metadata?: Record<string, string>;
     readonly details?: unknown[];
     readonly errors?: unknown;
+    readonly type?: string;
+    readonly title?: string;
+    readonly instance?: string;
     constructor(statusCode?: number, message?: string, options?: HttpErrorOptions);
 }
 declare class ClientError extends HttpError {
@@ -184,4 +209,4 @@ declare class NetworkAuthenticationRequiredError extends ServerError {
     constructor(message?: string, options?: HttpErrorOptions);
 }
 
-export { type Aip193ErrorInfoDetail, type Aip193ErrorPayload, BadGatewayError, BadRequestError, ClientError, ConflictError, ExpectationFailedError, FailedDependencyError, ForbiddenError, GatewayTimeoutError, GoneError, HttpError, type HttpErrorMetadataValue, type HttpErrorOptions, type HttpErrorShape, HttpVersionNotSupportedError, InsufficientStorageError, InternalServerError, LengthRequiredError, LockedError, LoopDetectedError, MethodNotAllowedError, MisdirectedRequestError, NetworkAuthenticationRequiredError, NotAcceptableError, NotExtendedError, NotFoundError, NotImplementedError, PayloadTooLargeError, PreconditionFailedError, PreconditionRequiredError, ProxyAuthRequiredError, RequestHeaderFieldsTooLargeError, RequestTimeoutError, RequestedRangeNotSatisfiableError, ServerError, ServiceUnavailableError, TeapotError, TooManyRequestsError, UnauthorizedError, UnavailableForLegalReasonsError, UnprocessableEntityError, UnsupportedMediaTypeError, UpgradeRequiredError, UriTooLongError, VariantAlsoNegotiatesError, canonicalStatusByHttpStatus, createAip193ErrorInfoDetail, getCanonicalStatus, toAip193ErrorPayload };
+export { type Aip193ErrorInfoDetail, type Aip193ErrorPayload, BadGatewayError, BadRequestError, ClientError, ConflictError, ExpectationFailedError, FailedDependencyError, ForbiddenError, GatewayTimeoutError, GoneError, HttpError, type HttpErrorMetadataValue, type HttpErrorOptions, type HttpErrorProblemFields, type HttpErrorShape, HttpVersionNotSupportedError, InsufficientStorageError, InternalServerError, LengthRequiredError, LockedError, LoopDetectedError, MethodNotAllowedError, MisdirectedRequestError, NetworkAuthenticationRequiredError, NotAcceptableError, NotExtendedError, NotFoundError, NotImplementedError, PayloadTooLargeError, PreconditionFailedError, PreconditionRequiredError, ProxyAuthRequiredError, RequestHeaderFieldsTooLargeError, RequestTimeoutError, RequestedRangeNotSatisfiableError, type Rfc9457ErrorPayload, type Rfc9457ValidationError, ServerError, ServiceUnavailableError, TeapotError, TooManyRequestsError, UnauthorizedError, UnavailableForLegalReasonsError, UnprocessableEntityError, UnsupportedMediaTypeError, UpgradeRequiredError, UriTooLongError, VariantAlsoNegotiatesError, canonicalStatusByHttpStatus, createAip193ErrorInfoDetail, getCanonicalStatus, getStatusTitle, toAip193ErrorPayload, toRfc9457ErrorPayload, toRfc9457ValidationErrorPayload };

package/index.js

@@ -64,11 +64,15 @@ __export(index_exports, {
   canonicalStatusByHttpStatus: () => canonicalStatusByHttpStatus,
   createAip193ErrorInfoDetail: () => createAip193ErrorInfoDetail,
   getCanonicalStatus: () => getCanonicalStatus,
-  toAip193ErrorPayload: () => toAip193ErrorPayload
+  getStatusTitle: () => getStatusTitle,
+  toAip193ErrorPayload: () => toAip193ErrorPayload,
+  toRfc9457ErrorPayload: () => toRfc9457ErrorPayload,
+  toRfc9457ValidationErrorPayload: () => toRfc9457ValidationErrorPayload
 });
 module.exports = __toCommonJS(index_exports);
 
 // src/status.ts
+var import_node_http = require("http");
 var canonicalStatusByHttpStatus = {
   400: "INVALID_ARGUMENT",
   401: "UNAUTHENTICATED",
@@ -83,8 +87,19 @@ var canonicalStatusByHttpStatus = {
   504: "DEADLINE_EXCEEDED"
 };
 var getCanonicalStatus = (statusCode) => canonicalStatusByHttpStatus[statusCode] || "UNKNOWN";
+var getStatusTitle = (statusCode) => import_node_http.STATUS_CODES[statusCode] || "Unknown Error";
 
 // src/serialize.ts
+var RFC_9457_DEFAULT_TYPE = "about:blank";
+var toAip193ErrorDetails = (error, fallbackDomain) => {
+  const status = error.status ?? getCanonicalStatus(error.statusCode);
+  return [
+    createAip193ErrorInfoDetail(error.reason ?? status, error.domain ?? fallbackDomain, error.metadata),
+    ...error.errors !== void 0 ? [{ type: "bad_request", errors: error.errors }] : [],
+    ...error.details ?? []
+  ];
+};
+var toRfc9457Errors = (errors) => Array.isArray(errors) ? errors : void 0;
 var createAip193ErrorInfoDetail = (reason, domain, metadata) => ({
   type: "error_info",
   reason,
@@ -92,21 +107,32 @@ var createAip193ErrorInfoDetail = (reason, domain, metadata) => ({
   ...metadata ? { metadata } : {}
 });
 var toAip193ErrorPayload = (error, fallbackDomain = "http-errors") => {
-  const status = error.status || getCanonicalStatus(error.statusCode);
-  const details = [
-    createAip193ErrorInfoDetail(error.reason || status, error.domain || fallbackDomain, error.metadata),
-    ...error.errors !== void 0 ? [{ type: "bad_request", errors: error.errors }] : [],
-    ...error.details || []
-  ];
+  const status = error.status ?? getCanonicalStatus(error.statusCode);
+  const details = toAip193ErrorDetails(error, fallbackDomain);
   return {
     error: {
       code: error.statusCode,
       status,
       message: error.message,
-      ...details.length > 0 ? { details } : {}
+      details
     }
   };
 };
+var toRfc9457ErrorPayload = (error) => {
+  const errors = toRfc9457Errors(error.errors);
+  return {
+    type: error.type ?? RFC_9457_DEFAULT_TYPE,
+    title: error.title ?? getStatusTitle(error.statusCode),
+    status: error.statusCode,
+    detail: error.message,
+    ...error.instance ? { instance: error.instance } : {},
+    ...errors ? { errors } : {}
+  };
+};
+var toRfc9457ValidationErrorPayload = (error) => toRfc9457ErrorPayload(error);
+
+// src/base.ts
+var import_utils = require("@web-ts-toolkit/utils");
 
 // src/messages.ts
 var messages = {
@@ -153,39 +179,41 @@ var getDefaultMessage = (statusCode) => messages[statusCode] || messages[500];
 
 // src/base.ts
 var ErrorCtor = Error;
-var toMetadata = (metadata) => {
-  if (!metadata) {
-    return void 0;
-  }
-  return Object.entries(metadata).reduce((result, [key, value]) => {
-    result[key] = String(value);
-    return result;
-  }, {});
-};
 var HttpError = class extends Error {
   constructor(statusCode = 500, message, options = {}) {
-    super(message || getDefaultMessage(statusCode), options);
+    super(message ?? getDefaultMessage(statusCode), options);
+    const { status, reason, domain, metadata, details, errors, type, title, instance } = options;
     if (ErrorCtor.captureStackTrace) {
       ErrorCtor.captureStackTrace(this, this.constructor);
     }
     this.name = this.constructor.name;
     this.statusCode = statusCode;
-    this.status = options.status || getCanonicalStatus(statusCode);
+    this.status = status ?? getCanonicalStatus(statusCode);
     this.date = /* @__PURE__ */ new Date();
-    if (options.reason) {
-      this.reason = options.reason;
+    if (reason !== void 0) {
+      this.reason = reason;
+    }
+    if (domain !== void 0) {
+      this.domain = domain;
+    }
+    const normalizedMetadata = (0, import_utils.toStringRecord)(metadata);
+    if (normalizedMetadata !== void 0) {
+      this.metadata = normalizedMetadata;
+    }
+    if (details !== void 0) {
+      this.details = details;
     }
-    if (options.domain) {
-      this.domain = options.domain;
+    if (errors !== void 0) {
+      this.errors = errors;
     }
-    if (options.metadata) {
-      this.metadata = toMetadata(options.metadata);
+    if (type !== void 0) {
+      this.type = type;
     }
-    if (options.details) {
-      this.details = options.details;
+    if (title !== void 0) {
+      this.title = title;
     }
-    if (options.errors !== void 0) {
-      this.errors = options.errors;
+    if (instance !== void 0) {
+      this.instance = instance;
     }
   }
 };
@@ -439,5 +467,8 @@ var NetworkAuthenticationRequiredError = class extends ServerError {
   canonicalStatusByHttpStatus,
   createAip193ErrorInfoDetail,
   getCanonicalStatus,
-  toAip193ErrorPayload
+  getStatusTitle,
+  toAip193ErrorPayload,
+  toRfc9457ErrorPayload,
+  toRfc9457ValidationErrorPayload
 });

package/index.mjs

@@ -1,4 +1,5 @@
 // src/status.ts
+import { STATUS_CODES } from "http";
 var canonicalStatusByHttpStatus = {
   400: "INVALID_ARGUMENT",
   401: "UNAUTHENTICATED",
@@ -13,8 +14,19 @@ var canonicalStatusByHttpStatus = {
   504: "DEADLINE_EXCEEDED"
 };
 var getCanonicalStatus = (statusCode) => canonicalStatusByHttpStatus[statusCode] || "UNKNOWN";
+var getStatusTitle = (statusCode) => STATUS_CODES[statusCode] || "Unknown Error";
 
 // src/serialize.ts
+var RFC_9457_DEFAULT_TYPE = "about:blank";
+var toAip193ErrorDetails = (error, fallbackDomain) => {
+  const status = error.status ?? getCanonicalStatus(error.statusCode);
+  return [
+    createAip193ErrorInfoDetail(error.reason ?? status, error.domain ?? fallbackDomain, error.metadata),
+    ...error.errors !== void 0 ? [{ type: "bad_request", errors: error.errors }] : [],
+    ...error.details ?? []
+  ];
+};
+var toRfc9457Errors = (errors) => Array.isArray(errors) ? errors : void 0;
 var createAip193ErrorInfoDetail = (reason, domain, metadata) => ({
   type: "error_info",
   reason,
@@ -22,21 +34,32 @@ var createAip193ErrorInfoDetail = (reason, domain, metadata) => ({
   ...metadata ? { metadata } : {}
 });
 var toAip193ErrorPayload = (error, fallbackDomain = "http-errors") => {
-  const status = error.status || getCanonicalStatus(error.statusCode);
-  const details = [
-    createAip193ErrorInfoDetail(error.reason || status, error.domain || fallbackDomain, error.metadata),
-    ...error.errors !== void 0 ? [{ type: "bad_request", errors: error.errors }] : [],
-    ...error.details || []
-  ];
+  const status = error.status ?? getCanonicalStatus(error.statusCode);
+  const details = toAip193ErrorDetails(error, fallbackDomain);
   return {
     error: {
       code: error.statusCode,
       status,
       message: error.message,
-      ...details.length > 0 ? { details } : {}
+      details
     }
   };
 };
+var toRfc9457ErrorPayload = (error) => {
+  const errors = toRfc9457Errors(error.errors);
+  return {
+    type: error.type ?? RFC_9457_DEFAULT_TYPE,
+    title: error.title ?? getStatusTitle(error.statusCode),
+    status: error.statusCode,
+    detail: error.message,
+    ...error.instance ? { instance: error.instance } : {},
+    ...errors ? { errors } : {}
+  };
+};
+var toRfc9457ValidationErrorPayload = (error) => toRfc9457ErrorPayload(error);
+
+// src/base.ts
+import { toStringRecord } from "@web-ts-toolkit/utils";
 
 // src/messages.ts
 var messages = {
@@ -83,39 +106,41 @@ var getDefaultMessage = (statusCode) => messages[statusCode] || messages[500];
 
 // src/base.ts
 var ErrorCtor = Error;
-var toMetadata = (metadata) => {
-  if (!metadata) {
-    return void 0;
-  }
-  return Object.entries(metadata).reduce((result, [key, value]) => {
-    result[key] = String(value);
-    return result;
-  }, {});
-};
 var HttpError = class extends Error {
   constructor(statusCode = 500, message, options = {}) {
-    super(message || getDefaultMessage(statusCode), options);
+    super(message ?? getDefaultMessage(statusCode), options);
+    const { status, reason, domain, metadata, details, errors, type, title, instance } = options;
     if (ErrorCtor.captureStackTrace) {
       ErrorCtor.captureStackTrace(this, this.constructor);
     }
     this.name = this.constructor.name;
     this.statusCode = statusCode;
-    this.status = options.status || getCanonicalStatus(statusCode);
+    this.status = status ?? getCanonicalStatus(statusCode);
     this.date = /* @__PURE__ */ new Date();
-    if (options.reason) {
-      this.reason = options.reason;
+    if (reason !== void 0) {
+      this.reason = reason;
+    }
+    if (domain !== void 0) {
+      this.domain = domain;
+    }
+    const normalizedMetadata = toStringRecord(metadata);
+    if (normalizedMetadata !== void 0) {
+      this.metadata = normalizedMetadata;
+    }
+    if (details !== void 0) {
+      this.details = details;
     }
-    if (options.domain) {
-      this.domain = options.domain;
+    if (errors !== void 0) {
+      this.errors = errors;
     }
-    if (options.metadata) {
-      this.metadata = toMetadata(options.metadata);
+    if (type !== void 0) {
+      this.type = type;
     }
-    if (options.details) {
-      this.details = options.details;
+    if (title !== void 0) {
+      this.title = title;
     }
-    if (options.errors !== void 0) {
-      this.errors = options.errors;
+    if (instance !== void 0) {
+      this.instance = instance;
     }
   }
 };
@@ -368,5 +393,8 @@ export {
   canonicalStatusByHttpStatus,
   createAip193ErrorInfoDetail,
   getCanonicalStatus,
-  toAip193ErrorPayload
+  getStatusTitle,
+  toAip193ErrorPayload,
+  toRfc9457ErrorPayload,
+  toRfc9457ValidationErrorPayload
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@web-ts-toolkit/http-errors",
   "description": "HTTP error classes for backend APIs",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "keywords": [
     "http-errors",
     "api-errors"
@@ -17,7 +17,10 @@
       "default": "./index.js"
     }
   },
-  "author": "Junmin Dev",
+  "dependencies": {
+    "@web-ts-toolkit/utils": "0.3.0"
+  },
+  "author": "Junmin Ahn",
   "bugs": {
     "url": "https://github.com/egose/web-ts-toolkit/issues"
   },