@boo-labs/server 0.0.0-stage → 1.0.0

package/source/core/value-objects/Address/index.mjs

@@ -0,0 +1,281 @@
+// @ts-check
+/**
+ * @file Defines the Address value object.
+ *
+ * @module Address
+ */
+
+// ━━ IMPORT MODULES ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// » IMPORT NATIVE NODEJS MODULES
+import { inspect } from 'node:util';
+
+// ━━ TYPE DEFINITIONS ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+/**
+ * Options accepted by the Address constructor.
+ *
+ * @typedef  {object} AddressOptions
+ * @property {string} address        - The network address where the server is listening.
+ * @property {number} port           - The TCP port where the server is listening.
+ * @property {string} family         - The IP address family.
+ */
+
+/**
+ * Plain object representation of an Address.
+ *
+ * @typedef  {object} AddressInfo
+ * @property {string} address     - The network address where the server is listening.
+ * @property {number} port        - The TCP port where the server is listening.
+ * @property {string} family      - The IP address family reported by Node.js.
+ * @property {string} displayHost - The hostname used when displaying the address.
+ */
+
+// ━━ MODULE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+/**
+ * Represents the network address of an HTTP server.
+ *
+ * @classdesc Immutable value object that encapsulates the network address,
+ * port and IP address family of an HTTP server.
+ *
+ * It provides multiple representations of the same address,
+ * including plain objects, JSON serialization and canonical string formatting.
+ *
+ * IPv6 addresses are automatically enclosed in square brackets when
+ * converted to their string representation.
+ */
+class Address {
+  /**
+   * The server network address.
+   *
+   * @type {string}
+   */
+  #address;
+
+  /**
+   * The TCP port where the server is listening.
+   *
+   * @type {number}
+   */
+  #port;
+
+  /**
+   * The IP address family.
+   *
+   * @type {string}
+   */
+  #family;
+
+  /**
+   * Creates a new Address instance.
+   *
+   * @param {AddressOptions} options - The server network address.
+   * @example
+   * ```js
+   * const address = new Address({
+   *   address: '127.0.0.1',
+   *   port: 3000,
+   *   family: 'IPv4'
+   * });
+   *
+   * console.log(address.toString()); // '127.0.0.1:3000'
+   * ```
+   */
+  constructor({ address, port, family }) {
+    this.#address = address;
+    this.#port = port;
+    this.#family = family;
+  }
+
+  /**
+   * The network address where the server is listening.
+   *
+   * @readonly
+   * @type {string}
+   */
+  get address() {
+    return this.#address;
+  }
+
+  /**
+   * The TCP port where the server is listening.
+   *
+   * @readonly
+   * @type {number}
+   */
+  get port() {
+    return this.#port;
+  }
+
+  /**
+   * The IP address family.
+   *
+   * @readonly
+   * @type {string}
+   */
+  get family() {
+    return this.#family;
+  }
+
+  /**
+   * The hostname used when displaying the network address.
+   *
+   * IPv4 and IPv6 loopback addresses.
+   *
+   * @readonly
+   * @type {string}
+   */
+  get displayHost() {
+    if (this.#address === '127.0.0.1' || this.#address === '::1') {
+      return 'localhost';
+    }
+
+    return this.#address;
+  }
+
+  /**
+   * Custom string tag for better type identification.
+   *
+   * @readonly
+   * @type {string}
+   * @example
+   * ```js
+   * const address = new Address({...});
+   * console.log(Object.prototype.toString.call(address)); // '[object Address]'
+   * console.log(address[Symbol.toStringTag]); // 'Address'
+   * ```
+   */
+  get [Symbol.toStringTag]() {
+    return this.constructor.name;
+  }
+
+  /**
+   * Returns the address as a plain JavaScript object.
+   *
+   * The returned object includes the real network data and a display-friendly
+   * host derived from loopback normalization.
+   *
+   * @returns {AddressInfo} A plain object representation of this address.
+   * @example
+   * ```js
+   * console.log(address.toObject());
+   * // {
+   * //   address: '::1',
+   * //   port: 3000,
+   * //   family: 'IPv6',
+   * //   displayHost: 'localhost'
+   * // }
+   * ```
+   */
+  toObject() {
+    return {
+      address: this.#address,
+      port: this.#port,
+      family: this.#family,
+      displayHost: this.displayHost,
+    };
+  }
+
+  /**
+   * Returns a JSON-serializable representation of this address.
+   *
+   * This method is automatically used by JSON.stringify().
+   *
+   * @returns {AddressInfo} A JSON representation of this address.
+   * @example
+   * ```js
+   * const json = JSON.stringify(address);
+   *
+   * console.log(json); // {"address":"::1","port":3000,"family":"IPv6","displayHost":"localhost"}
+   * ```
+   */
+  toJSON() {
+    return this.toObject();
+  }
+
+  /**
+   * Returns the canonical string representation of this address.
+   *
+   * IPv4 addresses are represented as `host:port`.
+   * IPv6 addresses are represented as `[host]:port`.
+   *
+   * @returns {string} The canonical network address.
+   * @example
+   * ```js
+   * const ipv4 = new Address({
+   *   address: '127.0.0.1',
+   *   port: 3000,
+   *   family: 'IPv4'
+   * });
+   *
+   * console.log(ipv4.toString()); // '127.0.0.1:3000'
+   * ```
+   *
+   * @example
+   * ```js
+   * const ipv6 = new Address({
+   *   address: '2001:db8::1',
+   *   port: 3000,
+   *   family: 'IPv6'
+   * });
+   *
+   * console.log(ipv6.toString()); // '[2001:db8::1]:3000'
+   * ```
+   */
+  toString() {
+    const host = this.#family === 'IPv6' ? `[${this.#address}]` : this.#address;
+
+    return `${host}:${this.#port}`;
+  }
+
+  /**
+   * Custom inspect implementation for Node.js `util.inspect()`.
+   *
+   * @returns {string} Custom string representation for debugging.
+   * @example
+   * ```js
+   * const address = new Address({...});
+   *
+   * console.log(address);
+   * // Address {
+   * //   address: '::1',
+   * //   port: 5173,
+   * //   family: 'IPv6',
+   * //   displayHost: 'localhost'
+   * // }
+   * ```
+   */
+  [inspect.custom]() {
+    return `${this.constructor.name} ${inspect(this.toObject(), { colors: true })}`;
+  }
+
+  /**
+   * Converts this address to a primitive value.
+   *
+   * String and default conversions return the canonical address string.
+   * Numeric conversion is not supported.
+   *
+   * @param {'string'|'number'|'default'} hint - The preferred primitive type.
+   * @returns {string} The canonical address string.
+   * @throws {TypeError} Thrown when a numeric conversion is attempted.
+   * @example
+   * ```js
+   * const address = new Address({
+   *   address: '127.0.0.1',
+   *   port: 3000,
+   *   family: 'IPv4'
+   * });
+   *
+   * console.log(`Server Address: ${address}`); // '127.0.0.1:3000'
+   * console.log(String(address)); // '127.0.0.1:3000'
+   * ```
+   */
+  [Symbol.toPrimitive](hint) {
+    if (hint === 'number') {
+      throw new TypeError(`${this.constructor.name} cannot be converted to number.`);
+    }
+    return this.toString();
+  }
+}
+
+// ━━ EXPORT MODULE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+export default Address;

