@muspellheim/shared 0.9.3 → 0.11.0

package/src/common/clock.ts

@@ -0,0 +1,60 @@
+// Copyright (c) 2025 Falko Schumann. All rights reserved. MIT license.
+
+/**
+ * A clock provides access to the current timestamp.
+ */
+export class Clock {
+  /**
+   * Create a clock using system the clock.
+   *
+   * @return A clock that uses the system clock.
+   */
+  static system(): Clock {
+    return new Clock();
+  }
+
+  /**
+   * Create a clock using a fixed date.
+   *
+   * @param date The fixed date of the clock.
+   * @return A clock that always returns a fixed date.
+   */
+  static fixed(date: Date | string | number): Clock {
+    return new Clock(new Date(date));
+  }
+
+  /**
+   * Create a clock that returns a fixed offset from the given clock.
+   *
+   * @param clock The clock to offset from.
+   * @param offsetMillis The offset in milliseconds.
+   * @return A clock that returns a fixed offset from the given clock.
+   */
+  static offset(clock: Clock, offsetMillis: number): Clock {
+    return new Clock(new Date(clock.millis() + offsetMillis));
+  }
+
+  readonly #date?: Date;
+
+  private constructor(date?: Date) {
+    this.#date = date;
+  }
+
+  /**
+   * Return the current timestamp of the clock.
+   *
+   * @return The current timestamp.
+   */
+  date(): Date {
+    return this.#date ? new Date(this.#date) : new Date();
+  }
+
+  /**
+   * Return the current timestamp of the clock in milliseconds.
+   *
+   * @return The current timestamp in milliseconds.
+   */
+  millis(): number {
+    return this.date().getTime();
+  }
+}

package/src/common/configurable_responses.ts

