@muspellheim/shared 0.4.0

package/lib/node/configuration-properties.js

@@ -0,0 +1,254 @@
+// Copyright (c) 2023-2024 Falko Schumann. All rights reserved. MIT license.
+
+import fsPromises from 'node:fs/promises';
+import path from 'node:path';
+import process from 'node:process';
+
+import { deepMerge } from '../util.js';
+
+// TODO How to handle optional values? Cast to which type?
+// TODO Use JSON schema to validate the configuration?
+
+/**
+ * Provide the configuration of an application.
+ *
+ * The configuration is read from a JSON file `application.json` from the
+ * working directory.
+ *
+ * Example:
+ *
+ * ```javascript
+ * const configuration = ConfigurationProperties.create();
+ * const config = await configuration.get();
+ * ```
+ *
+ * With default values:
+ *
+ * ```javascript
+ * const configuration = ConfigurationProperties.create({
+ *   defaults: {
+ *       port: 8080,
+ *       database: { host: 'localhost', port: 5432 },
+ *   },
+ * });
+ * const config = await configuration.get();
+ * ```
+ */
+export class ConfigurationProperties {
+  /**
+   * Creates an instance of the application configuration.
+   *
+   * @param {object} options The configuration options.
+   * @param {object} [options.defaults={}] The default configuration.
+   * @param {string} [options.prefix=""] The prefix of the properties to get.
+   * @param {string} [options.name='application.json'] The name of the
+   *   configuration file.
+   * @param {string[]} [options.location=['.', 'config']] The locations where to
+   *   search for the configuration file.
+   * @return {ConfigurationProperties} The new instance.
+   */
+  static create({
+    defaults = {},
+    prefix = '',
+    name = 'application.json',
+    location = ['.', 'config'],
+  } = {}) {
+    return new ConfigurationProperties(
+      defaults,
+      prefix,
+      name,
+      location,
+      fsPromises,
+    );
+  }
+
+  /**
+   * Creates a nullable of the application configuration.
+   *
+   * @param {object} options The configuration options.
+   * @param {object} [options.defaults={}] The default configuration.
+   * @param {string} [options.prefix=""] The prefix of the properties to get.
+   * @param {string} [options.name='application.json'] The name of the
+   *   configuration file.
+   * @param {string[]} [options.location=['.', 'config']] The locations where to
+   *   search for the configuration file.
+   * @param {object} [options.files={}] The files and file content that are
+   *   available.
+   */
+  static createNull({
+    defaults = {},
+    prefix = '',
+    name = 'application.json',
+    location = ['.', 'config'],
+    files = {},
+  } = {}) {
+    return new ConfigurationProperties(
+      defaults,
+      prefix,
+      name,
+      location,
+      new FsStub(files),
+    );
+  }
+
+  #defaults;
+  #prefix;
+  #name;
+  #locations;
+  #fs;
+
+  /**
+   * The constructor is for internal use. Use the factory methods instead.
+   *
+   * @see ConfigurationProperties.create
+   * @see ConfigurationProperties.createNull
+   */
+  constructor(
+    /** @type {object} */ defaults,
+    /** @type {string} */ prefix,
+    /** @type {string} */ name,
+    /** @type {string[]} */ locations,
+    /** @type {fsPromises} */ fs,
+  ) {
+    this.#defaults = defaults;
+    this.#prefix = prefix;
+    this.#name = name;
+    this.#locations = locations;
+    this.#fs = fs;
+  }
+
+  /**
+   * Loads the configuration from the file.
+   *
+   * @return {Promise<object>} The configuration object.
+   */
+  async get() {
+    let config = await this.#loadFile();
+    // FIXME copy defaults before merging
+    config = deepMerge(this.#defaults, config);
+    this.#applyEnvironmentVariables(config);
+    // TODO apply command line arguments
+    return this.#getSubset(config, this.#prefix);
+  }
+
+  async #loadFile() {
+    let config = {};
+    for (const location of this.#locations) {
+      try {
+        const filePath = path.join(location, this.#name);
+        const content = await this.#fs.readFile(filePath, 'utf-8');
+        config = JSON.parse(content);
+        break;
+      } catch (err) {
+        if (err.code === 'ENOENT') {
+          // ignore file not found
+          continue;
+        }
+
+        throw err;
+      }
+    }
+    return config;
+  }
+
+  #applyEnvironmentVariables(config, path) {
+    // handle object
+    // handle array
+    // handle string
+    // handle number
+    // handle boolean (true, false)
+    // handle null (empty env var set the value to null)
+    // if env var is undefined, keep the default value
+    for (const key in config) {
+      if (typeof config[key] === 'boolean') {
+        const value = this.#getEnv(key, path);
+        if (value === null) {
+          config[key] = null;
+        } else if (value) {
+          config[key] = value.toLowerCase() === 'true';
+        }
+      } else if (typeof config[key] === 'number') {
+        const value = this.#getEnv(key, path);
+        if (value === null) {
+          config[key] = null;
+        } else if (value) {
+          config[key] = Number(value);
+        }
+      } else if (typeof config[key] === 'string') {
+        const value = this.#getEnv(key, path);
+        if (value === null) {
+          config[key] = null;
+        } else if (value) {
+          config[key] = String(value);
+        }
+      } else if (config[key] === null) {
+        const value = this.#getEnv(key, path);
+        if (value === null) {
+          config[key] = null;
+        } else if (value) {
+          config[key] = value;
+        }
+      } else if (typeof config[key] === 'object') {
+        const value = this.#getEnv(key, path);
+        if (value === null) {
+          config[key] = null;
+        } else if (Array.isArray(config[key]) && value) {
+          config[key] = value.split(',');
+        } else {
+          this.#applyEnvironmentVariables(config[key], key);
+        }
+      } else {
+        throw new Error(`Unsupported type: ${typeof config[key]}`);
+      }
+    }
+  }
+
+  #getEnv(key, path = '') {
+    let envKey = key;
+    if (path) {
+      envKey = `${path}_${envKey}`;
+    }
+    envKey = envKey.toUpperCase();
+    const value = process.env[envKey];
+    if (value === '') {
+      return null;
+    }
+    return value;
+  }
+
+  #getSubset(config, prefix) {
+    if (prefix === '') {
+      return config;
+    }
+
+    const [key, ...rest] = prefix.split('.');
+    if (rest.length === 0) {
+      return config[key];
+    }
+
+    return this.#getSubset(config[key], rest.join('.'));
+  }
+}
+
+class FsStub {
+  #files;
+
+  constructor(files) {
+    this.#files = files;
+  }
+
+  readFile(path) {
+    const fileContent = this.#files[path];
+    if (fileContent == null) {
+      const err = new Error(`File not found: ${path}`);
+      err.code = 'ENOENT';
+      throw err;
+    }
+
+    if (typeof fileContent === 'string') {
+      return fileContent;
+    }
+
+    return JSON.stringify(fileContent);
+  }
+}

