@firebase/data-connect 0.3.12 → 0.4.0-canary.78384d32c

package/dist/internal.d.ts

@@ -8,6 +8,7 @@ import { AppCheckInternalComponentName } from '@firebase/app-check-interop-types
 import { AppCheckTokenListener } from '@firebase/app-check-interop-types';
 import { AppCheckTokenResult } from '@firebase/app-check-interop-types';
 import { FirebaseApp } from '@firebase/app';
+import { FirebaseAuthInternal } from '@firebase/auth-interop-types';
 import { FirebaseAuthInternalName } from '@firebase/auth-interop-types';
 import { FirebaseAuthTokenData } from '@firebase/auth-interop-types';
 import { FirebaseError } from '@firebase/util';
@@ -40,6 +41,20 @@ declare type AuthTokenListener = (token: string | null) => void;
 declare interface AuthTokenProvider {
     getToken(forceRefresh: boolean): Promise<FirebaseAuthTokenData | null>;
     addTokenChangeListener(listener: AuthTokenListener): void;
+    getAuth(): FirebaseAuthInternal;
+}
+
+export declare interface CacheProvider<T extends StorageType> {
+    type: T;
+    /**
+     * @internal
+     */
+    initialize(cacheId: string): InternalCacheProvider;
+}
+
+export declare interface CacheSettings {
+    cacheProvider: CacheProvider<StorageType>;
+    maxAgeSeconds?: number;
 }
 
 /**
@@ -106,15 +121,50 @@ export declare class DataConnect {
     _isUsingGeneratedSdk: boolean;
     _callerSdkType: CallerSdkType;
     private _appCheckTokenProvider?;
+    private _cacheSettings?;
+    /**
+     * @internal
+     */
+    private cache?;
     constructor(app: FirebaseApp, dataConnectOptions: DataConnectOptions, _authProvider: Provider<FirebaseAuthInternalName>, _appCheckProvider: Provider<AppCheckInternalComponentName>);
+    /**
+     * @internal
+     */
+    getCache(): DataConnectCache | undefined;
     _useGeneratedSdk(): void;
     _setCallerSdkType(callerSdkType: CallerSdkType): void;
     _delete(): Promise<void>;
     getSettings(): ConnectorConfig;
+    /**
+     * @internal
+     */
+    setCacheSettings(cacheSettings: CacheSettings): void;
     setInitialized(): void;
     enableEmulator(transportOptions: TransportOptions): void;
 }
 
