@boo-labs/server 0.0.0-stage → 1.0.0

package/source/shared/errors/PathnamePatternError/index.mjs

@@ -0,0 +1,103 @@
+/**
+ * @file Defines domain-specific errors for pathname pattern validation.
+ *
+ * @description PathnamePatternError extends BaseError to provide structured,
+ * identifiable errors specific to pathname pattern validation. It centralizes
+ * error messages and supports template placeholders for dynamic context.
+ *
+ * @module PathnamePatternError
+ */
+
+// ━━ IMPORT MODULES ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// » IMPORT LOCAL MODULES
+import BaseError from '../BaseError/index.mjs';
+
+// ━━ TYPE DEFINITIONS ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+/**
+ * @template {string} T
+ * @typedef {T | (string & {})} LiteralUnion
+ */
+
+/**
+ * Identifies a predefined pathname pattern error or allows a custom error message.
+ *
+ * @typedef {LiteralUnion<
+ * 'INVALID_PATTERN_TYPE' |
+ * 'EMPTY_PATTERN' |
+ * 'PATTERN_TOO_LONG' |
+ * 'INVALID_PATHNAME_PATTERN' |
+ * 'DUPLICATE_PARAMETER_NAME'
+ * >} PathnamePatternErrorIdentifier
+ */
+
+/**
+ * Options for creating an error instance.
+ *
+ * @typedef  {object}                  PathnamePatternErrorOptions
+ * @property {Record<string, unknown>} [values]                    - Values for template placeholders in the error message.
+ * @property {unknown}                 [details]                   - Additional contextual information about the error.
+ * @property {Error}                   [cause]                     - The original error that caused this error (for error chaining).
+ */
+
+// ━━ MODULE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+/**
+ * Error thrown when a pathname pattern cannot be validated.
+ *
+ * @classdesc This error type provides identifiable failures related to pathname
+ * pattern syntax and validation.
+ *
+ * @augments BaseError
+ * @private
+ */
+class PathnamePatternError extends BaseError {
+  /**
+   * Creates a new {@link PathnamePatternError}.
+   *
+   * @param {PathnamePatternErrorIdentifier} identifier - A predefined error identifier or a custom error message.
+   * @param {PathnamePatternErrorOptions} [options] - Additional information used to format the message, attach domain details, or preserve the original cause.
+   * @example
+   * ```js
+   * throw new PathnamePatternError('INVALID_PATHNAME_PATTERN', {
+   *   values: {
+   *     pattern: '/users/:id',
+   *   },
+   * });
+   * ```
+   * @example
+   * ```js
+   * throw new PathnamePatternError('EMPTY_PATTERN');
+   * ```
+   */
+  constructor(identifier, options = {}) {
+    super(identifier, options);
+  }
+
+  /**
+   * Collection of predefined pathname pattern error messages.
+   *
+   * Available error identifiers:
+   *
+   * - `'INVALID_PATTERN_TYPE'`.
+   * - `'EMPTY_PATTERN'`.
+   * - `'PATTERN_TOO_LONG'`.
+   * - `'INVALID_PATHNAME_PATTERN'`.
+   * - `'DUPLICATE_PARAMETER_NAME'`.
+   *
+   * @private
+   * @static
+   * @type {Map<PathnamePatternErrorIdentifier, string>}
+   */
+  static MESSAGES = new Map([
+    ['INVALID_PATTERN_TYPE', 'Expected pattern to be a {expected}, but received {received}.'],
+    ['EMPTY_PATTERN', 'Pathname pattern must not be empty.'],
+    [
+      'PATTERN_TOO_LONG',
+      'Pathname pattern length ({actualLength}) exceeds the maximum allowed limit of {maxLength} characters.',
+    ],
+    ['INVALID_PATHNAME_PATTERN', 'Invalid pathname pattern: "{pattern}".'],
+    ['DUPLICATE_PARAMETER_NAME', 'Duplicate parameter name: "{name}" in pattern.'],
+  ]);
+}
+
+// ━━ EXPORT MODULE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+export default PathnamePatternError;

package/source/shared/errors/RequestError/index.mjs

