@koolbase/react-native 9.0.0 → 9.2.0

package/dist/sync-engine.js

@@ -4,15 +4,55 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SyncEngine = void 0;
+const offline_state_1 = require("./offline-state");
+const errors_1 = require("./errors");
 const netinfo_1 = __importDefault(require("@react-native-community/netinfo"));
 const cache_store_1 = require("./cache-store");
+/**
+ * Internal signal that the server refused a write because the record moved.
+ *
+ * Not exported: a conflict during replay becomes durable state rather than
+ * reaching a caller, since nobody is waiting on a write made hours ago.
+ */
+/**
+ * Whether the server's answer can change on a later attempt.
+ *
+ * Terminal means the same request would meet the same decision: the data does
+ * not satisfy the collection's rules, the record is gone, the caller is not
+ * permitted, a unique value is taken. Retrying spends attempts to learn what is
+ * already known.
+ *
+ * 403 is terminal even though a role change could later permit it. A queue that
+ * holds writes indefinitely against a maybe is how a retry loop becomes
+ * invisible — surfacing it lets an app retry deliberately if roles change.
+ */
+function isTerminal(status) {
+    return status === 400 || status === 403 || status === 404 || status === 409;
+}
+/** Raised when the server refused for a reason retrying cannot change. */
+class TerminalRejection extends Error {
+    constructor(message, status) {
+        super(message);
+        this.status = status;
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+class RevisionMismatch extends Error {
+    constructor(serverRecord, serverRevision) {
+        super('revision mismatch');
+        this.serverRecord = serverRecord;
+        this.serverRevision = serverRevision;
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
 class SyncEngine {
-    constructor(config, getUserId, getToken, onSyncComplete) {
+    constructor(config, getUserId, getToken, onSyncComplete, onSessionExpired) {
         this.isSyncing = false;
         this.config = config;
         this.getUserId = getUserId;
         this.getToken = getToken;
         this.onSyncComplete = onSyncComplete;
+        this.onSessionExpired = onSessionExpired;
     }
     start() {
         this.unsubscribe = netinfo_1.default.addEventListener(state => {
@@ -32,16 +72,129 @@ class SyncEngine {
             return;
         this.isSyncing = true;
         try {
-            const queue = await (0, cache_store_1.getWriteQueue)(userId);
-            if (queue.length === 0)
+            // Before anything is sent. Writes queued by an earlier version sit under a
+            // different key, and a migration that ran after replay — or depended on
+            // 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_1.migrateLegacyQueue)(userId);
+            const { pending } = await (0, offline_state_1.readOfflineState)(userId);
+            if (pending.length === 0)
                 return;
-            for (const write of queue) {
+            // 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();
+            for (const queued of pending) {
+                if (queued.recordId && blocked.has(queued.recordId))
+                    continue;
+                // Read fresh. The list was taken at the start of the pass, so a write
+                // behind one that has already landed still carries the revision it was
+                // queued with — and would replay against a revision its predecessor has
+                // since superseded, conflicting for a reason the user never caused.
+                const state = await (0, offline_state_1.readOfflineState)(userId);
+                const write = state.pending.find((w) => w.id === queued.id);
+                if (!write)
+                    continue;
                 try {
-                    await this.executeWrite(write);
-                    await (0, cache_store_1.removeFromWriteQueue)(userId, write.id);
+                    const revision = await this.executeWrite(write);
+                    // The replayed write just changed the server; the cache must stop
+                    // testifying to the old world. Mirrors the online paths — a replayed
+                    // delete evicts the record, and every replayed write invalidates the
+                    // collection's cached queries, so the next query reconverges instead
+                    // of serving a ghost.
+                    if (write.operation === 'delete' && write.recordId) {
+                        await (0, cache_store_1.removeCachedRecord)(userId, write.recordId);
+                    }
+                    await (0, cache_store_1.invalidateCache)(userId, write.collection);
+                    await (0, offline_state_1.mutateOfflineState)(userId, (s) => {
+                        s.pending = s.pending.filter((w) => w.id !== write.id);
+                        // Anything behind this for the same record was composed against its
+                        // result, and now knows the revision that result carries.
+                        if (revision !== undefined && write.recordId) {
+                            for (const w of s.pending) {
+                                if (w.recordId === write.recordId)
+                                    w.baseRevision = revision;
+                            }
+                        }
+                    });
                 }
-                catch {
-                    await (0, cache_store_1.incrementWriteRetry)(userId, write.id);
+                catch (e) {
+                    if (e instanceof errors_1.KoolbaseUnauthenticatedError) {
+                        // The session is gone, so nothing else in the queue can succeed.
+                        // Stopping beats spending a retry on every remaining write against
+                        // a token the server has already refused; the queue is intact and
+                        // replays after login.
+                        await this.onSessionExpired?.();
+                        return;
+                    }
+                    if (e instanceof RevisionMismatch) {
+                        // Not a failure to retry — retrying cannot help. It becomes durable
+                        // unresolved state, in one write so it can be in neither place nor
+                        // both.
+                        await (0, offline_state_1.mutateOfflineState)(userId, (s) => {
+                            s.pending = s.pending.filter((w) => w.id !== write.id);
+                            s.conflicts.push({
+                                id: write.id,
+                                // The record moved between the change being made and the queue
+                                // reaching it — distinct from a write that never had a baseline
+                                // to compare against at all.
+                                reason: 'concurrent_modification',
+                                operation: write.operation,
+                                collection: write.collection,
+                                recordId: write.recordId,
+                                local: write.data,
+                                baseline: write.baseline,
+                                server: e.serverRecord,
+                                baseRevision: write.baseRevision,
+                                serverRevision: e.serverRevision,
+                                createdAt: new Date().toISOString(),
+                            });
+                        });
+                        if (write.recordId)
+                            blocked.add(write.recordId);
+                        continue;
+                    }
+                    if (e instanceof TerminalRejection) {
+                        // The server made a decision that will not change on a later
+                        // attempt. Retrying spends attempts to learn what is already known;
+                        // dropping loses a change the user believes is saved. It waits,
+                        // with what the server said, so someone can act on it.
+                        await (0, offline_state_1.mutateOfflineState)(userId, (s) => {
+                            s.pending = s.pending.filter((w) => w.id !== write.id);
+                            s.conflicts.push({
+                                id: write.id,
+                                reason: 'rejected',
+                                operation: write.operation,
+                                collection: write.collection,
+                                recordId: write.recordId ?? '',
+                                local: write.data,
+                                baseline: write.baseline,
+                                baseRevision: write.baseRevision,
+                                message: e.message,
+                                createdAt: new Date().toISOString(),
+                            });
+                        });
+                        // A terminally rejected insert leaves an optimistic record behind
+                        // — 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
+                        if (write.recordId)
+                            blocked.add(write.recordId);
+                        continue;
+                    }
+                    // Retryable: the network, a 5xx, a rate limit. The count is kept so a
+                    // caller can see a write that keeps failing, but nothing drops it —
+                    // a write discarded after three attempts is discarded silently, and
+                    // the user is never told.
+                    await (0, offline_state_1.mutateOfflineState)(userId, (s) => {
+                        const w = s.pending.find((x) => x.id === write.id);
+                        if (w)
+                            w.retries += 1;
+                    });
                 }
             }
             this.onSyncComplete?.();
@@ -50,6 +203,13 @@ class SyncEngine {
             this.isSyncing = false;
         }
     }
+    /**
+     * Sends one queued write, returning the revision the record now carries.
+     *
+     * The revision matters to whatever is queued behind this for the same record:
+     * those were composed against this one's result and cannot know its revision
+     * until the server assigns it.
+     */
     async executeWrite(write) {
         const token = await this.getToken();
         const headers = {
@@ -57,30 +217,74 @@ class SyncEngine {
             'x-api-key': this.config.publicKey,
             ...(token ? { Authorization: `Bearer ${token}` } : {}),
         };
-        if (write.type === 'insert') {
-            const res = await fetch(`${this.config.baseUrl}/v1/sdk/db/insert`, {
+        const url = write.operation === 'insert'
+            ? `${this.config.baseUrl}/v1/sdk/db/insert`
+            : `${this.config.baseUrl}/v1/sdk/db/records/${write.recordId}`;
+        let res;
+        if (write.operation === 'insert') {
+            res = await fetch(url, {
                 method: 'POST',
                 headers,
-                body: JSON.stringify({ collection: write.collection, data: write.data }),
+                // The write's own id: generated at enqueue, identical on every retry.
+                // Without it, an insert whose response was lost duplicated on replay —
+                // the server had no way to recognise the repeat.
+                body: JSON.stringify({
+                    collection: write.collection,
+                    data: write.data,
+                    idempotency_key: write.id,
+                }),
             });
-            if (!res.ok)
-                throw new Error(`Insert failed: ${res.status}`);
         }
-        else if (write.type === 'update') {
-            const res = await fetch(`${this.config.baseUrl}/v1/sdk/db/records/${write.recordId}`, {
+        else if (write.operation === 'update') {
+            res = await fetch(url, {
                 method: 'PATCH',
                 headers,
-                body: JSON.stringify({ data: write.data }),
+                // The revision the change was composed against. The server applies it
+                // only if the record still carries that revision, so nothing can land
+                // between the client deciding the write is safe and the server applying
+                // it — which matters here most of all, since hours may have passed.
+                body: JSON.stringify({
+                    data: write.data,
+                    ...(write.baseRevision !== undefined
+                        ? { expected_revision: write.baseRevision }
+                        : {}),
+                }),
             });
-            if (!res.ok)
-                throw new Error(`Update failed: ${res.status}`);
         }
-        else if (write.type === 'delete') {
-            const res = await fetch(`${this.config.baseUrl}/v1/sdk/db/records/${write.recordId}`, { method: 'DELETE', headers });
-            if (!res.ok && res.status !== 204) {
-                throw new Error(`Delete failed: ${res.status}`);
+        else {
+            const q = write.baseRevision !== undefined
+                ? `?expected_revision=${write.baseRevision}`
+                : '';
+            res = await fetch(`${url}${q}`, { method: 'DELETE', headers });
+        }
+        if (res.status === 401)
+            throw new errors_1.KoolbaseUnauthenticatedError('unauthorized');
+        if (res.status === 409) {
+            const body = await res.json().catch(() => ({}));
+            if (body?.code === 'revision_mismatch') {
+                throw new RevisionMismatch(body?.details?.record, body?.details?.current_revision);
             }
         }
+        if (!res.ok && res.status !== 204) {
+            const body = await res.json().catch(() => ({}));
+            const message = body?.error ?? `${write.operation} failed`;
+            // A 404 on a delete means the record is already gone, which is what the
+            // write was asking for. Satisfied, not failed.
+            if (res.status === 404 && write.operation === 'delete')
+                return undefined;
+            if (isTerminal(res.status))
+                throw new TerminalRejection(message, res.status);
+            throw new Error(`${write.operation} sync failed: ${res.status}`);
+        }
+        const text = await res.text().catch(() => '');
+        if (!text)
+            return undefined;
+        try {
+            return JSON.parse(text)?.$revision;
+        }
+        catch {
+            return undefined;
+        }
     }
 }
 exports.SyncEngine = SyncEngine;

package/dist/types.d.ts

@@ -120,6 +120,17 @@ export interface KoolbaseRecord {
     data: Record<string, unknown>;
     createdAt: string;
     updatedAt: string;
+    /**
+     * Advanced by the server on every write.
+     *
+     * Pass it back on an update or delete to apply the change only if nothing
+     * else has touched the record since — the difference between overwriting
+     * someone else's change and being told about it.
+     *
+     * Undefined for records from a server that predates revisions, and for
+     * records cached by an earlier version of this SDK.
+     */
+    revision?: number;
 }
 export interface QueryOptions {
     filters?: Record<string, unknown>;
@@ -138,7 +149,13 @@ export interface UpsertResult {
     record: KoolbaseRecord;
     created: boolean;
 }
-export interface PendingWrite {
+/**
+ * The 9.1.x queue entry shape. Superseded: the observable queue API returns
+ * the PendingWrite from './pending-write'; this shape survives only for
+ * migrateLegacyQueue, which drains the old storage key on first sync.
+ * No longer part of the public surface as of 9.2.0.
+ */
+export interface LegacyPendingWrite {
     id: string;
     type: 'insert' | 'update' | 'delete';
     collection?: string;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@koolbase/react-native",
-  "version": "9.0.0",
-  "description": "React Native SDK for Koolbase — auth, database, storage, realtime, feature flags, and functions in one package.",
+  "version": "9.2.0",
+  "description": "React Native SDK for Koolbase \u2014 auth, database, storage, realtime, feature flags, and functions in one package.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "files": [
@@ -9,7 +9,8 @@
   ],
   "scripts": {
     "build": "tsc",
-    "prepare": "npm run build"
+    "prepare": "npm run build",
+    "test": "jest"
   },
   "keywords": [
     "koolbase",
@@ -26,19 +27,24 @@
     "url": "https://github.com/koolbase/koolbase-react-native"
   },
   "devDependencies": {
+    "@types/jest": "^30.0.0",
     "@types/jszip": "^3.4.0",
     "@types/node": "^25.9.1",
+    "jest": "^30.4.2",
     "react-native": "^0.85.3",
     "react-native-keychain": "^10.0.0",
-    "typescript": "^5.0.0"
+    "ts-jest": "^29.4.12",
+    "typescript": "^5.0.0",
+    "@react-native-async-storage/async-storage": "^3.0.2",
+    "@react-native-community/netinfo": "^12.0.1"
   },
   "peerDependencies": {
     "react-native": ">=0.70.0",
-    "react-native-keychain": ">=8.0.0"
+    "react-native-keychain": ">=8.0.0",
+    "@react-native-async-storage/async-storage": "^3.0.2",
+    "@react-native-community/netinfo": "^12.0.1"
   },
   "dependencies": {
-    "@react-native-async-storage/async-storage": "^3.0.2",
-    "@react-native-community/netinfo": "^12.0.1",
     "jszip": "^3.10.1"
   },
   "publishConfig": {