dexie-cloud-addon 4.4.0 → 4.4.1

package/dist/modern/service-worker.js

@@ -8,7 +8,7 @@
  *
  * ==========================================================================
  *
- * Version 4.4.0, Wed Mar 18 2026
+ * Version 4.4.1, Thu Mar 19 2026
  *
  * https://dexie.org
  *
@@ -2603,6 +2603,194 @@ function bulkUpdate(table, keys, changeSpecs) {
     });
 }
 
+/**
+ * Check if a value is a BlobRef (offloaded binary data)
+ * A BlobRef has _bt (type), ref (blob ID), but no v (inline data)
+ */
+function isBlobRef(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const obj = value;
+    return (typeof obj._bt === 'string' &&
+        typeof obj.ref === 'string' &&
+        obj.v === undefined // No inline data = it's a reference
+    );
+}
+/**
+ * Check if a value is a serialized TSONRef (after IndexedDB storage)
+ * Has 'type' instead of '$t', and no Symbol marker
+ */
+function isSerializedTSONRef(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const obj = value;
+    return (typeof obj.type === 'string' &&
+        typeof obj.ref === 'string' &&
+        typeof obj.size === 'number' &&
+        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
+        : data.buffer.slice(data.byteOffset, data.byteOffset + data.byteLength);
+    switch (ref._bt) {
+        case 'Blob':
+            return new Blob([new Uint8Array(buffer)], { type: ref.ct || '' });
+        case 'ArrayBuffer':
+            return buffer;
+        case 'Uint8Array':
+            return data;
+        case 'Int8Array':
+            return new Int8Array(buffer);
+        case 'Uint8ClampedArray':
+            return new Uint8ClampedArray(buffer);
+        case 'Int16Array':
+            return new Int16Array(buffer);
+        case 'Uint16Array':
+            return new Uint16Array(buffer);
+        case 'Int32Array':
+            return new Int32Array(buffer);
+        case 'Uint32Array':
+            return new Uint32Array(buffer);
+        case 'Float32Array':
+            return new Float32Array(buffer);
+        case 'Float64Array':
+            return new Float64Array(buffer);
+        case 'BigInt64Array':
+            return new BigInt64Array(buffer);
+        case 'BigUint64Array':
+            return new BigUint64Array(buffer);
+        case 'DataView':
+            return new DataView(buffer);
+        default:
+            // Fallback to Uint8Array for unknown types
+            return data;
+    }
+}
+/**
+ * Recursively resolve all BlobRefs in an object and collect them for queueing.
+ * Returns a new object with BlobRefs replaced by their original type data,
+ * and populates the resolvedBlobs array with keyPath info for each blob.
+ *
+ * @param obj - Object to resolve
+ * @param dbUrl - Base URL for the database
+ * @param accessToken - Access token for blob downloads
+ * @param resolvedBlobs - Array to collect resolved blob info
+ * @param currentPath - Current property path (for tracking)
+ * @param visited - WeakMap for circular reference detection
+ */
+function resolveAllBlobRefs(obj_1, dbUrl_1) {
+    return __awaiter(this, arguments, void 0, function* (obj, dbUrl, resolvedBlobs = [], currentPath = '', visited = new WeakMap(), tracker) {
+        if (obj == null) { // null or undefined
+            return obj;
+        }
+        // Check if this is a BlobRef - resolve it and track it
+        if (isBlobRef(obj)) {
+            const rawData = yield tracker.download(obj, dbUrl);
+            const data = convertToOriginalType(rawData, obj);
+            resolvedBlobs.push({ keyPath: currentPath, data, ref: obj.ref });
+            return data;
+        }
+        // Handle arrays
+        if (Array.isArray(obj)) {
+            // Avoid circular references - check and set BEFORE iterating
+            if (visited.has(obj)) {
+                return visited.get(obj);
+            }
+            const result = [];
+            visited.set(obj, result); // Set before iterating to handle self-references
+            for (let i = 0; i < obj.length; i++) {
+                const itemPath = currentPath ? `${currentPath}.${i}` : `${i}`;
+                result.push(yield resolveAllBlobRefs(obj[i], dbUrl, resolvedBlobs, itemPath, visited, tracker));
+            }
+            return result;
+        }
+        // Handle POJO objects only (not Date, RegExp, Blob, ArrayBuffer, etc.)
+        if (typeof obj === 'object' && obj.constructor === Object) {
+            // Avoid circular references
+            if (visited.has(obj)) {
+                return visited.get(obj);
+            }
+            const result = {};
+            visited.set(obj, result);
+            for (const [propName, value] of Object.entries(obj)) {
+                // Skip the _hasBlobRefs marker itself
+                if (propName === '_hasBlobRefs') {
+                    continue;
+                }
+                const propPath = currentPath ? `${currentPath}.${propName}` : propName;
+                result[propName] = yield resolveAllBlobRefs(value, dbUrl, resolvedBlobs, propPath, visited, tracker);
+            }
+            return result;
+        }
+        return obj;
+    });
+}
+/**
+ * Check if an object has unresolved BlobRefs
+ */
+function hasUnresolvedBlobRefs(obj) {
+    return (typeof obj === 'object' &&
+        obj !== null &&
+        obj._hasBlobRefs === 1);
+}
+
+/**
+ * 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);
@@ -2638,6 +2826,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);
                         }
@@ -2650,6 +2839,7 @@ function applyServerChanges(changes, db) {
                         }
                         break;
                     case 'upsert':
+                        mut.values.forEach(markIfHasBlobRefs);
                         if (primaryKey.outbound) {
                             yield table.bulkPut(mut.values, keys);
                         }
@@ -2897,143 +3087,6 @@ function applyYServerMessages(yMessages, db) {
     });
 }
 
-/**
- * Check if a value is a BlobRef (offloaded binary data)
- * A BlobRef has _bt (type), ref (blob ID), but no v (inline data)
- */
-function isBlobRef(value) {
-    if (typeof value !== 'object' || value === null)
-        return false;
-    const obj = value;
-    return (typeof obj._bt === 'string' &&
-        typeof obj.ref === 'string' &&
-        obj.v === undefined // No inline data = it's a reference
-    );
-}
-/**
- * Check if a value is a serialized TSONRef (after IndexedDB storage)
- * Has 'type' instead of '$t', and no Symbol marker
- */
-function isSerializedTSONRef(value) {
-    if (typeof value !== 'object' || value === null)
-        return false;
-    const obj = value;
-    return (typeof obj.type === 'string' &&
-        typeof obj.ref === 'string' &&
-        typeof obj.size === 'number' &&
-        obj._bt === undefined // Not a raw BlobRef
-    );
-}
-/**
- * Convert downloaded Uint8Array to the original type specified in BlobRef
- */
-function convertToOriginalType(data, ref) {
-    // Get the underlying ArrayBuffer (handle shared buffer case)
-    const buffer = data.buffer.byteLength === data.byteLength
-        ? data.buffer
-        : data.buffer.slice(data.byteOffset, data.byteOffset + data.byteLength);
-    switch (ref._bt) {
-        case 'Blob':
-            return new Blob([new Uint8Array(buffer)], { type: ref.ct || '' });
-        case 'ArrayBuffer':
-            return buffer;
-        case 'Uint8Array':
-            return data;
-        case 'Int8Array':
-            return new Int8Array(buffer);
-        case 'Uint8ClampedArray':
-            return new Uint8ClampedArray(buffer);
-        case 'Int16Array':
-            return new Int16Array(buffer);
-        case 'Uint16Array':
-            return new Uint16Array(buffer);
-        case 'Int32Array':
-            return new Int32Array(buffer);
-        case 'Uint32Array':
-            return new Uint32Array(buffer);
-        case 'Float32Array':
-            return new Float32Array(buffer);
-        case 'Float64Array':
-            return new Float64Array(buffer);
-        case 'BigInt64Array':
-            return new BigInt64Array(buffer);
-        case 'BigUint64Array':
-            return new BigUint64Array(buffer);
-        case 'DataView':
-            return new DataView(buffer);
-        default:
-            // Fallback to Uint8Array for unknown types
-            return data;
-    }
-}
-/**
- * Recursively resolve all BlobRefs in an object and collect them for queueing.
- * Returns a new object with BlobRefs replaced by their original type data,
- * and populates the resolvedBlobs array with keyPath info for each blob.
- *
- * @param obj - Object to resolve
- * @param dbUrl - Base URL for the database
- * @param accessToken - Access token for blob downloads
- * @param resolvedBlobs - Array to collect resolved blob info
- * @param currentPath - Current property path (for tracking)
- * @param visited - WeakMap for circular reference detection
- */
-function resolveAllBlobRefs(obj_1, dbUrl_1) {
-    return __awaiter(this, arguments, void 0, function* (obj, dbUrl, resolvedBlobs = [], currentPath = '', visited = new WeakMap(), tracker) {
-        if (obj == null) { // null or undefined
-            return obj;
-        }
-        // Check if this is a BlobRef - resolve it and track it
-        if (isBlobRef(obj)) {
-            const rawData = yield tracker.download(obj, dbUrl);
-            const data = convertToOriginalType(rawData, obj);
-            resolvedBlobs.push({ keyPath: currentPath, data, ref: obj.ref });
-            return data;
-        }
-        // Handle arrays
-        if (Array.isArray(obj)) {
-            // Avoid circular references - check and set BEFORE iterating
-            if (visited.has(obj)) {
-                return visited.get(obj);
-            }
-            const result = [];
-            visited.set(obj, result); // Set before iterating to handle self-references
-            for (let i = 0; i < obj.length; i++) {
-                const itemPath = currentPath ? `${currentPath}.${i}` : `${i}`;
-                result.push(yield resolveAllBlobRefs(obj[i], dbUrl, resolvedBlobs, itemPath, visited, tracker));
-            }
-            return result;
-        }
-        // Handle POJO objects only (not Date, RegExp, Blob, ArrayBuffer, etc.)
-        if (typeof obj === 'object' && obj.constructor === Object) {
-            // Avoid circular references
-            if (visited.has(obj)) {
-                return visited.get(obj);
-            }
-            const result = {};
-            visited.set(obj, result);
-            for (const [propName, value] of Object.entries(obj)) {
-                // Skip the _hasBlobRefs marker itself
-                if (propName === '_hasBlobRefs') {
-                    continue;
-                }
-                const propPath = currentPath ? `${currentPath}.${propName}` : propName;
-                result[propName] = yield resolveAllBlobRefs(value, dbUrl, resolvedBlobs, propPath, visited, tracker);
-            }
-            return result;
-        }
-        return obj;
-    });
-}
-/**
- * Check if an object has unresolved BlobRefs
- */
-function hasUnresolvedBlobRefs(obj) {
-    return (typeof obj === 'object' &&
-        obj !== null &&
-        obj._hasBlobRefs === 1);
-}
-
 /**
  * Blob Offloading for Dexie Cloud
  *
@@ -3042,6 +3095,8 @@ function hasUnresolvedBlobRefs(obj) {
  */
 // 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();
@@ -3182,10 +3237,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;
@@ -3198,10 +3253,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) {
@@ -3230,7 +3301,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;
         }
@@ -3242,7 +3313,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;
     });
@@ -3251,13 +3322,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({
@@ -3268,20 +3339,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':
@@ -3296,33 +3367,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;
     }
@@ -3335,13 +3410,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;
 }
@@ -3602,7 +3677,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 });
         }
@@ -3676,9 +3751,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
@@ -8018,7 +8094,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() {
@@ -8046,6 +8122,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) {
@@ -8432,7 +8518,7 @@ function dexieCloud(dexie) {
     }
 }
 // @ts-ignore
-dexieCloud.version = "4.4.0";
+dexieCloud.version = "4.4.1";
 Dexie.Cloud = dexieCloud;
 
 // In case the SW lives for a while, let it reuse already opened connections: