@nexus_js/sync 0.6.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nexus Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,17 @@
+# @nexus_js/sync
+
+Nexus Local-First Sync Engine — IndexedDB-backed optimistic mutations with conflict resolution.
+
+## Documentation
+
+All guides, API reference, and examples live on **[nexusjs.dev](https://nexusjs.dev)**.
+
+## Links
+
+- **Website:** [https://nexusjs.dev](https://nexusjs.dev)
+- **Repository:** [github.com/bierfor/nexus](https://github.com/bierfor/nexus) (see `packages/sync/`)
+- **Issues:** [github.com/bierfor/nexus/issues](https://github.com/bierfor/nexus/issues)
+
+## License
+
+MIT © Nexus contributors

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@nexus_js/sync",
+  "version": "0.6.0",
+  "description": "Nexus Local-First Sync Engine — IndexedDB-backed optimistic mutations with conflict resolution",
+  "type": "module",
+  "main": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "keywords": [
+    "nexus",
+    "local-first",
+    "sync",
+    "indexeddb",
+    "offline",
+    "framework",
+    "full-stack",
+    "svelte",
+    "islands",
+    "ssr",
+    "vite",
+    "server-actions"
+  ],
+  "license": "MIT",
+  "homepage": "https://nexusjs.dev",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/bierfor/nexus.git",
+    "directory": "packages/sync"
+  },
+  "bugs": {
+    "url": "https://github.com/bierfor/nexus/issues"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}

package/src/engine.ts

@@ -0,0 +1,309 @@
+/**
+ * Nexus Local-First Sync Engine.
+ *
+ * Inspired by Replicache / ElectricSQL. Uses IndexedDB as the local store.
+ *
+ * Guarantees:
+ *  - Writes are immediate (IndexedDB) — zero perceived latency for the user.
+ *  - A "pending ops" queue is maintained. When online, ops are flushed to the
+ *    server. When offline, they accumulate and are retried on reconnect.
+ *  - Conflict resolution is pluggable via onConflict hook.
+ *  - All pending ops survive page refreshes (persisted in IDB, not memory).
+ */
+
+const DB_NAME    = 'nexus_sync';
+const DB_VERSION = 1;
+const STORES     = { data: 'data', ops: 'pending_ops' } as const;
+
+export type SyncStatus = 'synced' | 'pending' | 'syncing' | 'error' | 'offline';
+
+export interface SyncOp<T = unknown> {
+  id:        string;           // uuid for idempotency
+  store:     string;           // logical collection name
+  type:      'put' | 'delete'; // operation type
+  key:       string;           // record key within collection
+  data?:     T;                // payload (undefined for deletes)
+  ts:        number;           // client timestamp (for ordering)
+  retries:   number;           // how many sync attempts have failed
+}
+
+export interface ConflictInfo<T> {
+  local:    T;             // what the client has
+  remote:   T;             // what the server returned
+  op:       SyncOp<T>;    // the pending op that caused the conflict
+}
+
+export interface SyncCollectionOpts<T> {
+  /** Server endpoint to flush ops to (POST). Receives `{ ops: SyncOp[] }`. */
+  endpoint:    string;
+  /**
+   * Called when the server returns a conflict for an op.
+   * Return the version that should win. Default: local wins.
+   */
+  onConflict?: (info: ConflictInfo<T>) => T | Promise<T>;
+  /** Max retries before an op is moved to "dead letter" (logged, dropped). */
+  maxRetries?: number;
+}
+
+// ── IDB helpers ───────────────────────────────────────────────────────────────
+
+function openDB(): Promise<IDBDatabase> {
+  return new Promise((resolve, reject) => {
+    const req = indexedDB.open(DB_NAME, DB_VERSION);
+    req.onupgradeneeded = () => {
+      const db = req.result;
+      if (!db.objectStoreNames.contains(STORES.data)) {
+        db.createObjectStore(STORES.data);
+      }
+      if (!db.objectStoreNames.contains(STORES.ops)) {
+        const ops = db.createObjectStore(STORES.ops, { keyPath: 'id' });
+        ops.createIndex('store', 'store');
+      }
+    };
+    req.onsuccess = () => resolve(req.result);
+    req.onerror   = () => reject(req.error);
+  });
+}
+
+function idbGet<T>(db: IDBDatabase, storeName: string, key: string): Promise<T | undefined> {
+  return new Promise((resolve, reject) => {
+    const tx  = db.transaction(storeName, 'readonly');
+    const req = tx.objectStore(storeName).get(key);
+    req.onsuccess = () => resolve(req.result as T | undefined);
+    req.onerror   = () => reject(req.error);
+  });
+}
+
+function idbPut(db: IDBDatabase, storeName: string, key: string, value: unknown): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const tx  = db.transaction(storeName, 'readwrite');
+    const req = tx.objectStore(storeName).put(value, key);
+    req.onsuccess = () => resolve();
+    req.onerror   = () => reject(req.error);
+  });
+}
+
+function idbDelete(db: IDBDatabase, storeName: string, key: string): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const tx  = db.transaction(storeName, 'readwrite');
+    const req = tx.objectStore(storeName).delete(key);
+    req.onsuccess = () => resolve();
+    req.onerror   = () => reject(req.error);
+  });
+}
+
+function idbGetAll<T>(db: IDBDatabase, storeName: string): Promise<T[]> {
+  return new Promise((resolve, reject) => {
+    const tx  = db.transaction(storeName, 'readonly');
+    const req = tx.objectStore(storeName).getAll();
+    req.onsuccess = () => resolve(req.result as T[]);
+    req.onerror   = () => reject(req.error);
+  });
+}
+
+// ── Sync Engine ───────────────────────────────────────────────────────────────
+
+export class NexusSyncEngine {
+  private db:        IDBDatabase | null = null;
+  private flushing:  boolean            = false;
+  private listeners: Set<() => void>    = new Set();
+  status: SyncStatus = 'synced';
+
+  async init(): Promise<void> {
+    if (this.db) return;
+    this.db = await openDB();
+    this.#startNetworkWatcher();
+    // Flush any ops that survived a page refresh
+    if (navigator.onLine) void this.flush();
+  }
+
+  private ensureDB(): IDBDatabase {
+    if (!this.db) throw new Error('[Nexus Sync] Engine not initialized. Call await sync.init()');
+    return this.db;
+  }
+
+  /** Read the local (IndexedDB) value for a key in a collection. */
+  async get<T>(collection: string, key: string): Promise<T | undefined> {
+    return idbGet<T>(this.ensureDB(), STORES.data, `${collection}:${key}`);
+  }
+
+  /** Read all values in a collection. */
+  async getAll<T>(collection: string): Promise<T[]> {
+    const db   = this.ensureDB();
+    const all  = await idbGetAll<{ key: string; value: T }>(db, STORES.data);
+    const prefix = `${collection}:`;
+    return all
+      .filter((r) => (r as unknown as { _idbKey?: string })._idbKey?.startsWith(prefix) ?? false)
+      .map((r) => r.value);
+  }
+
+  /**
+   * Write a value locally (instant) and enqueue a server sync op.
+   * The UI is updated immediately — the server sync happens in the background.
+   */
+  async put<T>(
+    collection: string,
+    key:        string,
+    value:      T,
+    endpoint:   string,
+  ): Promise<void> {
+    const db = this.ensureDB();
+    // 1. Persist locally
+    await idbPut(db, STORES.data, `${collection}:${key}`, value);
+    // 2. Enqueue sync op
+    const op: SyncOp<T> = {
+      id:      crypto.randomUUID(),
+      store:   collection,
+      type:    'put',
+      key,
+      data:    value,
+      ts:      Date.now(),
+      retries: 0,
+    };
+    await idbPut(db, STORES.ops, op.id, op);
+    this.#setStatus('pending');
+    this.#notify();
+    // 3. Try to flush immediately if online
+    if (navigator.onLine) void this.flush(endpoint);
+  }
+
+  /** Delete locally and enqueue a delete op. */
+  async delete(collection: string, key: string, endpoint: string): Promise<void> {
+    const db = this.ensureDB();
+    await idbDelete(db, STORES.data, `${collection}:${key}`);
+    const op: SyncOp = {
+      id:      crypto.randomUUID(),
+      store:   collection,
+      type:    'delete',
+      key,
+      ts:      Date.now(),
+      retries: 0,
+    };
+    await idbPut(db, STORES.ops, op.id, op);
+    this.#setStatus('pending');
+    this.#notify();
+    if (navigator.onLine) void this.flush(endpoint);
+  }
+
+  /**
+   * Flush pending ops to the server. Ops are sent in timestamp order.
+   * On conflict, `onConflict` is called and the local store is updated.
+   */
+  async flush(endpoint?: string, opts?: Partial<SyncCollectionOpts<unknown>>): Promise<void> {
+    if (this.flushing || !navigator.onLine) return;
+    const db  = this.ensureDB();
+    const ops = (await idbGetAll<SyncOp>(db, STORES.ops))
+      .sort((a, b) => a.ts - b.ts);
+
+    if (ops.length === 0) {
+      this.#setStatus('synced');
+      return;
+    }
+
+    this.flushing = true;
+    this.#setStatus('syncing');
+
+    const maxRetries = opts?.maxRetries ?? 5;
+    const url = endpoint ?? ops[0]?.store ?? '';
+
+    try {
+      const res = await fetch(url, {
+        method:  'POST',
+        headers: { 'content-type': 'application/json', 'x-nexus-sync': '1' },
+        body:    JSON.stringify({ ops }),
+      });
+
+      if (!res.ok) throw new Error(`Server returned ${res.status}`);
+
+      const body = (await res.json()) as {
+        acked:     string[];
+        conflicts: Array<{ opId: string; serverValue: unknown }>;
+      };
+
+      // Acknowledge successful ops
+      for (const id of body.acked ?? []) {
+        await idbDelete(db, STORES.ops, id);
+      }
+
+      // Handle conflicts
+      for (const conflict of body.conflicts ?? []) {
+        const op = ops.find((o) => o.id === conflict.opId);
+        if (!op) continue;
+        if (opts?.onConflict) {
+          const localValue  = await this.get(op.store, op.key);
+          const winner = await opts.onConflict({
+            local:  localValue as unknown,
+            remote: conflict.serverValue,
+            op,
+          });
+          await idbPut(db, STORES.data, `${op.store}:${op.key}`, winner);
+        } else {
+          // Default: local wins — re-enqueue with fresh timestamp
+          const updated: SyncOp = { ...op, ts: Date.now() };
+          await idbPut(db, STORES.ops, updated.id, updated);
+        }
+      }
+
+      this.#setStatus('synced');
+    } catch {
+      // Increment retries on all remaining ops
+      for (const op of ops) {
+        const updated = { ...op, retries: op.retries + 1 };
+        if (updated.retries >= maxRetries) {
+          // Dead letter — drop and warn
+          console.warn(`[Nexus Sync] Op ${op.id} exceeded max retries, dropping.`, op);
+          await idbDelete(db, STORES.ops, op.id);
+        } else {
+          await idbPut(db, STORES.ops, op.id, updated);
+        }
+      }
+      this.#setStatus(navigator.onLine ? 'error' : 'offline');
+    } finally {
+      this.flushing = false;
+      this.#notify();
+    }
+  }
+
+  /** Returns the number of pending (unsynced) ops. */
+  async pendingCount(): Promise<number> {
+    const ops = await idbGetAll<SyncOp>(this.ensureDB(), STORES.ops);
+    return ops.length;
+  }
+
+  /** Subscribe to status changes (useful for UI indicators). */
+  subscribe(cb: () => void): () => void {
+    this.listeners.add(cb);
+    return () => this.listeners.delete(cb);
+  }
+
+  #setStatus(s: SyncStatus): void {
+    this.status = s;
+  }
+
+  #notify(): void {
+    for (const cb of this.listeners) cb();
+  }
+
+  #startNetworkWatcher(): void {
+    window.addEventListener('online', () => {
+      if (window.__NEXUS_DEV__) {
+        console.log('%c[Nexus Sync]%c 🟢 Back online — flushing pending ops...', 'color:#818cf8;font-weight:bold', 'color:#a3e635');
+      }
+      void this.flush();
+    });
+    window.addEventListener('offline', () => {
+      this.#setStatus('offline');
+      this.#notify();
+      if (window.__NEXUS_DEV__) {
+        console.log('%c[Nexus Sync]%c 🔴 Offline — writes queued in IndexedDB', 'color:#818cf8;font-weight:bold', 'color:#f87171');
+      }
+    });
+  }
+}
+
+declare global {
+  interface Window { __NEXUS_DEV__?: boolean; }
+}
+
+/** Singleton engine instance (shared across all $sync calls on a page). */
+export const syncEngine = new NexusSyncEngine();

