@nhtio/swarm 1.20250425.0 → 1.20260111.0

package/index.d.ts

@@ -1,14 +1,342 @@
-/**
- * The module which contains types and utilities for using the library.
- * @module @nhtio/swarm
- */
-/**
- * The current version of the package.
- */
-export declare const version: string;
-export * as types from './types';
-export * as errors from './errors';
-export { setLogLevel } from './lib/logger';
-export { Swarm } from './lib/class_swarm';
-export { Secret } from '@nhtio/web-encryption';
-export { setPSK } from './lib/encryption';
+/**
+ * Thrown by the {@link @nhtio/swarm!Swarm | Swarm} class when trying to be initialize more than one instance within the same context.
+ */
+declare class AlreadyInitializedInContextError extends SwarmError {
+    constructor();
+}
+
+/**
+ * The module which contains types for the library.
+ * @module @nhtio/swarm/types
+ */
+/**
+ * An inteface which describes the information about the browser and operating system
+ */
+declare interface BrowserInfo {
+    /**
+     * The name of the browser
+     */
+    browserName: string;
+    /**
+     * The version of the browser
+     */
+    browserVersion: string;
+    /**
+     * The name of the operating system
+     */
+    osName: string;
+    /**
+     * The version of the operating system
+     */
+    osVersion: string;
+    /**
+     * The type of platform i.e. desktop / mobile
+     */
+    platformType: string;
+    /**
+     * The name of the browser engine
+     */
+    engineName: string;
+    /**
+     * The version of the browser engine
+     */
+    engineVersion: string;
+}
+
+export declare namespace errors {
+    export {
+        AlreadyInitializedInContextError,
+        MissingEncryptionKey,
+        RequestTimeoutError,
+        SwarmError,
+        SwarmErrorOptions,
+        UnsupportedEnvironmentError
+    }
+}
+
+declare type LogLevel = keyof typeof LogLevelStyles;
+
+declare const LogLevelStyles: {
+    EMERG: (text: string) => string[];
+    ALERT: (text: string) => string[];
+    CRIT: (text: string) => string[];
+    ERROR: (text: string) => string[];
+    WARNING: (text: string) => string[];
+    NOTICE: (text: string) => string[];
+    INFO: (text: string) => string[];
+    DEBUG: (text: string) => string[];
+};
+
+/**
+ * Thrown by the {@link @nhtio/swarm!Swarm | Swarm} class trying to retrieve an instance without having previously or currently provided an encryption key.
+ */
+declare class MissingEncryptionKey extends SwarmError {
+    constructor();
+}
+
+declare type RequestHandlerMap<Events extends TypedEventMap> = {
+    [K in keyof Events]: (...args: Events[K]) => any;
+};
+
+/**
+ * Thrown by the {@link @nhtio/swarm!Swarm | Swarm} class when a request to the leader is not answered.
+ */
+declare class RequestTimeoutError extends SwarmError {
+    constructor(event: string | number | symbol);
+}
+
+/**
+ * Define a Secret value that hides itself from the logs or the console
+ * statements.
+ *
+ * The idea is to prevent accidental leaking of sensitive information.
+ * Idea borrowed from.
+ * https://transcend.io/blog/keep-sensitive-values-out-of-your-logs-with-types
+ */
+export declare class Secret<T> {
+    #private;
+    constructor(value: T, redactedKeyword?: string);
+    toJSON(): string;
+    valueOf(): string;
+    toLocaleString(): string;
+    toString(): string;
+    /**
+     * Returns the original value
+     */
+    release(): T;
+    /**
+     * Transform the original value and create a new
+     * secret from it.
+     */
+    map<R>(transformFunc: (value: T) => R): Secret<R>;
+}
+
+/**
+ * Sets the log level for the logger.
+ * @param level - The log level to set. Can be one of the following:
+ * - `EMERG` or `emerg`
+ * - `ALERT` or `alert`
+ * - `CRIT` or `crit`
+ * - `ERROR` or `error`
+ * - `WARNING` or `warning`
+ * - `NOTICE` or `notice`
+ * - `INFO` or `info`
+ * - `DEBUG` or `debug`
+ *
+ * @remarks You can also set `window.SWARM_LOG_LEVEL` or `globalThis.SWARM_LOG_LEVEL` to the same values to set the log level globally before initializing any of the Swarm modules.
+ */
+export declare const setLogLevel: (level: LogLevel) => void;
+
+/**
+ * Set the pre-shared key used to ensure that any data shared between nodes in the swarm is encrypted and namespaced.
+ * @param secret The pre-shared key to use
+ * @returns
+ */
+export declare const setPSK: (secret: string | Secret<string>) => void;
+
+/**
+ * The class that provides peer communication between browser tabs and service workers
+ * @typeParam Events - The map of events and their arguments that can be emitted and listened to.
+ */
+export declare class Swarm<Events extends TypedEventMap = TypedEventMap> extends TypedEventEmitter<Events> {
+    #private;
+    private static readonly INTERNAL_HEARTBEAT;
+    private static readonly INTERNAL_OBITUARY;
+    /** @private */
+    constructor(secret?: string | Secret<string>);
+    /**
+     * The ID of the current instance.
+     */
+    get id(): string;
+    /**
+     * Whether this instance is the leader or not.
+     */
+    get leader(): boolean;
+    /**
+     * Emit an event to all connected peers.
+     * @param event - The name of the event to emit.
+     * @param args - The arguments to pass to the event listeners.
+     * @typeParam E - The name of the event to emit.
+     */
+    emit<E extends keyof Events>(event: E, ...args: Events[E]): this;
+    /**
+     * Subscribe to the leadership change event.
+     * @param cb - The callback function to be called when the leadership status changes.
+     */
+    onLeadershipChange(cb: (is: boolean) => void): this;
+    /**
+     * Remove the leadership change event listener.
+     * @param cb - The callback function to be removed from the leadership change event.
+     */
+    offLeadershipChange(cb: (is: boolean) => void): this;
+    /**
+     * Subscribe to the next occurance of a leadership change event.
+     * @param cb - The callback function to be called when the leadership status changes.
+     */
+    onceLeadershipChange(cb: (is: boolean) => void): this;
+    /**
+     * Collect responses from all peers for a specific event.
+     * @param event The name of the event to collect responses for.
+     * @param args The arguments which will be passed to the event handler.
+     * @returns A promise that resolves with an array of responses from all peers.
+     * @typeParam R - The type of the response.
+     * @typeParam E - The name of the event to collect responses for.
+     */
+    collect<R, E extends keyof Events = keyof Events>(event: E, ...args: Events[E]): Promise<R[]>;
+    /**
+     * Register a handler for a specific event which will respond to incoming messages which require a general response
+     * @param event The name of the event to listen for.
+     * @param handler The function to call when the event is emitted.
+     * @typeParam E - The name of the event to listen for.
+     */
+    onCollect<E extends keyof Events>(event: E, handler: (...args: Events[E]) => ReturnType<RequestHandlerMap<Events>[E]>): this;
+    /**
+     * De-register a handler for a specific event which will respond to incoming messages which require a general response
+     * @param event The name of the event to listen for.
+     * @param handler The function to call when the event is emitted.
+     * @typeParam E - The name of the event to listen for.
+     */
+    offCollect<E extends keyof Events>(event: E): this;
+    /**
+     * Request feedback from the leader for a specific event.
+     * @param event The name of the event to request feedback for.
+     * @param args The arguments to pass to the event handler.
+     * @returns A promise that resolves with the response from the event handler.
+     * @typeParam R - The type of the response.
+     * @typeParam E - The name of the event to request feedback for.
+     */
+    request<R = any, E extends keyof Events = keyof Events>(event: E, ...args: Events[E]): Promise<R>;
+    /**
+     * Register a handler for a specific event which will respond to incoming messages which require a response from the leader
+     * @param event The name of the event to listen for.
+     * @param handler The function to call when the event is emitted.
+     * @typeParam E - The name of the event to listen for.
+     */
+    onRequest<E extends keyof Events>(event: E, handler: (...args: Events[E]) => ReturnType<RequestHandlerMap<Events>[E]>): this;
+    /**
+     * De-register a handler for a specific event which will respond to incoming messages which require a response from the leader
+     * @param event The name of the event to listen for.
+     * @param handler The function to call when the event is emitted.
+     * @typeParam E - The name of the event to listen for.
+     */
+    offRequest<E extends keyof Events>(event: E): this;
+    /**
+     * Set the timeout for waiting for a response from `request()` or `collect()`.
+     * @param timeout The timeout in milliseconds to wait for a response.
+     * @returns The current instance of the Swarm class for the current context.
+     */
+    setAwaitResponseTimeout(timeout: number): this;
+    /**
+     * Retreive the current instance of the Swarm class for the current context.
+     * @typeParam Events - The map of events and their arguments that can be emitted and listened to.
+     * @returns The current instance of the Swarm class for the current context.
+     */
+    static instance<Events extends TypedEventMap = TypedEventMap>(secret?: string | Secret<string>): Swarm<Events>;
+}
+
+/**
+ * Base class for all Swarm errors.
+ * @extends Error
+ */
+declare class SwarmError extends Error {
+    /** @private */
+    readonly $__name: string;
+    /** @private */
+    readonly $__message: string;
+    /**
+     * Creates a new SwarmError instance.
+     * @param message The error message.
+     * @param options The error options.
+     */
+    constructor(message: string, options?: SwarmErrorOptions);
+    get name(): string;
+    get message(): string;
+    get [Symbol.toStringTag](): string;
+    toString(): string;
+    [Symbol.toPrimitive](hint: 'number' | 'string' | 'default'): string | true;
+    static [Symbol.hasInstance](instance: unknown): boolean;
+}
+
+/**
+ * Easily accessible error classes for Swarm
+ * @module @nhtio/swarm/errors
+ */
+/**
+ * Describes the options for the SwarmError class.
+ */
+declare interface SwarmErrorOptions {
+    /**
+     * The cause data property of an Error instance indicates the specific original cause of the error.
+     */
+    cause?: Error;
+    /**
+     * How many rows to trim from the stack trace.
+     * This is useful for removing the stack trace of the current function from the error.
+     */
+    trim?: number;
+}
+
+declare class TinyEmitter {
+    on(event: string, callback: Function, ctx?: any): this;
+    once(event: string, callback: Function, ctx?: any): this;
+    emit(event: string, ...args: any[]): this;
+    off(event: string, callback?: Function): this;
+}
+
+/**
+ * A strongly-typed Tiny Event Emitter.
+ *
+ * @template Events
+ *   key = event name,
+ *   value = tuple type of that event’s arguments
+ */
+declare class TypedEventEmitter<Events extends TypedEventMap = TypedEventMap> extends TinyEmitter {
+    /**
+     * Subscribe to an event with a typed listener.
+     */
+    on<E extends keyof Events>(event: E, listener: (...args: Events[E]) => void, ctx?: any): this;
+    /**
+     * Subscribe once to an event.
+     */
+    once<E extends keyof Events>(event: E, listener: (...args: Events[E]) => void, ctx?: any): this;
+    /**
+     * Emit an event, enforcing that the args match Events[E].
+     */
+    emit<E extends keyof Events>(event: E, ...args: Events[E]): this;
+    /**
+     * Remove a listener.
+     */
+    off<E extends keyof Events>(event: E, listener?: (...args: Events[E]) => void): this;
+}
+
+/**
+ * A map from event-names to the tuple of arguments
+ * that listeners for that event will receive.
+ */
+declare interface TypedEventMap {
+    [event: string]: any[];
+}
+
+export declare namespace types {
+    export {
+        BrowserInfo,
+        TypedEventMap,
+        RequestHandlerMap,
+        LogLevel,
+        LogLevelStyles
+    }
+}
+
+/**
+ * Thrown by the {@link @nhtio/swarm!Swarm | Swarm} class when trying to be initialized in an environment that does not support Service Workers.
+ */
+declare class UnsupportedEnvironmentError extends SwarmError {
+    constructor();
+}
+
+/**
+ * The current version of the package.
+ */
+export declare const version: string;
+
+export { }