@boo-labs/server 0.0.0-stage → 1.0.0

package/source/core/routing/ExchangeLayer/ExchangeMatcher.mjs

@@ -0,0 +1,127 @@
+// @ts-check
+/**
+ * @file Defines the request matching pattern used by the HTTP routing layer.
+ *
+ * @description Provides the ExchangeMatcher class for evaluating whether
+ * incoming HTTP requests satisfy configured routing criteria using the native
+ * URLPattern API.
+ *
+ * @module ExchangeMatcher
+ */
+
+// ━━ TYPE DEFINITIONS ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+/**
+ * Represents a single HTTP transaction.
+ *
+ * @typedef {import('#Exchange').default} Exchange
+ */
+
+/**
+ * Represents an HTTP method supported by the routing layer.
+ *
+ * @typedef {'GET'|'HEAD'|'POST'|'PUT'|'PATCH'|'DELETE'|'OPTIONS'|'QUERY'|'TRACE'} HTTPMethod
+ */
+
+/**
+ * Defines the criteria used to match an HTTP exchange.
+ *
+ * @typedef  {object}               ExchangeMatcherOptions
+ * @property {HTTPMethod|undefined} method                 - HTTP method to match. When undefined, any HTTP method is accepted.
+ * @property {string|undefined}     pathnamePattern        - URL pathname pattern to match. When undefined, any pathname is accepted.
+ */
+
+// ━━ MODULE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+/**
+ * Represents a request matching pattern.
+ *
+ * @classdesc ExchangeMatcher defines matching criteria composed of an
+ * optional HTTP method and a pathname pattern.
+ *
+ * When the pathnamePattern is `undefined`, the pattern is considered global
+ * and matches every pathname. If a method is specified, the method must still
+ * match.
+ */
+class ExchangeMatcher {
+  /**
+   * HTTP method used as a matching criterion.
+   *
+   * @type {HTTPMethod|undefined}
+   */
+  #method;
+
+  /**
+   * Native URLPattern instance used to evaluate the pathname criterion.
+   *
+   * @type {URLPattern}
+   */
+  #pattern;
+
+  /**
+   * Indicates whether the matcher accepts every pathname.
+   *
+   * @type {boolean}
+   */
+  #isGlobal;
+
+  /**
+   * Creates an instance of ExchangeMatcher.
+   *
+   * @param {ExchangeMatcherOptions} options - Matching criteria.
+   * @example
+   * ```js
+   * const matcher = new ExchangeMatcher({
+   *   method: 'GET',
+   *   pathnamePattern: '/users',
+   * });
+   * ```
+   * @example
+   * ```js
+   * const matcher = new ExchangeMatcher({
+   *   method: undefined,
+   *   pathnamePattern: undefined,
+   * });
+   * ```
+   */
+  constructor({ method, pathnamePattern }) {
+    this.#method = method;
+    this.#isGlobal = pathnamePattern === undefined;
+    this.#pattern = new URLPattern({ pathname: this.#isGlobal ? '*' : pathnamePattern });
+  }
+
+  /**
+   * Tests whether the specified exchange matches this pattern.
+   *
+   * Evaluates the HTTP request method and pathname from the provided Exchange object
+   * against the configured matching criteria to determine if this layer should handle it.
+   *
+   * @param {Exchange} exchange - The exchange object to evaluate.
+   * @returns {boolean} `true` when the exchange matches the configured criteria; otherwise, `false`.
+   * @example
+   * ```js
+   * const matcher = new ExchangeMatcher({
+   *   method: 'POST',
+   *   pathnamePattern: '/api/users',
+   * });
+   *
+   * matcher.test(exchange); // true if exchange is POST /api/users
+   * ```
+   */
+  test(exchange) {
+    const method = exchange.request.method;
+
+    if (this.#method && this.#method !== method.toUpperCase()) {
+      return false;
+    }
+
+    if (this.#isGlobal) {
+      return true;
+    }
+
+    const pathname = exchange.request.pathname;
+
+    return this.#pattern.test({ pathname });
+  }
+}
+
+// ━━ EXPORT MODULE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+export default ExchangeMatcher;

package/source/core/routing/ExchangeLayer/index.mjs

