@boo-labs/server 0.0.0-stage → 1.0.0

package/source/core/routing/RouterRegister/OptionsMiddleware.mjs

@@ -0,0 +1,147 @@
+// @ts-check
+/**
+ * @file Defines the middleware for handling automatic OPTIONS requests.
+ *
+ * @description Provides automatic OPTIONS responses for routes by exposing the
+ * HTTP methods registered for each pathname pattern.
+ *
+ * @module OptionsMiddleware
+ */
+
+// ━━ TYPE DEFINITIONS ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+/**
+ * Represents a single HTTP transaction.
+ *
+ * @typedef {import('#Exchange').default} Exchange
+ */
+
+/**
+ * Represents an HTTP method supported by the routing layer.
+ *
+ * @typedef {import('#routing/ExchangeLayer').HTTPMethod} HTTPMethod
+ */
+
+// ━━ MODULE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+/**
+ * Handles automatic OPTIONS responses for a route.
+ *
+ * @classdesc `OptionsMiddleware` generates an OPTIONS response containing the
+ * HTTP methods registered for a pathname pattern.
+ */
+class OptionsMiddleware {
+  /**
+   * The HTTP methods registered for the route.
+   *
+   * `undefined` represents all methods during registration and is removed when
+   * the methods are resolved.
+   *
+   * @type {Set<HTTPMethod|undefined>}
+   */
+  #methods = new Set();
+
+  /**
+   * The cached resolved HTTP methods string.
+   *
+   * @type {string|null}
+   */
+  #methodsCache = null;
+
+  /**
+   * Creates an instance of OptionsMiddleware.
+   *
+   * @example
+   * ```js
+   * const middleware = new OptionsMiddleware();
+   * ```
+   */
+  constructor() {
+    this.handle = this.handle.bind(this);
+  }
+
+  /**
+   * The resolved HTTP methods string.
+   *
+   * @type {string}
+   */
+  get methods() {
+    if (this.#methodsCache !== null) {
+      return this.#methodsCache;
+    }
+
+    const methods = new Set(this.#methods);
+    methods.delete(undefined);
+
+    if (methods.size === 0) {
+      this.#methodsCache = OptionsMiddleware.#METHODS.join(', ');
+    } else {
+      methods.add('OPTIONS');
+      this.#methodsCache = [...methods].join(', ');
+    }
+
+    return this.#methodsCache;
+  }
+
+  /**
+   * Adds an HTTP method to the allowed methods.
+   *
+   * `undefined` represents all methods during registration.
+   *
+   * @param {HTTPMethod|undefined} method - The HTTP method to allow.
+   * @example
+   * ```js
+   * middleware.add('GET');
+   * middleware.add('POST');
+   * ```
+   */
+  add(method) {
+    this.#methods.add(method);
+    this.#methodsCache = null;
+  }
+
+  /**
+   * Handles an OPTIONS request and terminates the exchange.
+   *
+   * @param {Exchange} exchange - The current exchange.
+   * @param {Function} _next - The unused continuation function.
+   * @example
+   * ```js
+   * const middleware = new OptionsMiddleware();
+   * middleware.add('GET');
+   * middleware.add('POST');
+   * middleware.handle(exchange, next);
+   *
+   * // Response:
+   * // 204 No Content
+   * // Allow: GET, POST
+   * // Access-Control-Allow-Methods: GET, POST
+   * ```
+   */
+  handle(exchange, _next) {
+    exchange.response
+      .status(204)
+      .setHeader('Allow', this.methods)
+      .setHeader('Access-Control-Allow-Methods', this.methods)
+      .setHeader('Access-Control-Allow-Headers', 'Content-Type, Authorization')
+      .end();
+  }
+
+  /**
+   * The HTTP methods supported by the server.
+   *
+   * @type {Readonly<Array<HTTPMethod>>}
+   */
+  static #METHODS = Object.freeze([
+    'GET',
+    'HEAD',
+    'POST',
+    'PUT',
+    'PATCH',
+    'DELETE',
+    'OPTIONS',
+    'QUERY',
+    'TRACE',
+  ]);
+}
+
+// ━━ EXPORT MODULE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+export default OptionsMiddleware;

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

