@koolbase/js 10.0.0 → 10.1.0

package/CHANGELOG.md

@@ -7,6 +7,55 @@ 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.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
+
+- **`restoreSession()` threw in Node.** With no `indexedDB`, the adapter fell
+  through to `localStorage`, which does not exist on a server either — so a
+  Next.js server render, or any tooling that imports the SDK, crashed with
+  `ReferenceError: localStorage is not defined`. Storage now falls back to an
+  in-memory store when neither is present, and a server render reports
+  `NoSession` rather than failing.
+
+  Note what this is not: server-side authentication. This package holds one
+  session per process, which is correct for a browser tab and wrong for a
+  server handling many users. It renders without crashing; it is not a way to
+  sign users in on a server.
+
 ## 10.0.0
 
 The first release. Numbered to match `@koolbase/react-native` and

package/README.md

@@ -11,7 +11,8 @@ feature flags, remote config, and an offline write queue with conflict
 resolution — one package, one `initialize()` call, TypeScript throughout.
 
 Same core as [`@koolbase/react-native`](https://www.npmjs.com/package/@koolbase/react-native).
-Same behaviour, proven by the same test suite on both hosts.
+Same behaviour, proven by the same test suite on both hosts. The whole SDK
+is about 16 kB gzipped.
 
 ---
 
@@ -261,7 +262,10 @@ Stated here so nothing is discovered as a method that fails:
 - **Code push** — a native-bundle concept. The web already ships on deploy.
 - **Push messaging** — FCM device tokens come from a native module. Use Web
   Push through your own service worker and your backend.
-- **Native Google / Apple sign-in** — use the web OAuth flows, above.
+- **The native sign-in libraries** — `signInWithGoogle` and
+  `signInWithApple` themselves are here and work; what a browser cannot do
+  is fetch the credential from a native module. Run the provider's web
+  OAuth flow and pass the ID token, as above.
 
 ---
 

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

@@ -94,10 +94,76 @@ function browserVersion() {
     const m = /(Chrome|Firefox|Safari|Edg)\/([\d.]+)/.exec(ua);
     return m ? `${m[1]} ${m[2]}` : '';
 }
+// Neither store exists during server-side rendering, in a Node tool, or in
+// a worker without storage access. Persisting nothing is the correct answer
+// there: a server render has no session to restore, and the client hydrates
+// with the real one. Throwing instead — which it did — crashes the render.
+function memoryStorage() {
+    const m = new Map();
+    return {
+        getItem: async (k) => m.get(k) ?? null,
+        setItem: async (k, v) => { m.set(k, v); },
+        removeItem: async (k) => { m.delete(k); },
+        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; });
+    };
+}
 function browserPlatform() {
-    const hasIDB = typeof indexedDB !== 'undefined';
+    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(),
+    };
+    // 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 {
-        storage: hasIDB ? indexedDBStorage() : localStorageStorage(),
+        storageTier,
+        storage,
         network: {
             onChange: (cb) => {
                 // navigator.onLine is a hint that the interface is up, not that

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

@@ -91,10 +91,76 @@ function browserVersion() {
     const m = /(Chrome|Firefox|Safari|Edg)\/([\d.]+)/.exec(ua);
     return m ? `${m[1]} ${m[2]}` : '';
 }
+// Neither store exists during server-side rendering, in a Node tool, or in
+// a worker without storage access. Persisting nothing is the correct answer
+// there: a server render has no session to restore, and the client hydrates
+// with the real one. Throwing instead — which it did — crashes the render.
+function memoryStorage() {
+    const m = new Map();
+    return {
+        getItem: async (k) => m.get(k) ?? null,
+        setItem: async (k, v) => { m.set(k, v); },
+        removeItem: async (k) => { m.delete(k); },
+        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; });
+    };
+}
 export function browserPlatform() {
-    const hasIDB = typeof indexedDB !== 'undefined';
+    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(),
+    };
+    // 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 {
-        storage: hasIDB ? indexedDBStorage() : localStorageStorage(),
+        storageTier,
+        storage,
         network: {
             onChange: (cb) => {
                 // navigator.onLine is a hint that the interface is up, not that

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@koolbase/js",
-  "version": "10.0.0",
+  "version": "10.1.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.0"
+    "@koolbase/core": "10.1.0"
   },
   "publishConfig": {
     "access": "public"