@muspellheim/shared 0.4.0

package/lib/util.js

@@ -0,0 +1,361 @@
+// Copyright (c) 2023-2024 Falko Schumann. All rights reserved. MIT license.
+
+/**
+ * Contains several miscellaneous utility classes.
+ *
+ * Portated from
+ * [Java Util](https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/util/package-summary.html).
+ *
+ * @module
+ */
+
+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;
+  }
+
+  if (typeof target !== 'object' || target === null) {
+    return target;
+  }
+
+  if (Array.isArray(source) && Array.isArray(target)) {
+    for (const item of target) {
+      const element = deepMerge(undefined, item);
+      source.push(element);
+    }
+    return source;
+  }
+
+  for (const key in target) {
+    if (typeof source !== 'object' || source === null) {
+      source = {};
+    }
+
+    source[key] = deepMerge(source[key], target[key]);
+  }
+
+  return source;
+}
+
+/**
+ * An instance of `Random` is used to generate random numbers.
+ */
+export class Random {
+  static create() {
+    return new Random();
+  }
+
+  /** @hideconstructor */
+  constructor() {}
+
+  /**
+   * Returns a random boolean value.
+   *
+   * @param {number} [probabilityOfUndefined=0.0] The probability of returning
+   *   `undefined`.
+   * @return {boolean|undefined} A random boolean between `origin` (inclusive)
+   *   and `bound` (exclusive) or undefined.
+   */
+  nextBoolean(probabilityOfUndefined = 0.0) {
+    return this.#randomOptional(
+      () => Math.random() < 0.5,
+      probabilityOfUndefined,
+    );
+  }
+
+  /**
+   * Returns a random integer between `origin` (inclusive) and `bound`
+   * (exclusive).
+   *
+   * @param {number} [origin=0] The least value that can be returned.
+   * @param {number} [bound=1] The upper bound (exclusive) for the returned
+   *   value.
+   * @param {number} [probabilityOfUndefined=0.0] The probability of returning
+   *  `undefined`.
+   * @return {number|undefined} A random integer between `origin` (inclusive)
+   *   and `bound` (exclusive) or undefined.
+   */
+  nextInt(origin = 0, bound = 1, probabilityOfUndefined = 0.0) {
+    return this.#randomOptional(
+      () => Math.floor(this.nextFloat(origin, bound)),
+      probabilityOfUndefined,
+    );
+  }
+
+  /**
+   * Returns a random float between `origin` (inclusive) and `bound`
+   * (exclusive).
+   *
+   * @param {number} [origin=0.0] The least value that can be returned.
+   * @param {number} [bound=1.0] The upper bound (exclusive) for the returned
+   *   value.
+   * @param {number} [probabilityOfUndefined=0.0] The probability of returning
+   *   `undefined`.
+   * @return {number|undefined} A random float between `origin` (inclusive) and
+   *   `bound` (exclusive) or undefined.
+   */
+  nextFloat(origin = 0.0, bound = 1.0, probabilityOfUndefined = 0.0) {
+    return this.#randomOptional(
+      () => Math.random() * (bound - origin) + origin,
+      probabilityOfUndefined,
+    );
+  }
+
+  /**
+   * Returns a random timestamp with optional random offset.
+   *
+   * @param {number} [maxMillis=0] The maximum offset in milliseconds.
+   * @param {number} [probabilityOfUndefined=0.0] The probability of returning
+   *   `undefined`.
+   * @return {Date|undefined} A random timestamp or `undefined`.
+   */
+  nextDate(maxMillis = 0, probabilityOfUndefined = 0.0) {
+    return this.#randomOptional(() => {
+      const now = new Date();
+      let t = now.getTime();
+      const r = Math.random();
+      t += r * maxMillis;
+      return new Date(t);
+    }, probabilityOfUndefined);
+  }
+
+  /**
+   * Returns a random value from an array.
+   *
+   * @param {Array} [values=[]] The array of values.
+   * @param {number} [probabilityOfUndefined=0.0] The probability of returning
+   *   `undefined`.
+   * @return {*|undefined} A random value from the array or `undefined`.
+   */
+  nextValue(values = [], probabilityOfUndefined = 0.0) {
+    return this.#randomOptional(() => {
+      const index = new Random().nextInt(0, values.length - 1);
+      return values[index];
+    }, probabilityOfUndefined);
+  }
+
+  #randomOptional(randomFactory, probabilityOfUndefined) {
+    const r = Math.random();
+    return r < probabilityOfUndefined ? undefined : randomFactory();
+  }
+}
+
+const TASK_CREATED = 'created';
+const TASK_SCHEDULED = 'scheduled';
+const TASK_EXECUTED = 'executed';
+const TASK_CANCELLED = 'cancelled';
+
+/**
+ * A task that can be scheduled by a {@link Timer}.
+ */
+export class TimerTask {
+  _state = TASK_CREATED;
+  _nextExecutionTime = 0;
+  _period = 0;
+
+  /**
+   * Runs the task.
+   *
+   * @abstract
+   */
+  run() {
+    throw new Error('Method not implemented.');
+  }
+
+  /**
+   * Cancels the task.
+   *
+   * @return {boolean} `true` if this task was scheduled for one-time execution
+   *   and has not yet run, or this task was scheduled for repeated execution.
+   *   Return `false` if the task was scheduled for one-time execution and has
+   *   already run, or if the task was never scheduled, or if the task was
+   *   already cancelled.
+   */
+  cancel() {
+    const result = this._state === TASK_SCHEDULED;
+    this._state = TASK_CANCELLED;
+    return result;
+  }
+
+  /**
+   * Returns scheduled execution time of the most recent actual execution of
+   * this task.
+   *
+   * Example usage:
+   *
+   * ```javascript
+   * run() {
+   *   if (Date.now() - scheduledExecutionTime() >= MAX_TARDINESS) {
+   *     return; // Too late; skip this execution.
+   *   }
+   *   // Perform the task
+   * }
+   *
+   * ```
+   *
+   * @return {number} The time in milliseconds since the epoch, undefined if
+   *   the task has not yet run for the first time.
+   */
+  scheduledExecutionTime() {
+    return this._period < 0
+      ? this._nextExecutionTime + this._period
+      : this._nextExecutionTime - this._period;
+  }
+}
+
+/**
+ * A timer that schedules and cancels tasks.
+ *
+ * Tasks may be scheduled for one-time execution or for repeated execution at
+ * regular intervals.
+ */
+export class Timer extends EventTarget {
+  /**
+   * Returns a new `Timer`.
+   */
+  static create() {
+    return new Timer(Clock.system(), globalThis);
+  }
+
+  /**
+   * Returns a new `Timer` for testing without side effects.
+   */
+  static createNull({ clock = Clock.fixed() } = {}) {
+    return new Timer(clock, new TimeoutStub(clock));
+  }
+
+  #clock;
+  #global;
+  _queue;
+
+  /**
+   * Returns a new `Timer`.
+   */
+  constructor(
+    /** @type {Clock} */ clock = Clock.system(),
+    /** @type {globalThis} */ global = globalThis,
+  ) {
+    super();
+    this.#clock = clock;
+    this.#global = global;
+    this._queue = [];
+  }
+
+  /**
+   * Schedules a task for repeated execution at regular intervals.
+   *
+   * @param {TimerTask} task The task to execute.
+   * @param {number|Date} delayOrTime The delay before the first execution, in
+   *   milliseconds or the time of the first execution.
+   * @param {number} [period=0] The interval between executions, in
+   *   milliseconds; 0 means single execution.
+   */
+  schedule(task, delayOrTime, period = 0) {
+    this.#doSchedule(task, delayOrTime, -period);
+  }
+
+  /**
+   * Schedule a task for repeated fixed-rate execution.
+   *
+   * @param {TimerTask} task The task to execute.
+   * @param {number|Date} delayOrTime The delay before the first execution, in
+   *   milliseconds or the time of the first.
+   * @param {number} period The interval between executions, in milliseconds.
+   */
+  scheduleAtFixedRate(task, delayOrTime, period) {
+    this.#doSchedule(task, delayOrTime, period);
+  }
+
+  /**
+   * Cancels all scheduled tasks.
+   */
+  cancel() {
+    for (const task of this._queue) {
+      task.cancel();
+    }
+    this._queue = [];
+  }
+
+  /**
+   * Removes all cancelled tasks from the task queue.
+   *
+   * @return {number} The number of tasks removed from the task queue.
+   */
+  purge() {
+    let result = 0;
+    for (let i = 0; i < this._queue.length; i++) {
+      if (this._queue[i]._state === TASK_CANCELLED) {
+        this._queue.splice(i, 1);
+        i--;
+        result++;
+      }
+    }
+    return result;
+  }
+
+  /**
+   * Simulates the execution of a task.
+   *
+   * @param {object} options The simulation options.
+   * @param {number} [options.ticks=1000] The number of milliseconds to advance
+   *   the clock.
+   */
+  simulateTaskExecution({ ticks = 1000 } = {}) {
+    this.#clock.add(ticks);
+    this.#runMainLoop();
+  }
+
+  #doSchedule(task, delayOrTime, period) {
+    if (delayOrTime instanceof Date) {
+      task._nextExecutionTime = delayOrTime.getTime();
+    } else {
+      task._nextExecutionTime = this.#clock.millis() + delayOrTime;
+    }
+    task._period = period;
+    task._state = TASK_SCHEDULED;
+    this._queue.push(task);
+    this._queue.sort((a, b) => b._nextExecutionTime - a._nextExecutionTime);
+    if (this._queue[0] === task) {
+      this.#runMainLoop();
+    }
+  }
+
+  #runMainLoop() {
+    if (this._queue.length === 0) {
+      return;
+    }
+
+    /** @type {TimerTask} */ const task = this._queue[0];
+    if (task._state === TASK_CANCELLED) {
+      this._queue.shift();
+      return this.#runMainLoop();
+    }
+
+    const now = this.#clock.millis();
+    const executionTime = task._nextExecutionTime;
+    const taskFired = executionTime <= now;
+    if (taskFired) {
+      if (task._period === 0) {
+        this._queue.shift();
+        task._state = TASK_EXECUTED;
+      } else {
+        task._nextExecutionTime = task._period < 0
+          ? now - task._period
+          : executionTime + task._period;
+      }
+      task.run();
+    } else {
+      this.#global.setTimeout(() => this.#runMainLoop(), executionTime - now);
+    }
+  }
+}
+
+class TimeoutStub {
+  setTimeout() {}
+}