package/source/core/value-objects/Endpoint/index.mjs

@@ -0,0 +1,293 @@
+// @ts-check
+/**
+ * @file Defines the Endpoint value object.
+ *
+ * @module Endpoint
+ */
+
+// ━━ IMPORT MODULES ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// » IMPORT NATIVE NODEJS MODULES
+import { inspect } from 'node:util';
+
+// ━━ TYPE DEFINITIONS ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+/**
+ * Represents the network address of an HTTP server.
+ *
+ * @typedef {import('#value-objects/Address').default} Address
+ */
+
+/**
+ * Identifies an application-layer communication protocol.
+ *
+ * @typedef { 'http'|'https'|'ws'|'wss'|'grpc'|'mqtt'|'coap' } Protocol
+ */
+
+/**
+ * Represents network endpoint configuration options.
+ *
+ * @typedef  {object}   EndpointOptions
+ * @property {Protocol} protocol        - The communication protocol.
+ * @property {Address}  address         - The server network address.
+ */
+
+/**
+ * Represents the data of a network endpoint.
+ *
+ * @typedef  {object}   EndpointData
+ * @property {Protocol} protocol     - The communication protocol.
+ * @property {string}   address      - The network address where the server is listening.
+ * @property {number}   port         - The TCP port where the server is listening.
+ * @property {string}   family       - The IP address family.
+ * @property {string}   displayHost  - The hostname used when displaying the address.
+ * @property {string}   displayUrl   - The URL used when displaying the endpoint.
+ */
+
+// ━━ MODULE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+/**
+ * Represents a complete network endpoint.
+ *
+ * @classdesc Immutable value object that combines a communication protocol
+ * with a network address.
+ *
+ * It provides multiple representations of the same endpoint,
+ * including plain objects, JSON serialization and URL formatting.
+ */
+class Endpoint {
+  /**
+   * The communication protocol of the endpoint.
+   *
+   * @type {Protocol}
+   */
+  #protocol;
+
+  /**
+   * The server network address.
+   *
+   * @type {Address}
+   */
+  #address;
+
+  /**
+   * Creates a new Endpoint instance.
+   *
+   * @param {EndpointOptions} options - The network endpoint configuration.
+   * @example
+   * ```js
+   * const address = new Address({
+   *   address: '127.0.0.1',
+   *   port: 3000,
+   *   family: 'IPv4',
+   * });
+   *
+   * const endpoint = new Endpoint({
+   *   protocol: 'http',
+   *   address,
+   * });
+   * ```
+   */
+  constructor({ protocol, address }) {
+    this.#protocol = protocol;
+    this.#address = address;
+  }
+
+  /**
+   * The communication protocol.
+   *
+   * @readonly
+   * @type {Protocol}
+   */
+  get protocol() {
+    return this.#protocol;
+  }
+
+  /**
+   * The network address where the server is listening.
+   *
+   * @readonly
+   * @type {string}
+   */
+  get address() {
+    return this.#address.address;
+  }
+
+  /**
+   * The TCP port where the server is listening.
+   *
+   * @readonly
+   * @type {number}
+   */
+  get port() {
+    return this.#address.port;
+  }
+
+  /**
+   * The IP address family.
+   *
+   * @readonly
+   * @type {string}
+   */
+  get family() {
+    return this.#address.family;
+  }
+
+  /**
+   * The hostname used when displaying the network address.
+   *
+   * IPv4 and IPv6 loopback addresses.
+   *
+   * @readonly
+   * @type {string}
+   */
+  get displayHost() {
+    return this.#address.displayHost;
+  }
+
+  /**
+   * The URL used when displaying the endpoint.
+   *
+   * Loopback addresses are rendered as `localhost`.
+   *
+   * @readonly
+   * @type {string}
+   * @example
+   * ```js
+   * console.log(endpoint.displayUrl); // 'http://localhost:3000'
+   * ```
+   */
+  get displayUrl() {
+    const { displayHost, family, port } = this.#address;
+    const host =
+      family === 'IPv6' && displayHost !== 'localhost' ? `[${displayHost}]` : displayHost;
+
+    return `${this.#protocol}://${host}:${port}`;
+  }
+
+  /**
+   * Custom string tag for better type identification.
+   *
+   * @readonly
+   * @type {string}
+   * @example
+   * ```js
+   * const endpoint = new Endpoint({...});
+   * console.log(Object.prototype.toString.call(endpoint)); // '[object Endpoint]'
+   * console.log(endpoint[Symbol.toStringTag]); // 'Endpoint'
+   * ```
+   */
+  get [Symbol.toStringTag]() {
+    return this.constructor.name;
+  }
+
+  /**
+   * Returns the endpoint as a plain JavaScript object.
+   *
+   * @returns {EndpointData} A plain object representation of this endpoint.
+   * @example
+   * ```js
+   * console.log(endpoint.toObject());
+   * // {
+   * //   protocol: 'http',
+   * //   address: '::1',
+   * //   port: 3000,
+   * //   family: 'IPv6',
+   * //   displayHost: 'localhost',
+   * //   displayUrl: 'http://localhost:3000',
+   * // }
+   * ```
+   */
+  toObject() {
+    return {
+      protocol: this.#protocol,
+      ...this.#address.toObject(),
+      displayUrl: this.displayUrl,
+    };
+  }
+
+  /**
+   * Returns a JSON-serializable representation of this endpoint.
+   *
+   * This method is automatically used by JSON.stringify().
+   *
+   * @returns {EndpointData}  A JSON representation of this endpoint.
+   * @example
+   * ```js
+   * const json = JSON.stringify(address);
+   *
+   * console.log(json); // {"protocol":"http","address":"::1","port":3000,"family":"IPv6","displayHost":"localhost","displayUrl":"http://localhost:3000"}
+   * ```
+   */
+  toJSON() {
+    return this.toObject();
+  }
+
+  /**
+   * Returns the canonical URL representation of this endpoint.
+   *
+   * The URL consists of the endpoint protocol followed by the canonical
+   * string representation of its server address.
+   *
+   * @returns {string} The canonical endpoint URL.
+   * @example
+   * ```js
+   * const address = new Address({
+   *   address: '127.0.0.1',
+   *   port: 3000,
+   *   family: 'IPv4',
+   * });
+   *
+   * const endpoint = new Endpoint({
+   *   protocol: 'http',
+   *   address,
+   * });
+   *
+   * console.log(endpoint.toString()); // 'http://127.0.0.1:3000'
+   * ```
+   */
+  toString() {
+    return `${this.#protocol}://${this.#address}`;
+  }
+
+  /**
+   * Custom inspect implementation for Node.js `util.inspect()`.
+   *
+   * @returns {string} Custom string representation for debugging.
+   * @example
+   * ```js
+   * console.log(endpoint);
+   * // Endpoint {
+   * //   protocol: 'http',
+   * //   address: '::1',
+   * //   port: 5173,
+   * //   family: 'IPv6',
+   * //   displayHost: 'localhost',
+   * //   displayUrl: 'http://localhost:5173'
+   * // }
+   * ```
+   */
+  [inspect.custom]() {
+    return `${this.constructor.name} ${inspect(this.toObject(), { colors: true })}`;
+  }
+
+  /**
+   * Converts this endpoint to a primitive value.
+   *
+   * Numeric conversion is not supported.
+   *
+   * @param {'string'|'number'|'default'} hint - The preferred primitive type.
+   * @returns {string} The canonical endpoint URL.
+   * @throws {TypeError} Thrown when a numeric conversion is attempted.
+   * @example
+   * ```js
+   * console.log(`${endpoint}`); // 'http://127.0.0.1:3000'
+   * ```
+   */
+  [Symbol.toPrimitive](hint) {
+    if (hint === 'number') {
+      throw new TypeError(`${this.constructor.name} cannot be converted to number.`);
+    }
+    return this.toString();
+  }
+}
+
+// ━━ EXPORT MODULE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+export default Endpoint;

