@boo-labs/server 1.0.1 → 1.0.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@boo-labs/server",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "A zero-dependency, frameworkless HTTP server for Node.js, built around Clean Architecture principles.",
   "keywords": [
     "http-server",

package/source/core/IPCMain/IPCProtocol.mjs

@@ -17,6 +17,20 @@
 import Result from '#shared/outcome/Result';
 
 // ━━ TYPE DEFINITIONS ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+/**
+ * A successful {@link Result} instance.
+ *
+ * @template T
+ * @typedef {import('#shared/outcome/Result').SuccessResult<T>} SuccessResult
+ */
+
+/**
+ * A failed {@link Result} instance.
+ *
+ * @template {Error} E
+ * @typedef {import('#shared/outcome/Result').FailureResult<E>} FailureResult
+ */
+
 /**
  * Represents an IPC invocation request.
  *
@@ -99,6 +113,18 @@ function isPlainObject(value) {
   return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
 
+/**
+ * Attaches a machine-readable code to an Error instance.
+ *
+ * @template {Error} E
+ * @param {E} error - Error instance to annotate.
+ * @param {string} code - Machine-readable error code.
+ * @returns {E & { code: string }} The annotated error.
+ */
+function withCode(error, code) {
+  return Object.assign(error, { code });
+}
+
 // ━━ MODULE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 /**
  * Implements the IPC wire protocol for decoding requests and serializing responses.
@@ -243,25 +269,19 @@ class IPCProtocol {
    * a failure describing the first structural violation encountered.
    *
    * @param {unknown} message - Parsed IPC payload.
-   * @returns {Result<IPCRequest>} Successful result containing the normalized request, or a failure describing the validation error.
+   * @returns {SuccessResult<IPCRequest>|FailureResult<TypeError|ReferenceError>} Successful result containing the normalized request, or a failure describing the validation error.
    */
   #ensureRequest(message) {
     if (!isPlainObject(message)) {
-      return Result.failure({
-        error: TypeError,
-        message: 'IPC message must be a plain object.',
-        code: 'IPC_INVALID_MESSAGE',
-        custom: false,
-      });
+      return Result.failure(
+        withCode(new TypeError('IPC message must be a plain object.'), 'IPC_INVALID_MESSAGE'),
+      );
     }
 
     if (!('type' in message)) {
-      return Result.failure({
-        error: ReferenceError,
-        message: 'IPC message requires a "type" property.',
-        code: 'IPC_MISSING_TYPE',
-        custom: false,
-      });
+      return Result.failure(
+        withCode(new ReferenceError('IPC message requires a "type" property.'), 'IPC_MISSING_TYPE'),
+      );
     }
 
     if (message.type === 'invoke') {
@@ -272,73 +292,61 @@ class IPCProtocol {
       return this.#ensureEventRequest(message);
     }
 
-    return Result.failure({
-      error: TypeError,
-      message: 'IPC message type must be "invoke" or "event".',
-      code: 'IPC_INVALID_TYPE',
-      custom: false,
-    });
+    return Result.failure(
+      withCode(new TypeError('IPC message type must be "invoke" or "event".'), 'IPC_INVALID_TYPE'),
+    );
   }
 
   /**
    * Ensures a parsed IPC payload is a valid invocation request.
    *
    * @param {Record<string, unknown>} message - Parsed IPC payload.
-   * @returns {Result<IPCInvokeRequest>} Successful result containing the normalized request, or a failure describing the validation error.
+   * @returns {SuccessResult<IPCInvokeRequest>|FailureResult<TypeError|ReferenceError|RangeError>} Successful result containing the normalized request, or a failure describing the validation error.
    */
   #ensureInvokeRequest(message) {
     if (!('channel' in message)) {
-      return Result.failure({
-        error: ReferenceError,
-        message: 'IPC message requires a "channel" property.',
-        code: 'IPC_MISSING_CHANNEL',
-        custom: false,
-      });
+      return Result.failure(
+        withCode(
+          new ReferenceError('IPC message requires a "channel" property.'),
+          'IPC_MISSING_CHANNEL',
+        ),
+      );
     }
 
     if (typeof message.channel !== 'string') {
-      return Result.failure({
-        error: TypeError,
-        message: 'IPC channel must be a string.',
-        code: 'IPC_INVALID_CHANNEL_TYPE',
-        custom: false,
-      });
+      return Result.failure(
+        withCode(new TypeError('IPC channel must be a string.'), 'IPC_INVALID_CHANNEL_TYPE'),
+      );
     }
 
     if (message.channel.trim().length === 0) {
-      return Result.failure({
-        error: RangeError,
-        message: 'IPC channel must be a non-empty string.',
-        code: 'IPC_INVALID_CHANNEL_RANGE',
-        custom: false,
-      });
+      return Result.failure(
+        withCode(
+          new RangeError('IPC channel must be a non-empty string.'),
+          'IPC_INVALID_CHANNEL_RANGE',
+        ),
+      );
     }
 
     if (!('id' in message)) {
-      return Result.failure({
-        error: ReferenceError,
-        message: 'IPC invocation requires an "id" property.',
-        code: 'IPC_MISSING_ID',
-        custom: false,
-      });
+      return Result.failure(
+        withCode(new ReferenceError('IPC invocation requires an "id" property.'), 'IPC_MISSING_ID'),
+      );
     }
 
     if (typeof message.id !== 'string') {
-      return Result.failure({
-        error: TypeError,
-        message: 'IPC invocation id must be a string.',
-        code: 'IPC_INVALID_ID_TYPE',
-        custom: false,
-      });
+      return Result.failure(
+        withCode(new TypeError('IPC invocation id must be a string.'), 'IPC_INVALID_ID_TYPE'),
+      );
     }
 
     if (message.id.trim().length === 0) {
-      return Result.failure({
-        error: RangeError,
-        message: 'IPC invocation id must be a non-empty string.',
-        code: 'IPC_INVALID_ID_RANGE',
-        custom: false,
-      });
+      return Result.failure(
+        withCode(
+          new RangeError('IPC invocation id must be a non-empty string.'),
+          'IPC_INVALID_ID_RANGE',
+        ),
+      );
     }
 
     return Result.success({
@@ -353,34 +361,31 @@ class IPCProtocol {
    * Ensures a parsed IPC payload is a valid event request.
    *
    * @param {Record<string, unknown>} message - Parsed IPC payload.
-   * @returns {Result<IPCEventRequest>} Successful result containing the normalized request, or a failure describing the validation error.
+   * @returns {SuccessResult<IPCEventRequest>|FailureResult<TypeError|ReferenceError|RangeError>} Successful result containing the normalized request, or a failure describing the validation error.
    */
   #ensureEventRequest(message) {
     if (!('channel' in message)) {
-      return Result.failure({
-        error: ReferenceError,
-        message: 'IPC message requires a "channel" property.',
-        code: 'IPC_MISSING_CHANNEL',
-        custom: false,
-      });
+      return Result.failure(
+        withCode(
+          new ReferenceError('IPC message requires a "channel" property.'),
+          'IPC_MISSING_CHANNEL',
+        ),
+      );
     }
 
     if (typeof message.channel !== 'string') {
-      return Result.failure({
-        error: TypeError,
-        message: 'IPC channel must be a string.',
-        code: 'IPC_INVALID_CHANNEL_TYPE',
-        custom: false,
-      });
+      return Result.failure(
+        withCode(new TypeError('IPC channel must be a string.'), 'IPC_INVALID_CHANNEL_TYPE'),
+      );
     }
 
     if (message.channel.trim().length === 0) {
-      return Result.failure({
-        error: RangeError,
-        message: 'IPC channel must be a non-empty string.',
-        code: 'IPC_INVALID_CHANNEL_RANGE',
-        custom: false,
-      });
+      return Result.failure(
+        withCode(
+          new RangeError('IPC channel must be a non-empty string.'),
+          'IPC_INVALID_CHANNEL_RANGE',
+        ),
+      );
     }
 
     return Result.success({

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

@@ -13,6 +13,20 @@
  * @module UUIDV7
  */
 
+// ━━ TYPE DEFINITIONS ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+/**
+ * A successful {@link Validation} instance.
+ *
+ * @typedef {import('#shared/outcome/Validation').SuccessValidation} SuccessValidation
+ */
+
+/**
+ * A failed {@link Validation} instance.
+ *
+ * @template {Error} E
+ * @typedef {import('#shared/outcome/Validation').FailureValidation<E>} FailureValidation
+ */
+
 // ━━ IMPORT MODULES ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 // » IMPORT NATIVE NODEJS MODULES
 import { randomBytes } from 'node:crypto';
@@ -42,6 +56,11 @@ const UUIDV7_REGEXP = /^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[
  * sortable.
  */
 class UUIDV7 {
+  /**
+   * The UUID value.
+   *
+   * @type {string}
+   */
   #uuid;
 
   /**
@@ -235,8 +254,9 @@ class UUIDV7 {
    * timestamp, and a UUID v7 string represents the timestamp encoded in that
    * UUID.
    *
-   * @param {*} value - Value to validate.
-   * @returns {Validation} Validation result.
+   * @param {unknown} value - Value to validate.
+   * @returns {SuccessValidation|FailureValidation<RangeError|TypeError>} Validation result.
+   *
    * @example
    * ```js
    * const result = UUIDV7.validate();
@@ -249,41 +269,27 @@ class UUIDV7 {
 
     if (value instanceof Date) {
       if (Number.isNaN(value.getTime())) {
-        return Validation.failure({
-          error: RangeError,
-          message: 'Invalid timestamp.',
-          code: 'INVALID_TIMESTAMP',
-          custom: false,
-        });
+        return Validation.failure(new RangeError('Invalid timestamp.'));
       }
       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.failure(new RangeError('Invalid UUID v7.'));
       }
       return Validation.success();
     }
 
-    return Validation.failure({
-      error: TypeError,
-      message: 'Timestamp must be a Date, string, or undefined.',
-      code: 'INVALID_TIMESTAMP_SOURCE',
-      custom: false,
-    });
+    return Validation.failure(new TypeError('Timestamp must be a Date, string, or undefined.'));
   }
 
   /**
    * Validates that a value is a valid UUID v7 string.
    *
    * @param {unknown} value - Value to validate.
-   * @returns {Validation} Validation result.
+   * @returns {SuccessValidation|FailureValidation<ReferenceError|RangeError|TypeError>} Validation result.
+   *
    * @example
    * ```js
    * const result = UUIDV7.validateUUIDString('019937f2-1234-7abc-8def-123456789abc');
@@ -291,30 +297,15 @@ class UUIDV7 {
    */
   static validateUUIDString(value) {
     if (value === undefined) {
-      return Validation.failure({
-        error: ReferenceError,
-        message: 'UUID must be a string.',
-        custom: false,
-        code: 'MISSING_UUID',
-      });
+      return Validation.failure(new ReferenceError('UUID must be a string.'));
     }
 
     if (typeof value !== 'string') {
-      return Validation.failure({
-        error: TypeError,
-        message: 'UUID must be a string.',
-        custom: false,
-        code: 'INVALID_UUID_TYPE',
-      });
+      return Validation.failure(new TypeError('UUID must be a string.'));
     }
 
     if (!UUIDV7_REGEXP.test(value)) {
-      return Validation.failure({
-        error: RangeError,
-        message: 'Invalid UUID v7 format.',
-        custom: false,
-        code: 'INVALID_UUID',
-      });
+      return Validation.failure(new RangeError('Invalid UUID v7 format.'));
     }
 
     return Validation.success();
@@ -328,6 +319,7 @@ class UUIDV7 {
    * @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());

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

@@ -34,7 +34,15 @@ import BaseError from '../BaseError/index.mjs';
  * 'SERVER_CLOSED' |
  * 'SERVER_ERROR' |
  * 'SERVER_INVALID_STATE_TRANSITION' |
- * 'SERVER_EXCHANGE_INIT_FAILED'
+ * 'SERVER_EXCHANGE_INIT_FAILED' |
+ * 'INVALID_ROUTER_TYPE' |
+ * 'INVALID_ROUTER_INSTANCE' |
+ * 'INVALID_SYSTEM_ERROR_HANDLER_TYPE' |
+ * 'INVALID_SYSTEM_ERROR_HANDLER_ARITY' |
+ * 'INVALID_NOT_FOUND_HANDLER_TYPE' |
+ * 'INVALID_NOT_FOUND_HANDLER_ARITY' |
+ * 'INVALID_SERVER_CONFIGURATION_TYPE' |
+ * 'INVALID_SERVER_CONFIGURATION_INSTANCE'
  * >} ServerErrorIdentifier
  */
 
@@ -88,13 +96,29 @@ class ServerError extends BaseError {
   /**
    * Collection of predefined server error messages.
    *
-   * Available error identifiers.
+   * Available error identifiers:
    *
    * - `SERVER_LISTEN_FAILED`.
    * - `SERVER_CLOSE_FAILED`.
+   * - `SERVER_ADAPTER_INIT_FAILED`.
+   * - `SERVER_ALREADY_STARTING`.
    * - `SERVER_ALREADY_LISTENING`.
+   * - `SERVER_ALREADY_STOPPING`.
    * - `SERVER_ALREADY_CLOSED`.
+   * - `SERVER_NOT_LISTENING`.
+   * - `SERVER_STOPPING`.
+   * - `SERVER_CLOSED`.
+   * - `SERVER_ERROR`.
    * - `SERVER_INVALID_STATE_TRANSITION`.
+   * - `SERVER_EXCHANGE_INIT_FAILED`.
+   * - `INVALID_ROUTER_TYPE`.
+   * - `INVALID_ROUTER_INSTANCE`.
+   * - `INVALID_SYSTEM_ERROR_HANDLER_TYPE`.
+   * - `INVALID_SYSTEM_ERROR_HANDLER_ARITY`.
+   * - `INVALID_NOT_FOUND_HANDLER_TYPE`.
+   * - `INVALID_NOT_FOUND_HANDLER_ARITY`.
+   * - `INVALID_SERVER_CONFIGURATION_TYPE`.
+   * - `INVALID_SERVER_CONFIGURATION_INSTANCE`.
    *
    * @private
    * @static
@@ -121,6 +145,28 @@ class ServerError extends BaseError {
 
     // Exchange
     ['SERVER_EXCHANGE_INIT_FAILED', 'Failed to create the exchange for the incoming request.'],
+
+    // Router
+    ['INVALID_ROUTER_TYPE', 'Expected a Router instance, received: {received}.'],
+    ['INVALID_ROUTER_INSTANCE', 'Expected a Router instance.'],
+
+    // SystemErrorHandler
+    ['INVALID_SYSTEM_ERROR_HANDLER_TYPE', 'Handler must be a function, received: {received}.'],
+    [
+      'INVALID_SYSTEM_ERROR_HANDLER_ARITY',
+      'Handler must declare 2 parameters, received: {received}.',
+    ],
+
+    // NotFoundHandler
+    ['INVALID_NOT_FOUND_HANDLER_TYPE', 'Handler must be a function, received: {received}.'],
+    ['INVALID_NOT_FOUND_HANDLER_ARITY', 'Handler must declare 1 parameter, received: {received}.'],
+
+    // ServerConfiguration
+    [
+      'INVALID_SERVER_CONFIGURATION_TYPE',
+      'Expected a ServerConfiguration instance, received: {received}.',
+    ],
+    ['INVALID_SERVER_CONFIGURATION_INSTANCE', 'Expected a ServerConfiguration instance.'],
   ]);
 }
 // ━━ EXPORT MODULE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━