@boo-labs/server 0.0.0-stage → 1.0.1

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

@@ -0,0 +1,208 @@
+// @ts-check
+/**
+ * @file Core validation module for representing strict validation outcomes.
+ *
+ * @description Provides the {@link Validation} class for explicitly representing
+ * successful and failed operations without relying on
+ * ambiguous `undefined` states.
+ *
+ * @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.
+ *
+ * @typedef  {object}    ValidationStateSuccess
+ * @property {true}      ok                     - Indicates that the validation succeeded.
+ * @property {undefined} [error]                - Always undefined for a successful validation.
+ */
+
+/**
+ * Represents the failed state of a {@link Validation} instance.
+ *
+ * @typedef  {object}      ValidationStateFailure
+ * @property {false}       ok                     - Indicates that the validation failed.
+ * @property {ErrorSchema} error                  - Error schema describing the validation failure.
+ */
+
+/**
+ * Represents the internal state of a {@link Validation} instance.
+ *
+ * @typedef {ValidationStateSuccess|ValidationStateFailure} ValidationState
+ */
+
+// ━━ MODULE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+/**
+ * Represents the strict outcome of a validation operation (pass/fail).
+ *
+ * Unlike Result, it does not carry a successful payload, only an error on failure.
+ */
+class Validation {
+  /**
+   * Internal validation state.
+   *
+   * @type {ValidationState}
+   */
+  #validation;
+
+  /**
+   * 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.
+   * @example
+   * ```js
+   * const validation = new Validation(true);
+   * ```
+   *
+   * @example
+   * ```js
+   * const validation = new Validation(false, {
+   *   error: TypeError,
+   *   message: 'Expected a string.',
+   *   code: 'INVALID_TYPE',
+   * });
+   * ```
+   */
+  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) };
+    }
+  }
+
+  /**
+   * Indicates whether the validation succeeded.
+   *
+   * @readonly
+   * @type {boolean}
+   */
+  get ok() {
+    return this.#validation.ok;
+  }
+
+  /**
+   * The instantiated error of the failed validation.
+   *
+   * @readonly
+   * @type {Error}
+   * @throws {Error} If the validation succeeded.
+   */
+  get error() {
+    if (this.#validation.ok === true) {
+      throw new Error('Cannot access error of a successful Validation.');
+    }
+
+    return this.#validation.error.error;
+  }
+
+  /**
+   * Creates a successful {@link Validation}.
+   *
+   * @returns {Validation} A successful Validation instance.
+   * @example
+   * ```js
+   * const validation = Validation.success();
+   *
+   * if (validation.ok) {
+   *   console.log('Validation passed.');
+   * }
+   * ```
+   */
+  static success() {
+    return new Validation(true);
+  }
+
+  /**
+   * Creates a failed {@link Validation}.
+   *
+   * @param {ErrorSchemaDefinition} error - The error details describing the failure.
+   * @returns {Validation} A failed Validation instance.
+   * @example
+   * ```js
+   * const validation = Validation.failure({
+   *   error: RangeError,
+   *   message: 'Value is out of range.',
+   *   code: 'VALUE_OUT_OF_RANGE',
+   * });
+   *
+   * if (!validation.ok) {
+   *   console.log(validation.error);
+   * }
+   * ```
+   */
+  static failure(error) {
+    return new Validation(false, error);
+  }
+}
+
+// ━━ EXPORT MODULE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+export default Validation;

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

