@blueshed/railroad 0.3.4 → 0.5.0

package/delta-server.ts

@@ -0,0 +1,234 @@
+/**
+ * Delta Server — WebSocket protocol layer + document/method registration for Bun.
+ *
+ * Provides the server half of the delta-doc system:
+ *   - createWs()       — shared WebSocket infrastructure (action routing, pub/sub, upgrade)
+ *   - registerDoc()    — persist a typed JSON document, sync via delta ops
+ *   - registerMethod() — expose a stateless RPC handler
+ *
+ * Usage:
+ *   import { createWs, registerDoc, registerMethod } from "@blueshed/railroad/delta-server";
+ *
+ *   const ws = createWs();
+ *   await registerDoc<Message>(ws, "message", { file: "./message.json", empty: { message: "" } });
+ *   registerMethod(ws, "status", () => ({ bun: Bun.version }));
+ *
+ *   const server = Bun.serve({ routes: { "/ws": ws.upgrade }, websocket: ws.websocket });
+ *   ws.setServer(server);
+ */
+import { createLogger } from "./logger";
+import { applyOps, type DeltaOp } from "./delta";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export type ActionHandler = (
+  msg: any,
+  ws: any,
+  respond: (result: any) => void,
+) => any | Promise<any>;
+
+export interface WsServer {
+  on(action: string, handler: ActionHandler): void;
+  publish(channel: string, data: any): void;
+  sendTo(clientId: string, data: any): void;
+  setServer(s: any): void;
+  upgrade: (req: Request, server: any) => Response | undefined;
+  websocket: {
+    idleTimeout: number;
+    sendPings: boolean;
+    publishToSelf: boolean;
+    open(ws: any): void;
+    message(ws: any, raw: any): void;
+    close(ws: any): void;
+  };
+}
+
+export interface DocHandle<T> {
+  getDoc(): T;
+  setDoc(d: T): void;
+  persist(): Promise<void>;
+  applyAndBroadcast(ops: DeltaOp[]): void;
+}
+
+export interface DocOptions<T> {
+  file: string;
+  empty: T;
+}
+
+// ---------------------------------------------------------------------------
+// WebSocket server
+// ---------------------------------------------------------------------------
+
+/** Create a shared WebSocket server with action routing and Bun pub/sub. */
+export function createWs(): WsServer {
+  const log = createLogger("[ws]");
+  const actions = new Map<string, ActionHandler[]>();
+  const clients = new Map<string, any>();
+  let serverRef: any;
+
+  return {
+    on(action: string, handler: ActionHandler) {
+      if (!actions.has(action)) actions.set(action, []);
+      actions.get(action)!.push(handler);
+    },
+
+    publish(channel: string, data: any) {
+      serverRef?.publish(channel, JSON.stringify(data));
+    },
+
+    sendTo(clientId: string, data: any) {
+      const ws = clients.get(clientId);
+      if (ws?.readyState === 1) ws.send(JSON.stringify(data));
+    },
+
+    setServer(s: any) {
+      serverRef = s;
+    },
+
+    upgrade: (req: Request, server: any) => {
+      const url = new URL(req.url, "http://localhost");
+      const clientId = url.searchParams.get("clientId") ?? crypto.randomUUID();
+      if (server.upgrade(req, { data: { clientId } })) return;
+      return new Response("WebSocket upgrade failed", { status: 400 });
+    },
+
+    websocket: {
+      idleTimeout: 60,
+      sendPings: true,
+      publishToSelf: true,
+      open(ws: any) {
+        const clientId = ws.data?.clientId;
+        if (clientId) clients.set(clientId, ws);
+        for (const ch of ws.data?.channels ?? []) ws.subscribe(ch);
+        log.debug(`open id=${clientId ?? "?"}`);
+      },
+      async message(ws: any, raw: any) {
+        const msg = JSON.parse(String(raw));
+        const { id, action } = msg;
+
+        if (!action) {
+          for (const handler of actions.get("_raw") ?? []) {
+            await handler(msg, ws, () => {});
+          }
+          return;
+        }
+
+        try {
+          const handlers = actions.get(action);
+          if (!handlers?.length) {
+            if (id)
+              ws.send(
+                JSON.stringify({
+                  id,
+                  error: { code: -1, message: `Unknown action: ${action}` },
+                }),
+              );
+            return;
+          }
+          let responded = false;
+          const respond = (response: any) => {
+            if (!responded && id) {
+              responded = true;
+              ws.send(JSON.stringify({ id, ...response }));
+            }
+          };
+          for (const handler of handlers) {
+            await handler(msg, ws, respond);
+            if (responded) break;
+          }
+          if (!responded && id) {
+            ws.send(
+              JSON.stringify({
+                id,
+                error: { code: -1, message: `No handler matched: ${action}` },
+              }),
+            );
+          }
+        } catch (err: any) {
+          log.error(`error: ${err.message}`);
+          if (id)
+            ws.send(
+              JSON.stringify({ id, error: { code: -1, message: err.message } }),
+            );
+        }
+      },
+      close(ws: any) {
+        const clientId = ws.data?.clientId;
+        if (clientId) clients.delete(clientId);
+        log.debug(`close id=${clientId ?? "?"}`);
+      },
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Document registration
+// ---------------------------------------------------------------------------
+
+/** Register a persisted JSON document with the WebSocket server. */
+export async function registerDoc<T>(
+  ws: Pick<WsServer, "on" | "publish">,
+  name: string,
+  opts: DocOptions<T>,
+): Promise<DocHandle<T>> {
+  const log = createLogger(`[${name}]`);
+  const dataFile = Bun.file(opts.file);
+  let doc: T = (await dataFile.exists())
+    ? { ...structuredClone(opts.empty), ...((await dataFile.json()) as T) }
+    : structuredClone(opts.empty);
+
+  log.info(`loaded from ${opts.file}`);
+
+  async function persist() {
+    await Bun.write(dataFile, JSON.stringify(doc, null, 2));
+  }
+
+  function applyAndBroadcast(ops: DeltaOp[]) {
+    applyOps(doc, ops);
+    log.info(`delta [${ops.map((o) => `${o.op} ${o.path}`).join(", ")}]`);
+    ws.publish(name, { doc: name, ops });
+    persist();
+  }
+
+  ws.on("open", (msg, client, respond) => {
+    if (msg.doc !== name) return;
+    client.subscribe(name);
+    respond({ result: doc });
+    log.debug("opened");
+  });
+
+  ws.on("delta", (msg, _client, respond) => {
+    if (msg.doc !== name) return;
+    applyAndBroadcast(msg.ops);
+    respond({ result: { ack: true } });
+  });
+
+  ws.on("close", (msg, client, respond) => {
+    if (msg.doc !== name) return;
+    client.unsubscribe(name);
+    respond({ result: { ack: true } });
+    log.debug("closed");
+  });
+
+  return { getDoc: () => doc, setDoc: (d: T) => { doc = d; }, persist, applyAndBroadcast };
+}
+
+// ---------------------------------------------------------------------------
+// Method registration
+// ---------------------------------------------------------------------------
+
+/** Register a stateless RPC method with the WebSocket server. */
+export function registerMethod(
+  ws: Pick<WsServer, "on">,
+  name: string,
+  handler: (params: any, client: any) => any | Promise<any>,
+) {
+  ws.on("call", async (msg, client, respond) => {
+    if (msg.method !== name) return;
+    const log = createLogger(`[${name}]`);
+    log.debug("called");
+    respond({ result: await handler(msg.params, client) });
+  });
+}

package/delta.ts

@@ -0,0 +1,66 @@
+/**
+ * Delta — shared types and operations for JSON document patching.
+ *
+ * Used by both delta-server (apply + persist) and delta-client (apply + render).
+ * No dependencies — safe to import anywhere.
+ *
+ * Delta ops use JSON Pointer paths (`/`-separated, numeric for array index, `-` for append):
+ *   { op: "replace", path: "/field",    value: "new" }  — set a value at path
+ *   { op: "add",     path: "/items/-",  value: item }   — append to array
+ *   { op: "remove",  path: "/items/0" }                  — delete by index
+ *
+ * Multiple ops applied via applyOps() are atomic in memory.
+ */
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export type DeltaOp =
+  | { op: "replace"; path: string; value: unknown }
+  | { op: "add"; path: string; value: unknown }
+  | { op: "remove"; path: string };
+
+// ---------------------------------------------------------------------------
+// Apply
+// ---------------------------------------------------------------------------
+
+function parsePath(path: string): (string | number)[] {
+  return path
+    .split("/")
+    .filter(Boolean)
+    .map((s) => (/^\d+$/.test(s) ? Number(s) : s));
+}
+
+function walk(
+  obj: any,
+  segments: (string | number)[],
+): { parent: any; key: string | number } {
+  let current = obj;
+  for (let i = 0; i < segments.length - 1; i++) {
+    current = current[segments[i]!];
+    if (current == null)
+      throw new Error(`Path not found at segment ${segments[i]}`);
+  }
+  return { parent: current, key: segments[segments.length - 1]! };
+}
+
+/** Apply delta ops to a document in place. */
+export function applyOps(doc: any, ops: DeltaOp[]): void {
+  for (const op of ops) {
+    const segments = parsePath(op.path);
+    const { parent, key } = walk(doc, segments);
+    switch (op.op) {
+      case "replace":
+      case "add":
+        if (Array.isArray(parent) && key === "-") parent.push(op.value);
+        else parent[key] = op.value;
+        break;
+      case "remove":
+        if (Array.isArray(parent) && typeof key === "number")
+          parent.splice(key, 1);
+        else delete parent[key];
+        break;
+    }
+  }
+}

package/index.ts

@@ -1,12 +1,11 @@
-// Railroad — Signals, JSX, and Routes
+// Railroad — Signals, JSX, Routes, and Delta-doc
 
 export { Signal, signal, computed, effect, batch } from "./signals";
 export type { Dispose } from "./signals";
 
 export {
   createElement, Fragment,
-  text, when, list,
-  pushDisposeScope, popDisposeScope,
+  when, list,
 } from "./jsx";
 
 export { routes, route, navigate, matchRoute } from "./routes";
@@ -16,3 +15,6 @@ export type { Key } from "./shared";
 
 export { createLogger, setLogLevel, getLogLevel, loggedRequest } from "./logger";
 export type { LogLevel } from "./logger";
+
+export { applyOps } from "./delta";
+export type { DeltaOp } from "./delta";

package/jsx.ts

@@ -5,11 +5,16 @@
  *   - tag: string → creates HTML element (or SVG element inside <svg>)
  *   - tag: function → calls component function(props)
  *   - props: attributes, event handlers (onclick etc), ref
- *   - children: string, number, Node, Signal<T>, arrays, null/undefined
+ *   - children: string, number, Node, Signal<T>, () => any, arrays, null/undefined
  *
  * When a Signal is used as a child, an effect auto-updates the text node.
+ * When a function is used as a child, it auto-tracks dependencies:
+ *   <span>{() => count.get() > 5 ? "High" : "Low"}</span>
  * When a Signal is used as a prop value, an effect auto-updates the attribute.
  *
+ * Components are auto-scoped — effects/computeds inside are disposed when
+ * the parent scope (route, when, list) tears down. No manual dispose needed.
+ *
  * SVG support:
  *   <svg> is created with the SVG namespace. Any HTML children appended to
  *   an SVG-namespaced parent are automatically adopted into the SVG namespace.
@@ -20,13 +25,12 @@
  *   when(signal, truthy, falsy?)  — conditional rendering, swaps DOM nodes
  *   list(signal, keyFn, render)   — keyed reactive list, render receives Signal<T>
  *   list(signal, render)          — index-based reactive list, render receives raw T
- *   text(fn)                      — reactive text from computed expression
  */
 
 import { Signal, signal, effect, computed, pushDisposeScope, popDisposeScope, trackDispose } from "./signals";
 import type { Dispose } from "./signals";
 
-export { pushDisposeScope, popDisposeScope };
+// pushDisposeScope / popDisposeScope are internal — used by createElement, when, list, routes
 
 // === SVG namespace ===
 
@@ -52,35 +56,35 @@ function applyProps(el: Element, props: Record<string, any>): void {
       if (typeof value === "function") value(el);
     } else if (key === "innerHTML") {
       if (value instanceof Signal) {
-        trackDispose(effect(() => { el.innerHTML = value.get(); }));
+        effect(() => { el.innerHTML = value.get(); });
       } else {
         el.innerHTML = value;
       }
     } else if (key === "className" || key === "class") {
       if (value instanceof Signal) {
-        trackDispose(effect(() => { el.setAttribute("class", value.get()); }));
+        effect(() => { el.setAttribute("class", value.get()); });
       } else {
         el.setAttribute("class", value);
       }
     } else if (key === "value" || key === "checked" || key === "disabled" || key === "selected" || key === "srcdoc" || key === "src") {
       if (value instanceof Signal) {
-        trackDispose(effect(() => { (el as any)[key] = value.get(); }));
+        effect(() => { (el as any)[key] = value.get(); });
       } else {
         (el as any)[key] = value;
       }
     } else if (key === "style" && value instanceof Signal) {
-      trackDispose(effect(() => { Object.assign((el as HTMLElement).style, value.get()); }));
+      effect(() => { Object.assign((el as HTMLElement).style, value.get()); });
     } else if (key === "style" && typeof value === "object") {
       Object.assign((el as HTMLElement).style, value);
     } else if (key.startsWith("on")) {
       el.addEventListener(key.slice(2).toLowerCase(), value);
     } else {
       if (value instanceof Signal) {
-        trackDispose(effect(() => {
+        effect(() => {
           const v = value.get();
           if (v === false || v == null) el.removeAttribute(key);
           else el.setAttribute(key, String(v));
-        }));
+        });
       } else if (value !== false && value != null) {
         el.setAttribute(key, String(value));
       }
@@ -96,8 +100,12 @@ export function createElement(
   ...children: any[]
 ): Node {
   if (typeof tag === "function") {
+    pushDisposeScope();
     const componentProps = { ...props, children };
-    return tag(componentProps);
+    const node = tag(componentProps);
+    const dispose = popDisposeScope();
+    trackDispose(dispose);
+    return node;
   }
 
   // SVG root element is always created with the SVG namespace.
@@ -160,10 +168,17 @@ function appendChildren(parent: Node, children: any[]): void {
 
     if (child instanceof Signal) {
       const text = document.createTextNode(String(child.peek()));
-      trackDispose(effect(() => {
+      effect(() => {
         text.textContent = String(child.get());
-      }));
+      });
       parent.appendChild(text);
+    } else if (typeof child === "function") {
+      const fn = child as () => any;
+      const textNode = document.createTextNode("");
+      effect(() => {
+        textNode.textContent = String(fn() ?? "");
+      });
+      parent.appendChild(textNode);
     } else if (child instanceof Node) {
       // Adopt HTML elements into SVG namespace when parent is SVG
       if (isSvgParent &&
@@ -179,17 +194,6 @@ function appendChildren(parent: Node, children: any[]): void {
   }
 }
 
-// === text() — reactive computed text node ===
-// Use for expressions: text(() => count.get() > 5 ? "High" : "Low")
-
-export function text(fn: () => string): Node {
-  const value = computed(fn);
-  const node = document.createTextNode(value.peek());
-  trackDispose(effect(() => {
-    node.textContent = value.get();
-  }));
-  return node;
-}
 
 // === when() — conditional rendering ===
 // Swaps DOM nodes only when truthiness transitions (falsy↔truthy).
@@ -203,7 +207,7 @@ export function when(
   falsy?: () => Node,
 ): Node {
   const anchor = document.createComment("when");
-  let current: Node | null = null;
+  let currentNodes: Node[] = [];
   let currentDispose: Dispose | null = null;
   let wasTruthy: boolean | undefined = undefined;
 
@@ -218,32 +222,33 @@ export function when(
     wasTruthy = isTruthy;
 
     if (currentDispose) currentDispose();
-    if (current && anchor.parentNode) {
-      anchor.parentNode.removeChild(current);
-    }
+    for (const n of currentNodes) n.parentNode?.removeChild(n);
+    currentNodes = [];
 
     pushDisposeScope();
-    current = isTruthy ? truthy() : (falsy ? falsy() : null);
+    const result = isTruthy ? truthy() : (falsy ? falsy() : null);
     currentDispose = popDisposeScope();
 
-    if (current && anchor.parentNode) {
-      anchor.parentNode.insertBefore(current, anchor.nextSibling);
+    if (result && anchor.parentNode) {
+      // Capture actual child nodes before fragment is emptied by insertBefore
+      currentNodes = result instanceof DocumentFragment
+        ? [...result.childNodes]
+        : [result];
+      anchor.parentNode.insertBefore(result, anchor.nextSibling);
     }
   }
 
-  trackDispose(effect(() => {
+  effect(() => {
     sig.get(); // track
     if (!anchor.parentNode) {
       queueMicrotask(swap);
     } else {
       swap();
     }
-  }));
+  });
 
-  // Return a fragment: anchor + initial content
   const frag = document.createDocumentFragment();
   frag.appendChild(anchor);
-  if (current) frag.appendChild(current);
   return frag;
 }
 
@@ -252,11 +257,17 @@ export function when(
 //
 // Keyed form — render receives Signal<T> and Signal<number> so item
 // updates flow into existing DOM without re-creating nodes:
-//   list(items, (t) => t.id, (item, index) => <li>{text(() => item.get().name)}</li>)
+//   list(items, (t) => t.id, (item$) => <li>{item$.map(t => t.name)}</li>)
 //
 // Non-keyed form (index-based, raw values):
 //   list(items, (item, index) => <li>{item}</li>)
 
+function collectNodes(result: Node): Node[] {
+  return result instanceof DocumentFragment
+    ? [...result.childNodes]
+    : [result];
+}
+
 export function list<T>(
   items: Signal<T[]>,
   keyFnOrRender: ((item: T) => string | number) | ((item: T, index: number) => Node),
@@ -265,7 +276,7 @@ export function list<T>(
   const hasKeyFn = maybeRender !== undefined;
   const keyFn = hasKeyFn ? keyFnOrRender as (item: T) => string | number : null;
 
-  type Entry = { node: Node; dispose: Dispose; item?: Signal<T>; index?: Signal<number> };
+  type Entry = { nodes: Node[]; dispose: Dispose; item?: Signal<T>; index?: Signal<number> };
   const anchor = document.createComment("list");
   let entries: Map<string | number, Entry> = new Map();
   let order: (string | number)[] = [];
@@ -274,7 +285,7 @@ export function list<T>(
     const entry = entries.get(key);
     if (entry) {
       entry.dispose();
-      entry.node.parentNode?.removeChild(entry.node);
+      for (const n of entry.nodes) n.parentNode?.removeChild(n);
       entries.delete(key);
     }
   }
@@ -282,7 +293,7 @@ export function list<T>(
   function clearAll() {
     for (const [, entry] of entries) {
       entry.dispose();
-      entry.node.parentNode?.removeChild(entry.node);
+      for (const n of entry.nodes) n.parentNode?.removeChild(n);
     }
     entries = new Map();
     order = [];
@@ -310,17 +321,17 @@ export function list<T>(
       if (!entry) {
         // New item — create
         pushDisposeScope();
-        let node: Node;
+        let result: Node;
         if (hasKeyFn) {
           const itemSig = signal(arr[i]!);
           const indexSig = signal(i);
-          node = maybeRender!(itemSig, indexSig);
+          result = maybeRender!(itemSig, indexSig);
           const dispose = popDisposeScope();
-          entry = { node, dispose, item: itemSig, index: indexSig };
+          entry = { nodes: collectNodes(result), dispose, item: itemSig, index: indexSig };
         } else {
-          node = (keyFnOrRender as (item: T, index: number) => Node)(arr[i]!, i);
+          result = (keyFnOrRender as (item: T, index: number) => Node)(arr[i]!, i);
           const dispose = popDisposeScope();
-          entry = { node, dispose };
+          entry = { nodes: collectNodes(result), dispose };
         }
         entries.set(key, entry);
       } else if (hasKeyFn) {
@@ -329,34 +340,43 @@ export function list<T>(
         entry.index!.set(i);
       } else {
         // Index-based — dispose old, recreate with new item
-        const oldNode = entry.node;
+        const oldNodes = entry.nodes;
         entry.dispose();
         pushDisposeScope();
-        const node = (keyFnOrRender as (item: T, index: number) => Node)(arr[i]!, i);
+        const result = (keyFnOrRender as (item: T, index: number) => Node)(arr[i]!, i);
         const dispose = popDisposeScope();
-        entry = { node, dispose };
+        const nodes = collectNodes(result);
+        entry = { nodes, dispose };
         entries.set(key, entry);
-        if (oldNode.parentNode) oldNode.parentNode.replaceChild(node, oldNode);
+        const ref = oldNodes[oldNodes.length - 1]?.nextSibling ?? null;
+        const oldParent = oldNodes[0]?.parentNode;
+        for (const n of oldNodes) n.parentNode?.removeChild(n);
+        if (oldParent) {
+          for (const n of nodes) oldParent.insertBefore(n, ref);
+        }
       }
 
       // Move or insert into correct position
-      if (entry.node.nextSibling !== insertBefore) {
-        parent.insertBefore(entry.node, insertBefore);
+      const lastNode = entry.nodes[entry.nodes.length - 1];
+      if (lastNode?.nextSibling !== insertBefore) {
+        for (const n of entry.nodes) {
+          parent.insertBefore(n, insertBefore);
+        }
       }
-      insertBefore = entry.node;
+      insertBefore = entry.nodes[0] ?? insertBefore;
     }
 
     order = newKeys;
   }
 
-  trackDispose(effect(() => {
+  effect(() => {
     items.get(); // track
     if (!anchor.parentNode) {
       queueMicrotask(sync);
     } else {
       sync();
     }
-  }));
+  });
 
   trackDispose(() => clearAll());
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@blueshed/railroad",
-  "version": "0.3.4",
-  "description": "Signals, JSX, and routes — a micro UI framework for Bun",
+  "version": "0.5.0",
+  "description": "Signals, JSX, routes, and delta-doc — a micro UI framework for Bun",
   "type": "module",
   "main": "index.ts",
   "types": "index.ts",
@@ -11,6 +11,9 @@
     "./jsx": "./jsx.ts",
     "./routes": "./routes.ts",
     "./shared": "./shared.ts",
+    "./delta": "./delta.ts",
+    "./delta-server": "./delta-server.ts",
+    "./delta-client": "./delta-client.ts",
     "./jsx-runtime": "./jsx-runtime.ts",
     "./jsx-dev-runtime": "./jsx-dev-runtime.ts"
   },
@@ -36,5 +39,5 @@
     "type": "git",
     "url": "https://github.com/blueshed/railroad"
   },
-  "keywords": ["signals", "jsx", "router", "bun", "ui", "framework"]
+  "keywords": ["signals", "jsx", "router", "delta-doc", "bun", "ui", "framework"]
 }