@koolbase/js 10.1.0 → 10.2.0

package/CHANGELOG.md

@@ -7,6 +7,25 @@ is based on [Keep a Changelog][kac], and this project adheres to
 [kac]: https://keepachangelog.com/en/1.1.0/
 [semver]: https://semver.org/
 
+## 10.2.0
+
+### Added
+
+- **Multiple tabs are coordinated.** Tabs on one origin share one IndexedDB
+  and one offline queue. Two locks, through the Web Locks API, now keep them
+  honest: a short exclusive lock around every read-modify-write of the
+  offline state, so two tabs enqueueing at once cannot overwrite each other;
+  and a lease on replaying the queue, held for a whole flush including its
+  HTTP calls, so two tabs coming online together send each queued write once
+  rather than once each. A tab that cannot take the lease skips its pass and
+  rechecks once the holder is done, so a write queued during another tab's
+  flush is not stranded. A tab that closes mid-flush releases its lock
+  automatically. In a browser without Web Locks — none current — offline
+  queueing refuses with an explicit error rather than risking a double send.
+
+  Proven with a contended fake lock manager: two tabs, one queued write, one
+  HTTP request. Exercised in Chrome with real Web Locks.
+
 ## 10.1.0
 
 ### Fixed

package/README.md

@@ -168,11 +168,13 @@ becomes a conflict you resolve: `resolveWithLocal()`, `resolveWithServer()`,
 `resolveWithMerge({...})`, or `abandon()`. Conflicts survive reloads and do not
 expire; surface them if you support offline editing.
 
-**Single tab, in this release.** Two tabs share one IndexedDB and one queue,
-and both may replay the same write. Inserts are idempotent so the damage is
-bounded, but a conflict resolved in one tab can be re-resolved in another.
-Multi-tab coordination is on the roadmap; until then, treat the offline queue
-as belonging to one tab.
+**Multiple tabs are coordinated.** Tabs share one IndexedDB and one queue, and
+the SDK uses the Web Locks API so that only one tab replays a queued write and
+state changes from different tabs cannot overwrite each other. A tab that
+closes mid-flush releases its lock automatically; the next tab picks up
+whatever remains. Every current browser has Web Locks; in one that does not,
+offline queueing is disabled with an explicit error rather than risking a
+write being sent twice.
 
 ---
 

package/dist/cjs/platform.js

@@ -11,11 +11,9 @@ const auth_storage_js_1 = require("./auth-storage.js");
 //
 // What this adapter does NOT do, stated so it is not discovered later:
 //
-//  - Multi-tab coordination. Two tabs share one IndexedDB and one write
-//    queue; both may replay the same pending write. Inserts are idempotent
-//    on the server (ids are UUIDs from birth), so the damage is bounded, but
-//    a conflict resolved in one tab can be re-resolved in another. v1 is
-//    single-tab; a leader election is the fix and belongs in its own change.
+//  - Coordinate across origins. Tabs on one origin share a queue and are
+//    coordinated through Web Locks (see webLocks below); nothing coordinates
+//    two different origins, which is correct — they are different apps.
 //
 //  - Secure token storage. There is no keychain in a browser. Anything
 //    JavaScript can read, a script injected by XSS can read. The core's
@@ -148,6 +146,64 @@ function makeResolver() {
         return resolving.then((r) => { resolved = r; return r; });
     };
 }
