@vielzeug/pulse 1.0.3

package/dist/types.d.ts

@@ -0,0 +1,243 @@
+import type { Readable } from '@vielzeug/ripple';
+/** A read-only view of a Map — callers cannot mutate the entries. */
+export type ReadonlyMap<K, V> = Omit<Map<K, V>, 'clear' | 'delete' | 'set'>;
+/** A map of event name → payload type. Use as the generic parameter for Pulse. */
+export type MessageMap = Record<string, unknown>;
+/** Extract valid event keys from a MessageMap. */
+export type EventKey<T extends MessageMap> = keyof T & string;
+/** A function that removes a listener subscription. */
+export type Unsubscribe = () => void;
+/** Lifecycle state of a Pulse connection. */
+export type PulseStatus = 'connecting' | 'open' | 'reconnecting' | 'closed';
+export type ReconnectOptions = {
+    /**
+     * Delay strategy between reconnect attempts (ms).
+     * - number: fixed delay
+     * - function: `attempt` is zero-based (0 = waiting before 2nd try).
+     * Defaults to full-jitter exponential backoff capped at 30 s.
+     */
+    delay?: number | ((attempt: number) => number);
+    /** Maximum number of reconnect attempts after initial failure. Default: 5. */
+    maxAttempts?: number;
+};
+export type HeartbeatOptions = {
+    /** Interval between pings in ms. Default: 30_000. */
+    interval?: number;
+    /** How long to wait for a pong before treating the connection as dead. Default: 5_000. */
+    timeout?: number;
+};
+/**
+ * Intercepts outgoing messages. Call `next()` to allow the message to be sent;
+ * omit to suppress it.
+ */
+export type Middleware = (event: string, payload: unknown, next: () => void) => void;
+export type BufferOptions = {
+    /**
+     * Maximum number of outgoing frames to buffer while disconnected.
+     * Oldest frames are evicted when the buffer is full. Default: 50.
+     */
+    maxSize?: number;
+};
+export type PulseOptions = {
+    /**
+     * Buffer outgoing messages while the connection is not open, then flush on
+     * reconnect. `true` uses defaults (`maxSize: 50`). `false` disables (default).
+     * Dropped messages are discarded with a dev warning when buffering is off.
+     */
+    buffer?: boolean | BufferOptions;
+    /**
+     * Heartbeat ping/pong keep-alive.
+     * `true` uses defaults. `false` disables. Default: `false`.
+     */
+    heartbeat?: boolean | HeartbeatOptions;
+    /**
+     * Defer the initial WebSocket connection until `connect()` is called explicitly.
+     * Default: `false` (connects immediately on creation).
+     */
+    lazy?: boolean;
+    /**
+     * Middleware functions run on every outgoing `send()`, before the message is
+     * written to the socket. Call `next()` to proceed or omit to suppress.
+     */
+    middleware?: readonly Middleware[];
+    /** Called when the connection is closed by either side. */
+    onClose?: (code: number, reason: string) => void;
+    /**
+     * Called on a WebSocket error event. Note: WebSocket errors almost always
+     * precede a close event — use `onClose` for recovery logic.
+     */
+    onError?: (error: Error) => void;
+    /**
+     * Called with every raw `MessageEvent` before any parsing occurs.
+     * Useful for low-level debugging.
+     */
+    onMessage?: (event: MessageEvent) => void;
+    /** Called when the connection is established (or re-established). */
+    onOpen?: () => void;
+    /**
+     * Called at the start of each reconnect attempt.
+     * `attempt` is 1-based (1 = first retry).
+     */
+    onReconnect?: (attempt: number) => void;
+    /** Sub-protocols to pass to the WebSocket constructor. */
+    protocols?: string | string[];
+    /**
+     * Auto-reconnect on unexpected close.
+     * `true` uses defaults. `false` disables. Default: `false`.
+     */
+    reconnect?: boolean | ReconnectOptions;
+};
+/**
+ * An isolated message namespace multiplexed over the shared WebSocket connection.
+ * Obtain one via `pulse.channel(name)`. Multiple calls with the same name return
+ * the **same** channel object — dispose it once to fully remove the subscription.
+ *
+ * @example
+ * const notif = pulse.channel<{ alert: string }>('notifications');
+ * notif.on('alert', (msg) => console.log(msg));
+ * notif.send('alert', 'Hello!');
+ */
+export type PulseChannel<TServer extends MessageMap = MessageMap, TClient extends MessageMap = MessageMap> = {
+    /** Delegates to `dispose()`. Enables `using` declarations. */
+    [Symbol.dispose](): void;
+    /** `AbortSignal` aborted when `dispose()` is called. */
+    readonly disposalSignal: AbortSignal;
+    /** Permanently unsubscribes all listeners and prevents future sends. */
+    dispose(): void;
+    /** Whether this channel has been disposed. */
+    readonly disposed: boolean;
+    /** Channel name passed to `pulse.channel()`. */
+    readonly name: string;
+    /**
+     * Subscribe to a server event scoped to this channel.
+     * Returns an unsubscribe function. The handler is auto-removed on `dispose()`.
+     */
+    on<K extends EventKey<TServer>>(event: K, handler: (payload: TServer[K]) => void): Unsubscribe;
+    /** Subscribe once — auto-removes after first invocation. */
+    once<K extends EventKey<TServer>>(event: K, handler: (payload: TServer[K]) => void): Unsubscribe;
+    /**
+     * Send a typed message to the server, scoped to this channel.
+     * No-op if the pulse connection is not open and buffering is disabled.
+     */
+    send<K extends EventKey<TClient>>(event: K, payload: TClient[K]): void;
+    /**
+     * Resolve on the next emission of the given server event.
+     * Rejects when the signal aborts, the timeout elapses, or the channel is disposed.
+     */
+    wait<K extends EventKey<TServer>>(event: K, opts?: {
+        signal?: AbortSignal;
+        timeout?: number;
+    }): Promise<TServer[K]>;
+};
+/**
+ * A reactive presence channel that tracks members' state in a room.
+ * Obtain one via `pulse.presence(room)`.
+ *
+ * @example
+ * const lobby = pulse.presence<{ name: string; status: string }>('lobby');
+ * effect(() => console.log('Online:', [...lobby.state.value.keys()]));
+ * lobby.update({ name: 'Alice', status: 'online' });
+ */
+export type PresenceChannel<T = unknown> = {
+    /** Delegates to `dispose()`. Enables `using` declarations. */
+    [Symbol.dispose](): void;
+    /** `AbortSignal` aborted when `dispose()` is called. */
+    readonly disposalSignal: AbortSignal;
+    /** Permanently stops tracking. Sends a leave frame to the server. */
+    dispose(): void;
+    /** Whether this presence channel has been disposed. */
+    readonly disposed: boolean;
+    /**
+     * Register a handler called whenever a new member joins with their initial state.
+     * Returns an unsubscribe function.
+     */
+    onJoin(handler: (memberId: string, state: T) => void): Unsubscribe;
+    /**
+     * Register a handler called whenever a member leaves.
+     * Returns an unsubscribe function.
+     */
+    onLeave(handler: (memberId: string) => void): Unsubscribe;
+    /** Room name passed to `pulse.presence()`. */
+    readonly room: string;
+    /** Reactive map of `memberId → state`. Updates whenever any member joins, leaves, or updates. */
+    readonly state: Readable<ReadonlyMap<string, T>>;
+    /**
+     * Broadcast this client's presence state to all room members.
+     * Calling this also implicitly joins the room if not already joined.
+     */
+    update(state: T): void;
+};
+export type Pulse<TServer extends MessageMap = MessageMap, TClient extends MessageMap = MessageMap> = {
+    /** Delegates to `dispose()`. Enables `using` declarations. */
+    [Symbol.dispose](): void;
+    /**
+     * Return an isolated message namespace over the shared connection.
+     * Multiple calls with the same name return the **same** channel object —
+     * dispose it once to remove the subscription.
+     */
+    channel<TChServer extends MessageMap = TServer, TChClient extends MessageMap = TClient>(name: string): PulseChannel<TChServer, TChClient>;
+    /**
+     * Explicitly open the connection. Resolves when `'open'` fires.
+     * Required when `lazy: true`; otherwise called automatically on creation.
+     * Rejects if the connection closes before opening.
+     */
+    connect(): Promise<void>;
+    /**
+     * Close the connection without triggering reconnection.
+     * @param code WebSocket close code (default: 1000).
+     * @param reason Human-readable close reason string.
+     */
+    disconnect(code?: number, reason?: string): void;
+    /** `AbortSignal` aborted when `dispose()` is called. */
+    readonly disposalSignal: AbortSignal;
+    /** Permanently closes the connection and releases all resources. Idempotent. */
+    dispose(): void;
+    /** Whether the instance has been permanently disposed. */
+    readonly disposed: boolean;
+    /**
+     * Request to join a room. Resolves when the server confirms with a `joined` frame.
+     * Rejects if the pulse is disposed, the signal aborts, or the timeout elapses.
+     */
+    join(room: string, opts?: {
+        signal?: AbortSignal;
+        timeout?: number;
+    }): Promise<void>;
+    /**
+     * Request to leave a room. Resolves when the server confirms with a `left` frame.
+     * Rejects if the pulse is disposed, the signal aborts, or the timeout elapses.
+     */
+    leave(room: string, opts?: {
+        signal?: AbortSignal;
+        timeout?: number;
+    }): Promise<void>;
+    /**
+     * Subscribe to a typed server event. Returns an unsubscribe function.
+     * The same handler can be registered multiple times independently.
+     */
+    on<K extends EventKey<TServer>>(event: K, handler: (payload: TServer[K]) => void): Unsubscribe;
+    /** Subscribe once — auto-removes after first invocation. */
+    once<K extends EventKey<TServer>>(event: K, handler: (payload: TServer[K]) => void): Unsubscribe;
+    /**
+     * Return a presence channel that tracks all members' state in a room.
+     * Calling `presence()` implicitly joins the room.
+     */
+    presence<T>(room: string): PresenceChannel<T>;
+    /** Reactive set of rooms the client is currently a member of. */
+    readonly rooms: Readable<ReadonlySet<string>>;
+    /**
+     * Send a typed event to the server. If buffering is enabled, the message is
+     * queued when the connection is not open and flushed on reconnect.
+     */
+    send<K extends EventKey<TClient>>(event: K, payload: TClient[K]): void;
+    /** Reactive connection status. */
+    readonly status: Readable<PulseStatus>;
+    /**
+     * Resolve on the next emission of the given server event.
+     * Rejects when `opts.signal` aborts or the instance is disposed.
+     */
+    wait<K extends EventKey<TServer>>(event: K, opts?: {
+        signal?: AbortSignal;
+        timeout?: number;
+    }): Promise<TServer[K]>;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@vielzeug/pulse",
+  "version": "1.0.3",
+  "description": "Typed WebSocket client with channel multiplexing, presence tracking, auto-reconnect, and heartbeat",
+  "type": "module",
+  "files": [
+    "dist"
+  ],
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "scripts": {
+    "build": "vite build && pnpm run build:bundle && pnpm run build:types",
+    "build:bundle": "vite build --config vite.bundle.config.ts",
+    "build:types": "tsc -p tsconfig.declarations.json",
+    "fix": "eslint --fix src",
+    "lint": "eslint src",
+    "prepublishOnly": "pnpm run build",
+    "preview": "vite preview",
+    "test": "vitest"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "dependencies": {
+    "@vielzeug/ripple": "workspace:*"
+  },
+  "devDependencies": {
+    "@types/node": "^26.1.0",
+    "typescript": "~6.0.3",
+    "vite": "^8.1.3",
+    "vitest": "^4.1.9"
+  }
+}