@nexus_js/sync 0.6.0 → 0.7.1

package/dist/engine.d.ts

@@ -0,0 +1,75 @@
+/**
+ * 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).
+ */
+export type SyncStatus = 'synced' | 'pending' | 'syncing' | 'error' | 'offline';
+export interface SyncOp<T = unknown> {
+    id: string;
+    store: string;
+    type: 'put' | 'delete';
+    key: string;
+    data?: T;
+    ts: number;
+    retries: number;
+}
+export interface ConflictInfo<T> {
+    local: T;
+    remote: T;
+    op: SyncOp<T>;
+}
+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;
+}
+export declare class NexusSyncEngine {
+    #private;
+    private db;
+    private flushing;
+    private listeners;
+    status: SyncStatus;
+    init(): Promise<void>;
+    private ensureDB;
+    /** Read the local (IndexedDB) value for a key in a collection. */
+    get<T>(collection: string, key: string): Promise<T | undefined>;
+    /** Read all values in a collection. */
+    getAll<T>(collection: string): Promise<T[]>;
+    /**
+     * Write a value locally (instant) and enqueue a server sync op.
+     * The UI is updated immediately — the server sync happens in the background.
+     */
+    put<T>(collection: string, key: string, value: T, endpoint: string): Promise<void>;
+    /** Delete locally and enqueue a delete op. */
+    delete(collection: string, key: string, endpoint: string): Promise<void>;
+    /**
+     * Flush pending ops to the server. Ops are sent in timestamp order.
+     * On conflict, `onConflict` is called and the local store is updated.
+     */
+    flush(endpoint?: string, opts?: Partial<SyncCollectionOpts<unknown>>): Promise<void>;
+    /** Returns the number of pending (unsynced) ops. */
+    pendingCount(): Promise<number>;
+    /** Subscribe to status changes (useful for UI indicators). */
+    subscribe(cb: () => void): () => void;
+}
+declare global {
+    interface Window {
+        __NEXUS_DEV__?: boolean;
+    }
+}
+/** Singleton engine instance (shared across all $sync calls on a page). */
+export declare const syncEngine: NexusSyncEngine;
+//# sourceMappingURL=engine.d.ts.map

package/dist/engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../src/engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAMH,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,SAAS,GAAG,SAAS,GAAG,OAAO,GAAG,SAAS,CAAC;AAEhF,MAAM,WAAW,MAAM,CAAC,CAAC,GAAG,OAAO;IACjC,EAAE,EAAS,MAAM,CAAC;IAClB,KAAK,EAAM,MAAM,CAAC;IAClB,IAAI,EAAO,KAAK,GAAG,QAAQ,CAAC;IAC5B,GAAG,EAAQ,MAAM,CAAC;IAClB,IAAI,CAAC,EAAM,CAAC,CAAC;IACb,EAAE,EAAS,MAAM,CAAC;IAClB,OAAO,EAAI,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,YAAY,CAAC,CAAC;IAC7B,KAAK,EAAK,CAAC,CAAC;IACZ,MAAM,EAAI,CAAC,CAAC;IACZ,EAAE,EAAQ,MAAM,CAAC,CAAC,CAAC,CAAC;CACrB;AAED,MAAM,WAAW,kBAAkB,CAAC,CAAC;IACnC,4EAA4E;IAC5E,QAAQ,EAAK,MAAM,CAAC;IACpB;;;OAGG;IACH,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,YAAY,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IACvD,4EAA4E;IAC5E,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AA4DD,qBAAa,eAAe;;IAC1B,OAAO,CAAC,EAAE,CAAmC;IAC7C,OAAO,CAAC,QAAQ,CAA8B;IAC9C,OAAO,CAAC,SAAS,CAAiC;IAClD,MAAM,EAAE,UAAU,CAAY;IAExB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAQ3B,OAAO,CAAC,QAAQ;IAKhB,kEAAkE;IAC5D,GAAG,CAAC,CAAC,EAAE,UAAU,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC;IAIrE,uCAAuC;IACjC,MAAM,CAAC,CAAC,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC;IASjD;;;OAGG;IACG,GAAG,CAAC,CAAC,EACT,UAAU,EAAE,MAAM,EAClB,GAAG,EAAS,MAAM,EAClB,KAAK,EAAO,CAAC,EACb,QAAQ,EAAI,MAAM,GACjB,OAAO,CAAC,IAAI,CAAC;IAqBhB,8CAA8C;IACxC,MAAM,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAiB9E;;;OAGG;IACG,KAAK,CAAC,QAAQ,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,CAAC,kBAAkB,CAAC,OAAO,CAAC,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IA2E1F,oDAAoD;IAC9C,YAAY,IAAI,OAAO,CAAC,MAAM,CAAC;IAKrC,8DAA8D;IAC9D,SAAS,CAAC,EAAE,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI;CA4BtC;AAED,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,MAAM;QAAG,aAAa,CAAC,EAAE,OAAO,CAAC;KAAE;CAC9C;AAED,2EAA2E;AAC3E,eAAO,MAAM,UAAU,iBAAwB,CAAC"}

