@better-state/server 0.1.0

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}

package/dist/cli.js

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+import { randomBytes, createHash, randomUUID } from "node:crypto";
+import { writeFileSync, readFileSync, existsSync, mkdirSync } from "node:fs";
+import path from "node:path";
+const dataDir = path.join(process.cwd(), ".better-state");
+mkdirSync(dataDir, { recursive: true });
+process.env.DATABASE_PATH = process.env.DATABASE_PATH || path.join(dataDir, "state.db");
+process.env.DEV_KEY_PATH = process.env.DEV_KEY_PATH || path.join(dataDir, ".dev-key");
+const { createDatabase, runMigrations } = await import("./db.js");
+const PORT = parseInt(process.env.PORT || "3001", 10);
+function autoSeed() {
+    const db = createDatabase();
+    runMigrations(db);
+    const devKeyPath = process.env.DEV_KEY_PATH;
+    const existing = db.prepare("SELECT id FROM namespaces WHERE name = ?").get("default");
+    if (existing) {
+        db.close();
+        if (existsSync(devKeyPath)) {
+            return readFileSync(devKeyPath, "utf-8").trim();
+        }
+        return "";
+    }
+    const rawKey = randomBytes(32).toString("hex");
+    const hashedKey = createHash("sha256").update(rawKey).digest("hex");
+    const id = randomUUID();
+    const now = Date.now();
+    db.prepare("INSERT INTO namespaces (id, name, api_key, created_at) VALUES (?, ?, ?, ?)").run(id, "default", hashedKey, now);
+    writeFileSync(devKeyPath, rawKey, "utf-8");
+    db.close();
+    return rawKey;
+}
+const apiKey = autoSeed();
+const box = [
+    "",
+    "  ┌─────────────────────────────────────────────────────┐",
+    "  │                                                     │",
+    "  │   Better-State Server                               │",
+    "  │                                                     │",
+    `  │   Local:      http://localhost:${PORT}                  │`,
+    `  │   Playground: http://localhost:${PORT}/playground        │`,
+    `  │   Data:       ${dataDir}  │`.slice(0, 57) + "│",
+    "  │                                                     │",
+];
+if (apiKey) {
+    box.push("  │   API Key (save this):                              │", `  │   ${apiKey}  │`, "  │                                                     │", "  │   Usage in your app:                                │", "  │                                                     │", "  │     import { createClient }                         │", "  │       from '@better-state/client'                   │", "  │                                                     │", "  │     const bs = createClient(                        │", `  │       'http://localhost:${PORT}',                      │`, "  │       { apiKey: '<your-key>' }                      │", "  │     )                                               │", "  │     const counter = bs.state('counter', 0)          │", "  │     counter.set(1)                                  │", "  │                                                     │");
+}
+box.push("  └─────────────────────────────────────────────────────┘", "");
+console.log(box.join("\n"));
+await import("./index.js");
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}

package/dist/db.d.ts

@@ -0,0 +1,4 @@
+import Database from "better-sqlite3";
+export declare function createDatabase(): Database.Database;
+export declare function runMigrations(db: Database.Database): void;
+//# sourceMappingURL=db.d.ts.map

package/dist/db.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"db.d.ts","sourceRoot":"","sources":["../src/db.ts"],"names":[],"mappings":"AAAA,OAAO,QAAQ,MAAM,gBAAgB,CAAC;AAQtC,wBAAgB,cAAc,IAAI,QAAQ,CAAC,QAAQ,CAUlD;AAED,wBAAgB,aAAa,CAAC,EAAE,EAAE,QAAQ,CAAC,QAAQ,GAAG,IAAI,CAuCzD"}

package/dist/db.js