+declare class DataConnectCache {
+    private authProvider;
+    private projectId;
+    private connectorConfig;
+    private host;
+    cacheSettings: CacheSettings;
+    private cacheProvider;
+    private uid;
+    constructor(authProvider: AuthTokenProvider, projectId: string, connectorConfig: ConnectorConfig, host: string, cacheSettings: CacheSettings);
+    initialize(): Promise<void>;
+    getIdentifier(uid: string | null): Promise<string>;
+    initializeNewProviders(identifier: string): InternalCacheProvider;
+    containsResultTree(queryId: string): Promise<boolean>;
+    getResultTree(queryId: string): Promise<ResultTree | undefined>;
+    getResultJSON(queryId: string): Promise<Record<string, unknown>>;
+    update(queryId: string, serverValues: ServerValues, entityIds: Record<string, unknown>): Promise<string[]>;
+}
+
+export declare interface DataConnectEntityArray {
+    entityIds: string[];
+}
+
 /** An error returned by a DataConnect operation. */
 export declare class DataConnectError extends FirebaseError {
     /** @internal */
@@ -126,6 +176,20 @@ export declare class DataConnectError extends FirebaseError {
 
 export declare type DataConnectErrorCode = 'other' | 'already-initialized' | 'not-initialized' | 'not-supported' | 'invalid-argument' | 'partial-error' | 'unauthorized';
 
+export declare type DataConnectExtension = {
+    path: Array<string | number>;
+} & (DataConnectEntityArray | DataConnectSingleEntity);
+
+/** @internal */
+declare type DataConnectExtensionWithMaxAge = {
+    path: Array<string | number>;
+} & (DataConnectEntityArray | DataConnectSingleEntity | DataConnectMaxAge);
+
+/** @internal */
+declare interface DataConnectMaxAge {
+    maxAge: string;
+}
+
 /** An error returned by a DataConnect operation. */
 export declare class DataConnectOperationError extends DataConnectError {
     /** @internal */
@@ -153,17 +217,37 @@ export declare interface DataConnectOptions extends ConnectorConfig {
     projectId: string;
 }
 
+declare interface DataConnectResponse<T> {
+    data: T;
+    errors: Error[];
+    extensions: Extensions;
+}
+
+/** @internal */
+declare interface DataConnectResponseWithMaxAge<T> {
+    data: T;
+    errors: Error[];
+    extensions: ExtensionsWithMaxAge;
+}
+
 export declare interface DataConnectResult<Data, Variables> extends OpResult<Data> {
     ref: OperationRef<Data, Variables>;
 }
 
+export declare interface DataConnectSettings {
+    cacheSettings?: CacheSettings;
+}
+
+export declare interface DataConnectSingleEntity {
+    entityId: string;
+}
+
 /**
  * Representation of user provided subscription options.
  */
-declare interface DataConnectSubscription<Data, Variables> {
+export declare interface DataConnectSubscription<Data, Variables> {
     userCallback: OnResultSubscription<Data, Variables>;
     errCallback?: (e?: DataConnectError) => void;
-    onCompleteCallback?: () => void;
     unsubscribe: () => void;
 }
 
@@ -171,14 +255,8 @@ declare interface DataConnectSubscription<Data, Variables> {
  * @internal
  */
 export declare interface DataConnectTransport {
-    invokeQuery<T, U>(queryName: string, body?: U): Promise<{
-        data: T;
-        errors: Error[];
-    }>;
-    invokeMutation<T, U>(queryName: string, body?: U): Promise<{
-        data: T;
-        errors: Error[];
-    }>;
+    invokeQuery<T, U>(queryName: string, body?: U): Promise<DataConnectResponseWithMaxAge<T>>;
+    invokeMutation<T, U>(queryName: string, body?: U): Promise<DataConnectResponse<T>>;
     useEmulator(host: string, port?: number, sslEnabled?: boolean): void;
     onTokenChanged: (token: string | null) => void;
     _setCallerSdkType(callerSdkType: CallerSdkType): void;
@@ -186,6 +264,70 @@ export declare interface DataConnectTransport {
 
 export declare type DataSource = typeof SOURCE_CACHE | typeof SOURCE_SERVER;
 
+declare interface DehydratedResultTreeJson {
+    rootStub: DehydratedStubDataObject;
+    maxAge: number;
+    cachedAt: Date;
+    lastAccessed: Date;
+}
+
+declare interface DehydratedStubDataObject {
+    backingData?: EntityDataObjectJson;
+    globalID?: string;
+    scalars: {
+        [key: string]: FDCScalarValue;
+    };
+    references: {
+        [key: string]: DehydratedStubDataObject;
+    };
+    objectLists: {
+        [key: string]: DehydratedStubDataObject[];
+    };
+}
+
+declare enum EncodingMode {
+    hydrated = 0,
+    dehydrated = 1
+}
+
+declare class EntityDataObject {
+    readonly globalID: string;
+    getServerValue(key: string): unknown;
+    private serverValues;
+    private referencedFrom;
+    constructor(globalID: string);
+    getServerValues(): {
+        [key: string]: FDCScalarValue;
+    };
+    toJSON(): EntityDataObjectJson;
+    static fromJSON(json: EntityDataObjectJson): EntityDataObject;
+    updateServerValue(key: string, value: FDCScalarValue, requestedFrom: string): string[];
+}
+
+declare interface EntityDataObjectJson {
+    map: {
+        [key: string]: FDCScalarValue;
+    };
+    referencedFrom: string[];
+    globalID: string;
+}
+
+declare class EntityNode {
+    entityData?: EntityDataObject;
+    scalars: Record<string, FDCScalarValue>;
+    references: {
+        [key: string]: EntityNode;
+    };
+    objectLists: {
+        [key: string]: EntityNode[];
+    };
+    globalId?: string;
+    entityDataKeys: Set<string>;
+    loadData(queryId: string, values: FDCScalarValue, entityIds: Record<string, unknown> | undefined, acc: ImpactedQueryRefsAccumulator, cacheProvider: InternalCacheProvider): Promise<void>;
+    toJSON(mode: EncodingMode): Record<string, unknown>;
+    static fromJson(obj: DehydratedStubDataObject): EntityNode;
+}
+
 /**
  * Execute Mutation
  * @param mutationRef mutation to execute
@@ -198,20 +340,101 @@ export declare function executeMutation<Data, Variables>(mutationRef: MutationRe
  * @param queryRef query to execute.
  * @returns `QueryPromise`
  */
-export declare function executeQuery<Data, Variables>(queryRef: QueryRef<Data, Variables>): QueryPromise<Data, Variables>;
+export declare function executeQuery<Data, Variables>(queryRef: QueryRef<Data, Variables>, options?: ExecuteQueryOptions): QueryPromise<Data, Variables>;
+
+export declare interface ExecuteQueryOptions {
+    fetchPolicy: QueryFetchPolicy;
+}
+
+export declare interface Extensions {
+    dataConnect?: DataConnectExtension[];
+}
+
+/** @internal */
+declare interface ExtensionsWithMaxAge {
+    dataConnect?: DataConnectExtensionWithMaxAge[];
+}
+
+/**
+ * @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.
+ */
+declare type FDCScalarValue = string | number | boolean | undefined | null | Record<string, unknown> | FDCScalarValue[];
 
 /**
  * Initialize DataConnect instance
  * @param options ConnectorConfig
  */
+export declare function getDataConnect(options: ConnectorConfig, settings?: DataConnectSettings): DataConnect;
+
 export declare function getDataConnect(options: ConnectorConfig): DataConnect;
 
 /**
  * Initialize DataConnect instance
  * @param app FirebaseApp to initialize to.
- * @param options ConnectorConfig
+ * @param connectorConfig ConnectorConfig
+ */
+export declare function getDataConnect(app: FirebaseApp, connectorConfig: ConnectorConfig): DataConnect;
+
+/**
+ * Initialize DataConnect instance
+ * @param app FirebaseApp to initialize to.
+ * @param connectorConfig ConnectorConfig
  */
-export declare function getDataConnect(app: FirebaseApp, options: ConnectorConfig): DataConnect;
+export declare function getDataConnect(app: FirebaseApp, connectorConfig: ConnectorConfig, settings: DataConnectSettings): DataConnect;
+
+/**
+ * @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.
+ */
+declare class ImpactedQueryRefsAccumulator {
+    private queryId;
+    impacted: Set<string>;
+    constructor(queryId: string);
+    add(impacted: string[]): void;
+    consumeEvents(): string[];
+}
+
+declare interface InternalCacheProvider {
+    getEntityData(globalId: string): Promise<EntityDataObject>;
+    updateEntityData(entityData: EntityDataObject): Promise<void>;
+    getResultTree(queryId: string): Promise<ResultTree | undefined>;
+    setResultTree(queryId: string, resultTree: ResultTree): Promise<void>;
+    close(): void;
+}
+
+/** @internal */
+export declare type InternalQueryResult<Data, Variables> = QueryResult<Data, Variables> & Omit<DataConnectResult<Data, Variables>, 'extensions'> & {
+    extensions?: {
+        dataConnect?: DataConnectExtensionWithMaxAge[];
+    };
+};
+
+export declare function makeMemoryCacheProvider(): CacheProvider<'MEMORY'>;
 
 export declare const MUTATION_STR = "mutation";
 
@@ -283,6 +506,7 @@ export declare interface OpResult<Data> {
     data: Data;
     source: DataSource;
     fetchTime: string;
+    extensions?: Extensions;
 }
 
 declare interface ParsedArgs<Variables> {
@@ -300,13 +524,50 @@ export declare function parseOptions(fullHost: string): TransportOptions;
 
 export declare const QUERY_STR = "query";
 
+/**
+ * @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.
+ */
+export declare const QueryFetchPolicy: {
+    readonly PREFER_CACHE: "PREFER_CACHE";
+    readonly CACHE_ONLY: "CACHE_ONLY";
+    readonly SERVER_ONLY: "SERVER_ONLY";
+};
+
+export declare type QueryFetchPolicy = (typeof QueryFetchPolicy)[keyof typeof QueryFetchPolicy];
+
 declare class QueryManager {
     private transport;
-    _queries: Map<string, TrackedQuery<unknown, unknown>>;
-    constructor(transport: DataConnectTransport);
-    track<Data, Variables>(queryName: string, variables: Variables, initialCache?: OpResult<Data>): TrackedQuery<Data, Variables>;
-    addSubscription<Data, Variables>(queryRef: OperationRef<Data, Variables>, onResultCallback: OnResultSubscription<Data, Variables>, onCompleteCallback?: OnCompleteSubscription, onErrorCallback?: OnErrorSubscription, initialCache?: OpResult<Data>): () => void;
-    executeQuery<Data, Variables>(queryRef: QueryRef<Data, Variables>): QueryPromise<Data, Variables>;
+    private dc;
+    private cache?;
+    preferCacheResults<Data, Variables>(queryRef: QueryRef<Data, Variables>, allowStale?: boolean): Promise<QueryResult<Data, Variables>>;
+    private callbacks;
+    private subscriptionCache;
+    constructor(transport: DataConnectTransport, dc: DataConnect, cache?: DataConnectCache | undefined);
+    private queue;
+    waitForQueuedWrites(): Promise<void>;
+    updateSSR<Data, Variables>(updatedData: QueryResult<Data, Variables>): void;
+    updateCache<Data, Variables>(result: QueryResult<Data, Variables>, extensions?: DataConnectExtensionWithMaxAge[]): Promise<string[]>;
+    addSubscription<Data, Variables>(queryRef: QueryRef<Data, Variables>, onResultCallback: OnResultSubscription<Data, Variables>, onCompleteCallback?: OnCompleteSubscription, onErrorCallback?: OnErrorSubscription, initialCache?: QueryResult<Data, Variables>): () => void;
+    fetchServerResults<Data, Variables>(queryRef: QueryRef<Data, Variables>): Promise<QueryResult<Data, Variables>>;
+    fetchCacheResults<Data, Variables>(queryRef: QueryRef<Data, Variables>, allowStale?: boolean): Promise<QueryResult<Data, Variables>>;
+    publishErrorToSubscribers(key: string, err: unknown): void;
+    getFromResultTreeCache<Data, Variables>(queryRef: QueryRef<Data, Variables>, allowStale?: boolean): Promise<QueryResult<Data, Variables> | null>;
+    getFromSubscriberCache<Data, Variables>(queryRef: QueryRef<Data, Variables>): Promise<QueryResult<Data, Variables> | undefined>;
+    publishDataToSubscribers(key: string, queryResult: QueryResult<unknown, unknown>): void;
+    publishCacheResultsToSubscribers(impactedQueries: string[], fetchTime: string): Promise<void>;
     enableEmulator(host: string, port: number): void;
 }
 
@@ -364,6 +625,25 @@ export declare interface RefInfo<Variables> {
     connectorConfig: DataConnectOptions;
 }
 
+declare class ResultTree {
+    private rootStub;
+    private maxAge;
+    readonly cachedAt: Date;
+    private _lastAccessed;
+    /**
+     * Create a {@link ResultTree} from a dehydrated JSON object.
+     * @param value The dehydrated JSON object.
+     * @returns The {@link ResultTree}.
+     */
+    static fromJson(value: DehydratedResultTreeJson): ResultTree;
+    constructor(rootStub: EntityNode, maxAge: number, cachedAt: Date, _lastAccessed: Date);
+    isStale(): boolean;
+    updateMaxAge(maxAgeInSeconds: number): void;
+    updateAccessed(): void;
+    get lastAccessed(): Date;
+    getRootStub(): EntityNode;
+}
+
 /**
  * Serialized Ref as a result of `QueryResult.toJSON()`
  */
@@ -371,12 +651,25 @@ export declare interface SerializedRef<Data, Variables> extends OpResult<Data> {
     refInfo: RefInfo<Variables>;
 }
 
+/**
+ * ServerValues
+ */
+declare interface ServerValues extends Record<string, unknown> {
+    maxAge?: number;
+}
+
 export declare function setLogLevel(logLevel: LogLevelString): void;
 
 export declare const SOURCE_CACHE = "CACHE";
 
 export declare const SOURCE_SERVER = "SERVER";
 
+export declare const StorageType: {
+    readonly MEMORY: "MEMORY";
+};
+
+export declare type StorageType = (typeof StorageType)[keyof typeof StorageType];
+
 /**
  * Subscribe to a `QueryRef`
  * @param queryRefOrSerializedResult query ref or serialized result.
@@ -418,13 +711,6 @@ export declare function terminate(dataConnect: DataConnect): Promise<void>;
  */
 export declare function toQueryRef<Data, Variables>(serializedRef: SerializedRef<Data, Variables>): QueryRef<Data, Variables>;
 
-declare interface TrackedQuery<Data, Variables> {
-    ref: Omit<OperationRef<Data, Variables>, 'dataConnect'>;
-    subscriptions: Array<DataConnectSubscription<Data, Variables>>;
-    currentCache: OpResult<Data> | null;
-    lastError: DataConnectError | null;
-}
-
 /**
  * @internal
  */