@@ -0,0 +1,150 @@
+// @ts-check
+/**
+ * @file Defines the route register.
+ *
+ * @description Maintains route registrations and builds automatic OPTIONS
+ * middleware for each pathname pattern.
+ *
+ * @module RouteRegister
+ */
+
+// ━━ IMPORT MODULES ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// » IMPORT LOCAL MODULES
+import OptionsMiddleware from './OptionsMiddleware.mjs';
+
+// ━━ TYPE DEFINITIONS ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+/**
+ * Represents a single HTTP transaction.
+ *
+ * @typedef {import('#Exchange').default} Exchange
+ */
+
+/**
+ * Represents an HTTP method supported by the routing layer.
+ *
+ * @typedef {import('#routing/ExchangeLayer').HTTPMethod} HTTPMethod
+ */
+
+/**
+ * Represents an exchange middleware function.
+ *
+ * @typedef {import('#routing/ExchangeLayer').MiddlewareFunction} MiddlewareFunction
+ */
+
+/**
+ * Route registration containing an optional HTTP method and pathname pattern.
+ *
+ * @typedef {[HTTPMethod|undefined, string|undefined]} RouteRegistration
+ */
+
+/**
+ * Collection of route registrations.
+ *
+ * @typedef {RouteRegistration[]} RouteRegistrations
+ */
+
+/**
+ * Represents the options used to create an exchange layer.
+ *
+ * @typedef  {object}             ExchangeLayerOptions
+ * @property {'OPTIONS'}          method               - HTTP method to match for the automatic OPTIONS layer.
+ * @property {string}             pathnamePattern      - URL pathname pattern to match.
+ * @property {MiddlewareFunction} middleware           - Middleware executed when the exchange matches the layer criteria.
+ */
+
+// ━━ MODULE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+/**
+ * Maintains registered routes and their automatic OPTIONS middleware.
+ *
+ * @classdesc `RouteRegister` groups registered HTTP methods by pathname pattern
+ * and creates an OPTIONS route for each new pathname pattern.
+ */
+class RouteRegister {
+  /**
+   * OPTIONS middleware keyed by pathname pattern.
+   *
+   * @type {Map<string, OptionsMiddleware>}
+   */
+  #middlewares = new Map();
+
+  /**
+   * Registers a route by its HTTP method and pathname pattern.
+   *
+   * On the first registration of a pathname pattern, creates an
+   * `OptionsMiddleware` and returns the OPTIONS layer options. On later
+   * registrations of the same pattern, only adds the method to the existing
+   * middleware and returns `undefined`.
+   *
+   * @param {RouteRegistration} registration - The route registration to add.
+   * @returns {ExchangeLayerOptions|undefined} The OPTIONS layer options when the pathname pattern is new; otherwise `undefined`.
+   * @example
+   * ```js
+   * register(['GET', '/users']);
+   * // → { method: 'OPTIONS', pathnamePattern: '/users', middleware: handle }
+   *
+   * register(['POST', '/users']);
+   * // → undefined (methods updated)
+   * ```
+   */
+  register([method, pathnamePattern]) {
+    if (pathnamePattern === undefined) {
+      return undefined;
+    }
+
+    const optionsMiddleware = this.#middlewares.get(pathnamePattern);
+
+    if (optionsMiddleware !== undefined) {
+      optionsMiddleware.add(method);
+      return undefined;
+    }
+
+    const middleware = new OptionsMiddleware();
+    middleware.add(method);
+    this.#middlewares.set(pathnamePattern, middleware);
+    return {
+      method: 'OPTIONS',
+      pathnamePattern,
+      middleware: middleware.handle,
+    };
+  }
+
+  /**
+   * Registers multiple routes.
+   *
+   * Only the first registration of each pathname pattern contributes an OPTIONS
+   * layer. Later registrations for the same pattern update the existing
+   * middleware and are omitted from the result.
+   *
+   * @param {RouteRegistrations} registrations - The route registrations to add.
+   * @returns {ExchangeLayerOptions[]} The new OPTIONS layer options.
+   * @example
+   * ```js
+   * registerBatch([
+   *   ['GET', '/users'],
+   *   ['POST', '/users'],
+   *   ['GET', '/posts'],
+   * ]);
+   * // → [
+   * //   { method: 'OPTIONS', pathnamePattern: '/users', middleware: handle },
+   * //   { method: 'OPTIONS', pathnamePattern: '/posts', middleware: handle },
+   * // ]
+   * ```
+   */
+  registerBatch(registrations) {
+    /** @type {ExchangeLayerOptions[]} */
+    const options = [];
+
+    for (const registration of registrations) {
+      const layerOptions = this.register(registration);
+
+      if (layerOptions !== undefined) {
+        options.push(layerOptions);
+      }
+    }
+
+    return options;
+  }
+}
+
+// ━━ EXPORT MODULE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+export default RouteRegister;

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

