@koolbase/js 10.0.1 → 10.2.0

package/CHANGELOG.md

@@ -7,6 +7,58 @@ 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
+
+- **Uploads could not work from a browser.** `upload()` required
+  `{ uri, name, type }` — a React Native shape — and fetched that URI to get
+  the bytes. A browser `File` has no `uri`, so every upload from the web
+  failed before it reached the network, while the README showed a file input
+  as if it worked. `file` now accepts a `Blob` or `File` directly and the
+  React Native form is unchanged. Round-tripped in a browser: upload,
+  download, byte-for-byte comparison.
+
+### Added
+
+- **`storageTier()`** on the browser adapter — `'indexeddb'`,
+  `'localstorage'` or `'memory'`. Storage is now chosen by *trying* each
+  store rather than checking whether the API exists: Safari in private
+  browsing exposes `indexedDB` and may refuse to open it, and a browser with
+  site data blocked exposes `localStorage` and throws on write. A failure at
+  any tier falls to the next, ending in memory with one console warning. An
+  app can read the tier and tell the user their session will not survive a
+  reload.
+
+## 10.0.2
+
+### Fixed
+
+- **A Node process that initialized the SDK never exited.** The analytics
+  flush interval, and a pending realtime reconnect, counted as work on Node's
+  event loop, so a CLI, a test runner or an SSR build step hung after its last
+  line. Both timers are now unref'd where the runtime supports it. A browser
+  is unaffected: the page keeps itself alive regardless.
+
 ## 10.0.1
 
 ### 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.d.ts

@@ -1,2 +1,25 @@
 import type { PlatformAdapter } from '@koolbase/core';
-export declare function browserPlatform(): PlatformAdapter;
+/**
+ * What a browser is actually willing to persist, decided by trying.
+ *
+ * Feature detection is not capability detection. Safari in private browsing
+ * exposes `indexedDB` and then refuses to open a database; a browser with
+ * site data blocked exposes `localStorage` and throws on write; a storage
+ * quota can be exhausted at any point afterwards. A selector that checks
+ * `typeof` commits to a store that may never work.
+ *
+ * So the store is resolved on first use, by using it, and the result is
+ * cached. A failure at any tier falls to the next, ending in memory — which
+ * always works and persists nothing.
+ */
+type Tier = 'indexeddb' | 'localstorage' | 'memory';
+/**
+ * The browser adapter, plus what only a browser needs: which storage tier it
+ * settled on. Not on PlatformAdapter, because no other host has tiers — React
+ * Native's keychain either works or its package is absent.
+ */
+export interface BrowserPlatformAdapter extends PlatformAdapter {
+    storageTier(): Promise<Tier>;
+}
+export declare function browserPlatform(): BrowserPlatformAdapter;
+export {};

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
@@ -107,11 +105,128 @@ function memoryStorage() {
         getAllKeys: async () => Array.from(m.keys()),
     };
 }
