@boo-labs/server 1.0.1 → 1.0.2

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

@@ -1,203 +1,153 @@
 // @ts-check
 /**
- * @file Core result module for representing strict operation outcomes.
+ * @file Result — Represents successful and failed operation outcomes.
  *
- * @description Provides the {@link Result} class for explicitly representing
- * successful and failed operations without relying on ambiguous `undefined`
- * states.
+ * @description Provides a generic Result type that explicitly distinguishes
+ * successful operations from failed ones through the `ok` discriminant.
+ * The discriminant determines which value is available: `value` on success
+ * or `error` on failure. Accessing the property for the opposite state throws.
  *
  * @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.
+ * The value associated with a Result state.
  *
- * @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.
+ * @template {boolean} K
+ * @template T
+ * @typedef {K extends true ? T : undefined } Value
  */
 
 /**
- * Represents a supported Error schema definition.
+ * The error associated with a Result state.
  *
- * @typedef {NativeErrorSchema|CustomErrorSchema} ErrorSchemaDefinition
+ * @template {boolean} K
+ * @template E
+ * @typedef {K extends false ? E : undefined} ErrorValue
  */
 
 /**
- * Represents the successful state of a {@link Result} instance.
+ * A successful {@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.
+ * @typedef {Result<true, T, undefined>} SuccessResult
  */
 
 /**
- * Represents the internal state of a {@link Result} instance.
+ * A failed {@link Result} instance.
  *
- * @template T
- * @typedef {ResultSuccess<T>|ResultFailure} ResultState
+ * @template E
+ * @typedef {Result<false, undefined, E>} FailureResult
  */
 
 // ━━ MODULE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
 /**
- * Represents the strict outcome of an operation that may yield a value or an
- * error.
+ * Represents the outcome of an operation.
+ *
+ * @classdesc `Result` uses the `ok` property as a discriminant to distinguish
+ * successful outcomes from failures. A successful result exposes `value`,
+ * while a failed result exposes `error`. Accessing the property associated
+ * with the opposite state throws an error.
  *
+ * @template {boolean} K
  * @template T
+ * @template E
  */
 class Result {
   /**
-   * Stores the internal result state.
+   * Indicates whether the operation succeeded.
+   *
+   * @type {K}
+   */
+  #ok;
+
+  /**
+   * Stores the value associated with a successful operation.
    *
-   * @type {ResultState<T>}
+   * @type {Value<K, T>}
    */
-  #result;
+  #value;
 
   /**
-   * Creates a Result instance.
+   * Stores the error associated with a failed operation.
+   *
+   * @type {ErrorValue<K, E>}
+   */
+  #error;
+
+  /**
+   * Creates a Result instance with the specified outcome.
+   *
+   * The `ok` flag determines which argument represents the meaningful
+   * result: `value` for success or `error` for failure.
+   *
+   * @param {K} ok - Whether the operation succeeded.
+   * @param {Value<K, T>} value - The successful value, if applicable.
+   * @param {ErrorValue<K, E>} error - The failure value, if applicable.
    *
-   * @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' });
+   * const result = new Result(true, { id: '123' }, undefined);
    * ```
    *
    * @example
    * ```js
-   * const result = new Result(false, undefined, {
-   *   error: RangeError,
-   *   message: 'Value is out of range.',
-   *   custom: false,
-   *   code: 'ERR_RANGE',
-   * });
+   * const result = new Result(false, undefined, new RangeError('Value is out of 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),
-      };
-    }
+    this.#ok = ok;
+    this.#value = value;
+    this.#error = error;
   }
 
   /**
    * Indicates whether the operation succeeded.
    *
    * @readonly
-   * @type {boolean}
+   * @type {K}
    */
   get ok() {
-    return this.#result.ok;
+    return this.#ok;
   }
 
   /**
    * The successful value of the operation.
    *
    * @readonly
-   * @type {T}
+   * @type {Value<K, T>}
    * @throws {Error} If the result is not ok.
    */
   get value() {
-    if (this.#result.ok === false) {
+    if (this.#ok !== true) {
       throw new Error('Cannot access value of a failed Result.');
     }
-
-    return this.#result.value;
+    return this.#value;
   }
 
   /**
-   * The instantiated error of the failed operation.
+   * The error instance of the failed operation.
    *
    * @readonly
-   * @type {Error}
+   * @type {ErrorValue<K, E>}
    * @throws {Error} If the result is ok.
    */
   get error() {
-    if (this.#result.ok === true) {
+    if (this.#ok !== false) {
       throw new Error('Cannot access error of a successful Result.');
     }
-
-    return this.#result.error.error;
+    return this.#error;
   }
 
   /**
    * Creates a successful {@link Result}.
    *
-   * @template U
-   * @param {U} [value] - The successful value.
-   * @returns {Result<U>} A successful Result instance.
+   * @template V
+   * @param {V} value - The successful value.
+   * @returns {SuccessResult<V>} A successful Result instance.
+   *
    * @example
    * ```js
    * const result = Result.success({ id: '123' });
@@ -208,22 +158,19 @@ class Result {
    * ```
    */
   static success(value) {
-    return new Result(true, value);
+    return new Result(true, value, undefined);
   }
 
   /**
    * Creates a failed {@link Result}.
    *
-   * @param {ErrorSchemaDefinition} error - The error details describing the failure.
-   * @returns {Result<never>} A failed Result instance.
+   * @template {Error} E
+   * @param {E} error - The error instance describing the failure.
+   * @returns {FailureResult<E>} A failed Result instance.
+   *
    * @example
    * ```js
-   * const result = Result.failure({
-   *   error: RangeError,
-   *   message: 'Value is out of range.',
-   *   custom: false,
-   *   code: 'ERR_RANGE',
-   * });
+   * const result = Result.failure(new RangeError('Value is out of range.'));
    *
    * if (!result.ok) {
    *   console.log(result.error);
@@ -231,7 +178,7 @@ class Result {
    * ```
    */
   static failure(error) {
-    return /** @type {Result<never>} */ (new Result(false, undefined, error));
+    return new Result(false, undefined, error);
   }
 }
 

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

@@ -1,173 +1,117 @@
 // @ts-check
 /**
- * @file Core validation module for representing strict validation outcomes.
+ * @file Validation — Represents successful and failed validation outcomes.
  *
- * @description Provides the {@link Validation} class for explicitly representing
- * successful and failed operations without relying on
- * ambiguous `undefined` states.
+ * @description Provides a generic Validation type that explicitly distinguishes
+ * successful validations from failed ones through the `ok` discriminant.
+ * A successful validation has no payload. A failed validation exposes `error`.
+ * Accessing `error` on a successful validation throws.
  *
  * @module Validation
  */
 
-// ━━ IMPORT MODULES ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-// » IMPORT LOCAL MODULES
-import ErrorSchema from '../ErrorSchema.mjs';
-
 // ━━ 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
- */
-
-/**
- * Represents the successful state of a {@link Validation} instance.
+ * The error associated with a Validation state.
  *
- * @typedef  {object}    ValidationStateSuccess
- * @property {true}      ok                     - Indicates that the validation succeeded.
- * @property {undefined} [error]                - Always undefined for a successful validation.
+ * @template {boolean} K
+ * @template E
+ * @typedef {K extends false ? E : undefined} ErrorValue
  */
 
 /**
- * Represents the failed state of a {@link Validation} instance.
+ * A successful {@link Validation} instance.
  *
- * @typedef  {object}      ValidationStateFailure
- * @property {false}       ok                     - Indicates that the validation failed.
- * @property {ErrorSchema} error                  - Error schema describing the validation failure.
+ * @typedef {Validation<true, undefined>} SuccessValidation
  */
 
 /**
- * Represents the internal state of a {@link Validation} instance.
+ * A failed {@link Validation} instance.
  *
- * @typedef {ValidationStateSuccess|ValidationStateFailure} ValidationState
+ * @template {Error} E
+ * @typedef {Validation<false, E>} FailureValidation
  */
 
 // ━━ MODULE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 /**
- * Represents the strict outcome of a validation operation (pass/fail).
+ * Represents the outcome of a validation operation (pass / fail).
  *
- * Unlike Result, it does not carry a successful payload, only an error on failure.
+ * @classdesc `Validation` uses the `ok` property as a discriminant to
+ * distinguish successful validations from failures. A successful validation
+ * has no payload; a failed validation exposes `error`. Accessing `error` on
+ * a successful validation throws.
+ *
+ * @template {boolean} K
+ * @template E
  */
 class Validation {
   /**
-   * Internal validation state.
+   * Indicates whether the validation succeeded.
+   *
+   * @type {K}
+   */
+  #ok;
+
+  /**
+   * Stores the error associated with a failed validation.
    *
-   * @type {ValidationState}
+   * @type {ErrorValue<K, E>}
    */
-  #validation;
+  #error;
 
   /**
    * Creates a Validation instance.
    *
-   * @param {boolean} ok - Whether the validation succeeded.
-   * @param {ErrorSchemaDefinition} [error] - Required when ok is false.
-   * @throws {TypeError} If the combination of ok and error is invalid.
+   * The `ok` flag determines whether an error is required: no error on success,
+   * a required error instance on failure.
+   *
+   * @param {K} ok - Whether the validation succeeded.
+   * @param {ErrorValue<K, E>} error - The error instance, required when ok is false.
+   *
    * @example
    * ```js
-   * const validation = new Validation(true);
+   * const validation = new Validation(true, undefined);
    * ```
    *
    * @example
    * ```js
-   * const validation = new Validation(false, {
-   *   error: TypeError,
-   *   message: 'Expected a string.',
-   *   code: 'INVALID_TYPE',
-   * });
+   * const validation = new Validation(false, new TypeError('Expected a string.'));
    * ```
    */
   constructor(ok, error) {
-    if (typeof ok !== 'boolean') {
-      throw new TypeError('Validation status (ok) must be a boolean.');
-    }
-
-    if (ok === true) {
-      if (error !== undefined) {
-        throw new TypeError('A successful Validation cannot contain an error.');
-      }
-
-      this.#validation = { ok, error };
-    } else {
-      if (error === undefined) {
-        throw new TypeError('A failed Validation must contain an error.');
-      }
-      this.#validation = { ok, error: new ErrorSchema(error) };
-    }
+    this.#ok = ok;
+    this.#error = error;
   }
 
   /**
    * Indicates whether the validation succeeded.
    *
    * @readonly
-   * @type {boolean}
+   * @type {K}
    */
   get ok() {
-    return this.#validation.ok;
+    return this.#ok;
   }
 
   /**
-   * The instantiated error of the failed validation.
+   * The error instance of the failed validation.
    *
    * @readonly
-   * @type {Error}
+   * @type {ErrorValue<K, E>}
    * @throws {Error} If the validation succeeded.
    */
   get error() {
-    if (this.#validation.ok === true) {
+    if (this.#ok !== false) {
       throw new Error('Cannot access error of a successful Validation.');
     }
-
-    return this.#validation.error.error;
+    return this.#error;
   }
 
   /**
    * Creates a successful {@link Validation}.
    *
-   * @returns {Validation} A successful Validation instance.
+   * @returns {SuccessValidation} A successful Validation instance.
+   *
    * @example
    * ```js
    * const validation = Validation.success();
@@ -178,21 +122,19 @@ class Validation {
    * ```
    */
   static success() {
-    return new Validation(true);
+    return new Validation(true, undefined);
   }
 
   /**
    * Creates a failed {@link Validation}.
    *
-   * @param {ErrorSchemaDefinition} error - The error details describing the failure.
-   * @returns {Validation} A failed Validation instance.
+   * @template {Error} E
+   * @param {E} error - The error instance describing the failure.
+   * @returns {FailureValidation<E>} A failed Validation instance.
+   *
    * @example
    * ```js
-   * const validation = Validation.failure({
-   *   error: RangeError,
-   *   message: 'Value is out of range.',
-   *   code: 'VALUE_OUT_OF_RANGE',
-   * });
+   * const validation = Validation.failure(new RangeError('Value is out of range.'));
    *
    * if (!validation.ok) {
    *   console.log(validation.error);

package/source/shared/validations/Middleware/index.mjs

@@ -12,6 +12,20 @@
 import Validation from '#shared/outcome/Validation';
 import MiddlewareError from '#shared/errors/MiddlewareError';
 
+// ━━ 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
+ */
+
 // ━━ MODULE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 /**
  * Validates a middleware function.
@@ -20,7 +34,8 @@ import MiddlewareError from '#shared/errors/MiddlewareError';
  * `context` and `next`.
  *
  * @param {unknown} middleware - Middleware function to validate.
- * @returns {Validation} Validation result.
+ * @returns {SuccessValidation|FailureValidation<MiddlewareError>} Validation result.
+ *
  * @example
  * ```js
  * const validation = validateMiddleware((context, next) => {
@@ -43,31 +58,25 @@ import MiddlewareError from '#shared/errors/MiddlewareError';
  */
 export function validateMiddleware(middleware) {
   if (typeof middleware !== 'function') {
-    return Validation.failure({
-      error: MiddlewareError,
-      code: 'INVALID_MIDDLEWARE_TYPE',
-      custom: true,
-      options: {
+    return Validation.failure(
+      new MiddlewareError('INVALID_MIDDLEWARE_TYPE', {
         values: {
           expected: 'function',
           received: typeof middleware,
         },
-      },
-    });
+      }),
+    );
   }
 
   if (middleware.length !== 2) {
-    return Validation.failure({
-      error: MiddlewareError,
-      code: 'INVALID_MIDDLEWARE_ARITY',
-      custom: true,
-      options: {
+    return Validation.failure(
+      new MiddlewareError('INVALID_MIDDLEWARE_ARITY', {
         values: {
           expected: 2,
           received: middleware.length,
         },
-      },
-    });
+      }),
+    );
   }
 
   return Validation.success();
@@ -79,6 +88,7 @@ export function validateMiddleware(middleware) {
  * @param {unknown} middleware - Middleware function to validate.
  * @throws {MiddlewareError} If the middleware is not a function.
  * @throws {MiddlewareError} If the middleware does not declare exactly two parameters.
+ *
  * @example
  * ```js
  * assertMiddleware((context, next) => {
@@ -98,7 +108,8 @@ export function assertMiddleware(middleware) {
  * Validates an array of middleware functions.
  *
  * @param {unknown} middlewares - Middleware functions to validate.
- * @returns {Validation} Validation result.
+ * @returns {SuccessValidation|FailureValidation<MiddlewareError>} Validation result.
+ *
  * @example
  * ```js
  * const validation = validateMiddlewares([
@@ -112,17 +123,14 @@ export function assertMiddleware(middleware) {
  */
 export function validateMiddlewares(middlewares) {
   if (!Array.isArray(middlewares)) {
-    return Validation.failure({
-      error: MiddlewareError,
-      code: 'INVALID_MIDDLEWARES_TYPE',
-      custom: true,
-      options: {
+    return Validation.failure(
+      new MiddlewareError('INVALID_MIDDLEWARES_TYPE', {
         values: {
           expected: 'array',
           received: typeof middlewares,
         },
-      },
-    });
+      }),
+    );
   }
 
   for (const middleware of middlewares) {
@@ -143,6 +151,7 @@ export function validateMiddlewares(middlewares) {
  * @throws {MiddlewareError} If the middleware collection is not an array.
  * @throws {MiddlewareError} If a middleware is not a function.
  * @throws {MiddlewareError} If a middleware does not declare exactly two parameters.
+ *
  * @example
  * ```js
  * assertMiddlewares([