decantr 0.9.0

package/src/data/realtime.js

@@ -0,0 +1,299 @@
+/**
+ * Decantr Realtime Primitives
+ * WebSocket and EventSource wrappers built on Decantr signals.
+ *
+ * @module decantr/data/realtime
+ *
+ * Exports:
+ *   createWebSocket(url, options?)    — Reactive WebSocket with auto-reconnect
+ *   createEventSource(url, options?)  — Reactive Server-Sent Events wrapper
+ */
+import { createSignal, batch } from '../state/index.js';
+
+// ─── CONSTANTS ──────────────────────────────────────────────────
+
+const MAX_MESSAGES = 100;
+const MAX_BACKOFF = 30000;
+
+// ─── createWebSocket ────────────────────────────────────────────
+
+/**
+ * Create a reactive WebSocket connection with auto-reconnect and message buffering.
+ *
+ * @param {string} url — WebSocket endpoint (ws:// or wss://)
+ * @param {object} [options]
+ * @param {number} [options.reconnectDelay=1000] — Initial reconnect delay in ms
+ * @param {number} [options.maxRetries=5] — Maximum reconnect attempts
+ * @param {boolean} [options.buffer=true] — Buffer sends while disconnected
+ * @param {(data: any) => any} [options.parse] — Message parser (default: identity)
+ * @param {string[]} [options.protocols] — WebSocket sub-protocols
+ * @returns {{
+ *   lastMessage: () => any,
+ *   messages: () => any[],
+ *   status: () => 'connecting'|'open'|'closed'|'reconnecting',
+ *   send: (data: any) => void,
+ *   close: () => void,
+ *   reconnect: () => void,
+ *   on: (handler: (msg: any) => void) => () => void
+ * }}
+ */
+export function createWebSocket(url, options = {}) {
+  const {
+    reconnectDelay = 1000,
+    maxRetries = 5,
+    buffer = true,
+    parse = (d) => d,
+    protocols
+  } = options;
+
+  const [lastMessage, setLastMessage] = createSignal(null);
+  const [messages, setMessages] = createSignal([]);
+  const [status, setStatus] = createSignal('connecting');
+
+  /** @type {((msg: any) => void)[]} */
+  const handlers = [];
+  /** @type {any[]} */
+  const sendBuffer = [];
+  /** @type {{ ws: WebSocket|null, attempts: number, timer: number|null, stopped: boolean }} */
+  const state = { ws: null, attempts: 0, timer: null, stopped: false };
+
+  /**
+   * Flush the send buffer once the socket is open.
+   * @param {WebSocket} ws
+   */
+  function flushBuffer(ws) {
+    while (sendBuffer.length > 0) {
+      ws.send(sendBuffer.shift());
+    }
+  }
+
+  /**
+   * Connect (or reconnect) to the WebSocket server.
+   */
+  function connect() {
+    if (state.stopped) return;
+    const ws = protocols
+      ? new WebSocket(url, protocols)
+      : new WebSocket(url);
+
+    state.ws = ws;
+
+    ws.addEventListener('open', () => {
+      batch(() => {
+        state.attempts = 0;
+        setStatus('open');
+      });
+      flushBuffer(ws);
+    });
+
+    ws.addEventListener('message', (ev) => {
+      const parsed = parse(ev.data);
+      batch(() => {
+        setLastMessage(parsed);
+        setMessages((prev) => {
+          const next = prev.concat(parsed);
+          return next.length > MAX_MESSAGES ? next.slice(next.length - MAX_MESSAGES) : next;
+        });
+      });
+      for (let i = 0; i < handlers.length; i++) handlers[i](parsed);
+    });
+
+    ws.addEventListener('close', () => {
+      if (state.stopped) {
+        setStatus('closed');
+        return;
+      }
+      scheduleReconnect();
+    });
+
+    ws.addEventListener('error', () => {
+      // Error is always followed by close — reconnect logic lives there.
+      // Explicitly close to ensure the close event fires consistently.
+      ws.close();
+    });
+  }
+
+  /**
+   * Schedule a reconnect attempt with exponential backoff + jitter.
+   */
+  function scheduleReconnect() {
+    if (state.stopped) return;
+    if (state.attempts >= maxRetries) {
+      setStatus('closed');
+      return;
+    }
+    setStatus('reconnecting');
+    const delay = Math.min(
+      reconnectDelay * Math.pow(2, state.attempts) + Math.random() * 1000,
+      MAX_BACKOFF
+    );
+    state.attempts++;
+    state.timer = setTimeout(() => {
+      state.timer = null;
+      connect();
+    }, delay);
+  }
+
+  /**
+   * Send data through the WebSocket. Buffers if disconnected and `buffer` is enabled.
+   * @param {any} data
+   */
+  function send(data) {
+    if (state.ws && state.ws.readyState === WebSocket.OPEN) {
+      state.ws.send(data);
+    } else if (buffer) {
+      sendBuffer.push(data);
+    }
+  }
+
+  /**
+   * Close the connection and stop all reconnection attempts.
+   */
+  function close() {
+    state.stopped = true;
+    if (state.timer !== null) {
+      clearTimeout(state.timer);
+      state.timer = null;
+    }
+    if (state.ws) {
+      state.ws.close();
+      state.ws = null;
+    }
+    setStatus('closed');
+  }
+
+  /**
+   * Manually trigger a reconnect. Resets attempt counter.
+   */
+  function reconnect() {
+    if (state.timer !== null) {
+      clearTimeout(state.timer);
+      state.timer = null;
+    }
+    if (state.ws) {
+      state.stopped = true; // prevent auto-reconnect from close handler
+      state.ws.close();
+      state.ws = null;
+    }
+    state.stopped = false;
+    state.attempts = 0;
+    setStatus('connecting');
+    connect();
+  }
+
+  /**
+   * Register a message handler. Returns an unsubscribe function.
+   * @param {(msg: any) => void} handler
+   * @returns {() => void}
+   */
+  function on(handler) {
+    handlers.push(handler);
+    return () => {
+      const idx = handlers.indexOf(handler);
+      if (idx !== -1) handlers.splice(idx, 1);
+    };
+  }
+
+  // Kick off initial connection
+  connect();
+
+  return { lastMessage, messages, status, send, close, reconnect, on };
+}
+
+// ─── createEventSource ──────────────────────────────────────────
+
+/**
+ * Create a reactive EventSource (Server-Sent Events) wrapper.
+ *
+ * @param {string} url — SSE endpoint
+ * @param {object} [options]
+ * @param {string[]} [options.events] — Event types to listen for (default: ['message'])
+ * @param {boolean} [options.withCredentials=false] — Send credentials with request
+ * @returns {{
+ *   lastEvent: () => { type: string, data: string }|null,
+ *   status: () => 'connecting'|'open'|'closed',
+ *   close: () => void,
+ *   on: (eventType: string, handler: (ev: { type: string, data: string }) => void) => () => void
+ * }}
+ */
+export function createEventSource(url, options = {}) {
+  const { events, withCredentials = false } = options;
+
+  const [lastEvent, setLastEvent] = createSignal(null);
+  const [status, setStatus] = createSignal('connecting');
+
+  /** @type {Map<string, ((ev: {type: string, data: string}) => void)[]>} */
+  const handlerMap = new Map();
+
+  const source = new EventSource(url, { withCredentials });
+
+  source.addEventListener('open', () => {
+    setStatus('open');
+  });
+
+  source.addEventListener('error', () => {
+    // EventSource auto-reconnects; reflect readyState
+    if (source.readyState === EventSource.CLOSED) {
+      setStatus('closed');
+    } else {
+      setStatus('connecting');
+    }
+  });
+
+  /**
+   * Internal handler factory for a given event type.
+   * @param {string} type
+   * @returns {(ev: MessageEvent) => void}
+   */
+  function makeListener(type) {
+    return (ev) => {
+      const record = { type, data: ev.data };
+      setLastEvent(record);
+      const list = handlerMap.get(type);
+      if (list) {
+        for (let i = 0; i < list.length; i++) list[i](record);
+      }
+    };
+  }
+
+  // Attach listeners for requested event types
+  const types = events && events.length > 0 ? events : ['message'];
+  for (let i = 0; i < types.length; i++) {
+    source.addEventListener(types[i], makeListener(types[i]));
+  }
+
+  /**
+   * Close the EventSource connection.
+   */
+  function close() {
+    source.close();
+    setStatus('closed');
+  }
+
+  /**
+   * Register a handler for a specific event type. Returns an unsubscribe function.
+   * If the event type was not in the initial `events` list, it is dynamically added.
+   *
+   * @param {string} eventType
+   * @param {(ev: { type: string, data: string }) => void} handler
+   * @returns {() => void}
+   */
+  function on(eventType, handler) {
+    if (!handlerMap.has(eventType)) {
+      handlerMap.set(eventType, []);
+      // Attach a native listener if this type wasn't in the initial set
+      if (!types.includes(eventType)) {
+        source.addEventListener(eventType, makeListener(eventType));
+      }
+    }
+    handlerMap.get(eventType).push(handler);
+    return () => {
+      const list = handlerMap.get(eventType);
+      if (!list) return;
+      const idx = list.indexOf(handler);
+      if (idx !== -1) list.splice(idx, 1);
+    };
+  }
+
+  return { lastEvent, status, close, on };
+}

