@classytic/arc-next 0.4.1 → 0.5.0

package/dist/ws.js

@@ -0,0 +1,274 @@
+"use client";
+
+import { buildStreamUrl } from "./client.js";
+import { useQueryClient } from "@tanstack/react-query";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+
+//#region src/ws.ts
+/**
+* Build an authenticated WebSocket URL using the global client + auth singletons.
+*
+* Thin alias for {@link import('./client.js').buildStreamUrl} with the WS
+* protocol — rewrites `http(s)://` → `ws(s)://` and attaches the same auth
+* params SSE uses, so the two transports stay in lock-step.
+*
+* @example
+* const socket = new WebSocket(buildWsUrl('/ws'));
+*/
+function buildWsUrl(path = "/ws", params = {}) {
+	return buildStreamUrl(path, params, "ws");
+}
+/**
+* Connect to an Arc WebSocket channel from any JS context (React, Node, Bun, tests).
+* Pure function — no React hook required. Returns a handle with `send()`,
+* `subscribe()`, `on()`, `close()`, `reconnect()`, `isConnected()`.
+*
+* Reconnect uses exponential backoff (×1.5 per attempt, capped at 30s).
+* Subscriptions persist across reconnect.
+*
+* @example
+* const ws = connectWs<CrudEvent<Todo>>({
+*   subscribe: ['todo'],
+*   onMessage: (m) => console.log(m.type, m.data),
+* });
+*
+* const off = ws.on('todo.created', (m) => console.log('new todo:', m.data));
+* // ...later
+* off();
+* ws.close();
+*/
+function connectWs(options = {}) {
+	const { url, path = "/ws", reconnectDelay = 3e3, maxReconnectAttempts = Infinity, heartbeatInterval = 0, protocols, patterns = [] } = options;
+	let ws = null;
+	let reconnectAttempts = 0;
+	let reconnectTimer = null;
+	let heartbeatTimer = null;
+	let manualClose = false;
+	let connected = false;
+	const subscriptions = new Set(options.subscribe ?? []);
+	const listeners = /* @__PURE__ */ new Map();
+	const matchesPattern = (type) => {
+		if (patterns.length === 0) return true;
+		return patterns.some((p) => p.endsWith(".") ? type.startsWith(p) : type === p);
+	};
+	const sendRaw = (payload) => {
+		if (!ws || ws.readyState !== WebSocket.OPEN) return false;
+		try {
+			ws.send(typeof payload === "string" ? payload : JSON.stringify(payload));
+			return true;
+		} catch {
+			return false;
+		}
+	};
+	const dispatch = (message) => {
+		if (!matchesPattern(message.type)) return;
+		options.onMessage?.(message);
+		const exact = listeners.get(message.type);
+		if (exact) for (const fn of exact) fn(message);
+		const wildcard = listeners.get("*");
+		if (wildcard) for (const fn of wildcard) fn(message);
+	};
+	const connect = () => {
+		if (ws) try {
+			ws.close();
+		} catch {}
+		if (heartbeatTimer) {
+			clearInterval(heartbeatTimer);
+			heartbeatTimer = null;
+		}
+		manualClose = false;
+		const wsUrl = url ?? buildWsUrl(path);
+		ws = protocols !== void 0 ? new WebSocket(wsUrl, protocols) : new WebSocket(wsUrl);
+		ws.onopen = () => {
+			reconnectAttempts = 0;
+			connected = true;
+			options.onConnectionChange?.(true);
+			for (const resource of subscriptions) sendRaw({
+				type: "subscribe",
+				resource
+			});
+			if (heartbeatInterval > 0) heartbeatTimer = setInterval(() => {
+				sendRaw({ type: "ping" });
+			}, heartbeatInterval);
+		};
+		ws.onmessage = (event) => {
+			let parsed;
+			try {
+				parsed = JSON.parse(typeof event.data === "string" ? event.data : String(event.data));
+			} catch {
+				parsed = {
+					type: "message",
+					data: event.data
+				};
+			}
+			dispatch(parsed);
+		};
+		ws.onerror = () => {};
+		ws.onclose = () => {
+			connected = false;
+			options.onConnectionChange?.(false);
+			if (heartbeatTimer) {
+				clearInterval(heartbeatTimer);
+				heartbeatTimer = null;
+			}
+			if (manualClose) return;
+			if (reconnectAttempts < maxReconnectAttempts) {
+				reconnectAttempts += 1;
+				const delay = Math.min(reconnectDelay * Math.pow(1.5, reconnectAttempts - 1), 3e4);
+				reconnectTimer = setTimeout(connect, delay);
+			}
+		};
+	};
+	connect();
+	return {
+		isConnected: () => connected,
+		send: sendRaw,
+		subscribe: (resource) => {
+			subscriptions.add(resource);
+			if (ws?.readyState === WebSocket.OPEN) sendRaw({
+				type: "subscribe",
+				resource
+			});
+		},
+		unsubscribe: (resource) => {
+			subscriptions.delete(resource);
+			if (ws?.readyState === WebSocket.OPEN) sendRaw({
+				type: "unsubscribe",
+				resource
+			});
+		},
+		on: (eventType, handler) => {
+			let bucket = listeners.get(eventType);
+			if (!bucket) {
+				bucket = /* @__PURE__ */ new Set();
+				listeners.set(eventType, bucket);
+			}
+			bucket.add(handler);
+			return () => {
+				bucket?.delete(handler);
+				if (bucket && bucket.size === 0) listeners.delete(eventType);
+			};
+		},
+		close: () => {
+			manualClose = true;
+			if (reconnectTimer) {
+				clearTimeout(reconnectTimer);
+				reconnectTimer = null;
+			}
+			if (heartbeatTimer) {
+				clearInterval(heartbeatTimer);
+				heartbeatTimer = null;
+			}
+			if (ws) {
+				try {
+					ws.close();
+				} catch {}
+				ws = null;
+			}
+			connected = false;
+			options.onConnectionChange?.(false);
+		},
+		reconnect: () => {
+			reconnectAttempts = 0;
+			manualClose = false;
+			connect();
+		}
+	};
+}
+/**
+* Connect to an Arc WebSocket channel with auto-reconnect, subscription
+* persistence, and TanStack Query invalidation on inbound messages.
+*
+* Internally delegates to {@link connectWs} — for non-React contexts (Node,
+* tests, plain JS) call that directly.
+*
+* @example
+* const { isConnected, lastMessage } = useWebSocket<CrudEvent<Todo>>({
+*   subscribe: ['todo'],
+*   invalidateQueries: [todoKeys.lists()],
+* });
+*/
+function useWebSocket(options) {
+	const { url, path = "/ws", enabled = true, trackLastMessage = true, trackMessageCount = true } = options;
+	const queryClient = useQueryClient();
+	const [isConnected, setIsConnected] = useState(false);
+	const [lastMessage, setLastMessage] = useState(null);
+	const [messageCount, setMessageCount] = useState(0);
+	const handleRef = useRef(null);
+	const onMessageRef = useRef(options.onMessage);
+	onMessageRef.current = options.onMessage;
+	const onConnectionChangeRef = useRef(options.onConnectionChange);
+	onConnectionChangeRef.current = options.onConnectionChange;
+	const invalidateKeysRef = useRef(options.invalidateQueries ?? []);
+	invalidateKeysRef.current = options.invalidateQueries ?? [];
+	const subscribeKey = JSON.stringify(options.subscribe ?? []);
+	const patternsKey = JSON.stringify(options.patterns ?? null);
+	const subscribeArr = useMemo(() => options.subscribe ?? [], [subscribeKey]);
+	const patternsArr = useMemo(() => options.patterns, [patternsKey]);
+	useEffect(() => {
+		if (!enabled) {
+			handleRef.current?.close();
+			handleRef.current = null;
+			return;
+		}
+		const handle = connectWs({
+			url,
+			path,
+			subscribe: subscribeArr,
+			patterns: patternsArr,
+			reconnectDelay: options.reconnectDelay,
+			maxReconnectAttempts: options.maxReconnectAttempts,
+			heartbeatInterval: options.heartbeatInterval,
+			protocols: options.protocols,
+			onConnectionChange: (c) => {
+				setIsConnected(c);
+				onConnectionChangeRef.current?.(c);
+			},
+			onMessage: (msg) => {
+				if (trackLastMessage) setLastMessage(msg);
+				if (trackMessageCount) setMessageCount((n) => n + 1);
+				onMessageRef.current?.(msg);
+				for (const key of invalidateKeysRef.current) queryClient.invalidateQueries({ queryKey: key });
+			}
+		});
+		handleRef.current = handle;
+		return () => {
+			handle.close();
+			handleRef.current = null;
+		};
+	}, [
+		enabled,
+		url,
+		path,
+		subscribeArr,
+		patternsArr,
+		options.reconnectDelay,
+		options.maxReconnectAttempts,
+		options.heartbeatInterval,
+		options.protocols,
+		trackLastMessage,
+		trackMessageCount,
+		queryClient
+	]);
+	const subscribe = useCallback((resource) => {
+		handleRef.current?.subscribe(resource);
+	}, []);
+	const unsubscribe = useCallback((resource) => {
+		handleRef.current?.unsubscribe(resource);
+	}, []);
+	return {
+		isConnected,
+		lastMessage,
+		messageCount,
+		send: useCallback((payload) => {
+			return handleRef.current?.send(payload) ?? false;
+		}, []),
+		subscribe,
+		unsubscribe,
+		close: useCallback(() => handleRef.current?.close(), []),
+		reconnect: useCallback(() => handleRef.current?.reconnect(), [])
+	};
+}
+
+//#endregion
+export { buildWsUrl, connectWs, useWebSocket };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classytic/arc-next",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "description": "React + TanStack Query SDK for Arc resources",
   "type": "module",
   "sideEffects": false,
