@web-ts-toolkit/http-errors 0.31.5 → 0.33.0

package/index.mjs

@@ -1,6 +1,7 @@
 // src/status.ts
+import assert from "assert";
 import { STATUS_CODES } from "http";
-var canonicalStatusByHttpStatus = {
+var canonicalStatusLookup = Object.freeze({
   400: "INVALID_ARGUMENT",
   401: "UNAUTHENTICATED",
   403: "PERMISSION_DENIED",
@@ -12,26 +13,77 @@ var canonicalStatusByHttpStatus = {
   501: "UNIMPLEMENTED",
   503: "UNAVAILABLE",
   504: "DEADLINE_EXCEEDED"
-};
-var getCanonicalStatus = (statusCode) => canonicalStatusByHttpStatus[statusCode] || "UNKNOWN";
+});
+var canonicalStatusByHttpStatus = Object.freeze({
+  ...canonicalStatusLookup
+});
+var getCanonicalStatus = (statusCode) => canonicalStatusLookup[statusCode] || "UNKNOWN";
 var getStatusTitle = (statusCode) => STATUS_CODES[statusCode] || "Unknown Error";
+var isHttpErrorStatusCode = (statusCode) => typeof statusCode === "number" && Number.isFinite(statusCode) && Number.isInteger(statusCode) && statusCode >= 400 && statusCode <= 599;
+var validateHttpErrorStatusCode = (statusCode, source = "statusCode") => {
+  assert.ok(
+    isHttpErrorStatusCode(statusCode),
+    `${source} must be an integer HTTP error status code between 400 and 599`
+  );
+  return statusCode;
+};
+var validateClientErrorStatusCode = (statusCode, source = "statusCode") => {
+  validateHttpErrorStatusCode(statusCode, source);
+  assert.ok(typeof statusCode === "number" && statusCode <= 499, `${source} must be a 4xx HTTP error status code`);
+  return statusCode;
+};
+var validateServerErrorStatusCode = (statusCode, source = "statusCode") => {
+  validateHttpErrorStatusCode(statusCode, source);
+  assert.ok(typeof statusCode === "number" && statusCode >= 500, `${source} must be a 5xx HTTP error status code`);
+  return statusCode;
+};
 
 // src/serialize.ts
 var RFC_9457_DEFAULT_TYPE = "about:blank";
+var RFC_9457_VALIDATION_ERROR_OPTIONAL_FIELDS = ["pointer", "parameter", "header"];
 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.errors !== void 0 ? [{ type: "bad_request", errors: Array.isArray(error.errors) ? [...error.errors] : error.errors }] : [],
     ...error.details ?? []
   ];
 };
-var toRfc9457Errors = (errors) => Array.isArray(errors) ? errors : void 0;
+var toRfc9457Errors = (errors) => Array.isArray(errors) && errors.length > 0 ? [...errors] : void 0;
+var isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+var toRfc9457ValidationError = (value) => {
+  if (!isRecord(value) || !Object.prototype.hasOwnProperty.call(value, "detail") || typeof value.detail !== "string") {
+    return void 0;
+  }
+  const validationError = {
+    detail: value.detail
+  };
+  for (const field of RFC_9457_VALIDATION_ERROR_OPTIONAL_FIELDS) {
+    if (Object.prototype.hasOwnProperty.call(value, field)) {
+      const fieldValue = value[field];
+      if (typeof fieldValue !== "string") {
+        return void 0;
+      }
+      validationError[field] = fieldValue;
+    }
+  }
+  return validationError;
+};
+var toRfc9457ValidationErrors = (errors) => {
+  if (!Array.isArray(errors)) {
+    return void 0;
+  }
+  const validationErrors = errors.flatMap((entry) => {
+    const validationError = toRfc9457ValidationError(entry);
+    return validationError ? [validationError] : [];
+  });
+  return validationErrors.length > 0 ? validationErrors : void 0;
+};
 var createAip193ErrorInfoDetail = (reason, domain, metadata) => ({
   type: "error_info",
   reason,
   domain,
-  ...metadata ? { metadata } : {}
+  ...metadata ? { metadata: { ...metadata } } : {}
 });
 var toAip193ErrorPayload = (error, fallbackDomain = "http-errors") => {
   const status = error.status ?? getCanonicalStatus(error.statusCode);
@@ -45,7 +97,7 @@ var toAip193ErrorPayload = (error, fallbackDomain = "http-errors") => {
     }
   };
 };