package/lib/node/handler.js

@@ -0,0 +1,23 @@
+// Copyright (c) 2023-2024 Falko Schumann. All rights reserved. MIT license.
+
+/**
+ * @import * as express from 'express'
+ */
+
+export function runSafe(/** @type {express.RequestHandler} */ handler) {
+  // TODO runSafe is obsolete with with Express 5
+  return async (request, response, next) => {
+    try {
+      await handler(request, response);
+    } catch (error) {
+      next(error);
+    }
+  };
+}
+
+export function reply(
+  /** @type {express.Response} */ response,
+  { status = 200, headers = { 'Content-Type': 'text/plain' }, body = '' } = {},
+) {
+  response.status(status).header(headers).send(body);
+}

package/lib/node/index.js

@@ -0,0 +1,10 @@
+// Copyright (c) 2023-2024 Falko Schumann. All rights reserved. MIT license.
+
+export * from '../index.js';
+
+export * from './actuator-controller.js';
+export * from './configuration-properties.js';
+export * from './handler.js';
+export * from './logging.js';
+export * from './long-polling.js';
+export * from './sse-emitter.js';

package/lib/node/logging.js

@@ -0,0 +1,57 @@
+// Copyright (c) 2023-2024 Falko Schumann. All rights reserved. MIT license.
+
+/**
+ * @import { LogRecord } from '../logging.js';
+ */
+
+import fsPromises from 'node:fs/promises';
+
+import { Handler } from '../logging.js';
+
+/**
+ * A `Handler` that writes log messages to a file.
+ *
+ * @extends {Handler}
+ */
+export class FileHandler extends Handler {
+  #filename;
+  #limit;
+
+  /**
+   * Initialize a new `FileHandler`.
+   *
+   * @param {string} filename The name of the file to write log messages to.
+   * @param {number} [limit=0] The maximum size of the file in bytes before it
+   *   is rotated.
+   */
+  constructor(filename, limit = 0) {
+    super();
+    this.#filename = filename;
+    this.#limit = limit < 0 ? 0 : limit;
+  }
+
+  /** @override  */
+  async publish(/** @type {LogRecord} */ record) {
+    if (!this.isLoggable(record.level)) {
+      return;
+    }
+
+    const message = this.formatter.format(record);
+    if (this.#limit > 0) {
+      try {
+        const stats = await fsPromises.stat(this.#filename);
+        const fileSize = stats.size;
+        const newSize = fileSize + message.length;
+        if (newSize > this.#limit) {
+          await fsPromises.rm(this.#filename);
+        }
+      } catch (error) {
+        // ignore error if file does not exist
+        if (error.code !== 'ENOENT') {
+          console.error(error);
+        }
+      }
+    }
+    await fsPromises.appendFile(this.#filename, message + '\n');
+  }
+}

package/lib/node/long-polling.js

@@ -0,0 +1,81 @@
+// Copyright (c) 2023-2024 Falko Schumann. All rights reserved. MIT license.
+
+/**
+ * @import * as express from 'express'
+ */
+
+import * as handler from './handler.js';
+
+export class LongPolling {
+  #version = 0;
+  #waiting = [];
+  #getData;
+
+  constructor(/** @type {function(): Promise<*>} */ getData) {
+    this.#getData = getData;
+  }
+
+  async poll(
+    /** @type {express.Request} */ request,
+    /** @type {express.Response} */ response,
+  ) {
+    if (this.#isCurrentVersion(request)) {
+      const responseData = await this.#tryLongPolling(request);
+      handler.reply(response, responseData);
+    } else {
+      const responseData = await this.#getResponse();
+      handler.reply(response, responseData);
+    }
+  }
+
+  async send() {
+    this.#version++;
+    const response = await this.#getResponse();
+    this.#waiting.forEach((resolve) => resolve(response));
+    this.#waiting = [];
+  }
+
+  #isCurrentVersion(/** @type {express.Request} */ request) {
+    const tag = /"(.*)"/.exec(request.get('If-None-Match'));
+    return tag && tag[1] === String(this.#version);
+  }
+
+  #tryLongPolling(/** @type {express.Request} */ request) {
+    const time = this.#getPollingTime(request);
+    if (time == null) {
+      return { status: 304 };
+    }
+
+    return this.#waitForChange(time);
+  }
+
+  #getPollingTime(/** @type {express.Request} */ request) {
+    const wait = /\bwait=(\d+)/.exec(request.get('Prefer'));
+    return wait != null ? Number(wait[1]) : null;
+  }
+
+  #waitForChange(/** @type {number} */ time) {
+    return new Promise((resolve) => {
+      this.#waiting.push(resolve);
+      setTimeout(() => {
+        if (this.#waiting.includes(resolve)) {
+          this.#waiting = this.#waiting.filter((r) => r !== resolve);
+          resolve({ status: 304 });
+        }
+      }, time * 1000);
+    });
+  }
+
+  async #getResponse() {
+    const data = await this.#getData();
+    const body = JSON.stringify(data);
+    return {
+      headers: {
+        'Content-Type': 'application/json',
+        ETag: `"${this.#version}"`,
+        'Cache-Control': 'no-store',
+      },
+      body,
+    };
+  }
+}