@@ -0,0 +1,160 @@
+// @ts-check
+/**
+ * @file Middleware validation utilities.
+ *
+ * @description Validates middleware functions used by the HTTP server.
+ *
+ * @module Validation/Middleware
+ */
+
+// ━━ IMPORT MODULES ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// » IMPORT LOCAL MODULES
+import Validation from '#shared/outcome/Validation';
+import MiddlewareError from '#shared/errors/MiddlewareError';
+
+// ━━ MODULE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+/**
+ * Validates a middleware function.
+ *
+ * A middleware must be a function that declares exactly two parameters:
+ * `context` and `next`.
+ *
+ * @param {unknown} middleware - Middleware function to validate.
+ * @returns {Validation} Validation result.
+ * @example
+ * ```js
+ * const validation = validateMiddleware((context, next) => {
+ *   next();
+ * });
+ *
+ * console.log(validation.ok);
+ * // => true
+ * ```
+ *
+ * @example
+ * ```js
+ * const validation = validateMiddleware((context) => {
+ *   return context;
+ * });
+ *
+ * console.log(validation.ok);
+ * // => false
+ * ```
+ */
+export function validateMiddleware(middleware) {
+  if (typeof middleware !== 'function') {
+    return Validation.failure({
+      error: MiddlewareError,
+      code: 'INVALID_MIDDLEWARE_TYPE',
+      custom: true,
+      options: {
+        values: {
+          expected: 'function',
+          received: typeof middleware,
+        },
+      },
+    });
+  }
+
+  if (middleware.length !== 2) {
+    return Validation.failure({
+      error: MiddlewareError,
+      code: 'INVALID_MIDDLEWARE_ARITY',
+      custom: true,
+      options: {
+        values: {
+          expected: 2,
+          received: middleware.length,
+        },
+      },
+    });
+  }
+
+  return Validation.success();
+}
+
+/**
+ * Asserts that a middleware function is valid.
+ *
+ * @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) => {
+ *   next();
+ * });
+ * ```
+ */
+export function assertMiddleware(middleware) {
+  const validation = validateMiddleware(middleware);
+
+  if (!validation.ok) {
+    throw validation.error;
+  }
+}
+
+/**
+ * Validates an array of middleware functions.
+ *
+ * @param {unknown} middlewares - Middleware functions to validate.
+ * @returns {Validation} Validation result.
+ * @example
+ * ```js
+ * const validation = validateMiddlewares([
+ *   (context, next) => next(),
+ *   (context, next) => next(),
+ * ]);
+ *
+ * console.log(validation.ok);
+ * // => true
+ * ```
+ */
+export function validateMiddlewares(middlewares) {
+  if (!Array.isArray(middlewares)) {
+    return Validation.failure({
+      error: MiddlewareError,
+      code: 'INVALID_MIDDLEWARES_TYPE',
+      custom: true,
+      options: {
+        values: {
+          expected: 'array',
+          received: typeof middlewares,
+        },
+      },
+    });
+  }
+
+  for (const middleware of middlewares) {
+    const validation = validateMiddleware(middleware);
+
+    if (!validation.ok) {
+      return validation;
+    }
+  }
+
+  return Validation.success();
+}
+
+/**
+ * Asserts that all middleware functions are valid.
+ *
+ * @param {unknown} middlewares - Middleware functions to validate.
+ * @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([
+ *   (context, next) => next(),
+ *   (context, next) => next(),
+ * ]);
+ * ```
+ */
+export function assertMiddlewares(middlewares) {
+  const validation = validateMiddlewares(middlewares);
+
+  if (!validation.ok) {
+    throw validation.error;
+  }
+}

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