@@ -0,0 +1,254 @@
+// @ts-check
+/**
+ * @file Defines the HTTP exchange execution layer.
+ *
+ * @description Provides the ExchangeLayer class for matching exchanges against
+ * HTTP routing criteria and executing the associated middleware.
+ *
+ * @module ExchangeLayer
+ */
+
+// ━━ IMPORT MODULES ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// » IMPORT NATIVE NODEJS MODULES
+import { inspect } from 'node:util';
+
+// » IMPORT LOCAL MODULES
+import ExchangeMatcher from './ExchangeMatcher.mjs';
+
+// ━━ TYPE DEFINITIONS ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+/**
+ * Represents a single HTTP transaction.
+ *
+ * @typedef {import('#Exchange').default} Exchange
+ */
+
+/**
+ * Represents an HTTP method supported by the routing layer.
+ *
+ * @typedef {'GET'|'HEAD'|'POST'|'PUT'|'PATCH'|'DELETE'|'OPTIONS'|'QUERY'|'TRACE'} HTTPMethod
+ */
+
+/**
+ * Represents a function that delegates execution to the next
+ * middleware layer.
+ *
+ * @callback NextFunction
+ * @returns {void|Promise<void>}
+ */
+
+/**
+ * Represents an exchange middleware function.
+ *
+ * @callback MiddlewareFunction
+ * @param {Exchange} exchange - Current HTTP exchange.
+ * @param {NextFunction} next - The function to call the next layer.
+ * @returns {void|Promise<void>}
+ */
+
+/**
+ * Defines the criteria and middleware used by an exchange layer.
+ *
+ * @typedef  {object}               ExchangeLayerOptions
+ * @property {HTTPMethod|undefined} method               - HTTP method to match. When undefined, any HTTP method is accepted.
+ * @property {string|undefined}     pathnamePattern      - URL pathname pattern to match. When undefined, any pathname is accepted.
+ * @property {MiddlewareFunction}   middleware           - Middleware executed when the exchange matches the layer criteria.
+ */
+
+/**
+ * Represents the plain object representation of an exchange layer.
+ *
+ * @typedef  {object}               ExchangeLayerObject
+ * @property {HTTPMethod|undefined} method              - HTTP method used by the layer.
+ * @property {string|undefined}     pathnamePattern     - URL pathname pattern used by the layer.
+ * @property {MiddlewareFunction}   middleware          - Middleware executed by the layer.
+ */
+
+// ━━ MODULE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+/**
+ * Represents an executable layer for HTTP exchange processing.
+ *
+ * @classdesc Associates middleware with matching criteria based on an HTTP
+ * method and pathname pattern.
+ *
+ * The layer delegates matching to an ExchangeMatcher and execution to
+ * the middleware provided during construction.
+ */
+class ExchangeLayer {
+  /**
+   * The HTTP method used by the layer.
+   *
+   * @type {HTTPMethod|undefined}
+   */
+  #method;
+
+  /**
+   * The pathname pattern used by the layer.
+   *
+   * @type {string|undefined}
+   */
+  #pathnamePattern;
+
+  /**
+   * The matcher used to evaluate incoming exchanges.
+   *
+   * @type {ExchangeMatcher}
+   */
+  #matcher;
+
+  /**
+   * The middleware executed when the exchange matches the layer criteria.
+   *
+   * @type {MiddlewareFunction}
+   */
+  #middleware;
+
+  /**
+   * Creates an ExchangeLayer.
+   *
+   * @param {ExchangeLayerOptions} options - Configuration used to define the exchange layer.
+   * @example
+   * ```js
+   * const authLayer = new ExchangeLayer({
+   *   method: undefined,
+   *   pathnamePattern: '/api/v1/users',
+   *   middleware: authMiddleware,
+   * });
+   * ```
+   */
+  constructor({ method, pathnamePattern, middleware }) {
+    this.#matcher = new ExchangeMatcher({ method, pathnamePattern });
+    this.#method = method;
+    this.#pathnamePattern = pathnamePattern;
+    this.#middleware = middleware;
+  }
+
+  /**
+   * The HTTP method used by the layer.
+   *
+   * @type {HTTPMethod|undefined}
+   */
+  get method() {
+    return this.#method;
+  }
+
+  /**
+   * The pathname pattern used by the layer.
+   *
+   * @type {string|undefined}
+   */
+  get pathnamePattern() {
+    return this.#pathnamePattern;
+  }
+
+  /**
+   * Custom string tag for better type identification.
+   *
+   * @readonly
+   * @type {string}
+   * @example
+   * ```js
+   * const exchangeLayer = new ExchangeLayer({...});
+   *
+   * console.log(Object.prototype.toString.call(exchangeLayer));
+   * // '[object ExchangeLayer]'
+   * console.log(exchangeLayer[Symbol.toStringTag]);
+   * // 'ExchangeLayer'
+   * ```
+   */
+  get [Symbol.toStringTag]() {
+    return this.constructor.name;
+  }
+
+  /**
+   * Handles the exchange. If constraints match, executes the middleware.
+   * Otherwise, delegates to the next layer in the pipeline.
+   *
+   * @param {Exchange} exchange - The current exchange.
+   * @param {NextFunction} next - The function to call the next layer.
+   * @returns {Promise<void>} The result of calling the next layer or the completion of the middleware execution.
+   * @example
+   * ```js
+   * await layer.handle(exchange, next);
+   * ```
+   */
+  async handle(exchange, next) {
+    if (!this.#matcher.test(exchange)) {
+      return next();
+    }
+    await this.#middleware(exchange, next);
+  }
+
+  /**
+   * Converts the `ExchangeLayer` instance to a plain JavaScript object.
+   *
+   * @returns {ExchangeLayerObject} A plain object representation of the exchange layer.
+   * @example
+   * ```js
+   * const usersLayer = new ExchangeLayer({
+   *   method: 'GET',
+   *   pathnamePattern: '/api/users/:id',
+   *   middleware: usersRepository.find,
+   * });
+   *
+   * console.log(usersLayer.toObject());
+   * // {
+   * //   method: 'GET',
+   * //   pathnamePattern: '/api/users/:id',
+   * //   middleware: [AsyncFunction: middleware]
+   * // }
+   * ```
+   */
+  toObject() {
+    return Object.freeze({
+      method: this.method,
+      pathnamePattern: this.pathnamePattern,
+      middleware: this.#middleware,
+    });
+  }
+
+  /**
+   * Converts the `ExchangeLayer` instance to a plain JavaScript object.
+   *
+   * @returns {ExchangeLayerObject} A plain object representation of the exchange layer.
+   * @example
+   * ```js
+   * const usersLayer = new ExchangeLayer({
+   *   method: 'DELETE',
+   *   pathnamePattern: '/api/users/:id',
+   *   middleware: usersRepository.delete,
+   * });
+   *
+   * console.log(JSON.stringify(usersLayer));
+   * // '{"method":"DELETE","pathnamePattern":"/api/users/:id"}'
+   * ```
+   */
+  toJSON() {
+    return this.toObject();
+  }
+
+  /**
+   * Custom inspect implementation for Node.js `util.inspect()`.
+   *
+   * @returns {string} Custom string representation for debugging.
+   * @example
+   * ```js
+   * const authLayer = new ExchangeLayer({
+   *   method: undefined,
+   *   pathnamePattern: '/api/login',
+   *   middleware: authMiddleware,
+   * });
+   *
+   * console.log(authLayer);
+   * // ExchangeLayer {
+   * //   method: undefined,
+   * //   pathnamePattern: '/api/login',
+   * //   middleware: [AsyncFunction: middleware]
+   * // }
+   * ```
+   */
+  [inspect.custom]() {
+    return `${this.constructor.name} ${inspect(this.toObject(), { colors: true })}`;
+  }
+}
+// ━━ EXPORT MODULE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+export default ExchangeLayer;