+async function probe(store) {
+    const k = '__koolbase_probe__';
+    try {
+        await store.setItem(k, '1');
+        const v = await store.getItem(k);
+        await store.removeItem(k);
+        return v === '1';
+    }
+    catch {
+        return false;
+    }
+}
+function makeResolver() {
+    // Per adapter, not per module: two adapters must not share a store, or a
+    // server that built one client per request would hand one request's
+    // session to the next.
+    let resolved = null;
+    let resolving = null;
+    return () => {
+        if (resolved)
+            return Promise.resolve(resolved);
+        resolving ?? (resolving = (async () => {
+            if (typeof indexedDB !== 'undefined') {
+                const s = indexedDBStorage();
+                if (await probe(s))
+                    return { tier: 'indexeddb', store: s };
+            }
+            if (typeof localStorage !== 'undefined') {
+                const s = localStorageStorage();
+                if (await probe(s))
+                    return { tier: 'localstorage', store: s };
+            }
+            // eslint-disable-next-line no-console
+            console.warn('[Koolbase] No persistent storage available in this browser ' +
+                '(private browsing, blocked site data, or an exhausted quota). ' +
+                'The session and the offline queue will not survive a reload.');
+            return { tier: 'memory', store: memoryStorage() };
+        })());
+        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 storage = typeof indexedDB !== 'undefined' ? indexedDBStorage()
-        : typeof localStorage !== 'undefined' ? localStorageStorage()
-            : memoryStorage();
+    const resolve = makeResolver();
+    // Every call resolves first, so a browser that only reveals its refusal on
+    // use is handled here rather than by the caller.
+    const storage = {
+        getItem: async (k) => (await resolve()).store.getItem(k),
+        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.
+    const storageTier = async () => (await resolve()).tier;
     return {
+        storageTier,
         storage,
         network: {
             onChange: (cb) => {
@@ -153,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.d.ts

@@ -1,2 +1,25 @@
 import type { PlatformAdapter } from '@koolbase/core';
-export declare function browserPlatform(): PlatformAdapter;
+/**
+ * What a browser is actually willing to persist, decided by trying.
+ *
+ * Feature detection is not capability detection. Safari in private browsing
+ * exposes `indexedDB` and then refuses to open a database; a browser with
+ * site data blocked exposes `localStorage` and throws on write; a storage
+ * quota can be exhausted at any point afterwards. A selector that checks
+ * `typeof` commits to a store that may never work.
+ *
+ * So the store is resolved on first use, by using it, and the result is
+ * cached. A failure at any tier falls to the next, ending in memory — which
+ * always works and persists nothing.
+ */
+type Tier = 'indexeddb' | 'localstorage' | 'memory';
+/**
+ * The browser adapter, plus what only a browser needs: which storage tier it
+ * settled on. Not on PlatformAdapter, because no other host has tiers — React
+ * Native's keychain either works or its package is absent.
+ */
+export interface BrowserPlatformAdapter extends PlatformAdapter {
+    storageTier(): Promise<Tier>;
+}
+export declare function browserPlatform(): BrowserPlatformAdapter;
+export {};

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
@@ -104,11 +102,128 @@ function memoryStorage() {
         getAllKeys: async () => Array.from(m.keys()),
     };
 }
+async function probe(store) {
+    const k = '__koolbase_probe__';
+    try {
+        await store.setItem(k, '1');
+        const v = await store.getItem(k);
+        await store.removeItem(k);
+        return v === '1';
+    }
+    catch {
+        return false;
+    }
+}
+function makeResolver() {
+    // Per adapter, not per module: two adapters must not share a store, or a
+    // server that built one client per request would hand one request's
+    // session to the next.
+    let resolved = null;
+    let resolving = null;
+    return () => {
+        if (resolved)
+            return Promise.resolve(resolved);
+        resolving ?? (resolving = (async () => {
+            if (typeof indexedDB !== 'undefined') {
+                const s = indexedDBStorage();
+                if (await probe(s))
+                    return { tier: 'indexeddb', store: s };
+            }
+            if (typeof localStorage !== 'undefined') {
+                const s = localStorageStorage();
+                if (await probe(s))
+                    return { tier: 'localstorage', store: s };
+            }
+            // eslint-disable-next-line no-console
+            console.warn('[Koolbase] No persistent storage available in this browser ' +
+                '(private browsing, blocked site data, or an exhausted quota). ' +
+                'The session and the offline queue will not survive a reload.');
+            return { tier: 'memory', store: memoryStorage() };
+        })());
+        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 storage = typeof indexedDB !== 'undefined' ? indexedDBStorage()
-        : typeof localStorage !== 'undefined' ? localStorageStorage()
-            : memoryStorage();
+    const resolve = makeResolver();
+    // Every call resolves first, so a browser that only reveals its refusal on
+    // use is handled here rather than by the caller.
+    const storage = {
+        getItem: async (k) => (await resolve()).store.getItem(k),
+        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.
+    const storageTier = async () => (await resolve()).tier;
     return {
+        storageTier,
         storage,
         network: {
             onChange: (cb) => {
@@ -150,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.0.1",
+  "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.0.1"
+    "@koolbase/core": "10.2.0"
   },
   "publishConfig": {
     "access": "public"