@muspellheim/shared 0.5.0 → 0.6.0

package/.prettierignore

@@ -0,0 +1,3 @@
+coverage/
+docs/
+*-corrupt.*

package/.prettierrc

@@ -0,0 +1,5 @@
+{
+  "proseWrap": "always",
+  "singleQuote": true,
+  "trailingComma": "all"
+}

package/README.md

@@ -1,4 +1,7 @@
-# Shared [![Build](https://github.com/falkoschumann/muspellheim-utils-javascript/actions/workflows/pipeline.yml/badge.svg)](https://github.com/falkoschumann/muspellheim-utils-javascript/actions/workflows/pipeline.yml)
+# Shared
+
+[![Build](https://github.com/falkoschumann/muspellheim-utils-javascript/actions/workflows/build.yml/badge.svg)](https://github.com/falkoschumann/muspellheim-utils-javascript/actions/workflows/build.yml)
+[![NPM Version](https://img.shields.io/npm/v/%40muspellheim%2Fshared)](https://www.npmjs.com/package/@muspellheim/shared)
 
 Some shared modules for the browser and Node from my projects.
 
@@ -9,8 +12,8 @@ Some shared modules for the browser and Node from my projects.
 ## Usage
 
     import { XXX } from '@muspellheim/shared';
-    import { XXX } from '@muspellheim/shared/browser/index.js';
-    import { XXX } from '@muspellheim/shared/browser/node.js';
+    import { XXX } from '@muspellheim/shared/browser';
+    import { XXX } from '@muspellheim/shared/node';
 
 See https://falkoschumann.github.io/muspellheim-shared-javascript/
 
@@ -25,5 +28,7 @@ The `Makefile` runs the build as default task. Other tasks are
 
 ## Open issues
 
-- [ ] Add missing docs.
-- [ ] Use asserts for parameters.
+- [ ] Add missing docs
+- [ ] Use asserts for parameters
+- [ ] Rename project to `muspellheim-shared-js`
+- [ ] Use equatable protocol for value objects

package/deno.json

@@ -1,6 +1,9 @@
 {
   "compilerOptions": {
-    "checkJs": false
+    "lib": ["es2022", "dom"],
+    "checkJs": true,
+    "noImplicitAny": false,
+    "strictNullChecks": false
   },
   "fmt": {
     "singleQuote": true,

package/deno.mk

@@ -0,0 +1,68 @@
+# Possible values: major, minor, patch or concrete version
+VERSION = minor
+
+all: dist docs check
+
+clean:
+	rm -rf coverage docs
+
+distclean: clean
+	rm -rf dist
+	rm -rf node_modules
+
+dist: build
+
+release: all
+	npm version $(VERSION) -m "chore: create release v%s"
+	git push
+	git push --tags
+
+publish: all
+	deno publish --dry-run
+
+docs:
+# FIXME	deno doc --html --name="Muspellheim Shared" --lint lib
+# FIXME deno doc --html --name="Muspellheim Shared" lib
+
+check: test
+	deno run --allow-all npm:eslint lib test
+	deno run --allow-all npm:prettier . --check
+# TODO	deno fmt --check
+	deno lint
+
+format:
+	deno run --allow-all npm:eslint --fix lib test
+	deno run --allow-all npm:prettier . --write
+# TODO	deno fmt
+	deno lint --fix
+
+dev: build
+	deno run --allow-all npm:vitest
+
+test: build
+	deno run --allow-all npm:vitest run
+
+unit-tests: build
+	deno run --allow-all npm:vitest run --testPathPattern=".*\/unit\/.*"
+
+integration-tests: build
+	deno run --allow-all npm:vitest run --testPathPattern=".*\/integration\/.*"
+
+e2e-tests: build
+	deno run --allow-all npm:vitest run --testPathPattern=".*\/e2e\/.*"
+
+coverage: build
+	deno run --allow-all npm:vitest run --coverage
+
+build: prepare
+
+prepare: version
+	deno install
+
+version:
+	@echo "Use Deno $(shell deno --version)"
+
+.PHONY: all clean distclean dist release publish docs \
+	check format \
+	dev test unit-tests integration-tests e2e-tests coverage \
+	build prepare version

package/eslint.config.js

@@ -0,0 +1,23 @@
+import js from '@eslint/js';
+import globals from 'globals';
+
+/** @type { import("eslint").Linter.FlatConfig[] } */
+export default [
+  js.configs.recommended,
+  {
+    languageOptions: {
+      ecmaVersion: 2022,
+      globals: {
+        ...globals.es2021,
+        ...globals.node,
+        ...globals.browser,
+        //...globals.serviceworker,
+        //...globals['shared-node-browser'],
+      },
+    },
+    ignores: ['coverage/**', 'docs/**'],
+    rules: {
+      'no-unused-vars': ['error', { argsIgnorePattern: '^_' }],
+    },
+  },
+];

package/lib/assert.js

@@ -9,7 +9,7 @@
  */
 export function assertNotNull(object, message) {
   if (object == null) {
-    message = typeof message === 'function' ? message() : message;
-    throw new ReferenceError(message);
+    const m = typeof message === 'function' ? message() : message;
+    throw new ReferenceError(m);
   }
 }

package/lib/browser/index.js

@@ -1,5 +1,3 @@
 // Copyright (c) 2023-2024 Falko Schumann. All rights reserved. MIT license.
 
-export * from '../index.js';
-
 export * from './components.js';

package/lib/color.js

@@ -6,37 +6,35 @@ const FACTOR = 0.7;
  * The Color class represents a color in the RGB color space.
  */
 export class Color {
-  #value;
+  /**
+   * The RGB value of the color.
+   *
+   * @type {number}
+   */
+  rgb;
 
   /**
    * Creates a color instance from RGB values.
    *
-   * @param {number} red The red component or the RGB value.
+   * @param {number|string} [red] The red component or the RGB value.
    * @param {number} [green] The green component.
    * @param {number} [blue] The blue component.
    */
   constructor(red, green, blue) {
-    if (green === undefined && blue === undefined) {
-      if (typeof red === 'string') {
-        this.#value = parseInt(red, 16);
-        return;
-      }
-
-      this.#value = Number(red);
-      return;
+    if (typeof red === 'string') {
+      this.rgb = parseInt(red, 16);
+    } else if (
+      typeof red === 'number' &&
+      typeof green === 'number' &&
+      typeof blue === 'number'
+    ) {
+      this.rgb =
+        ((red & 0xff) << 16) | ((green & 0xff) << 8) | ((blue & 0xff) << 0);
+    } else if (typeof red === 'number') {
+      this.rgb = red;
+    } else {
+      this.rgb = NaN;
     }
-
-    this.#value = ((red & 0xff) << 16) | ((green & 0xff) << 8) |
-      ((blue & 0xff) << 0);
-  }
-
-  /**
-   * The RGB value of the color.
-   *
-   * @type {number}
-   */
-  get rgb() {
-    return this.#value;
   }
 
   /**

package/lib/health.js

@@ -161,10 +161,7 @@ export class Health {
    * @param {Status} status The status of the health.
    * @param {Record<string, *>} details The details of the health.
    */
-  constructor(
-    /** @type {Status} */ status,
-    /** @type {?Record<string, *>} */ details,
-  ) {
+  constructor(status, details) {
     assertNotNull(status, 'Status must not be null.');
     // TODO assertNotNull(details, 'Details must not be null.');
 
@@ -502,9 +499,8 @@ export class HealthEndpoint {
 
     let health;
     if (statuses.length > 0) {
-      const status = this.#groups.primary.statusAggregator.getAggregateStatus(
-        statuses,
-      );
+      const status =
+        this.#groups.primary.statusAggregator.getAggregateStatus(statuses);
       health = new CompositeHealth(status, components);
     } else {
       health = Health.up();

package/lib/index.js

@@ -3,12 +3,13 @@
 export * from './assert.js';
 export * from './color.js';
 export * from './configurable-responses.js';
-export * from './lang.js';
 export * from './feature-toggle.js';
 export * from './health.js';
+export * from './lang.js';
 export * from './logging.js';
 export * from './long-polling-client.js';
 export * from './message-client.js';
+export * from './messages.js';
 export * from './metrics.js';
 export * from './output-tracker.js';
 export * from './service-locator.js';

package/lib/lang.js

@@ -22,14 +22,12 @@ import { ensureArguments } from './validation.js';
  *   static NO = new YesNo('NO', 1);
  * }
  * ```
- *
- * @template [T=Enum] - the type of the enum object
  */
 export class Enum {
   /**
    * Returns all enum constants.
    *
-   * @return {T[]} All enum constants.
+   * @return {Enum[]} All enum constants.
    */
   static values() {
     return Object.values(this);
@@ -39,7 +37,7 @@ export class Enum {
    * Returns an enum constant by its name.
    *
    * @param {string} name The name of the enum constant.
-   * @return {T} The enum constant.
+   * @return {Enum} The enum constant.
    */
   static valueOf(name) {
     const value = this.values().find((v) => v.name === name);
@@ -53,8 +51,8 @@ export class Enum {
   /**
    * Creates an enum object.
    *
-   * @param {number} ordinal The ordinal of the enum constant.
    * @param {string} name The name of the enum constant.
+   * @param {number} ordinal The ordinal of the enum constant.
    */
   constructor(name, ordinal) {
     ensureArguments(arguments, [String, Number]);

package/lib/logging.js

@@ -179,7 +179,7 @@ export class Logger extends EventTarget {
    *
    * The root logger has not a parent.
    *
-   * @type {?Logger}
+   * @type {Logger=}
    */
   parent;
 
@@ -202,8 +202,7 @@ export class Logger extends EventTarget {
   /**
    * Initializes a new logger with the given name.
    *
-   * @param {string} name The name of the logger.
-   * @private
+   * @param {?string} name The name of the logger.
    */
   constructor(name) {
     super();
@@ -213,7 +212,7 @@ export class Logger extends EventTarget {
   /**
    * The name of the logger.
    *
-   * @type {string}
+   * @type {?string}
    */
   get name() {
     return this.#name;
@@ -307,7 +306,7 @@ export class Logger extends EventTarget {
   isLoggable(level) {
     return this.level != null
       ? level >= this.level
-      : this.parent.isLoggable(level);
+      : (this.parent?.isLoggable(level) ?? false);
   }
 
   /**
@@ -376,7 +375,7 @@ export class LogRecord {
   /**
    * The name of the logger.
    *
-   * @type {string|undefined}
+   * @type {string|null}
    */
   loggerName;
 
@@ -428,7 +427,7 @@ export class Handler {
    * @param {LogRecord} record The log record to publish.
    * @abstract
    */
-  async publish() {
+  async publish(_record) {
     await Promise.reject('Not implemented');
   }
 
@@ -489,7 +488,7 @@ export class Formatter {
    * @return {string} The formatted log record.
    * @abstract
    */
-  format() {
+  format(_record) {
     throw new Error('Not implemented');
   }
 }
@@ -507,7 +506,8 @@ export class SimpleFormatter extends Formatter {
       s += ' [' + record.loggerName + ']';
     }
     s += ' ' + record.level.toString();
-    s += ' - ' +
+    s +=
+      ' - ' +
       record.message
         .map((m) => (typeof m === 'object' ? JSON.stringify(m) : m))
         .join(' ');
@@ -572,7 +572,8 @@ class LogManager {
   }
 
   addLogger(/** @type {Logger} */ logger) {
-    this.#namedLoggers.set(logger.name, logger);
+    const loggerName = logger.name;
+    this.#namedLoggers.set(loggerName, logger);
   }
 
   getLogger(/** @type {string} */ name) {

package/lib/long-polling-client.js

@@ -35,16 +35,14 @@ export class LongPollingClient extends MessageClient {
    * @param {object} options
    * @return {LongPollingClient} A new nulled long polling client.
    */
-  static createNull(
-    {
-      fetchResponse = {
-        status: 304,
-        statusText: 'Not Modified',
-        headers: undefined,
-        body: null,
-      },
-    } = {},
-  ) {
+  static createNull({
+    fetchResponse = {
+      status: 304,
+      statusText: 'Not Modified',
+      headers: undefined,
+      body: null,
+    },
+  } = {}) {
     return new LongPollingClient(90000, 0, createFetchStub(fetchResponse));
   }
 
@@ -75,14 +73,23 @@ export class LongPollingClient extends MessageClient {
     this.#aboutController = new AbortController();
   }
 
+  /**
+   * @override
+   */
   get isConnected() {
     return this.#connected;
   }
 
+  /**
+   * @override
+   */
   get url() {
     return this.#url;
   }
 
+  /**
+   * @override
+   */
   async connect(url) {
     if (this.isConnected) {
       throw new Error('Already connected.');
@@ -103,6 +110,9 @@ export class LongPollingClient extends MessageClient {
     return OutputTracker.create(this, REQUEST_SENT_EVENT);
   }
 
+  /**
+   * @override
+   */
   async close() {
     this.#aboutController.abort();
     this.#connected = false;
@@ -126,6 +136,7 @@ export class LongPollingClient extends MessageClient {
         });
         await this.#handleResponse(response);
       } catch (error) {
+        // @ts-ignore NodeJS error code
         if (error.name === 'AbortError') {
           break;
         } else {

package/lib/message-client.js

@@ -1,11 +1,5 @@
 // Copyright (c) 2023-2024 Falko Schumann. All rights reserved. MIT license.
 
-/**
- * @import { LongPollingClient } from './long-polling-client.js'
- * @import { SseClient } from './sse-client.js'
- * @import { WebSocketClient } from './web-socket-client.js'
- */
-
 /**
  * An interface for a streaming message client.
  *

package/lib/messages.js

@@ -0,0 +1,68 @@
+/**
+ * Provides CQNS features.
+ *
+ * The Command Query Notification Separation principle is a software design
+ * principle that separates the concerns of commands, queries, and
+ * notifications.
+ *
+ * Message hierarchy:
+ *
+ * - Message
+ *   - Incoming / outgoing
+ *     - Request (outgoing) -> response (incoming)
+ *       - Command -> command status
+ *       - Query -> query result
+ *     - Notification
+ *       - Incoming: notification -> commands
+ *       - Outgoing
+ *   - Event (internal)
+ *
+ * @see https://ralfw.de/command-query-notification-separation-cqns/
+ * @module
+ */
+
+/**
+ * The status returned by a command handler.
+ */
+export class CommandStatus {
+  /**
+   * Creates a successful status.
+   */
+  static success() {
+    return new CommandStatus(true);
+  }
+
+  /**
+   * Creates a failed status.
+   *
+   * @param {string} errorMessage
+   */
+  static failure(errorMessage) {
+    return new CommandStatus(false, errorMessage);
+  }
+
+  /**
+   * Indicates whether the command was successful.
+   *
+   * @type {boolean}
+   */
+  isSuccess;
+
+  /**
+   * The error message if the command failed.
+   *
+   * @type {string}
+   */
+  errorMessage;
+
+  /**
+   * Creates a new instance of CommandStatus.
+   *
+   * @param {boolean} isSuccess Indicates whether the command was successful.
+   * @param {string} [errorMessage] The error message if the command failed.
+   */
+  constructor(isSuccess, errorMessage) {
+    this.isSuccess = isSuccess;
+    this.errorMessage = errorMessage;
+  }
+}

package/lib/metrics.js

@@ -30,7 +30,7 @@ export class MeterRegistry {
   counter(name, tags) {
     const id = MeterId.create({ name, tags, type: MeterType.COUNTER });
     /** @type {Counter} */ let meter = this.#meters.find((meter) =>
-      meter.id.equals(id)
+      meter.id.equals(id),
     );
     if (!meter) {
       meter = new Counter(id);

package/lib/node/actuator-controller.js

@@ -10,6 +10,8 @@ import process from 'node:process';
 
 import * as handler from './handler.js';
 
+// TODO Remove dependency to express
+
 export class ActuatorController {
   #services;
   #healthContributorRegistry;
@@ -36,8 +38,8 @@ export class ActuatorController {
     /** @type {express.Request} */ request,
     /** @type {express.Response} */ response,
   ) {
-    let requestedUrl = request.protocol + '://' + request.get('host') +
-      request.originalUrl;
+    let requestedUrl =
+      request.protocol + '://' + request.get('host') + request.originalUrl;
     if (!requestedUrl.endsWith('/')) {
       requestedUrl += '/';
     }
@@ -92,12 +94,9 @@ export class ActuatorController {
 
     const metrics = await this.#services.getMetrics();
     const timestamp = new Date().getTime();
-    let body =
-      `# TYPE talks_count gauge\ntalks_count ${metrics.talksCount} ${timestamp}\n\n`;
-    body +=
-      `# TYPE presenters_count gauge\npresenters_count ${metrics.presentersCount} ${timestamp}\n\n`;
-    body +=
-      `# TYPE comments_count gauge\ncomments_count ${metrics.commentsCount} ${timestamp}\n\n`;
+    let body = `# TYPE talks_count gauge\ntalks_count ${metrics.talksCount} ${timestamp}\n\n`;
+    body += `# TYPE presenters_count gauge\npresenters_count ${metrics.presentersCount} ${timestamp}\n\n`;
+    body += `# TYPE comments_count gauge\ncomments_count ${metrics.commentsCount} ${timestamp}\n\n`;
     handler.reply(response, { body });
   }
 }