dexie-cloud-addon 4.4.0 → 4.4.2

package/dist/modern/DexieCloudOptions.d.ts

@@ -50,4 +50,16 @@ export interface DexieCloudOptions {
      *   Best for apps with large media that may not all be needed offline.
      */
     blobMode?: 'eager' | 'lazy';
+    /** Maximum string length (in characters) before offloading to blob storage during sync.
+     *
+     * Strings longer than this threshold are uploaded as blobs during sync,
+     * reducing sync payload size. The original string is kept intact in IndexedDB.
+     *
+     * Set to `Infinity` to disable string offloading.
+     * Minimum value is 100 to prevent accidental offloading of primary keys.
+     * Maximum value is 32768 (server limit).
+     *
+     * @default 32768
+     */
+    maxStringLength?: number;
 }

package/dist/modern/default-ui/AuthProviderButton.d.ts

@@ -0,0 +1,21 @@
+import { h } from 'preact';
+import type { OAuthProviderInfo } from 'dexie-cloud-common';
+export interface AuthProviderButtonProps {
+    provider: OAuthProviderInfo;
+    onClick: () => void;
+}
+/**
+ * Button component for OAuth provider login.
+ * Displays the provider's icon and name following provider branding guidelines.
+ */
+export declare function AuthProviderButton({ provider, onClick }: AuthProviderButtonProps): h.JSX.Element;
+/**
+ * Button for email/OTP authentication option.
+ */
+export declare function OtpButton({ onClick }: {
+    onClick: () => void;
+}): h.JSX.Element;
+/**
+ * Visual divider with "or" text.
+ */
+export declare function Divider(): h.JSX.Element;

package/dist/modern/default-ui/ProviderSelectionDialog.d.ts

@@ -0,0 +1,7 @@
+import { h } from 'preact';
+import { DXCProviderSelection } from '../types/DXCUserInteraction';
+/**
+ * Dialog component for OAuth provider selection.
+ * Displays available OAuth providers as buttons and optionally an email/OTP option.
+ */
+export declare function ProviderSelectionDialog({ title, alerts, providers, otpEnabled, cancelLabel, onSelectProvider, onSelectOtp, onCancel, }: DXCProviderSelection): h.JSX.Element;

package/dist/modern/default-ui/SelectDialog.d.ts

@@ -0,0 +1,10 @@
+import { h } from 'preact';
+import { DXCSelect } from '../types/DXCUserInteraction';
+/**
+ * Dialog component for generic option selection.
+ * Displays available options as buttons.
+ *
+ * This component is UI-agnostic and works with any DXCSelect interaction,
+ * whether for authentication, settings, or other selection purposes.
+ */
+export declare function SelectDialog({ title, alerts, options, cancelLabel, onSelect, onCancel, }: DXCSelect): h.JSX.Element;

package/dist/modern/dexie-cloud-addon.js

@@ -8,7 +8,7 @@
  *
  * ==========================================================================
  *
- * Version 4.4.0, Wed Mar 18 2026
+ * Version 4.4.2, Thu Mar 19 2026
  *
  * https://dexie.org
  *
@@ -1365,10 +1365,48 @@ function isSerializedTSONRef(value) {
         obj._bt === undefined // Not a raw BlobRef
     );
 }
+/**
+ * Recursively check if an object contains any BlobRefs
+ */
+function hasBlobRefs(obj, visited = new WeakSet()) {
+    if (obj === null || obj === undefined) {
+        return false;
+    }
+    if (isBlobRef(obj)) {
+        return true;
+    }
+    if (typeof obj !== 'object') {
+        return false;
+    }
+    // Avoid circular references - check BEFORE processing
+    if (visited.has(obj)) {
+        return false;
+    }
+    visited.add(obj);
+    // Skip special objects that can't contain BlobRefs
+    if (obj instanceof Date || obj instanceof RegExp || obj instanceof Blob) {
+        return false;
+    }
+    if (obj instanceof ArrayBuffer || ArrayBuffer.isView(obj)) {
+        return false;
+    }
+    if (Array.isArray(obj)) {
+        return obj.some(item => hasBlobRefs(item, visited));
+    }
+    // Only traverse POJOs
+    if (obj.constructor === Object) {
+        return Object.values(obj).some(value => hasBlobRefs(value, visited));
+    }
+    return false;
+}
 /**
  * Convert downloaded Uint8Array to the original type specified in BlobRef
  */
 function convertToOriginalType(data, ref) {
+    // String type: decode UTF-8 back to string
+    if (ref._bt === 'string') {
+        return new TextDecoder().decode(data);
+    }
     // Get the underlying ArrayBuffer (handle shared buffer case)
     const buffer = data.buffer.byteLength === data.byteLength
         ? data.buffer
@@ -3541,6 +3579,19 @@ function bulkUpdate(table, keys, changeSpecs) {
     });
 }
 
