@muspellheim/shared 0.6.0 → 0.7.0

package/lib/node/configuration-properties.js

@@ -1,291 +0,0 @@
-// Copyright (c) 2023-2024 Falko Schumann. All rights reserved. MIT license.
-
-/**
- * Provide the configuration of an application.
- *
- * The sources in order of priority:
- *
- * 1. JSON file
- * 2. Environment variables
- * 3. Command line arguments
- *
- * @module
- */
-
-import fsPromises from 'node:fs/promises';
-import path from 'node:path';
-import process from 'node:process';
-
-import { deepCopy, deepMerge } from '../util.js';
-
-// TODO How to handle optional values? Cast to which type?
-// TODO Use JSON schema to validate the configuration?
-
-/**
- * Reads the configuration from file and environment variables.
- *
- * The configuration is read from a JSON file `application.json` from the
- * working directory. Can be configured with `config.name`, `config.location`.
- *
- * Example:
- *
- * ```javascript
- * const configuration = ConfigurationProperties.create();
- * const config = await configuration.get();
- * ```
- *
- * With default values:
- *
- * ```javascript
- * const configuration = ConfigurationProperties.create({
- *   defaultProperties: {
- *       port: 8080,
- *       database: { host: 'localhost', port: 5432 },
- *   },
- * });
- * const config = await configuration.get();
- * ```
- *
- * @template T
- */
-export class ConfigurationProperties {
-  /**
-   * Creates an instance of the application configuration.
-   *
-   * @template T
-   * @param {object} options The configuration options.
-   * @param {T} [options.defaultProperties=null] The default configuration.
-   * @param {string} [options.prefix=""] The prefix of the properties to get.
-   * @return {ConfigurationProperties<T>} The new instance.
-   */
-  static create({ defaultProperties = null, prefix = '' } = {}) {
-    return new ConfigurationProperties(defaultProperties, prefix, fsPromises);
-  }
-
-  /**
-   * Creates a nullable of the application configuration.
-   *
-   * @template T
-   * @param {object} options The configuration options.
-   * @param {T} [options.defaultProperties=null] The default configuration.
-   * @param {string} [options.prefix=""] The prefix of the properties to get.
-   * @param {object} [options.files={}] The files and file content that are
-   *   available.
-   * @return {ConfigurationProperties<T>} The new instance.
-   */
-  static createNull({
-    defaultProperties = null,
-    prefix = '',
-    files = {},
-  } = {}) {
-    return new ConfigurationProperties(
-      defaultProperties,
-      prefix,
-      new FsStub(files),
-    );
-  }
-
-  /** @type {T} */
-  #defaultProperties;
-
-  /** @type {string} */
-  #prefix;
-
-  /** @type {fsPromises} */
-  #fs;
-
-  /** @type {T} */
-  #cached;
-
-  /**
-   * The constructor is for internal use. Use the factory methods instead.
-   *
-   * @param {T} defaultProperties
-   * @param {string} prefix
-   * @param {fsPromises} fs
-   * @see ConfigurationProperties.create
-   * @see ConfigurationProperties.createNull
-   */
-  constructor(defaultProperties, prefix, fs) {
-    this.#defaultProperties = defaultProperties;
-    this.#prefix = prefix;
-    this.#fs = fs;
-  }
-
-  /**
-   * Loads the configuration from the file.
-   *
-   * @return {Promise<T>} The configuration object.
-   */
-  async get() {
-    if (this.#cached !== undefined) {
-      return this.#cached;
-    }
-
-    // TODO Interpret placeholders like ${foo.bar}
-    // TODO Interpret placeholders with default value like ${foo.bar:default}
-
-    let config = await this.#loadFile();
-    config = deepMerge(deepCopy(this.#defaultProperties), config);
-    // TODO apply environment variable APPLICATION_JSON as JSON string
-    this.#applyVariables(config, getEnv);
-    this.#applyVariables(config, getArg);
-    this.#cached = this.#getSubset(config, this.#prefix);
-    return this.#cached;
-  }
-
-  async #loadFile() {
-    const { name, location } = this.#getConfig();
-    for (const l of location) {
-      try {
-        const filePath = path.join(l, name);
-        const content = await this.#fs.readFile(filePath, 'utf-8');
-        return JSON.parse(content);
-      } catch (err) {
-        // @ts-ignore NodeJS error code
-        if (err.code === 'ENOENT') {
-          // ignore file not found
-          continue;
-        }
-
-        throw err;
-      }
-    }
-  }
-
-  #getConfig() {
-    const defaultConfig = {
-      config: {
-        name: 'application.json',
-        location: ['.', 'config'],
-      },
-    };
-    this.#applyVariables(defaultConfig, getEnv);
-    this.#applyVariables(defaultConfig, getArg);
-    const {
-      config: { name, location },
-    } = defaultConfig;
-    return { name, location };
-  }
-
-  #applyVariables(config, getValue, path) {
-    // handle object
-    // handle array
-    // handle string
-    // handle number
-    // handle boolean (true, false)
-    // handle null (empty string set the value to null)
-    // if value is undefined, keep the default value
-    for (const key in config) {
-      if (typeof config[key] === 'boolean') {
-        const value = getValue(key, path);
-        if (value === null) {
-          config[key] = null;
-        } else if (value) {
-          config[key] = value.toLowerCase() === 'true';
-        }
-      } else if (typeof config[key] === 'number') {
-        const value = getValue(key, path);
-        if (value === null) {
-          config[key] = null;
-        } else if (value) {
-          config[key] = Number(value);
-        }
-      } else if (typeof config[key] === 'string') {
-        const value = getValue(key, path);
-        if (value === null) {
-          config[key] = null;
-        } else if (value) {
-          config[key] = String(value);
-        }
-      } else if (config[key] === null) {
-        const value = getValue(key, path);
-        if (value === null) {
-          config[key] = null;
-        } else if (value) {
-          config[key] = value;
-        }
-      } else if (typeof config[key] === 'object') {
-        const value = getValue(key, path);
-        if (value === null) {
-          config[key] = null;
-        } else if (Array.isArray(config[key]) && value) {
-          config[key] = value.split(',');
-        } else {
-          this.#applyVariables(config[key], getValue, key);
-        }
-      } else {
-        throw new Error(`Unsupported type: ${typeof config[key]}`);
-      }
-    }
-  }
-
-  #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('.'));
-  }
-}
-
-function getEnv(key, path = '') {
-  if (path) {
-    key = `${path}_${key}`;
-  }
-  key = key.toUpperCase();
-  const value = process.env[key];
-  if (value === '') {
-    return null;
-  }
-  return value;
-}
-
-function getArg(key, path = '') {
-  if (path) {
-    key = `${path}.${key}`;
-  }
-  key = `--${key}=`;
-  const keyValue = process.argv.find((arg) => arg.startsWith(key));
-  if (keyValue == null) {
-    return;
-  }
-
-  const [, value] = keyValue.split('=');
-  if (value === '') {
-    return null;
-  }
-  return value;
-}
-
-/**
- * @ignore
- */
-class FsStub {
-  /** @type {Record<string, string>} */
-  #files;
-
-  /**
-   * @param {Record<string, string>} files
-   */
-  constructor(files) {
-    this.#files = files;
-  }
-
-  readFile(path) {
-    const fileContent = this.#files[path];
-    if (fileContent == null) {
-      const err = new Error(`No such file or directory`);
-      // @ts-ignore NodeJS error code
-      err.code = 'ENOENT';
-      throw err;
-    }
-
-    return JSON.stringify(fileContent);
-  }
-}

