@muspellheim/shared 0.6.1 → 0.7.0

package/lib/util.js

@@ -1,380 +0,0 @@
-// Copyright (c) 2023-2024 Falko Schumann. All rights reserved. MIT license.
-
-/**
- * Contains several miscellaneous utility classes.
- *
- * Ported 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 deep equals
-
-/**
- * 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));
-}
-
-/**
- * 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 (typeof source !== 'object' || source === null) {
-    return source;
-  }
-
-  if (Array.isArray(target) && Array.isArray(source)) {
-    for (const item of source) {
-      const element = deepMerge(undefined, item);
-      target.push(element);
-    }
-    return target;
-  }
-
-  for (const key in source) {
-    if (typeof target !== 'object' || target === null) {
-      target = {};
-    }
-
-    target[key] = deepMerge(target[key], source[key]);
-  }
-
-  return target;
-}
-
-/**
- * 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());
-  }
-
-  /** @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(clock = Clock.system(), 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;
-    }
-
-    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

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