package/source/index.mjs

@@ -0,0 +1,62 @@
+// @ts-check
+/**
+ * @file Public API for the `@boo/server` package.
+ *
+ * @description Exposes the public classes for configuring, routing, and
+ * running zero-dependency HTTP servers in Node.js, following Clean
+ * Architecture principles.
+ *
+ * Exports:
+ *
+ * - Server (default): The main HTTP server class.
+ * - Router: Provides route registration and composition.
+ * - HttpServerConfiguration: Configuration for standard HTTP/1.1 servers.
+ * - HttpsServerConfiguration: Configuration for secure HTTPS servers.
+ * - Http2CleartextServerConfiguration: Configuration for cleartext HTTP/2 (h2c) servers.
+ * - Http2SecureServerConfiguration: Configuration for secure HTTP/2 (h2) servers.
+ *
+ * @module BooServerAPI
+ */
+
+// ━━ IMPORT MODULES ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// » IMPORT LOCAL MODULES
+import Server from '#Server';
+import Router from '#routing/Router';
+import HttpServerConfiguration from '#configurations/HttpServerConfiguration';
+import HttpsServerConfiguration from '#configurations/HttpsServerConfiguration';
+import Http2CleartextServerConfiguration from '#configurations/Http2CleartextServerConfiguration';
+import Http2SecureServerConfiguration from '#configurations/Http2SecureServerConfiguration';
+
+// ━━ TYPE DEFINITIONS ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+/**
+ * Public API namespace for the `@boo/server` package.
+ *
+ * Describes the classes exposed by the package's public entry point.
+ *
+ * @typedef  {object}                                   BooServerAPI
+ * @property {typeof Server}                            default                           - Main HTTP server class.
+ * @property {typeof Router}                            Router                            - Route registration and composition.
+ * @property {typeof HttpServerConfiguration}           HttpServerConfiguration           - HTTP/1.1 server configuration.
+ * @property {typeof HttpsServerConfiguration}          HttpsServerConfiguration          - HTTPS server configuration.
+ * @property {typeof Http2CleartextServerConfiguration} Http2CleartextServerConfiguration - Cleartext HTTP/2 (h2c) server configuration.
+ * @property {typeof Http2SecureServerConfiguration}    Http2SecureServerConfiguration    - Secure HTTP/2 (h2) server configuration.
+ */
+
+// ━━ EXPORT MODULE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+/**
+ * Default export: The primary class used to create and run an HTTP server.
+ *
+ * @type {typeof Server}
+ */
+export default Server;
+
+/**
+ * Named exports: The router and the supported server configuration classes.
+ */
+export {
+  Router,
+  HttpServerConfiguration,
+  HttpsServerConfiguration,
+  Http2CleartextServerConfiguration,
+  Http2SecureServerConfiguration,
+};