@boo-labs/server 0.0.0-stage → 1.0.1

package/source/shared/domain/UUIDV7/index.mjs

@@ -0,0 +1,346 @@
+// @ts-check
+/**
+ * @file Provides a UUID version 7 implementation.
+ *
+ * @description Defines the UUIDV7 class for creating, validating, and working
+ * with RFC 9562-compliant UUID version 7 identifiers.
+ *
+ * UUID v7 embeds a 48-bit Unix timestamp in milliseconds in the first
+ * six bytes of the identifier, followed by randomly generated bits.
+ * This provides identifiers that are practically unique and naturally
+ * sortable by creation time.
+ *
+ * @module UUIDV7
+ */
+
+// ━━ IMPORT MODULES ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// » IMPORT NATIVE NODEJS MODULES
+import { randomBytes } from 'node:crypto';
+
+// » IMPORT THIRD PARTY MODULES
+
+// » IMPORT LOCAL MODULES
+import Validation from '#shared/outcome/Validation';
+
+// ━━ CONSTANTS ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+/**
+ * Matches the canonical hexadecimal representation of a UUID version 7.
+ *
+ * The expression validates the UUID structure, version field, and RFC 9562
+ * variant bits.
+ *
+ * @type {RegExp}
+ */
+const UUIDV7_REGEXP = /^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+
+// ━━ MODULE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+/**
+ * Represents a UUID version 7.
+ *
+ * UUID v7 combines a Unix timestamp in milliseconds with randomly generated
+ * bits, producing identifiers that are practically unique and chronologically
+ * sortable.
+ */
+class UUIDV7 {
+  #uuid;
+
+  /**
+   * Creates a UUID v7 instance.
+   *
+   * When no timestamp is provided, the current time is used. A `Date` instance
+   * uses its Unix timestamp, while an existing UUID v7 uses the timestamp
+   * encoded in its first 48 bits.
+   *
+   * @param {Date|string|undefined} inputId - Timestamp source or existing UUID v7.
+   * @throws {TypeError} If the input type is invalid.
+   * @throws {RangeError} If the input value is invalid.
+   *
+   * @example
+   * ```js
+   * const id = new UUIDV7();
+   * ```
+   *
+   * @example
+   * ```js
+   * const id = new UUIDV7(new Date('2026-09-07T10:00:00Z'));
+   * ```
+   *
+   * @example
+   * ```js
+   * const source = new UUIDV7();
+   * const id = new UUIDV7(source.value);
+   * ```
+   */
+  constructor(inputId = undefined) {
+    UUIDV7.assert(inputId);
+
+    const milliseconds = UUIDV7.#normalizeTimestamp(inputId);
+
+    this.#uuid = UUIDV7.#generateUUID(milliseconds);
+  }
+
+  /**
+   * The UUID value.
+   *
+   * @readonly
+   * @type {string}
+   */
+  get value() {
+    return this.#uuid;
+  }
+
+  /**
+   * The UUID value without separators.
+   *
+   * @readonly
+   * @type {string}
+   */
+  get hexadecimal() {
+    return this.#uuid.replace(/-/g, '');
+  }
+
+  /**
+   * The Unix timestamp encoded in the UUID.
+   *
+   * @readonly
+   * @type {number}
+   */
+  get timestamp() {
+    return Number.parseInt(this.hexadecimal.slice(0, 12), 16);
+  }
+
+  /**
+   * Returns the Unix timestamp encoded in the UUID as a Date instance.
+   *
+   * @returns {Date} Date represented by the UUID timestamp.
+   * @example
+   * ```js
+   * const id = new UUIDV7();
+   * const date = id.toDate();
+   * ```
+   */
+  toDate() {
+    return new Date(this.timestamp);
+  }
+
+  /**
+   * Returns the UUID as a string.
+   *
+   * @returns {string} UUID in canonical hexadecimal format.
+   * @example
+   * ```js
+   * const id = new UUIDV7();
+   * console.log(id.toString());
+   * ```
+   */
+  toString() {
+    return this.#uuid;
+  }
+
+  /**
+   * Returns the UUID as a JSON value.
+   *
+   * @returns {string} UUID in canonical hexadecimal format.
+   *
+   * @example
+   * ```js
+   * const id = new UUIDV7();
+   * console.log(JSON.stringify(id));
+   * ```
+   */
+  toJSON() {
+    return this.#uuid;
+  }
+
+  /**
+   * Normalizes a timestamp source into Unix milliseconds.
+   *
+   * Accepted values are:
+   * - `undefined`, which resolves to the current time.
+   * - A `Date` instance, which resolves to its Unix timestamp.
+   * - A valid UUID v7 string, from which the embedded timestamp is extracted.
+   *
+   * @param {Date|string|undefined} inputId - Timestamp source.
+   * @returns {number} Unix timestamp in milliseconds.
+   */
+  static #normalizeTimestamp(inputId) {
+    if (inputId === undefined) {
+      return Date.now();
+    }
+
+    if (inputId instanceof Date) {
+      return inputId.getTime();
+    }
+
+    const hexadecimal = inputId.replace(/-/g, '');
+
+    return Number.parseInt(hexadecimal.substring(0, 12), 16);
+  }
+
+  /**
+   * Generates a UUID version 7 from a Unix timestamp.
+   *
+   * The generated identifier contains:
+   * - A 48-bit Unix timestamp in milliseconds.
+   * - The UUID version 7 field.
+   * - The RFC 9562 variant field.
+   * - Random bits filling the remaining identifier space.
+   *
+   * @param {number} milliseconds - Unix timestamp in milliseconds.
+   * @returns {string} UUID v7 in canonical hexadecimal format.
+   */
+  static #generateUUID(milliseconds) {
+    const bytes = randomBytes(16);
+
+    // ━━ 48-bit Unix timestamp (bytes 0-5) ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+    bytes[0] = Math.floor(milliseconds / 0x10000000000) & 0xff;
+    bytes[1] = Math.floor(milliseconds / 0x100000000) & 0xff;
+    bytes[2] = Math.floor(milliseconds / 0x1000000) & 0xff;
+    bytes[3] = Math.floor(milliseconds / 0x10000) & 0xff;
+    bytes[4] = Math.floor(milliseconds / 0x100) & 0xff;
+    bytes[5] = milliseconds & 0xff;
+
+    // ━━ Version 7 + random bits ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+    bytes[6] = (bytes[6] & 0x0f) | 0x70;
+
+    // ━━ RFC 9562 variant + random bits ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+    bytes[8] = (bytes[8] & 0x3f) | 0x80;
+
+    // ━━ Canonical format ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+    const hexadecimal = bytes.toString('hex');
+
+    return `${hexadecimal.slice(0, 8)}-${hexadecimal.slice(8, 12)}-${hexadecimal.slice(12, 16)}-${hexadecimal.slice(16, 20)}-${hexadecimal.slice(20)}`;
+  }
+
+  /**
+   * Creates a new UUID v7 string using the current time.
+   *
+   * Convenience shortcut equivalent to `new UUIDV7().toString()`.
+   *
+   * @returns {string} UUID v7 in canonical hexadecimal format.
+   *
+   * @example
+   * ```js
+   * const id = UUIDV7.create();
+   * ```
+   */
+  static create() {
+    return new UUIDV7().toString();
+  }
+
+  /**
+   * Validates a value that can be used as a UUID v7 timestamp source.
+   *
+   * `undefined` represents the current time, a `Date` represents its Unix
+   * timestamp, and a UUID v7 string represents the timestamp encoded in that
+   * UUID.
+   *
+   * @param {*} value - Value to validate.
+   * @returns {Validation} Validation result.
+   * @example
+   * ```js
+   * const result = UUIDV7.validate();
+   * ```
+   */
+  static validate(value) {
+    if (value === undefined) {
+      return Validation.success();
+    }
+
+    if (value instanceof Date) {
+      if (Number.isNaN(value.getTime())) {
+        return Validation.failure({
+          error: RangeError,
+          message: 'Invalid timestamp.',
+          code: 'INVALID_TIMESTAMP',
+          custom: false,
+        });
+      }
+      return Validation.success();
+    }
+
+    if (typeof value === 'string') {
+      if (!UUIDV7_REGEXP.test(value)) {
+        return Validation.failure({
+          error: RangeError,
+          message: 'Invalid UUID v7.',
+          code: 'INVALID_UUID',
+          custom: false,
+        });
+      }
+      return Validation.success();
+    }
+
+    return Validation.failure({
+      error: TypeError,
+      message: 'Timestamp must be a Date, string, or undefined.',
+      code: 'INVALID_TIMESTAMP_SOURCE',
+      custom: false,
+    });
+  }
+
+  /**
+   * Validates that a value is a valid UUID v7 string.
+   *
+   * @param {unknown} value - Value to validate.
+   * @returns {Validation} Validation result.
+   * @example
+   * ```js
+   * const result = UUIDV7.validateUUIDString('019937f2-1234-7abc-8def-123456789abc');
+   * ```
+   */
+  static validateUUIDString(value) {
+    if (value === undefined) {
+      return Validation.failure({
+        error: ReferenceError,
+        message: 'UUID must be a string.',
+        custom: false,
+        code: 'MISSING_UUID',
+      });
+    }
+
+    if (typeof value !== 'string') {
+      return Validation.failure({
+        error: TypeError,
+        message: 'UUID must be a string.',
+        custom: false,
+        code: 'INVALID_UUID_TYPE',
+      });
+    }
+
+    if (!UUIDV7_REGEXP.test(value)) {
+      return Validation.failure({
+        error: RangeError,
+        message: 'Invalid UUID v7 format.',
+        custom: false,
+        code: 'INVALID_UUID',
+      });
+    }
+
+    return Validation.success();
+  }
+
+  /**
+   * Asserts that a value can be used as a UUID v7 timestamp source.
+   *
+   * Unlike {@link UUIDV7.validate}, this method throws when validation fails.
+   *
+   * @param {unknown} value - Value to validate.
+   * @throws {TypeError} If the value has an unsupported type.
+   * @throws {RangeError} If the value is invalid.
+   * @example
+   * ```js
+   * UUIDV7.assert(new Date());
+   * ```
+   */
+  static assert(value) {
+    const validation = UUIDV7.validate(value);
+
+    if (!validation.ok) {
+      throw validation.error;
+    }
+  }
+}
+
+// ━━ EXPORT MODULE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+export default UUIDV7;

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