@@ -0,0 +1,90 @@
+// Copyright (c) 2025 Falko Schumann. All rights reserved. MIT license.
+// Copyright 2023 Titanium I.T. LLC. MIT License.
+
+/**
+ * Handle returning pre-configured responses.
+ *
+ * This is one of the nullability patterns from James Shore's article on
+ * [testing without mocks](https://www.jamesshore.com/v2/projects/nullables/testing-without-mocks#configurable-responses).
+ *
+ * Example usage for stubbing `fetch` function:
+ *
+ * ```javascript
+ * function createFetchStub(responses) {
+ *   const configurableResponses = ConfigurableResponses.create(responses);
+ *   return async function () {
+ *     const response = configurableResponses.next();
+ *     return {
+ *       status: response.status,
+ *       json: async () => response.body,
+ *     };
+ *   };
+ * }
+ * ```
+ */
+export class ConfigurableResponses<T = unknown> {
+  /**
+   * Create a list of responses (by providing an array), or a single repeating
+   * response (by providing any other type). 'Name' is optional and used in
+   * error messages.
+   *
+   * @param responses A single response or an array of responses.
+   * @param name An optional name for the responses.
+   */
+  static create<T>(responses?: T | T[], name?: string) {
+    return new ConfigurableResponses<T>(responses, name);
+  }
+
+  /**
+   * Convert all properties in an object into ConfigurableResponse instances.
+   * For example, { a: 1 } becomes { a: ConfigurableResponses.create(1) }.
+   * 'Name' is optional and used in error messages.
+   *
+   * @param responseObject An object with single response or an array of responses.
+   * @param name An optional name for the responses.
+   */
+  static mapObject<T extends Record<string, unknown>>(
+    responseObject: T,
+    name?: string,
+  ) {
+    const entries = Object.entries(responseObject);
+    const translatedEntries = entries.map(([key, value]) => {
+      const translatedName = name === undefined ? undefined : `${name}: ${key}`;
+      return [key, ConfigurableResponses.create(value, translatedName)];
+    });
+    return Object.fromEntries(translatedEntries);
+  }
+
+  readonly #description;
+  readonly #responses;
+
+  /**
+   * Create a list of responses (by providing an array), or a single repeating
+   * response (by providing any other type). 'Name' is optional and used in
+   * error messages.
+   *
+   * @param responses A single response or an array of responses.
+   * @param name An optional name for the responses.
+   */
+  constructor(responses?: T | T[], name?: string) {
+    this.#description = name == null ? "" : ` in ${name}`;
+    this.#responses = Array.isArray(responses) ? [...responses] : responses;
+  }
+
+  /**
+   * Get the next configured response. Throws an error when configured with a list
+   * of responses and no more responses remain.
+   *
+   * @return The next response.
+   */
+  next(): T {
+    const response = Array.isArray(this.#responses)
+      ? this.#responses.shift()
+      : this.#responses;
+    if (response === undefined) {
+      throw new Error(`No more responses configured${this.#description}.`);
+    }
+
+    return response;
+  }
+}

package/src/common/log.ts

@@ -0,0 +1,17 @@
+// Copyright (c) 2025 Falko Schumann. All rights reserved. MIT license.
+
+/**
+ * A simple logging facade.
+ *
+ * This is a subset of the `console` interface.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/Console_API
+ */
+export interface Log {
+  log(...data: unknown[]): void;
+  error(...data: unknown[]): void;
+  warn(...data: unknown[]): void;
+  info(...data: unknown[]): void;
+  debug(...data: unknown[]): void;
+  trace(...data: unknown[]): void;
+}

package/src/common/mod.ts

@@ -0,0 +1,6 @@
+// Copyright (c) 2025 Falko Schumann. All rights reserved. MIT license.
+
+export * from "./clock";
+export * from "./configurable_responses";
+export * from "./log";
+export * from "./output_tracker";

package/src/common/output_tracker.ts

@@ -0,0 +1,89 @@
+// Copyright (c) 2025 Falko Schumann. All rights reserved. MIT license.
+// Copyright 2020-2022 Titanium I.T. LLC. MIT License.
+
+/**
+ * Track output events.
+ *
+ * This is one of the nullability patterns from James Shore's article on
+ * [testing without mocks](https://www.jamesshore.com/v2/projects/nullables/testing-without-mocks#output-tracking).
+ *
+ * Example implementation of an event store:
+ *
+ * ```javascript
+ * async record(event) {
+ *   // ...
+ *   this.dispatchEvent(new CustomEvent("eventRecorded", { detail: event }));
+ * }
+ *
+ * trackEventsRecorded() {
+ *   return new OutputTracker(this, "eventRecorded");
+ * }
+ * ```
+ *
+ * Example usage:
+ *
+ * ```javascript
+ * const eventsRecorded = eventStore.trackEventsRecorded();
+ * // ...
+ * const data = eventsRecorded.data(); // [event1, event2, ...]
+ * ```
+ */
+export class OutputTracker<T = unknown> {
+  /**
+   * Create a tracker for a specific event of an event target.
+   *
+   * @param eventTarget The target to track.
+   * @param event The event name to track.
+   */
+  static create<T>(eventTarget: EventTarget, event: string) {
+    return new OutputTracker<T>(eventTarget, event);
+  }
+
+  readonly #eventTarget;
+  readonly #event;
+  readonly #data: T[];
+  readonly #tracker;
+
+  /**
+   * Create a tracker for a specific event of an event target.
+   *
+   * @param eventTarget The target to track.
+   * @param event The event name to track.
+   */
+  constructor(eventTarget: EventTarget, event: string) {
+    this.#eventTarget = eventTarget;
+    this.#event = event;
+    this.#data = [];
+    this.#tracker = (event: Event) =>
+      this.#data.push((event as CustomEvent<T>).detail);
+
+    this.#eventTarget.addEventListener(this.#event, this.#tracker);
+  }
+
+  /**
+   * Return the tracked data.
+   *
+   * @return The tracked data.
+   */
+  get data(): T[] {
+    return this.#data;
+  }
+
+  /**
+   * Clear the tracked data and return the cleared data.
+   *
+   * @return The cleared data.
+   */
+  clear(): T[] {
+    const result = [...this.#data];
+    this.#data.length = 0;
+    return result;
+  }
+
+  /**
+   * Stop tracking.
+   */
+  stop() {
+    this.#eventTarget.removeEventListener(this.#event, this.#tracker);
+  }
+}

package/src/domain/messages.ts

@@ -0,0 +1,53 @@
+// Copyright (c) 2025 Falko Schumann. All rights reserved. MIT license.
+
+/**
+ * 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 type CommandStatus = Success | Failure;
+
+/**
+ * A successful status.
+ */
+export class Success {
+  readonly isSuccess = true;
+}
+
+/**
+ * A failed status.
+ */
+export class Failure {
+  readonly isSuccess = false;
+  errorMessage: string;
+
+  /**
+   * Creates a failed status.
+   *
+   * @param errorMessage
+   */
+  constructor(errorMessage: string) {
+    this.errorMessage = errorMessage;
+  }
+}

package/src/domain/mod.ts

@@ -0,0 +1,3 @@
+// Copyright (c) 2025 Falko Schumann. All rights reserved. MIT license.
+
+export * from "./messages";

package/src/infrastructure/console_stub.ts

@@ -0,0 +1,67 @@
+// Copyright (c) 2025 Falko Schumann. All rights reserved. MIT license.
+
+import { OutputTracker } from "../common/output_tracker";
+
+const MESSAGE_EVENT = "message";
+
+/**
+ * A stub for the console interface.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/Console_API
+ */
+export class ConsoleStub extends EventTarget {
+  log(...data: unknown[]) {
+    this.dispatchEvent(
+      new CustomEvent(MESSAGE_EVENT, {
+        detail: { level: "log", message: data },
+      }),
+    );
+  }
+
+  error(...data: unknown[]) {
+    this.dispatchEvent(
+      new CustomEvent(MESSAGE_EVENT, {
+        detail: { level: "error", message: data },
+      }),
+    );
+  }
+
+  warn(...data: unknown[]) {
+    this.dispatchEvent(
+      new CustomEvent(MESSAGE_EVENT, {
+        detail: { level: "warn", message: data },
+      }),
+    );
+  }
+
+  info(...data: unknown[]) {
+    this.dispatchEvent(
+      new CustomEvent(MESSAGE_EVENT, {
+        detail: { level: "info", message: data },
+      }),
+    );
+  }
+
+  debug(...data: unknown[]) {
+    this.dispatchEvent(
+      new CustomEvent(MESSAGE_EVENT, {
+        detail: { level: "debug", message: data },
+      }),
+    );
+  }
+
+  trace(...data: unknown[]) {
+    this.dispatchEvent(
+      new CustomEvent(MESSAGE_EVENT, {
+        detail: { level: "trace", message: data },
+      }),
+    );
+  }
+
+  /**
+   * Track the console messages.
+   */
+  trackMessages() {
+    return new OutputTracker(this, MESSAGE_EVENT);
+  }
+}

package/src/infrastructure/fetch_stub.ts

@@ -0,0 +1,89 @@
+// Copyright (c) 2025 Falko Schumann. All rights reserved. MIT license.
+
+import { ConfigurableResponses } from "../common/configurable_responses";
+
+/**
+ * This data object configures the response of a fetch stub call.
+ */
+export interface ResponseData {
+  /** The HTTP status code. */
+  status: number;
+
+  /** The HTTP status text. */
+  statusText: string;
+
+  /** The optional response body. */
+  body?: Blob | object | string | null;
+}
+
+/**
+ * Create a fetch stub.
+ *
+ * The stub returns a response from the provided response data or throws an provided error.
+ *
+ * @param responses A single response or an array of responses.
+ * @returns The fetch stub.
+ */
+export function createFetchStub(
+  responses?: ResponseData | Error | (ResponseData | Error)[],
+): () => Promise<Response> {
+  const configurableResponses = ConfigurableResponses.create(responses);
+  return async function () {
+    const response = configurableResponses.next();
+    if (response instanceof Error) {
+      throw response;
+    }
+
+    return new ResponseStub(response) as unknown as Response;
+  };
+}
+
+class ResponseStub {
+  #status: number;
+  #statusText: string;
+  #body?: Blob | object | string | null;
+
+  constructor({ status, statusText, body = null }: ResponseData) {
+    this.#status = status;
+    this.#statusText = statusText;
+    this.#body = body;
+  }
+
+  get ok() {
+    return this.status >= 200 && this.status < 300;
+  }
+
+  get status() {
+    return this.#status;
+  }
+
+  get statusText() {
+    return this.#statusText;
+  }
+
+  async blob() {
+    if (this.#body == null) {
+      return null;
+    }
+
+    if (this.#body instanceof Blob) {
+      return this.#body;
+    }
+
+    throw new TypeError("Body is not a Blob.");
+  }
+
+  async json() {
+    const json =
+      typeof this.#body === "string" ? this.#body : JSON.stringify(this.#body);
+    return Promise.resolve(JSON.parse(json));
+  }
+
+  async text() {
+    if (this.#body == null) {
+      return "";
+    }
+
+    return String(this.#body);
+  }
+}

package/src/infrastructure/message_client.ts

@@ -0,0 +1,50 @@
+// Copyright (c) 2025 Falko Schumann. All rights reserved. MIT license.
+
+/**
+ * An interface for a streaming message client.
+ *
+ * Emits the following events:
+ *
+ * - open, {@link Event}
+ * - message, {@link MessageEvent}
+ * - error, {@link Event}
+ * - close, optional {@link CloseEvent}
+ *
+ * It is used for wrappers around {@link EventSource} and {@link WebSocket}.
+ *
+ * @see {@link SseClient}
+ * @see {@link WebSocketClient}
+ */
+export interface MessageClient extends EventTarget {
+  /**
+   * Return whether the client is connected.
+   */
+  get isConnected(): boolean;
+
+  /**
+   * Return the server URL.
+   */
+  get url(): string | undefined;
+
+  /**
+   * Connect to the server.
+   *
+   * @param url The server URL to connect to.
+   */
+  connect(url: string | URL): Promise<void>;
+
+  /**
+   * Send a message to the server.
+   *
+   * This is an optional method for streams with bidirectional communication.
+   *
+   * @param message The message to send.
+   * @param type The optional message type.
+   */
+  send(message: string, type?: string): Promise<void>;
+
+  /**
+   * Close the connection.
+   */
+  close(): Promise<void>;
+}

package/src/infrastructure/mod.ts

@@ -0,0 +1,7 @@
+// Copyright (c) 2025 Falko Schumann. All rights reserved. MIT license.
+
+export * from "./console_stub";
+export * from "./fetch_stub";
+export * from "./message_client";
+export * from "./sse_client";
+export * from "./web_socket_client";

package/src/infrastructure/sse_client.ts

@@ -0,0 +1,162 @@
+// Copyright (c) 2025 Falko Schumann. All rights reserved. MIT license.
+
+import type { MessageClient } from "./message_client";
+
+/**
+ * A client for the server-sent events protocol.
+ */
+export class SseClient extends EventTarget implements MessageClient {
+  /**
+   * Create an SSE client.
+   *
+   * @return A new SSE client.
+   */
+  static create(): SseClient {
+    return new SseClient(EventSource);
+  }
+
+  /**
+   * Create a nulled SSE client.
+   *
+   * @return A new SSE client.
+   */
+  static createNull(): SseClient {
+    return new SseClient(EventSourceStub as typeof EventSource);
+  }
+
+  readonly #eventSourceConstructor: typeof EventSource;
+
+  #eventSource?: EventSource;
+
+  private constructor(eventSourceConstructor: typeof EventSource) {
+    super();
+    this.#eventSourceConstructor = eventSourceConstructor;
+  }
+
+  get isConnected(): boolean {
+    return this.#eventSource?.readyState === this.#eventSourceConstructor.OPEN;
+  }
+
+  get url(): string | undefined {
+    return this.#eventSource?.url;
+  }
+
+  async connect(
+    url: string | URL,
+    eventName = "message",
+    ...otherEvents: string[]
+  ): Promise<void> {
+    await new Promise<void>((resolve, reject) => {
+      if (this.isConnected) {
+        reject(new Error("Already connected."));
+        return;
+      }
+
+      try {
+        this.#eventSource = new this.#eventSourceConstructor(url);
+        this.#eventSource.addEventListener("open", (e) => {
+          this.#handleOpen(e);
+          resolve();
+        });
+        this.#eventSource.addEventListener(eventName, (e) =>
+          this.#handleMessage(e),
+        );
+        for (const otherEvent of otherEvents) {
+          this.#eventSource.addEventListener(otherEvent, (e) =>
+            this.#handleMessage(e),
+          );
+        }
+        this.#eventSource.addEventListener("error", (e) =>
+          this.#handleError(e),
+        );
+      } catch (error) {
+        reject(error);
+      }
+    });
+  }
+
+  send(_message: string, _type?: string): Promise<void> {
+    throw new Error("Method not implemented.");
+  }
+
+  async close(): Promise<void> {
+    await new Promise<void>((resolve, reject) => {
+      if (!this.isConnected) {
+        resolve();
+        return;
+      }
+
+      try {
+        this.#eventSource!.close();
+        resolve();
+      } catch (error) {
+        reject(error);
+      }
+    });
+  }
+
+  /**
+   * Simulate a message event from the server.
+   *
+   * @param message The message to receive.
+   * @param eventName The optional event type.
+   * @param lastEventId The optional last event ID.
+   */
+  simulateMessage(
+    message: string | number | boolean | object | null,
+    eventName = "message",
+    lastEventId?: string,
+  ) {
+    if (typeof message !== "string") {
+      message = JSON.stringify(message);
+    }
+    this.#handleMessage(
+      new MessageEvent(eventName, { data: message, lastEventId }),
+    );
+  }
+
+  /**
+   * Simulate an error event.
+   */
+  simulateError() {
+    this.#handleError(new Event("error"));
+  }
+
+  #handleOpen(event: Event) {
+    this.dispatchEvent(new Event(event.type, event));
+  }
+
+  #handleMessage(event: MessageEvent) {
+    this.dispatchEvent(
+      new MessageEvent(event.type, event as unknown as MessageEventInit),
+    );
+  }
+
+  #handleError(event: Event) {
+    this.dispatchEvent(new Event(event.type, event));
+  }
+}
+
+class EventSourceStub extends EventTarget {
+  // The constants have to be defined here because Node.js support is currently
+  // experimental only.
+  static CONNECTING = 0;
+  static OPEN = 1;
+  static CLOSED = 2;
+
+  url: string;
+  readyState = EventSourceStub.CONNECTING;
+
+  constructor(url: string | URL) {
+    super();
+    this.url = url.toString();
+    setTimeout(() => {
+      this.readyState = EventSourceStub.OPEN;
+      this.dispatchEvent(new Event("open"));
+    }, 0);
+  }
+
+  close() {
+    this.readyState = EventSourceStub.CLOSED;
+  }
+}