spark-html-websocket 0.1.0

package/README.md

@@ -0,0 +1,73 @@
+# ⚡ spark-html-websocket
+
+Declarative WebSocket for [spark-html](https://www.npmjs.com/package/spark-html)
+— a live connection as a **reactive store**, with auto-reconnect, JSON
+parsing, status, and `send()`. Zero dependencies. No more hand-rolled
+connect/reconnect/parse/cleanup boilerplate in `onMount`.
+
+```js
+import { ws } from 'spark-html-websocket';
+ws('wss://stream.example.com/prices', { name: 'prices' });
+```
+
+```html
+<!-- any component -->
+<p :hidden="prices.status !== 'open'">● live</p>
+<h1>{prices.data?.btc}</h1>
+<button onclick="{() => prices.send({ subscribe: 'btc' })}">Subscribe</button>
+<script>
+  const prices = useStore('prices');
+</script>
+```
+
+Or fully declarative, the way the router declares routes:
+
+```html
+<template ws="wss://stream.example.com/prices" store="prices"></template>
+<script type="module">
+  import { sockets } from 'spark-html-websocket';
+  sockets();
+</script>
+```
+
+## Install
+
+```bash
+npm install spark-html-websocket
+```
+
+## The store
+
+| Key | Meaning |
+|-----|---------|
+| `data` | The last (post-filter) message — JSON-parsed when it looks like JSON. Survives reconnects. |
+| `status` | `'connecting'` · `'open'` · `'closed'` · `'error'` |
+| `error` | The last connection error, `null` when healthy. |
+| `send(v)` | Send a message; objects are stringified. Queued until the socket opens. |
+| `close()` | Deliberate close — never reconnects. |
+| `open()` | Re-open after a `close()` (or exhausted retries). |
+
+## Options
+
+```js
+ws('wss://x.dev/feed', {
+  name: 'feed',                          // store name (default "ws:x.dev/feed")
+  json: true,                            // parse messages as JSON when possible
+  filter: (d) => d.type === 'ticker',    // only these land in `data`
+  onMessage: (d) => { store('candles').list.push(d); }, // feed ANY store
+  reconnect: { retries: Infinity, base: 500, max: 10000 }, // backoff (ms); false disables
+  protocols: ['v1'],
+});
+```
+
+- **Auto-reconnect** — a dropped connection retries with exponential backoff
+  (`base·2ⁿ` capped at `max`); `data` keeps rendering through the gap.
+- **Shared handles** — `ws()` with the same name returns the existing store;
+  two components never open two sockets.
+- **Prerender-safe** — during `spark-prerender` builds (or anywhere
+  `WebSocket` doesn't exist) the store is created inert with
+  `status: 'closed'`, so components render their fallback and the build never
+  hangs. No guard needed.
+
+Declarative attributes: `ws` (url), `store` (name), `raw` (skip JSON),
+`retries` / `backoff` / `backoff-max` (reconnect tuning, ms).

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "spark-html-websocket",
+  "version": "0.1.0",
+  "description": "Declarative WebSocket for spark-html — a reactive store with auto-reconnect, JSON parsing, status, and send(). Zero dependencies.",
+  "type": "module",
+  "main": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "homepage": "https://wilkinnovo.github.io/spark",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "default": "./src/index.js"
+    }
+  },
+  "scripts": {
+    "test": "node test/websocket.js"
+  },
+  "files": [
+    "src"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wilkinnovo/spark.git",
+    "directory": "packages/spark-html-websocket"
+  },
+  "peerDependencies": {
+    "spark-html": ">=0.23.1"
+  },
+  "keywords": [
+    "spark-html",
+    "websocket",
+    "realtime",
+    "reactive",
+    "store",
+    "reconnect"
+  ],
+  "license": "MIT"
+}

package/src/index.d.ts

