@firebase/data-connect 0.3.12 → 0.4.0-20260224183151

package/dist/index.cjs.js

@@ -8,7 +8,7 @@ var util = require('@firebase/util');
 var logger$1 = require('@firebase/logger');
 
 const name = "@firebase/data-connect";
-const version = "0.3.12";
+const version = "0.4.0-20260224183151";
 
 /**
  * @license
@@ -36,6 +36,572 @@ function setSDKVersion(version) {
     SDK_VERSION = version;
 }
 
+/**
+ * @license
+ * Copyright 2024 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+const Code = {
+    OTHER: 'other',
+    ALREADY_INITIALIZED: 'already-initialized',
+    NOT_INITIALIZED: 'not-initialized',
+    NOT_SUPPORTED: 'not-supported',
+    INVALID_ARGUMENT: 'invalid-argument',
+    PARTIAL_ERROR: 'partial-error',
+    UNAUTHORIZED: 'unauthorized'
+};
+/** An error returned by a DataConnect operation. */
+class DataConnectError extends util.FirebaseError {
+    constructor(code, message) {
+        super(code, message);
+        /** @internal */
+        this.name = 'DataConnectError';
+        // Ensure the instanceof operator works as expected on subclasses of Error.
+        // See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error#custom_error_types
+        // and https://www.typescriptlang.org/docs/handbook/release-notes/typescript-2-2.html#support-for-newtarget
+        Object.setPrototypeOf(this, DataConnectError.prototype);
+    }
+    /** @internal */
+    toString() {
+        return `${this.name}[code=${this.code}]: ${this.message}`;
+    }
+}
+/** An error returned by a DataConnect operation. */
+class DataConnectOperationError extends DataConnectError {
+    /** @hideconstructor */
+    constructor(message, response) {
+        super(Code.PARTIAL_ERROR, message);
+        /** @internal */
+        this.name = 'DataConnectOperationError';
+        this.response = response;
+    }
+}
+
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+class EntityDataObject {
+    getServerValue(key) {
+        return this.serverValues[key];
+    }
+    constructor(globalID) {
+        this.globalID = globalID;
+        this.serverValues = {};
+        this.referencedFrom = new Set();
+    }
+    getServerValues() {
+        return this.serverValues;
+    }
+    toJSON() {
+        return {
+            globalID: this.globalID,
+            map: this.serverValues,
+            referencedFrom: Array.from(this.referencedFrom)
+        };
+    }
+    static fromJSON(json) {
+        const edo = new EntityDataObject(json.globalID);
+        edo.serverValues = json.map;
+        edo.referencedFrom = new Set(json.referencedFrom);
+        return edo;
+    }
+    updateServerValue(key, value, requestedFrom) {
+        this.serverValues[key] = value;
+        this.referencedFrom.add(requestedFrom);
+        return Array.from(this.referencedFrom);
+    }
+}
+
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+class InMemoryCacheProvider {
+    constructor(_keyId) {
+        this._keyId = _keyId;
+        this.edos = new Map();
+        this.resultTrees = new Map();
+    }
+    async setResultTree(queryId, rt) {
+        this.resultTrees.set(queryId, rt);
+    }
+    async getResultTree(queryId) {
+        return this.resultTrees.get(queryId);
+    }
+    async updateEntityData(entityData) {
+        this.edos.set(entityData.globalID, entityData);
+    }
+    async getEntityData(globalId) {
+        if (!this.edos.has(globalId)) {
+            this.edos.set(globalId, new EntityDataObject(globalId));
+        }
+        // Because of the above, we can guarantee that there will be an EDO at the globalId.
+        return this.edos.get(globalId);
+    }
+    close() {
+        // No-op
+        return Promise.resolve();
+    }
+}
+
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+const GLOBAL_ID_KEY = '_id';
+const OBJECT_LISTS_KEY = '_objectLists';
+const REFERENCES_KEY = '_references';
+const SCALARS_KEY = '_scalars';
+const ENTITY_DATA_KEYS_KEY = '_entity_data_keys';
+class EntityNode {
+    constructor() {
+        this.scalars = {};
+        this.references = {};
+        this.objectLists = {};
+        this.entityDataKeys = new Set();
+    }
+    async loadData(queryId, values, entityIds, acc, cacheProvider) {
+        if (values === undefined) {
+            return;
+        }
+        if (typeof values !== 'object' || Array.isArray(values)) {
+            throw new DataConnectError(Code.INVALID_ARGUMENT, 'EntityNode initialized with non-object value');
+        }
+        if (values === null) {
+            return;
+        }
+        if (typeof values === 'object' &&
+            entityIds &&
+            entityIds[GLOBAL_ID_KEY] &&
+            typeof entityIds[GLOBAL_ID_KEY] === 'string') {
+            this.globalId = entityIds[GLOBAL_ID_KEY];
+            this.entityData = await cacheProvider.getEntityData(this.globalId);
+        }
+        for (const key in values) {
+            if (values.hasOwnProperty(key)) {
+                if (typeof values[key] === 'object') {
+                    if (Array.isArray(values[key])) {
+                        const ids = entityIds && entityIds[key];
+                        const objArray = [];
+                        const scalarArray = [];
+                        for (const [index, value] of values[key].entries()) {
+                            if (typeof value === 'object') {
+                                if (Array.isArray(value)) ;
+                                else {
+                                    const entityNode = new EntityNode();
+                                    await entityNode.loadData(queryId, value, ids && ids[index], acc, cacheProvider);
+                                    objArray.push(entityNode);
+                                }
+                            }
+                            else {
+                                scalarArray.push(value);
+                            }
+                        }
+                        if (scalarArray.length > 0 && objArray.length > 0) {
+                            this.scalars[key] = values[key];
+                        }
+                        else if (scalarArray.length > 0) {
+                            if (this.entityData) {
+                                const impactedRefs = this.entityData.updateServerValue(key, scalarArray, queryId);
+                                this.entityDataKeys.add(key);
+                                acc.add(impactedRefs);
+                            }
+                            else {
+                                this.scalars[key] = scalarArray;
+                            }
+                        }
+                        else if (objArray.length > 0) {
+                            this.objectLists[key] = objArray;
+                        }
+                        else {
+                            this.scalars[key] = [];
+                        }
+                    }
+                    else {
+                        if (values[key] === null) {
+                            this.scalars[key] = null;
+                            continue;
+                        }
+                        const entityNode = new EntityNode();
+                        // TODO: Load Data might need to be pushed into ResultTreeProcessor instead.
+                        await entityNode.loadData(queryId, values[key], entityIds && entityIds[key], acc, cacheProvider);
+                        this.references[key] = entityNode;
+                    }
+                }
+                else {
+                    if (this.entityData) {
+                        const impactedRefs = this.entityData.updateServerValue(key, values[key], queryId);
+                        this.entityDataKeys.add(key);
+                        acc.add(impactedRefs);
+                    }
+                    else {
+                        this.scalars[key] = values[key];
+                    }
+                }
+            }
+        }
+        if (this.entityData) {
+            await cacheProvider.updateEntityData(this.entityData);
+        }
+    }
+    toJSON(mode) {
+        const resultObject = {};
+        if (mode === EncodingMode.hydrated) {
+            if (this.entityData) {
+                for (const key of this.entityDataKeys) {
+                    resultObject[key] = this.entityData.getServerValue(key);
+                }
+            }
+            if (this.scalars) {
+                Object.assign(resultObject, this.scalars);
+            }
+            if (this.references) {
+                for (const key in this.references) {
+                    if (this.references.hasOwnProperty(key)) {
+                        resultObject[key] = this.references[key].toJSON(mode);
+                    }
+                }
+            }
+            if (this.objectLists) {
+                for (const key in this.objectLists) {
+                    if (this.objectLists.hasOwnProperty(key)) {
+                        resultObject[key] = this.objectLists[key].map(obj => obj.toJSON(mode));
+                    }
+                }
+            }
+            return resultObject;
+        }
+        else {
+            // Get JSON representation of dehydrated list
+            if (this.entityData) {
+                resultObject[GLOBAL_ID_KEY] = this.entityData.globalID;
+            }
+            resultObject[ENTITY_DATA_KEYS_KEY] = Array.from(this.entityDataKeys);
+            if (this.scalars) {
+                resultObject[SCALARS_KEY] = this.scalars;
+            }
+            if (this.references) {
+                const references = {};
+                for (const key in this.references) {
+                    if (this.references.hasOwnProperty(key)) {
+                        references[key] = this.references[key].toJSON(mode);
+                    }
+                }
+                resultObject[REFERENCES_KEY] = references;
+            }
+            if (this.objectLists) {
+                const objectLists = {};
+                for (const key in this.objectLists) {
+                    if (this.objectLists.hasOwnProperty(key)) {
+                        objectLists[key] = this.objectLists[key].map(obj => obj.toJSON(mode));
+                    }
+                }
+                resultObject[OBJECT_LISTS_KEY] = objectLists;
+            }
+        }
+        return resultObject;
+    }
+    static fromJson(obj) {
+        const sdo = new EntityNode();
+        if (obj.backingData) {
+            sdo.entityData = EntityDataObject.fromJSON(obj.backingData);
+        }
+        sdo.globalId = obj.globalID;
+        sdo.scalars = obj.scalars;
+        if (obj.references) {
+            const references = {};
+            for (const key in obj.references) {
+                if (obj.references.hasOwnProperty(key)) {
+                    references[key] = EntityNode.fromJson(obj.references[key]);
+                }
+            }
+            sdo.references = references;
+        }
+        if (obj.objectLists) {
+            const objectLists = {};
+            for (const key in obj.objectLists) {
+                if (obj.objectLists.hasOwnProperty(key)) {
+                    objectLists[key] = obj.objectLists[key].map(obj => EntityNode.fromJson(obj));
+                }
+            }
+            sdo.objectLists = objectLists;
+        }
+        return sdo;
+    }
+}
+// Helpful for storing in persistent cache, which is not available yet.
+var EncodingMode;
+(function (EncodingMode) {
+    EncodingMode[EncodingMode["hydrated"] = 0] = "hydrated";
+    EncodingMode[EncodingMode["dehydrated"] = 1] = "dehydrated";
+})(EncodingMode || (EncodingMode = {}));
+
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+class ResultTree {
+    /**
+     * Create a {@link ResultTree} from a dehydrated JSON object.
+     * @param value The dehydrated JSON object.
+     * @returns The {@link ResultTree}.
+     */
+    static fromJson(value) {
+        return new ResultTree(EntityNode.fromJson(value.rootStub), value.maxAge, value.cachedAt, value.lastAccessed);
+    }
+    constructor(rootStub, maxAge = 0, cachedAt, _lastAccessed) {
+        this.rootStub = rootStub;
+        this.maxAge = maxAge;
+        this.cachedAt = cachedAt;
+        this._lastAccessed = _lastAccessed;
+    }
+    isStale() {
+        return (Date.now() - new Date(this.cachedAt.getTime()).getTime() >
+            this.maxAge * 1000);
+    }
+    updateMaxAge(maxAgeInSeconds) {
+        this.maxAge = maxAgeInSeconds;
+    }
+    updateAccessed() {
+        this._lastAccessed = new Date();
+    }
+    get lastAccessed() {
+        return this._lastAccessed;
+    }
+    getRootStub() {
+        return this.rootStub;
+    }
+}
+
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+class ImpactedQueryRefsAccumulator {
+    constructor(queryId) {
+        this.queryId = queryId;
+        this.impacted = new Set();
+    }
+    add(impacted) {
+        impacted
+            .filter(ref => ref !== this.queryId)
+            .forEach(ref => this.impacted.add(ref));
+    }
+    consumeEvents() {
+        const events = Array.from(this.impacted);
+        this.impacted.clear();
+        return events;
+    }
+}
+
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+class ResultTreeProcessor {
+    /**
+     * Hydrate the EntityNode into a JSON object so that it can be returned to the user.
+     * @param rootStubObject
+     * @returns {string}
+     */
+    hydrateResults(rootStubObject) {
+        return rootStubObject.toJSON(EncodingMode.hydrated);
+    }
+    /**
+     * Dehydrate results so that they can be stored in the cache.
+     * @param json
+     * @param entityIds
+     * @param cacheProvider
+     * @param queryId
+     * @returns {Promise<DehydratedResults>}
+     */
+    async dehydrateResults(json, entityIds, cacheProvider, queryId) {
+        const acc = new ImpactedQueryRefsAccumulator(queryId);
+        const entityNode = new EntityNode();
+        await entityNode.loadData(queryId, json, entityIds, acc, cacheProvider);
+        return {
+            entityNode,
+            impacted: acc.consumeEvents()
+        };
+    }
+}
+
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+class DataConnectCache {
+    constructor(authProvider, projectId, connectorConfig, host, cacheSettings) {
+        this.authProvider = authProvider;
+        this.projectId = projectId;
+        this.connectorConfig = connectorConfig;
+        this.host = host;
+        this.cacheSettings = cacheSettings;
+        this.cacheProvider = null;
+        this.uid = null;
+        this.authProvider.addTokenChangeListener(async (_) => {
+            const newUid = this.authProvider.getAuth().getUid();
+            // We should only close if the token changes and so does the new UID
+            if (this.uid !== newUid) {
+                this.cacheProvider?.close();
+                this.uid = newUid;
+                const identifier = await this.getIdentifier(this.uid);
+                this.cacheProvider = this.initializeNewProviders(identifier);
+            }
+        });
+    }
+    async initialize() {
+        if (!this.cacheProvider) {
+            const identifier = await this.getIdentifier(this.uid);
+            this.cacheProvider = this.initializeNewProviders(identifier);
+        }
+    }
+    async getIdentifier(uid) {
+        const identifier = `${'memory' // TODO: replace this with indexeddb when persistence is available.
+        }-${this.projectId}-${this.connectorConfig.service}-${this.connectorConfig.connector}-${this.connectorConfig.location}-${uid}-${this.host}`;
+        const sha256 = await util.generateSHA256Hash(identifier);
+        return sha256;
+    }
+    initializeNewProviders(identifier) {
+        return this.cacheSettings.cacheProvider.initialize(identifier);
+    }
+    async containsResultTree(queryId) {
+        await this.initialize();
+        const resultTree = await this.cacheProvider.getResultTree(queryId);
+        return resultTree !== undefined;
+    }
+    async getResultTree(queryId) {
+        await this.initialize();
+        return this.cacheProvider.getResultTree(queryId);
+    }
+    async getResultJSON(queryId) {
+        await this.initialize();
+        const processor = new ResultTreeProcessor();
+        const cacheProvider = this.cacheProvider;
+        const resultTree = await cacheProvider.getResultTree(queryId);
+        if (!resultTree) {
+            throw new DataConnectError(Code.INVALID_ARGUMENT, `${queryId} not found in cache. Call "update()" first.`);
+        }
+        return processor.hydrateResults(resultTree.getRootStub());
+    }
+    async update(queryId, serverValues, entityIds) {
+        await this.initialize();
+        const processor = new ResultTreeProcessor();
+        const cacheProvider = this.cacheProvider;
+        const { entityNode: stubDataObject, impacted } = await processor.dehydrateResults(serverValues, entityIds, cacheProvider, queryId);
+        const now = new Date();
+        await cacheProvider.setResultTree(queryId, new ResultTree(stubDataObject, serverValues.maxAge || this.cacheSettings.maxAgeSeconds, now, now));
+        return impacted;
+    }
+}
+class MemoryStub {
+    constructor() {
+        this.type = 'MEMORY';
+    }
+    /**
+     * @internal
+     */
+    initialize(cacheId) {
+        return new InMemoryCacheProvider(cacheId);
+    }
+}
+
 /**
  * @license
  * Copyright 2024 Google LLC
@@ -99,58 +665,6 @@ class AppCheckTokenProvider {
     }
 }
 
-/**
- * @license
- * Copyright 2024 Google LLC
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *   http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-const Code = {
-    OTHER: 'other',
-    ALREADY_INITIALIZED: 'already-initialized',
-    NOT_INITIALIZED: 'not-initialized',
-    NOT_SUPPORTED: 'not-supported',
-    INVALID_ARGUMENT: 'invalid-argument',
-    PARTIAL_ERROR: 'partial-error',
-    UNAUTHORIZED: 'unauthorized'
-};
-/** An error returned by a DataConnect operation. */
-class DataConnectError extends util.FirebaseError {
-    constructor(code, message) {
-        super(code, message);
-        /** @internal */
-        this.name = 'DataConnectError';
-        // Ensure the instanceof operator works as expected on subclasses of Error.
-        // See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error#custom_error_types
-        // and https://www.typescriptlang.org/docs/handbook/release-notes/typescript-2-2.html#support-for-newtarget
-        Object.setPrototypeOf(this, DataConnectError.prototype);
-    }
-    /** @internal */
-    toString() {
-        return `${this.name}[code=${this.code}]: ${this.message}`;
-    }
-}
-/** An error returned by a DataConnect operation. */
-class DataConnectOperationError extends DataConnectError {
-    /** @hideconstructor */
-    constructor(message, response) {
-        super(Code.PARTIAL_ERROR, message);
-        /** @internal */
-        this.name = 'DataConnectOperationError';
-        this.response = response;
-    }
-}
-
 /**
  * @license
  * Copyright 2024 Google LLC
@@ -205,6 +719,9 @@ class FirebaseAuthProvider {
             _authProvider.onInit(auth => (this._auth = auth));
         }
     }
+    getAuth() {
+        return this._auth;
+    }
     getToken(forceRefresh) {
         if (!this._auth) {
             return new Promise((resolve, reject) => {
@@ -264,7 +781,7 @@ const SOURCE_CACHE = 'CACHE';
 
 /**
  * @license
- * Copyright 2024 Google LLC
+ * Copyright 2026 Google LLC
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -278,11 +795,43 @@ const SOURCE_CACHE = 'CACHE';
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-let encoderImpl;
-function setEncoder(encoder) {
-    encoderImpl = encoder;
+function parseEntityIds(result) {
+    // Iterate through extensions.dataConnect
+    const dataConnectExtensions = result.extensions?.dataConnect;
+    const dataCopy = Object.assign(result);
+    if (!dataConnectExtensions) {
+        return dataCopy;
+    }
+    const ret = {};
+    for (const extension of dataConnectExtensions) {
+        const { path } = extension;
+        populatePath(path, ret, extension);
+    }
+    return ret;
+}
+// mutates the object to update the path
+function populatePath(path, toUpdate, extension) {
+    let curObj = toUpdate;
+    for (const slice of path) {
+        if (typeof curObj[slice] !== 'object') {
+            curObj[slice] = {};
+        }
+        curObj = curObj[slice];
+    }
+    if ('entityId' in extension && extension.entityId) {
+        curObj['_id'] = extension.entityId;
+    }
+    else if ('entityIds' in extension) {
+        const entityArr = extension.entityIds;
+        for (let i = 0; i < entityArr.length; i++) {
+            const entityId = entityArr[i];
+            if (typeof curObj[i] === 'undefined') {
+                curObj[i] = {};
+            }
+            curObj[i]._id = entityId;
+        }
+    }
 }
-setEncoder(o => JSON.stringify(o));
 
 /**
  * @license
@@ -300,11 +849,24 @@ setEncoder(o => JSON.stringify(o));
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-function setIfNotExists(map, key, val) {
-    if (!map.has(key)) {
-        map.set(key, val);
-    }
+let encoderImpl;
+let decoderImpl;
+function setEncoder(encoder) {
+    encoderImpl = encoder;
+}
+function setDecoder(decoder) {
+    decoderImpl = decoder;
 }
+function sortKeysForObj(o) {
+    return Object.keys(o)
+        .sort()
+        .reduce((accumulator, currentKey) => {
+        accumulator[currentKey] = o[currentKey];
+        return accumulator;
+    }, {});
+}
+setEncoder((o) => JSON.stringify(sortKeysForObj(o)));
+setDecoder(s => sortKeysForObj(JSON.parse(s)));
 
 /**
  * @license
@@ -322,7 +884,7 @@ function setIfNotExists(map, key, val) {
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-function getRefSerializer(queryRef, data, source) {
+function getRefSerializer(queryRef, data, source, fetchTime) {
     return function toJSON() {
         return {
             data,
@@ -334,32 +896,65 @@ function getRefSerializer(queryRef, data, source) {
                     ...queryRef.dataConnect.getSettings()
                 }
             },
-            fetchTime: Date.now().toLocaleString(),
+            fetchTime,
             source
         };
     };
 }
 class QueryManager {
-    constructor(transport) {
+    async preferCacheResults(queryRef, allowStale = false) {
+        let cacheResult;
+        try {
+            cacheResult = await this.fetchCacheResults(queryRef, allowStale);
+        }
+        catch (e) {
+            // Ignore the error and try to fetch from the server.
+        }
+        if (cacheResult) {
+            return cacheResult;
+        }
+        return this.fetchServerResults(queryRef);
+    }
+    constructor(transport, dc, cache) {
         this.transport = transport;
-        this._queries = new Map();
+        this.dc = dc;
+        this.cache = cache;
+        this.callbacks = new Map();
+        this.subscriptionCache = new Map();
+        this.queue = [];
     }
-    track(queryName, variables, initialCache) {
-        const ref = {
-            name: queryName,
-            variables,
-            refType: QUERY_STR
-        };
-        const key = encoderImpl(ref);
-        const newTrackedQuery = {
-            ref,
-            subscriptions: [],
-            currentCache: initialCache || null,
-            lastError: null
-        };
-        // @ts-ignore
-        setIfNotExists(this._queries, key, newTrackedQuery);
-        return this._queries.get(key);
+    async waitForQueuedWrites() {
+        for (const promise of this.queue) {
+            await promise;
+        }
+        this.queue = [];
+    }
+    updateSSR(updatedData) {
+        this.queue.push(this.updateCache(updatedData).then(async (result) => this.publishCacheResultsToSubscribers(result, updatedData.fetchTime)));
+    }
+    async updateCache(result, extensions) {
+        await this.waitForQueuedWrites();
+        if (this.cache) {
+            const entityIds = parseEntityIds(result);
+            const updatedMaxAge = getMaxAgeFromExtensions(extensions);
+            if (updatedMaxAge !== undefined) {
+                this.cache.cacheSettings.maxAgeSeconds = updatedMaxAge;
+            }
+            return this.cache.update(encoderImpl({
+                name: result.ref.name,
+                variables: result.ref.variables,
+                refType: QUERY_STR
+            }), result.data, entityIds);
+        }
+        else {
+            const key = encoderImpl({
+                name: result.ref.name,
+                variables: result.ref.variables,
+                refType: QUERY_STR
+            });
+            this.subscriptionCache.set(key, result);
+            return [key];
+        }
     }
     addSubscription(queryRef, onResultCallback, onCompleteCallback, onErrorCallback, initialCache) {
         const key = encoderImpl({
@@ -367,99 +962,213 @@ class QueryManager {
             variables: queryRef.variables,
             refType: QUERY_STR
         });
-        const trackedQuery = this._queries.get(key);
-        const subscription = {
-            userCallback: onResultCallback,
-            onCompleteCallback,
-            errCallback: onErrorCallback
-        };
         const unsubscribe = () => {
-            const trackedQuery = this._queries.get(key);
-            trackedQuery.subscriptions = trackedQuery.subscriptions.filter(sub => sub !== subscription);
-            onCompleteCallback?.();
-        };
-        if (initialCache && trackedQuery.currentCache !== initialCache) {
-            logDebug('Initial cache found. Comparing dates.');
-            if (!trackedQuery.currentCache ||
-                (trackedQuery.currentCache &&
-                    compareDates(trackedQuery.currentCache.fetchTime, initialCache.fetchTime))) {
-                trackedQuery.currentCache = initialCache;
+            if (this.callbacks.has(key)) {
+                const callbackList = this.callbacks.get(key);
+                this.callbacks.set(key, callbackList.filter(callback => callback !== subscription));
+                onCompleteCallback?.();
             }
-        }
-        if (trackedQuery.currentCache !== null) {
-            const cachedData = trackedQuery.currentCache.data;
-            onResultCallback({
-                data: cachedData,
-                source: SOURCE_CACHE,
-                ref: queryRef,
-                toJSON: getRefSerializer(queryRef, trackedQuery.currentCache.data, SOURCE_CACHE),
-                fetchTime: trackedQuery.currentCache.fetchTime
-            });
-            if (trackedQuery.lastError !== null && onErrorCallback) {
-                onErrorCallback(undefined);
-            }
-        }
-        trackedQuery.subscriptions.push({
+        };
+        const subscription = {
             userCallback: onResultCallback,
             errCallback: onErrorCallback,
             unsubscribe
-        });
-        if (!trackedQuery.currentCache) {
-            logDebug(`No cache available for query ${queryRef.name} with variables ${JSON.stringify(queryRef.variables)}. Calling executeQuery.`);
-            const promise = this.executeQuery(queryRef);
-            // We want to ignore the error and let subscriptions handle it
-            promise.then(undefined, err => { });
+        };
+        if (initialCache) {
+            this.updateSSR(initialCache);
+        }
+        const promise = this.preferCacheResults(queryRef, /*allowStale=*/ true);
+        // We want to ignore the error and let subscriptions handle it
+        promise.then(undefined, err => { });
+        if (!this.callbacks.has(key)) {
+            this.callbacks.set(key, []);
         }