package/dist/engine.js

@@ -0,0 +1,250 @@
+/**
+ * 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' };
+// ── IDB helpers ───────────────────────────────────────────────────────────────
+function openDB() {
+    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(db, storeName, key) {
+    return new Promise((resolve, reject) => {
+        const tx = db.transaction(storeName, 'readonly');
+        const req = tx.objectStore(storeName).get(key);
+        req.onsuccess = () => resolve(req.result);
+        req.onerror = () => reject(req.error);
+    });
+}
+function idbPut(db, storeName, key, value) {
+    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, storeName, key) {
+    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(db, storeName) {
+    return new Promise((resolve, reject) => {
+        const tx = db.transaction(storeName, 'readonly');
+        const req = tx.objectStore(storeName).getAll();
+        req.onsuccess = () => resolve(req.result);
+        req.onerror = () => reject(req.error);
+    });
+}
+// ── Sync Engine ───────────────────────────────────────────────────────────────
+export class NexusSyncEngine {
+    db = null;
+    flushing = false;
+    listeners = new Set();
+    status = 'synced';
+    async init() {
+        if (this.db)
+            return;
+        this.db = await openDB();
+        this.#startNetworkWatcher();
+        // Flush any ops that survived a page refresh
+        if (navigator.onLine)
+            void this.flush();
+    }
+    ensureDB() {
+        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(collection, key) {
+        return idbGet(this.ensureDB(), STORES.data, `${collection}:${key}`);
+    }
+    /** Read all values in a collection. */
+    async getAll(collection) {
+        const db = this.ensureDB();
+        const all = await idbGetAll(db, STORES.data);
+        const prefix = `${collection}:`;
+        return all
+            .filter((r) => r._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(collection, key, value, endpoint) {
+        const db = this.ensureDB();
+        // 1. Persist locally
+        await idbPut(db, STORES.data, `${collection}:${key}`, value);
+        // 2. Enqueue sync op
+        const op = {
+            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, key, endpoint) {
+        const db = this.ensureDB();
+        await idbDelete(db, STORES.data, `${collection}:${key}`);
+        const op = {
+            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, opts) {
+        if (this.flushing || !navigator.onLine)
+            return;
+        const db = this.ensureDB();
+        const ops = (await idbGetAll(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());
+            // 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,
+                        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 = { ...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() {
+        const ops = await idbGetAll(this.ensureDB(), STORES.ops);
+        return ops.length;
+    }
+    /** Subscribe to status changes (useful for UI indicators). */
+    subscribe(cb) {
+        this.listeners.add(cb);
+        return () => this.listeners.delete(cb);
+    }
+    #setStatus(s) {
+        this.status = s;
+    }
+    #notify() {
+        for (const cb of this.listeners)
+            cb();
+    }
+    #startNetworkWatcher() {
+        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');
+            }
+        });
+    }
+}
+/** Singleton engine instance (shared across all $sync calls on a page). */
+export const syncEngine = new NexusSyncEngine();
+//# sourceMappingURL=engine.js.map

package/dist/engine.js.map

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

package/{src/index.ts → dist/index.d.ts}

@@ -4,22 +4,12 @@
  * 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;
