@boo-labs/server 0.0.0-stage → 1.0.0

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

@@ -0,0 +1,58 @@
+/**
+ * @file Defines the internal error type used for WebSocket failures.
+ *
+ * @description WebSocketError provides structured errors for WebSocket protocol
+ * and connection failures, including errors that map to a WebSocket close code.
+ *
+ * @private
+ * @module WebSocketError
+ */
+
+import BaseError from '../BaseError/index.mjs';
+
+/**
+ * @typedef {import('../BaseError/index.mjs').ErrorOptions} ErrorOptions
+ */
+
+/**
+ * Internal error type used for WebSocket protocol and connection failures.
+ *
+ * @augments BaseError
+ * @private
+ */
+class WebSocketError extends BaseError {
+  /**
+   * Creates a new {@link WebSocketError}.
+   *
+   * @param {string} identifier - A predefined WebSocket error identifier or a custom error message.
+   * @param {ErrorOptions} [options] - Additional error options.
+   * @example
+   * ```js
+   * throw new WebSocketError('WS_MESSAGE_TOO_BIG', {
+   *   values: {
+   *     size: payloadLength,
+   *     maxSize: maxMessageSize,
+   *   },
+   * });
+   * ```
+   */
+  constructor(identifier, options = {}) {
+    super(identifier, options);
+  }
+
+  /**
+   * Message template catalog indexed by WebSocket error identifier.
+   *
+   * @type {Map<string, string>}
+   * @private
+   * @static
+   */
+  static MESSAGES = new Map([
+    [
+      'WS_MESSAGE_TOO_BIG',
+      'WebSocket payload size ({size} bytes) exceeds maximum allowed message size ({maxSize} bytes).',
+    ],
+  ]);
+}
+
+export default WebSocketError;

package/source/shared/outcome/ErrorSchema.mjs