@@ -0,0 +1,225 @@
+// @ts-check
+/**
+ * @file Provides the routing system for route registration and execution.
+ *
+ * @module RouterSystem
+ */
+
+// ━━ IMPORT MODULES ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// » IMPORT LOCAL MODULES
+import Pipeline from '#routing/Pipeline';
+import RouteRegister from '#routing/RouterRegister';
+import ExchangeLayer from '#routing/ExchangeLayer';
+
+// ━━ TYPE DEFINITIONS ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+/**
+ * Represents a single HTTP transaction.
+ *
+ * @typedef {import('#Exchange').default} Exchange
+ */
+
+/**
+ * Defines HTTP middleware pipelines by pathname pattern and method.
+ *
+ * @typedef {import('#routing/Router').default} Router
+ */
+
+/**
+ * Represents an exchange middleware function.
+ *
+ * @typedef {import('#routing/ExchangeLayer').MiddlewareFunction} MiddlewareFunction
+ */
+
+/**
+ * Represents the fallback handler invoked when no layer resolves the exchange.
+ *
+ * @typedef {import('#routing/Pipeline').NotFoundHandler} NotFoundHandler
+ */
+
+/**
+ * Collection of route registrations.
+ *
+ * @typedef {import('#routing/RouterRegister').RouteRegistrations} RouteRegistrations
+ */
+
+/**
+ * Defines the criteria and middleware used by an exchange layer.
+ *
+ * @typedef {import('#routing/ExchangeLayer').ExchangeLayerOptions} ExchangeLayerOptions
+ */
+
+/**
+ * Represents an HTTP method supported by the routing layer.
+ *
+ * @typedef {import('#routing/ExchangeLayer').HTTPMethod} HTTPMethod
+ */
+
+/**
+ * Collection of layer options.
+ *
+ * @typedef {ExchangeLayerOptions[]} ExchangeLayersOptions
+ */
+
+// ━━ MODULE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+/**
+ * Coordinates route registration and layer execution.
+ *
+ * @classdesc `RouterSystem` maintains the routing pipeline and translates
+ * route registrations and layer options into executable exchange layers.
+ */
+class RouterSystem {
+  /**
+   * Pipeline containing the executable exchange layers.
+   *
+   * @type {Pipeline}
+   */
+  #pipeline = new Pipeline();
+
+  /**
+   * Route register used to maintain registered routes and compose automatic
+   * OPTIONS layer options.
+   *
+   * @type {RouteRegister}
+   */
+
+  #routes = new RouteRegister();
+  /**
+   * Registers multiple exchange layers from layer options.
+   *
+   * @param {ExchangeLayersOptions} layersOptions - The layer options used to create
+   * executable exchange layers.
+   * @example
+   * ```js
+   * routerSystem.registerLayerOptionsBatch([
+   *   { method: undefined, pathnamePattern: '/api', middleware: middleware },
+   * ]);
+   * ```
+   */
+  registerLayerOptionsBatch(layersOptions) {
+    this.#registerLayerBatch(layersOptions);
+  }
+
+  /**
+   * Registers a route entry by transforming method, pathname pattern, and middlewares
+   * into executable exchange layers and route registrations.
+   *
+   * @param {HTTPMethod|undefined} method - The HTTP method to match.
+   * @param {string|undefined} pathnamePattern - The URL pathname pattern to match.
+   * @param {MiddlewareFunction[]} middlewares - The middleware functions to execute.
+   * @example
+   * ```js
+   * routerSystem.registerRouteEntry('GET', '/users', [authenticate, getUsers]);
+   * ```
+   */
+  registerRouteEntry(method, pathnamePattern, middlewares) {
+    const layersOptions = middlewares.map(middleware => ({
+      method,
+      pathnamePattern,
+      middleware,
+    }));
+
+    /** @type {RouteRegistrations} */
+    const routes = layersOptions.map(layerOptions => [
+      layerOptions.method,
+      layerOptions.pathnamePattern,
+    ]);
+
+    this.#registerRouteBatch(routes);
+    this.#registerLayerBatch(layersOptions);
+  }
+
+  /**
+   * Registers a mounted router by prefixing its routes and middlewares with a base pathname pattern.
+   *
+   * @param {string} basePathnamePattern - The base URL pathname pattern to prefix.
+   * @param {Router} router - The router instance to mount (must implement a `compose()` method).
+   * @example
+   * ```js
+   * const userRouter = new Router();
+   * userRouter.get('/', getUsers);
+   * routerSystem.registerMountEntry('/api/users', userRouter);
+   * ```
+   */
+  registerMountEntry(basePathnamePattern, router) {
+    const { middlewares, layersOptions } = router.compose();
+
+    const options = [
+      ...middlewares.map(middleware => ({
+        method: undefined,
+        pathnamePattern: basePathnamePattern,
+        middleware,
+      })),
+      ...layersOptions.map(({ method, pathnamePattern, middleware }) => ({
+        method,
+        pathnamePattern: `${basePathnamePattern}${pathnamePattern}`,
+        middleware,
+      })),
+    ];
+
+    /** @type {RouteRegistrations} */
+    const routes = options.map(({ method, pathnamePattern }) => [method, pathnamePattern]);
+
+    this.#registerRouteBatch(routes);
+    this.#registerLayerBatch(options);
+  }
+
+  /**
+   * Executes the routing pipeline for an exchange.
+   *
+   * @param {Exchange} exchange - The exchange to process.
+   * @param {NotFoundHandler} notFoundHandler - The fallback async function to execute if no layer resolves the exchange.
+   * @returns {Promise<void>} A promise fulfilled when routing execution completes.
+   * @example
+   * ```js
+   * await routerSystem.executePipeline(exchange, async (exc) => {
+   *   exc.response.status(404).json({ error: 'Not Found' });
+   * });
+   * ```
+   */
+  executePipeline(exchange, notFoundHandler) {
+    return this.#pipeline.execute(exchange, notFoundHandler);
+  }
+
+  /**
+   * Registers multiple routes and adds their automatic OPTIONS layers to
+   * the routing pipeline.
+   *
+   * @param {RouteRegistrations} routes - The route registrations to add.
+   * @example
+   * ```js
+   * routerSystem.registerRouteBatch([
+   *   ['GET', '/users'],
+   *   ['POST', '/users'],
+   * ]);
+   * ```
+   */
+  #registerRouteBatch(routes) {
+    const layersOptions = this.#routes.registerBatch(routes);
+
+    const layers = layersOptions.map(layerOptions => new ExchangeLayer(layerOptions));
+
+    this.#pipeline.addBatch(layers);
+  }
+
+  /**
+   * Registers multiple `ExchangeLayer` instances created from the provided layer
+   * options and adds them to the routing pipeline.
+   *
+   * @param {ExchangeLayersOptions} layersOptions - The layer options used to create the `ExchangeLayer` instances.
+   * @example
+   * ```js
+   * routerSystem.registerLayerBatch([
+   *   { method: 'GET', pathnamePattern: '/users', middleware: getUsers },
+   *   { method: 'POST', pathnamePattern: '/users', middleware: createUser },
+   * ]);
+   * ```
+   */
+  #registerLayerBatch(layersOptions) {
+    const layers = layersOptions.map(layerOptions => new ExchangeLayer(layerOptions));
+
+    this.#pipeline.addBatch(layers);
+  }
+}
+
+// ━━ EXPORT MODULE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+export default RouterSystem;