+/**
+ * If the incoming value contains BlobRefs (e.g. offloaded strings or binaries),
+ * mark it with _hasBlobRefs = 1 so the blobResolveMiddleware will resolve them
+ * on the next read.
+ */
+function markIfHasBlobRefs(obj) {
+    if (obj !== null &&
+        typeof obj === 'object' &&
+        obj.constructor === Object &&
+        hasBlobRefs(obj)) {
+        obj._hasBlobRefs = 1;
+    }
+}
 function applyServerChanges(changes, db) {
     return __awaiter(this, void 0, void 0, function* () {
         console.debug('Applying server changes', changes, Dexie.currentTransaction);
@@ -3576,6 +3627,7 @@ function applyServerChanges(changes, db) {
                 const keys = mut.keys.map(keyDecoder);
                 switch (mut.type) {
                     case 'insert':
+                        mut.values.forEach(markIfHasBlobRefs);
                         if (primaryKey.outbound) {
                             yield table.bulkAdd(mut.values, keys);
                         }
@@ -3588,6 +3640,7 @@ function applyServerChanges(changes, db) {
                         }
                         break;
                     case 'upsert':
+                        mut.values.forEach(markIfHasBlobRefs);
                         if (primaryKey.outbound) {
                             yield table.bulkPut(mut.values, keys);
                         }
@@ -3843,6 +3896,8 @@ function applyYServerMessages(yMessages, db) {
  */
 // Blobs >= 4KB are offloaded to blob storage
 const BLOB_OFFLOAD_THRESHOLD = 4096;
+// Default max string length before offloading (32KB characters)
+const DEFAULT_MAX_STRING_LENGTH = 32768;
 // Cache: once we know the server doesn't support blob storage, skip future uploads.
 // Maps databaseUrl → boolean (true = supported, false = not supported).
 const blobEndpointSupported = new Map();
@@ -3983,10 +4038,10 @@ function uploadBlob(databaseUrl, getCachedAccessToken, blob) {
         );
     });
 }
-function offloadBlobsAndMarkDirty(obj, databaseUrl, getCachedAccessToken) {
-    return __awaiter(this, void 0, void 0, function* () {
+function offloadBlobsAndMarkDirty(obj_1, databaseUrl_1, getCachedAccessToken_1) {
+    return __awaiter(this, arguments, void 0, function* (obj, databaseUrl, getCachedAccessToken, maxStringLength = DEFAULT_MAX_STRING_LENGTH) {
         const dirtyFlag = { dirty: false };
-        const result = yield offloadBlobs(obj, databaseUrl, getCachedAccessToken, dirtyFlag);
+        const result = yield offloadBlobs(obj, databaseUrl, getCachedAccessToken, maxStringLength, dirtyFlag);
         // Mark the object as dirty for sync if any blobs were offloaded
         if (dirtyFlag.dirty && typeof result === 'object' && result !== null && result.constructor === Object) {
             result._hasBlobRefs = 1;
@@ -3999,10 +4054,26 @@ function offloadBlobsAndMarkDirty(obj, databaseUrl, getCachedAccessToken) {
  * Returns a new object with blobs replaced by BlobRefs
  */
 function offloadBlobs(obj_1, databaseUrl_1, getCachedAccessToken_1) {
-    return __awaiter(this, arguments, void 0, function* (obj, databaseUrl, getCachedAccessToken, dirtyFlag = { dirty: false }, visited = new WeakSet()) {
+    return __awaiter(this, arguments, void 0, function* (obj, databaseUrl, getCachedAccessToken, maxStringLength = DEFAULT_MAX_STRING_LENGTH, dirtyFlag = { dirty: false }, visited = new WeakSet()) {
         if (obj === null || obj === undefined) {
             return obj;
         }
+        // Check if this is a long string that should be offloaded
+        if (typeof obj === 'string' && obj.length > maxStringLength && maxStringLength !== Infinity) {
+            if (blobEndpointSupported.get(databaseUrl) === false) {
+                return obj;
+            }
+            const blob = new Blob([obj], { type: 'text/plain;charset=utf-8' });
+            const blobRef = yield uploadBlob(databaseUrl, getCachedAccessToken, blob);
+            if (blobRef === null) {
+                blobEndpointSupported.set(databaseUrl, false);
+                return obj;
+            }
+            blobEndpointSupported.set(databaseUrl, true);
+            dirtyFlag.dirty = true;
+            // Mark as string type so it's resolved back to string, not Blob
+            return Object.assign(Object.assign({}, blobRef), { _bt: 'string' });
+        }
         // Check if this is a blob that should be offloaded
         if (shouldOffloadBlob(obj)) {
             if (blobEndpointSupported.get(databaseUrl) === false) {
@@ -4031,7 +4102,7 @@ function offloadBlobs(obj_1, databaseUrl_1, getCachedAccessToken_1) {
         if (Array.isArray(obj)) {
             const result = [];
             for (const item of obj) {
-                result.push(yield offloadBlobs(item, databaseUrl, getCachedAccessToken, dirtyFlag, visited));
+                result.push(yield offloadBlobs(item, databaseUrl, getCachedAccessToken, maxStringLength, dirtyFlag, visited));
             }
             return result;
         }
@@ -4043,7 +4114,7 @@ function offloadBlobs(obj_1, databaseUrl_1, getCachedAccessToken_1) {
         }
         const result = {};
         for (const [key, value] of Object.entries(obj)) {
-            result[key] = yield offloadBlobs(value, databaseUrl, getCachedAccessToken, dirtyFlag, visited);
+            result[key] = yield offloadBlobs(value, databaseUrl, getCachedAccessToken, maxStringLength, dirtyFlag, visited);
         }
         return result;
     });
@@ -4052,13 +4123,13 @@ function offloadBlobs(obj_1, databaseUrl_1, getCachedAccessToken_1) {
  * Process a DBOperationsSet and offload any large blobs
  * Returns a new DBOperationsSet with blobs replaced by BlobRefs
  */
-function offloadBlobsInOperations(operations, databaseUrl, getCachedAccessToken) {
-    return __awaiter(this, void 0, void 0, function* () {
+function offloadBlobsInOperations(operations_1, databaseUrl_1, getCachedAccessToken_1) {
+    return __awaiter(this, arguments, void 0, function* (operations, databaseUrl, getCachedAccessToken, maxStringLength = DEFAULT_MAX_STRING_LENGTH) {
         const result = [];
         for (const tableOps of operations) {
             const processedMuts = [];
             for (const mut of tableOps.muts) {
-                const processedMut = yield offloadBlobsInOperation(mut, databaseUrl, getCachedAccessToken);
+                const processedMut = yield offloadBlobsInOperation(mut, databaseUrl, getCachedAccessToken, maxStringLength);
                 processedMuts.push(processedMut);
             }
             result.push({
@@ -4069,20 +4140,20 @@ function offloadBlobsInOperations(operations, databaseUrl, getCachedAccessToken)
         return result;
     });
 }
-function offloadBlobsInOperation(op, databaseUrl, getCachedAccessToken) {
-    return __awaiter(this, void 0, void 0, function* () {
+function offloadBlobsInOperation(op_1, databaseUrl_1, getCachedAccessToken_1) {
+    return __awaiter(this, arguments, void 0, function* (op, databaseUrl, getCachedAccessToken, maxStringLength = DEFAULT_MAX_STRING_LENGTH) {
         switch (op.type) {
             case 'insert':
             case 'upsert': {
-                const processedValues = yield Promise.all(op.values.map(value => offloadBlobsAndMarkDirty(value, databaseUrl, getCachedAccessToken)));
+                const processedValues = yield Promise.all(op.values.map(value => offloadBlobsAndMarkDirty(value, databaseUrl, getCachedAccessToken, maxStringLength)));
                 return Object.assign(Object.assign({}, op), { values: processedValues });
             }
             case 'update': {
-                const processedChangeSpecs = yield Promise.all(op.changeSpecs.map(spec => offloadBlobsAndMarkDirty(spec, databaseUrl, getCachedAccessToken)));
+                const processedChangeSpecs = yield Promise.all(op.changeSpecs.map(spec => offloadBlobsAndMarkDirty(spec, databaseUrl, getCachedAccessToken, maxStringLength)));
                 return Object.assign(Object.assign({}, op), { changeSpecs: processedChangeSpecs });
             }
             case 'modify': {
-                const processedChangeSpec = yield offloadBlobsAndMarkDirty(op.changeSpec, databaseUrl, getCachedAccessToken);
+                const processedChangeSpec = yield offloadBlobsAndMarkDirty(op.changeSpec, databaseUrl, getCachedAccessToken, maxStringLength);
                 return Object.assign(Object.assign({}, op), { changeSpec: processedChangeSpec });
             }
             case 'delete':
@@ -4097,33 +4168,37 @@ function offloadBlobsInOperation(op, databaseUrl, getCachedAccessToken) {
  * Check if there are any large blobs in the operations that need offloading
  * This is a quick check to avoid unnecessary processing
  */
-function hasLargeBlobsInOperations(operations) {
+function hasLargeBlobsInOperations(operations, maxStringLength = DEFAULT_MAX_STRING_LENGTH) {
     for (const tableOps of operations) {
         for (const mut of tableOps.muts) {
-            if (hasLargeBlobsInOperation(mut)) {
+            if (hasLargeBlobsInOperation(mut, maxStringLength)) {
                 return true;
             }
         }
     }
     return false;
 }
-function hasLargeBlobsInOperation(op) {
+function hasLargeBlobsInOperation(op, maxStringLength) {
     switch (op.type) {
         case 'insert':
         case 'upsert':
-            return op.values.some(value => hasLargeBlobs(value));
+            return op.values.some(value => hasLargeBlobs(value, maxStringLength));
         case 'update':
-            return op.changeSpecs.some(spec => hasLargeBlobs(spec));
+            return op.changeSpecs.some(spec => hasLargeBlobs(spec, maxStringLength));
         case 'modify':
-            return hasLargeBlobs(op.changeSpec);
+            return hasLargeBlobs(op.changeSpec, maxStringLength);
         default:
             return false;
     }
 }
-function hasLargeBlobs(obj, visited = new WeakSet()) {
+function hasLargeBlobs(obj, maxStringLength, visited = new WeakSet()) {
     if (obj === null || obj === undefined) {
         return false;
     }
+    // Check long strings
+    if (typeof obj === 'string' && obj.length > maxStringLength && maxStringLength !== Infinity) {
+        return true;
+    }
     if (shouldOffloadBlob(obj)) {
         return true;
     }
@@ -4136,13 +4211,13 @@ function hasLargeBlobs(obj, visited = new WeakSet()) {
     }
     visited.add(obj);
     if (Array.isArray(obj)) {
-        return obj.some(item => hasLargeBlobs(item, visited));
+        return obj.some(item => hasLargeBlobs(item, maxStringLength, visited));
     }
     // Traverse plain objects (POJO-like) - use duck typing since IndexedDB
     // may return objects where constructor !== Object
     const proto = Object.getPrototypeOf(obj);
     if (proto === Object.prototype || proto === null) {
-        return Object.values(obj).some(value => hasLargeBlobs(value, visited));
+        return Object.values(obj).some(value => hasLargeBlobs(value, maxStringLength, visited));
     }
     return false;
 }
@@ -4403,7 +4478,7 @@ function _sync(db_1, options_1, schema_1) {
     return __awaiter(this, arguments, void 0, function* (db, options, schema, { isInitialSync, cancelToken, justCheckIfNeeded, purpose } = {
         isInitialSync: false,
     }) {
-        var _a;
+        var _a, _b, _c;
         if (!justCheckIfNeeded) {
             console.debug('SYNC STARTED', { isInitialSync, purpose });
         }
@@ -4477,9 +4552,10 @@ function _sync(db_1, options_1, schema_1) {
         // Offload large blobs to blob storage before sync
         //
         let processedChangeSet = clientChangeSet;
-        const hasLargeBlobs = hasLargeBlobsInOperations(clientChangeSet);
+        const maxStringLength = (_c = (_b = db.cloud.options) === null || _b === void 0 ? void 0 : _b.maxStringLength) !== null && _c !== void 0 ? _c : 32768;
+        const hasLargeBlobs = hasLargeBlobsInOperations(clientChangeSet, maxStringLength);
         if (hasLargeBlobs) {
-            processedChangeSet = yield offloadBlobsInOperations(clientChangeSet, databaseUrl, () => loadCachedAccessToken(db));
+            processedChangeSet = yield offloadBlobsInOperations(clientChangeSet, databaseUrl, () => loadCachedAccessToken(db), maxStringLength);
         }
         //
         // Push changes to server
@@ -4785,13 +4861,13 @@ function MessagesFromServerConsumer(db) {
                             //triggerSync(db, 'pull');
                             yield db.cloud.sync({ purpose: 'pull', wait: true });
                             break;
-                        case 'changes':
+                        case 'changes': {
                             console.debug('changes');
                             if (((_f = db.cloud.syncState.value) === null || _f === void 0 ? void 0 : _f.phase) === 'error') {
                                 triggerSync(db, 'pull');
                                 break;
                             }
-                            yield db.transaction('rw', db.dx.tables, (tx) => __awaiter(this, void 0, void 0, function* () {
+                            const didApplyChanges = yield db.transaction('rw', db.dx.tables, (tx) => __awaiter(this, void 0, void 0, function* () {
                                 // @ts-ignore
                                 tx.idbtrans.disableChangeTracking = true;
                                 // @ts-ignore
@@ -4808,7 +4884,7 @@ function MessagesFromServerConsumer(db) {
                                         schema,
                                         currentUser,
                                     });
-                                    return; // Initial sync must have taken place - otherwise, ignore this.
+                                    return false; // Initial sync must have taken place - otherwise, ignore this.
                                 }
                                 // Verify again in ACID tx that we're on same server revision.
                                 if (msg.baseRev !== syncState.serverRevision) {
@@ -4829,7 +4905,7 @@ function MessagesFromServerConsumer(db) {
                                         // If we don't do a sync request now, we could stuck in an endless loop.
                                         triggerSync(db, 'pull');
                                     }
-                                    return; // Ignore message
+                                    return false; // Ignore message
                                 }
                                 // Verify also that the message is based on the exact same set of realms
                                 const ourRealmSetHash = yield Dexie.waitFor(
@@ -4841,7 +4917,7 @@ function MessagesFromServerConsumer(db) {
                                     triggerSync(db, 'pull');
                                     // The message isn't based on the same realms.
                                     // Trigger a sync instead to resolve all things up.
-                                    return;
+                                    return false;
                                 }
                                 // Get clientChanges
                                 let clientChanges = [];
@@ -4871,9 +4947,17 @@ function MessagesFromServerConsumer(db) {
                                 //
                                 console.debug('Updating syncState', syncState);
                                 yield db.$syncState.put(syncState, 'syncState');
+                                return true;
                             }));
                             console.debug('msg queue: done with rw transaction');
+                            // Trigger eager blob download for any BlobRefs received via WebSocket.
+                            // This mirrors the behavior after normal HTTP sync (syncCompleteEvent).
+                            // Only emit if changes were actually applied (not on early returns).
+                            if (didApplyChanges && msg.changes.length > 0) {
+                                db.syncCompleteEvent.next();
+                            }
                             break;
+                        }
                     }
                 }
                 catch (error) {
@@ -5844,7 +5928,7 @@ function createBlobResolveMiddleware(db) {
     return {
         stack: 'dbcore',
         name: 'blobResolve',
-        level: -2, // Run below other middlewares and after sync and caching middlewares
+        level: 2, // Run above cache (0) and other middlewares (1) to resolve BlobRefs from cached data
         create(downlevelDatabase) {
             // Create a single queue instance for this database
             const blobSavingQueue = new BlobSavingQueue(db);
@@ -8189,7 +8273,7 @@ function dexieCloud(dexie) {
     const downloading$ = createDownloadingState();
     dexie.cloud = {
         // @ts-ignore
-        version: "4.4.0",
+        version: "4.4.2",
         options: Object.assign({}, DEFAULT_OPTIONS),
         schema: null,
         get currentUserId() {
@@ -8217,6 +8301,19 @@ function dexieCloud(dexie) {
         invites: getInvitesObservable(dexie),
         roles: getGlobalRolesObservable(dexie),
         configure(options) {
+            // Validate maxStringLength — Infinity disables offloading, otherwise must be
+            // a finite number between 100 and the server limit (32768).
+            // Minimum 100 prevents accidental offloading of primary keys and short strings
+            // that would break sync.
+            const MIN_STRING_LENGTH = 100;
+            const MAX_SERVER_STRING_LENGTH = 32768;
+            if (options.maxStringLength !== undefined &&
+                options.maxStringLength !== Infinity &&
+                (!Number.isFinite(options.maxStringLength) ||
+                    options.maxStringLength < MIN_STRING_LENGTH ||
+                    options.maxStringLength > MAX_SERVER_STRING_LENGTH)) {
+                throw new Error(`maxStringLength must be Infinity or a finite number in [${MIN_STRING_LENGTH}, ${MAX_SERVER_STRING_LENGTH}]. Got: ${options.maxStringLength}`);
+            }
             options = dexie.cloud.options = Object.assign(Object.assign({}, dexie.cloud.options), options);
             configuredProgramatically = true;
             if (options.databaseUrl && options.nameSuffix) {
@@ -8603,7 +8700,7 @@ function dexieCloud(dexie) {
     }
 }
 // @ts-ignore
-dexieCloud.version = "4.4.0";
+dexieCloud.version = "4.4.2";
 Dexie.Cloud = dexieCloud;
 
 export { dexieCloud as default, defineYDocTrigger, dexieCloud, getTiedObjectId, getTiedRealmId, resolveText };