+        this.callbacks
+            .get(key)
+            .push(subscription);
         return unsubscribe;
     }
-    executeQuery(queryRef) {
-        if (queryRef.refType !== QUERY_STR) {
-            throw new DataConnectError(Code.INVALID_ARGUMENT, `ExecuteQuery can only execute query operation`);
-        }
+    async fetchServerResults(queryRef) {
+        await this.waitForQueuedWrites();
         const key = encoderImpl({
             name: queryRef.name,
             variables: queryRef.variables,
             refType: QUERY_STR
         });
-        const trackedQuery = this._queries.get(key);
-        const result = this.transport.invokeQuery(queryRef.name, queryRef.variables);
-        const newR = result.then(res => {
-            const fetchTime = new Date().toString();
-            const result = {
-                ...res,
-                source: SOURCE_SERVER,
+        try {
+            const result = await this.transport.invokeQuery(queryRef.name, queryRef.variables);
+            const fetchTime = Date.now().toString();
+            const originalExtensions = result.extensions;
+            const queryResult = {
+                ...result,
                 ref: queryRef,
-                toJSON: getRefSerializer(queryRef, res.data, SOURCE_SERVER),
-                fetchTime
+                source: SOURCE_SERVER,
+                fetchTime,
+                data: result.data,
+                extensions: getDataConnectExtensionsWithoutMaxAge(originalExtensions),
+                toJSON: getRefSerializer(queryRef, result.data, SOURCE_SERVER, fetchTime)
             };
-            trackedQuery.subscriptions.forEach(subscription => {
-                subscription.userCallback(result);
+            let updatedKeys = [];
+            updatedKeys = await this.updateCache(queryResult, originalExtensions?.dataConnect);
+            this.publishDataToSubscribers(key, queryResult);
+            if (this.cache) {
+                await this.publishCacheResultsToSubscribers(updatedKeys, fetchTime);
+            }
+            else {
+                this.subscriptionCache.set(key, queryResult);
+            }
+            return queryResult;
+        }
+        catch (e) {
+            this.publishErrorToSubscribers(key, e);
+            throw e;
+        }
+    }
+    async fetchCacheResults(queryRef, allowStale = false) {
+        await this.waitForQueuedWrites();
+        let result;
+        if (!this.cache) {
+            result = await this.getFromSubscriberCache(queryRef);
+        }
+        else {
+            result = await this.getFromResultTreeCache(queryRef, allowStale);
+        }
+        if (!result) {
+            throw new DataConnectError(Code.OTHER, 'No cache entry found for query: ' + queryRef.name);
+        }
+        const fetchTime = Date.now().toString();
+        const queryResult = {
+            ...result,
+            ref: queryRef,
+            source: SOURCE_CACHE,
+            fetchTime,
+            data: result.data,
+            extensions: result.extensions,
+            toJSON: getRefSerializer(queryRef, result.data, SOURCE_CACHE, fetchTime)
+        };
+        if (this.cache) {
+            const key = encoderImpl({
+                name: queryRef.name,
+                variables: queryRef.variables,
+                refType: QUERY_STR
             });
-            trackedQuery.currentCache = {
-                data: res.data,
-                source: SOURCE_CACHE,
-                fetchTime
-            };
-            return result;
-        }, err => {
-            trackedQuery.lastError = err;
-            trackedQuery.subscriptions.forEach(subscription => {
-                if (subscription.errCallback) {
-                    subscription.errCallback(err);
-                }
+            await this.publishCacheResultsToSubscribers([key], fetchTime);
+        }
+        else {
+            const key = encoderImpl({
+                name: queryRef.name,
+                variables: queryRef.variables,
+                refType: QUERY_STR
             });
-            throw err;
+            this.subscriptionCache.set(key, queryResult);
+            this.publishDataToSubscribers(key, queryResult);
+        }
+        return queryResult;
+    }
+    publishErrorToSubscribers(key, err) {
+        this.callbacks.get(key)?.forEach(subscription => {
+            if (subscription.errCallback) {
+                subscription.errCallback(err);
+            }
+        });
+    }
+    async getFromResultTreeCache(queryRef, allowStale = false) {
+        const key = encoderImpl({
+            name: queryRef.name,
+            variables: queryRef.variables,
+            refType: QUERY_STR
+        });
+        if (!this.cache || !(await this.cache.containsResultTree(key))) {
+            return null;
+        }
+        const cacheResult = (await this.cache.getResultJSON(key));
+        const resultTree = await this.cache.getResultTree(key);
+        if (!allowStale && resultTree.isStale()) {
+            return null;
+        }
+        const result = {
+            source: SOURCE_CACHE,
+            ref: queryRef,
+            data: cacheResult,
+            toJSON: getRefSerializer(queryRef, cacheResult, SOURCE_CACHE, resultTree.cachedAt.toString()),
+            fetchTime: resultTree.cachedAt.toString()
+        };
+        (await this.cache.getResultTree(key)).updateAccessed();
+        return result;
+    }
+    async getFromSubscriberCache(queryRef) {
+        const key = encoderImpl({
+            name: queryRef.name,
+            variables: queryRef.variables,
+            refType: QUERY_STR
+        });
+        if (!this.subscriptionCache.has(key)) {
+            return;
+        }
+        const result = this.subscriptionCache.get(key);
+        result.source = SOURCE_CACHE;
+        result.toJSON = getRefSerializer(result.ref, result.data, SOURCE_CACHE, result.fetchTime);
+        return result;
+    }
+    publishDataToSubscribers(key, queryResult) {
+        if (!this.callbacks.has(key)) {
+            return;
+        }
+        const subscribers = this.callbacks.get(key);
+        subscribers.forEach(callback => {
+            callback.userCallback(queryResult);
         });
-        return newR;
+    }
+    async publishCacheResultsToSubscribers(impactedQueries, fetchTime) {
+        if (!this.cache) {
+            return;
+        }
+        for (const query of impactedQueries) {
+            const callbacks = this.callbacks.get(query);
+            if (!callbacks) {
+                continue;
+            }
+            const newJson = (await this.cache.getResultTree(query))
+                .getRootStub()
+                .toJSON(EncodingMode.hydrated);
+            const { name, variables } = decoderImpl(query);
+            const queryRef = {
+                dataConnect: this.dc,
+                refType: QUERY_STR,
+                name,
+                variables
+            };
+            this.publishDataToSubscribers(query, {
+                data: newJson,
+                fetchTime,
+                ref: queryRef,
+                source: SOURCE_CACHE,
+                toJSON: getRefSerializer(queryRef, newJson, SOURCE_CACHE, fetchTime)
+            });
+        }
     }
     enableEmulator(host, port) {
         this.transport.useEmulator(host, port);
     }
 }
-function compareDates(str1, str2) {
-    const date1 = new Date(str1);
-    const date2 = new Date(str2);
-    return date1.getTime() < date2.getTime();
+function getMaxAgeFromExtensions(extensions) {
+    if (!extensions) {
+        return;
+    }
+    for (const extension of extensions) {
+        if ('maxAge' in extension &&
+            extension.maxAge !== undefined &&
+            extension.maxAge !== null) {
+            if (extension.maxAge.endsWith('s')) {
+                return Number(extension.maxAge.substring(0, extension.maxAge.length - 1));
+            }
+        }
+    }
+}
+function getDataConnectExtensionsWithoutMaxAge(extensions) {
+    return {
+        dataConnect: extensions.dataConnect?.filter(extension => 'entityId' in extension || 'entityIds' in extension)
+    };
 }
 
 /**
@@ -503,11 +1212,12 @@ const CallerSdkTypeEnum = {
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+const PROD_HOST = 'firebasedataconnect.googleapis.com';
 function urlBuilder(projectConfig, transportOptions) {
     const { connector, location, projectId: project, service } = projectConfig;
     const { host, sslEnabled, port } = transportOptions;
     const protocol = sslEnabled ? 'https' : 'http';
-    const realHost = host || `firebasedataconnect.googleapis.com`;
+    const realHost = host || PROD_HOST;
     let baseUrl = `${protocol}://${realHost}`;
     if (typeof port === 'number') {
         baseUrl += `:${port}`;
@@ -555,7 +1265,7 @@ function getGoogApiClientValue(_isUsingGen, _callerSdkType) {
     }
     return str;
 }
-function dcFetch(url, body, { signal }, appId, accessToken, appCheckToken, _isUsingGen, _callerSdkType, _isUsingEmulator) {
+async function dcFetch(url, body, { signal }, appId, accessToken, appCheckToken, _isUsingGen, _callerSdkType, _isUsingEmulator) {
     if (!connectFetch) {
         throw new DataConnectError(Code.OTHER, 'No Fetch Implementation detected!');
     }
@@ -582,41 +1292,44 @@ function dcFetch(url, body, { signal }, appId, accessToken, appCheckToken, _isUs
     if (util.isCloudWorkstation(url) && _isUsingEmulator) {
         fetchOptions.credentials = 'include';
     }
-    return connectFetch(url, fetchOptions)
-        .catch(err => {
+    let response;
+    try {
+        response = await connectFetch(url, fetchOptions);
+    }
+    catch (err) {
         throw new DataConnectError(Code.OTHER, 'Failed to fetch: ' + JSON.stringify(err));
-    })
-        .then(async (response) => {
-        let jsonResponse = null;
-        try {
-            jsonResponse = await response.json();
-        }
-        catch (e) {
-            throw new DataConnectError(Code.OTHER, JSON.stringify(e));
-        }
-        const message = getMessage(jsonResponse);
-        if (response.status >= 400) {
-            logError('Error while performing request: ' + JSON.stringify(jsonResponse));
-            if (response.status === 401) {
-                throw new DataConnectError(Code.UNAUTHORIZED, message);
-            }
-            throw new DataConnectError(Code.OTHER, message);
-        }
-        return jsonResponse;
-    })
-        .then(res => {
-        if (res.errors && res.errors.length) {
-            const stringified = JSON.stringify(res.errors);
-            const response = {
-                errors: res.errors,
-                data: res.data
-            };
-            throw new DataConnectOperationError('DataConnect error while performing request: ' + stringified, response);
+    }
+    let jsonResponse;
+    try {
+        jsonResponse = await response.json();
+    }
+    catch (e) {
+        throw new DataConnectError(Code.OTHER, JSON.stringify(e));
+    }
+    const message = getErrorMessage(jsonResponse);
+    if (response.status >= 400) {
+        logError('Error while performing request: ' + JSON.stringify(jsonResponse));
+        if (response.status === 401) {
+            throw new DataConnectError(Code.UNAUTHORIZED, message);
         }
-        return res;
-    });
+        throw new DataConnectError(Code.OTHER, message);
+    }
+    if (jsonResponse.errors && jsonResponse.errors.length) {
+        const stringified = JSON.stringify(jsonResponse.errors);
+        const failureResponse = {
+            errors: jsonResponse.errors,
+            data: jsonResponse.data
+        };
+        throw new DataConnectOperationError('DataConnect error while performing request: ' + stringified, failureResponse);
+    }
+    if (!jsonResponse.extensions) {
+        jsonResponse.extensions = {
+            dataConnect: []
+        };
+    }
+    return jsonResponse;
 }
-function getMessage(obj) {
+function getErrorMessage(obj) {
     if ('message' in obj && obj.message) {
         return obj.message;
     }
@@ -733,7 +1446,10 @@ class RESTTransport {
     async getWithAuth(forceToken = false) {
         let starterPromise = new Promise(resolve => resolve(this._accessToken));
         if (this.appCheckProvider) {
-            this._appCheckToken = (await this.appCheckProvider.getToken())?.token;
+            const appCheckToken = await this.appCheckProvider.getToken();
+            if (appCheckToken) {
+                this._appCheckToken = appCheckToken.token;
+            }
         }
         if (this.authProvider) {
             starterPromise = this.authProvider
@@ -902,6 +1618,12 @@ class DataConnect {
             }
         }
     }
+    /**
+     * @internal
+     */
+    getCache() {
+        return this.cache;
+    }
     // @internal
     _useGeneratedSdk() {
         if (!this._isUsingGeneratedSdk) {
@@ -924,6 +1646,12 @@ class DataConnect {
         delete copy.projectId;
         return copy;
     }
+    /**
+     * @internal
+     */
+    setCacheSettings(cacheSettings) {
+        this._cacheSettings = cacheSettings;
+    }
     // @internal
     setInitialized() {
         if (this._initialized) {
@@ -933,19 +1661,25 @@ class DataConnect {
             logDebug('transportClass not provided. Defaulting to RESTTransport.');
             this._transportClass = RESTTransport;
         }
-        if (this._authProvider) {
-            this._authTokenProvider = new FirebaseAuthProvider(this.app.name, this.app.options, this._authProvider);
+        this._authTokenProvider = new FirebaseAuthProvider(this.app.name, this.app.options, this._authProvider);
+        const connectorConfig = {
+            connector: this.dataConnectOptions.connector,
+            service: this.dataConnectOptions.service,
+            location: this.dataConnectOptions.location
+        };
+        if (this._cacheSettings) {
+            this.cache = new DataConnectCache(this._authTokenProvider, this.app.options.projectId, connectorConfig, this._transportOptions?.host || PROD_HOST, this._cacheSettings);
         }
         if (this._appCheckProvider) {
             this._appCheckTokenProvider = new AppCheckTokenProvider(this.app, this._appCheckProvider);
         }
-        this._initialized = true;
         this._transport = new this._transportClass(this.dataConnectOptions, this.app.options.apiKey, this.app.options.appId, this._authTokenProvider, this._appCheckTokenProvider, undefined, this._isUsingGeneratedSdk, this._callerSdkType);
         if (this._transportOptions) {
             this._transport.useEmulator(this._transportOptions.host, this._transportOptions.port, this._transportOptions.sslEnabled);
         }
-        this._queryManager = new QueryManager(this._transport);
+        this._queryManager = new QueryManager(this._transport, this, this.cache);
         this._mutationManager = new MutationManager(this._transport);
+        this._initialized = true;
     }
     // @internal
     enableEmulator(transportOptions) {
@@ -985,22 +1719,32 @@ function connectDataConnectEmulator(dc, host, port, sslEnabled = false) {
     }
     dc.enableEmulator({ host, port, sslEnabled });
 }
-function getDataConnect(appOrOptions, optionalOptions) {
+function getDataConnect(appOrConnectorConfig, settingsOrConnectorConfig, settings) {
     let app$1;
-    let dcOptions;
-    if ('location' in appOrOptions) {
-        dcOptions = appOrOptions;
+    let connectorConfig;
+    let realSettings;
+    if ('location' in appOrConnectorConfig) {
+        connectorConfig = appOrConnectorConfig;
         app$1 = app.getApp();
+        realSettings = settingsOrConnectorConfig;
     }
     else {
-        dcOptions = optionalOptions;
-        app$1 = appOrOptions;
+        app$1 = appOrConnectorConfig;
+        connectorConfig = settingsOrConnectorConfig;
+        realSettings = settings;
     }
     if (!app$1 || Object.keys(app$1).length === 0) {
         app$1 = app.getApp();
     }
+    // Options to store in Firebase Component Provider.
+    const serializedOptions = {
+        ...connectorConfig,
+        projectId: app$1.options.projectId
+    };
+    // We should sort the keys before initialization.
+    const sortedSerialized = Object.fromEntries(Object.entries(serializedOptions).sort());
     const provider = app._getProvider(app$1, 'data-connect');
-    const identifier = JSON.stringify(dcOptions);
+    const identifier = JSON.stringify(sortedSerialized);
     if (provider.isInitialized(identifier)) {
         const dcInstance = provider.getImmediate({ identifier });
         const options = provider.getOptions(identifier);
@@ -1010,13 +1754,19 @@ function getDataConnect(appOrOptions, optionalOptions) {
             return dcInstance;
         }
     }
-    validateDCOptions(dcOptions);
+    validateDCOptions(connectorConfig);
     logDebug('Creating new DataConnect instance');
     // Initialize with options.
-    return provider.initialize({
+    const dataConnect = provider.initialize({
         instanceIdentifier: identifier,
-        options: dcOptions
+        options: Object.fromEntries(Object.entries({
+            ...sortedSerialized
+        }).sort())
     });
+    if (realSettings?.cacheSettings) {
+        dataConnect.setCacheSettings(realSettings.cacheSettings);
+    }
+    return dataConnect;
 }
 /**
  *
@@ -1046,6 +1796,12 @@ function terminate(dataConnect) {
     return dataConnect._delete();
     // TODO(mtewani): Stop pending tasks
 }
+const StorageType = {
+    MEMORY: 'MEMORY'
+};
+function makeMemoryCacheProvider() {
+    return new MemoryStub();
+}
 
 /**
  * @license
@@ -1065,13 +1821,16 @@ function terminate(dataConnect) {
  */
 function registerDataConnect(variant) {
     setSDKVersion(app.SDK_VERSION);
-    app._registerComponent(new component.Component('data-connect', (container, { instanceIdentifier: settings, options }) => {
+    app._registerComponent(new component.Component('data-connect', (container, { instanceIdentifier: connectorConfigStr, options }) => {
         const app = container.getProvider('app').getImmediate();
         const authProvider = container.getProvider('auth-internal');
         const appCheckProvider = container.getProvider('app-check-internal');
         let newOpts = options;
-        if (settings) {
-            newOpts = JSON.parse(settings);
+        if (connectorConfigStr) {
+            newOpts = {
+                ...JSON.parse(connectorConfigStr),
+                ...newOpts
+            };
         }
         if (!app.options.projectId) {
             throw new DataConnectError(Code.INVALID_ARGUMENT, 'Project ID must be provided. Did you pass in a proper projectId to initializeApp?');
@@ -1083,6 +1842,28 @@ function registerDataConnect(variant) {
     app.registerVersion(name, version, 'cjs2020');
 }
 
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+const QueryFetchPolicy = {
+    PREFER_CACHE: 'PREFER_CACHE',
+    CACHE_ONLY: 'CACHE_ONLY',
+    SERVER_ONLY: 'SERVER_ONLY'
+};
+
 /**
  * @license
  * Copyright 2024 Google LLC
@@ -1104,8 +1885,22 @@ function registerDataConnect(variant) {
  * @param queryRef query to execute.
  * @returns `QueryPromise`
  */
-function executeQuery(queryRef) {
-    return queryRef.dataConnect._queryManager.executeQuery(queryRef);
+function executeQuery(queryRef, options) {
+    if (queryRef.refType !== QUERY_STR) {
+        return Promise.reject(new DataConnectError(Code.INVALID_ARGUMENT, `ExecuteQuery can only execute query operations`));
+    }
+    const queryManager = queryRef.dataConnect._queryManager;
+    const fetchPolicy = options?.fetchPolicy ?? QueryFetchPolicy.PREFER_CACHE;
+    switch (fetchPolicy) {
+        case QueryFetchPolicy.SERVER_ONLY:
+            return queryManager.fetchServerResults(queryRef);
+        case QueryFetchPolicy.CACHE_ONLY:
+            return queryManager.fetchCacheResults(queryRef, true);
+        case QueryFetchPolicy.PREFER_CACHE:
+            return queryManager.preferCacheResults(queryRef, false);
+        default:
+            throw new DataConnectError(Code.INVALID_ARGUMENT, `Invalid fetch policy: ${fetchPolicy}`);
+    }
 }
 /**
  * Execute Query
@@ -1117,7 +1912,9 @@ function executeQuery(queryRef) {
  */
 function queryRef(dcInstance, queryName, variables, initialCache) {
     dcInstance.setInitialized();
-    dcInstance._queryManager.track(queryName, variables, initialCache);
+    if (initialCache !== undefined) {
+        dcInstance._queryManager.updateSSR(initialCache);
+    }
     return {
         dataConnect: dcInstance,
         refType: QUERY_STR,
@@ -1180,7 +1977,7 @@ function validateArgs(connectorConfig, dcOrVars, vars, validateVars) {
 
 /**
  * @license
- * Copyright 2024 Google LLC
+ * Copyright 2025 Google LLC
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -1208,12 +2005,14 @@ function subscribe(queryRefOrSerializedResult, observerOrOnNext, onError, onComp
     if ('refInfo' in queryRefOrSerializedResult) {
         const serializedRef = queryRefOrSerializedResult;
         const { data, source, fetchTime } = serializedRef;
+        ref = toQueryRef(serializedRef);
         initialCache = {
             data,
             source,
-            fetchTime
+            fetchTime,
+            ref,
+            toJSON: getRefSerializer(ref, data, source, fetchTime)
         };
-        ref = toQueryRef(serializedRef);
     }
     else {
         ref = queryRefOrSerializedResult;
@@ -1248,13 +2047,16 @@ exports.DataConnectOperationError = DataConnectOperationError;
 exports.MUTATION_STR = MUTATION_STR;
 exports.MutationManager = MutationManager;
 exports.QUERY_STR = QUERY_STR;
+exports.QueryFetchPolicy = QueryFetchPolicy;
 exports.SOURCE_CACHE = SOURCE_CACHE;
 exports.SOURCE_SERVER = SOURCE_SERVER;
+exports.StorageType = StorageType;
 exports.areTransportOptionsEqual = areTransportOptionsEqual;
 exports.connectDataConnectEmulator = connectDataConnectEmulator;
 exports.executeMutation = executeMutation;
 exports.executeQuery = executeQuery;
 exports.getDataConnect = getDataConnect;
+exports.makeMemoryCacheProvider = makeMemoryCacheProvider;
 exports.mutationRef = mutationRef;
 exports.parseOptions = parseOptions;
 exports.queryRef = queryRef;