@@ -0,0 +1,361 @@
+/**
+ * @file Defines the structured schema used to describe operation errors.
+ *
+ * @description ErrorSchema normalizes literal-message and code-based error
+ * definitions into a consistent schema used to instantiate Error objects.
+ *
+ * @module ErrorSchema
+ */
+
+// ━━ IMPORT MODULES ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// » IMPORT NATIVE NODEJS MODULES
+import { inspect } from 'node:util';
+
+// » IMPORT THIRD PARTY MODULES
+
+// » IMPORT LOCAL MODULES
+
+// ━━ TYPE DEFINITIONS ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+/**
+ * Represents an Error constructor.
+ *
+ * @typedef {new (identifier: string, options?: Record<string, unknown>) => Error} ErrorConstructor
+ */
+
+/**
+ * Represents options passed to a native Error constructor.
+ *
+ * @typedef  {object}  NativeErrorOptions
+ * @property {unknown} [cause]            - Cause associated with the error.
+ */
+
+/**
+ * Represents a native Error schema definition.
+ *
+ * @typedef  {object}             NativeErrorSchema
+ * @property {ErrorConstructor}   error             - Error constructor used to create the error.
+ * @property {string}             message           - Literal error message.
+ * @property {NativeErrorOptions} [options]         - Options passed to the Error constructor.
+ * @property {false}              custom            - Indicates that the constructor represents a native Error.
+ * @property {string}             code              - Error identifier.
+ */
+
+/**
+ * Represents options passed to a custom Error constructor.
+ *
+ * @typedef  {object}                  CustomErrorOptions
+ * @property {Record<string, unknown>} [values]           - Values used to resolve message placeholders.
+ * @property {Record<string, unknown>} [details]          - Additional contextual information about the error.
+ * @property {unknown}                 [cause]            - Cause associated with the error.
+ */
+
+/**
+ * Represents a custom Error schema definition.
+ *
+ * @typedef  {object}             CustomErrorSchema
+ * @property {ErrorConstructor}   error             - Error constructor used to create the error.
+ * @property {string}             code              - Error code used to resolve the error message and error identifier.
+ * @property {string}             [message]         - Literal error message.
+ * @property {CustomErrorOptions} [options]         - Options passed to the Error constructor.
+ * @property {true}               custom            - Indicates that the constructor represents a custom Error.
+ */
+
+/**
+ * Represents a supported Error schema definition.
+ *
+ * @typedef {NativeErrorSchema|CustomErrorSchema} ErrorSchemaDefinition
+ * @exports ErrorSchemaDefinition
+ */
+
+/**
+ * Represents the normalized state of an ErrorSchema.
+ *
+ * @typedef  {object}                  ErrorSchemaState
+ * @property {string}                  [message]        - Literal error message.
+ * @property {string}                  type             - Error constructor name.
+ * @property {Record<string, unknown>} options          - Options passed to the Error constructor.
+ * @property {string}                  code             - Error identifier.
+ */
+
+// ━━ FUNCTIONS ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+/**
+ * Determines whether a value is a plain object.
+ *
+ * @private
+ * @param {unknown} value - Value to check.
+ * @returns {boolean} Whether the value is a plain object.
+ */
+const isObject = value => Object.prototype.toString.call(value) === '[object Object]';
+
+// ━━ MODULE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+/**
+ * Defines a structured error schema and creates its corresponding Error.
+ *
+ * @classdesc ErrorSchema accepts either a literal error message or a domain
+ * error code. Message-based schemas create errors directly from the message,
+ * while code-based schemas preserve the code, values, and details required by
+ * the consuming error system.
+ */
+class ErrorSchema {
+  /**
+   * Normalized error schema definition.
+   *
+   * @type {ErrorSchemaState}
+   */
+  #schema;
+
+  /**
+   * Error constructor used to reconstruct the error.
+   *
+   * @type {typeof Error}
+   */
+  #error;
+
+  /**
+   * Indicates whether the error uses the custom Error flow.
+   *
+   * @type {boolean}
+   */
+  #custom;
+
+  /**
+   * Creates an error schema from an Error definition.
+   *
+   * The schema must provide an Error constructor. Native Errors require a
+   * message and code, while custom Errors require a code and may provide a message.
+   *
+   * @param {ErrorSchemaDefinition} schema - Error schema configuration.
+   * @throws {TypeError} If `error` is not an Error constructor.
+   * @throws {TypeError} If a native Error does not provide a message.
+   * @throws {TypeError} If message is not a string.
+   * @throws {TypeError} If a custom Error provides neither message nor code.
+   * @example
+   * ```js
+   * const schema = new ErrorSchema({
+   *   error: TypeError,
+   *   message: 'Invalid request.'
+   * });
+   *
+   * schema.error;
+   * ```
+   *
+   * @example
+   * ```js
+   * const schema = new ErrorSchema({
+   *   error: RequestError,
+   *   code: 'INVALID_REQUEST',
+   *   options: {
+   *     values: { field: 'email' },
+   *     details: { source: 'RequestValidator' }
+   *   },
+   *   custom: true
+   * });
+   *
+   * schema.error;
+   * ```
+   */
+  constructor(schema) {
+    if (!isObject(schema)) {
+      throw new TypeError('Schema options must be an object.');
+    }
+
+    if (!('error' in schema)) {
+      throw new TypeError('ErrorSchema error constructor is required.');
+    }
+
+    if (!ErrorSchema.isErrorConstructor(schema.error)) {
+      throw new TypeError('Expected an Error constructor');
+    }
+
+    const custom = schema.custom ?? false;
+
+    if (!custom && !('message' in schema)) {
+      throw new TypeError('Message is required for a native Error');
+    }
+
+    if (!custom && !('code' in schema)) {
+      throw new TypeError('Code is required for Error Schema');
+    }
+
+    if ('message' in schema && typeof schema.message !== 'string') {
+      throw new TypeError('Message must be a string');
+    }
+
+    if (custom && !('message' in schema) && !('code' in schema)) {
+      throw new TypeError('Message or code is required for a Custom Error');
+    }
+
+    this.#error = schema.error;
+    this.#custom = custom;
+
+    this.#schema = Object.freeze({
+      message: schema.message,
+      type: schema.error.name,
+      options: schema.options ?? {},
+      code: schema.code,
+    });
+  }
+
+  /**
+   * Normalized error schema.
+   *
+   * @readonly
+   * @type {object}
+   */
+  get schema() {
+    return this.#schema;
+  }
+
+  /**
+   * Creates a new Error instance from the configured schema.
+   *
+   * @readonly
+   * @type {Error}
+   */
+  get error() {
+    const { message, options, code } = this.#schema;
+
+    if (this.#custom) {
+      return new this.#error(message ?? code, options);
+    }
+
+    return new this.#error(message, options);
+  }
+
+  /**
+   * Custom string tag for type identification.
+   *
+   * @readonly
+   * @type {string}
+   */
+  get [Symbol.toStringTag]() {
+    return `${this.constructor.name}`;
+  }
+
+  /**
+   * Creates a plain object representation of the error schema.
+   *
+   * @returns {ErrorSchemaState} Normalized error schema.
+   * @example
+   * ```js
+   * const schema = new ErrorSchema({
+   *   error: TypeError,
+   *   message: 'Invalid middleware.',
+   *   code: 'INVALID_MIDDLEWARE',
+   *   custom: false
+   * });
+   *
+   * console.log(schema.toObject());
+   * // {
+   * //   message: 'Invalid middleware.',
+   * //   type: 'TypeError',
+   * //   options: {},
+   * //   code: 'INVALID_MIDDLEWARE'
+   * // }
+   * ```
+   */
+  toObject() {
+    return { ...this.#schema };
+  }
+
+  /**
+   * Creates a JSON-compatible representation of the error schema.
+   *
+   * @returns {ErrorSchemaState} Normalized error schema.
+   * @example
+   * ```js
+   * const schema = new ErrorSchema({
+   *   error: RequestError,
+   *   code: 'INVALID_REQUEST',
+   *   options: {
+   *     values: { field: 'email' },
+   *     details: { source: 'RequestValidator' }
+   *   },
+   *   custom: true
+   * });
+   *
+   * console.log(JSON.stringify(schema));
+   * // {"message":undefined,"type":"RequestError",
+   * // "options":{"values":{"field":"email"},
+   * // "details":{"source":"RequestValidator"}},
+   * // "code":"INVALID_REQUEST"}
+   * ```
+   */
+  toJSON() {
+    const schema = this.toObject();
+    const options = schema.options;
+
+    const base = {
+      message: schema.message,
+      type: schema.type,
+      code: schema.code,
+    };
+
+    if ('cause' in options && options.cause instanceof Error) {
+      const { cause, ...rest } = options;
+
+      return {
+        ...base,
+        options: {
+          ...rest,
+          cause: {
+            name: cause.name,
+            message: cause.message,
+            stack: cause.stack,
+          },
+        },
+      };
+    }
+
+    return {
+      ...base,
+      options,
+    };
+  }
+
+  /**
+   * Custom inspect implementation for Node.js `util.inspect()`.
+   *
+   * @returns {string} Custom string representation for debugging.
+   * @example
+   * ```js
+   * const schema = new ErrorSchema({
+   *   error: TypeError,
+   *   message: 'Invalid middleware.',
+   *   code: 'INVALID_MIDDLEWARE',
+   *   custom: false
+   * });
+   *
+   * console.log(inspect(schema));
+   * // ErrorSchema({
+   * //   message: 'Invalid middleware.',
+   * //   type: 'TypeError',
+   * //   options: {},
+   * //   code: 'INVALID_MIDDLEWARE'
+   * // })
+   * ```
+   */
+  [inspect.custom]() {
+    return `${this.constructor.name}(${inspect(this.toObject(), { colors: true, depth: 2 })})`;
+  }
+
+  /**
+   * Determines whether a value is an Error constructor.
+   *
+   * @param {unknown} error - Value to check.
+   * @returns {boolean} Whether `error` is a constructor that inherits from `Error`.
+   * @example
+   * ```js
+   * ErrorSchema.isErrorConstructor(TypeError); // true
+   * ErrorSchema.isErrorConstructor(RangeError); // true
+   * ErrorSchema.isErrorConstructor(Math); // false
+   * ```
+   */
+  static isErrorConstructor(error) {
+    if (error === Error) return true;
+    if (typeof error !== 'function') return false;
+    return Object.prototype.isPrototypeOf.call(Error.prototype, error.prototype);
+  }
+}
+// ━━ EXPORT MODULE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+export default ErrorSchema;