package/source/core/routing/Pipeline/index.mjs

@@ -0,0 +1,157 @@
+// @ts-check
+/**
+ * @file Defines the Pipeline execution component for HTTP exchanges.
+ *
+ * @description Manages and executes an ordered chain of middleware layers.
+ * It acts as the core dispatch mechanism, handling control flow and safe
+ * delegation through `next()`. It is transport-agnostic.
+ *
+ * @module Pipeline
+ */
+
+// ━━ TYPE DEFINITIONS ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+/**
+ * Represents an executable layer for HTTP exchange processing.
+ *
+ * @typedef {import('#routing/ExchangeLayer').default} ExchangeLayer
+ */
+
+/**
+ * Represents an exchange middleware function.
+ *
+ * @typedef {import('#routing/ExchangeLayer').MiddlewareFunction} MiddlewareFunction
+ */
+
+/**
+ * Represents a single HTTP transaction.
+ *
+ * @typedef {import('#Exchange').default} Exchange
+ */
+
+/**
+ * Represents the fallback handler invoked when no layer resolves
+ * the exchange.
+ *
+ * @typedef {(exchange: Exchange) => void | Promise<void>} NotFoundHandler
+ */
+
+// ━━ MODULE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+/**
+ * Represents an ordered processing pipeline for HTTP exchanges.
+ *
+ * @classdesc Stores processing layers and executes their handlers in
+ * registration order. Each layer is responsible for determining whether
+ * it applies to the current exchange.
+ */
+class Pipeline {
+  /**
+   * Stores the middleware layer instances in execution order.
+   *
+   * @type {ExchangeLayer[]}
+   */
+  #layers = [];
+
+  /**
+   * Appends a single middleware layer to the end of the execution chain.
+   *
+   * @param {ExchangeLayer} layer - The middleware layer instance to add.
+   * @returns {Pipeline} The current pipeline instance for method chaining.
+   * @example
+   * ```js
+   * const layer = new ExchangeLayer({
+   *  method: undefined,
+   *  pathnamePattern: '/api/v1/users',
+   *  middleware: authMiddleware
+   * });
+   *
+   * pipeline.add(layer);
+   * ```
+   */
+  add(layer) {
+    this.#layers.push(layer);
+    return this;
+  }
+
+  /**
+   * Appends multiple middleware layers to the execution chain at once.
+   *
+   * This is particularly useful when mounting an entire router or a
+   * predefined set of middleware into the main server pipeline.
+   *
+   * @param {ExchangeLayer[]} layers - The middleware layer instances to add.
+   * @returns {Pipeline} The current pipeline instance for method chaining.
+   * @example
+   * ```js
+   * const routerLayers = [
+   *  new ExchangeLayer({
+   *    method: undefined,
+   *    pathnamePattern: '/api/v1/users',
+   *    middleware: authMiddleware
+   *  }),
+   *  new ExchangeLayer({
+   *    method: 'GET',
+   *    pathnamePattern: '/api/v1/users',
+   *    middleware: listUsers
+   *  }),
+   * ];
+   * pipeline.addBatch(routerLayers);
+   * ```
+   */
+  addBatch(layers) {
+    this.#layers.push(...layers);
+    return this;
+  }
+
+  /**
+   * Executes the middleware pipeline for a given exchange.
+   *
+   * Layers are processed sequentially in registration order. Each matching
+   * layer receives the exchange and a `next()` function that delegates
+   * execution to the following layer. If no layer resolves the exchange,
+   * the `notFoundHandler` is invoked.
+   *
+   * @param {Exchange} exchange - The current exchange.
+   * @param {NotFoundHandler} notFoundHandler - The fallback async function to execute, if no layer resolves the exchange.
+   * @returns {Promise<void>} Resolves when the processing chain completes.
+   * @throws {Error} If a middleware layer calls `next()` more than once.
+   * @example
+   * ```js
+   * await pipeline.execute(exchange, async exchange => {
+   *   exchange.response.status(404).json({ error: 'Not Found' });
+   * });
+   * ```
+   */
+  async execute(exchange, notFoundHandler) {
+    const called = new Set();
+
+    /**
+     * Dispatches middleware execution by index.
+     *
+     * @private
+     * @param {number} index - The current layer index in the pipeline.
+     * @returns {Promise<void>}
+     */
+    const dispatch = async index => {
+      if (index >= this.#layers.length) {
+        await notFoundHandler(exchange);
+      } else {
+        const layer = this.#layers[index];
+
+        const next = async () => {
+          if (called.has(index)) {
+            throw new Error(`next() called multiple times at pipeline index ${index}.`);
+          }
+          called.add(index);
+          await dispatch(index + 1);
+        };
+
+        await layer.handle(exchange, next);
+      }
+    };
+
+    await dispatch(0);
+  }
+}
+
+// ━━ EXPORT MODULE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+export default Pipeline;