dexie-cloud-addon 4.4.0 → 4.4.1

package/dist/modern/DexieCloudOptions.d.ts

@@ -50,4 +50,14 @@ 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.
+     *
+     * @default 32768
+     */
+    maxStringLength?: number;
 }

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

@@ -8,7 +8,7 @@
  *
  * ==========================================================================
  *
- * Version 4.4.0, Wed Mar 18 2026
+ * Version 4.4.1, 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
@@ -8189,7 +8265,7 @@ function dexieCloud(dexie) {
     const downloading$ = createDownloadingState();
     dexie.cloud = {
         // @ts-ignore
-        version: "4.4.0",
+        version: "4.4.1",
         options: Object.assign({}, DEFAULT_OPTIONS),
         schema: null,
         get currentUserId() {
@@ -8217,6 +8293,16 @@ function dexieCloud(dexie) {
         invites: getInvitesObservable(dexie),
         roles: getGlobalRolesObservable(dexie),
         configure(options) {
+            // Validate maxStringLength — Infinity disables offloading, otherwise must be
+            // a finite positive number not exceeding the server limit (32768).
+            const MAX_SERVER_STRING_LENGTH = 32768;
+            if (options.maxStringLength !== undefined &&
+                options.maxStringLength !== Infinity &&
+                (!Number.isFinite(options.maxStringLength) ||
+                    options.maxStringLength < 0 ||
+                    options.maxStringLength > MAX_SERVER_STRING_LENGTH)) {
+                throw new Error(`maxStringLength must be Infinity or a finite number in [0, ${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 +8689,7 @@ function dexieCloud(dexie) {
     }
 }
 // @ts-ignore
-dexieCloud.version = "4.4.0";
+dexieCloud.version = "4.4.1";
 Dexie.Cloud = dexieCloud;
 
 export { dexieCloud as default, defineYDocTrigger, dexieCloud, getTiedObjectId, getTiedRealmId, resolveText };