@firebase/firestore 3.9.0-canary.ce79f7fe2 → 3.9.0-canary.f8a2c5865

package/dist/firestore/src/api.d.ts

@@ -54,3 +54,4 @@ export type { ByteString as _ByteString } from './util/byte_string';
 export { logWarn as _logWarn } from './util/log';
 export { EmptyAuthCredentialsProvider as _EmptyAuthCredentialsProvider } from './api/credentials';
 export { EmptyAppCheckTokenProvider as _EmptyAppCheckTokenProvider } from './api/credentials';
+export { TestingHooks as _TestingHooks } from './util/testing_hooks';

package/dist/firestore/src/util/testing_hooks.d.ts

@@ -0,0 +1,84 @@
+/**
+ * @license
+ * Copyright 2023 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.
+ */
+/**
+ * Manages "testing hooks", hooks into the internals of the SDK to verify
+ * internal state and events during integration tests. Do not use this class
+ * except for testing purposes.
+ *
+ * There are two ways to retrieve the global singleton instance of this class:
+ * 1. The `instance` property, which returns null if the global singleton
+ *      instance has not been created. Use this property if the caller should
+ *      "do nothing" if there are no testing hooks registered, such as when
+ *      delivering an event to notify registered callbacks.
+ * 2. The `getOrCreateInstance()` method, which creates the global singleton
+ *      instance if it has not been created. Use this method if the instance is
+ *      needed to, for example, register a callback.
+ *
+ * @internal
+ */
+export declare class TestingHooks {
+    private readonly onExistenceFilterMismatchCallbacks;
+    private constructor();
+    /**
+     * Returns the singleton instance of this class, or null if it has not been
+     * initialized.
+     */
+    static get instance(): TestingHooks | null;
+    /**
+     * Returns the singleton instance of this class, creating it if is has never
+     * been created before.
+     */
+    static getOrCreateInstance(): TestingHooks;
+    /**
+     * Registers a callback to be notified when an existence filter mismatch
+     * occurs in the Watch listen stream.
+     *
+     * The relative order in which callbacks are notified is unspecified; do not
+     * rely on any particular ordering. If a given callback is registered multiple
+     * times then it will be notified multiple times, once per registration.
+     *
+     * @param callback the callback to invoke upon existence filter mismatch.
+     *
+     * @return a function that, when called, unregisters the given callback; only
+     * the first invocation of the returned function does anything; all subsequent
+     * invocations do nothing.
+     */
+    onExistenceFilterMismatch(callback: ExistenceFilterMismatchCallback): () => void;
+    /**
+     * Invokes all currently-registered `onExistenceFilterMismatch` callbacks.
+     * @param info Information about the existence filter mismatch.
+     */
+    notifyOnExistenceFilterMismatch(info: ExistenceFilterMismatchInfo): void;
+}
+/**
+ * Information about an existence filter mismatch, as specified to callbacks
+ * registered with `TestingUtils.onExistenceFilterMismatch()`.
+ */
+export interface ExistenceFilterMismatchInfo {
+    /** The number of documents that matched the query in the local cache. */
+    localCacheCount: number;
+    /**
+     * The number of documents that matched the query on the server, as specified
+     * in the ExistenceFilter message's `count` field.
+     */
+    existenceFilterCount: number;
+}
+/**
+ * The signature of callbacks registered with
+ * `TestingUtils.onExistenceFilterMismatch()`.
+ */
+export declare type ExistenceFilterMismatchCallback = (info: ExistenceFilterMismatchInfo) => void;

package/dist/firestore/test/integration/util/testing_hooks_util.d.ts

@@ -0,0 +1,40 @@
+/**
+ * @license
+ * Copyright 2023 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.
+ */
+/**
+ * Captures all existence filter mismatches in the Watch 'Listen' stream that
+ * occur during the execution of the given code block.
+ * @param callback The callback to invoke; during the invocation of this
+ * callback all existence filter mismatches will be captured.
+ * @return the captured existence filter mismatches and the result of awaiting
+ * the given callback.
+ */
+export declare function captureExistenceFilterMismatches<T>(callback: () => Promise<T>): Promise<[ExistenceFilterMismatchInfo[], T]>;
+/**
+ * Information about an existence filter mismatch, captured during an invocation
+ * of `captureExistenceFilterMismatches()`.
+ *
+ * See the documentation of `TestingHooks.notifyOnExistenceFilterMismatch()`
+ * for the meaning of these values.
+ *
+ * TODO: Delete this "interface" definition and instead use the one from
+ * testing_hooks.ts. I tried to do this but couldn't figure out how to get it to
+ * work in a way that survived bundling and minification.
+ */
+export interface ExistenceFilterMismatchInfo {
+    localCacheCount: number;
+    existenceFilterCount: number;
+}