package/src/index.ts

@@ -0,0 +1,25 @@
+/**
+ * @nexus_js/sync — Local-First Sync Engine
+ *
+ * Provides offline-first data persistence and background synchronization
+ * using IndexedDB as the local store and Server Actions as the sync target.
+ */
+
+export { syncEngine, NexusSyncEngine } from './engine.js';
+export type { SyncOp, SyncStatus, SyncCollectionOpts, ConflictInfo } from './engine.js';
+
+export { $localSync } from './rune.js';
+export type { LocalSyncState, LocalSyncOpts } from './rune.js';
+
+/** Convenience: check if the browser is currently online. */
+export const isOnline = (): boolean =>
+  typeof navigator !== 'undefined' ? navigator.onLine : true;
+
+/** Returns a promise that resolves when the browser comes back online. */
+export function waitForOnline(): Promise<void> {
+  if (isOnline()) return Promise.resolve();
+  return new Promise<void>((resolve) => {
+    const handler = () => { window.removeEventListener('online', handler); resolve(); };
+    window.addEventListener('online', handler);
+  });
+}

package/src/rune.ts

@@ -0,0 +1,140 @@
+/**
+ * $localSync — the Local-First reactive rune.
+ *
+ * Usage (inside a .nx island):
+ *
+ * ```ts
+ * import { $localSync } from '@nexus_js/sync';
+ *
+ * const captures = $localSync<string[]>('my-captures', {
+ *   default: [],
+ *   endpoint: '/_nexus/action/sync-captures',
+ *   onConflict: ({ local, remote }) => [...new Set([...local, ...remote])],
+ * });
+ *
+ * // Read — always reflects local IndexedDB state
+ * console.log(captures.value);
+ *
+ * // Mutate — instant UI update, background server sync
+ * await captures.add('pikachu');
+ * await captures.remove('pikachu');
+ * ```
+ *
+ * The framework automatically:
+ *  - Persists every mutation to IndexedDB (works offline).
+ *  - Syncs to the server when online.
+ *  - Retries failed syncs on reconnect.
+ *  - Calls onConflict if the server disagrees.
+ */
+
+import { syncEngine, type SyncCollectionOpts, type SyncStatus } from './engine.js';
+
+let engineReady: Promise<void> | null = null;
+
+function ensureEngine(): Promise<void> {
+  if (!engineReady) engineReady = syncEngine.init();
+  return engineReady;
+}
+
+export interface LocalSyncState<T> {
+  /** Current value (IndexedDB, reflects all local mutations immediately). */
+  readonly value: T;
+  /** Current sync status. */
+  readonly status: SyncStatus;
+  /** Pending op count. */
+  readonly pending: number;
+  /** Overwrite entire value and enqueue a sync op. */
+  set(next: T): Promise<void>;
+  /**
+   * Array helpers — only valid when T extends unknown[].
+   * push/remove mutate the local array atomically.
+   */
+  push(item: T extends (infer I)[] ? I : never): Promise<void>;
+  remove(predicate: T extends (infer I)[] ? (item: I) => boolean : never): Promise<void>;
+  /** Force an immediate flush attempt. */
+  flush(): Promise<void>;
+  /** Subscribe to value/status changes (returns unsubscribe fn). */
+  subscribe(cb: (state: LocalSyncState<T>) => void): () => void;
+}
+
+export interface LocalSyncOpts<T> extends Partial<SyncCollectionOpts<T>> {
+  /** Default value used before IndexedDB is ready. */
+  default: T;
+  /** Server endpoint to sync ops to. */
+  endpoint: string;
+  /**
+   * Unique key for this value within the collection.
+   * Defaults to 'default'. Useful to scope per-user data.
+   */
+  key?: string;
+}
+
+/**
+ * Creates a Local-First reactive state container.
+ * The returned object is reactive — UI should re-render on .value access
+ * (integration with Svelte 5 Runes happens at the compiler layer).
+ */
+export function $localSync<T>(
+  collection: string,
+  opts:       LocalSyncOpts<T>,
+): LocalSyncState<T> {
+  const storeKey = opts.key ?? 'default';
+  let   current  = opts.default;
+  let   status:  SyncStatus = 'synced';
+  let   pending  = 0;
+  const subs     = new Set<(s: LocalSyncState<T>) => void>();
+
+  function notify(): void {
+    for (const cb of subs) cb(state);
+  }
+
+  // Load initial value from IndexedDB
+  ensureEngine().then(async () => {
+    const stored = await syncEngine.get<T>(collection, storeKey);
+    if (stored !== undefined) {
+      current = stored;
+      notify();
+    }
+    // Track engine status
+    syncEngine.subscribe(async () => {
+      status  = syncEngine.status;
+      pending = await syncEngine.pendingCount();
+      notify();
+    });
+  });
+
+  const state: LocalSyncState<T> = {
+    get value()   { return current; },
+    get status()  { return status; },
+    get pending() { return pending; },
+
+    async set(next: T): Promise<void> {
+      current = next;
+      notify();
+      await ensureEngine();
+      await syncEngine.put(collection, storeKey, next, opts.endpoint);
+    },
+
+    async push(item): Promise<void> {
+      if (!Array.isArray(current)) throw new Error('[Nexus Sync] .push() requires an array value');
+      await state.set([...current, item] as T);
+    },
+
+    async remove(predicate): Promise<void> {
+      if (!Array.isArray(current)) throw new Error('[Nexus Sync] .remove() requires an array value');
+      await state.set((current as unknown[]).filter((i) => !(predicate as (x: unknown) => boolean)(i)) as T);
+    },
+
+    async flush(): Promise<void> {
+      await ensureEngine();
+      await syncEngine.flush(opts.endpoint, opts as Partial<SyncCollectionOpts<unknown>>);
+    },
+
+    subscribe(cb): () => void {
+      subs.add(cb);
+      return () => subs.delete(cb);
+    },
+  };
+
+  return state;
+}