@@ -0,0 +1,157 @@
+/**
+ * @file Defines the base class for structured application errors.
+ *
+ * @description BaseError serves as the foundation for application-specific errors.
+ * It provides a consistent interface for error handling with support for:
+ *
+ * - Predefined error identifiers and custom error messages.
+ * - Message templating with placeholders.
+ * - Error chaining via the `cause` property.
+ * - Contextual information via `details`.
+ * - A consistent error structure across the application.
+ *
+ * Subclasses should define their own `MESSAGES` map with domain-specific
+ * error identifiers and message templates.
+ *
+ * @private
+ * @module BaseError
+ */
+
+// ━━ TYPE DEFINITIONS ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+/**
+ * A symbolic identifier used to resolve an application error definition.
+ *
+ * @typedef {string} ErrorIdentifier
+ */
+
+/**
+ * Options for creating an error instance.
+ *
+ * @typedef  {object}                  ErrorOptions
+ * @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).
+ */
+
+/**
+ * Normalized error definition used internally to construct an error instance.
+ *
+ * @typedef  {object}           ErrorDefinition
+ * @property {string}           message         - The final error message.
+ * @property {ErrorIdentifier}  [code]          - The resolved error identifier.
+ * @property {unknown}          [details]       - Additional error details.
+ * @property {{ cause: Error }} [errorOptions]  - Options for the Error constructor (e.g., cause).
+ */
+
+// ━━	MODULE	━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+/**
+ * Base class for application-specific errors.
+ *
+ * This class supports predefined error identifiers as well as custom error
+ * messages. When a known error identifier is provided, it is automatically
+ * resolved to its corresponding message template.
+ *
+ * @augments Error
+ * @private
+ */
+class BaseError extends Error {
+  /**
+   * Creates a new {@link BaseError}.
+   *
+   * @param {ErrorIdentifier} identifier - A predefined error identifier or a custom error message.
+   * @param {ErrorOptions} [options] - Additional information used to format the message, attach domain details, or preserve the original cause.
+   * @example
+   * ```js
+   * class ValidationError extends BaseError {}
+   * throw new ValidationError('INVALID_VALUE');
+   * ```
+   */
+  constructor(identifier, options = {}) {
+    const definition = new.target.resolveDefinition(identifier, options);
+
+    super(definition.message, definition.errorOptions);
+
+    this.name = new.target.name;
+
+    if (definition.code !== undefined) {
+      /**
+       * Predefined error identifier, when available.
+       *
+       * @type {ErrorIdentifier}
+       */
+      this.code = definition.code;
+    }
+
+    if (definition.details !== undefined) {
+      /**
+       * Additional contextual information about the error.
+       *
+       * @type {unknown}
+       */
+      this.details = definition.details;
+    }
+
+    Error.captureStackTrace?.(this, new.target);
+  }
+
+  /**
+   * Replaces placeholder tokens in a predefined message.
+   *
+   * Placeholders are in the format `{key}` and are replaced with the
+   * corresponding value from the `values` object.
+   *
+   * @private
+   * @static
+   * @param {string} message - The message template containing placeholders.
+   * @param {Record<string, unknown>} [values] - Key-value pairs for placeholder replacement.
+   * @returns {string} The formatted message with placeholders replaced.
+   */
+  static #formatMessage(message, values = {}) {
+    return message.replace(/\{(\w+)\}/g, (_, key) => String(values[key] ?? `{${key}}`));
+  }
+
+  /**
+   * Resolves an error identifier into a normalized error definition.
+   *
+   * This method handles both predefined error identifiers and custom error messages.
+   * When a predefined identifier is found, it resolves to the corresponding message
+   * and applies any placeholders.
+   *
+   * @private
+   * @static
+   * @param {ErrorIdentifier} identifier - The error identifier or custom message.
+   * @param {ErrorOptions} [options] - Additional error options.
+   * @returns {ErrorDefinition} Normalized error definition.
+   */
+  static resolveDefinition(identifier, options) {
+    const entry = this.MESSAGES.get(identifier);
+
+    if (entry === undefined) {
+      return {
+        message: identifier,
+      };
+    }
+
+    return {
+      message: BaseError.#formatMessage(entry, options.values),
+      code: identifier,
+      details: options.details,
+      errorOptions: options.cause !== undefined ? { cause: options.cause } : undefined,
+    };
+  }
+
+  /**
+   * Message template catalog indexed by error identifier.
+   *
+   * Subclasses should override this property with their own
+   * identifier-to-message mappings.
+   *
+   * @type {Map<ErrorIdentifier, string>}
+   * @private
+   * @static
+   */
+  static MESSAGES = new Map();
+}
+
+// ━━	EXPORT MODULE	━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+export default BaseError;

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