-
+export declare const isOnline: () => boolean;
 /** 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);
-  });
-}
+export declare function waitForOnline(): Promise<void>;
+//# 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;;;;;GAKG;AAEH,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC1D,YAAY,EAAE,MAAM,EAAE,UAAU,EAAE,kBAAkB,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAExF,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AACvC,YAAY,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAE/D,6DAA6D;AAC7D,eAAO,MAAM,QAAQ,QAAO,OACgC,CAAC;AAE7D,0EAA0E;AAC1E,wBAAgB,aAAa,IAAI,OAAO,CAAC,IAAI,CAAC,CAM7C"}

package/dist/index.js

@@ -0,0 +1,20 @@
+/**
+ * @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 { $localSync } from './rune.js';
+/** Convenience: check if the browser is currently online. */
+export const isOnline = () => typeof navigator !== 'undefined' ? navigator.onLine : true;
+/** Returns a promise that resolves when the browser comes back online. */
+export function waitForOnline() {
+    if (isOnline())
+        return Promise.resolve();
+    return new Promise((resolve) => {
+        const handler = () => { window.removeEventListener('online', handler); resolve(); };
+        window.addEventListener('online', handler);
+    });
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAG1D,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAGvC,6DAA6D;AAC7D,MAAM,CAAC,MAAM,QAAQ,GAAG,GAAY,EAAE,CACpC,OAAO,SAAS,KAAK,WAAW,CAAC,CAAC,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC;AAE7D,0EAA0E;AAC1E,MAAM,UAAU,aAAa;IAC3B,IAAI,QAAQ,EAAE;QAAE,OAAO,OAAO,CAAC,OAAO,EAAE,CAAC;IACzC,OAAO,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE;QACnC,MAAM,OAAO,GAAG,GAAG,EAAE,GAAG,MAAM,CAAC,mBAAmB,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC;QACpF,MAAM,CAAC,gBAAgB,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;IAC7C,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/rune.d.ts

@@ -0,0 +1,67 @@
+/**
+ * $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 { type SyncCollectionOpts, type SyncStatus } from './engine.js';
+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 declare function $localSync<T>(collection: string, opts: LocalSyncOpts<T>): LocalSyncState<T>;
+//# sourceMappingURL=rune.d.ts.map

package/dist/rune.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rune.d.ts","sourceRoot":"","sources":["../src/rune.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,EAAc,KAAK,kBAAkB,EAAE,KAAK,UAAU,EAAE,MAAM,aAAa,CAAC;AASnF,MAAM,WAAW,cAAc,CAAC,CAAC;IAC/B,2EAA2E;IAC3E,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC;IAClB,2BAA2B;IAC3B,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B,wBAAwB;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,oDAAoD;IACpD,GAAG,CAAC,IAAI,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5B;;;OAGG;IACH,IAAI,CAAC,IAAI,EAAE,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,EAAE,GAAG,CAAC,GAAG,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7D,MAAM,CAAC,SAAS,EAAE,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,EAAE,GAAG,CAAC,IAAI,EAAE,CAAC,KAAK,OAAO,GAAG,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACvF,wCAAwC;IACxC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,kEAAkE;IAClE,SAAS,CAAC,EAAE,EAAE,CAAC,KAAK,EAAE,cAAc,CAAC,CAAC,CAAC,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;CAC/D;AAED,MAAM,WAAW,aAAa,CAAC,CAAC,CAAE,SAAQ,OAAO,CAAC,kBAAkB,CAAC,CAAC,CAAC,CAAC;IACtE,oDAAoD;IACpD,OAAO,EAAE,CAAC,CAAC;IACX,sCAAsC;IACtC,QAAQ,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAC1B,UAAU,EAAE,MAAM,EAClB,IAAI,EAAQ,aAAa,CAAC,CAAC,CAAC,GAC3B,cAAc,CAAC,CAAC,CAAC,CA4DnB"}

package/dist/rune.js

@@ -0,0 +1,96 @@
+/**
+ * $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 } from './engine.js';
+let engineReady = null;
+function ensureEngine() {
+    if (!engineReady)
+        engineReady = syncEngine.init();
+    return engineReady;
+}
+/**
+ * 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(collection, opts) {
+    const storeKey = opts.key ?? 'default';
+    let current = opts.default;
+    let status = 'synced';
+    let pending = 0;
+    const subs = new Set();
+    function notify() {
+        for (const cb of subs)
+            cb(state);
+    }
+    // Load initial value from IndexedDB
+    ensureEngine().then(async () => {
+        const stored = await syncEngine.get(collection, storeKey);
+        if (stored !== undefined) {
+            current = stored;
+            notify();
+        }
+        // Track engine status
+        syncEngine.subscribe(async () => {
+            status = syncEngine.status;
+            pending = await syncEngine.pendingCount();
+            notify();
+        });
+    });
+    const state = {
+        get value() { return current; },
+        get status() { return status; },
+        get pending() { return pending; },
+        async set(next) {
+            current = next;
+            notify();
+            await ensureEngine();
+            await syncEngine.put(collection, storeKey, next, opts.endpoint);
+        },
+        async push(item) {
+            if (!Array.isArray(current))
+                throw new Error('[Nexus Sync] .push() requires an array value');
+            await state.set([...current, item]);
+        },
+        async remove(predicate) {
+            if (!Array.isArray(current))
+                throw new Error('[Nexus Sync] .remove() requires an array value');
+            await state.set(current.filter((i) => !predicate(i)));
+        },
+        async flush() {
+            await ensureEngine();
+            await syncEngine.flush(opts.endpoint, opts);
+        },
+        subscribe(cb) {
+            subs.add(cb);
+            return () => subs.delete(cb);
+        },
+    };
+    return state;
+}
+//# sourceMappingURL=rune.js.map

package/dist/rune.js.map

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

package/package.json

@@ -1,11 +1,15 @@
 {
   "name": "@nexus_js/sync",
-  "version": "0.6.0",
+  "version": "0.7.1",
   "description": "Nexus Local-First Sync Engine — IndexedDB-backed optimistic mutations with conflict resolution",
   "type": "module",
-  "main": "./src/index.ts",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
   "exports": {
-    ".": "./src/index.ts"
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
   },
   "keywords": [
     "nexus",
@@ -31,12 +35,21 @@
   "bugs": {
     "url": "https://github.com/bierfor/nexus/issues"
   },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.5.0"
+  },
   "files": [
-    "src",
+    "dist",
     "README.md"
   ],
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsc -p tsconfig.json --watch",
+    "clean": "rm -rf dist"
   }
 }

package/src/engine.ts

@@ -1,309 +0,0 @@
-/**
- * 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/rune.ts

@@ -1,140 +0,0 @@
-/**
- * $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;
-}