@wooksjs/ws-client 0.7.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 wooksjs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,46 @@
+# @wooksjs/ws-client
+
+<p align="center">
+<img src="../../wooks-logo.png" width="450px"><br>
+<a  href="https://github.com/wooksjs/wooksjs/blob/main/LICENSE">
+    <img src="https://img.shields.io/badge/License-MIT-green?style=for-the-badge" />
+</a>
+</p>
+
+WebSocket client for Wooks with RPC, subscriptions, reconnection, push listeners, and message queuing. Works in browsers and Node.js.
+
+## Installation
+
+```sh
+npm install @wooksjs/ws-client
+```
+
+## Documentation
+
+For full documentation, visit [wooks.moost.org](https://wooks.moost.org/wsapp/).
+
+## AI Agent Skills
+
+This package ships with structured skill files for AI coding agents (Claude Code, Cursor, Windsurf, Codex, etc.).
+
+```bash
+# Project-local (recommended — version-locked, commits with your repo)
+npx wooksjs-ws-client-skill
+
+# Global (available across all your projects)
+npx wooksjs-ws-client-skill --global
+```
+
+To keep skills automatically up-to-date, add a postinstall script to your `package.json`:
+
+```json
+{
+  "scripts": {
+    "postinstall": "wooksjs-ws-client-skill --postinstall"
+  }
+}
+```
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,409 @@
+
+//#region packages/ws-client/src/ws-client-error.ts
+/** Error from the WebSocket client (server error reply, timeout, or disconnect). */
+var WsClientError = class extends Error {
+	constructor(code, message) {
+		super(message ?? `WsClientError ${code}`);
+		this.code = code;
+		this.name = "WsClientError";
+	}
+};
+
+//#endregion
+//#region packages/ws-client/src/rpc-tracker.ts
+/** Tracks pending RPC calls by correlation ID. */
+var RpcTracker = class {
+	nextId = 1;
+	pending = /* @__PURE__ */ new Map();
+	/** Generate a new unique message ID. */
+	generateId() {
+		return this.nextId++;
+	}
+	/** Track a new pending RPC. Returns a promise that resolves/rejects based on the reply. */
+	track(id, timeout) {
+		return new Promise((resolve, reject) => {
+			const timer = setTimeout(() => {
+				this.pending.delete(id);
+				reject(new WsClientError(408, "RPC timeout"));
+			}, timeout);
+			this.pending.set(id, {
+				resolve,
+				reject,
+				timer
+			});
+		});
+	}
+	/** Resolve a pending RPC with a server reply. Returns true if an RPC was found. */
+	resolve(reply) {
+		const id = typeof reply.id === "number" ? reply.id : Number(reply.id);
+		const entry = this.pending.get(id);
+		if (!entry) return false;
+		clearTimeout(entry.timer);
+		this.pending.delete(id);
+		if (reply.error) entry.reject(new WsClientError(reply.error.code, reply.error.message));
+		else entry.resolve(reply.data);
+		return true;
+	}
+	/** Reject all pending RPCs (on disconnect or close). */
+	rejectAll(code, message) {
+		for (const [, entry] of this.pending) {
+			clearTimeout(entry.timer);
+			entry.reject(new WsClientError(code, message));
+		}
+		this.pending.clear();
+	}
+	/** Number of pending RPCs. */
+	get size() {
+		return this.pending.size;
+	}
+};
+
+//#endregion
+//#region packages/ws-client/src/push-dispatcher.ts
+/** Dispatches server push messages to registered client-side listeners. */
+var PushDispatcher = class {
+	/** Exact match: key = "event:path", value = set of handlers. */
+	exact = /* @__PURE__ */ new Map();
+	/** Wildcard listeners (path ends with "*"). */
+	wildcards = [];
+	/**
+	* Register a push listener. Returns an unregister function.
+	*
+	* - Exact path: `"/chat/rooms/lobby"` — O(1) Map lookup.
+	* - Wildcard: `"/chat/rooms/*"` — `startsWith` prefix check.
+	*/
+	on(event, pathPattern, handler) {
+		const h = handler;
+		if (pathPattern.endsWith("*")) {
+			const prefix = pathPattern.slice(0, -1);
+			const entry = {
+				event,
+				prefix,
+				handler: h
+			};
+			this.wildcards.push(entry);
+			return () => {
+				const idx = this.wildcards.indexOf(entry);
+				if (idx !== -1) this.wildcards.splice(idx, 1);
+			};
+		}
+		const key = `${event}:${pathPattern}`;
+		let set = this.exact.get(key);
+		if (!set) {
+			set = /* @__PURE__ */ new Set();
+			this.exact.set(key, set);
+		}
+		set.add(h);
+		return () => {
+			set.delete(h);
+			if (set.size === 0) this.exact.delete(key);
+		};
+	}
+	/** Dispatch a server push message to matching listeners. */
+	dispatch(msg) {
+		const pushEvent = {
+			event: msg.event,
+			path: msg.path,
+			params: msg.params ?? {},
+			data: msg.data
+		};
+		const key = `${msg.event}:${msg.path}`;
+		const exactSet = this.exact.get(key);
+		if (exactSet) for (const handler of exactSet) handler(pushEvent);
+		for (const { event, prefix, handler } of this.wildcards) if (msg.event === event && msg.path.startsWith(prefix)) handler(pushEvent);
+	}
+	/** Remove all listeners. */
+	clear() {
+		this.exact.clear();
+		this.wildcards.length = 0;
+	}
+};
+
+//#endregion
+//#region packages/ws-client/src/message-queue.ts
+/** Queue for outbound messages that accumulate while disconnected. */
+var MessageQueue = class {
+	queue = [];
+	/** Enqueue a serialized message. */
+	enqueue(serialized) {
+		this.queue.push(serialized);
+	}
+	/** Flush all queued messages via the provided send function. Returns number flushed. */
+	flush(send) {
+		const count = this.queue.length;
+		for (const msg of this.queue) send(msg);
+		this.queue.length = 0;
+		return count;
+	}
+	/** Discard all queued messages. */
+	clear() {
+		this.queue.length = 0;
+	}
+	/** Number of queued messages. */
+	get size() {
+		return this.queue.length;
+	}
+};
+
+//#endregion
+//#region packages/ws-client/src/reconnect.ts
+/** Normalize the user-facing reconnect option into a full config. */
+function normalizeReconnectConfig(opt) {
+	if (opt === true) return {
+		enabled: true,
+		maxRetries: Infinity,
+		baseDelay: 1e3,
+		maxDelay: 3e4,
+		backoff: "exponential"
+	};
+	if (opt === false || opt === void 0) return {
+		enabled: false,
+		maxRetries: 0,
+		baseDelay: 1e3,
+		maxDelay: 3e4,
+		backoff: "exponential"
+	};
+	return {
+		enabled: opt.enabled,
+		maxRetries: opt.maxRetries ?? Infinity,
+		baseDelay: opt.baseDelay ?? 1e3,
+		maxDelay: opt.maxDelay ?? 3e4,
+		backoff: opt.backoff ?? "exponential"
+	};
+}
+/** Manages reconnection state and backoff calculation. */
+var ReconnectController = class {
+	attempt = 0;
+	timer;
+	stopped = false;
+	constructor(config) {
+		this.config = config;
+	}
+	/** Whether reconnect is enabled and not manually stopped. */
+	get enabled() {
+		return this.config.enabled && !this.stopped;
+	}
+	/** Current attempt number. */
+	get currentAttempt() {
+		return this.attempt;
+	}
+	/** Schedule a reconnection attempt. Returns false if max retries exceeded or stopped. */
+	schedule(onReconnect) {
+		if (this.stopped) return false;
+		if (this.attempt >= this.config.maxRetries) return false;
+		const delay = this.getDelay();
+		this.attempt++;
+		this.timer = setTimeout(onReconnect, delay);
+		return true;
+	}
+	/** Reset attempt counter (called on successful connection). */
+	reset() {
+		this.attempt = 0;
+		this.cancelPending();
+	}
+	/** Permanently stop reconnection (called on explicit close()). */
+	stop() {
+		this.stopped = true;
+		this.cancelPending();
+	}
+	getDelay() {
+		const { baseDelay, maxDelay, backoff } = this.config;
+		const delay = backoff === "exponential" ? baseDelay * 2 ** this.attempt : baseDelay * (this.attempt + 1);
+		return Math.min(delay, maxDelay);
+	}
+	cancelPending() {
+		if (this.timer !== void 0) {
+			clearTimeout(this.timer);
+			this.timer = void 0;
+		}
+	}
+};
+
+//#endregion
+//#region packages/ws-client/src/ws-client.ts
+const DEFAULT_RPC_TIMEOUT = 1e4;
+function getWebSocketImpl(override) {
+	if (override) return override;
+	if (typeof WebSocket !== "undefined") return WebSocket;
+	throw new TypeError("@wooksjs/ws-client: No WebSocket implementation found. Install the \"ws\" package for Node.js < 22 or use a polyfill.");
+}
+/** WebSocket client with RPC, subscriptions, reconnection, and push listeners. */
+var WsClient = class {
+	ws = null;
+	url;
+	protocols;
+	rpcTimeout;
+	serializer;
+	parser;
+	WsImpl;
+	rpc;
+	dispatcher;
+	queue;
+	reconnector;
+	/** Active subscriptions for auto-resubscribe: path → data. */
+	subscriptions = /* @__PURE__ */ new Map();
+	openHandlers = [];
+	closeHandlers = [];
+	errorHandlers = [];
+	reconnectHandlers = [];
+	closed = false;
+	constructor(url, options) {
+		this.url = url;
+		this.protocols = options?.protocols;
+		this.rpcTimeout = options?.rpcTimeout ?? DEFAULT_RPC_TIMEOUT;
+		this.serializer = options?.messageSerializer ?? JSON.stringify;
+		this.parser = options?.messageParser ?? JSON.parse;
+		this.WsImpl = getWebSocketImpl(options?._WebSocket);
+		this.rpc = new RpcTracker();
+		this.dispatcher = new PushDispatcher();
+		this.queue = new MessageQueue();
+		this.reconnector = new ReconnectController(normalizeReconnectConfig(options?.reconnect));
+		this.connect();
+	}
+	/** Fire-and-forget. Queued when disconnected with reconnect enabled. */
+	send(event, path, data) {
+		const msg = {
+			event,
+			path
+		};
+		if (data !== void 0) msg.data = data;
+		const serialized = this.serializer(msg);
+		if (this.isOpen()) this.ws.send(serialized);
+		else if (this.reconnector.enabled) this.queue.enqueue(serialized);
+	}
+	/** RPC with auto-generated correlation ID. Rejects when not connected. */
+	call(event, path, data) {
+		if (!this.isOpen()) return Promise.reject(new WsClientError(503, "Not connected"));
+		const id = this.rpc.generateId();
+		const msg = {
+			event,
+			path,
+			id
+		};
+		if (data !== void 0) msg.data = data;
+		this.ws.send(this.serializer(msg));
+		return this.rpc.track(id, this.rpcTimeout);
+	}
+	/** Subscribe to a path. Returns an unsubscribe function. Auto-resubscribes on reconnect. */
+	async subscribe(path, data) {
+		await this.call("subscribe", path, data);
+		this.subscriptions.set(path, data);
+		return () => {
+			this.subscriptions.delete(path);
+			if (this.isOpen()) this.send("unsubscribe", path);
+		};
+	}
+	/** Register a client-side push listener. Returns an unregister function. */
+	on(event, pathPattern, handler) {
+		return this.dispatcher.on(event, pathPattern, handler);
+	}
+	/** Close the connection. Disables reconnect. Rejects pending RPCs. */
+	close() {
+		this.closed = true;
+		this.reconnector.stop();
+		this.rpc.rejectAll(503, "Connection closed");
+		this.queue.clear();
+		if (this.ws) {
+			this.ws.close(1e3, "Client closed");
+			this.ws = null;
+		}
+	}
+	/** Register a handler called when the WebSocket connection opens. Returns an unregister function. */
+	onOpen(handler) {
+		this.openHandlers.push(handler);
+		return () => {
+			const idx = this.openHandlers.indexOf(handler);
+			if (idx !== -1) this.openHandlers.splice(idx, 1);
+		};
+	}
+	/** Register a handler called when the WebSocket connection closes. Returns an unregister function. */
+	onClose(handler) {
+		this.closeHandlers.push(handler);
+		return () => {
+			const idx = this.closeHandlers.indexOf(handler);
+			if (idx !== -1) this.closeHandlers.splice(idx, 1);
+		};
+	}
+	/** Register a handler called on WebSocket errors. Returns an unregister function. */
+	onError(handler) {
+		this.errorHandlers.push(handler);
+		return () => {
+			const idx = this.errorHandlers.indexOf(handler);
+			if (idx !== -1) this.errorHandlers.splice(idx, 1);
+		};
+	}
+	/** Register a handler called before each reconnection attempt. Returns an unregister function. */
+	onReconnect(handler) {
+		this.reconnectHandlers.push(handler);
+		return () => {
+			const idx = this.reconnectHandlers.indexOf(handler);
+			if (idx !== -1) this.reconnectHandlers.splice(idx, 1);
+		};
+	}
+	isOpen() {
+		return this.ws !== null && this.ws.readyState === 1;
+	}
+	connect() {
+		if (this.closed) return;
+		const ws = new this.WsImpl(this.url, this.protocols);
+		this.ws = ws;
+		ws.addEventListener("open", () => {
+			this.reconnector.reset();
+			this.queue.flush((data) => ws.send(data));
+			this.resubscribe();
+			for (const h of this.openHandlers) h();
+		});
+		ws.addEventListener("close", (ev) => {
+			this.rpc.rejectAll(503, "Connection lost");
+			for (const h of this.closeHandlers) h(ev.code, ev.reason ?? "");
+			if (!this.closed && this.reconnector.enabled) this.reconnector.schedule(() => {
+				for (const h of this.reconnectHandlers) h(this.reconnector.currentAttempt);
+				this.connect();
+			});
+		});
+		ws.addEventListener("error", (ev) => {
+			for (const h of this.errorHandlers) h(ev);
+		});
+		ws.addEventListener("message", (ev) => {
+			this.handleMessage(ev.data);
+		});
+	}
+	handleMessage(raw) {
+		let msg;
+		try {
+			msg = this.parser(raw);
+		} catch {
+			return;
+		}
+		if ("id" in msg && msg.id !== void 0) {
+			this.rpc.resolve(msg);
+			return;
+		}
+		if ("event" in msg && "path" in msg) this.dispatcher.dispatch(msg);
+	}
+	resubscribe() {
+		for (const [path, data] of this.subscriptions) this.call("subscribe", path, data).catch(() => {});
+	}
+};
+/**
+* Creates a new WebSocket client.
+*
+* @example
+* ```ts
+* const client = createWsClient('wss://api.example.com', { reconnect: true })
+*
+* client.on('message', '/chat/*', ({ data }) => console.log(data))
+* await client.subscribe('/chat/rooms/lobby')
+* client.send('message', '/chat/rooms/lobby', { text: 'hello' })
+*
+* const me = await client.call('rpc', '/users/me')
+* ```
+*/
+function createWsClient(url, options) {
+	return new WsClient(url, options);
+}
+
+//#endregion
+exports.WsClient = WsClient;
+exports.WsClientError = WsClientError;
+exports.createWsClient = createWsClient;

package/dist/index.d.ts

@@ -0,0 +1,144 @@
+/** Client-to-server message. */
+interface WsClientMessage {
+    /** Event type — used as the router method on the server. */
+    event: string;
+    /** Route path (always concrete, never a pattern). */
+    path: string;
+    /** Payload. */
+    data?: unknown;
+    /** Correlation ID. When present, the server sends a reply with the same ID. */
+    id?: number;
+}
+/** Server-to-client reply (sent only when the client message included an `id`). */
+interface WsReplyMessage {
+    /** Correlation ID matching the client's request. */
+    id: string | number;
+    /** Response payload. */
+    data?: unknown;
+    /** Error (mutually exclusive with data). */
+    error?: {
+        code: number;
+        message: string;
+    };
+}
+/** Server-to-client push (broadcast, direct send, subscription notification). */
+interface WsPushMessage {
+    /** Event type. */
+    event: string;
+    /** The concrete path this message relates to. */
+    path: string;
+    /** Route params extracted by the server router. */
+    params?: Record<string, string>;
+    /** Payload. */
+    data?: unknown;
+}
+/** Reconnection behaviour configuration for the WebSocket client. */
+interface WsClientReconnectOptions {
+    /** Whether reconnection is enabled. */
+    enabled: boolean;
+    /** Max reconnection attempts (default: Infinity). */
+    maxRetries?: number;
+    /** Base delay in ms (default: 1000). */
+    baseDelay?: number;
+    /** Max delay in ms (default: 30000). */
+    maxDelay?: number;
+    /** Backoff strategy (default: "exponential"). */
+    backoff?: 'linear' | 'exponential';
+}
+/** Options for {@link WsClient} / {@link createWsClient}. */
+interface WsClientOptions {
+    /** Protocols passed to the WebSocket constructor. */
+    protocols?: string | string[];
+    /** Reconnection config. */
+    reconnect?: boolean | WsClientReconnectOptions;
+    /** Timeout for RPC calls in ms (default: 10000). */
+    rpcTimeout?: number;
+    /** Custom message parser. Default: JSON.parse. */
+    messageParser?: (raw: string) => WsReplyMessage | WsPushMessage;
+    /** Custom message serializer. Default: JSON.stringify. */
+    messageSerializer?: (msg: WsClientMessage) => string;
+    /** @internal For testing only — override the WebSocket constructor. */
+    _WebSocket?: new (url: string, protocols?: string | string[]) => WebSocket;
+}
+/** Payload shape received by `client.on()` handlers. */
+interface WsClientPushEvent<T = unknown> {
+    /** Event type from server. */
+    event: string;
+    /** Concrete path from server. */
+    path: string;
+    /** Route params extracted by the server. */
+    params: Record<string, string>;
+    /** Payload. */
+    data: T;
+}
+/** Push message handler. */
+type WsPushHandler<T = unknown> = (ev: WsClientPushEvent<T>) => void;
+
+/** WebSocket client with RPC, subscriptions, reconnection, and push listeners. */
+declare class WsClient {
+    private ws;
+    private readonly url;
+    private readonly protocols;
+    private readonly rpcTimeout;
+    private readonly serializer;
+    private readonly parser;
+    private readonly WsImpl;
+    private readonly rpc;
+    private readonly dispatcher;
+    private readonly queue;
+    private readonly reconnector;
+    /** Active subscriptions for auto-resubscribe: path → data. */
+    private readonly subscriptions;
+    private readonly openHandlers;
+    private readonly closeHandlers;
+    private readonly errorHandlers;
+    private readonly reconnectHandlers;
+    private closed;
+    constructor(url: string, options?: WsClientOptions);
+    /** Fire-and-forget. Queued when disconnected with reconnect enabled. */
+    send(event: string, path: string, data?: unknown): void;
+    /** RPC with auto-generated correlation ID. Rejects when not connected. */
+    call<T = unknown>(event: string, path: string, data?: unknown): Promise<T>;
+    /** Subscribe to a path. Returns an unsubscribe function. Auto-resubscribes on reconnect. */
+    subscribe(path: string, data?: unknown): Promise<() => void>;
+    /** Register a client-side push listener. Returns an unregister function. */
+    on<T = unknown>(event: string, pathPattern: string, handler: WsPushHandler<T>): () => void;
+    /** Close the connection. Disables reconnect. Rejects pending RPCs. */
+    close(): void;
+    /** Register a handler called when the WebSocket connection opens. Returns an unregister function. */
+    onOpen(handler: () => void): () => void;
+    /** Register a handler called when the WebSocket connection closes. Returns an unregister function. */
+    onClose(handler: (code: number, reason: string) => void): () => void;
+    /** Register a handler called on WebSocket errors. Returns an unregister function. */
+    onError(handler: (error: Event) => void): () => void;
+    /** Register a handler called before each reconnection attempt. Returns an unregister function. */
+    onReconnect(handler: (attempt: number) => void): () => void;
+    private isOpen;
+    private connect;
+    private handleMessage;
+    private resubscribe;
+}
+/**
+ * Creates a new WebSocket client.
+ *
+ * @example
+ * ```ts
+ * const client = createWsClient('wss://api.example.com', { reconnect: true })
+ *
+ * client.on('message', '/chat/*', ({ data }) => console.log(data))
+ * await client.subscribe('/chat/rooms/lobby')
+ * client.send('message', '/chat/rooms/lobby', { text: 'hello' })
+ *
+ * const me = await client.call('rpc', '/users/me')
+ * ```
+ */
+declare function createWsClient(url: string, options?: WsClientOptions): WsClient;
+
+/** Error from the WebSocket client (server error reply, timeout, or disconnect). */
+declare class WsClientError extends Error {
+    readonly code: number;
+    constructor(code: number, message?: string);
+}
+
+export { WsClient, WsClientError, createWsClient };
+export type { WsClientMessage, WsClientOptions, WsClientPushEvent, WsClientReconnectOptions, WsPushHandler, WsPushMessage, WsReplyMessage };