@muspellheim/shared 0.5.0 → 0.6.1

package/lib/node/configuration-properties.js

@@ -1,19 +1,31 @@
 // 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 { deepMerge } from '../util.js';
+import { deepCopy, 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.
+ * Reads the configuration from file and environment variables.
  *
  * The configuration is read from a JSON file `application.json` from the
- * working directory.
+ * working directory. Can be configured with `config.name`, `config.location`.
  *
  * Example:
  *
@@ -26,120 +38,111 @@ import { deepMerge } from '../util.js';
  *
  * ```javascript
  * const configuration = ConfigurationProperties.create({
- *   defaults: {
+ *   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 {object} [options.defaults={}] The default configuration.
+   * @param {T} [options.defaultProperties=null] 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.
+   * @return {ConfigurationProperties<T>} The new instance.
    */
-  static create({
-    defaults = {},
-    prefix = '',
-    name = 'application.json',
-    location = ['.', 'config'],
-  } = {}) {
-    return new ConfigurationProperties(
-      defaults,
-      prefix,
-      name,
-      location,
-      fsPromises,
-    );
+  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 {object} [options.defaults={}] The default configuration.
+   * @param {T} [options.defaultProperties=null] 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.
+   * @return {ConfigurationProperties<T>} The new instance.
    */
   static createNull({
-    defaults = {},
+    defaultProperties = null,
     prefix = '',
-    name = 'application.json',
-    location = ['.', 'config'],
     files = {},
   } = {}) {
     return new ConfigurationProperties(
-      defaults,
+      defaultProperties,
       prefix,
-      name,
-      location,
       new FsStub(files),
     );
   }
 
-  #defaults;
+  /** @type {T} */
+  #defaultProperties;
+
+  /** @type {string} */
   #prefix;
-  #name;
-  #locations;
+
+  /** @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(
-    /** @type {object} */ defaults,
-    /** @type {string} */ prefix,
-    /** @type {string} */ name,
-    /** @type {string[]} */ locations,
-    /** @type {fsPromises} */ fs,
-  ) {
-    this.#defaults = defaults;
+  constructor(defaultProperties, prefix, fs) {
+    this.#defaultProperties = defaultProperties;
     this.#prefix = prefix;
-    this.#name = name;
-    this.#locations = locations;
     this.#fs = fs;
   }
 
   /**
    * Loads the configuration from the file.
    *
-   * @return {Promise<object>} The configuration object.
+   * @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();
-    // FIXME copy defaults before merging
-    config = deepMerge(this.#defaults, config);
-    this.#applyEnvironmentVariables(config);
-    // TODO apply command line arguments
-    return this.#getSubset(config, this.#prefix);
+    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() {
-    let config = {};
-    for (const location of this.#locations) {
+    const { name, location } = this.#getConfig();
+    for (const l of location) {
       try {
-        const filePath = path.join(location, this.#name);
+        const filePath = path.join(l, name);
         const content = await this.#fs.readFile(filePath, 'utf-8');
-        config = JSON.parse(content);
-        break;
+        return JSON.parse(content);
       } catch (err) {
+        // @ts-ignore NodeJS error code
         if (err.code === 'ENOENT') {
           // ignore file not found
           continue;
@@ -148,54 +151,68 @@ export class ConfigurationProperties {
         throw err;
       }
     }
-    return config;
   }
 
-  #applyEnvironmentVariables(config, path) {
+  #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 env var set the value to null)
-    // if env var is undefined, keep the default value
+    // 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 = this.#getEnv(key, path);
+        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 = this.#getEnv(key, path);
+        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 = this.#getEnv(key, path);
+        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 = this.#getEnv(key, path);
+        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 = this.#getEnv(key, path);
+        const value = getValue(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);
+          this.#applyVariables(config[key], getValue, key);
         }
       } else {
         throw new Error(`Unsupported type: ${typeof config[key]}`);
@@ -203,19 +220,6 @@ export class ConfigurationProperties {
     }
   }
 
-  #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;
@@ -230,9 +234,45 @@ export class ConfigurationProperties {
   }
 }
 
+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;
   }
@@ -240,15 +280,12 @@ class FsStub {
   readFile(path) {
     const fileContent = this.#files[path];
     if (fileContent == null) {
-      const err = new Error(`File not found: ${path}`);
+      const err = new Error(`No such file or directory`);
+      // @ts-ignore NodeJS error code
       err.code = 'ENOENT';
       throw err;
     }
 
-    if (typeof fileContent === 'string') {
-      return fileContent;
-    }
-
     return JSON.stringify(fileContent);
   }
 }

package/lib/node/handler.js

@@ -1,14 +1,16 @@
 // Copyright (c) 2023-2024 Falko Schumann. All rights reserved. MIT license.
 
 /**
- * @import * as express from 'express'
+ * @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);
+      await handler(request, response, next);
     } catch (error) {
       next(error);
     }

package/lib/node/index.js

@@ -1,10 +1,9 @@
 // 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';
+export * from './static-files-controller.js';

package/lib/node/logging.js

@@ -46,9 +46,12 @@ export class FileHandler extends Handler {
           await fsPromises.rm(this.#filename);
         }
       } catch (error) {
-        // ignore error if file does not exist
-        if (error.code !== 'ENOENT') {
+        // @ts-ignore NodeJS error code
+        if (error.code === 'ENOENT') {
+          // ignore error if file does not exist
           console.error(error);
+        } else {
+          throw error;
         }
       }
     }

package/lib/node/long-polling.js

@@ -6,6 +6,8 @@
 
 import * as handler from './handler.js';
 
+// TODO Remove dependency to express
+
 export class LongPolling {
   #version = 0;
   #waiting = [];

package/lib/node/static-files-controller.js

@@ -0,0 +1,15 @@
+// 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/sse-client.js

@@ -2,6 +2,10 @@
 
 import { MessageClient } from './message-client.js';
 
+/**
+ * @ignore @typedef {typeof EventSource} EventSourceConstructor
+ */
+
 /**
  * A client for the server-sent events protocol.
  *
@@ -32,29 +36,35 @@ export class SseClient extends MessageClient {
   /**
    * The constructor is for internal use. Use the factory methods instead.
    *
+   * @param {EventSourceConstructor} eventSourceConstructor
    * @see SseClient.create
    * @see SseClient.createNull
    */
-  constructor(/** @type {function(new:EventSource)} */ eventSourceConstructor) {
+  constructor(eventSourceConstructor) {
     super();
     this.#eventSourceConstructor = eventSourceConstructor;
   }
 
+  /**
+   * @override
+   */
   get isConnected() {
     return this.#eventSource?.readyState === this.#eventSourceConstructor.OPEN;
   }
 
+  /**
+   * @override
+   */
   get url() {
     return this.#eventSource?.url;
   }
 
   /**
    * Connects to the server.
-   *
    * @param {URL | string} url The server URL to connect to.
-   * @param {string} [eventName=message] The optional event type to listen to.
+   * @param {string} [eventName] The optional event type to listen to.
+   * @override
    */
-
   async connect(url, eventName = 'message') {
     await new Promise((resolve, reject) => {
       if (this.isConnected) {
@@ -68,13 +78,11 @@ export class SseClient extends MessageClient {
           this.#handleOpen(e);
           resolve();
         });
-        this.#eventSource.addEventListener(
-          eventName,
-          (e) => this.#handleMessage(e),
+        this.#eventSource.addEventListener(eventName, (e) =>
+          this.#handleMessage(e),
         );
-        this.#eventSource.addEventListener(
-          'error',
-          (e) => this.#handleError(e),
+        this.#eventSource.addEventListener('error', (e) =>
+          this.#handleError(e),
         );
       } catch (error) {
         reject(error);
@@ -82,6 +90,9 @@ export class SseClient extends MessageClient {
     });
   }
 
+  /**
+   * @override
+   */
   async close() {
     await new Promise((resolve, reject) => {
       if (!this.isConnected) {

package/lib/time.js

@@ -25,12 +25,12 @@ export class Clock {
   /**
    * Creates a clock using a fixed date.
    *
-   * @param {Date} [fixed='2024-02-21T19:16:00Z'] The fixed date of the clock.
+   * @param {Date} [date='2024-02-21T19:16:00Z'] The fixed date of the clock.
    * @return {Clock} A clock that returns alaways a fixed date.
    * @see Clock#add
    */
-  static fixed(fixedDate = new Date('2024-02-21T19:16:00Z')) {
-    return new Clock(fixedDate);
+  static fixed(date = new Date('2024-02-21T19:16:00Z')) {
+    return new Clock(date);
   }
 
   #date;
@@ -241,10 +241,11 @@ export class Duration {
    * @readonly
    */
   get secondsPart() {
-    const value = (this.millis -
-      this.daysPart * 86400000 -
-      this.hoursPart * 3600000 -
-      this.minutesPart * 60000) /
+    const value =
+      (this.millis -
+        this.daysPart * 86400000 -
+        this.hoursPart * 3600000 -
+        this.minutesPart * 60000) /
       1000;
     return this.isNegative() ? Math.ceil(value) : Math.floor(value);
   }
@@ -256,7 +257,8 @@ export class Duration {
    * @readonly
    */
   get millisPart() {
-    const value = this.millis -
+    const value =
+      this.millis -
       this.daysPart * 86400000 -
       this.hoursPart * 3600000 -
       this.minutesPart * 60000 -
@@ -267,7 +269,7 @@ export class Duration {
   /**
    * Checks if the duration is zero.
    *
-   * @type {boolean}
+   * @return {boolean}
    */
   isZero() {
     return this.millis === 0;
@@ -276,7 +278,7 @@ export class Duration {
   /**
    * Checks if the duration is negative.
    *
-   * @type {boolean}
+   * @return {boolean}
    */
   isNegative() {
     return this.millis < 0;
@@ -285,7 +287,7 @@ export class Duration {
   /**
    * Checks if the duration is positive.
    *
-   * @type {boolean}
+   * @return {boolean}
    */
   isPositive() {
     return this.millis > 0;