package/lib/node/handler.js

@@ -1,25 +0,0 @@
-// Copyright (c) 2023-2024 Falko Schumann. All rights reserved. MIT license.
-
-/**
- * @import express from 'express'
- */
-
-// TODO Remove dependency to 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, next);
-    } 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

@@ -1,9 +0,0 @@
-// Copyright (c) 2023-2024 Falko Schumann. All rights reserved. MIT license.
-
-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';
-export * from './static-files-controller.js';

package/lib/node/logging.js

@@ -1,60 +0,0 @@
-// 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) {
-        // @ts-ignore NodeJS error code
-        if (error.code !== 'ENOENT') {
-          // ignore error if file does not exist
-          console.error(error);
-        } else {
-          throw error;
-        }
-      }
-    }
-    await fsPromises.appendFile(this.#filename, message + '\n');
-  }
-}

package/lib/node/long-polling.js

@@ -1,83 +0,0 @@
-// Copyright (c) 2023-2024 Falko Schumann. All rights reserved. MIT license.
-
-/**
- * @import * as express from 'express'
- */
-
-import * as handler from './handler.js';
-
-// TODO Remove dependency to express
-
-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

@@ -1,104 +0,0 @@
-// 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/node/static-files-controller.js

@@ -1,15 +0,0 @@
-// Copyright (c) 2024 Falko Schumann. All rights reserved. MIT license.
-
-import path from 'node:path';
-import express from 'express';
-
-export class StaticFilesController {
-  /**
-   * @param {express.Express} app
-   * @param {string} [directory="./public"]
-   * @param {string} [route="/"]
-   */
-  constructor(app, directory = './public', route = '/') {
-    app.use(route, express.static(path.join(directory)));
-  }
-}

package/lib/output-tracker.js

@@ -1,89 +0,0 @@
-// 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);
-  }
-}