@koolbase/core 12.7.0 → 12.8.0

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

@@ -3,6 +3,7 @@ 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");
@@ -11,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);
 }
@@ -111,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?.();
             }
@@ -145,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?.();
             }
@@ -230,7 +231,7 @@ class KoolbaseDatabase {
      */
     async invalidate(collection) {
         await (0, cache_store_js_2.invalidateCache)(this.getUserId() ?? 'anonymous', collection);
-        await (0, query_refresh_js_1.refreshCollectionQueries)(collection);
+        void (0, query_refresh_js_1.refreshCollectionQueries)(collection);
     }
     // ─── Insert (online-first with offline fallback) ───────────────────────────
     /**
@@ -254,7 +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);
-            await (0, query_refresh_js_1.refreshCollectionQueries)(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);
@@ -329,7 +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);
-        await (0, query_refresh_js_1.refreshCollectionQueries)(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 };
     }
@@ -349,7 +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);
-        await (0, query_refresh_js_1.refreshCollectionQueries)(collection);
+        void (0, query_refresh_js_1.refreshCollectionQueries)(collection);
         return body.deleted ?? 0;
     }
     // ─── Batch (atomic, online-only) ────────────────────────────────────────────
@@ -413,7 +414,7 @@ class KoolbaseDatabase {
         }
         for (const col of touched) {
             await (0, cache_store_js_2.invalidateCache)(userId, col);
-            await (0, query_refresh_js_1.refreshCollectionQueries)(col);
+            void (0, query_refresh_js_1.refreshCollectionQueries)(col);
         }
         return results;
     }
@@ -535,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;
     }
@@ -584,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') {
@@ -598,14 +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);
-        await (0, query_refresh_js_1.refreshCollectionQueries)(c.collection);
+        void (0, query_refresh_js_1.refreshCollectionQueries)(c.collection);
     }
     // ─── Update (online-first with offline fallback) ───────────────────────────
     /**
@@ -662,12 +663,15 @@ 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).
@@ -675,7 +679,7 @@ class KoolbaseDatabase {
             if (updated.collection) {
                 await (0, cache_store_js_1.cacheRecord)(userId, updated.collection, updated.id, updated.data, updated.revision);
             }
-            await (0, query_refresh_js_1.refreshCollectionQueries)(refreshed);
+            void (0, query_refresh_js_1.refreshCollectionQueries)(refreshed);
             return updated;
         }
         catch (e) {
@@ -685,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
@@ -716,15 +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.
-            await (0, query_refresh_js_1.refreshCollectionQueries)(base?.collection);
+            void (0, query_refresh_js_1.refreshCollectionQueries)(base?.collection);
         }
         catch (e) {
             // A server that answered has refused: a permission denial or a missing
@@ -735,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/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,5 +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';
@@ -227,7 +228,7 @@ export class KoolbaseDatabase {
      */
     async invalidate(collection) {
         await invalidateCache(this.getUserId() ?? 'anonymous', collection);
-        await refreshCollectionQueries(collection);
+        void refreshCollectionQueries(collection);
     }
     // ─── Insert (online-first with offline fallback) ───────────────────────────
     /**
@@ -251,7 +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);
-            await refreshCollectionQueries(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);
@@ -326,7 +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);
-        await refreshCollectionQueries(collection);
+        void refreshCollectionQueries(collection);
         await cacheRecord(userId, collection, record.id, record.data, record.revision);
         return { record, created };
     }
@@ -346,7 +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);
-        await refreshCollectionQueries(collection);
+        void refreshCollectionQueries(collection);
         return body.deleted ?? 0;
     }
     // ─── Batch (atomic, online-only) ────────────────────────────────────────────
@@ -410,7 +411,7 @@ export class KoolbaseDatabase {
         }
         for (const col of touched) {
             await invalidateCache(userId, col);
-            await refreshCollectionQueries(col);
+            void refreshCollectionQueries(col);
         }
         return results;
     }
@@ -602,7 +603,7 @@ export class KoolbaseDatabase {
         }
         await this.dropConflict(c.id);
         await invalidateCache(this.getUserId() ?? 'anonymous', c.collection);
-        await refreshCollectionQueries(c.collection);
+        void refreshCollectionQueries(c.collection);
     }
     // ─── Update (online-first with offline fallback) ───────────────────────────
     /**
@@ -659,12 +660,15 @@ 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).
@@ -672,7 +676,7 @@ export class KoolbaseDatabase {
             if (updated.collection) {
                 await cacheRecord(userId, updated.collection, updated.id, updated.data, updated.revision);
             }
-            await refreshCollectionQueries(refreshed);
+            void refreshCollectionQueries(refreshed);
             return updated;
         }
         catch (e) {
@@ -682,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
@@ -713,15 +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.
-            await refreshCollectionQueries(base?.collection);
+            void refreshCollectionQueries(base?.collection);
         }
         catch (e) {
             // A server that answered has refused: a permission denial or a missing
@@ -732,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@koolbase/core",
-  "version": "12.7.0",
+  "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",