@@ -0,0 +1,116 @@
+/**
+ * @file Defines domain-specific errors for request processing.
+ *
+ * @description RequestError extends BaseError to provide structured,
+ * identifiable errors specific to request validation, body parsing,
+ * and stream consumption. It centralizes error messages and supports
+ * template placeholders for dynamic context.
+ *
+ * @module RequestError
+ */
+
+// ━━ IMPORT MODULES ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// » IMPORT LOCAL MODULES
+import BaseError from '../BaseError/index.mjs';
+
+// ━━ TYPE DEFINITIONS ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+/**
+ * @template {string} T
+ * @typedef {T | (string & {})} LiteralUnion
+ */
+
+/**
+ * Identifies a predefined request error or allows a custom error message.
+ *
+ * @typedef {LiteralUnion<
+ * 'UNSUPPORTED_MEDIA_TYPE' |
+ * 'BODY_PARSE_FAILED' |
+ * 'BODY_LIMIT_EXCEEDED' |
+ * 'MISSING_METHOD' |
+ * 'INVALID_REQUEST_URL' |
+ * 'BODY_STREAM_ERROR' |
+ * 'INVALID_CONTENT_LENGTH' |
+ * 'MISSING_HOST' |
+ * 'INVALID_TRANSFER_ENCODING'
+ * >} RequestErrorIdentifier
+ */
+
+/**
+ * Options for creating an error instance.
+ *
+ * @typedef  {object}                  RequestErrorOptions
+ * @property {Record<string, unknown>} [values]            - Values for template placeholders in the error message.
+ * @property {unknown}                 [details]           - Additional contextual information about the error.
+ * @property {Error}                   [cause]             - The original error that caused this error.
+ */
+
+// ━━ MODULE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+/**
+ * Error thrown when an incoming request cannot be processed.
+ *
+ * @classdesc This error type provides identifiable failures related to
+ * incoming request validation, body parsing limits, and stream consumption.
+ *
+ * @augments BaseError
+ * @private
+ */
+class RequestError extends BaseError {
+  /**
+   * Creates a new {@link RequestError}.
+   *
+   * @param {RequestErrorIdentifier} identifier - A predefined error identifier or a custom error message.
+   * @param {RequestErrorOptions} [options] - Additional information used to format the message, attach domain details, or preserve the original cause.
+   * @example
+   * ```js
+   * throw new RequestError('UNSUPPORTED_MEDIA_TYPE', {
+   *   values: { mediaType: 'text/xml' },
+   * });
+   * ```
+   * @example
+   * ```js
+   * throw new RequestError('BODY_LIMIT_EXCEEDED', {
+   *   values: { bodySize: 15000000, bodyLimit: 10000000 },
+   * });
+   * ```
+   */
+  constructor(identifier, options = {}) {
+    super(identifier, options);
+  }
+
+  /**
+   * Collection of predefined request error messages.
+   *
+   * Available error identifiers:
+   *
+   * - `'UNSUPPORTED_MEDIA_TYPE'`.
+   * - `'BODY_PARSE_FAILED'`.
+   * - `'BODY_LIMIT_EXCEEDED'`.
+   * - `'MISSING_METHOD'`.
+   * - `'INVALID_REQUEST_URL'`.
+   * - `'BODY_STREAM_ERROR'`.
+   * - `'INVALID_CONTENT_LENGTH'`.
+   * - `'MISSING_HOST'`.
+   * - `'INVALID_TRANSFER_ENCODING'`.
+   *
+   * @private
+   * @static
+   * @type {Map<RequestErrorIdentifier, string>}
+   */
+  static MESSAGES = new Map([
+    ['UNSUPPORTED_MEDIA_TYPE', 'Unsupported media type: {mediaType}.'],
+    ['BODY_PARSE_FAILED', 'Request body could not be parsed: {reason}.'],
+    [
+      'BODY_LIMIT_EXCEEDED',
+      'Request body size ({bodySize} bytes) exceeds the configured limit ({bodyLimit} bytes).',
+    ],
+    ['MISSING_METHOD', 'The request does not declare an HTTP method.'],
+    ['INVALID_REQUEST_URL', 'The request URL could not be parsed.'],
+    ['BODY_STREAM_ERROR', 'The request body stream failed while being read.'],
+    ['INVALID_CONTENT_LENGTH', 'Invalid Content-Length header: {contentLength}.'],
+    ['MISSING_HOST', 'The request does not declare a valid authority.'],
+    ['INVALID_TRANSFER_ENCODING', 'Invalid Transfer-Encoding header: {transferEncoding}.'],
+  ]);
+}
+
+// ━━ EXPORT MODULE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+export default RequestError;

package/source/shared/errors/ResponseError/index.mjs

