@muspellheim/shared 0.6.1 → 0.7.0

package/LICENSE.txt

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2023-2024 Falko Schumann
+Copyright (c) 2025 Falko Schumann
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -3,32 +3,30 @@
 [![Build](https://github.com/falkoschumann/muspellheim-utils-javascript/actions/workflows/build.yml/badge.svg)](https://github.com/falkoschumann/muspellheim-utils-javascript/actions/workflows/build.yml)
 [![NPM Version](https://img.shields.io/npm/v/%40muspellheim%2Fshared)](https://www.npmjs.com/package/@muspellheim/shared)
 
-Some shared modules for the browser and Node from my projects.
+Some shared modules from my projects.
 
 ## Installation
 
-    npm install @muspellheim/shared
+```bash
+npm install @muspellheim/shared
+```
 
 ## Usage
 
-    import { XXX } from '@muspellheim/shared';
-    import { XXX } from '@muspellheim/shared/browser';
-    import { XXX } from '@muspellheim/shared/node';
+```typescript
+import { ConfigurableResponses, OutputTracker } from "@muspellheim/shared";
+```
 
-See https://falkoschumann.github.io/muspellheim-shared-javascript/
+See more at https://falkoschumann.github.io/muspellheim-shared-js/
 
 ## Contributing
 
-The `Makefile` runs the build as default task. Other tasks are
+The `Makefile` runs the build as the default task. Other tasks are
 
 - `test`: run all tests,
 - `format`: format source code
 
 ## Credits
 
-## Open issues
-
-- [ ] Add missing docs
-- [ ] Use asserts for parameters
-- [ ] Rename project to `muspellheim-shared-js`
-- [ ] Use equatable protocol for value objects
+- [Testing Without Mocks](https://www.jamesshore.com/v2/projects/nullables/testing-without-mocks),
+  Copyright 2023 Titanium I.T. LLC. MIT License.

package/dist/shared.d.ts

@@ -0,0 +1,423 @@
+/**
+ * A clock provides access to the current timestamp.
+ */
+export declare class Clock {
+    #private;
+    /**
+     * Creates a clock using system the clock.
+     *
+     * @return A clock that uses the system clock.
+     */
+    static system(): Clock;
+    /**
+     * Creates 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;
+    /**
+     * Creates 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;
+    private constructor();
+    /**
+     * Returns the current timestamp of the clock.
+     *
+     * @return The current timestamp.
+     */
+    date(): Date;
+    /**
+     * Returns the current timestamp of the clock in milliseconds.
+     *
+     * @return The current timestamp in milliseconds.
+     */
+    millis(): number;
+}
+
+/**
+ * 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 declare type CommandStatus = Success | Failure;
+
+/**
+ * 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> {
+    #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): any;
+    /**
+     * 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;
+}
+
+/**
+ * A stub for the console interface.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/Console_API
+ */
+export declare class ConsoleStub extends EventTarget {
+    log(...data: unknown[]): void;
+    error(...data: unknown[]): void;
+    warn(...data: unknown[]): void;
+    info(...data: unknown[]): void;
+    debug(...data: unknown[]): void;
+    trace(...data: unknown[]): void;
+    /**
+     * Tracks console messages.
+     */
+    trackMessages(): OutputTracker<unknown>;
+}
+
+/**
+ * Creates 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>;
+
+/**
+ * A failed status.
+ */
+export declare class Failure {
+    readonly isSuccess = false;
+    errorMessage: string;
+    /**
+     * Creates a failed status.
+     *
+     * @param errorMessage
+     */
+    constructor(errorMessage: string);
+}
+
+export declare const HEARTBEAT_TYPE = "heartbeat";
+
+/**
+ * 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 declare 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;
+}
+
+/**
+ * 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 declare interface MessageClient extends EventTarget {
+    /**
+     * Returns whether the client is connected.
+     */
+    get isConnected(): boolean;
+    /**
+     * Returns the server URL.
+     */
+    get url(): string | undefined;
+    /**
+     * Connects to the server.
+     *
+     * @param url The server URL to connect to.
+     */
+    connect(url: string | URL): Promise<void>;
+    /**
+     * Sends 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>;
+    /**
+     * Closes the connection.
+     */
+    close(): Promise<void>;
+}
+
+/**
+ * Tracks 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> {
+    #private;
+    /**
+     * Creates 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>;
+    /**
+     * Creates 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);
+    /**
+     * Returns the tracked data.
+     *
+     * @return The tracked data.
+     */
+    get data(): T[];
+    /**
+     * Clears the tracked data and returns the cleared data.
+     *
+     * @return The cleared data.
+     */
+    clear(): T[];
+    /**
+     * Stops tracking.
+     */
+    stop(): void;
+}
+
+/**
+ * This data object configures the response of a fetch stub call.
+ */
+export declare interface ResponseData {
+    /** The HTTP status code. */
+    status: number;
+    /** The HTTP status text. */
+    statusText: string;
+    /** The optional response body. */
+    body?: Blob | object | string | null;
+}
+
+/**
+ * A client for the server-sent events protocol.
+ */
+export declare class SseClient extends EventTarget implements MessageClient {
+    #private;
+    /**
+     * Creates an SSE client.
+     *
+     * @return A new SSE client.
+     */
+    static create(): SseClient;
+    /**
+     * Creates 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): Promise<void>;
+    send(_message: string, _type?: string): Promise<void>;
+    close(): Promise<void>;
+    /**
+     * Simulates 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, eventName?: string, lastEventId?: string): void;
+    /**
+     * Simulates an error event.
+     */
+    simulateError(): void;
+}
+
+/**
+ * A successful status.
+ */
+export declare class Success {
+    readonly isSuccess = true;
+}
+
+/**
+ * A client for the WebSocket protocol.
+ */
+export declare class WebSocketClient extends EventTarget implements MessageClient {
+    #private;
+    /**
+     * Creates a WebSocket client.
+     *
+     * @param options The options for the WebSocket client.
+     * @return A new WebSocket client.
+     */
+    static create({ heartbeat }?: WebSocketOptions): WebSocketClient;
+    /**
+     * Creates a nulled WebSocket client.
+     *
+     * @param options The options for the WebSocket client.
+     * @return A new nulled WebSocket client.
+     */
+    static createNull({ heartbeat }?: WebSocketOptions): WebSocketClient;
+    private constructor();
+    get isConnected(): boolean;
+    get url(): string | undefined;
+    connect(url: string | URL): Promise<void>;
+    send(message: string): Promise<void>;
+    /**
+     * Returns a tracker for messages sent.
+     *
+     * @return A new output tracker.
+     */
+    trackMessageSent(): OutputTracker<string>;
+    /**
+     * Closes 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>;
+    /**
+     * Simulates a message event from the server.
+     *
+     * @param message The message to receive.
+     */
+    simulateMessage(message: string): void;
+    /**
+     * Simulates a heartbeat.
+     */
+    simulateHeartbeat(): void;
+    /**
+     * Simulates a close event.
+     *
+     * @param code An optional code.
+     * @param reason An optional reason.
+     */
+    simulateClose(code?: number, reason?: string): void;
+    /**
+     * Simulates an error event.
+     */
+    simulateError(): void;
+}
+
+/**
+ * Options for the WebSocket client.
+ */
+export declare interface WebSocketOptions {
+    /**
+     * The heartbeat interval in milliseconds. A value <= 0 disables the
+     * heartbeat.
+     */
+    heartbeat?: number;
+}
+
+export { }