dexie-cloud-addon 4.4.0 → 4.4.2

package/dist/umd/default-ui/Styles.d.ts

@@ -0,0 +1,3 @@
+export declare const Styles: {
+    [styleAlias: string]: Partial<CSSStyleDeclaration> | any;
+};

package/dist/umd/default-ui/index.d.ts

@@ -0,0 +1,24 @@
+import Dexie from "dexie";
+import "../extend-dexie-interface";
+import { h, Component } from "preact";
+import { Subscription } from "rxjs";
+import { DXCUserInteraction } from "../types/DXCUserInteraction";
+export interface Props {
+    db: Dexie;
+}
+interface State {
+    userInteraction: DXCUserInteraction | undefined;
+}
+export default class LoginGui extends Component<Props, State> {
+    subscription?: Subscription;
+    observer: (userInteraction: DXCUserInteraction | undefined) => void;
+    constructor(props: Props);
+    componentDidMount(): void;
+    componentWillUnmount(): void;
+    render(props: Props, { userInteraction }: State): h.JSX.Element | null;
+}
+export declare function setupDefaultGUI(db: Dexie): {
+    unsubscribe(): void;
+    readonly closed: boolean;
+};
+export {};

package/dist/umd/define-ydoc-trigger.d.ts

@@ -0,0 +1,3 @@
+import { type Table } from 'dexie';
+import type { Doc as YjsDoc } from 'yjs';
+export declare function defineYDocTrigger<T, TKey>(table: Table<T, TKey>, prop: keyof T & string, trigger: (ydoc: YjsDoc, parentId: TKey) => any): void;

package/dist/umd/dexie-cloud-addon.d.ts

@@ -0,0 +1,3 @@
+import dexieCloudAddon from './dexie-cloud-client';
+export * from './dexie-cloud-client';
+export default dexieCloudAddon;

package/dist/umd/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
  *
@@ -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
@@ -15753,13 +15829,13 @@
                                 //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
@@ -15776,7 +15852,7 @@
                                             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) {
@@ -15797,7 +15873,7 @@
                                             // 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(
@@ -15809,7 +15885,7 @@
                                         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 = [];
@@ -15839,9 +15915,17 @@
                                     //
                                     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) {
@@ -16812,7 +16896,7 @@
         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);
@@ -19419,7 +19503,7 @@
         const downloading$ = createDownloadingState();
         dexie.cloud = {
             // @ts-ignore
-            version: "4.4.0",
+            version: "4.4.2",
             options: Object.assign({}, DEFAULT_OPTIONS),
             schema: null,
             get currentUserId() {
@@ -19447,6 +19531,19 @@
             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) {
@@ -19833,7 +19930,7 @@
         }
     }
     // @ts-ignore
-    dexieCloud.version = "4.4.0";
+    dexieCloud.version = "4.4.2";
     Dexie.Cloud = dexieCloud;
 
     exports.default = dexieCloud;