package/source/shared/outcome/Result/index.mjs

@@ -0,0 +1,239 @@
+// @ts-check
+/**
+ * @file Core result module for representing strict operation outcomes.
+ *
+ * @description Provides the {@link Result} class for explicitly representing
+ * successful and failed operations without relying on ambiguous `undefined`
+ * states.
+ *
+ * @module Result
+ */
+
+// ━━ IMPORT MODULES ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// » IMPORT LOCAL MODULES
+import ErrorSchema from '../ErrorSchema.mjs';
+
+// ━━ TYPE DEFINITIONS ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+/**
+ * Represents options passed to a native Error constructor.
+ *
+ * @typedef  {object}  NativeErrorOptions
+ * @property {unknown} [cause]            - Cause associated with the error.
+ */
+
+/**
+ * Represents a native Error schema definition.
+ *
+ * @typedef  {object}             NativeErrorSchema
+ * @property {typeof Error}       error             - Error constructor used to create the error.
+ * @property {string}             message           - Literal error message.
+ * @property {NativeErrorOptions} [options]         - Options passed to the Error constructor.
+ * @property {false}              custom            - Indicates that the constructor represents a native Error.
+ * @property {string}             code              - Error identifier.
+ */
+
+/**
+ * Represents options passed to a custom Error constructor.
+ *
+ * @typedef  {object}                  CustomErrorOptions
+ * @property {Record<string, unknown>} [values]           - Values used to resolve message placeholders.
+ * @property {Record<string, unknown>} [details]          - Additional contextual information about the error.
+ * @property {unknown}                 [cause]            - Cause associated with the error.
+ */
+
+/**
+ * Represents a custom Error schema definition.
+ *
+ * @typedef  {object}             CustomErrorSchema
+ * @property {typeof Error}       error             - Error constructor used to create the error.
+ * @property {string}             code              - Error code used to resolve the error message and error identifier.
+ * @property {string}             [message]         - Literal error message.
+ * @property {CustomErrorOptions} [options]         - Options passed to the Error constructor.
+ * @property {true}               custom            - Indicates that the constructor represents a custom Error.
+ */
+
+/**
+ * Represents a supported Error schema definition.
+ *
+ * @typedef {NativeErrorSchema|CustomErrorSchema} ErrorSchemaDefinition
+ */
+
+/**
+ * Represents the successful state of a {@link Result} instance.
+ *
+ * @template T
+ * @typedef  {object}    ResultSuccess
+ * @property {true}      ok            - Indicates that the operation succeeded.
+ * @property {T}         value         - Successful value produced by the operation.
+ * @property {undefined} [error]       - Always undefined for a successful result.
+ */
+
+/**
+ * Represents the failed state of a {@link Result} instance.
+ *
+ * @typedef  {object}      ResultFailure
+ * @property {false}       ok            - Indicates that the operation failed.
+ * @property {undefined}   [value]       - Always undefined for a failed result.
+ * @property {ErrorSchema} error         - Error schema describing the operation failure.
+ */
+
+/**
+ * Represents the internal state of a {@link Result} instance.
+ *
+ * @template T
+ * @typedef {ResultSuccess<T>|ResultFailure} ResultState
+ */
+
+// ━━ MODULE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+/**
+ * Represents the strict outcome of an operation that may yield a value or an
+ * error.
+ *
+ * @template T
+ */
+class Result {
+  /**
+   * Stores the internal result state.
+   *
+   * @type {ResultState<T>}
+   */
+  #result;
+
+  /**
+   * Creates a Result instance.
+   *
+   * @param {boolean} ok - Whether the operation succeeded.
+   * @param {T} [value] - The successful value.
+   * @param {ErrorSchemaDefinition} [error] - Required when ok is false.
+   * @throws {TypeError} If the combination of ok, value, and error is invalid.
+   * @example
+   * ```js
+   * const result = new Result(true, { id: '123' });
+   * ```
+   *
+   * @example
+   * ```js
+   * const result = new Result(false, undefined, {
+   *   error: RangeError,
+   *   message: 'Value is out of range.',
+   *   custom: false,
+   *   code: 'ERR_RANGE',
+   * });
+   * ```
+   */
+  constructor(ok, value, error) {
+    if (typeof ok !== 'boolean') {
+      throw new TypeError('Result status (ok) must be a boolean.');
+    }
+
+    if (ok === true) {
+      if (value === undefined) {
+        throw new TypeError('A successful Result must contain a value.');
+      }
+      if (error !== undefined) {
+        throw new TypeError('A successful Result cannot contain an error.');
+      }
+
+      this.#result = { ok, value, error };
+    } else {
+      if (error === undefined) {
+        throw new TypeError('A failed Result must contain an error.');
+      }
+
+      if (value !== undefined) {
+        throw new TypeError('A failed Result cannot contain a value.');
+      }
+
+      this.#result = {
+        ok,
+        value: undefined,
+        error: new ErrorSchema(error),
+      };
+    }
+  }
+
+  /**
+   * Indicates whether the operation succeeded.
+   *
+   * @readonly
+   * @type {boolean}
+   */
+  get ok() {
+    return this.#result.ok;
+  }
+
+  /**
+   * The successful value of the operation.
+   *
+   * @readonly
+   * @type {T}
+   * @throws {Error} If the result is not ok.
+   */
+  get value() {
+    if (this.#result.ok === false) {
+      throw new Error('Cannot access value of a failed Result.');
+    }
+
+    return this.#result.value;
+  }
+
+  /**
+   * The instantiated error of the failed operation.
+   *
+   * @readonly
+   * @type {Error}
+   * @throws {Error} If the result is ok.
+   */
+  get error() {
+    if (this.#result.ok === true) {
+      throw new Error('Cannot access error of a successful Result.');
+    }
+
+    return this.#result.error.error;
+  }
+
+  /**
+   * Creates a successful {@link Result}.
+   *
+   * @template U
+   * @param {U} [value] - The successful value.
+   * @returns {Result<U>} A successful Result instance.
+   * @example
+   * ```js
+   * const result = Result.success({ id: '123' });
+   *
+   * if (result.ok) {
+   *   console.log(result.value.id);
+   * }
+   * ```
+   */
+  static success(value) {
+    return new Result(true, value);
+  }
+
+  /**
+   * Creates a failed {@link Result}.
+   *
+   * @param {ErrorSchemaDefinition} error - The error details describing the failure.
+   * @returns {Result<never>} A failed Result instance.
+   * @example
+   * ```js
+   * const result = Result.failure({
+   *   error: RangeError,
+   *   message: 'Value is out of range.',
+   *   custom: false,
+   *   code: 'ERR_RANGE',
+   * });
+   *
+   * if (!result.ok) {
+   *   console.log(result.error);
+   * }
+   * ```
+   */
+  static failure(error) {
+    return /** @type {Result<never>} */ (new Result(false, undefined, error));
+  }
+}
+
+// ━━ EXPORT MODULE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+export default Result;