@@ -0,0 +1,97 @@
+/**
+ * @file Defines the internal error type used for IPC subsystem failures.
+ *
+ * @description This class supports predefined error identifiers as well
+ * as custom error messages. When a known error identifier is provided,
+ * it is automatically resolved to its corresponding message.
+ *
+ * @private
+ * @module IPCError
+ */
+
+// ━━ IMPORT MODULES ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// » IMPORT LOCAL MODULES
+import BaseError from '../BaseError/index.mjs';
+
+// ━━ TYPE DEFINITIONS ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+/**
+ * @template {string} T
+ * @typedef {T | (string & {})} LiteralUnion
+ */
+
+/**
+ * @typedef {LiteralUnion<
+ * 'IPC_INVALID_CHANNEL' |
+ * 'IPC_INVALID_HANDLER' |
+ * 'IPC_INVALID_LISTENER' |
+ * 'IPC_CLOSED' |
+ * 'IPC_CHANNEL_NOT_FOUND'
+ * >} IPCErrorIdentifier
+ */
+
+/**
+ * Options for creating an error instance.
+ *
+ * @typedef  {object}                  IPCErrorOptions
+ * @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 an IPC subsystem operation cannot be completed.
+ *
+ * This error type covers failures related to IPC handler registration,
+ * listener management, and IPC lifecycle operations.
+ *
+ * @augments BaseError
+ * @private
+ */
+class IPCError extends BaseError {
+  /**
+   * Creates a new {@link IPCError}.
+   *
+   * @param {IPCErrorIdentifier} identifier - A predefined error identifier or a custom error message.
+   * @param {IPCErrorOptions} [options] - Additional information used to format the message, attach domain details, or preserve the original cause.
+   * @example
+   * ```js
+   * throw new IPCError('IPC_INVALID_CHANNEL');
+   * ```
+   * @example
+   * ```js
+   * throw new IPCError('IPC_CHANNEL_NOT_FOUND', {
+   *   values: { channel: 'get-user' },
+   * });
+   * ```
+   */
+  constructor(identifier, options = {}) {
+    super(identifier, options);
+  }
+
+  /**
+   * Collection of predefined IPC error messages.
+   *
+   * Available error identifiers:
+   *
+   * - `IPC_INVALID_CHANNEL`.
+   * - `IPC_INVALID_HANDLER`.
+   * - `IPC_INVALID_LISTENER`.
+   * - `IPC_CLOSED`.
+   * - `IPC_CHANNEL_NOT_FOUND`.
+   *
+   * @private
+   * @static
+   * @type {Map<IPCErrorIdentifier, string>}
+   */
+  static MESSAGES = new Map([
+    ['IPC_INVALID_CHANNEL', 'Channel must be a non-empty string.'],
+    ['IPC_INVALID_HANDLER', 'Handler must be a function.'],
+    ['IPC_INVALID_LISTENER', 'Listener must be a function.'],
+    ['IPC_CLOSED', 'IPCMain has been closed.'],
+    ['IPC_CHANNEL_NOT_FOUND', 'No handler registered for channel "{channel}".'],
+  ]);
+}
+
+// ━━ EXPORT MODULE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+export default IPCError;

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