@@ -0,0 +1,50 @@
+/**
+ * spark-html-websocket — declarative WebSocket as a reactive store.
+ */
+
+export type WsStatus = 'connecting' | 'open' | 'closed' | 'error';
+
+export interface WsStore<T = unknown> {
+  /** The last (post-filter) message. Survives reconnects. */
+  data: T | null;
+  status: WsStatus;
+  error: Error | null;
+  /** Send a message; objects are JSON-stringified. Queued until open. */
+  send(value: unknown): void;
+  /** Deliberate close — never reconnects. */
+  close(): void;
+  /** Re-open after a close() (or after retries were exhausted). */
+  open(): void;
+}
+
+export interface WsOptions {
+  /** Store name (default derived from the URL: "ws:host/path"). */
+  name?: string;
+  /** Parse incoming messages as JSON when possible. Default true. */
+  json?: boolean;
+  /** Only messages passing this land in `data`. */
+  filter?: (data: unknown, event: MessageEvent) => boolean;
+  /** Runs for every (post-filter) message — write to any store you like. */
+  onMessage?: (data: unknown, event: MessageEvent) => void;
+  /** Backoff tuning ({ retries=Infinity, base=500, max=10000 } ms) or false to disable. */
+  reconnect?: { retries?: number; base?: number; max?: number } | false;
+  /** WebSocket subprotocols. */
+  protocols?: string[];
+}
+
+/**
+ * Open (or join) a reactive WebSocket store. Calling it again with the same
+ * name returns the existing handle (shared connection). Inert (status
+ * 'closed') during prerender or where WebSocket doesn't exist.
+ */
+export function ws<T = unknown>(url: string, options?: WsOptions): WsStore<T>;
+
+/**
+ * Declarative form: open a socket per inert `<template ws="wss://…">` block.
+ * Attributes: `ws` (url), `store` (name), `raw` (skip JSON parsing),
+ * `retries` / `backoff` / `backoff-max` (reconnect tuning, ms).
+ */
+export function sockets(root?: ParentNode): WsStore[];
+
+declare const _default: { ws: typeof ws; sockets: typeof sockets };
+export default _default;

package/src/index.js