@@ -0,0 +1,256 @@
+// @ts-check
+/**
+ * @file Pathname pattern validation utilities.
+ *
+ * @description Validates pathname patterns used by the HTTP router, including
+ * parameter syntax, wildcard segments, length constraints, and duplicate
+ * parameter names.
+ *
+ * @module Validation/PathnamePattern
+ */
+
+// ━━ IMPORT MODULES ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// » IMPORT LOCAL MODULES
+import Validation from '#shared/outcome/Validation';
+import PathnamePatternError from '#shared/errors/PathnamePatternError';
+
+// ━━ CONSTANTS ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+/**
+ * Maximum number of characters allowed in a pathname pattern.
+ *
+ * @private
+ * @type {number}
+ */
+const MAX_PATTERN_LENGTH = 512;
+
+/**
+ * Regular expression source for a valid pathname parameter name.
+ *
+ * Parameter names must begin with a letter or underscore and may contain
+ * letters, digits, and underscores.
+ *
+ * @private
+ * @type {string}
+ */
+const PARAM_NAME = String.raw`[A-Za-z_][A-Za-z0-9_]*`;
+
+/**
+ * Regular expression source for a literal character allowed inside a pathname
+ * segment.
+ *
+ * @private
+ * @type {string}
+ */
+const LITERAL_CHAR = String.raw`[A-Za-z0-9._~!$&'()+,;=@-]`;
+
+/**
+ * Regular expression source for a parameter segment using colon or brace
+ * syntax.
+ *
+ * Supported forms are `:name` and `{name}`.
+ *
+ * @private
+ * @type {string}
+ */
+const PARAM_SEGMENT = String.raw`(?::${PARAM_NAME}|\{${PARAM_NAME}\})`;
+
+/**
+ * Regular expression source for a normal pathname segment.
+ *
+ * A normal segment may contain literal characters and parameter segments, but
+ * cannot represent `.` or `..` as complete path segments.
+ *
+ * @private
+ * @type {string}
+ */
+const NORMAL_SEGMENT = String.raw`(?!\.{1,2}(?=/|$))(?:${LITERAL_CHAR}|${PARAM_SEGMENT})+`;
+
+/**
+ * Regular expression source for a wildcard pathname segment.
+ *
+ * @private
+ * @type {string}
+ */
+const WILDCARD_SEGMENT = String.raw`\*`;
+
+/**
+ * Complete regular expression source for supported pathname patterns.
+ *
+ * The expression supports the global wildcard `*` and pathname patterns
+ * beginning with `/`, including parameter and trailing wildcard segments.
+ *
+ * @private
+ * @type {string}
+ */
+const PATHNAME_PATTERN_SEGMENT = String.raw`^(?:\*|/(?:${NORMAL_SEGMENT}(?:/${NORMAL_SEGMENT})*)?(?:/${WILDCARD_SEGMENT})?)$`;
+
+/**
+ * Regular expression used to validate pathname pattern syntax.
+ *
+ * @private
+ * @type {RegExp}
+ */
+const PATHNAME_PATTERN_REGEXP = new RegExp(PATHNAME_PATTERN_SEGMENT);
+
+/**
+ * Regular expression used to extract pathname parameter names.
+ *
+ * Both `:name` and `{name}` parameter syntaxes are supported.
+ *
+ * @private
+ * @type {RegExp}
+ */
+const PARAMETER_PATTERN_REGEXP = /:([A-Za-z_][A-Za-z0-9_]*)|\{([A-Za-z_][A-Za-z0-9_]*)\}/g;
+
+// ━━ FUNCTIONS ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+/**
+ * Validates that all parameter names in a pathname pattern are unique.
+ *
+ * Parameter names are compared by their literal names regardless of whether
+ * they use colon or brace syntax.
+ *
+ * @private
+ * @param {string} pathnamePattern - Pathname pattern to validate.
+ * @returns {Validation} Validation result.
+ * @example
+ * ```js
+ * const validation = validateUniqueParamNames('/users/:id/posts/{postId}');
+ *
+ * console.log(validation.ok);
+ * // => true
+ * ```
+ * @example
+ * ```js
+ * const validation = validateUniqueParamNames('/users/:id/posts/{id}');
+ *
+ * console.log(validation.ok);
+ * // => false
+ * ```
+ */
+function validateUniqueParamNames(pathnamePattern) {
+  const names = new Set();
+
+  for (const match of pathnamePattern.matchAll(PARAMETER_PATTERN_REGEXP)) {
+    const name = match[1] ?? match[2];
+
+    if (names.has(name)) {
+      return Validation.failure({
+        error: PathnamePatternError,
+        code: 'DUPLICATE_PARAMETER_NAME',
+        custom: true,
+        options: {
+          values: { name },
+          details: { pathnamePattern },
+        },
+      });
+    }
+
+    names.add(name);
+  }
+
+  return Validation.success();
+}
+
+// ━━ MODULE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+/**
+ * Validates a pathname pattern against the supported pathname syntax and
+ * semantic constraints.
+ *
+ * Validation is performed in the following order:
+ *
+ * 1. The pathname pattern must be a string.
+ * 2. The pathname pattern must not be empty.
+ * 3. The pathname pattern must not exceed the maximum allowed length.
+ * 4. The pathname pattern must match the supported pathname syntax.
+ * 5. Parameter names must be unique.
+ *
+ * @param {unknown} pathnamePattern - Pathname pattern to validate.
+ * @returns {Validation} Validation result.
+ * @example
+ * ```js
+ * const validation = validatePathnamePattern('/users/:id');
+ *
+ * console.log(validation.ok);
+ * // => true
+ * ```
+ *
+ * @example
+ * ```js
+ * const validation = validatePathnamePattern('/users/:id/:id');
+ *
+ * console.log(validation.ok);
+ * // => false
+ * ```
+ */
+export function validatePathnamePattern(pathnamePattern) {
+  if (typeof pathnamePattern !== 'string') {
+    return Validation.failure({
+      error: PathnamePatternError,
+      code: 'INVALID_PATTERN_TYPE',
+      custom: true,
+      options: {
+        values: { expected: 'string', received: typeof pathnamePattern },
+      },
+    });
+  }
+
+  if (pathnamePattern.length === 0) {
+    return Validation.failure({
+      error: PathnamePatternError,
+      code: 'EMPTY_PATTERN',
+      custom: true,
+    });
+  }
+
+  if (pathnamePattern.length > MAX_PATTERN_LENGTH) {
+    return Validation.failure({
+      error: PathnamePatternError,
+      code: 'PATTERN_TOO_LONG',
+      custom: true,
+      options: {
+        values: { maxLength: MAX_PATTERN_LENGTH, actualLength: pathnamePattern.length },
+      },
+    });
+  }
+
+  if (!PATHNAME_PATTERN_REGEXP.test(pathnamePattern)) {
+    return Validation.failure({
+      error: PathnamePatternError,
+      code: 'INVALID_PATHNAME_PATTERN',
+      custom: true,
+      options: {
+        values: { pathnamePattern },
+        details: { constraint: 'Must be * or start with / and contain valid segments' },
+      },
+    });
+  }
+
+  return validateUniqueParamNames(pathnamePattern);
+}
+
+/**
+ * Asserts that a pathname pattern is valid.
+ *
+ * @param {unknown} pathnamePattern - Pathname pattern to validate.
+ * @throws {PathnamePatternError} If the pathname pattern is not a string.
+ * @throws {PathnamePatternError} If the pathname pattern is empty.
+ * @throws {PathnamePatternError} If the pathname pattern exceeds the maximum length.
+ * @throws {PathnamePatternError} If the pathname pattern syntax is invalid.
+ * @throws {PathnamePatternError} If the pathname pattern has duplicate parameter names.
+ * @example
+ * ```js
+ * assertPathnamePattern('/users/:id');
+ * ```
+ *
+ * @example
+ * ```js
+ * assertPathnamePattern('/users/:id/:id');
+ * // throws PathnamePatternError with code 'DUPLICATE_PARAMETER_NAME'
+ * ```
+ */
+export function assertPathnamePattern(pathnamePattern) {
+  const validation = validatePathnamePattern(pathnamePattern);
+  if (!validation.ok) {
+    throw validation.error;
+  }
+}