package/lib/validation.js

@@ -0,0 +1,299 @@
+// Copyright (c) 2023-2024 Falko Schumann. All rights reserved. MIT license.
+
+// TODO Use JSON schema to validate like Java Bean Validation?
+
+export class ValidationError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'ValidationError';
+  }
+}
+
+/** @return {never} */
+export function ensureUnreachable(message = 'Unreachable code executed.') {
+  throw new Error(message);
+}
+
+export function ensureThat(
+  value,
+  predicate,
+  message = 'Expected predicate is not true.',
+) {
+  const condition = predicate(value);
+  if (!condition) {
+    throw new ValidationError(message);
+  }
+
+  return value;
+}
+
+export function ensureAnything(value, { name = 'value' } = {}) {
+  if (value == null) {
+    throw new ValidationError(`The ${name} is required, but it was ${value}.`);
+  }
+
+  return value;
+}
+
+export function ensureNonEmpty(value, { name = 'value' } = {}) {
+  const valueType = getType(value);
+  if (
+    (valueType === String && value.length === 0) ||
+    (valueType === Array && value.length === 0) ||
+    (valueType === Object && Object.keys(value).length === 0)
+  ) {
+    throw new ValidationError(
+      `The ${name} must not be empty, but it was ${JSON.stringify(value)}.`,
+    );
+  }
+
+  return value;
+}
+
+/*
+ * type: undefined | null | Boolean | Number | BigInt | String | Symbol | Function | Object | Array | Enum | constructor | Record<string, type>
+ * expectedType: type | [ type ]
+ */
+
+export function ensureType(value, expectedType, { name = 'value' } = {}) {
+  const result = checkType(value, expectedType, { name });
+  if (result.error) {
+    throw new ValidationError(result.error);
+  }
+  return result.value;
+}
+
+export function ensureItemType(array, expectedType, { name = 'value' } = {}) {
+  const result = checkType(array, Array, { name });
+  if (result.error) {
+    throw new ValidationError(result.error);
+  }
+
+  array.forEach((item, index) => {
+    const result = checkType(item, expectedType, {
+      name: `${name}.${index}`,
+    });
+    if (result.error) {
+      throw new ValidationError(result.error);
+    }
+    array[index] = result.value;
+  });
+  return array;
+}
+
+export function ensureArguments(args, expectedTypes = [], names = []) {
+  ensureThat(
+    expectedTypes,
+    Array.isArray,
+    'The expectedTypes must be an array.',
+  );
+  ensureThat(names, Array.isArray, 'The names must be an array.');
+  if (args.length > expectedTypes.length) {
+    throw new ValidationError(
+      `Too many arguments: expected ${expectedTypes.length}, but got ${args.length}.`,
+    );
+  }
+  expectedTypes.forEach((expectedType, index) => {
+    const name = names[index] ? names[index] : `argument #${index + 1}`;
+    ensureType(args[index], expectedType, { name });
+  });
+}
+
+/** @return {{value: ?*, error: ?string}}} */
+function checkType(value, expectedType, { name = 'value' } = {}) {
+  const valueType = getType(value);
+
+  // Check built-in types
+  if (
+    expectedType === undefined ||
+    expectedType === null ||
+    expectedType === Boolean ||
+    expectedType === Number ||
+    expectedType === BigInt ||
+    expectedType === String ||
+    expectedType === Symbol ||
+    expectedType === Function ||
+    expectedType === Object ||
+    expectedType === Array
+  ) {
+    if (valueType === expectedType) {
+      return { value };
+    }
+
+    return {
+      error: `The ${name} must be ${
+        describe(expectedType, {
+          articles: true,
+        })
+      }, but it was ${describe(valueType, { articles: true })}.`,
+    };
+  }
+
+  // Check enum types
+  if (Object.getPrototypeOf(expectedType).name === 'Enum') {
+    try {
+      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 })}.`,
+      };
+    }
+  }
+
+  // Check constructor types
+  if (typeof expectedType === 'function') {
+    if (value instanceof expectedType) {
+      return { 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 })}`;
+        if (valueType != null) {
+          error += `: ${JSON.stringify(value, { articles: true })}`;
+        }
+        error += '.';
+        return { error };
+      }
+
+      return { value: convertedValue };
+    }
+  }
+
+  // Check one of multiple types
+  if (Array.isArray(expectedType)) {
+    for (const type of expectedType) {
+      const result = checkType(value, type, { name });
+      if (!result.error) {
+        return { value };
+      }
+    }
+
+    return {
+      error: `The ${name} must be ${
+        describe(expectedType, {
+          articles: true,
+        })
+      }, but it was ${describe(valueType, { articles: true })}.`,
+    };
+  }
+
+  if (typeof expectedType === 'object') {
+    // Check struct types
+    const result = checkType(value, Object, { name });
+    if (result.error) {
+      return result;
+    }
+
+    for (const key in expectedType) {
+      const result = checkType(value[key], expectedType[key], {
+        name: `${name}.${key}`,
+      });
+      if (result.error) {
+        return result;
+      }
+      value[key] = result.value;
+    }
+
+    return { value };
+  }
+
+  ensureUnreachable();
+}
+
+function getType(value) {
+  if (value === null) {
+    return null;
+  }
+  if (Array.isArray(value)) {
+    return Array;
+  }
+  if (Number.isNaN(value)) {
+    return NaN;
+  }
+
+  switch (typeof value) {
+    case 'undefined':
+      return undefined;
+    case 'boolean':
+      return Boolean;
+    case 'number':
+      return Number;
+    case 'bigint':
+      return BigInt;
+    case 'string':
+      return String;
+    case 'symbol':
+      return Symbol;
+    case 'function':
+      return Function;
+    case 'object':
+      return Object;
+    default:
+      ensureUnreachable(`Unknown typeof value: ${typeof value}.`);
+  }
+}
+
+function describe(type, { articles = false } = {}) {
+  if (Array.isArray(type)) {
+    const types = type.map((t) => describe(t, { articles }));
+    if (types.length <= 2) {
+      return types.join(' or ');
+    } else {
+      const allButLast = types.slice(0, -1);
+      const last = types.at(-1);
+      return allButLast.join(', ') + ', or ' + last;
+    }
+  }
+
+  if (Number.isNaN(type)) {
+    return 'NaN';
+  }
+
+  let name;
+  switch (type) {
+    case null:
+      return 'null';
+    case undefined:
+      return 'undefined';
+    case Array:
+      name = 'array';
+      break;
+    case Boolean:
+      name = 'boolean';
+      break;
+    case Number:
+      name = 'number';
+      break;
+    case BigInt:
+      name = 'bigint';
+      break;
+    case String:
+      name = 'string';
+      break;
+    case Symbol:
+      name = 'symbol';
+      break;
+    case Function:
+      name = 'function';
+      break;
+    case Object:
+      name = 'object';
+      break;
+    default:
+      name = type.name;
+      break;
+  }
+
+  if (articles) {
+    name = 'aeiou'.includes(name[0].toLowerCase()) ? `an ${name}` : `a ${name}`;
+  }
+  return name;
+}