@@ -0,0 +1,106 @@
+/**
+ * @file Defines domain-specific errors for middleware validation.
+ *
+ * @description MiddlewareError extends BaseError to provide structured,
+ * identifiable errors specific to middleware validation. It centralizes
+ * error messages and supports template placeholders for dynamic context.
+ *
+ * @module MiddlewareError
+ */
+
+// ━━ IMPORT MODULES ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// » IMPORT LOCAL MODULES
+import BaseError from '../BaseError/index.mjs';
+
+// ━━ TYPE DEFINITIONS ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+/**
+ * @template {string} T
+ * @typedef {T | (string & {})} LiteralUnion
+ */
+
+/**
+ * Identifies a predefined middleware error or allows a custom error message.
+ *
+ * @typedef {LiteralUnion<
+ * 'INVALID_MIDDLEWARE_TYPE' |
+ * 'INVALID_MIDDLEWARE_ARITY' |
+ * 'INVALID_MIDDLEWARES_TYPE'
+ * >} MiddlewareErrorIdentifier
+ */
+
+/**
+ * Options for creating an error instance.
+ *
+ * @typedef  {object}                  MiddlewareErrorOptions
+ * @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 middleware cannot be validated.
+ *
+ * @classdesc This error type provides identifiable failures related to
+ * middleware validation.
+ *
+ * @augments BaseError
+ * @private
+ */
+class MiddlewareError extends BaseError {
+  /**
+   * Creates a new {@link MiddlewareError}.
+   *
+   * @param {MiddlewareErrorIdentifier} identifier - A predefined error identifier or a custom error message.
+   * @param {MiddlewareErrorOptions} [options] - Additional information used to format the message, attach domain details, or preserve the original cause.
+   * @example
+   * ```js
+   * throw new MiddlewareError('INVALID_MIDDLEWARE_TYPE', {
+   *   values: {
+   *     expected: 'function',
+   *     received: 'string',
+   *   },
+   * });
+   * ```
+   * @example
+   * ```js
+   * throw new MiddlewareError('INVALID_MIDDLEWARE_ARITY', {
+   *   values: {
+   *     expected: 2,
+   *     received: 1,
+   *   },
+   * });
+   * ```
+   */
+  constructor(identifier, options = {}) {
+    super(identifier, options);
+  }
+
+  /**
+   * Collection of predefined middleware error messages.
+   *
+   * Available error identifiers:
+   *
+   * - `'INVALID_MIDDLEWARE_TYPE'`.
+   * - `'INVALID_MIDDLEWARE_ARITY'`.
+   * - `'INVALID_MIDDLEWARES_TYPE'`.
+   *
+   * @private
+   * @static
+   * @type {Map<MiddlewareErrorIdentifier, string>}
+   */
+  static MESSAGES = new Map([
+    ['INVALID_MIDDLEWARE_TYPE', 'Expected middleware to be a {expected}, but received {received}.'],
+    [
+      'INVALID_MIDDLEWARE_ARITY',
+      'Middleware must declare exactly {expected} parameters, but received {received}.',
+    ],
+    [
+      'INVALID_MIDDLEWARES_TYPE',
+      'Expected middlewares to be an {expected}, but received {received}.',
+    ],
+  ]);
+}
+
+// ━━ EXPORT MODULE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+export default MiddlewareError;