@wooksjs/ws-client 0.7.0

package/dist/index.mjs

@@ -0,0 +1,406 @@
+//#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
+export { WsClient, WsClientError, createWsClient };

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@wooksjs/ws-client",
+  "version": "0.7.0",
+  "description": "WebSocket client for Wooks with RPC, subscriptions, reconnection, and push listeners",
+  "keywords": [
+    "client",
+    "realtime",
+    "rpc",
+    "websocket",
+    "wooks",
+    "ws"
+  ],
+  "homepage": "https://github.com/wooksjs/wooksjs/tree/main/packages/ws-client#readme",
+  "bugs": {
+    "url": "https://github.com/wooksjs/wooksjs/issues"
+  },
+  "license": "MIT",
+  "author": "Artem Maltsev",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wooksjs/wooksjs.git",
+    "directory": "packages/ws-client"
+  },
+  "bin": {
+    "wooksjs-ws-client-skill": "./scripts/setup-skills.js"
+  },
+  "files": [
+    "dist",
+    "skills",
+    "scripts/setup-skills.js"
+  ],
+  "main": "dist/index.cjs",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./dist/index.d.ts",
+      "require": "./dist/index.cjs",
+      "import": "./dist/index.mjs"
+    }
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.4"
+  },
+  "peerDependencies": {
+    "ws": "^8.0.0"
+  },
+  "peerDependenciesMeta": {
+    "ws": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "build": "rolldown -c ../../rolldown.config.mjs",
+    "setup-skills": "node ./scripts/setup-skills.js"
+  }
+}

package/scripts/setup-skills.js

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+/* prettier-ignore */
+import fs from 'fs'
+import path from 'path'
+import os from 'os'
+import { fileURLToPath } from 'url'
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+
+const SKILL_NAME = 'wooksjs-ws-client'
+const SKILL_SRC = path.join(__dirname, '..', 'skills', SKILL_NAME)
+
+if (!fs.existsSync(SKILL_SRC)) {
+  console.error(`No skills found at ${SKILL_SRC}`)
+  console.error('Add your SKILL.md files to the skills/' + SKILL_NAME + '/ directory first.')
+  process.exit(1)
+}
+
+const AGENTS = {
+  'Claude Code': { dir: '.claude/skills',   global: path.join(os.homedir(), '.claude', 'skills') },
+  'Cursor':      { dir: '.cursor/skills',   global: path.join(os.homedir(), '.cursor', 'skills') },
+  'Windsurf':    { dir: '.windsurf/skills', global: path.join(os.homedir(), '.windsurf', 'skills') },
+  'Codex':       { dir: '.codex/skills',    global: path.join(os.homedir(), '.codex', 'skills') },
+  'OpenCode':    { dir: '.opencode/skills', global: path.join(os.homedir(), '.opencode', 'skills') },
+}
+
+const args = process.argv.slice(2)
+const isGlobal = args.includes('--global') || args.includes('-g')
+const isPostinstall = args.includes('--postinstall')
+let installed = 0, skipped = 0
+const installedDirs = []
+
+for (const [agentName, cfg] of Object.entries(AGENTS)) {
+  const targetBase = isGlobal ? cfg.global : path.join(process.cwd(), cfg.dir)
+  const agentRootDir = path.dirname(cfg.global) // Check if the agent has ever been installed globally
+
+  // In postinstall mode: silently skip agents that aren't set up globally
+  if (isPostinstall || isGlobal) {
+    if (!fs.existsSync(agentRootDir)) { skipped++; continue }
+  }
+
+  const dest = path.join(targetBase, SKILL_NAME)
+  try {
+    fs.mkdirSync(dest, { recursive: true })
+    fs.cpSync(SKILL_SRC, dest, { recursive: true })
+    console.log(`✅  ${agentName}: installed to ${dest}`)
+    installed++
+    if (!isGlobal) installedDirs.push(cfg.dir + '/' + SKILL_NAME)
+  } catch (err) {
+    console.warn(`⚠️   ${agentName}: failed — ${err.message}`)
+  }
+}
+
+// Add locally-installed skill dirs to .gitignore
+if (!isGlobal && installedDirs.length > 0) {
+  const gitignorePath = path.join(process.cwd(), '.gitignore')
+  let gitignoreContent = ''
+  try { gitignoreContent = fs.readFileSync(gitignorePath, 'utf8') } catch {}
+  const linesToAdd = installedDirs.filter(d => !gitignoreContent.includes(d))
+  if (linesToAdd.length > 0) {
+    const hasHeader = gitignoreContent.includes('# AI agent skills')
+    const block = (gitignoreContent && !gitignoreContent.endsWith('\n') ? '\n' : '')
+      + (hasHeader ? '' : '\n# AI agent skills (auto-generated by setup-skills)\n')
+      + linesToAdd.join('\n') + '\n'
+    fs.appendFileSync(gitignorePath, block)
+    console.log(`📝  Added ${linesToAdd.length} entries to .gitignore`)
+  }
+}
+
+if (installed === 0 && isPostinstall) {
+  // Silence is fine — no agents present, nothing to do
+} else if (installed === 0 && skipped === Object.keys(AGENTS).length) {
+  console.log('No agent directories detected. Try --global or run without it for project-local install.')
+} else if (installed === 0) {
+  console.log('Nothing installed. Run without --global to install project-locally.')
+} else {
+  console.log(`\n✨  Done! Restart your AI agent to pick up the "${SKILL_NAME}" skill.`)
+}

package/skills/wooksjs-ws-client/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: wooksjs-ws-client
+description: Use this skill when working with @wooksjs/ws-client — to create a WebSocket client with createWsClient() or WsClient, send fire-and-forget messages with send(), make RPC calls with call(), subscribe to server paths with subscribe(), listen for push messages with on(), handle reconnection with WsClientReconnectOptions, manage lifecycle events with onOpen()/onClose()/onError()/onReconnect(), use WsClientError for error handling, or configure custom serializers and protocols. Covers the wire protocol (WsClientMessage, WsReplyMessage, WsPushMessage), message queuing during disconnect, and auto-resubscription.
+---
+
+# @wooksjs/ws-client
+
+WebSocket client for Wooks with RPC, subscriptions, reconnection, push listeners, and message queuing — works in browsers and Node.js.
+
+## How to use this skill
+
+Read the domain file that matches the task. Do not load all files — only what you need.
+
+| Domain                | File                         | Load when...                                                                                          |
+| --------------------- | ---------------------------- | ----------------------------------------------------------------------------------------------------- |
+| Core concepts & setup | [core.md](core.md)           | Creating a client, understanding the wire protocol, configuring options, sending messages             |
+| RPC & subscriptions   | [rpc.md](rpc.md)             | Making RPC calls with `call()`, subscribing to paths with `subscribe()`, handling timeouts and errors |
+| Push listeners        | [push.md](push.md)           | Listening for server push messages with `on()`, exact and wildcard matching, dispatching              |
+| Reconnection          | [reconnect.md](reconnect.md) | Configuring auto-reconnect, backoff strategies, message queuing, auto-resubscription                  |
+
+## Quick reference
+
+```ts
+import { createWsClient, WsClient, WsClientError } from '@wooksjs/ws-client'
+
+import type {
+  WsClientOptions,
+  WsClientReconnectOptions,
+  WsClientMessage,
+  WsReplyMessage,
+  WsPushMessage,
+  WsClientPushEvent,
+  WsPushHandler,
+} from '@wooksjs/ws-client'
+```