@koolbase/core 12.6.0 → 12.8.0

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

@@ -38,6 +38,7 @@ export declare class KoolbaseCollectionController {
     private pageOne;
     private laterPages;
     private nextOffset;
+    private unregister;
     constructor(db: QueryReader, collection: string, query?: CollectionQuery);
     getState(): CollectionState;
     /** Called on every change. Returns the unsubscribe. */
@@ -46,6 +47,12 @@ export declare class KoolbaseCollectionController {
     load(): Promise<void>;
     /** Page one again, from the server. What is shown stays while it runs, and stays if it fails. */
     refresh(): Promise<void>;
+    /**
+     * After a write to this collection: page one again from the server,
+     * SILENTLY -- no `refreshing`, which is the user's pull-to-refresh. What is
+     * shown stays while it runs, and stays if it fails.
+     */
+    private refreshAfterWrite;
     /**
      * The next page, appended. Does nothing unless loaded with more to load.
      * If rows are added or removed on the server between pages, one can be

package/dist/cjs/collection-controller.js

@@ -25,6 +25,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.KoolbaseCollectionController = exports.initialCollectionState = void 0;
 exports.collectionQueryKey = collectionQueryKey;
+const query_refresh_js_1 = require("./query-refresh.js");
 exports.initialCollectionState = Object.freeze({
     status: 'loading',
     records: Object.freeze([]),
@@ -73,6 +74,8 @@ class KoolbaseCollectionController {
         // Where the next page starts on the server. Not records.length: once rows
         // are de-duplicated, a shifted page could otherwise be requested forever.
         this.nextOffset = 0;
+        // A write to this collection re-runs this query (query-refresh.ts).
+        this.unregister = null;
         this.db = db;
         this.collection = collection;
         this.spec = query;
@@ -93,6 +96,7 @@ class KoolbaseCollectionController {
     async load() {
         if (this.disposed)
             return;
+        this.unregister ?? (this.unregister = (0, query_refresh_js_1.registerQueryRefresher)(this.collection, () => this.refreshAfterWrite()));
         await this.firstPage('default');
     }
     /** Page one again, from the server. What is shown stays while it runs, and stays if it fails. */
@@ -104,6 +108,16 @@ class KoolbaseCollectionController {
         if (!this.isStale(gen))
             this.set({ refreshing: false });
     }
+    /**
+     * After a write to this collection: page one again from the server,
+     * SILENTLY -- no `refreshing`, which is the user's pull-to-refresh. What is
+     * shown stays while it runs, and stays if it fails.
+     */
+    async refreshAfterWrite() {
+        if (this.disposed)
+            return;
+        await this.firstPage('network-only');
+    }
     /**
      * The next page, appended. Does nothing unless loaded with more to load.
      * If rows are added or removed on the server between pages, one can be
@@ -137,6 +151,8 @@ class KoolbaseCollectionController {
     /** Stops all updates. Results still in flight are dropped when they land. */
     dispose() {
         this.disposed = true;
+        this.unregister?.();
+        this.unregister = null;
         this.listeners.clear();
     }
     async firstPage(cache) {

package/dist/cjs/database.d.ts

@@ -207,8 +207,19 @@ export declare class KoolbaseDatabase {
      * already removed it locally.
      */
     private resolveBaseline;
-    update(recordId: string, data: Record<string, unknown>): Promise<KoolbaseRecord>;
-    delete(recordId: string): Promise<void>;
+    update(recordId: string, data: Record<string, unknown>, 
+    /** expectedRevision: apply only if the record still carries it; refused
+     *  with KoolbaseRevisionMismatchError otherwise (as the Flutter SDK). */
+    options?: {
+        expectedRevision?: number;
+    }): Promise<KoolbaseRecord>;
+    delete(recordId: string, 
+    /** expectedRevision: delete only if the record still carries it (as the
+     *  Flutter SDK) -- removing a record someone changed a moment ago is the
+     *  more destructive stale write. */
+    options?: {
+        expectedRevision?: number;
+    }): Promise<void>;
     /**
      * Write (or replace) a vector for a record on the named `field`.
      *

package/dist/cjs/database.js

@@ -2,6 +2,8 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.KoolbaseDatabase = void 0;
 const network_js_1 = require("./network.js");
+const query_refresh_js_1 = require("./query-refresh.js");
+const database_errors_js_1 = require("./database-errors.js");
 const errors_js_1 = require("./errors.js");
 const cache_store_js_1 = require("./cache-store.js");
 const offline_state_js_1 = require("./offline-state.js");
@@ -10,7 +12,7 @@ const pending_write_js_1 = require("./pending-write.js");
 const cache_store_js_2 = require("./cache-store.js");
 const sync_engine_js_1 = require("./sync-engine.js");
 const record_js_1 = require("./record.js");
-const database_errors_js_1 = require("./database-errors.js");
+const database_errors_js_2 = require("./database-errors.js");
 function generateWriteId() {
     return 'local_' + Math.random().toString(36).slice(2) + Date.now().toString(36);
 }
@@ -110,7 +112,7 @@ class KoolbaseDatabase {
             }
         }
         if (!res.ok) {
-            const err = (0, database_errors_js_1.koolbaseDataError)(res.status, data ?? {}, `Request failed: ${res.status}`);
+            const err = (0, database_errors_js_2.koolbaseDataError)(res.status, data ?? {}, `Request failed: ${res.status}`);
             if (err instanceof errors_js_1.KoolbaseUnauthenticatedError) {
                 await this.onSessionExpired?.();
             }
@@ -144,7 +146,7 @@ class KoolbaseDatabase {
             }
         }
         if (!res.ok) {
-            const err = (0, database_errors_js_1.koolbaseDataError)(res.status, data ?? {}, `Request failed: ${res.status}`);
+            const err = (0, database_errors_js_2.koolbaseDataError)(res.status, data ?? {}, `Request failed: ${res.status}`);
             if (err instanceof errors_js_1.KoolbaseUnauthenticatedError) {
                 await this.onSessionExpired?.();
             }
@@ -229,6 +231,7 @@ class KoolbaseDatabase {
      */
     async invalidate(collection) {
         await (0, cache_store_js_2.invalidateCache)(this.getUserId() ?? 'anonymous', collection);
+        void (0, query_refresh_js_1.refreshCollectionQueries)(collection);
     }
     // ─── Insert (online-first with offline fallback) ───────────────────────────
     /**
@@ -252,6 +255,7 @@ class KoolbaseDatabase {
             const raw = await this.request('POST', '/v1/sdk/db/insert', { collection, data });
             const record = (0, record_js_1.recordFromWire)(raw);
             await (0, cache_store_js_2.invalidateCache)(userId, collection);
+            void (0, query_refresh_js_1.refreshCollectionQueries)(collection);
             // The response carries a fresh revision, so caching it keeps the
             // baseline current for whatever edits this record next.
             await (0, cache_store_js_1.cacheRecord)(userId, collection, record.id, record.data, record.revision);
@@ -326,6 +330,7 @@ class KoolbaseDatabase {
         // Keep the cache fresh, same intent as insert's post-success invalidate.
         const userId = this.getUserId() ?? 'anonymous';
         await (0, cache_store_js_2.invalidateCache)(userId, collection);
+        void (0, query_refresh_js_1.refreshCollectionQueries)(collection);
         await (0, cache_store_js_1.cacheRecord)(userId, collection, record.id, record.data, record.revision);
         return { record, created };
     }
@@ -345,6 +350,7 @@ class KoolbaseDatabase {
         const body = await this.request('POST', '/v1/sdk/db/delete-where', { collection, filters });
         const userId = this.getUserId() ?? 'anonymous';
         await (0, cache_store_js_2.invalidateCache)(userId, collection);
+        void (0, query_refresh_js_1.refreshCollectionQueries)(collection);
         return body.deleted ?? 0;
     }
     // ─── Batch (atomic, online-only) ────────────────────────────────────────────
@@ -408,6 +414,7 @@ class KoolbaseDatabase {
         }
         for (const col of touched) {
             await (0, cache_store_js_2.invalidateCache)(userId, col);
+            void (0, query_refresh_js_1.refreshCollectionQueries)(col);
         }
         return results;
     }
@@ -529,7 +536,7 @@ class KoolbaseDatabase {
         const { conflicts } = await (0, offline_state_js_1.readOfflineState)(userId);
         const found = conflicts.find((c) => c.id === id);
         if (!found) {
-            throw new database_errors_js_1.KoolbaseDataError('That conflict is no longer outstanding — it may already have been resolved.', 'conflict_not_found');
+            throw new database_errors_js_2.KoolbaseDataError('That conflict is no longer outstanding — it may already have been resolved.', 'conflict_not_found');
         }
         return found;
     }
@@ -578,7 +585,7 @@ class KoolbaseDatabase {
             // retry replays the stale condition and a conflict whose resolution
             // fails once is permanently unresolvable except by abandon —
             // device-proven: three identical refusals against an unchanged server.
-            const details = e instanceof database_errors_js_1.KoolbaseDataError ? e.details : undefined;
+            const details = e instanceof database_errors_js_2.KoolbaseDataError ? e.details : undefined;
             const current = details?.current_revision;
             const record = details?.record;
             if (typeof current === 'number') {
@@ -592,13 +599,14 @@ class KoolbaseDatabase {
                     if (record)
                         stored.server = record;
                 });
-                throw new database_errors_js_1.KoolbaseDataError('The record has changed again while deciding. The conflict now ' +
+                throw new database_errors_js_2.KoolbaseDataError('The record has changed again while deciding. The conflict now ' +
                     'reflects the server\'s current state — review and retry.', 'revision_mismatch');
             }
             throw e;
         }
         await this.dropConflict(c.id);
         await (0, cache_store_js_2.invalidateCache)(this.getUserId() ?? 'anonymous', c.collection);
+        void (0, query_refresh_js_1.refreshCollectionQueries)(c.collection);
     }
     // ─── Update (online-first with offline fallback) ───────────────────────────
     /**
@@ -655,16 +663,23 @@ class KoolbaseDatabase {
             return null;
         return { baseline: cached.data, revision: cached.revision, collection: cached.collection };
     }
-    async update(recordId, data) {
+    async update(recordId, data, 
+    /** expectedRevision: apply only if the record still carries it; refused
+     *  with KoolbaseRevisionMismatchError otherwise (as the Flutter SDK). */
+    options = {}) {
         const userId = this.getUserId() ?? 'anonymous';
         // Resolved before the request, so a network failure has somewhere to go.
         const base = await this.resolveBaseline(userId, recordId);
         try {
-            const raw = await this.request('PATCH', `/v1/sdk/db/records/${recordId}`, { data });
+            const raw = await this.request('PATCH', `/v1/sdk/db/records/${recordId}`, { data, ...(options.expectedRevision !== undefined ? { expected_revision: options.expectedRevision } : {}) });
             const updated = (0, record_js_1.recordFromWire)(raw);
+            // Its collection's live queries re-run (every one, if the record's
+            // collection is not known).
+            const refreshed = updated.collection;
             if (updated.collection) {
                 await (0, cache_store_js_1.cacheRecord)(userId, updated.collection, updated.id, updated.data, updated.revision);
             }
+            void (0, query_refresh_js_1.refreshCollectionQueries)(refreshed);
             return updated;
         }
         catch (e) {
@@ -674,6 +689,10 @@ class KoolbaseDatabase {
             // credential — must not be queued: it will be refused again on every
             // retry. Checked against the root rather than the data family, because a
             // rejected credential belongs to no single surface.
+            // Refused as stale: the server holds newer data, so show it -- the
+            // collection's live queries re-run in the background (as Flutter).
+            if (e instanceof database_errors_js_1.KoolbaseRevisionMismatchError)
+                void (0, query_refresh_js_1.refreshCollectionQueries)(base?.collection);
             if (e instanceof errors_js_1.KoolbaseError)
                 throw e;
             // Genuine network failure. Queueable only if the SDK knows what the
@@ -705,12 +724,19 @@ class KoolbaseDatabase {
         }
     }
     // ─── Delete ─────────────────────────────────────────────────────────────────
-    async delete(recordId) {
+    async delete(recordId, 
+    /** expectedRevision: delete only if the record still carries it (as the
+     *  Flutter SDK) -- removing a record someone changed a moment ago is the
+     *  more destructive stale write. */
+    options = {}) {
         const userId = this.getUserId() ?? 'anonymous';
         const base = await this.resolveBaseline(userId, recordId);
         try {
-            await this.request('DELETE', `/v1/sdk/db/records/${recordId}`);
+            await this.request('DELETE', `/v1/sdk/db/records/${recordId}${options.expectedRevision !== undefined ? `?expected_revision=${options.expectedRevision}` : ''}`);
             await (0, cache_store_js_1.removeCachedRecord)(userId, recordId);
+            // Its collection is known from the baseline when the record was seen;
+            // otherwise every live query re-runs, rather than a guess.
+            void (0, query_refresh_js_1.refreshCollectionQueries)(base?.collection);
         }
         catch (e) {
             // A server that answered has refused: a permission denial or a missing
@@ -721,6 +747,10 @@ class KoolbaseDatabase {
             // credential — must not be queued: it will be refused again on every
             // retry. Checked against the root rather than the data family, because a
             // rejected credential belongs to no single surface.
+            // Refused as stale: the server holds newer data, so show it -- the
+            // collection's live queries re-run in the background (as Flutter).
+            if (e instanceof database_errors_js_1.KoolbaseRevisionMismatchError)
+                void (0, query_refresh_js_1.refreshCollectionQueries)(base?.collection);
             if (e instanceof errors_js_1.KoolbaseError)
                 throw e;
             // Genuine network failure. Queued here rather than before the request,

package/dist/cjs/query-refresh.d.ts

@@ -0,0 +1,10 @@
+/** Registers one live query's refresher; returns the unregister. */
+export declare function registerQueryRefresher(collection: string, refresh: () => Promise<void>): () => void;
+/**
+ * Re-runs every live query on a collection, after a write -- or every live
+ * query when the collection is not known (a delete of a record never read on
+ * this device). One after another; a failure in one never stops the others.
+ */
+export declare function refreshCollectionQueries(collection?: string): Promise<void>;
+/** Tests only. */
+export declare function clearQueryRefreshers(): void;

package/dist/cjs/query-refresh.js

@@ -0,0 +1,41 @@
+"use strict";
+// Live queries refreshed after a write -- the Flutter SDK's _refreshers and
+// refreshCollectionStreams, mirrored. A query refreshes ITSELF: a key carries
+// the collection and filters but not the ordering, limit or paging, so a
+// refresh rebuilt from a key alone would be a different query.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerQueryRefresher = registerQueryRefresher;
+exports.refreshCollectionQueries = refreshCollectionQueries;
+exports.clearQueryRefreshers = clearQueryRefreshers;
+const refreshers = new Map();
+let next = 0;
+/** Registers one live query's refresher; returns the unregister. */
+function registerQueryRefresher(collection, refresh) {
+    const key = `${collection}:${++next}`;
+    refreshers.set(key, refresh);
+    return () => {
+        refreshers.delete(key);
+    };
+}
+/**
+ * Re-runs every live query on a collection, after a write -- or every live
+ * query when the collection is not known (a delete of a record never read on
+ * this device). One after another; a failure in one never stops the others.
+ */
+async function refreshCollectionQueries(collection) {
+    const prefix = collection === undefined ? null : `${collection}:`;
+    const due = [...refreshers.entries()].filter(([k]) => prefix === null || k.startsWith(prefix)).map(([, f]) => f);
+    for (const refresh of due) {
+        try {
+            await refresh();
+        }
+        catch (e) {
+            // eslint-disable-next-line no-console
+            console.warn('[Koolbase] A live query failed to refresh after a write:', e);
+        }
+    }
+}
+/** Tests only. */
+function clearQueryRefreshers() {
+    refreshers.clear();
+}

package/dist/esm/collection-controller.d.ts

@@ -38,6 +38,7 @@ export declare class KoolbaseCollectionController {
     private pageOne;
     private laterPages;
     private nextOffset;
+    private unregister;
     constructor(db: QueryReader, collection: string, query?: CollectionQuery);
     getState(): CollectionState;
     /** Called on every change. Returns the unsubscribe. */
@@ -46,6 +47,12 @@ export declare class KoolbaseCollectionController {
     load(): Promise<void>;
     /** Page one again, from the server. What is shown stays while it runs, and stays if it fails. */
     refresh(): Promise<void>;
+    /**
+     * After a write to this collection: page one again from the server,
+     * SILENTLY -- no `refreshing`, which is the user's pull-to-refresh. What is
+     * shown stays while it runs, and stays if it fails.
+     */
+    private refreshAfterWrite;
     /**
      * The next page, appended. Does nothing unless loaded with more to load.
      * If rows are added or removed on the server between pages, one can be

package/dist/esm/collection-controller.js

@@ -21,6 +21,7 @@
 // Known limit: if rows are added or removed on the server between pages,
 // the pages shift and a row can be skipped until refresh(), which reloads
 // from page one. Duplicates are removed; a skipped row cannot be detected.
+import { registerQueryRefresher } from './query-refresh.js';
 export const initialCollectionState = Object.freeze({
     status: 'loading',
     records: Object.freeze([]),
@@ -69,6 +70,8 @@ export class KoolbaseCollectionController {
         // Where the next page starts on the server. Not records.length: once rows
         // are de-duplicated, a shifted page could otherwise be requested forever.
         this.nextOffset = 0;
+        // A write to this collection re-runs this query (query-refresh.ts).
+        this.unregister = null;
         this.db = db;
         this.collection = collection;
         this.spec = query;
@@ -89,6 +92,7 @@ export class KoolbaseCollectionController {
     async load() {
         if (this.disposed)
             return;
+        this.unregister ?? (this.unregister = registerQueryRefresher(this.collection, () => this.refreshAfterWrite()));
         await this.firstPage('default');
     }
     /** Page one again, from the server. What is shown stays while it runs, and stays if it fails. */
@@ -100,6 +104,16 @@ export class KoolbaseCollectionController {
         if (!this.isStale(gen))
             this.set({ refreshing: false });
     }
+    /**
+     * After a write to this collection: page one again from the server,
+     * SILENTLY -- no `refreshing`, which is the user's pull-to-refresh. What is
+     * shown stays while it runs, and stays if it fails.
+     */
+    async refreshAfterWrite() {
+        if (this.disposed)
+            return;
+        await this.firstPage('network-only');
+    }
     /**
      * The next page, appended. Does nothing unless loaded with more to load.
      * If rows are added or removed on the server between pages, one can be
@@ -133,6 +147,8 @@ export class KoolbaseCollectionController {
     /** Stops all updates. Results still in flight are dropped when they land. */
     dispose() {
         this.disposed = true;
+        this.unregister?.();
+        this.unregister = null;
         this.listeners.clear();
     }
     async firstPage(cache) {

package/dist/esm/database.d.ts

@@ -207,8 +207,19 @@ export declare class KoolbaseDatabase {
      * already removed it locally.
      */
     private resolveBaseline;
-    update(recordId: string, data: Record<string, unknown>): Promise<KoolbaseRecord>;
-    delete(recordId: string): Promise<void>;
+    update(recordId: string, data: Record<string, unknown>, 
+    /** expectedRevision: apply only if the record still carries it; refused
+     *  with KoolbaseRevisionMismatchError otherwise (as the Flutter SDK). */
+    options?: {
+        expectedRevision?: number;
+    }): Promise<KoolbaseRecord>;
+    delete(recordId: string, 
+    /** expectedRevision: delete only if the record still carries it (as the
+     *  Flutter SDK) -- removing a record someone changed a moment ago is the
+     *  more destructive stale write. */
+    options?: {
+        expectedRevision?: number;
+    }): Promise<void>;
     /**
      * Write (or replace) a vector for a record on the named `field`.
      *

package/dist/esm/database.js

@@ -1,4 +1,6 @@
 import { koolbaseFetch } from './network.js';
+import { refreshCollectionQueries } from './query-refresh.js';
+import { KoolbaseRevisionMismatchError } from './database-errors.js';
 import { KoolbaseError, KoolbaseOfflineBaselineUnavailableError, KoolbaseUnauthenticatedError, } from './errors.js';
 import { cacheRecord, getCachedRecord, removeCachedRecord } from './cache-store.js';
 import { readOfflineState, mutateOfflineState, queueWrite, } from './offline-state.js';
@@ -226,6 +228,7 @@ export class KoolbaseDatabase {
      */
     async invalidate(collection) {
         await invalidateCache(this.getUserId() ?? 'anonymous', collection);
+        void refreshCollectionQueries(collection);
     }
     // ─── Insert (online-first with offline fallback) ───────────────────────────
     /**
@@ -249,6 +252,7 @@ export class KoolbaseDatabase {
             const raw = await this.request('POST', '/v1/sdk/db/insert', { collection, data });
             const record = recordFromWire(raw);
             await invalidateCache(userId, collection);
+            void refreshCollectionQueries(collection);
             // The response carries a fresh revision, so caching it keeps the
             // baseline current for whatever edits this record next.
             await cacheRecord(userId, collection, record.id, record.data, record.revision);
@@ -323,6 +327,7 @@ export class KoolbaseDatabase {
         // Keep the cache fresh, same intent as insert's post-success invalidate.
         const userId = this.getUserId() ?? 'anonymous';
         await invalidateCache(userId, collection);
+        void refreshCollectionQueries(collection);
         await cacheRecord(userId, collection, record.id, record.data, record.revision);
         return { record, created };
     }
@@ -342,6 +347,7 @@ export class KoolbaseDatabase {
         const body = await this.request('POST', '/v1/sdk/db/delete-where', { collection, filters });
         const userId = this.getUserId() ?? 'anonymous';
         await invalidateCache(userId, collection);
+        void refreshCollectionQueries(collection);
         return body.deleted ?? 0;
     }
     // ─── Batch (atomic, online-only) ────────────────────────────────────────────
@@ -405,6 +411,7 @@ export class KoolbaseDatabase {
         }
         for (const col of touched) {
             await invalidateCache(userId, col);
+            void refreshCollectionQueries(col);
         }
         return results;
     }
@@ -596,6 +603,7 @@ export class KoolbaseDatabase {
         }
         await this.dropConflict(c.id);
         await invalidateCache(this.getUserId() ?? 'anonymous', c.collection);
+        void refreshCollectionQueries(c.collection);
     }
     // ─── Update (online-first with offline fallback) ───────────────────────────
     /**
@@ -652,16 +660,23 @@ export class KoolbaseDatabase {
             return null;
         return { baseline: cached.data, revision: cached.revision, collection: cached.collection };
     }
-    async update(recordId, data) {
+    async update(recordId, data, 
+    /** expectedRevision: apply only if the record still carries it; refused
+     *  with KoolbaseRevisionMismatchError otherwise (as the Flutter SDK). */
+    options = {}) {
         const userId = this.getUserId() ?? 'anonymous';
         // Resolved before the request, so a network failure has somewhere to go.
         const base = await this.resolveBaseline(userId, recordId);
         try {
-            const raw = await this.request('PATCH', `/v1/sdk/db/records/${recordId}`, { data });
+            const raw = await this.request('PATCH', `/v1/sdk/db/records/${recordId}`, { data, ...(options.expectedRevision !== undefined ? { expected_revision: options.expectedRevision } : {}) });
             const updated = recordFromWire(raw);
+            // Its collection's live queries re-run (every one, if the record's
+            // collection is not known).
+            const refreshed = updated.collection;
             if (updated.collection) {
                 await cacheRecord(userId, updated.collection, updated.id, updated.data, updated.revision);
             }
+            void refreshCollectionQueries(refreshed);
             return updated;
         }
         catch (e) {
@@ -671,6 +686,10 @@ export class KoolbaseDatabase {
             // credential — must not be queued: it will be refused again on every
             // retry. Checked against the root rather than the data family, because a
             // rejected credential belongs to no single surface.
+            // Refused as stale: the server holds newer data, so show it -- the
+            // collection's live queries re-run in the background (as Flutter).
+            if (e instanceof KoolbaseRevisionMismatchError)
+                void refreshCollectionQueries(base?.collection);
             if (e instanceof KoolbaseError)
                 throw e;
             // Genuine network failure. Queueable only if the SDK knows what the
@@ -702,12 +721,19 @@ export class KoolbaseDatabase {
         }
     }
     // ─── Delete ─────────────────────────────────────────────────────────────────
-    async delete(recordId) {
+    async delete(recordId, 
+    /** expectedRevision: delete only if the record still carries it (as the
+     *  Flutter SDK) -- removing a record someone changed a moment ago is the
+     *  more destructive stale write. */
+    options = {}) {
         const userId = this.getUserId() ?? 'anonymous';
         const base = await this.resolveBaseline(userId, recordId);
         try {
-            await this.request('DELETE', `/v1/sdk/db/records/${recordId}`);
+            await this.request('DELETE', `/v1/sdk/db/records/${recordId}${options.expectedRevision !== undefined ? `?expected_revision=${options.expectedRevision}` : ''}`);
             await removeCachedRecord(userId, recordId);
+            // Its collection is known from the baseline when the record was seen;
+            // otherwise every live query re-runs, rather than a guess.
+            void refreshCollectionQueries(base?.collection);
         }
         catch (e) {
             // A server that answered has refused: a permission denial or a missing
@@ -718,6 +744,10 @@ export class KoolbaseDatabase {
             // credential — must not be queued: it will be refused again on every
             // retry. Checked against the root rather than the data family, because a
             // rejected credential belongs to no single surface.
+            // Refused as stale: the server holds newer data, so show it -- the
+            // collection's live queries re-run in the background (as Flutter).
+            if (e instanceof KoolbaseRevisionMismatchError)
+                void refreshCollectionQueries(base?.collection);
             if (e instanceof KoolbaseError)
                 throw e;
             // Genuine network failure. Queued here rather than before the request,

package/dist/esm/query-refresh.d.ts

@@ -0,0 +1,10 @@
+/** Registers one live query's refresher; returns the unregister. */
+export declare function registerQueryRefresher(collection: string, refresh: () => Promise<void>): () => void;
+/**
+ * Re-runs every live query on a collection, after a write -- or every live
+ * query when the collection is not known (a delete of a record never read on
+ * this device). One after another; a failure in one never stops the others.
+ */
+export declare function refreshCollectionQueries(collection?: string): Promise<void>;
+/** Tests only. */
+export declare function clearQueryRefreshers(): void;

package/dist/esm/query-refresh.js

@@ -0,0 +1,36 @@
+// Live queries refreshed after a write -- the Flutter SDK's _refreshers and
+// refreshCollectionStreams, mirrored. A query refreshes ITSELF: a key carries
+// the collection and filters but not the ordering, limit or paging, so a
+// refresh rebuilt from a key alone would be a different query.
+const refreshers = new Map();
+let next = 0;
+/** Registers one live query's refresher; returns the unregister. */
+export function registerQueryRefresher(collection, refresh) {
+    const key = `${collection}:${++next}`;
+    refreshers.set(key, refresh);
+    return () => {
+        refreshers.delete(key);
+    };
+}
+/**
+ * Re-runs every live query on a collection, after a write -- or every live
+ * query when the collection is not known (a delete of a record never read on
+ * this device). One after another; a failure in one never stops the others.
+ */
+export async function refreshCollectionQueries(collection) {
+    const prefix = collection === undefined ? null : `${collection}:`;
+    const due = [...refreshers.entries()].filter(([k]) => prefix === null || k.startsWith(prefix)).map(([, f]) => f);
+    for (const refresh of due) {
+        try {
+            await refresh();
+        }
+        catch (e) {
+            // eslint-disable-next-line no-console
+            console.warn('[Koolbase] A live query failed to refresh after a write:', e);
+        }
+    }
+}
+/** Tests only. */
+export function clearQueryRefreshers() {
+    refreshers.clear();
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@koolbase/core",
-  "version": "12.6.0",
-  "description": "Koolbase SDK core \u2014 shared behaviour behind @koolbase/react-native and @koolbase/js. Install one of those, not this.",
+  "version": "12.8.0",
+  "description": "Koolbase SDK core — shared behaviour behind @koolbase/react-native and @koolbase/js. Install one of those, not this.",
   "main": "./dist/cjs/index.js",
   "types": "./dist/esm/index.d.ts",
   "files": [