@nexus_js/runtime 0.6.0

package/dist/sync.js

@@ -0,0 +1,156 @@
+/**
+ * Nexus $sync Rune — "The Teleportation Rune"
+ *
+ * Automatically synchronizes client state with:
+ *   - Browser cookies
+ *   - SessionStorage / LocalStorage
+ *   - Server-side DB (via Server Action endpoint)
+ *
+ * Usage:
+ *   // Sync with a cookie (persists across sessions)
+ *   const theme = $sync('theme', { default: 'dark', persist: 'cookie' });
+ *   theme.value = 'light'; // auto-saves to cookie + syncs to server
+ *
+ *   // Sync with DB (calls /_nexus/sync/:key automatically)
+ *   const cart = $sync('cart', { default: [], persist: 'db' });
+ *   cart.value = [...cart.value, newItem]; // writes to DB in background
+ *
+ *   // Optimistic DB sync
+ *   const likes = $sync('post:42:likes', { default: 0, persist: 'db', optimistic: true });
+ *   likes.value++; // UI updates immediately, DB writes in background
+ */
+import { $state, $effect } from './runes.js';
+const SYNC_ENDPOINT = '/_nexus/sync/';
+/**
+ * Creates a synced reactive signal.
+ * Reads initial value from storage/server, writes back on every change.
+ */
+export function $sync(key, opts = {}) {
+    const persist = opts.persist ?? 'local';
+    const debounceMs = opts.debounce ?? 300;
+    // Read initial value from storage
+    const initial = readFromStorage(key, persist) ?? opts.default;
+    const signal = $state(initial);
+    const pending = $state(false);
+    const error = $state(null);
+    let debounceTimer = null;
+    // Watch for changes and persist
+    $effect(() => {
+        const val = signal.value;
+        if (debounceTimer)
+            clearTimeout(debounceTimer);
+        debounceTimer = setTimeout(async () => {
+            pending.value = true;
+            error.value = null;
+            try {
+                await writeToStorage(key, val, persist, opts.cookie);
+            }
+            catch (err) {
+                error.value = err instanceof Error ? err.message : String(err);
+                console.error(`[Nexus $sync] Failed to persist "${key}":`, err);
+            }
+            finally {
+                pending.value = false;
+            }
+        }, debounceMs);
+    });
+    const refresh = async () => {
+        pending.value = true;
+        try {
+            const fresh = await readFromServer(key);
+            if (fresh !== null)
+                signal.value = fresh;
+        }
+        catch (err) {
+            error.value = err instanceof Error ? err.message : String(err);
+        }
+        finally {
+            pending.value = false;
+        }
+    };
+    // Initial server sync for 'db' persistence
+    if (persist === 'db') {
+        refresh().catch(() => { });
+    }
+    return {
+        get value() { return signal.value; },
+        set value(v) { signal.value = v; },
+        get pending() { return pending.value; },
+        get error() { return error.value; },
+        refresh,
+    };
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Storage adapters
+// ─────────────────────────────────────────────────────────────────────────────
+function readFromStorage(key, persist) {
+    if (typeof window === 'undefined')
+        return null;
+    try {
+        switch (persist) {
+            case 'cookie': {
+                const match = document.cookie.match(new RegExp(`(?:^|; )nx_${escKey(key)}=([^;]*)`));
+                return match ? JSON.parse(decodeURIComponent(match[1] ?? '')) : null;
+            }
+            case 'session': {
+                const raw = sessionStorage.getItem(`nx:${key}`);
+                return raw ? JSON.parse(raw) : null;
+            }
+            case 'local': {
+                const raw = localStorage.getItem(`nx:${key}`);
+                return raw ? JSON.parse(raw) : null;
+            }
+            case 'db':
+                return null; // DB reads happen async via refresh()
+        }
+    }
+    catch {
+        return null;
+    }
+}
+async function writeToStorage(key, value, persist, cookieOpts = {}) {
+    const serialized = JSON.stringify(value);
+    switch (persist) {
+        case 'cookie': {
+            const maxAge = cookieOpts?.maxAge ?? 60 * 60 * 24 * 30; // 30 days
+            const path = cookieOpts?.path ?? '/';
+            const secure = cookieOpts?.secure ? '; Secure' : '';
+            const sameSite = cookieOpts?.sameSite ?? 'Lax';
+            document.cookie =
+                `nx_${escKey(key)}=${encodeURIComponent(serialized)}; Max-Age=${maxAge}; Path=${path}; SameSite=${sameSite}${secure}`;
+            break;
+        }
+        case 'session':
+            sessionStorage.setItem(`nx:${key}`, serialized);
+            break;
+        case 'local':
+            localStorage.setItem(`nx:${key}`, serialized);
+            break;
+        case 'db':
+            await writeToServer(key, value);
+            break;
+    }
+}
+async function readFromServer(key) {
+    const res = await fetch(`${SYNC_ENDPOINT}${encodeURIComponent(key)}`, {
+        headers: { 'x-nexus-sync': '1' },
+    });
+    if (!res.ok)
+        return null;
+    const data = await res.json();
+    return data.value ?? null;
+}
+async function writeToServer(key, value) {
+    await fetch(`${SYNC_ENDPOINT}${encodeURIComponent(key)}`, {
+        method: 'POST',
+        headers: {
+            'content-type': 'application/json',
+            'x-nexus-sync': '1',
+        },
+        body: JSON.stringify({ value }),
+    });
+}
+function escKey(key) {
+    return key.replace(/[^a-zA-Z0-9_-]/g, '_');
+}
+//# sourceMappingURL=sync.js.map

package/dist/sync.js.map

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

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@nexus_js/runtime",
+  "version": "0.6.0",
+  "description": "Nexus Islands runtime — selective hydration with fine-grained reactivity",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./island": {
+      "import": "./dist/island.js",
+      "types": "./dist/island.d.ts"
+    },
+    "./runes": {
+      "import": "./dist/runes.js",
+      "types": "./dist/runes.d.ts"
+    }
+  },
+  "dependencies": {
+    "@nexus_js/serialize": "0.6.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.5.0",
+    "vitest": "^2.0.0"
+  },
+  "license": "MIT",
+  "homepage": "https://nexusjs.dev",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/bierfor/nexus.git",
+    "directory": "packages/runtime"
+  },
+  "bugs": {
+    "url": "https://github.com/bierfor/nexus/issues"
+  },
+  "keywords": [
+    "nexus",
+    "framework",
+    "full-stack",
+    "svelte",
+    "islands",
+    "ssr",
+    "vite",
+    "server-actions"
+  ],
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsc -p tsconfig.json --watch",
+    "test": "vitest run --passWithNoTests",
+    "clean": "rm -rf dist"
+  }
+}