@muspellheim/shared 0.18.1 → 0.19.1

package/src/infrastructure/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,
+  ): Record<string, ConfigurableResponses> {
+    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/infrastructure/console_log.ts

@@ -0,0 +1,160 @@
+// Copyright (c) 2026 Falko Schumann. All rights reserved. MIT license.
+
+import type { Log, LogLevel } from "../common/mod";
+import { OutputTracker } from "./output_tracker";
+
+const MESSAGE_EVENT = "message";
+
+export interface ConsoleMessage {
+  level: LogLevel;
+  message: unknown[];
+}
+
+/**
+ * Wraps the console interface and allow setting the log level.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/Console_API
+ */
+export class ConsoleLog extends EventTarget implements Log {
+  static create({ name }: { name?: string } = {}) {
+    return new ConsoleLog(globalThis.console, name);
+  }
+
+  static createNull({ name }: { name?: string } = {}) {
+    return new ConsoleLog(new ConsoleStub(), name);
+  }
+
+  name?: string;
+  level: LogLevel = "info";
+
+  #console;
+
+  private constructor(console: Log, name?: string) {
+    super();
+    this.name = name;
+    this.#console = console;
+  }
+
+  log(...data: unknown[]) {
+    if (!this.isLoggable("log")) {
+      return;
+    }
+
+    data = this.#applyName(data);
+    this.#console.log(...data);
+    this.dispatchEvent(
+      new CustomEvent(MESSAGE_EVENT, {
+        detail: { level: "log", message: data },
+      }),
+    );
+  }
+
+  error(...data: unknown[]) {
+    if (!this.isLoggable("error")) {
+      return;
+    }
+
+    data = this.#applyName(data);
+    this.#console.error(...data);
+    this.dispatchEvent(
+      new CustomEvent(MESSAGE_EVENT, {
+        detail: { level: "error", message: data },
+      }),
+    );
+  }
+
+  warn(...data: unknown[]) {
+    if (!this.isLoggable("warn")) {
+      return;
+    }
+
+    data = this.#applyName(data);
+    this.#console.warn(...data);
+    this.dispatchEvent(
+      new CustomEvent(MESSAGE_EVENT, {
+        detail: { level: "warn", message: data },
+      }),
+    );
+  }
+
+  info(...data: unknown[]) {
+    if (!this.isLoggable("info")) {
+      return;
+    }
+
+    data = this.#applyName(data);
+    this.#console.info(...data);
+    this.dispatchEvent(
+      new CustomEvent(MESSAGE_EVENT, {
+        detail: { level: "info", message: data },
+      }),
+    );
+  }
+
+  debug(...data: unknown[]) {
+    if (!this.isLoggable("debug")) {
+      return;
+    }
+
+    data = this.#applyName(data);
+    this.#console.debug(...data);
+    this.dispatchEvent(
+      new CustomEvent(MESSAGE_EVENT, {
+        detail: { level: "debug", message: data },
+      }),
+    );
+  }
+
+  trace(...data: unknown[]) {
+    if (!this.isLoggable("trace")) {
+      return;
+    }
+
+    data = this.#applyName(data);
+    this.#console.trace(...data);
+    this.dispatchEvent(
+      new CustomEvent(MESSAGE_EVENT, {
+        detail: { level: "trace", message: data },
+      }),
+    );
+  }
+
+  /**
+   * Track the console messages.
+   */
+  trackMessages() {
+    return new OutputTracker<ConsoleMessage>(this, MESSAGE_EVENT);
+  }
+
+  isLoggable(level: LogLevel) {
+    const normalize = (level: LogLevel) => (level === "log" ? "info" : level);
+    const levels: LogLevel[] = [
+      "off",
+      "error",
+      "warn",
+      "info",
+      "debug",
+      "trace",
+    ];
+    const currentLevelIndex = levels.indexOf(normalize(this.level));
+    const messageLevelIndex = levels.indexOf(normalize(level));
+    return messageLevelIndex <= currentLevelIndex;
+  }
+
+  #applyName(data: unknown[]) {
+    if (this.name == null) {
+      return data;
+    }
+
+    return [`${this.name}`, ...data];
+  }
+}
+
+class ConsoleStub implements Log {
+  log(..._data: unknown[]) {}
+  error(..._data: unknown[]) {}
+  warn(..._data: unknown[]) {}
+  info(..._data: unknown[]) {}
+  debug(..._data: unknown[]) {}
+  trace(..._data: unknown[]) {}
+}

package/src/infrastructure/fetch_stub.ts

@@ -0,0 +1,51 @@
+// Copyright (c) 2025 Falko Schumann. All rights reserved. MIT license.
+
+import { ConfigurableResponses } from "./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?: BodyInit | object;
+}
+
+/**
+ * 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;
+    }
+
+    let body = response?.body;
+    if (
+      body != null &&
+      !(body instanceof Blob) &&
+      !(typeof body === "string")
+    ) {
+      // If the body is an object, we convert it to a JSON string.
+      body = JSON.stringify(body);
+    }
+    return new Response(body, {
+      status: response.status,
+      statusText: response.statusText,
+    });
+  };
+}

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,9 @@
+// Copyright (c) 2025 Falko Schumann. All rights reserved. MIT license.
+
+export * from "./configurable_responses";
+export * from "./console_log";
+export * from "./fetch_stub";
+export * from "./message_client";
+export * from "./output_tracker";
+export * from "./sse_client";
+export * from "./web_socket_client";

package/src/infrastructure/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/infrastructure/sse_client.ts

@@ -0,0 +1,161 @@
+// 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);
+      }
+    });
+  }
+
+  async send(_message: string, _type?: string): Promise<void> {
+    throw new Error("unsupported method");
+  }
+
+  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") {
+      // If the message is not a string, we convert it to a JSON 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 {
+  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;
+  }
+}