@muspellheim/shared 0.17.0 → 0.18.1

package/dist/types/infrastructure/configurable_responses.d.ts

@@ -0,0 +1,58 @@
+/**
+ * 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 declare class ConfigurableResponses<T = unknown> {
+    #private;
+    /**
+     * 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): ConfigurableResponses<T>;
+    /**
+     * 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>;
+    /**
+     * 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);
+    /**
+     * 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;
+}

package/dist/types/infrastructure/console_log.d.ts

@@ -0,0 +1,34 @@
+import type { Log, LogLevel } from "../common/mod";
+import { OutputTracker } from "./output_tracker";
+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 declare class ConsoleLog extends EventTarget implements Log {
+    #private;
+    static create({ name }?: {
+        name?: string;
+    }): ConsoleLog;
+    static createNull({ name }?: {
+        name?: string;
+    }): ConsoleLog;
+    name?: string;
+    level: LogLevel;
+    private constructor();
+    log(...data: unknown[]): void;
+    error(...data: unknown[]): void;
+    warn(...data: unknown[]): void;
+    info(...data: unknown[]): void;
+    debug(...data: unknown[]): void;
+    trace(...data: unknown[]): void;
+    /**
+     * Track the console messages.
+     */
+    trackMessages(): OutputTracker<ConsoleMessage>;
+    isLoggable(level: LogLevel): boolean;
+}

package/dist/types/infrastructure/fetch_stub.d.ts

@@ -0,0 +1,20 @@
+/**
+ * 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 declare function createFetchStub(responses?: ResponseData | Error | (ResponseData | Error)[]): () => Promise<Response>;

package/dist/types/infrastructure/message_client.d.ts

@@ -0,0 +1,44 @@
+/**
+ * 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 → dist/types/infrastructure/mod.d.ts}

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

package/dist/types/infrastructure/output_tracker.d.ts

@@ -0,0 +1,60 @@
+/**
+ * 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 declare class OutputTracker<T = unknown> {
+    #private;
+    /**
+     * 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): OutputTracker<T>;
+    /**
+     * 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);
+    /**
+     * Return the tracked data.
+     *
+     * @return The tracked data.
+     */
+    get data(): T[];
+    /**
+     * Clear the tracked data and return the cleared data.
+     *
+     * @return The cleared data.
+     */
+    clear(): T[];
+    /**
+     * Stop tracking.
+     */
+    stop(): void;
+}

package/dist/types/infrastructure/sse_client.d.ts

@@ -0,0 +1,37 @@
+import type { MessageClient } from "./message_client";
+/**
+ * A client for the server-sent events protocol.
+ */
+export declare class SseClient extends EventTarget implements MessageClient {
+    #private;
+    /**
+     * Create an SSE client.
+     *
+     * @return A new SSE client.
+     */
+    static create(): SseClient;
+    /**
+     * Create a nulled SSE client.
+     *
+     * @return A new SSE client.
+     */
+    static createNull(): SseClient;
+    private constructor();
+    get isConnected(): boolean;
+    get url(): string | undefined;
+    connect(url: string | URL, eventName?: string, ...otherEvents: string[]): Promise<void>;
+    send(_message: string, _type?: string): Promise<void>;
+    close(): Promise<void>;
+    /**
+     * 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?: string, lastEventId?: string): void;
+    /**
+     * Simulate an error event.
+     */
+    simulateError(): void;
+}

package/dist/types/infrastructure/web_socket_client.d.ts