@@ -42,6 +42,10 @@
       "types": "./dist/api.d.ts",
       "default": "./dist/api.js"
     },
+    "./cache": {
+      "types": "./dist/cache.d.ts",
+      "default": "./dist/cache.js"
+    },
     "./query": {
       "types": "./dist/query.d.ts",
       "default": "./dist/query.js"
@@ -66,6 +70,34 @@
       "types": "./dist/sse.d.ts",
       "default": "./dist/sse.js"
     },
+    "./ws": {
+      "types": "./dist/ws.d.ts",
+      "default": "./dist/ws.js"
+    },
+    "./upload": {
+      "types": "./dist/upload.d.ts",
+      "default": "./dist/upload.js"
+    },
+    "./presets/soft-delete": {
+      "types": "./dist/presets/soft-delete.d.ts",
+      "default": "./dist/presets/soft-delete.js"
+    },
+    "./presets/bulk": {
+      "types": "./dist/presets/bulk.d.ts",
+      "default": "./dist/presets/bulk.js"
+    },
+    "./presets/slug": {
+      "types": "./dist/presets/slug.d.ts",
+      "default": "./dist/presets/slug.js"
+    },
+    "./presets/tree": {
+      "types": "./dist/presets/tree.d.ts",
+      "default": "./dist/presets/tree.js"
+    },
+    "./presets/search": {
+      "types": "./dist/presets/search.d.ts",
+      "default": "./dist/presets/search.js"
+    },
     "./package.json": "./package.json"
   },
   "files": [
@@ -84,6 +116,9 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "typecheck": "tsc --noEmit",
+    "push": "classytic-push",
+    "release:tag": "node -e \"require('child_process').execSync('npm run push -- v'+require('./package.json').version,{stdio:'inherit'})\"",
+    "release": "npm run push -- main && npm run release:tag && npm publish",
     "prepublishOnly": "npm run typecheck && npm test && npm run build"
   },
   "peerDependencies": {
@@ -91,6 +126,7 @@
     "react": ">=19.0.0"
   },
   "devDependencies": {
+    "@classytic/dev-tools": "^0.2.0",
     "@tanstack/react-query": "^5.97.0",
     "@testing-library/jest-dom": "^6.9.1",
     "@testing-library/react": "^16.3.2",