dexie-cloud-addon 4.4.0 → 4.4.1

package/dist/modern/sync/blobOffloading.d.ts

@@ -6,6 +6,7 @@
  */
 import { DBOperationsSet } from 'dexie-cloud-common';
 import { BlobRef, BlobRefOrigType, isBlobRef as isBlobRefFromResolve } from './blobResolve';
+export declare const DEFAULT_MAX_STRING_LENGTH = 32768;
 export type { BlobRef, BlobRefOrigType };
 export declare const isBlobRef: typeof isBlobRefFromResolve;
 /**
@@ -17,21 +18,21 @@ export declare function shouldOffloadBlob(value: unknown): value is Blob | Array
  * Upload a blob to the blob storage endpoint
  */
 export declare function uploadBlob(databaseUrl: string, getCachedAccessToken: () => Promise<string | null>, blob: Blob | ArrayBuffer | ArrayBufferView): Promise<BlobRef | null>;
-export declare function offloadBlobsAndMarkDirty(obj: unknown, databaseUrl: string, getCachedAccessToken: () => Promise<string | null>): Promise<unknown>;
+export declare function offloadBlobsAndMarkDirty(obj: unknown, databaseUrl: string, getCachedAccessToken: () => Promise<string | null>, maxStringLength?: number): Promise<unknown>;
 /**
  * Recursively scan an object for large blobs and upload them
  * Returns a new object with blobs replaced by BlobRefs
  */
-export declare function offloadBlobs(obj: unknown, databaseUrl: string, getCachedAccessToken: () => Promise<string | null>, dirtyFlag?: {
+export declare function offloadBlobs(obj: unknown, databaseUrl: string, getCachedAccessToken: () => Promise<string | null>, maxStringLength?: number, dirtyFlag?: {
     dirty: boolean;
 }, visited?: WeakSet<object>): Promise<unknown>;
 /**
  * Process a DBOperationsSet and offload any large blobs
  * Returns a new DBOperationsSet with blobs replaced by BlobRefs
  */
-export declare function offloadBlobsInOperations(operations: DBOperationsSet, databaseUrl: string, getCachedAccessToken: () => Promise<string | null>): Promise<DBOperationsSet>;
+export declare function offloadBlobsInOperations(operations: DBOperationsSet, databaseUrl: string, getCachedAccessToken: () => Promise<string | null>, maxStringLength?: number): Promise<DBOperationsSet>;
 /**
  * Check if there are any large blobs in the operations that need offloading
  * This is a quick check to avoid unnecessary processing
  */
-export declare function hasLargeBlobsInOperations(operations: DBOperationsSet): boolean;
+export declare function hasLargeBlobsInOperations(operations: DBOperationsSet, maxStringLength?: number): boolean;

package/dist/modern/sync/blobResolve.d.ts

@@ -18,7 +18,7 @@ import { BlobDownloadTracker } from './BlobDownloadTracker';
  * Original type that was offloaded to blob storage.
  * Matches the TSON type names.
  */
-export type BlobRefOrigType = 'Blob' | 'ArrayBuffer' | 'Uint8Array' | 'Int8Array' | 'Uint8ClampedArray' | 'Int16Array' | 'Uint16Array' | 'Int32Array' | 'Uint32Array' | 'Float32Array' | 'Float64Array' | 'BigInt64Array' | 'BigUint64Array' | 'DataView';
+export type BlobRefOrigType = 'Blob' | 'ArrayBuffer' | 'Uint8Array' | 'Int8Array' | 'Uint8ClampedArray' | 'Int16Array' | 'Uint16Array' | 'Int32Array' | 'Uint32Array' | 'Float32Array' | 'Float64Array' | 'BigInt64Array' | 'BigUint64Array' | 'DataView' | 'string';
 /**
  * BlobRef represents a reference to binary data stored in blob storage.
  * The _bt field contains the original JavaScript type (Uint8Array, Blob, etc.)
@@ -35,7 +35,7 @@ export interface BlobRef {
  */
 export interface ResolvedBlob {
     keyPath: string;
-    data: Blob | ArrayBuffer | ArrayBufferView;
+    data: Blob | ArrayBuffer | ArrayBufferView | string;
     ref: string;
 }
 /**
@@ -65,7 +65,7 @@ export declare function hasBlobRefs(obj: unknown, visited?: WeakSet<object>): bo
 /**
  * Convert downloaded Uint8Array to the original type specified in BlobRef
  */
-export declare function convertToOriginalType(data: Uint8Array, ref: BlobRef): Blob | ArrayBuffer | ArrayBufferView;
+export declare function convertToOriginalType(data: Uint8Array, ref: BlobRef): Blob | ArrayBuffer | ArrayBufferView | string;
 /**
  * Recursively resolve all BlobRefs in an object and collect them for queueing.
  * Returns a new object with BlobRefs replaced by their original type data,

package/dist/umd/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
  *
@@ -2665,10 +2665,48 @@
             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
@@ -4841,6 +4879,19 @@
         });
     }
 
+    /**
+     * 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);
@@ -4876,6 +4927,7 @@
                     const keys = mut.keys.map(keyDecoder);
                     switch (mut.type) {
                         case 'insert':
+                            mut.values.forEach(markIfHasBlobRefs);
                             if (primaryKey.outbound) {
                                 yield table.bulkAdd(mut.values, keys);
                             }
@@ -4888,6 +4940,7 @@
                             }
                             break;
                         case 'upsert':
+                            mut.values.forEach(markIfHasBlobRefs);
                             if (primaryKey.outbound) {
                                 yield table.bulkPut(mut.values, keys);
                             }
@@ -14306,7 +14359,7 @@
      *
      * ==========================================================================
      *
-     * Version 4.4.0, Wed Mar 18 2026
+     * Version 4.4.0, Thu Mar 19 2026
      *
      * https://dexie.org
      *
@@ -14811,6 +14864,8 @@
      */
     // 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();
@@ -14951,10 +15006,10 @@
             );
         });
     }
-    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;
@@ -14967,10 +15022,26 @@
      * 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) {
@@ -14999,7 +15070,7 @@
             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;
             }
@@ -15011,7 +15082,7 @@
             }
             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;
         });
@@ -15020,13 +15091,13 @@
      * 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({
@@ -15037,20 +15108,20 @@
             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':
@@ -15065,33 +15136,37 @@
      * 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;
         }
@@ -15104,13 +15179,13 @@
         }
         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;
     }
@@ -15371,7 +15446,7 @@
         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 });
             }
@@ -15445,9 +15520,10 @@
             // 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
@@ -19419,7 +19495,7 @@
         const downloading$ = createDownloadingState();
         dexie.cloud = {
             // @ts-ignore
-            version: "4.4.0",
+            version: "4.4.1",
             options: Object.assign({}, DEFAULT_OPTIONS),
             schema: null,
             get currentUserId() {
@@ -19447,6 +19523,16 @@
             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) {
@@ -19833,7 +19919,7 @@
         }
     }
     // @ts-ignore
-    dexieCloud.version = "4.4.0";
+    dexieCloud.version = "4.4.1";
     Dexie.Cloud = dexieCloud;
 
     exports.default = dexieCloud;