@koolbase/core 10.0.1 → 10.2.0

package/dist/cjs/analytics.js

@@ -29,6 +29,11 @@ class KoolbaseAnalytics {
         (0, platform_js_1.getPlatform)().lifecycle.onBackground(() => { this.flush(); });
         // Periodic flush
         this.flushTimer = setInterval(() => this.flush(), FLUSH_INTERVAL_MS);
+        // A browser keeps the page alive regardless; Node counts this timer as
+        // work and will not exit while it is pending. Without unref, any script
+        // that initializes the SDK — a CLI, a test runner, an SSR build step —
+        // hangs after its last line. unref exists only on Node's timer object.
+        this.flushTimer.unref?.();
         // Auto track app_open
         this.track('app_open');
         this.initialized = true;

package/dist/cjs/index.d.ts

@@ -19,4 +19,4 @@ export { getOrCreateDeviceId } from './device-id.js';
 export { koolbaseSdkVersion } from './device-metadata.js';
 export { RestoreResult } from './types.js';
 export type { AuthStateListener, FetchLike, KoolbaseAuthStorage } from './types.js';
-export { setPlatform, getPlatform, memoryPlatform, type PlatformAdapter, type PlatformStorage, type PlatformNetwork, type PlatformLifecycle, type PlatformInfo, } from './platform.js';
+export { setPlatform, getPlatform, memoryPlatform, type PlatformAdapter, type PlatformStorage, type PlatformNetwork, type PlatformLifecycle, type PlatformLocks, type PlatformInfo, } from './platform.js';

package/dist/cjs/offline-state.d.ts

@@ -70,6 +70,14 @@ export interface OfflineState {
 export declare class OfflineStateTooLargeError extends Error {
     constructor(bytes: number);
 }
+/**
+ * Lock names derive from the storage key they protect, so the two cannot
+ * drift apart. Note what the key does NOT carry: a project id. Two Koolbase
+ * apps on one origin with the same user id already share offline state —
+ * a pre-existing collision these locks neither create nor fix.
+ */
+export declare function stateLockName(userId: string): string;
+export declare function flushLockName(userId: string): string;
 export declare function readOfflineState(userId: string): Promise<OfflineState>;
 /**
  * Reads, mutates, and writes the state under the user's lock.

package/dist/cjs/offline-state.js

@@ -2,6 +2,8 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.OfflineStateTooLargeError = void 0;
 exports.recordKey = recordKey;
+exports.stateLockName = stateLockName;
+exports.flushLockName = flushLockName;
 exports.readOfflineState = readOfflineState;
 exports.mutateOfflineState = mutateOfflineState;
 exports.queueWrite = queueWrite;
@@ -72,6 +74,18 @@ function byteLength(s) {
     return bytes;
 }
 const locks = () => (0, shared_js_1.shared)('locks', () => new Map());
+/**
+ * Lock names derive from the storage key they protect, so the two cannot
+ * drift apart. Note what the key does NOT carry: a project id. Two Koolbase
+ * apps on one origin with the same user id already share offline state —
+ * a pre-existing collision these locks neither create nor fix.
+ */
+function stateLockName(userId) {
+    return `${stateKey(userId)}:lock`;
+}
+function flushLockName(userId) {
+    return `${stateKey(userId)}:flush`;
+}
 async function withLock(userId, fn) {
     const previous = locks().get(userId) ?? Promise.resolve();
     let release = () => { };
@@ -79,7 +93,10 @@ async function withLock(userId, fn) {
     locks().set(userId, previous.then(() => next));
     await previous;
     try {
-        return await fn();
+        // In-process first, then across copies of the app that share this store.
+        // Both are needed: the promise chain orders callers within one runtime,
+        // the platform lock orders runtimes.
+        return await (0, platform_js_1.getPlatform)().locks.exclusive(stateLockName(userId), fn);
     }
     finally {
         release();

package/dist/cjs/platform.d.ts

@@ -17,6 +17,31 @@ export interface PlatformLifecycle {
     /** Subscribe to the app moving to the background. Used to flush analytics. */
     onBackground(callback: () => void): () => void;
 }
+/**
+ * Coordination between copies of the SDK that share durable storage.
+ *
+ * Two locks, different problems, different durations:
+ *
+ *   exclusive     short, waited for, held across a read-modify-write of the
+ *                 offline state and never across the network. Stops one copy
+ *                 overwriting another's queued write.
+ *
+ *   tryExclusive  a lease on the responsibility to replay the queue, held for
+ *                 a whole flush pass INCLUDING its HTTP calls, and never
+ *                 waited for. Without it two tabs read the same pending write
+ *                 and both send it: the state stays consistent and the server
+ *                 is hit twice. A copy that cannot take the lease skips,
+ *                 because whoever holds it is already doing the work.
+ *
+ * A host where the SDK cannot be running twice over one store — React Native,
+ * one process — satisfies both by just running the function.
+ */
+export interface PlatformLocks {
+    exclusive<T>(name: string, fn: () => Promise<T>): Promise<T>;
+    tryExclusive(name: string, fn: () => Promise<void>): Promise<{
+        ran: boolean;
+    }>;
+}
 export interface PlatformInfo {
     /** e.g. 'ios', 'android', 'web' */
     os: string;
@@ -28,6 +53,7 @@ export interface PlatformAdapter {
     network: PlatformNetwork;
     lifecycle: PlatformLifecycle;
     info: PlatformInfo;
+    locks: PlatformLocks;
     /**
      * The host's best persistent store for the auth session, or null if it has
      * none worth the name. Used only when the app injects nothing through

package/dist/cjs/platform.js

@@ -28,6 +28,12 @@ function memoryPlatform() {
             onBackground: () => () => { },
         },
         info: { os: 'memory', version: '' },
+        // One process, one store, and the in-process promise chain in
+        // offline-state already serialises it.
+        locks: {
+            exclusive: (_n, fn) => fn(),
+            tryExclusive: async (_n, fn) => { await fn(); return { ran: true }; },
+        },
         authStorage: () => null,
     };
 }

package/dist/cjs/realtime.js

@@ -176,10 +176,13 @@ class KoolbaseRealtime {
             return;
         const delay = Math.min(3000 * Math.pow(2, this.reconnectAttempts), 60000);
         this.reconnectAttempts += 1;
+        // Same reason as the analytics flush: a pending reconnect must not be
+        // the thing that keeps a Node process alive.
         this.reconnectTimer = setTimeout(() => {
             this.reconnectTimer = null;
             void this.connect();
         }, delay);
+        this.reconnectTimer.unref?.();
     }
     disconnect() {
         if (this.reconnectTimer) {

package/dist/cjs/storage.js

@@ -88,7 +88,14 @@ class KoolbaseStorage {
      */
     async upload(options) {
         const overwrite = options.overwrite ?? false;
-        const contentType = options.file.type;
+        // A Blob (browser File included) knows its own type; the React Native
+        // URI form carries it alongside. Falling back to octet-stream keeps a
+        // typeless Blob from presigning with an empty content type, which R2
+        // then refuses at PUT.
+        const isBlob = typeof Blob !== 'undefined' && options.file instanceof Blob;
+        const contentType = isBlob
+            ? options.file.type || 'application/octet-stream'
+            : options.file.type;
         // ─── Step 1: Get presigned upload URL ───
         const urlRes = await fetch(`${this.config.baseUrl}/v1/sdk/storage/upload-url`, {
             method: 'POST',
@@ -108,10 +115,15 @@ class KoolbaseStorage {
         }
         const { upload_url } = (await urlRes.json());
         // ─── Step 2: Upload directly to R2 ───
-        // RN's fetch resolves local file URIs and Blob bodies on a raw PUT.
         // R2 presigned URLs expect raw binary, NOT multipart/form-data.
-        const fileResp = await fetch(options.file.uri);
-        const fileBlob = await fileResp.blob();
+        //
+        // A browser hands us the bytes already: a File from an input is a Blob,
+        // and fetching its .uri would be fetching undefined. React Native hands
+        // us a local URI, and its fetch resolves that into a Blob — which is why
+        // the two hosts differ here and nowhere else in this method.
+        const fileBlob = isBlob
+            ? options.file
+            : await (await fetch(options.file.uri)).blob();
         const fileSize = fileBlob.size;
         const uploadRes = await fetch(upload_url, {
             method: 'PUT',

package/dist/cjs/sync-engine.d.ts

@@ -18,6 +18,9 @@ export declare class SyncEngine {
     start(): void;
     stop(): void;
     flush(): Promise<void>;
+    private recheckTimer;
+    private scheduleRecheck;
+    private flushHeld;
     /**
      * Sends one queued write, returning the revision the record now carries.
      *

package/dist/cjs/sync-engine.js

@@ -45,6 +45,7 @@ class RevisionMismatch extends Error {
 class SyncEngine {
     constructor(config, getUserId, getToken, onSyncComplete, onSessionExpired) {
         this.isSyncing = false;
+        this.recheckTimer = null;
         this.config = config;
         this.getUserId = getUserId;
         this.getToken = getToken;
@@ -66,6 +67,32 @@ class SyncEngine {
         const userId = this.getUserId();
         if (!userId)
             return;
+        // A lease on replaying this user's queue, held for the whole pass
+        // including its HTTP calls. isSyncing does this within one runtime; this
+        // does it across every copy sharing the store. Not waited for: a copy
+        // that cannot take it skips, because the holder is replaying the same
+        // queue — waiting would duplicate the wait, not the work.
+        const { ran } = await (0, platform_js_1.getPlatform)().locks.tryExclusive((0, offline_state_js_1.flushLockName)(userId), () => this.flushHeld(userId));
+        if (!ran) {
+            // Skipped, and a write queued between the holder's last read and its
+            // release would otherwise sit until an unrelated reconnect. Re-check
+            // once, after the holder has had time to finish; if it is still
+            // running, its own recheck covers what we would have sent.
+            this.scheduleRecheck();
+        }
+    }
+    scheduleRecheck() {
+        // Bounded and coalesced: one pending recheck at a time, so a page with
+        // several tabs cannot turn a skipped flush into a retry storm.
+        if (this.recheckTimer)
+            return;
+        this.recheckTimer = setTimeout(() => {
+            this.recheckTimer = null;
+            void this.flush();
+        }, 1500);
+        this.recheckTimer.unref?.();
+    }
+    async flushHeld(userId) {
         this.isSyncing = true;
         try {
             // Before anything is sent. Writes queued by an earlier version sit under a

package/dist/cjs/types.d.ts

@@ -214,7 +214,16 @@ export interface SemanticSearchResult {
 export interface UploadOptions {
     bucket: string;
     path: string;
-    file: {
+    /**
+     * The bytes to upload, in whichever form the host produces them.
+     *
+     * A browser gives you a `File` from an `<input type="file">` or a `Blob`
+     * you built; pass it directly. React Native gives you a local URI from an
+     * image picker or the file system; pass `{ uri, name, type }` and the SDK
+     * resolves it. A Blob already carries its own content type, so `type` is
+     * only needed for the URI form.
+     */
+    file: Blob | {
         uri: string;
         name: string;
         type: string;

package/dist/esm/analytics.js

@@ -26,6 +26,11 @@ export class KoolbaseAnalytics {
         getPlatform().lifecycle.onBackground(() => { this.flush(); });
         // Periodic flush
         this.flushTimer = setInterval(() => this.flush(), FLUSH_INTERVAL_MS);
+        // A browser keeps the page alive regardless; Node counts this timer as
+        // work and will not exit while it is pending. Without unref, any script
+        // that initializes the SDK — a CLI, a test runner, an SSR build step —
+        // hangs after its last line. unref exists only on Node's timer object.
+        this.flushTimer.unref?.();
         // Auto track app_open
         this.track('app_open');
         this.initialized = true;

package/dist/esm/index.d.ts

@@ -19,4 +19,4 @@ export { getOrCreateDeviceId } from './device-id.js';
 export { koolbaseSdkVersion } from './device-metadata.js';
 export { RestoreResult } from './types.js';
 export type { AuthStateListener, FetchLike, KoolbaseAuthStorage } from './types.js';
-export { setPlatform, getPlatform, memoryPlatform, type PlatformAdapter, type PlatformStorage, type PlatformNetwork, type PlatformLifecycle, type PlatformInfo, } from './platform.js';
+export { setPlatform, getPlatform, memoryPlatform, type PlatformAdapter, type PlatformStorage, type PlatformNetwork, type PlatformLifecycle, type PlatformLocks, type PlatformInfo, } from './platform.js';

package/dist/esm/offline-state.d.ts

@@ -70,6 +70,14 @@ export interface OfflineState {
 export declare class OfflineStateTooLargeError extends Error {
     constructor(bytes: number);
 }
+/**
+ * Lock names derive from the storage key they protect, so the two cannot
+ * drift apart. Note what the key does NOT carry: a project id. Two Koolbase
+ * apps on one origin with the same user id already share offline state —
+ * a pre-existing collision these locks neither create nor fix.
+ */
+export declare function stateLockName(userId: string): string;
+export declare function flushLockName(userId: string): string;
 export declare function readOfflineState(userId: string): Promise<OfflineState>;
 /**
  * Reads, mutates, and writes the state under the user's lock.

package/dist/esm/offline-state.js

@@ -63,6 +63,18 @@ function byteLength(s) {
     return bytes;
 }
 const locks = () => shared('locks', () => new Map());
+/**
+ * Lock names derive from the storage key they protect, so the two cannot
+ * drift apart. Note what the key does NOT carry: a project id. Two Koolbase
+ * apps on one origin with the same user id already share offline state —
+ * a pre-existing collision these locks neither create nor fix.
+ */
+export function stateLockName(userId) {
+    return `${stateKey(userId)}:lock`;
+}
+export function flushLockName(userId) {
+    return `${stateKey(userId)}:flush`;
+}
 async function withLock(userId, fn) {
     const previous = locks().get(userId) ?? Promise.resolve();
     let release = () => { };
@@ -70,7 +82,10 @@ async function withLock(userId, fn) {
     locks().set(userId, previous.then(() => next));
     await previous;
     try {
-        return await fn();
+        // In-process first, then across copies of the app that share this store.
+        // Both are needed: the promise chain orders callers within one runtime,
+        // the platform lock orders runtimes.
+        return await getPlatform().locks.exclusive(stateLockName(userId), fn);
     }
     finally {
         release();

package/dist/esm/platform.d.ts

@@ -17,6 +17,31 @@ export interface PlatformLifecycle {
     /** Subscribe to the app moving to the background. Used to flush analytics. */
     onBackground(callback: () => void): () => void;
 }
+/**
+ * Coordination between copies of the SDK that share durable storage.
+ *
+ * Two locks, different problems, different durations:
+ *
+ *   exclusive     short, waited for, held across a read-modify-write of the
+ *                 offline state and never across the network. Stops one copy
+ *                 overwriting another's queued write.
+ *
+ *   tryExclusive  a lease on the responsibility to replay the queue, held for
+ *                 a whole flush pass INCLUDING its HTTP calls, and never
+ *                 waited for. Without it two tabs read the same pending write
+ *                 and both send it: the state stays consistent and the server
+ *                 is hit twice. A copy that cannot take the lease skips,
+ *                 because whoever holds it is already doing the work.
+ *
+ * A host where the SDK cannot be running twice over one store — React Native,
+ * one process — satisfies both by just running the function.
+ */
+export interface PlatformLocks {
+    exclusive<T>(name: string, fn: () => Promise<T>): Promise<T>;
+    tryExclusive(name: string, fn: () => Promise<void>): Promise<{
+        ran: boolean;
+    }>;
+}
 export interface PlatformInfo {
     /** e.g. 'ios', 'android', 'web' */
     os: string;
@@ -28,6 +53,7 @@ export interface PlatformAdapter {
     network: PlatformNetwork;
     lifecycle: PlatformLifecycle;
     info: PlatformInfo;
+    locks: PlatformLocks;
     /**
      * The host's best persistent store for the auth session, or null if it has
      * none worth the name. Used only when the app injects nothing through

package/dist/esm/platform.js

@@ -23,6 +23,12 @@ export function memoryPlatform() {
             onBackground: () => () => { },
         },
         info: { os: 'memory', version: '' },
+        // One process, one store, and the in-process promise chain in
+        // offline-state already serialises it.
+        locks: {
+            exclusive: (_n, fn) => fn(),
+            tryExclusive: async (_n, fn) => { await fn(); return { ran: true }; },
+        },
         authStorage: () => null,
     };
 }

package/dist/esm/realtime.js

@@ -173,10 +173,13 @@ export class KoolbaseRealtime {
             return;
         const delay = Math.min(3000 * Math.pow(2, this.reconnectAttempts), 60000);
         this.reconnectAttempts += 1;
+        // Same reason as the analytics flush: a pending reconnect must not be
+        // the thing that keeps a Node process alive.
         this.reconnectTimer = setTimeout(() => {
             this.reconnectTimer = null;
             void this.connect();
         }, delay);
+        this.reconnectTimer.unref?.();
     }
     disconnect() {
         if (this.reconnectTimer) {

package/dist/esm/storage.js

@@ -85,7 +85,14 @@ export class KoolbaseStorage {
      */
     async upload(options) {
         const overwrite = options.overwrite ?? false;
-        const contentType = options.file.type;
+        // A Blob (browser File included) knows its own type; the React Native
+        // URI form carries it alongside. Falling back to octet-stream keeps a
+        // typeless Blob from presigning with an empty content type, which R2
+        // then refuses at PUT.
+        const isBlob = typeof Blob !== 'undefined' && options.file instanceof Blob;
+        const contentType = isBlob
+            ? options.file.type || 'application/octet-stream'
+            : options.file.type;
         // ─── Step 1: Get presigned upload URL ───
         const urlRes = await fetch(`${this.config.baseUrl}/v1/sdk/storage/upload-url`, {
             method: 'POST',
@@ -105,10 +112,15 @@ export class KoolbaseStorage {
         }
         const { upload_url } = (await urlRes.json());
         // ─── Step 2: Upload directly to R2 ───
-        // RN's fetch resolves local file URIs and Blob bodies on a raw PUT.
         // R2 presigned URLs expect raw binary, NOT multipart/form-data.
-        const fileResp = await fetch(options.file.uri);
-        const fileBlob = await fileResp.blob();
+        //
+        // A browser hands us the bytes already: a File from an input is a Blob,
+        // and fetching its .uri would be fetching undefined. React Native hands
+        // us a local URI, and its fetch resolves that into a Blob — which is why
+        // the two hosts differ here and nowhere else in this method.
+        const fileBlob = isBlob
+            ? options.file
+            : await (await fetch(options.file.uri)).blob();
         const fileSize = fileBlob.size;
         const uploadRes = await fetch(upload_url, {
             method: 'PUT',

package/dist/esm/sync-engine.d.ts

@@ -18,6 +18,9 @@ export declare class SyncEngine {
     start(): void;
     stop(): void;
     flush(): Promise<void>;
+    private recheckTimer;
+    private scheduleRecheck;
+    private flushHeld;
     /**
      * Sends one queued write, returning the revision the record now carries.
      *

package/dist/esm/sync-engine.js

@@ -1,4 +1,4 @@
-import { readOfflineState, mutateOfflineState, migrateLegacyQueue, } from './offline-state.js';
+import { readOfflineState, mutateOfflineState, migrateLegacyQueue, flushLockName, } from './offline-state.js';
 import { KoolbaseUnauthenticatedError } from './errors.js';
 import { getPlatform } from './platform.js';
 import { invalidateCache, removeCachedRecord, } from './cache-store.js';
@@ -42,6 +42,7 @@ class RevisionMismatch extends Error {
 export class SyncEngine {
     constructor(config, getUserId, getToken, onSyncComplete, onSessionExpired) {
         this.isSyncing = false;
+        this.recheckTimer = null;
         this.config = config;
         this.getUserId = getUserId;
         this.getToken = getToken;
@@ -63,6 +64,32 @@ export class SyncEngine {
         const userId = this.getUserId();
         if (!userId)
             return;
+        // A lease on replaying this user's queue, held for the whole pass
+        // including its HTTP calls. isSyncing does this within one runtime; this
+        // does it across every copy sharing the store. Not waited for: a copy
+        // that cannot take it skips, because the holder is replaying the same
+        // queue — waiting would duplicate the wait, not the work.
+        const { ran } = await getPlatform().locks.tryExclusive(flushLockName(userId), () => this.flushHeld(userId));
+        if (!ran) {
+            // Skipped, and a write queued between the holder's last read and its
+            // release would otherwise sit until an unrelated reconnect. Re-check
+            // once, after the holder has had time to finish; if it is still
+            // running, its own recheck covers what we would have sent.
+            this.scheduleRecheck();
+        }
+    }
+    scheduleRecheck() {
+        // Bounded and coalesced: one pending recheck at a time, so a page with
+        // several tabs cannot turn a skipped flush into a retry storm.
+        if (this.recheckTimer)
+            return;
+        this.recheckTimer = setTimeout(() => {
+            this.recheckTimer = null;
+            void this.flush();
+        }, 1500);
+        this.recheckTimer.unref?.();
+    }
+    async flushHeld(userId) {
         this.isSyncing = true;
         try {
             // Before anything is sent. Writes queued by an earlier version sit under a

package/dist/esm/types.d.ts

@@ -214,7 +214,16 @@ export interface SemanticSearchResult {
 export interface UploadOptions {
     bucket: string;
     path: string;
-    file: {
+    /**
+     * The bytes to upload, in whichever form the host produces them.
+     *
+     * A browser gives you a `File` from an `<input type="file">` or a `Blob`
+     * you built; pass it directly. React Native gives you a local URI from an
+     * image picker or the file system; pass `{ uri, name, type }` and the SDK
+     * resolves it. A Blob already carries its own content type, so `type` is
+     * only needed for the URI form.
+     */
+    file: Blob | {
         uri: string;
         name: string;
         type: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@koolbase/core",
-  "version": "10.0.1",
+  "version": "10.2.0",
   "description": "Koolbase SDK core \u2014 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",