@@ -0,0 +1,140 @@
+/**
+ * @file Defines domain-specific errors for response construction.
+ *
+ * @description ResponseError extends BaseError to provide structured,
+ * identifiable errors specific to response status, headers, and body
+ * validation. It centralizes error messages and supports template
+ * placeholders for dynamic context.
+ *
+ * @module ResponseError
+ */
+
+// ━━ IMPORT MODULES ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// » IMPORT LOCAL MODULES
+import BaseError from '../BaseError/index.mjs';
+
+// ━━ TYPE DEFINITIONS ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+/**
+ * @template {string} T
+ * @typedef {T | (string & {})} LiteralUnion
+ */
+
+/**
+ * Identifies a predefined response error or allows a custom error message.
+ *
+ * @typedef {LiteralUnion<
+ * 'INVALID_STATUS_CODE' |
+ * 'BODY_NOT_ALLOWED' |
+ * 'RESPONSE_ALREADY_SENT' |
+ * 'BODY_ALREADY_DESCRIBED' |
+ * 'INVALID_BODY' |
+ * 'INVALID_JSON' |
+ * 'INVALID_STREAM' |
+ * 'INVALID_REDIRECT_URL' |
+ * 'INVALID_REDIRECT_STATUS' |
+ * 'CONTENT_TYPE_LOCKED' |
+ * 'INVALID_CACHE_DURATION' |
+ * 'INVALID_HEADER_NAME' |
+ * 'INVALID_HEADER_VALUE' |
+ * 'INVALID_HEADERS' |
+ * 'INVALID_CONTENT_TYPE'|
+ * 'BODY_ALREADY_WRAPPED' |
+ * 'BODY_NOT_DESCRIBED'
+ * >} ResponseErrorIdentifier
+ */
+
+/**
+ * Options for creating an error instance.
+ *
+ * @typedef  {object}                  ResponseErrorOptions
+ * @property {Record<string, unknown>} [values]             - Values for template placeholders in the error message.
+ * @property {unknown}                 [details]            - Additional contextual information about the error.
+ * @property {Error}                   [cause]              - The original error that caused this error.
+ */
+
+// ━━ MODULE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+/**
+ * Error thrown when a response cannot be constructed.
+ *
+ * @classdesc This error type provides identifiable failures related to
+ * response status, headers, body composition, and commit operations.
+ *
+ * @augments BaseError
+ * @private
+ */
+class ResponseError extends BaseError {
+  /**
+   * Creates a new {@link ResponseError}.
+   *
+   * @param {ResponseErrorIdentifier} identifier - A predefined error identifier or a custom error message.
+   * @param {ResponseErrorOptions} [options] - Additional information used to format the message, attach domain details, or preserve the original cause.
+   * @example
+   * ```js
+   * throw new ResponseError('INVALID_STATUS_CODE', {
+   *   values: { statusCode: 999 },
+   * });
+   * ```
+   * @example
+   * ```js
+   * throw new ResponseError('BODY_NOT_ALLOWED', {
+   *   values: { statusCode: 204 },
+   * });
+   * ```
+   */
+  constructor(identifier, options = {}) {
+    super(identifier, options);
+  }
+
+  /**
+   * Collection of predefined response error messages.
+   *
+   * Available error identifiers:
+   *
+   * - `'INVALID_STATUS_CODE'`.
+   * - `'BODY_NOT_ALLOWED'`.
+   * - `'RESPONSE_ALREADY_SENT'`.
+   * - `'BODY_ALREADY_DESCRIBED'`.
+   * - `'INVALID_BODY'`.
+   * - `'INVALID_JSON'`.
+   * - `'INVALID_STREAM'`.
+   * - `'INVALID_REDIRECT_URL'`.
+   * - `'INVALID_REDIRECT_STATUS'`.
+   * - `'CONTENT_TYPE_LOCKED'`.
+   * - `'INVALID_CACHE_DURATION'`.
+   * - `'INVALID_HEADER_NAME'`.
+   * - `'INVALID_HEADER_VALUE'`.
+   * - `'INVALID_HEADERS'`.
+   * - `'INVALID_CONTENT_TYPE'`.
+   * - `'BODY_ALREADY_WRAPPED'`.
+   * - `'BODY_NOT_DESCRIBED'`.
+   *
+   * @private
+   * @static
+   * @type {Map<ResponseErrorIdentifier, string>}
+   */
+  static MESSAGES = new Map([
+    ['INVALID_STATUS_CODE', 'Invalid or unsupported HTTP status code: {statusCode}.'],
+    ['BODY_NOT_ALLOWED', 'Status code {statusCode} does not allow a response body.'],
+    ['RESPONSE_ALREADY_SENT', 'The response has already been committed.'],
+    ['BODY_ALREADY_DESCRIBED', 'A response body has already been described.'],
+    ['INVALID_BODY', 'Invalid response body. Received: {received}.'],
+    ['INVALID_JSON', 'The value cannot be serialized as JSON.'],
+    ['INVALID_STREAM', 'The provided value is not a valid stream.'],
+    ['INVALID_REDIRECT_URL', 'The redirect URL must be a non-empty string.'],
+    ['INVALID_REDIRECT_STATUS', 'Invalid redirect status code: {statusCode}.'],
+    [
+      'CONTENT_TYPE_LOCKED',
+      'Cannot {operation} the Content-Type header after a body has been described.',
+    ],
+    ['INVALID_CACHE_DURATION', 'The cache duration must be a non-negative integer.'],
+    ['INVALID_HEADER_NAME', 'Invalid HTTP header name.'],
+    ['INVALID_HEADER_VALUE', 'Invalid HTTP header value.'],
+    ['INVALID_HEADERS', 'Headers must be a plain object.'],
+    ['INVALID_CONTENT_TYPE', 'Invalid Content-Type. Expected a string, but received {received}.'],
+    ['BODY_ALREADY_WRAPPED', 'The response body has already been wrapped.'],
+    ['BODY_NOT_DESCRIBED', 'A response body has not been described.'],
+  ]);
+}
+
+// ━━ EXPORT MODULE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+export default ResponseError;

