@koolbase/core 12.13.0 → 12.14.0

package/dist/cjs/offline-state.js

@@ -8,6 +8,8 @@ exports.readOfflineState = readOfflineState;
 exports.mutateOfflineState = mutateOfflineState;
 exports.queueWrite = queueWrite;
 exports.migrateLegacyQueue = migrateLegacyQueue;
+exports.rebaseHeldWrites = rebaseHeldWrites;
+exports.onOfflineStateChange = onOfflineStateChange;
 const platform_js_1 = require("./platform.js");
 const shared_js_1 = require("./shared.js");
 /**
@@ -141,6 +143,7 @@ async function mutateOfflineState(userId, mutate) {
         }
         await (0, platform_js_1.getPlatform)().storage.setItem(stateKey(userId), serialised);
     });
+    announce(userId);
 }
 /** Adds a write to the queue, under the user's lock. */
 async function queueWrite(userId, write) {
@@ -213,3 +216,70 @@ async function migrateLegacyQueue(userId) {
     });
     await (0, platform_js_1.getPlatform)().storage.removeItem(legacyQueueKey(userId));
 }
+/**
+ * Points the writes still queued for a record at the state it is now in.
+ *
+ * When a conflict is decided, the writes held behind it carry baselines
+ * describing the state the conflicted write would have produced -- a state
+ * that no longer exists, and may never have. Released unchanged they would
+ * replay against a revision that has moved on, and each would conflict in
+ * turn: one disagreement multiplying into as many conflicts as the user had
+ * queued. The same rule as the Flutter SDK's rebaseAfterResolution.
+ *
+ * Refreshing the baseline is enough because every operation is an absolute
+ * assignment: a patch says what a field becomes, not what to do to it. If a
+ * relative operation is ever added (an increment, an append), the chain must
+ * be replayed through its projected states instead.
+ */
+function rebaseHeldWrites(state, recordId, resolved, revision) {
+    let current = {};
+    for (const [k, v] of Object.entries(resolved)) {
+        if (!k.startsWith('$'))
+            current[k] = v;
+    }
+    for (const w of state.pending) {
+        if (w.recordId !== recordId)
+            continue;
+        w.baseline = { ...current };
+        w.baseRevision = revision;
+        // Each write is composed against the one before it.
+        if (w.operation === 'update')
+            current = { ...current, ...(w.data ?? {}) };
+        else if (w.operation === 'delete')
+            break;
+    }
+}
+// ─── Change notification ─────────────────────────────────────────────────────
+const ANNOUNCE_PREFIX = 'koolbase:offline-state:';
+function stateListeners() {
+    return (0, shared_js_1.shared)('offlineStateListeners', () => new Set());
+}
+/**
+ * Tells whoever is watching that a user's offline state changed -- here, and
+ * in every other copy of the SDK sharing this storage (other tabs). A badge in
+ * one tab must move when another tab's sync drains the queue.
+ */
+function announce(userId) {
+    for (const listener of [...stateListeners()]) {
+        try {
+            listener(userId);
+        }
+        catch { /* one broken listener must not stop the rest */ }
+    }
+    try {
+        (0, platform_js_1.getPlatform)().broadcast?.post(ANNOUNCE_PREFIX + userId);
+    }
+    catch { /* best effort */ }
+}
+/** Called with the user id whenever that user's offline state changes. */
+function onOfflineStateChange(listener) {
+    stateListeners().add(listener);
+    const off = (0, platform_js_1.getPlatform)().broadcast?.on((message) => {
+        if (message.startsWith(ANNOUNCE_PREFIX))
+            listener(message.slice(ANNOUNCE_PREFIX.length));
+    });
+    return () => {
+        stateListeners().delete(listener);
+        off?.();
+    };
+}

package/dist/cjs/platform.d.ts