+/**
+ * Web Locks. One holder per name across every tab on the origin, with
+ * ownership released when a tab closes or crashes — which is why this and
+ * not a BroadcastChannel election with heartbeats and a dead-leader timeout.
+ *
+ * Where the API is absent there is deliberately no fallback to running the
+ * function unlocked: that is exactly the uncoordinated behaviour the lock
+ * exists to prevent, and doing it silently would be worse than refusing.
+ * Every browser current enough to run this SDK has Web Locks (Safari 15.4+,
+ * Chrome 69+, Firefox 96+), so this is a guard, not a limitation.
+ */
+function webLocks() {
+    // Tabs are what need coordinating, and a tab has a window. No window means
+    // server rendering, a build step, a Node tool, a worker — nothing else can
+    // be sharing this store, so run the work. Not navigator: Node 22 ships a
+    // navigator object without locks, and testing for it would refuse every
+    // server environment the memory fallback exists to support.
+    if (typeof window === 'undefined') {
+        return {
+            exclusive: (_name, fn) => fn(),
+            tryExclusive: async (_name, fn) => { await fn(); return { ran: true }; },
+        };
+    }
+    // A browser that has navigator but no locks is a browser too old to
+    // coordinate. That one refuses: tabs exist, and running unlocked is the
+    // duplicate-replay risk this lock was added to remove.
+    if (typeof navigator === 'undefined' || !('locks' in navigator)) {
+        const refuse = () => {
+            throw new Error('[Koolbase] This browser has no Web Locks API, so the SDK cannot ' +
+                'coordinate offline writes between tabs. Offline queueing is ' +
+                'disabled rather than risking a write being replayed twice.');
+        };
+        return {
+            exclusive: async () => refuse(),
+            tryExclusive: async () => refuse(),
+        };
+    }
+    const locks = navigator.locks;
+    return {
+        // request() resolves with whatever the callback resolves to; the DOM
+        // typings describe the callback's return as the result, so an async
+        // callback types as Promise<Promise<T>>. The runtime awaits it.
+        exclusive: (name, fn) => locks.request(name, fn),
+        tryExclusive: async (name, fn) => {
+            let ran = false;
+            await locks.request(name, { ifAvailable: true }, async (lock) => {
+                // A null lock means another tab holds it. Skip: it is already
+                // replaying the same queue, and waiting would only duplicate the
+                // wait, not the work.
+                if (!lock)
+                    return;
+                ran = true;
+                await fn();
+            });
+            return { ran };
+        },
+    };
+}
 function browserPlatform() {
     const resolve = makeResolver();
     // Every call resolves first, so a browser that only reveals its refusal on
@@ -157,6 +213,14 @@ function browserPlatform() {
         setItem: async (k, v) => { await (await resolve()).store.setItem(k, v); },
         removeItem: async (k) => { await (await resolve()).store.removeItem(k); },
         getAllKeys: async () => (await resolve()).store.getAllKeys(),
+        // Reaches through to the resolved tier. Only IndexedDB holds a
+        // connection worth closing; the test harness needs it released before
+        // it can delete the database between cases, and without this the
+        // façade hid the handle and every browser test hung on its hook.
+        close: async () => {
+            const r = await resolve();
+            await r.store.close?.();
+        },
     };
     // Which tier this adapter settled on: 'indexeddb', 'localstorage' or
     // 'memory'. An app that cares can warn the user before they lose a session.
@@ -204,6 +268,7 @@ function browserPlatform() {
             os: 'web',
             version: browserVersion(),
         },
+        locks: webLocks(),
         // IndexedDB-backed; see auth-storage.ts for what that does and does not
         // protect against.
         authStorage: () => new auth_storage_js_1.BrowserAuthStorage(),

package/dist/esm/platform.js

@@ -8,11 +8,9 @@ import { BrowserAuthStorage } from './auth-storage.js';
 //
 // What this adapter does NOT do, stated so it is not discovered later:
 //
-//  - Multi-tab coordination. Two tabs share one IndexedDB and one write
-//    queue; both may replay the same pending write. Inserts are idempotent
-//    on the server (ids are UUIDs from birth), so the damage is bounded, but
-//    a conflict resolved in one tab can be re-resolved in another. v1 is
-//    single-tab; a leader election is the fix and belongs in its own change.
+//  - Coordinate across origins. Tabs on one origin share a queue and are
+//    coordinated through Web Locks (see webLocks below); nothing coordinates
+//    two different origins, which is correct — they are different apps.
 //
 //  - Secure token storage. There is no keychain in a browser. Anything
 //    JavaScript can read, a script injected by XSS can read. The core's
@@ -145,6 +143,64 @@ function makeResolver() {
         return resolving.then((r) => { resolved = r; return r; });
     };
 }