package/lib/node/sse-emitter.js

@@ -0,0 +1,104 @@
+// Copyright (c) 2023-2024 Falko Schumann. All rights reserved. MIT license.
+
+/**
+ * @import http from 'node:http'
+ */
+
+/**
+ * An object for sending
+ * [Server-Sent Events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events).
+ */
+export class SseEmitter {
+  /** @type {?number} */ #timeout;
+  /** @type {http.ServerResponse|undefined} */ #response;
+
+  /**
+   * Creates a new SSE emitter with an optional timeout.
+   *
+   * @param {number} [timeout] The timeout in milliseconds after which the
+   *   connection will be closed.
+   */
+  constructor(timeout) {
+    this.#timeout = timeout;
+  }
+
+  /**
+   * The timeout in milliseconds after which the connection will be closed or
+   * undefined if no timeout is set.
+   *
+   * @type {number|undefined}
+   */
+  get timeout() {
+    return this.#timeout;
+  }
+
+  /**
+   * Sets and extends the response object for sending Server-Sent Events.
+   *
+   * @param {http.ServerResponse} outputMessage The response object to use.
+   */
+  extendResponse(outputMessage) {
+    // TODO check HTTP version, is it HTTP/2 when using EventSource?
+    outputMessage.statusCode = 200;
+    this.#response = outputMessage
+      .setHeader('Content-Type', 'text/event-stream')
+      .setHeader('Cache-Control', 'no-cache')
+      .setHeader('Keep-Alive', 'timeout=60')
+      .setHeader('Connection', 'keep-alive');
+
+    if (this.timeout != null) {
+      const timeoutId = setTimeout(() => this.#close(), this.timeout);
+      this.#response.addListener('close', () => clearTimeout(timeoutId));
+    }
+  }
+
+  /**
+   * Sends a SSE event.
+   *
+   * @param {object} event The event to send.
+   * @param {string} [event.id] Add a SSE "id" line.
+   * @param {string} [event.name] Add a SSE "event" line.
+   * @param {number} [event.reconnectTime] Add a SSE "retry" line.
+   * @param {string} [event.comment] Add a SSE "comment" line.
+   * @param {string|object} [event.data] Add a SSE "data" line.
+   */
+  send({ id, name, reconnectTime, comment, data } = {}) {
+    if (comment != null) {
+      this.#response.write(`: ${comment}\n`);
+    }
+
+    if (name != null) {
+      this.#response.write(`event: ${name}\n`);
+    }
+
+    if (data != null) {
+      if (typeof data === 'object') {
+        data = JSON.stringify(data);
+      } else {
+        data = String(data).replaceAll('\n', '\ndata: ');
+      }
+      this.#response.write(`data: ${data}\n`);
+    }
+
+    if (id != null) {
+      this.#response.write(`id: ${id}\n`);
+    }
+
+    if (reconnectTime != null) {
+      this.#response.write(`retry: ${reconnectTime}\n`);
+    }
+
+    this.#response.write('\n');
+  }
+
+  /**
+   * Simulates a timeout.
+   */
+  simulateTimeout() {
+    this.#close();
+  }
+
+  #close() {
+    this.#response.end();
+  }
+}