-var toRfc9457ErrorPayload = (error) => {
+function toRfc9457ErrorPayload(error) {
   const errors = toRfc9457Errors(error.errors);
   return {
     type: error.type ?? RFC_9457_DEFAULT_TYPE,
@@ -55,67 +107,237 @@ var toRfc9457ErrorPayload = (error) => {
     ...error.instance ? { instance: error.instance } : {},
     ...errors ? { errors } : {}
   };
+}
+var toRfc9457ValidationErrorPayload = (error) => {
+  const errors = toRfc9457ValidationErrors(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 = {
-  400: "The server cannot process the request due to a client error",
-  401: "The user is not authorized",
-  403: "The server refused to authorize the request",
-  404: "The server did not find a current representation for the target resource",
-  405: "The method received is not allowed",
-  406: "The request is not acceptable to the user agent",
-  407: "The client needs to authenticate itself in order to use a proxy",
-  408: "The request was not completed in the expected time",
-  409: "The request was not completed due to a conflict with the target resource",
-  410: "The target resource is no longer available at the origin server",
-  411: "The server refuses to accept the request without a defined Content-Length",
-  412: "One or more conditions given in the request header fields evaluated to false",
-  413: "The request payload is too large",
-  414: "The request target is too long",
-  415: "The payload is in a format not supported",
-  416: "None of the ranges in the request's Range header field overlap the current extent of the selected resource",
-  417: "The expectation given in the request's Expect header field could not be met",
-  418: "I'm a teapot",
-  421: "The request was directed at a server that is not able to produce a response",
-  422: "The server is unable to process the request",
-  423: "The source or destination resource of a method is locked",
-  424: "The requested action depended on another action",
-  426: "This service requires use of a different protocol",
-  428: "This request is required to be conditional",
-  429: "The user has sent too many requests in a given amount of time",
-  431: "Request header fields too large",
-  451: "Denied access due to a consequence of a legal demand",
-  500: "The server encountered an unexpected condition",
-  501: "The server does not support the functionality required to fulfill the request",
-  502: "The server received an invalid response from an upstream server",
-  503: "The server is temporarily unable to handle the request",
-  504: "The server did not receive a timely response from an upstream server",
-  505: "The server does not support the HTTP protocol version used in the request",
-  506: "The server has an internal configuration error",
-  507: "The server is unable to store the representation needed to complete the request",
-  508: "The server detected an infinite loop while processing the request",
-  510: "Further extensions to the request are required for the server to fulfill it",
-  511: "The client needs to authenticate to gain network access"
+// src/status-definitions.ts
+var httpErrorStatusDefinitions = {
+  BadRequestError: {
+    statusCode: 400,
+    category: "client",
+    message: "The server cannot process the request due to a client error"
+  },
+  UnauthorizedError: {
+    statusCode: 401,
+    category: "client",
+    message: "The user is not authorized"
+  },
+  ForbiddenError: {
+    statusCode: 403,
+    category: "client",
+    message: "The server refused to authorize the request"
+  },
+  NotFoundError: {
+    statusCode: 404,
+    category: "client",
+    message: "The server did not find a current representation for the target resource"
+  },
+  MethodNotAllowedError: {
+    statusCode: 405,
+    category: "client",
+    message: "The method received is not allowed"
+  },
+  NotAcceptableError: {
+    statusCode: 406,
+    category: "client",
+    message: "The request is not acceptable to the user agent"
+  },
+  ProxyAuthRequiredError: {
+    statusCode: 407,
+    category: "client",
+    message: "The client needs to authenticate itself in order to use a proxy"
+  },
+  RequestTimeoutError: {
+    statusCode: 408,
+    category: "client",
+    message: "The request was not completed in the expected time"
+  },
+  ConflictError: {
+    statusCode: 409,
+    category: "client",
+    message: "The request was not completed due to a conflict with the target resource"
+  },
+  GoneError: {
+    statusCode: 410,
+    category: "client",
+    message: "The target resource is no longer available at the origin server"
+  },
+  LengthRequiredError: {
+    statusCode: 411,
+    category: "client",
+    message: "The server refuses to accept the request without a defined Content-Length"
+  },
+  PreconditionFailedError: {
+    statusCode: 412,
+    category: "client",
+    message: "One or more conditions given in the request header fields evaluated to false"
+  },
+  PayloadTooLargeError: {
+    statusCode: 413,
+    category: "client",
+    message: "The request payload is too large"
+  },
+  UriTooLongError: {
+    statusCode: 414,
+    category: "client",
+    message: "The request target is too long"
+  },
+  UnsupportedMediaTypeError: {
+    statusCode: 415,
+    category: "client",
+    message: "The payload is in a format not supported"
+  },
+  RequestedRangeNotSatisfiableError: {
+    statusCode: 416,
+    category: "client",
+    message: "None of the ranges in the request's Range header field overlap the current extent of the selected resource"
+  },
+  ExpectationFailedError: {
+    statusCode: 417,
+    category: "client",
+    message: "The expectation given in the request's Expect header field could not be met"
+  },
+  TeapotError: {
+    statusCode: 418,
+    category: "client",
+    message: "I'm a teapot"
+  },
+  MisdirectedRequestError: {
+    statusCode: 421,
+    category: "client",
+    message: "The request was directed at a server that is not able to produce a response"
+  },
+  UnprocessableEntityError: {
+    statusCode: 422,
+    category: "client",
+    message: "The server is unable to process the request"
+  },
+  LockedError: {
+    statusCode: 423,
+    category: "client",
+    message: "The source or destination resource of a method is locked"
+  },
+  FailedDependencyError: {
+    statusCode: 424,
+    category: "client",
+    message: "The requested action depended on another action"
+  },
+  UpgradeRequiredError: {
+    statusCode: 426,
+    category: "client",
+    message: "This service requires use of a different protocol"
+  },
+  PreconditionRequiredError: {
+    statusCode: 428,
+    category: "client",
+    message: "This request is required to be conditional"
+  },
+  TooManyRequestsError: {
+    statusCode: 429,
+    category: "client",
+    message: "The user has sent too many requests in a given amount of time"
+  },
+  RequestHeaderFieldsTooLargeError: {
+    statusCode: 431,
+    category: "client",
+    message: "Request header fields too large"
+  },
+  UnavailableForLegalReasonsError: {
+    statusCode: 451,
+    category: "client",
+    message: "Denied access due to a consequence of a legal demand"
+  },
+  InternalServerError: {
+    statusCode: 500,
+    category: "server",
+    message: "The server encountered an unexpected condition"
+  },
+  NotImplementedError: {
+    statusCode: 501,
+    category: "server",
+    message: "The server does not support the functionality required to fulfill the request"
+  },
+  BadGatewayError: {
+    statusCode: 502,
+    category: "server",
+    message: "The server received an invalid response from an upstream server"
+  },
+  ServiceUnavailableError: {
+    statusCode: 503,
+    category: "server",
+    message: "The server is temporarily unable to handle the request"
+  },
+  GatewayTimeoutError: {
+    statusCode: 504,
+    category: "server",
+    message: "The server did not receive a timely response from an upstream server"
+  },
+  HttpVersionNotSupportedError: {
+    statusCode: 505,
+    category: "server",
+    message: "The server does not support the HTTP protocol version used in the request"
+  },
+  VariantAlsoNegotiatesError: {
+    statusCode: 506,
+    category: "server",
+    message: "The server has an internal configuration error"
+  },
+  InsufficientStorageError: {
+    statusCode: 507,
+    category: "server",
+    message: "The server is unable to store the representation needed to complete the request"
+  },
+  LoopDetectedError: {
+    statusCode: 508,
+    category: "server",
+    message: "The server detected an infinite loop while processing the request"
+  },
+  NotExtendedError: {
+    statusCode: 510,
+    category: "server",
+    message: "Further extensions to the request are required for the server to fulfill it"
+  },
+  NetworkAuthenticationRequiredError: {
+    statusCode: 511,
+    category: "server",
+    message: "The client needs to authenticate to gain network access"
+  }
 };
+
+// src/messages.ts
+var messages = Object.freeze(
+  Object.fromEntries(
+    Object.values(httpErrorStatusDefinitions).map(({ statusCode, message }) => [statusCode, message])
+  )
+);
 var getDefaultMessage = (statusCode) => messages[statusCode] || messages[500];
 
 // src/base.ts
 var ErrorCtor = Error;
 var HttpError = class extends Error {
   constructor(statusCode = 500, message, options = {}) {
-    super(message ?? getDefaultMessage(statusCode), options);
+    const validatedStatusCode = validateHttpErrorStatusCode(statusCode);
+    super(message ?? getDefaultMessage(validatedStatusCode), 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 = status ?? getCanonicalStatus(statusCode);
+    this.statusCode = validatedStatusCode;
+    this.status = status ?? getCanonicalStatus(validatedStatusCode);
     this.date = /* @__PURE__ */ new Date();
     if (reason !== void 0) {
       this.reason = reason;
@@ -125,13 +347,13 @@ var HttpError = class extends Error {
     }
     const normalizedMetadata = toStringRecord(metadata);
     if (normalizedMetadata !== void 0) {
-      this.metadata = normalizedMetadata;
+      this.metadata = Object.freeze(normalizedMetadata);
     }
     if (details !== void 0) {
-      this.details = details;
+      this.details = Object.freeze([...details]);
     }
     if (errors !== void 0) {
-      this.errors = errors;
+      this.errors = Array.isArray(errors) ? Object.freeze([...errors]) : errors;
     }
     if (type !== void 0) {
       this.type = type;
@@ -146,12 +368,12 @@ var HttpError = class extends Error {
 };
 var ClientError = class extends HttpError {
   constructor(statusCode = 400, message, options = {}) {
-    super(statusCode, message, options);
+    super(validateClientErrorStatusCode(statusCode), message, options);
   }
 };
 var ServerError = class extends HttpError {
   constructor(statusCode = 500, message, options = {}) {
-    super(statusCode, message, options);
+    super(validateServerErrorStatusCode(statusCode), message, options);
   }
 };
 
@@ -394,7 +616,11 @@ export {
   createAip193ErrorInfoDetail,
   getCanonicalStatus,
   getStatusTitle,
+  isHttpErrorStatusCode,
   toAip193ErrorPayload,
   toRfc9457ErrorPayload,
-  toRfc9457ValidationErrorPayload
+  toRfc9457ValidationErrorPayload,
+  validateClientErrorStatusCode,
+  validateHttpErrorStatusCode,
+  validateServerErrorStatusCode
 };

package/package.json

@@ -2,7 +2,7 @@
   "name": "@web-ts-toolkit/http-errors",
   "description": "Typed HTTP error classes and payload helpers for backend APIs",
   "homepage": "https://web-ts-toolkit.pages.dev/docs/packages/http-errors",
-  "version": "0.31.5",
+  "version": "0.33.0",
   "sideEffects": false,
   "keywords": [
     "http-errors",
@@ -16,17 +16,21 @@
   "types": "./index.d.ts",
   "exports": {
     ".": {
-      "types": "./index.d.ts",
+      "types": {
+        "import": "./index.d.mts",
+        "require": "./index.d.ts",
+        "default": "./index.d.ts"
+      },
       "import": "./index.mjs",
       "require": "./index.js",
       "default": "./index.js"
     }
   },
   "engines": {
-    "node": ">=20"
+    "node": ">=22"
   },
   "dependencies": {
-    "@web-ts-toolkit/utils": "0.31.5"
+    "@web-ts-toolkit/utils": "0.33.0"
   },
   "files": [
     "**/*",