@@ -12,6 +12,21 @@ export interface PlatformNetwork {
      * Koolbase is unreachable is handled the same as any failed request.
      */
     onChange(callback: (online: boolean) => void): () => void;
+    /**
+     * What the host believes right now: true online, false offline, null when
+     * it cannot tell. Optional: a host without it reports nothing until its
+     * first change, and connectivity stays 'unknown' until then.
+     */
+    current?(): Promise<boolean | null>;
+}
+/**
+ * A message to every other copy of the SDK sharing this storage -- other tabs
+ * of the same origin in a browser. Optional: one process (React Native) has no
+ * other copies to tell.
+ */
+export interface PlatformBroadcast {
+    post(message: string): void;
+    on(callback: (message: string) => void): () => void;
 }
 export interface PlatformLifecycle {
     /** Subscribe to the app moving to the background. Used to flush analytics. */
@@ -54,6 +69,7 @@ export interface PlatformAdapter {
     lifecycle: PlatformLifecycle;
     info: PlatformInfo;
     locks: PlatformLocks;
+    broadcast?: PlatformBroadcast;
     /**
      * The host's best persistent store for the auth session, or null if it has
      * none worth the name. Used only when the app injects nothing through

package/dist/cjs/react/use-record.d.ts

@@ -3,6 +3,6 @@ export interface UseRecordResult extends RecordState {
     /** The record again, from the server. What is shown stays while it runs, and stays if it fails. */
     refresh: () => Promise<void>;
 }
-export declare function createUseRecord(getDb: () => Pick<KoolbaseDatabase, 'get'>): (collection: string, id: string | null | undefined, options?: {
+export declare function createUseRecord(getDb: () => Pick<KoolbaseDatabase, 'get'> & Partial<Pick<KoolbaseDatabase, 'getSaved'>>): (collection: string, id: string | null | undefined, options?: {
     live?: boolean;
 }) => UseRecordResult;

package/dist/cjs/record-controller.d.ts

@@ -8,9 +8,14 @@ export interface RecordState {
     readonly error: unknown;
     /** True while refresh() runs. */
     readonly refreshing: boolean;
+    /**
+     * True while the record shown is the device's saved copy and the server has
+     * not confirmed it on this load. Stays true if the server cannot be reached.
+     */
+    readonly isSaved: boolean;
 }
 export declare const initialRecordState: RecordState;
-type RecordReader = Pick<KoolbaseDatabase, 'get'>;
+type RecordReader = Pick<KoolbaseDatabase, 'get'> & Partial<Pick<KoolbaseDatabase, 'getSaved'>>;
 export declare class KoolbaseRecordController {
     readonly collection: string;
     readonly id: string;
@@ -31,6 +36,8 @@ export declare class KoolbaseRecordController {
     subscribe(listener: () => void): () => void;
     /** The first load. Call once; refresh() for later loads. */
     load(): Promise<void>;
+    /** The device's saved copy, shown at once while the server is asked. */
+    private showSaved;
     /** The record again, from the server. What is shown stays while it runs, and stays if it fails. */
     refresh(): Promise<void>;
     /** Stops all updates. A result still in flight is dropped when it lands. */

package/dist/cjs/record-controller.js

@@ -15,8 +15,10 @@
 //    or landing after dispose(), is dropped.
 //  - live (the option): realtime events for THIS record only. An update
 //    re-reads it silently, once per burst; a delete is notFound at once.
-// Not yet: an offline fallback from the record cache, which keeps data and
-// revision but not createdAt or createdBy.
+//  - saved-first, never saved-only: the device's saved copy (db.getSaved)
+//    shows at once with isSaved true while the server is asked. Success
+//    replaces it (isSaved false); failure keeps it (isSaved stays true); not
+//    found is notFound. No saved copy: the ordinary loading/error states.
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.KoolbaseRecordController = exports.initialRecordState = void 0;
 const database_errors_js_1 = require("./database-errors.js");
@@ -26,6 +28,7 @@ exports.initialRecordState = Object.freeze({
     record: null,
     error: null,
     refreshing: false,
+    isSaved: false,
 });
 class KoolbaseRecordController {
     constructor(db, collection, id, options = {}) {
@@ -61,8 +64,27 @@ class KoolbaseRecordController {
         if (this.live && this.id) {
             this.unlive ?? (this.unlive = (0, live_source_js_1.liveSource)()?.subscribe(this.collection, (event) => this.onLive(event)) ?? null);
         }
+        await this.showSaved();
         await this.fetch();
     }
+    /** The device's saved copy, shown at once while the server is asked. */
+    async showSaved() {
+        if (!this.id || !this.db.getSaved)
+            return;
+        const gen = this.generation;
+        let saved = null;
+        try {
+            saved = await this.db.getSaved(this.id);
+        }
+        catch {
+            return;
+        }
+        if (!saved || this.isStale(gen) || this.state.status !== 'loading')
+            return;
+        if (saved.collection !== undefined && saved.collection !== this.collection)
+            return;
+        this.set({ status: 'loaded', record: saved, error: null, isSaved: true });
+    }
     /** The record again, from the server. What is shown stays while it runs, and stays if it fails. */
     async refresh() {
         if (this.disposed)
@@ -102,7 +124,7 @@ class KoolbaseRecordController {
                 this.liveTimer = null;
             }
             this.generation += 1;
-            this.set({ status: 'notFound', record: null, error: null, refreshing: false });
+            this.set({ status: 'notFound', record: null, error: null, refreshing: false, isSaved: false });
             return;
         }
         if (this.liveTimer)
@@ -117,7 +139,7 @@ class KoolbaseRecordController {
     async fetch() {
         const gen = ++this.generation;
         if (!this.id) {
-            this.set({ status: 'notFound', record: null, error: null });
+            this.set({ status: 'notFound', record: null, error: null, isSaved: false });
             return gen;
         }
         try {
@@ -125,17 +147,17 @@ class KoolbaseRecordController {
             if (this.isStale(gen))
                 return gen;
             if (record.collection !== undefined && record.collection !== this.collection) {
-                this.set({ status: 'notFound', record: null, error: null });
+                this.set({ status: 'notFound', record: null, error: null, isSaved: false });
             }
             else {
-                this.set({ status: 'loaded', record, error: null });
+                this.set({ status: 'loaded', record, error: null, isSaved: false });
             }
         }
         catch (error) {
             if (this.isStale(gen))
                 return gen;
             if (error instanceof database_errors_js_1.KoolbaseNotFoundError) {
-                this.set({ status: 'notFound', record: null, error: null });
+                this.set({ status: 'notFound', record: null, error: null, isSaved: false });
             }
             else if (this.state.record === null) {
                 this.set({ status: 'error', error });

package/dist/cjs/shared.d.ts

@@ -1,4 +1,5 @@
 interface Slot {
+    offlineStateListeners: Set<(userId: string) => void>;
     platform?: unknown;
     locks?: Map<string, Promise<unknown>>;
 }

package/dist/cjs/sync-engine.js

@@ -101,13 +101,21 @@ class SyncEngine {
             // being online — would give the same input different outcomes. It clears
             // the old key when done, so later calls find nothing and return.
             await (0, offline_state_js_1.migrateLegacyQueue)(userId);
-            const { pending } = await (0, offline_state_js_1.readOfflineState)(userId);
+            const { pending, conflicts } = await (0, offline_state_js_1.readOfflineState)(userId);
             if (pending.length === 0)
                 return;
             // Records whose chain stopped this pass. Writes queued after a conflicted
             // one were composed against the state it would have produced, so applying
             // them now would write against a state their baseline never described.
             const blocked = new Set();
+            // And records whose chain stopped in an EARLIER pass: a conflict waits
+            // for a decision across restarts, and so must the writes behind it.
+            // Seeded only from this pass's finds, the next pass replayed them
+            // against a state their baselines never described -- each becoming its
+            // own conflict. Deciding the conflict rebases and releases them.
+            for (const c of conflicts)
+                if (c.recordId)
+                    blocked.add(c.recordId);
             for (const queued of pending) {
                 if (queued.recordId && blocked.has(queued.recordId))
                     continue;
@@ -202,10 +210,15 @@ class SyncEngine {
                         // — cached at enqueue for a record the server refused to create.
                         // Left alone it is a phantom: it renders as saved, and an offline
                         // edit against it queues a write to a record that does not exist.
-                        // Evict it, and invalidate the collection so cached queries stop
-                        // serving it. The conflict above keeps the user's data and the
-                        // server's verdict; the cache stops testifying to a fiction.
-                        // MUTATION: phantom eviction removed
+                        // Evict it from the record cache and from every cached query that
+                        // holds it -- precisely, not by dropping the collection's saved
+                        // results, which a device still offline needs. The conflict above
+                        // keeps the user's data and the server's verdict; the cache stops
+                        // testifying to a fiction.
+                        if (write.operation === 'insert' && write.recordId) {
+                            await (0, cache_store_js_1.removeCachedRecord)(userId, write.recordId);
+                            await (0, cache_store_js_1.removeFromCachedQueries)(userId, write.collection, write.recordId);
+                        }
                         if (write.recordId)
                             blocked.add(write.recordId);
                         continue;

package/dist/esm/cache-store.d.ts

@@ -58,3 +58,17 @@ export declare function addToWriteQueue(userId: string, write: Omit<LegacyPendin
 export declare function removeFromWriteQueue(userId: string, writeId: string): Promise<void>;
 export declare function incrementWriteRetry(userId: string, writeId: string): Promise<void>;
 export declare function optimisticallyInsert(userId: string, collection: string, record: KoolbaseRecord): Promise<void>;
+/**
+ * The reverse of optimisticallyInsert: takes one record out of every cached
+ * result of a collection.
+ *
+ * Precise on purpose. Dropping the collection's cached results instead would
+ * leave a device that is still offline with no saved lists to show at all,
+ * to get rid of one record.
+ */
+export declare function removeFromCachedQueries(userId: string, collection: string, recordId: string): Promise<void>;
+/**
+ * Applies an offline edit to the record wherever a cached result holds it, so
+ * a saved list shows what the user just changed rather than what it was.
+ */
+export declare function updateInCachedQueries(userId: string, collection: string, recordId: string, data: Record<string, unknown>): Promise<void>;

package/dist/esm/cache-store.js

@@ -196,3 +196,65 @@ export async function optimisticallyInsert(userId, collection, record) {
         // ignore
     }
 }
+/**
+ * The reverse of optimisticallyInsert: takes one record out of every cached
+ * result of a collection.
+ *
+ * Precise on purpose. Dropping the collection's cached results instead would
+ * leave a device that is still offline with no saved lists to show at all,
+ * to get rid of one record.
+ */
+export async function removeFromCachedQueries(userId, collection, recordId) {
+    try {
+        const keys = await getPlatform().storage.getAllKeys();
+        const prefix = `koolbase:${CACHE_VERSION}:${userId}:${collection}:`;
+        for (const key of keys.filter(k => k.startsWith(prefix))) {
+            const raw = await getPlatform().storage.getItem(key);
+            if (!raw)
+                continue;
+            const cached = JSON.parse(raw);
+            if (!Array.isArray(cached.records))
+                continue;
+            const kept = cached.records.filter(r => r.id !== recordId);
+            const removed = cached.records.length - kept.length;
+            if (removed === 0)
+                continue;
+            cached.records = kept;
+            cached.total = Math.max(0, cached.total - removed);
+            await getPlatform().storage.setItem(key, JSON.stringify(cached));
+        }
+    }
+    catch {
+        // ignore
+    }
+}
+/**
+ * Applies an offline edit to the record wherever a cached result holds it, so
+ * a saved list shows what the user just changed rather than what it was.
+ */
+export async function updateInCachedQueries(userId, collection, recordId, data) {
+    try {
+        const keys = await getPlatform().storage.getAllKeys();
+        const prefix = `koolbase:${CACHE_VERSION}:${userId}:${collection}:`;
+        for (const key of keys.filter(k => k.startsWith(prefix))) {
+            const raw = await getPlatform().storage.getItem(key);
+            if (!raw)
+                continue;
+            const cached = JSON.parse(raw);
+            if (!Array.isArray(cached.records))
+                continue;
+            let changed = false;
+            cached.records = cached.records.map(r => {
+                if (r.id !== recordId)
+                    return r;
+                changed = true;
+                return { ...r, data: { ...(r.data ?? {}), ...data } };
+            });
+            if (changed)
+                await getPlatform().storage.setItem(key, JSON.stringify(cached));
+        }
+    }
+    catch {
+        // ignore
+    }
+}

package/dist/esm/connectivity.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Whether the device reports a network connection. A hint, not a promise that
+ * Koolbase is reachable: requests can still fail while online.
+ *
+ * 'unknown' until the platform first answers -- a real state, not a guess. An
+ * app should neither show "offline" nor run online-only logic on it.
+ */
+export type ConnectivityState = 'unknown' | 'online' | 'offline';
+/**
+ * The device's connectivity, as state an app can render: getState() for now,
+ * subscribe() for changes (the shape React's useSyncExternalStore takes).
+ */
+export declare class KoolbaseConnectivity {
+    private state;
+    private readonly listeners;
+    private stop;
+    private heard;
+    /** Starts following the platform. Called once by Koolbase.initialize. */
+    start(): void;
+    getState(): ConnectivityState;
+    /** Called on every change. Returns the unsubscribe. */
+    subscribe(listener: () => void): () => void;
+    dispose(): void;
+    private set;
+}

package/dist/esm/connectivity.js

@@ -0,0 +1,55 @@
+import { getPlatform } from './platform.js';
+/**
+ * The device's connectivity, as state an app can render: getState() for now,
+ * subscribe() for changes (the shape React's useSyncExternalStore takes).
+ */
+export class KoolbaseConnectivity {
+    constructor() {
+        this.state = 'unknown';
+        this.listeners = new Set();
+        this.stop = null;
+        // A change event is fresher than the first read: once one arrives, a late
+        // answer to that read is ignored.
+        this.heard = false;
+    }
+    /** Starts following the platform. Called once by Koolbase.initialize. */
+    start() {
+        if (this.stop)
+            return;
+        const network = getPlatform().network;
+        this.stop = network.onChange((online) => {
+            this.heard = true;
+            this.set(online ? 'online' : 'offline');
+        });
+        if (network.current) {
+            network.current().then((online) => {
+                if (!this.heard && online !== null && online !== undefined)
+                    this.set(online ? 'online' : 'offline');
+            }, () => { });
+        }
+    }
+    getState() {
+        return this.state;
+    }
+    /** Called on every change. Returns the unsubscribe. */
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => { this.listeners.delete(listener); };
+    }
+    dispose() {
+        this.stop?.();
+        this.stop = null;
+        this.listeners.clear();
+    }
+    set(next) {
+        if (next === this.state)
+            return;
+        this.state = next;
+        for (const listener of [...this.listeners]) {
+            try {
+                listener();
+            }
+            catch { /* one broken listener must not stop the rest */ }
+        }
+    }
+}

package/dist/esm/database.d.ts

@@ -119,6 +119,16 @@ export declare class KoolbaseDatabase {
      */
     batch(operations: BatchOp[]): Promise<BatchResult[]>;
     get(recordId: string): Promise<KoolbaseRecord>;
+    /**
+     * The device's saved copy of a record: what this device last read, with the
+     * changes queued on it applied. Never contacts the server. Null when there is
+     * none: never read here, or deleted on this device.
+     *
+     * For showing something at once while get() asks the server -- saved-first,
+     * never saved-only. Kept data and revision, not createdAt or createdBy, which
+     * the saved copy does not hold (empty strings here).
+     */
+    getSaved(recordId: string): Promise<KoolbaseRecord | null>;
     /**
      * Writes that could not be applied, waiting for a decision.
      *
@@ -134,6 +144,28 @@ export declare class KoolbaseDatabase {
      * moment matters. Snapshot, not a live handle; per-user.
      */
     pendingWrites(): Promise<PendingWrite[]>;
+    /**
+     * The pending writes now, and again whenever they change -- here, in another
+     * tab, or because the signed-in user changed. For a sync badge that reflects
+     * reality. null while signed out: per-user state has no answer then, and a
+     * fake empty list is how a badge says "all synced" while a user's changes
+     * sit queued. Returns the unsubscribe.
+     */
+    watchPendingWrites(listener: (writes: PendingWrite[] | null) => void): () => void;
+    /** The unresolved conflicts now, and again whenever they change. null while signed out. */
+    watchConflicts(listener: (conflicts: KoolbaseConflict[] | null) => void): () => void;
+    /**
+     * The signed-in user changed: every watcher reads again, for the new user
+     * (or null, signed out). Koolbase.initialize wires it to auth changes.
+     */
+    sessionChanged(): void;
+    private readonly stateWatchers;
+    private offStateChange;
+    /**
+     * One watcher: reads at once, then on every change to the signed-in user's
+     * offline state. Reads can finish out of order; only the latest delivers.
+     */
+    private watchState;
     /**
      * Count and total over a whole collection, with the read rule applied
      * inside the query.
@@ -173,6 +205,15 @@ export declare class KoolbaseDatabase {
      */
     private requireUserId;
     private requireConflict;
+    /**
+     * Removes a decided conflict and points the writes held behind it at the
+     * state the record is now in -- in one transaction, so the conflict can
+     * never be gone while its held writes still describe the old world.
+     *
+     * Without a known state (a refused add, a delete) there is nothing to
+     * rebase onto: the conflict is removed and the held writes stay as they are.
+     */
+    private settleConflict;
     private dropConflict;
     /**
      * Issues the resolving write, conditional on the revision the refusal