package/lib/output-tracker.js

@@ -0,0 +1,89 @@
+// Copyright (c) 2023-2024 Falko Schumann. All rights reserved. MIT license.
+
+/**
+ * Tracks output events.
+ *
+ * This is one of the nullability patterns from James Shore's article on
+ * [testing without mocks](https://www.jamesshore.com/v2/projects/nullables/testing-without-mocks#output-tracking).
+ *
+ * Example implementation of an event store:
+ *
+ * ```javascript
+ * async record(event) {
+ *   // ...
+ *   this.dispatchEvent(new CustomEvent(EVENT_RECORDED_EVENT, { detail: event }));
+ * }
+ *
+ * trackEventsRecorded() {
+ *   return new OutputTracker(this, EVENT_RECORDED_EVENT);
+ * }
+ * ```
+ *
+ * Example usage:
+ *
+ * ```javascript
+ * const eventsRecorded = eventStore.trackEventsRecorded();
+ * // ...
+ * const data = eventsRecorded.data(); // [event1, event2, ...]
+ * ```
+ */
+export class OutputTracker {
+  /**
+   * Creates a tracker for a specific event of an event target.
+   *
+   * @param {EventTarget} eventTarget The event target to track.
+   * @param {string} event The event name to track.
+   */
+  static create(eventTarget, event) {
+    return new OutputTracker(eventTarget, event);
+  }
+
+  #eventTarget;
+  #event;
+  #tracker;
+  #data = [];
+
+  /**
+   * Creates a tracker for a specific event of an event target.
+   *
+   * @param {EventTarget} eventTarget The event target to track.
+   * @param {string} event The event name to track.
+   */
+  constructor(
+    /** @type {EventTarget} */ eventTarget,
+    /** @type {string} */ event,
+  ) {
+    this.#eventTarget = eventTarget;
+    this.#event = event;
+    this.#tracker = (event) => this.#data.push(event.detail);
+
+    this.#eventTarget.addEventListener(this.#event, this.#tracker);
+  }
+
+  /**
+   * Returns the tracked data.
+   *
+   * @return {Array} The tracked data.
+   */
+  get data() {
+    return this.#data;
+  }
+
+  /**
+   * Clears the tracked data and returns the cleared data.
+   *
+   * @return {Array} The cleared data.
+   */
+  clear() {
+    const result = [...this.#data];
+    this.#data.length = 0;
+    return result;
+  }
+
+  /**
+   * Stops tracking.
+   */
+  stop() {
+    this.#eventTarget.removeEventListener(this.#event, this.#tracker);
+  }
+}

package/lib/service-locator.js

@@ -0,0 +1,44 @@
+// Copyright (c) 2023-2024 Falko Schumann. All rights reserved. MIT license.
+
+/**
+ * A central place to register and resolve services.
+ */
+export class ServiceLocator {
+  static #instance = new ServiceLocator();
+
+  /**
+   * Gets the default service locator.
+   *
+   * @return {ServiceLocator} The default service locator.
+   */
+  static getDefault() {
+    return ServiceLocator.#instance;
+  }
+
+  #services = new Map();
+
+  /**
+   * Registers a service with name.
+   *
+   * @param {string} name The name of the service.
+   * @param {object|Function} service The service object or constructor.
+   */
+  register(name, service) {
+    this.#services.set(name, service);
+  }
+
+  /**
+   * Resolves a service by name.
+   *
+   * @param {string} name The name of the service.
+   * @return {object} The service object.
+   */
+  resolve(name) {
+    const service = this.#services.get(name);
+    if (service == null) {
+      throw new Error(`Service not found: ${name}.`);
+    }
+
+    return typeof service === 'function' ? service() : service;
+  }
+}