@@ -0,0 +1,79 @@
+import { OutputTracker } from "./output_tracker";
+import type { MessageClient } from "./message_client";
+export declare const HEARTBEAT_TYPE = "heartbeat";
+/**
+ * Options for the WebSocket client.
+ */
+export interface WebSocketOptions {
+    /**
+     * The heartbeat interval in milliseconds. A value <= 0 disables the
+     * heartbeat.
+     */
+    heartbeat?: number;
+    /**
+     * The time in milliseconds to wait before retrying a connection after an
+     * error. A value <= 0 disables automatic retries.
+     */
+    retry?: number;
+}
+/**
+ * A client for the WebSocket protocol.
+ */
+export declare class WebSocketClient extends EventTarget implements MessageClient {
+    #private;
+    /**
+     * Create a WebSocket client.
+     *
+     * @param options The options for the WebSocket client.
+     * @return A new WebSocket client.
+     */
+    static create({ heartbeat, retry, }?: WebSocketOptions): WebSocketClient;
+    /**
+     * Create a nulled WebSocket client.
+     *
+     * @param options The options for the WebSocket client.
+     * @return A new nulled WebSocket client.
+     */
+    static createNull({ heartbeat, retry }?: WebSocketOptions): WebSocketClient;
+    private constructor();
+    get isConnected(): boolean;
+    get url(): string | undefined;
+    connect(url: string | URL): Promise<void>;
+    send(message: string | ArrayBuffer | Blob | ArrayBufferView): Promise<void>;
+    /**
+     * Return a tracker for messages sent.
+     *
+     * @return A new output tracker.
+     */
+    trackMessageSent(): OutputTracker<string>;
+    /**
+     * Close the connection.
+     *
+     * If a code is provided, also a reason should be provided.
+     *
+     * @param code An optional code.
+     * @param reason An optional reason.
+     */
+    close(code?: number, reason?: string): Promise<void>;
+    /**
+     * Simulate a message event from the server.
+     *
+     * @param message The message to receive.
+     */
+    simulateMessage(message: string | number | boolean | object | null | Blob | ArrayBuffer): void;
+    /**
+     * Simulate a heartbeat.
+     */
+    simulateHeartbeat(): void;
+    /**
+     * Simulate a close event.
+     *
+     * @param code An optional code.
+     * @param reason An optional reason.
+     */
+    simulateClose(code?: number, reason?: string): void;
+    /**
+     * Simulate an error event.
+     */
+    simulateError(): void;
+}

package/{src/mod.ts → dist/types/mod.d.ts}

@@ -1,5 +1,3 @@
-// Copyright (c) 2025 Falko Schumann. All rights reserved. MIT license.
-
 export * from "./common/mod";
 export * from "./domain/mod";
 export * from "./infrastructure/mod";

package/package.json

@@ -1,43 +1,34 @@
 {
   "name": "@muspellheim/shared",
-  "version": "0.17.0",
+  "version": "0.18.1",
   "author": "Falko Schumann",
   "license": "MIT",
   "engines": {
-    "node": ">=20.0.0"
+    "node": ">=20.0.0",
+    "bun": ">=1.0.0"
   },
   "type": "module",
   "files": [
-    "dist",
-    "src"
+    "dist"
   ],
-  "main": "./dist/shared.umd.cjs",
-  "module": "./dist/shared.js",
-  "exports": {
-    ".": {
-      "types": "./dist/shared.d.ts",
-      "import": "./dist/shared.js",
-      "require": "./dist/shared.umd.cjs"
-    }
-  },
+  "main": "./dist/mod.cjs",
+  "module": "./dist/mod.js",
+  "types": "./dist/types/mod.d.ts",
   "scripts": {
-    "build": "vite build",
+    "build": "tsc --project tsconfig.build.json && bun build src/mod.ts --outdir=dist",
     "test": "vitest"
   },
   "devDependencies": {
     "@eslint/js": "9.39.2",
-    "@types/node": "20.19.28",
-    "@vitest/coverage-v8": "4.0.16",
+    "@softarc/sheriff-core": "0.19.6",
+    "@vitest/coverage-istanbul": "4.0.18",
     "eslint": "9.39.2",
     "eslint-plugin-headers": "1.3.3",
-    "jsdom": "27.4.0",
-    "globals": "17.0.0",
-    "prettier": "3.7.4",
+    "globals": "17.3.0",
+    "prettier": "3.8.1",
     "typedoc": "0.28.16",
     "typescript": "5.9.3",
-    "typescript-eslint": "8.52.0",
-    "vite": "7.3.1",
-    "vitest": "4.0.16",
-    "vite-plugin-dts": "4.5.4"
+    "typescript-eslint": "8.54.0",
+    "vitest": "4.0.18"
   }
 }