+/**
+ * Web Locks. One holder per name across every tab on the origin, with
+ * ownership released when a tab closes or crashes — which is why this and
+ * not a BroadcastChannel election with heartbeats and a dead-leader timeout.
+ *
+ * Where the API is absent there is deliberately no fallback to running the
+ * function unlocked: that is exactly the uncoordinated behaviour the lock
+ * exists to prevent, and doing it silently would be worse than refusing.
+ * Every browser current enough to run this SDK has Web Locks (Safari 15.4+,
+ * Chrome 69+, Firefox 96+), so this is a guard, not a limitation.
+ */
+function webLocks() {
+    // Tabs are what need coordinating, and a tab has a window. No window means
+    // server rendering, a build step, a Node tool, a worker — nothing else can
+    // be sharing this store, so run the work. Not navigator: Node 22 ships a
+    // navigator object without locks, and testing for it would refuse every
+    // server environment the memory fallback exists to support.
+    if (typeof window === 'undefined') {
+        return {
+            exclusive: (_name, fn) => fn(),
+            tryExclusive: async (_name, fn) => { await fn(); return { ran: true }; },
+        };
+    }
+    // A browser that has navigator but no locks is a browser too old to
+    // coordinate. That one refuses: tabs exist, and running unlocked is the
+    // duplicate-replay risk this lock was added to remove.
+    if (typeof navigator === 'undefined' || !('locks' in navigator)) {
+        const refuse = () => {
+            throw new Error('[Koolbase] This browser has no Web Locks API, so the SDK cannot ' +
+                'coordinate offline writes between tabs. Offline queueing is ' +
+                'disabled rather than risking a write being replayed twice.');
+        };
+        return {
+            exclusive: async () => refuse(),
+            tryExclusive: async () => refuse(),
+        };
+    }
+    const locks = navigator.locks;
+    return {
+        // request() resolves with whatever the callback resolves to; the DOM
+        // typings describe the callback's return as the result, so an async
+        // callback types as Promise<Promise<T>>. The runtime awaits it.
+        exclusive: (name, fn) => locks.request(name, fn),
+        tryExclusive: async (name, fn) => {
+            let ran = false;
+            await locks.request(name, { ifAvailable: true }, async (lock) => {
+                // A null lock means another tab holds it. Skip: it is already
+                // replaying the same queue, and waiting would only duplicate the
+                // wait, not the work.
+                if (!lock)
+                    return;
+                ran = true;
+                await fn();
+            });
+            return { ran };
+        },
+    };
+}
 export function browserPlatform() {
     const resolve = makeResolver();
     // Every call resolves first, so a browser that only reveals its refusal on
@@ -154,6 +210,14 @@ export function browserPlatform() {
         setItem: async (k, v) => { await (await resolve()).store.setItem(k, v); },
         removeItem: async (k) => { await (await resolve()).store.removeItem(k); },
         getAllKeys: async () => (await resolve()).store.getAllKeys(),
+        // Reaches through to the resolved tier. Only IndexedDB holds a
+        // connection worth closing; the test harness needs it released before
+        // it can delete the database between cases, and without this the
+        // façade hid the handle and every browser test hung on its hook.
+        close: async () => {
+            const r = await resolve();
+            await r.store.close?.();
+        },
     };
     // Which tier this adapter settled on: 'indexeddb', 'localstorage' or
     // 'memory'. An app that cares can warn the user before they lose a session.
@@ -201,6 +265,7 @@ export function browserPlatform() {
             os: 'web',
             version: browserVersion(),
         },
+        locks: webLocks(),
         // IndexedDB-backed; see auth-storage.ts for what that does and does not
         // protect against.
         authStorage: () => new BrowserAuthStorage(),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@koolbase/js",
-  "version": "10.1.0",
+  "version": "10.2.0",
   "description": "Koolbase SDK for the browser \u2014 auth, database, storage, realtime, functions, flags and offline sync in one package.",
   "main": "./dist/cjs/index.js",
   "types": "./dist/esm/index.d.ts",
@@ -25,7 +25,7 @@
     "url": "https://github.com/koolbase/koolbase-react-native"
   },
   "dependencies": {
-    "@koolbase/core": "10.1.0"
+    "@koolbase/core": "10.2.0"
   },
   "publishConfig": {
     "access": "public"