@@ -0,0 +1,190 @@
+/**
+ * spark-html-websocket — declarative WebSocket as a reactive store.
+ *
+ * Every real-time app writes the same connect/reconnect/parse/cleanup
+ * boilerplate in onMount. This turns a socket into a named store any
+ * component reads with the `useStore` it already knows:
+ *
+ *   import { ws } from 'spark-html-websocket';
+ *   ws('wss://stream.example.com/prices', { name: 'prices' });
+ *
+ *   // any component:
+ *   //   <script>const prices = useStore('prices');</script>
+ *   //   <p :hidden="prices.status !== 'open'">live</p>
+ *   //   <h1>{prices.data?.btc}</h1>
+ *   //   <button onclick="{() => prices.send({ subscribe: 'btc' })}">sub</button>
+ *
+ * Store shape: { data, status, error, send(v), close(), open() } where
+ * status ∈ 'connecting' | 'open' | 'closed' | 'error'. Messages parse as
+ * JSON when they look like it (raw string otherwise); objects passed to
+ * send() are stringified.
+ *
+ * Auto-reconnect: a dropped connection retries with exponential backoff
+ * (base·2ⁿ capped at max) until `retries` is exhausted; a deliberate
+ * close() never reconnects. `data` survives reconnects — subscribers keep
+ * rendering the last message during the gap.
+ *
+ * Declarative form — sockets() scans inert templates the same way the
+ * router scans <template route>:
+ *
+ *   <template ws="wss://stream.example.com/prices" store="prices"></template>
+ *   <script type="module">
+ *     import { sockets } from 'spark-html-websocket';
+ *     sockets();
+ *   </script>
+ *
+ * Prerender-safe: at build time (or wherever WebSocket doesn't exist) the
+ * store is created inert with status 'closed' — components render their
+ * fallback state and nothing connects. Zero dependencies beyond spark-html.
+ */
+import { store } from 'spark-html';
+
+// One live handle per store name — calling ws() twice with the same name
+// (e.g. from two components) shares the connection instead of duplicating it.
+const handles = new Map();
+
+const DEFAULTS = { retries: Infinity, base: 500, max: 10000 };
+
+// Derive a stable store name from the URL when none is given:
+// "wss://x.dev/prices?k=1" → "ws:x.dev/prices"
+function nameFor(url) {
+  return 'ws:' + String(url).replace(/^[a-z]+:\/\//i, '').split(/[?#]/)[0].replace(/\/$/, '');
+}
+
+function parseMessage(raw, json) {
+  if (!json || typeof raw !== 'string') return raw;
+  try { return JSON.parse(raw); } catch { return raw; }
+}
+
+/**
+ * Open (or join) a reactive WebSocket store.
+ *
+ * @param {string} url  ws:// or wss:// endpoint.
+ * @param {object} [options]
+ * @param {string}   [options.name]     Store name (default derived from the URL).
+ * @param {boolean}  [options.json=true] Parse incoming messages as JSON when possible.
+ * @param {(data, event) => boolean} [options.filter]    Only messages passing this land in `data`.
+ * @param {(data, event) => void}    [options.onMessage] Every (post-filter) message — write to any store you like.
+ * @param {object}   [options.reconnect] { retries=Infinity, base=500, max=10000 } — backoff in ms; `false` disables.
+ * @param {string[]} [options.protocols] WebSocket subprotocols.
+ * @returns the reactive store proxy: { data, status, error, send, close, open }
+ */
+export function ws(url, options = {}) {
+  const name = options.name || nameFor(url);
+  if (handles.has(name)) return handles.get(name);
+
+  const json = options.json !== false;
+  const backoff = options.reconnect === false
+    ? { ...DEFAULTS, retries: 0 }
+    : { ...DEFAULTS, ...(options.reconnect || {}) };
+
+  const s = store(name, { data: null, status: 'connecting', error: null });
+  // Tag for tooling (spark-html-devtools) — non-enumerable, never in dumps.
+  try {
+    Object.defineProperty(s, Symbol.for('spark.storeKind'), { value: 'ws', configurable: true });
+  } catch { /* ignore */ }
+
+  let socket = null;
+  let attempts = 0;
+  let timer = null;
+  let closed = false;   // a deliberate close() — never reconnect
+  const queue = [];     // send() before open — flushed on connect
+
+  // No WebSocket here (prerender / old Node): the store stays inert so
+  // components render their fallback state and the build never hangs.
+  const WS = typeof globalThis.WebSocket === 'function' ? globalThis.WebSocket : null;
+  const inert = !WS || globalThis.__SPARK_PRERENDER__;
+
+  function connect() {
+    if (inert || closed) return;
+    s.status = 'connecting'; // no-op write when already connecting (store dedupes)
+    socket = options.protocols ? new WS(url, options.protocols) : new WS(url);
+    socket.onopen = () => {
+      attempts = 0;
+      s.status = 'open';
+      s.error = null;
+      while (queue.length) socket.send(queue.shift());
+    };
+    socket.onmessage = (event) => {
+      const data = parseMessage(event.data, json);
+      if (options.filter && !options.filter(data, event)) return;
+      if (options.onMessage) {
+        try { options.onMessage(data, event); }
+        catch (e) { console.warn(`[spark-ws] onMessage for "${name}" threw: ${e.message}`); }
+      }
+      s.data = data;
+    };
+    socket.onerror = (event) => {
+      s.error = (event && event.error) || new Error('WebSocket error');
+      s.status = 'error';
+    };
+    socket.onclose = () => {
+      socket = null;
+      if (closed) { s.status = 'closed'; return; }
+      if (attempts >= backoff.retries) { s.status = 'closed'; return; }
+      // Exponential backoff: base·2ⁿ capped at max.
+      const delay = Math.min(backoff.base * 2 ** attempts, backoff.max);
+      attempts++;
+      s.status = 'connecting';
+      timer = setTimeout(connect, delay);
+      if (timer && typeof timer.unref === 'function') timer.unref();
+    };
+  }
+
+  s.send = (value) => {
+    const raw = typeof value === 'string' ? value : JSON.stringify(value);
+    if (socket && socket.readyState === 1) socket.send(raw);
+    else queue.push(raw); // flushed when the (re)connect opens
+  };
+  s.close = () => {
+    closed = true;
+    if (timer) { clearTimeout(timer); timer = null; }
+    if (socket) socket.close();
+    else s.status = 'closed';
+    handles.delete(name);
+  };
+  s.open = () => {
+    if (!closed && (socket || timer)) return; // already live/scheduled
+    closed = false;
+    attempts = 0;
+    s.status = 'connecting';
+    connect();
+  };
+
+  if (inert) s.status = 'closed';
+  else connect();
+
+  handles.set(name, s);
+  return s;
+}
+
+/**
+ * Declarative form: open a socket per inert <template ws="…"> block.
+ *
+ *   <template ws="wss://x/prices" store="prices"></template>
+ *
+ * Attributes: `ws` (url), `store` (name), `raw` (skip JSON parsing),
+ * `retries` / `backoff` / `backoff-max` (reconnect tuning, ms).
+ * Returns the opened store proxies.
+ */
+export function sockets(root) {
+  if (typeof document === 'undefined') return [];
+  const scope = root || document;
+  const out = [];
+  for (const t of scope.querySelectorAll('template[ws]')) {
+    const url = t.getAttribute('ws');
+    if (!url) continue;
+    const reconnect = {};
+    if (t.hasAttribute('retries')) reconnect.retries = Number(t.getAttribute('retries'));
+    if (t.hasAttribute('backoff')) reconnect.base = Number(t.getAttribute('backoff'));
+    if (t.hasAttribute('backoff-max')) reconnect.max = Number(t.getAttribute('backoff-max'));
+    out.push(ws(url, {
+      name: t.getAttribute('store') || undefined,
+      json: !t.hasAttribute('raw'),
+      reconnect: Object.keys(reconnect).length ? reconnect : undefined,
+    }));
+  }
+  return out;
+}
+
+export default { ws, sockets };