@muspellheim/shared 0.4.0 → 0.6.0

package/lib/util.js

@@ -3,7 +3,7 @@
 /**
  * Contains several miscellaneous utility classes.
  *
- * Portated from
+ * Ported from
  * [Java Util](https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/util/package-summary.html).
  *
  * @module
@@ -11,36 +11,51 @@
 
 import { Clock } from './time.js';
 
-// TODO check if import from time.js is needed
-// TODO deep copy
 // TODO deep equals
 
-export function deepMerge(source, target) {
-  if (target === undefined) {
-    return source;
-  }
+/**
+ * Creates a deep copy of a value.
+ *
+ * @param {*} value The value to copy.
+ * @returns {*} The deep copy of the value.
+ */
+export function deepCopy(value) {
+  return JSON.parse(JSON.stringify(value));
+}
 
-  if (typeof target !== 'object' || target === null) {
+/**
+ * Merges two objects deeply.
+ *
+ * @param {*} target The object to merge into.
+ * @param {*} source The object to merge.
+ * @returns {*} The merged object.
+ */
+export function deepMerge(target, source) {
+  if (source === undefined) {
     return target;
   }
 
-  if (Array.isArray(source) && Array.isArray(target)) {
-    for (const item of target) {
+  if (typeof source !== 'object' || source === null) {
+    return source;
+  }
+
+  if (Array.isArray(target) && Array.isArray(source)) {
+    for (const item of source) {
       const element = deepMerge(undefined, item);
-      source.push(element);
+      target.push(element);
     }
-    return source;
+    return target;
   }
 
-  for (const key in target) {
-    if (typeof source !== 'object' || source === null) {
-      source = {};
+  for (const key in source) {
+    if (typeof target !== 'object' || target === null) {
+      target = {};
     }
 
-    source[key] = deepMerge(source[key], target[key]);
+    target[key] = deepMerge(target[key], source[key]);
   }
 
-  return source;
+  return target;
 }
 
 /**
@@ -227,20 +242,25 @@ export class Timer extends EventTarget {
    * Returns a new `Timer` for testing without side effects.
    */
   static createNull({ clock = Clock.fixed() } = {}) {
-    return new Timer(clock, new TimeoutStub(clock));
+    return new Timer(clock, new TimeoutStub());
   }
 
+  /** @type {Clock} */
   #clock;
+
+  /** @type {globalThis} */
   #global;
+
+  /** @type {TimerTask[]} */
   _queue;
 
   /**
    * Returns a new `Timer`.
+   *
+   * @param {Clock=} clock The clock to use.
+   * @param {globalThis} global The global object.
    */
-  constructor(
-    /** @type {Clock} */ clock = Clock.system(),
-    /** @type {globalThis} */ global = globalThis,
-  ) {
+  constructor(clock = Clock.system(), global = globalThis) {
     super();
     this.#clock = clock;
     this.#global = global;
@@ -331,7 +351,7 @@ export class Timer extends EventTarget {
       return;
     }
 
-    /** @type {TimerTask} */ const task = this._queue[0];
+    const task = this._queue[0];
     if (task._state === TASK_CANCELLED) {
       this._queue.shift();
       return this.#runMainLoop();
@@ -345,9 +365,8 @@ export class Timer extends EventTarget {
         this._queue.shift();
         task._state = TASK_EXECUTED;
       } else {
-        task._nextExecutionTime = task._period < 0
-          ? now - task._period
-          : executionTime + task._period;
+        task._nextExecutionTime =
+          task._period < 0 ? now - task._period : executionTime + task._period;
       }
       task.run();
     } else {

package/lib/validation.js

@@ -99,7 +99,6 @@ export function ensureArguments(args, expectedTypes = [], names = []) {
   });
 }
 
-/** @return {{value: ?*, error: ?string}}} */
 function checkType(value, expectedType, { name = 'value' } = {}) {
   const valueType = getType(value);
 
@@ -121,11 +120,9 @@ function checkType(value, expectedType, { name = 'value' } = {}) {
     }
 
     return {
-      error: `The ${name} must be ${
-        describe(expectedType, {
-          articles: true,
-        })
-      }, but it was ${describe(valueType, { articles: true })}.`,
+      error: `The ${name} must be ${describe(expectedType, {
+        articles: true,
+      })}, but it was ${describe(valueType, { articles: true })}.`,
     };
   }
 
@@ -135,11 +132,9 @@ function checkType(value, expectedType, { name = 'value' } = {}) {
       return { value: expectedType.valueOf(String(value).toUpperCase()) };
     } catch {
       return {
-        error: `The ${name} must be ${
-          describe(expectedType, {
-            articles: true,
-          })
-        }, but it was ${describe(valueType, { articles: true })}.`,
+        error: `The ${name} must be ${describe(expectedType, {
+          articles: true,
+        })}, but it was ${describe(valueType, { articles: true })}.`,
       };
     }
   }
@@ -151,13 +146,11 @@ function checkType(value, expectedType, { name = 'value' } = {}) {
     } else {
       const convertedValue = new expectedType(value);
       if (String(convertedValue).toLowerCase().startsWith('invalid')) {
-        let error = `The ${name} must be a valid ${
-          describe(
-            expectedType,
-          )
-        }, but it was ${describe(valueType, { articles: true })}`;
+        let error = `The ${name} must be a valid ${describe(
+          expectedType,
+        )}, but it was ${describe(valueType, { articles: true })}`;
         if (valueType != null) {
-          error += `: ${JSON.stringify(value, { articles: true })}`;
+          error += `: ${JSON.stringify(value)}`;
         }
         error += '.';
         return { error };
@@ -177,11 +170,9 @@ function checkType(value, expectedType, { name = 'value' } = {}) {
     }
 
     return {
-      error: `The ${name} must be ${
-        describe(expectedType, {
-          articles: true,
-        })
-      }, but it was ${describe(valueType, { articles: true })}.`,
+      error: `The ${name} must be ${describe(expectedType, {
+        articles: true,
+      })}, but it was ${describe(valueType, { articles: true })}.`,
     };
   }
 

package/lib/vector.js

@@ -168,7 +168,7 @@ export class Line2D {
    * Returns the perpendicular of a point on this line.
    *
    * @param {Vector2D} point A point.
-   * @return {{foot: number, scalar: number}} The `foot` and the `scalar`.
+   * @return {{foot: Vector2D, scalar: number}} The `foot` and the `scalar`.
    */
   perpendicular(point) {
     // dissolve after r: (line.position + r * line.direction - point) * line.direction = 0

package/lib/vitest/equality-testers.js

@@ -0,0 +1,19 @@
+import { expect } from 'vitest';
+
+function isEquatable(a) {
+  return a != null && typeof a.equals === 'function';
+}
+
+function testEquatable(a, b) {
+  const isAEquatable = isEquatable(a);
+  const isBEquatable = isEquatable(b);
+  if (isAEquatable && isBEquatable) {
+    return a.equals(b);
+  } else if (isAEquatable === isBEquatable) {
+    return undefined;
+  } else {
+    return false;
+  }
+}
+
+expect.addEqualityTesters([testEquatable]);

package/lib/vitest/index.js

@@ -0,0 +1 @@
+export * from './equality-testers.js';

package/lib/web-socket-client.js

@@ -4,6 +4,10 @@ import { MessageClient } from './message-client.js';
 import { OutputTracker } from './output-tracker.js';
 import { Timer, TimerTask } from './util.js';
 
+/**
+ * @ignore @typedef {typeof WebSocket} WebSocketConstructor
+ */
+
 export const HEARTBEAT_TYPE = 'heartbeat';
 
 const MESSAGE_SENT_EVENT = 'message-sent';
@@ -61,7 +65,7 @@ export class WebSocketClient extends MessageClient {
   constructor(
     /** @type {number} */ heartbeat,
     /** @type {Timer} */ timer,
-    /** @type {function(new:WebSocket)} */ webSocketConstructor,
+    /** @type {WebSocketConstructor} */ webSocketConstructor,
   ) {
     super();
     this.#heartbeat = heartbeat;
@@ -69,14 +73,23 @@ export class WebSocketClient extends MessageClient {
     this.#webSocketConstructor = webSocketConstructor;
   }
 
+  /**
+   * @override
+   */
   get isConnected() {
     return this.#webSocket?.readyState === WebSocket.OPEN;
   }
 
+  /**
+   * @override
+   */
   get url() {
     return this.#webSocket?.url;
   }
 
+  /**
+   * @override
+   */
   async connect(/** @type {string | URL} */ url) {
     await new Promise((resolve, reject) => {
       if (this.isConnected) {
@@ -90,9 +103,8 @@ export class WebSocketClient extends MessageClient {
           this.#handleOpen(e);
           resolve();
         });
-        this.#webSocket.addEventListener(
-          'message',
-          (e) => this.#handleMessage(e),
+        this.#webSocket.addEventListener('message', (e) =>
+          this.#handleMessage(e),
         );
         this.#webSocket.addEventListener('close', (e) => this.#handleClose(e));
         this.#webSocket.addEventListener('error', (e) => this.#handleError(e));
@@ -104,14 +116,15 @@ export class WebSocketClient extends MessageClient {
 
   /**
    * Sends a message to the server.
-   *
    * @param {string} message The message to send.
+   * @override
    */
-  send(message) {
+  async send(message) {
     this.#webSocket.send(message);
     this.dispatchEvent(
       new CustomEvent(MESSAGE_SENT_EVENT, { detail: message }),
     );
+    await Promise.resolve();
   }
 
   /**
@@ -127,9 +140,9 @@ export class WebSocketClient extends MessageClient {
    * Closes the connection.
    *
    * If a code is provided, also a reason should be provided.
-   *
-   * @param {number} code An optional code.
-   * @param {string} reason An optional reason.
+   * @param {number} [code] An optional code.
+   * @param {string} [reason] An optional reason.
+   * @override
    */
   async close(code, reason) {
     await new Promise((resolve) => {
@@ -219,12 +232,16 @@ class HeartbeatTask extends TimerTask {
     this.#client = client;
   }
 
+  /**
+   * @override
+   */
   run() {
     this.#client.send(HEARTBEAT_TYPE);
   }
 }
 
 class WebSocketStub extends EventTarget {
+  /** @type {number} */
   readyState = WebSocket.CONNECTING;
 
   constructor(url) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@muspellheim/shared",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "author": "Falko Schumann",
   "license": "MIT",
   "engines": {
@@ -8,21 +8,31 @@
     "node": ">=18.7.0"
   },
   "type": "module",
-  "main": "dist/index.cjs",
-  "browser": "lib/browser/index.js",
+  "exports": {
+    ".": "./lib/index.js",
+    "./*.js": "./lib/*.js",
+    "./browser": "./lib/browser/index.js",
+    "./browser/*.js": "./lib/browser/*.js",
+    "./node": "./lib/node/index.js",
+    "./node/*.js": "./lib/node/*.js",
+    "./vitest": "./lib/vitest/index.js",
+    "./vitest/*.js": "./lib/vitest/*.js"
+  },
   "scripts": {
-    "build": "rollup -c",
     "test": "vitest"
   },
   "dependencies": {
-    "express": "^4.20.0",
-    "lit-html": "^3.2.0"
+    "express": "^4.21.2",
+    "lit-html": "^3.1.0"
   },
   "devDependencies": {
-    "@vitest/coverage-v8": "2.1.4",
+    "@eslint/js": "9.17.0",
+    "@vitest/coverage-v8": "2.1.8",
+    "eslint": "9.17.0",
+    "globals": "15.13.0",
     "jsdoc": "4.0.4",
     "jsdom": "25.0.1",
-    "rollup": "4.24.3",
-    "vitest": "2.1.4"
+    "prettier": "3.4.2",
+    "vitest": "2.1.8"
   }
 }

package/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "nodenext",
+    "lib": ["es2022", "dom"],
+    "allowJs": true,
+    "checkJs": false,
+    "noImplicitAny": false,
+    "strictNullChecks": false
+  },
+  "exclude": ["coverage", "dist", "node_modules"]
+}