package/source/shared/validations/Server/NotFoundHandler/index.mjs

@@ -0,0 +1,94 @@
+// @ts-check
+/**
+ * @file NotFoundHandler validation utilities.
+ *
+ * @description Validates handlers used to resolve requests that do not match
+ * any registered route.
+ *
+ * @module Validation/Server/NotFoundHandler
+ */
+
+// ━━ IMPORT MODULES ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// » IMPORT LOCAL MODULES
+import Validation from '#shared/outcome/Validation';
+import ServerError from '#shared/errors/ServerError';
+
+// ━━ MODULE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+/**
+ * Validates a not-found handler.
+ *
+ * A not-found handler must be a function that declares exactly one parameter:
+ * `exchange`.
+ *
+ * @param {unknown} handler - Handler function to validate.
+ * @returns {Validation} Validation result.
+ * @example
+ * ```js
+ * const validation = validateNotFoundHandler((exchange) => {
+ *   exchange.response.status(404).end();
+ * });
+ *
+ * console.log(validation.ok);
+ * // => true
+ * ```
+ *
+ * @example
+ * ```js
+ * const validation = validateNotFoundHandler(() => {});
+ *
+ * console.log(validation.ok);
+ * // => false
+ * ```
+ */
+export function validateNotFoundHandler(handler) {
+  if (typeof handler !== 'function') {
+    return Validation.failure({
+      error: ServerError,
+      code: 'INVALID_NOT_FOUND_HANDLER_TYPE',
+      custom: true,
+      options: {
+        values: {
+          expected: 'function',
+          received: typeof handler,
+        },
+      },
+    });
+  }
+
+  if (handler.length !== 1) {
+    return Validation.failure({
+      error: ServerError,
+      code: 'INVALID_NOT_FOUND_HANDLER_ARITY',
+      custom: true,
+      options: {
+        values: {
+          expected: 1,
+          received: handler.length,
+        },
+      },
+    });
+  }
+
+  return Validation.success();
+}
+
+/**
+ * Asserts that a not-found handler is valid.
+ *
+ * @param {unknown} handler - Handler function to validate.
+ * @throws {ServerError} If the handler is not a function.
+ * @throws {ServerError} If the handler does not declare exactly one parameter.
+ * @example
+ * ```js
+ * assertNotFoundHandler((exchange) => {
+ *   exchange.response.status(404).end();
+ * });
+ * ```
+ */
+export function assertNotFoundHandler(handler) {
+  const validation = validateNotFoundHandler(handler);
+
+  if (!validation.ok) {
+    throw validation.error;
+  }
+}