package/source/shared/errors/RouterError/index.mjs

@@ -0,0 +1,90 @@
+/**
+ * @file Defines domain-specific errors for the HTTP Router.
+ *
+ * @description RouterError extends BaseError to provide structured,
+ * identifiable errors specific to routing operations. It centralizes
+ * error messages and supports template placeholders for dynamic context.
+ *
+ * @module RouterError
+ */
+
+// ━━ IMPORT MODULES ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// » IMPORT LOCAL MODULES
+import BaseError from '../BaseError/index.mjs';
+
+// ━━ TYPE DEFINITIONS ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+/**
+ * @template {string} T
+ * @typedef {T | (string & {})} LiteralUnion
+ */
+
+/**
+ * Identifies a predefined response error or allows a custom error message.
+ *
+ * @typedef {LiteralUnion<
+ * 'DUPLICATE_ALL_METHOD' |
+ * 'DUPLICATE_ROUTE'
+ * >} RouterErrorIdentifier
+ */
+
+/**
+ * Options for creating an error instance.
+ *
+ * @typedef  {object}                  RouterErrorOptions
+ * @property {Record<string, unknown>} [values]           - Values for template placeholders in the error message.
+ * @property {unknown}                 [details]          - Additional contextual information about the error.
+ * @property {Error}                   [cause]            - The original error that caused this error (for error chaining).
+ */
+
+// ━━ MODULE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+/**
+ * Error thrown when a `Router` operation cannot be completed.
+ *
+ * @classdesc This error type provides identifiable failures related to pathname
+ * patterns, route registration, and handler configuration.
+ *
+ * @augments BaseError
+ * @private
+ */
+class RouterError extends BaseError {
+  /**
+   * Creates a new {@link RouterError}.
+   *
+   * @param {RouterErrorIdentifier} identifier - A predefined error identifier or a custom error message.
+   * @param {RouterErrorOptions} [options] - Additional information used to format the message, attach domain details, or preserve the original cause.
+   * @example
+   * ```js
+   *  throw new RouterError('DUPLICATE_ALL', { values: { pathnamePattern } });
+   * ```
+   *
+   */
+  constructor(identifier, options = {}) {
+    super(identifier, options);
+  }
+
+  /**
+   * Collection of predefined server error messages.
+   *
+   * Available error identifiers:
+   *
+   * - `'DUPLICATE_ALL_METHOD'`.
+   * - `'ROUTE_ALREADY_REGISTERED'`.
+   *
+   * @private
+   * @static
+   * @type {Map<RouterErrorIdentifier, string>}
+   */
+  static MESSAGES = new Map([
+    [
+      'DUPLICATE_ALL_METHOD',
+      'The "ALL" registration is already defined for pathname pattern "{pathnamePattern}".',
+    ],
+    [
+      'DUPLICATE_ROUTE',
+      'The "{mark}" method is already defined for pathname pattern "{pathnamePattern}".',
+    ],
+  ]);
+}
+
+// ━━ EXPORT MODULE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+export default RouterError;