package/src/data/url.js

@@ -0,0 +1,177 @@
+import { createSignal, batch, untrack } from '../state/index.js';
+
+/* Built-in parsers -------------------------------------------------------- */
+
+/** @type {{ parse: (v: string) => string, serialize: (v: string) => string }} */
+const string = { parse: v => v, serialize: v => v };
+/** @type {{ parse: (v: string) => number, serialize: (v: number) => string }} */
+const integer = { parse: v => parseInt(v, 10), serialize: v => String(v) };
+/** @type {{ parse: (v: string) => number, serialize: (v: number) => string }} */
+const float = { parse: v => parseFloat(v), serialize: v => String(v) };
+/** @type {{ parse: (v: string) => boolean, serialize: (v: boolean) => string }} */
+const boolean = { parse: v => v === 'true', serialize: v => v ? 'true' : 'false' };
+/** @type {{ parse: (v: string) => any, serialize: (v: any) => string }} */
+const json = { parse: v => JSON.parse(v), serialize: v => JSON.stringify(v) };
+/** @type {{ parse: (v: string) => Date, serialize: (v: Date) => string }} */
+const date = { parse: v => new Date(v), serialize: v => v.toISOString() };
+
+/**
+ * Factory parser that validates against an allowed set of values.
+ * @template {string} T
+ * @param {T[]} values
+ * @returns {{ parse: (v: string) => T | undefined, serialize: (v: T) => string }}
+ */
+function enumParser(values) {
+  const allowed = new Set(values);
+  return { parse: v => allowed.has(v) ? /** @type {T} */ (v) : undefined, serialize: v => v };
+}
+
+export const parsers = { string, integer, float, boolean, json, date, enum: enumParser };
+
+/* Internal helpers -------------------------------------------------------- */
+
+/** Detect hash-based routing (`#/...`). */
+function isHashMode() {
+  return typeof window !== 'undefined' && window.location.hash.startsWith('#/');
+}
+
+/**
+ * Read current URL search params, respecting routing mode.
+ * @returns {URLSearchParams}
+ */
+function readParams() {
+  if (isHashMode()) {
+    const hash = window.location.hash.slice(1);
+    const qi = hash.indexOf('?');
+    return new URLSearchParams(qi >= 0 ? hash.slice(qi + 1) : '');
+  }
+  return new URLSearchParams(window.location.search);
+}
+
+/**
+ * Write search params back to URL, preserving routing mode.
+ * @param {URLSearchParams} params
+ * @param {boolean} push — true = pushState, false = replaceState
+ */
+function writeParams(params, push) {
+  const qs = params.toString();
+  const nav = push ? 'pushState' : 'replaceState';
+  if (isHashMode()) {
+    let hash = window.location.hash.slice(1);
+    const qi = hash.indexOf('?');
+    const path = qi >= 0 ? hash.slice(0, qi) : hash;
+    window.history[nav](null, '', window.location.pathname + window.location.search + '#' + path + (qs ? '?' + qs : ''));
+  } else {
+    window.history[nav](null, '', window.location.pathname + (qs ? '?' + qs : ''));
+  }
+}
+
+/* Throttled URL writer (shared across all signals) ------------------------ */
+
+/** @type {number | null} */
+let _flushTimer = null;
+/** @type {Array<{ key: string, value: string | null, push: boolean }>} */
+let _pendingWrites = [];
+
+function scheduleFlush() {
+  if (_flushTimer !== null) return;
+  _flushTimer = setTimeout(() => {
+    _flushTimer = null;
+    const writes = _pendingWrites;
+    _pendingWrites = [];
+    if (writes.length === 0) return;
+    const params = readParams();
+    let push = false;
+    for (const w of writes) {
+      if (w.value === null) params.delete(w.key);
+      else params.set(w.key, w.value);
+      if (w.push) push = true;
+    }
+    writeParams(params, push);
+  }, 50);
+}
+
+/* createURLSignal --------------------------------------------------------- */
+
+/**
+ * Create a reactive signal backed by a URL search parameter.
+ * @template T
+ * @param {string} key — URL param name
+ * @param {{ parse: (v: string) => T, serialize: (v: T) => string }} parser
+ * @param {{ defaultValue?: T, push?: boolean }} [options]
+ * @returns {[() => T, (v: T | ((prev: T) => T)) => void]}
+ */
+export function createURLSignal(key, parser, options = {}) {
+  const { defaultValue, push = false } = options;
+
+  function fromURL() {
+    const raw = readParams().get(key);
+    if (raw === null) return defaultValue;
+    const parsed = parser.parse(raw);
+    return parsed === undefined ? defaultValue : parsed;
+  }
+
+  const [get, set] = createSignal(fromURL());
+
+  // URL -> signal: sync on browser navigation
+  const onNav = () => {
+    const next = fromURL();
+    if (!Object.is(untrack(get), next)) set(next);
+  };
+  if (typeof window !== 'undefined') {
+    window.addEventListener('popstate', onNav);
+    window.addEventListener('hashchange', onNav);
+  }
+
+  /**
+   * Update signal value and schedule a throttled URL write.
+   * @param {T | ((prev: T) => T)} v
+   */
+  function setter(v) {
+    const prev = untrack(get);
+    const next = typeof v === 'function' ? /** @type {Function} */ (v)(prev) : v;
+    set(next);
+    const serialized = Object.is(next, defaultValue) ? null : parser.serialize(next);
+    _pendingWrites.push({ key, value: serialized, push });
+    scheduleFlush();
+  }
+
+  return [get, setter];
+}
+
+/* createURLStore ---------------------------------------------------------- */
+
+/**
+ * Create a reactive store backed by multiple URL search parameters.
+ * @template {Record<string, { parser: { parse: (v: string) => any, serialize: (v: any) => string }, defaultValue?: any }>} S
+ * @param {S} schema
+ * @returns {Record<string, any>} — getter/setter pairs, plus values() and reset()
+ */
+export function createURLStore(schema) {
+  const keys = Object.keys(schema);
+  /** @type {Record<string, [Function, Function]>} */
+  const signals = {};
+  const store = {};
+
+  for (const key of keys) {
+    const { parser, defaultValue, ...rest } = schema[key];
+    const [get, set] = createURLSignal(key, parser, { defaultValue, ...rest });
+    signals[key] = [get, set];
+    store[key] = get;
+    store['set' + key.charAt(0).toUpperCase() + key.slice(1)] = set;
+  }
+
+  /** @returns {Record<string, any>} All current values as a plain object. */
+  store.values = () => {
+    const out = {};
+    for (const key of keys) out[key] = signals[key][0]();
+    return out;
+  };
+
+  /** Reset all params to their defaults. */
+  store.reset = () => {
+    batch(() => { for (const key of keys) signals[key][1](schema[key].defaultValue); });
+  };
+
+  return store;
+}