@@ -0,0 +1,55 @@
+import Database from "better-sqlite3";
+import { mkdirSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const DB_PATH = process.env.DATABASE_PATH || path.join(__dirname, "..", "data", "state.db");
+export function createDatabase() {
+    const dir = path.dirname(DB_PATH);
+    mkdirSync(dir, { recursive: true });
+    const db = new Database(DB_PATH);
+    db.pragma("journal_mode = WAL");
+    db.pragma("foreign_keys = ON");
+    return db;
+}
+export function runMigrations(db) {
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS namespaces (
+      id          TEXT PRIMARY KEY,
+      name        TEXT NOT NULL,
+      api_key     TEXT NOT NULL UNIQUE,
+      created_at  INTEGER NOT NULL
+    );
+
+    CREATE TABLE IF NOT EXISTS states (
+      id          TEXT PRIMARY KEY,
+      namespace   TEXT NOT NULL REFERENCES namespaces(id),
+      key         TEXT NOT NULL,
+      initial     TEXT NOT NULL,
+      snapshot    TEXT NOT NULL,
+      version     INTEGER NOT NULL DEFAULT 0,
+      created_at  INTEGER NOT NULL,
+      updated_at  INTEGER NOT NULL,
+      UNIQUE(namespace, key)
+    );
+
+    CREATE TABLE IF NOT EXISTS event_log (
+      id          TEXT PRIMARY KEY,
+      state_id    TEXT NOT NULL REFERENCES states(id),
+      client_id   TEXT NOT NULL,
+      client_ts   INTEGER NOT NULL,
+      server_ts   INTEGER NOT NULL,
+      seq         INTEGER NOT NULL,
+      mutation    TEXT NOT NULL,
+      meta        TEXT,
+      created_at  INTEGER NOT NULL
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_event_log_state_ts
+      ON event_log(state_id, server_ts, seq);
+
+    CREATE INDEX IF NOT EXISTS idx_states_namespace_key
+      ON states(namespace, key);
+  `);
+}
+//# sourceMappingURL=db.js.map

package/dist/db.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"db.js","sourceRoot":"","sources":["../src/db.ts"],"names":[],"mappings":"AAAA,OAAO,QAAQ,MAAM,gBAAgB,CAAC;AACtC,OAAO,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACpC,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,MAAM,SAAS,GAAG,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAC/D,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,aAAa,IAAI,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE,UAAU,CAAC,CAAC;AAE5F,MAAM,UAAU,cAAc;IAC5B,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;IAClC,SAAS,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAEpC,MAAM,EAAE,GAAG,IAAI,QAAQ,CAAC,OAAO,CAAC,CAAC;IAEjC,EAAE,CAAC,MAAM,CAAC,oBAAoB,CAAC,CAAC;IAChC,EAAE,CAAC,MAAM,CAAC,mBAAmB,CAAC,CAAC;IAE/B,OAAO,EAAE,CAAC;AACZ,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,EAAqB;IACjD,EAAE,CAAC,IAAI,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCP,CAAC,CAAC;AACL,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+import express from "express";
+import { Server } from "socket.io";
+declare const app: ReturnType<typeof express>;
+declare const io: Server<import("socket.io").DefaultEventsMap, import("socket.io").DefaultEventsMap, import("socket.io").DefaultEventsMap, any>;
+export { app, io };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,OAAO,MAAM,SAAS,CAAC;AAO9B,OAAO,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAYnC,QAAA,MAAM,GAAG,EAAE,UAAU,CAAC,OAAO,OAAO,CAAa,CAAC;AAKlD,QAAA,MAAM,EAAE,+HAEN,CAAC;AAgRH,OAAO,EAAE,GAAG,EAAE,EAAE,EAAE,CAAC"}

package/dist/index.js

@@ -0,0 +1,241 @@
+import express from "express";
+import cors from "cors";
+import { createServer } from "node:http";
+import { readFileSync } from "node:fs";
+import { randomBytes, createHash, randomUUID } from "node:crypto";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { Server } from "socket.io";
+import { createDatabase, runMigrations } from "./db.js";
+import { ensureState, processMutations, getHistory } from "./state-engine.js";
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const PORT = parseInt(process.env.PORT || "3001", 10);
+const CORS_ORIGIN = process.env.CORS_ORIGIN || "*";
+const db = createDatabase();
+runMigrations(db);
+const app = express();
+app.use(cors({ origin: CORS_ORIGIN }));
+app.use(express.json());
+const httpServer = createServer(app);
+const io = new Server(httpServer, {
+    cors: { origin: CORS_ORIGIN, methods: ["GET", "POST"] },
+});
+// ─── REST API (Dashboard) ────────────────────────────────────────────────────
+app.get("/api/v1/health", (_req, res) => {
+    res.json({ status: "ok", uptime: process.uptime() });
+});
+app.get("/api/v1/namespaces", (_req, res) => {
+    const rows = db.prepare("SELECT id, name, created_at FROM namespaces").all();
+    res.json(rows);
+});
+app.post("/api/v1/namespaces", (req, res) => {
+    const { name } = req.body;
+    if (!name || typeof name !== "string") {
+        res.status(400).json({ error: "name is required" });
+        return;
+    }
+    const rawKey = randomBytes(32).toString("hex");
+    const hashedKey = createHash("sha256").update(rawKey).digest("hex");
+    const id = randomUUID();
+    const now = Date.now();
+    db.prepare("INSERT INTO namespaces (id, name, api_key, created_at) VALUES (?, ?, ?, ?)").run(id, name, hashedKey, now);
+    res.status(201).json({ id, name, apiKey: rawKey, created_at: now });
+});
+app.get("/api/v1/states", (req, res) => {
+    const namespace = req.query.namespace;
+    if (!namespace) {
+        res.status(400).json({ error: "namespace query param is required" });
+        return;
+    }
+    const rows = db
+        .prepare("SELECT id, key, snapshot, version, created_at, updated_at FROM states WHERE namespace = ?")
+        .all(namespace);
+    res.json(rows);
+});
+app.get("/api/v1/states/:key/history", (req, res) => {
+    const namespace = req.query.namespace;
+    if (!namespace) {
+        res.status(400).json({ error: "namespace query param is required" });
+        return;
+    }
+    const stateRow = db
+        .prepare("SELECT * FROM states WHERE namespace = ? AND key = ?")
+        .get(namespace, req.params.key);
+    if (!stateRow) {
+        res.status(404).json({ error: "state not found" });
+        return;
+    }
+    const limit = parseInt(req.query.limit, 10) || 50;
+    const cursor = req.query.cursor;
+    const { events, hasMore } = getHistory(db, stateRow.id, limit, cursor);
+    res.json({
+        key: stateRow.key,
+        version: stateRow.version,
+        events,
+        cursor: events.length > 0 ? events[events.length - 1].id : null,
+        hasMore,
+    });
+});
+// ─── Playground & SDK Serving ─────────────────────────────────────────────────
+import { existsSync } from "node:fs";
+const CLIENT_BUNDLE = path.resolve(__dirname, "../../client/dist/browser.mjs");
+const CLIENT_SOURCEMAP = path.resolve(__dirname, "../../client/dist/browser.mjs.map");
+const PLAYGROUND_HTML = path.resolve(__dirname, "../public/playground.html");
+app.get("/sdk/browser.mjs", (_req, res) => {
+    if (existsSync(CLIENT_BUNDLE)) {
+        res.setHeader("Content-Type", "application/javascript");
+        res.sendFile(CLIENT_BUNDLE);
+    }
+    else {
+        res.redirect("https://unpkg.com/@better-state/client/dist/browser.mjs");
+    }
+});
+app.get("/sdk/browser.mjs.map", (_req, res) => {
+    if (existsSync(CLIENT_SOURCEMAP)) {
+        res.setHeader("Content-Type", "application/json");
+        res.sendFile(CLIENT_SOURCEMAP);
+    }
+    else {
+        res.redirect("https://unpkg.com/@better-state/client/dist/browser.mjs.map");
+    }
+});
+app.get("/playground", (_req, res) => {
+    const ns = db.prepare("SELECT api_key FROM namespaces WHERE name = ?").get("default");
+    if (!ns) {
+        res.status(500).send("No default namespace. Run the server via CLI to auto-seed.");
+        return;
+    }
+    const devKeyPath = process.env.DEV_KEY_PATH || path.resolve(__dirname, "../data/.dev-key");
+    let apiKey;
+    try {
+        apiKey = readFileSync(devKeyPath, "utf-8").trim();
+    }
+    catch {
+        res.status(500).send("Dev API key not found. Delete the .better-state directory and restart the server.");
+        return;
+    }
+    if (!existsSync(PLAYGROUND_HTML)) {
+        const inline = getInlinePlayground(apiKey);
+        res.setHeader("Content-Type", "text/html");
+        res.send(inline);
+        return;
+    }
+    const html = readFileSync(PLAYGROUND_HTML, "utf-8").replace("__API_KEY__", apiKey);
+    res.setHeader("Content-Type", "text/html");
+    res.send(html);
+});
+function getInlinePlayground(apiKey) {
+    return `<!DOCTYPE html>
+<html lang="en"><head><meta charset="UTF-8"><meta name="viewport" content="width=device-width,initial-scale=1">
+<title>Better-State Playground</title>
+<style>*{margin:0;padding:0;box-sizing:border-box}body{font-family:system-ui,-apple-system,sans-serif;background:#0f172a;color:#e2e8f0;display:flex;flex-direction:column;align-items:center;justify-content:center;min-height:100vh;gap:1.5rem}
+h1{font-size:1.5rem;font-weight:600}#counter{font-size:4rem;font-weight:700;color:#38bdf8}
+.row{display:flex;gap:.75rem}button{background:#1e293b;color:#e2e8f0;border:1px solid #334155;padding:.5rem 1.25rem;border-radius:.5rem;font-size:1rem;cursor:pointer;transition:background .15s}
+button:hover{background:#334155}#status{font-size:.875rem;color:#94a3b8}</style></head>
+<body><h1>Better-State Playground</h1><div id="counter">0</div>
+<div class="row"><button onclick="dec()">-1</button><button onclick="reset()">Reset</button><button onclick="inc()">+1</button></div>
+<div id="status">connecting...</div>
+<script type="module">
+import{createClient}from"/sdk/browser.mjs";
+const bs=createClient(location.origin,{apiKey:"${apiKey}",debug:false});
+bs.onStatusChange(s=>document.getElementById("status").textContent=s);
+const counter=bs.state("counter",0);
+counter.subscribe(v=>document.getElementById("counter").textContent=String(v));
+window.inc=()=>counter.update(n=>n+1);
+window.dec=()=>counter.update(n=>n-1);
+window.reset=()=>counter.set(0);
+</script></body></html>`;
+}
+// ─── WebSocket (Real-time Sync) ──────────────────────────────────────────────
+const namespaceCache = new Map(); // apiKey hash → namespace id
+function authenticateApiKey(rawKey) {
+    const hash = createHash("sha256").update(rawKey).digest("hex");
+    if (namespaceCache.has(hash))
+        return namespaceCache.get(hash);
+    const row = db
+        .prepare("SELECT id FROM namespaces WHERE api_key = ?")
+        .get(hash);
+    if (!row)
+        return null;
+    namespaceCache.set(hash, row.id);
+    return row.id;
+}
+io.on("connection", (socket) => {
+    let authedNamespace = null;
+    let clientId = null;
+    console.log(`[ws] new connection: ${socket.id}`);
+    socket.on("auth", (payload, ack) => {
+        const nsId = authenticateApiKey(payload.apiKey);
+        if (!nsId) {
+            socket.emit("auth:error", { message: "Invalid API key" });
+            if (typeof ack === "function")
+                ack({ ok: false });
+            return;
+        }
+        authedNamespace = nsId;
+        clientId = payload.clientId;
+        console.log(`[ws] auth ok: socket=${socket.id} client=${clientId}`);
+        socket.emit("auth:ok", { sessionId: socket.id });
+        if (typeof ack === "function")
+            ack({ ok: true });
+    });
+    socket.on("subscribe", (payload) => {
+        if (!authedNamespace) {
+            socket.emit("auth:error", { message: "Not authenticated" });
+            return;
+        }
+        for (const entry of payload.keys) {
+            const key = typeof entry === "string" ? entry : entry.key;
+            const initialValue = typeof entry === "object" && entry !== null ? entry.initialValue : null;
+            const room = `${authedNamespace}:${key}`;
+            socket.join(room);
+            const state = ensureState(db, authedNamespace, key, initialValue);
+            socket.emit("state:init", {
+                key,
+                value: JSON.parse(state.snapshot),
+                version: state.version,
+            });
+        }
+    });
+    socket.on("unsubscribe", (payload) => {
+        if (!authedNamespace)
+            return;
+        for (const key of payload.keys) {
+            socket.leave(`${authedNamespace}:${key}`);
+        }
+    });
+    socket.on("mutate", (payload) => {
+        if (!authedNamespace || !clientId) {
+            socket.emit("auth:error", { message: "Not authenticated" });
+            return;
+        }
+        try {
+            console.log(`[ws] mutate: key=${payload.key} client=${clientId} count=${payload.mutations.length}`);
+            const { value, version, mutationIds } = processMutations(db, authedNamespace, payload.key, clientId, payload.mutations);
+            socket.emit("mutate:ack", { mutationIds });
+            const room = `${authedNamespace}:${payload.key}`;
+            io.to(room).emit("state:update", {
+                key: payload.key,
+                value,
+                version,
+            });
+            console.log(`[ws] broadcast: key=${payload.key} version=${version}`);
+        }
+        catch (err) {
+            socket.emit("mutate:error", {
+                message: err.message,
+            });
+        }
+    });
+    socket.on("disconnect", (reason) => {
+        console.log(`[ws] disconnect: socket=${socket.id} client=${clientId} reason=${reason}`);
+        authedNamespace = null;
+        clientId = null;
+    });
+});
+// ─── Start ───────────────────────────────────────────────────────────────────
+httpServer.listen(PORT, () => {
+    console.log(`[better-state] server running on http://localhost:${PORT}`);
+});
+export { app, io };
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/seed.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=seed.d.ts.map

package/dist/seed.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"seed.d.ts","sourceRoot":"","sources":["../src/seed.ts"],"names":[],"mappings":""}

package/dist/seed.js

@@ -0,0 +1,28 @@
+import { createDatabase, runMigrations } from "./db.js";
+import { randomBytes, createHash, randomUUID } from "node:crypto";
+import { writeFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const db = createDatabase();
+runMigrations(db);
+const existing = db.prepare("SELECT id FROM namespaces WHERE name = ?").get("default");
+if (existing) {
+    console.log("[seed] Default namespace already exists. Skipping.");
+    process.exit(0);
+}
+const rawKey = randomBytes(32).toString("hex");
+const hashedKey = createHash("sha256").update(rawKey).digest("hex");
+const id = randomUUID();
+const now = Date.now();
+db.prepare("INSERT INTO namespaces (id, name, api_key, created_at) VALUES (?, ?, ?, ?)").run(id, "default", hashedKey, now);
+const devKeyPath = path.resolve(__dirname, "../data/.dev-key");
+writeFileSync(devKeyPath, rawKey, "utf-8");
+console.log("[seed] Created default namespace:");
+console.log(`  Namespace ID : ${id}`);
+console.log(`  API Key      : ${rawKey}`);
+console.log(`  Dev key file : ${devKeyPath}`);
+console.log("");
+console.log("Use it in your client: createClient({ apiKey: '...' })");
+console.log("Or open http://localhost:3001/playground to test interactively.");
+//# sourceMappingURL=seed.js.map

package/dist/seed.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"seed.js","sourceRoot":"","sources":["../src/seed.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AACxD,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAClE,OAAO,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AACxC,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,MAAM,SAAS,GAAG,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAE/D,MAAM,EAAE,GAAG,cAAc,EAAE,CAAC;AAC5B,aAAa,CAAC,EAAE,CAAC,CAAC;AAElB,MAAM,QAAQ,GAAG,EAAE,CAAC,OAAO,CAAC,0CAA0C,CAAC,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;AACvF,IAAI,QAAQ,EAAE,CAAC;IACb,OAAO,CAAC,GAAG,CAAC,oDAAoD,CAAC,CAAC;IAClE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC;AAED,MAAM,MAAM,GAAG,WAAW,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AAC/C,MAAM,SAAS,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AACpE,MAAM,EAAE,GAAG,UAAU,EAAE,CAAC;AACxB,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;AAEvB,EAAE,CAAC,OAAO,CACR,4EAA4E,CAC7E,CAAC,GAAG,CAAC,EAAE,EAAE,SAAS,EAAE,SAAS,EAAE,GAAG,CAAC,CAAC;AAErC,MAAM,UAAU,GAAG,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,kBAAkB,CAAC,CAAC;AAC/D,aAAa,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;AAE3C,OAAO,CAAC,GAAG,CAAC,mCAAmC,CAAC,CAAC;AACjD,OAAO,CAAC,GAAG,CAAC,oBAAoB,EAAE,EAAE,CAAC,CAAC;AACtC,OAAO,CAAC,GAAG,CAAC,oBAAoB,MAAM,EAAE,CAAC,CAAC;AAC1C,OAAO,CAAC,GAAG,CAAC,oBAAoB,UAAU,EAAE,CAAC,CAAC;AAC9C,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;AAChB,OAAO,CAAC,GAAG,CAAC,wDAAwD,CAAC,CAAC;AACtE,OAAO,CAAC,GAAG,CAAC,iEAAiE,CAAC,CAAC"}

package/dist/state-engine.d.ts

@@ -0,0 +1,57 @@
+import type Database from "better-sqlite3";
+export interface MutationInput {
+    id: string;
+    clientTs: number;
+    fn: string;
+    value?: unknown;
+}
+export interface EventRecord {
+    id: string;
+    state_id: string;
+    client_id: string;
+    client_ts: number;
+    server_ts: number;
+    seq: number;
+    mutation: string;
+    meta: string | null;
+    created_at: number;
+}
+export interface StateRecord {
+    id: string;
+    namespace: string;
+    key: string;
+    initial: string;
+    snapshot: string;
+    version: number;
+    created_at: number;
+    updated_at: number;
+}
+/**
+ * Ensures a state row exists for the given namespace + key.
+ * If it doesn't exist, creates one with the provided initial value.
+ * Returns the state row.
+ */
+export declare function ensureState(db: Database.Database, namespace: string, key: string, initialValue?: unknown): StateRecord;
+/**
+ * Processes a batch of mutations for a given state key.
+ * Appends events to the log, replays to compute new snapshot,
+ * persists the snapshot, and returns the new value + version.
+ */
+export declare function processMutations(db: Database.Database, namespace: string, key: string, clientId: string, mutations: MutationInput[]): {
+    value: unknown;
+    version: number;
+    mutationIds: string[];
+};
+/**
+ * Replays the full event log for a state to compute the current value.
+ * This is the authoritative state computation.
+ */
+export declare function replayState(db: Database.Database, stateId: string, initialJson: string): unknown;
+/**
+ * Returns the event history for a state key (paginated).
+ */
+export declare function getHistory(db: Database.Database, stateId: string, limit?: number, cursor?: string): {
+    events: EventRecord[];
+    hasMore: boolean;
+};
+//# sourceMappingURL=state-engine.d.ts.map

package/dist/state-engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-engine.d.ts","sourceRoot":"","sources":["../src/state-engine.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,QAAQ,MAAM,gBAAgB,CAAC;AAG3C,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC;IACjB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CACzB,EAAE,EAAE,QAAQ,CAAC,QAAQ,EACrB,SAAS,EAAE,MAAM,EACjB,GAAG,EAAE,MAAM,EACX,YAAY,GAAE,OAAc,GAC3B,WAAW,CAmBb;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,EAAE,EAAE,QAAQ,CAAC,QAAQ,EACrB,SAAS,EAAE,MAAM,EACjB,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,aAAa,EAAE,GACzB;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,EAAE,CAAA;CAAE,CAmC5D;AAED;;;GAGG;AACH,wBAAgB,WAAW,CACzB,EAAE,EAAE,QAAQ,CAAC,QAAQ,EACrB,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,MAAM,GAClB,OAAO,CAoCT;AAoCD;;GAEG;AACH,wBAAgB,UAAU,CACxB,EAAE,EAAE,QAAQ,CAAC,QAAQ,EACrB,OAAO,EAAE,MAAM,EACf,KAAK,SAAK,EACV,MAAM,CAAC,EAAE,MAAM,GACd;IAAE,MAAM,EAAE,WAAW,EAAE,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,CA0B7C"}

package/dist/state-engine.js

@@ -0,0 +1,141 @@
+import { v4 as uuid } from "uuid";
+/**
+ * Ensures a state row exists for the given namespace + key.
+ * If it doesn't exist, creates one with the provided initial value.
+ * Returns the state row.
+ */
+export function ensureState(db, namespace, key, initialValue = null) {
+    const existing = db
+        .prepare("SELECT * FROM states WHERE namespace = ? AND key = ?")
+        .get(namespace, key);
+    if (existing)
+        return existing;
+    const now = Date.now();
+    const serialized = JSON.stringify(initialValue);
+    const id = uuid();
+    db.prepare(`INSERT INTO states (id, namespace, key, initial, snapshot, version, created_at, updated_at)
+     VALUES (?, ?, ?, ?, ?, 0, ?, ?)`).run(id, namespace, key, serialized, serialized, now, now);
+    return db
+        .prepare("SELECT * FROM states WHERE id = ?")
+        .get(id);
+}
+/**
+ * Processes a batch of mutations for a given state key.
+ * Appends events to the log, replays to compute new snapshot,
+ * persists the snapshot, and returns the new value + version.
+ */
+export function processMutations(db, namespace, key, clientId, mutations) {
+    const state = ensureState(db, namespace, key);
+    const maxSeqRow = db
+        .prepare("SELECT MAX(seq) as max_seq FROM event_log WHERE state_id = ?")
+        .get(state.id);
+    let seq = (maxSeqRow.max_seq ?? -1) + 1;
+    const now = Date.now();
+    const insertEvent = db.prepare(`INSERT INTO event_log (id, state_id, client_id, client_ts, server_ts, seq, mutation, meta, created_at)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`);
+    const mutationIds = [];
+    const insertAll = db.transaction(() => {
+        for (const mut of mutations) {
+            const eventId = mut.id || uuid();
+            const meta = mut.value !== undefined ? JSON.stringify({ fallbackValue: mut.value }) : null;
+            insertEvent.run(eventId, state.id, clientId, mut.clientTs, now, seq, mut.fn, meta, now);
+            mutationIds.push(eventId);
+            seq++;
+        }
+    });
+    insertAll();
+    const newValue = replayState(db, state.id, state.initial);
+    const newVersion = state.version + mutations.length;
+    db.prepare("UPDATE states SET snapshot = ?, version = ?, updated_at = ? WHERE id = ?").run(JSON.stringify(newValue), newVersion, Date.now(), state.id);
+    return { value: newValue, version: newVersion, mutationIds };
+}
+/**
+ * Replays the full event log for a state to compute the current value.
+ * This is the authoritative state computation.
+ */
+export function replayState(db, stateId, initialJson) {
+    const events = db
+        .prepare("SELECT mutation, meta FROM event_log WHERE state_id = ? ORDER BY server_ts ASC, seq ASC")
+        .all(stateId);
+    let state = JSON.parse(initialJson);
+    for (const event of events) {
+        if (event.mutation === "__SET__") {
+            if (event.meta) {
+                try {
+                    state = JSON.parse(event.meta).fallbackValue;
+                }
+                catch { }
+            }
+            continue;
+        }
+        try {
+            state = applyMutation(state, event.mutation);
+        }
+        catch (err) {
+            if (event.meta) {
+                try {
+                    const parsed = JSON.parse(event.meta);
+                    if (parsed.fallbackValue !== undefined) {
+                        state = parsed.fallbackValue;
+                        continue;
+                    }
+                }
+                catch { }
+            }
+            console.error(`Skipping faulting mutation: ${err.message}`);
+        }
+    }
+    return state;
+}
+const SANDBOX_KEYS = [
+    "crypto", "JSON", "Math", "Date", "Array", "Object", "String",
+    "Number", "Boolean", "parseInt", "parseFloat", "isNaN", "isFinite",
+    "structuredClone", "undefined", "NaN", "Infinity",
+];
+const SANDBOX_VALUES = [
+    globalThis.crypto, JSON, Math, Date, Array, Object, String,
+    Number, Boolean, parseInt, parseFloat, isNaN, isFinite,
+    structuredClone, undefined, NaN, Infinity,
+];
+/**
+ * Applies a serialized mutation function to a state value.
+ * The mutation must be a pure arrow function: (old) => newValue
+ *
+ * Runs in a sandbox with a curated set of globals. Mutation functions
+ * should ideally be deterministic, but we provide crypto etc. as a
+ * safety net for common patterns.
+ */
+function applyMutation(state, mutationBody) {
+    const ARROW_FN = /^\s*\(?\s*\w+\s*\)?\s*=>/;
+    if (!ARROW_FN.test(mutationBody)) {
+        throw new Error(`Invalid mutation format: must be an arrow function`);
+    }
+    const fn = new Function("__state__", ...SANDBOX_KEYS, `"use strict"; const __fn__ = ${mutationBody}; return __fn__(__state__);`);
+    return fn(structuredClone(state), ...SANDBOX_VALUES);
+}
+/**
+ * Returns the event history for a state key (paginated).
+ */
+export function getHistory(db, stateId, limit = 50, cursor) {
+    let events;
+    if (cursor) {
+        events = db
+            .prepare(`SELECT * FROM event_log
+         WHERE state_id = ? AND (server_ts, seq) > (
+           SELECT server_ts, seq FROM event_log WHERE id = ?
+         )
+         ORDER BY server_ts ASC, seq ASC
+         LIMIT ?`)
+            .all(stateId, cursor, limit + 1);
+    }
+    else {
+        events = db
+            .prepare("SELECT * FROM event_log WHERE state_id = ? ORDER BY server_ts ASC, seq ASC LIMIT ?")
+            .all(stateId, limit + 1);
+    }
+    const hasMore = events.length > limit;
+    if (hasMore)
+        events.pop();
+    return { events, hasMore };
+}
+//# sourceMappingURL=state-engine.js.map

package/dist/state-engine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-engine.js","sourceRoot":"","sources":["../src/state-engine.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@better-state/server",
+  "version": "0.1.0",
+  "description": "Better-State server — shared state primitive for developers",
+  "type": "module",
+  "bin": {
+    "better-state": "dist/cli.js"
+  },
+  "scripts": {
+    "dev": "tsx watch src/index.ts",
+    "build": "tsc && node scripts/postbuild.js",
+    "start": "node dist/index.js",
+    "seed": "tsx src/seed.ts",
+    "test": "tsx --test src/__tests__/*.test.ts",
+    "clean": "rm -rf dist"
+  },
+  "files": [
+    "dist",
+    "!dist/__tests__",
+    "public"
+  ],
+  "keywords": [
+    "state",
+    "shared-state",
+    "realtime",
+    "sync",
+    "websocket",
+    "server"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/better-state/better-state"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "better-sqlite3": "^11.0.0",
+    "cors": "^2.8.5",
+    "express": "^4.21.0",
+    "socket.io": "^4.8.0",
+    "uuid": "^11.0.0"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.0",
+    "@types/cors": "^2.8.0",
+    "@types/express": "^5.0.0",
+    "@types/uuid": "^10.0.0",
+    "socket.io-client": "^4.8.3",
+    "tsx": "^4.19.0",
+    "typescript": "^5.7.0"
+  }
+}

package/public/playground.html

@@ -0,0 +1,301 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>Better-State Playground</title>
+  <style>
+    *, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
+
+    body {
+      font-family: "Inter", ui-sans-serif, system-ui, -apple-system, sans-serif;
+      background: #0a0a0f;
+      color: #e2e8f0;
+      min-height: 100vh;
+      padding: 2rem;
+    }
+
+    .header {
+      display: flex;
+      align-items: center;
+      gap: 0.75rem;
+      margin-bottom: 2rem;
+    }
+    .header h1 {
+      font-size: 1.5rem;
+      font-weight: 700;
+      letter-spacing: -0.02em;
+    }
+    .header h1 span { color: #36adf6; }
+    .badge {
+      font-size: 0.7rem;
+      background: rgba(12, 147, 231, 0.15);
+      color: #7cc8fb;
+      padding: 0.15rem 0.5rem;
+      border-radius: 9999px;
+    }
+
+    .status-bar {
+      display: flex;
+      gap: 1.5rem;
+      margin-bottom: 2rem;
+      font-size: 0.85rem;
+      color: #94a3b8;
+    }
+    .status-dot {
+      display: inline-block;
+      width: 8px;
+      height: 8px;
+      border-radius: 50%;
+      margin-right: 0.4rem;
+      vertical-align: middle;
+    }
+    .status-dot.green { background: #34d399; }
+    .status-dot.red { background: #f87171; }
+    .status-dot.yellow { background: #fbbf24; }
+
+    .grid {
+      display: grid;
+      grid-template-columns: 1fr 1fr;
+      gap: 1.5rem;
+      margin-bottom: 2rem;
+    }
+
+    .card {
+      background: rgba(15, 23, 42, 0.6);
+      border: 1px solid #1e293b;
+      border-radius: 12px;
+      padding: 1.25rem;
+    }
+    .card h2 {
+      font-size: 0.75rem;
+      font-weight: 600;
+      text-transform: uppercase;
+      letter-spacing: 0.05em;
+      color: #64748b;
+      margin-bottom: 1rem;
+    }
+
+    .state-display {
+      background: #0f172a;
+      border: 1px solid #1e293b;
+      border-radius: 8px;
+      padding: 1rem;
+      font-family: "JetBrains Mono", "Fira Code", monospace;
+      font-size: 0.85rem;
+      min-height: 120px;
+      white-space: pre-wrap;
+      word-break: break-all;
+      color: #a5b4fc;
+      margin-bottom: 1rem;
+    }
+
+    .controls { display: flex; gap: 0.5rem; flex-wrap: wrap; }
+
+    button {
+      background: linear-gradient(135deg, #0c93e7, #015da0);
+      color: white;
+      border: none;
+      padding: 0.5rem 1rem;
+      border-radius: 8px;
+      font-size: 0.8rem;
+      font-weight: 500;
+      cursor: pointer;
+      transition: opacity 0.15s;
+    }
+    button:hover { opacity: 0.85; }
+    button.secondary {
+      background: rgba(30, 41, 59, 0.8);
+      border: 1px solid #334155;
+    }
+    button.danger {
+      background: linear-gradient(135deg, #dc2626, #991b1b);
+    }
+
+    input[type="text"] {
+      background: #0f172a;
+      border: 1px solid #334155;
+      color: #e2e8f0;
+      padding: 0.5rem 0.75rem;
+      border-radius: 8px;
+      font-size: 0.85rem;
+      flex: 1;
+      min-width: 180px;
+    }
+    input[type="text"]:focus { outline: none; border-color: #36adf6; }
+
+    .log {
+      background: #0f172a;
+      border: 1px solid #1e293b;
+      border-radius: 8px;
+      padding: 1rem;
+      font-family: "JetBrains Mono", "Fira Code", monospace;
+      font-size: 0.75rem;
+      max-height: 300px;
+      overflow-y: auto;
+      line-height: 1.6;
+    }
+    .log .entry { margin-bottom: 0.25rem; }
+    .log .ts { color: #475569; }
+    .log .event { color: #34d399; }
+    .log .data { color: #94a3b8; }
+    .log .error { color: #f87171; }
+
+    .hint {
+      font-size: 0.8rem;
+      color: #475569;
+      margin-top: 0.5rem;
+      line-height: 1.5;
+    }
+
+    @media (max-width: 768px) {
+      .grid { grid-template-columns: 1fr; }
+    }
+  </style>
+</head>
+<body>
+  <div class="header">
+    <h1><span>Better</span>-State</h1>
+    <span class="badge">Playground</span>
+  </div>
+
+  <div class="status-bar">
+    <div><span id="conn-dot" class="status-dot yellow"></span> <span id="conn-text">Connecting...</span></div>
+    <div>Client: <code id="client-id">—</code></div>
+    <div>Version: <code id="version">0</code></div>
+  </div>
+
+  <div class="grid">
+    <!-- Counter state -->
+    <div class="card">
+      <h2>State: counter</h2>
+      <div id="counter-display" class="state-display">0</div>
+      <div class="controls">
+        <button onclick="increment()">+ Increment</button>
+        <button onclick="decrement()" class="secondary">- Decrement</button>
+        <button onclick="resetCounter()" class="danger">Reset</button>
+      </div>
+      <p class="hint">Click buttons in multiple tabs — they all sync in real-time.</p>
+    </div>
+
+    <!-- Todos state -->
+    <div class="card">
+      <h2>State: todos</h2>
+      <div id="todos-display" class="state-display">[]</div>
+      <div class="controls">
+        <input id="todo-input" type="text" placeholder="Add a todo..." onkeydown="if(event.key==='Enter') addTodo()" />
+        <button onclick="addTodo()">Add</button>
+        <button onclick="clearTodos()" class="danger">Clear</button>
+      </div>
+    </div>
+  </div>
+
+  <!-- Event log -->
+  <div class="card">
+    <h2>Event Log</h2>
+    <div id="log" class="log">
+      <div class="entry"><span class="ts">[init]</span> <span class="data">Waiting for connection...</span></div>
+    </div>
+  </div>
+
+  <script type="module">
+    // --- Config ---
+    // The API key is injected by the server into the page.
+    const API_KEY = "__API_KEY__";
+    const SERVER_URL = window.location.origin;
+
+    // --- Load SDK ---
+    const { createClient } = await import("/sdk/browser.mjs");
+
+    const log = document.getElementById("log");
+    const connDot = document.getElementById("conn-dot");
+    const connText = document.getElementById("conn-text");
+    const clientIdEl = document.getElementById("client-id");
+    const versionEl = document.getElementById("version");
+
+    function addLog(event, data, isError = false) {
+      const ts = new Date().toLocaleTimeString();
+      const entry = document.createElement("div");
+      entry.className = "entry";
+      entry.innerHTML = `<span class="ts">[${ts}]</span> <span class="${isError ? "error" : "event"}">${event}</span> <span class="data">${data}</span>`;
+      log.appendChild(entry);
+      log.scrollTop = log.scrollHeight;
+    }
+
+    // --- Create client ---
+    const client = createClient(SERVER_URL, {
+      apiKey: API_KEY,
+      debug: true,
+    });
+
+    clientIdEl.textContent = "connecting...";
+
+    // --- Counter state ---
+    const counter = client.state("counter", 0);
+
+    counter.subscribe((val) => {
+      document.getElementById("counter-display").textContent = JSON.stringify(val, null, 2);
+      versionEl.textContent = counter.getVersion();
+      addLog("counter:update", `value=${val} version=${counter.getVersion()}`);
+    });
+
+    // --- Todos state ---
+    const todos = client.state("todos", []);
+
+    todos.subscribe((val) => {
+      document.getElementById("todos-display").textContent = JSON.stringify(val, null, 2);
+      addLog("todos:update", `items=${Array.isArray(val) ? val.length : "?"}`);
+    });
+
+    // --- Connection status ---
+    // Poll connection status (simple approach)
+    setInterval(() => {
+      const connected = counter.getVersion() >= 0;
+      if (connText.textContent === "Connecting..." && counter.getVersion() > 0) {
+        connDot.className = "status-dot green";
+        connText.textContent = "Connected";
+        clientIdEl.textContent = client._clientId || "active";
+      }
+    }, 500);
+
+    // Mark connected once we get first state
+    setTimeout(() => {
+      connDot.className = "status-dot green";
+      connText.textContent = "Connected";
+    }, 2000);
+
+    // --- Actions (exposed globally for onclick handlers) ---
+    window.increment = () => {
+      counter.update((n) => n + 1);
+      addLog("action", "increment");
+    };
+
+    window.decrement = () => {
+      counter.update((n) => n - 1);
+      addLog("action", "decrement");
+    };
+
+    window.resetCounter = () => {
+      counter.update(() => 0);
+      addLog("action", "reset counter");
+    };
+
+    window.addTodo = () => {
+      const input = document.getElementById("todo-input");
+      const text = input.value.trim();
+      if (!text) return;
+      const id = crypto.randomUUID();
+      todos.update((list) => [...list, { id, text, done: false }]);
+      addLog("action", `add todo: "${text}"`);
+      input.value = "";
+    };
+
+    window.clearTodos = () => {
+      todos.update(() => []);
+      addLog("action", "clear todos");
+    };
+
+    addLog("init", "SDK loaded, connecting to server...");
+  </script>
+</body>
+</html>