package/src/data/worker.js

@@ -0,0 +1,134 @@
+import { createSignal, createEffect } from '../state/index.js';
+
+/** @type {number} */
+let nextId = 1;
+
+/**
+ * Persistent bridge to a Web Worker with reactive state.
+ *
+ * Sends messages using `{ id, payload }` protocol and expects
+ * `{ id, result }` or `{ id, error }` responses.
+ *
+ * @param {Worker} worker
+ * @returns {{
+ *   result: () => any,
+ *   busy: () => boolean,
+ *   error: () => any,
+ *   send: (data: any) => number,
+ *   terminate: () => void
+ * }}
+ *
+ * @example
+ * ```js
+ * const ws = createWorkerSignal(new Worker('./compute.js'));
+ * ws.send({ type: 'process', data: [1,2,3] });
+ * // ws.result() — last result from worker
+ * // ws.busy()   — true while worker is processing
+ * // ws.error()  — last error (if any)
+ * ```
+ */
+export function createWorkerSignal(worker) {
+  const [result, setResult] = createSignal(undefined);
+  const [busy, setBusy] = createSignal(false);
+  const [error, setError] = createSignal(undefined);
+
+  /** @type {Set<number>} */
+  const pending = new Set();
+
+  function onMessage(e) {
+    const msg = e.data;
+    if (msg && typeof msg.id === 'number') {
+      pending.delete(msg.id);
+      if ('error' in msg) {
+        setError(msg.error);
+      } else {
+        setResult(msg.result);
+        setError(undefined);
+      }
+      if (pending.size === 0) setBusy(false);
+    }
+  }
+
+  function onError(e) {
+    setError(e.message || e);
+    pending.clear();
+    setBusy(false);
+  }
+
+  worker.addEventListener('message', onMessage);
+  worker.addEventListener('error', onError);
+
+  /**
+   * Send a message to the worker.
+   * @param {any} data
+   * @returns {number} message id
+   */
+  function send(data) {
+    const id = nextId++;
+    pending.add(id);
+    setBusy(true);
+    setError(undefined);
+    worker.postMessage({ id, payload: data });
+    return id;
+  }
+
+  /** Terminate the worker and clean up listeners. */
+  function terminate() {
+    worker.removeEventListener('message', onMessage);
+    worker.removeEventListener('error', onError);
+    worker.terminate();
+    pending.clear();
+    setBusy(false);
+  }
+
+  return { result, busy, error, send, terminate };
+}
+
+/**
+ * One-shot reactive computation via a Web Worker.
+ *
+ * When `input` is a signal getter, re-sends to the worker whenever
+ * the value changes. Returns a resource-like object.
+ *
+ * @param {Worker} worker
+ * @param {(() => any) | any} input - Signal getter or plain value
+ * @returns {{
+ *   data: () => any,
+ *   loading: () => boolean,
+ *   error: () => any,
+ *   refetch: () => void
+ * }}
+ *
+ * @example
+ * ```js
+ * const result = createWorkerQuery(new Worker('./heavy.js'), () => ({ data: largeArray() }));
+ * // result.data()    — computed result
+ * // result.loading() — true while computing
+ * // result.error()   — last error
+ * // result.refetch() — re-run with current input
+ * ```
+ */
+export function createWorkerQuery(worker, input) {
+  const ws = createWorkerSignal(worker);
+  const isGetter = typeof input === 'function';
+
+  /** Resolve current input value and send to worker. */
+  function run() {
+    const value = isGetter ? input() : input;
+    ws.send(value);
+  }
+
+  // If input is reactive, track changes and re-send automatically.
+  if (isGetter) {
+    createEffect(() => { run(); });
+  } else {
+    run();
+  }
+
+  return {
+    data: ws.result,
+    loading: ws.busy,
+    error: ws.error,
+    refetch: run
+  };
+}