change ListenSource from Enum to union type

Author: milaGGL

common/api-review/firestore.api.md

@@ -351,10 +351,7 @@ export function limit(limit: number): QueryLimitConstraint;
 export function limitToLast(limit: number): QueryLimitConstraint;
 
 // @public
-export const enum ListenSource {
-    Cache = 1,
-    Default = 0
-}
+export type ListenSource = 'default' | 'cache';
 
 // @public
 export function loadBundle(firestore: Firestore, bundleData: ReadableStream<Uint8Array> | ArrayBuffer | string): LoadBundleTask;

docs-devsite/firestore_.md

@@ -157,12 +157,6 @@ https://github.com/firebase/firebase-js-sdk
 |  [Transaction](./firestore_.transaction.md#transaction_class) | A reference to a transaction.<!-- -->The <code>Transaction</code> object passed to a transaction's <code>updateFunction</code> provides the methods to read and write data within the transaction context. See [runTransaction()](./firestore_.md#runtransaction_6f03ec4)<!-- -->. |
 |  [WriteBatch](./firestore_.writebatch.md#writebatch_class) | A write batch, used to perform multiple writes as a single atomic unit.<!-- -->A <code>WriteBatch</code> object can be acquired by calling [writeBatch()](./firestore_.md#writebatch_231a8e0)<!-- -->. It provides methods for adding writes to the write batch. None of the writes will be committed (or visible locally) until [WriteBatch.commit()](./firestore_.writebatch.md#writebatchcommit) is called. |
 
-## Enumerations
-
-|  Enumeration | Description |
-|  --- | --- |
-|  [ListenSource](./firestore_.md#listensource) | Describe the source a query listens to. |
-
 ## Interfaces
 
 |  Interface | Description |
@@ -210,6 +204,7 @@ https://github.com/firebase/firebase-js-sdk
 |  [DocumentChangeType](./firestore_.md#documentchangetype) | The type of a <code>DocumentChange</code> may be 'added', 'removed', or 'modified'. |
 |  [FirestoreErrorCode](./firestore_.md#firestoreerrorcode) | The set of Firestore status codes. The codes are the same at the ones exposed by gRPC here: https://github.com/grpc/grpc/blob/master/doc/statuscodes.md<!-- -->Possible values: - 'cancelled': The operation was cancelled (typically by the caller). - 'unknown': Unknown error or an error from a different error domain. - 'invalid-argument': Client specified an invalid argument. Note that this differs from 'failed-precondition'. 'invalid-argument' indicates arguments that are problematic regardless of the state of the system (e.g. an invalid field name). - 'deadline-exceeded': Deadline expired before operation could complete. For operations that change the state of the system, this error may be returned even if the operation has completed successfully. For example, a successful response from a server could have been delayed long enough for the deadline to expire. - 'not-found': Some requested document was not found. - 'already-exists': Some document that we attempted to create already exists. - 'permission-denied': The caller does not have permission to execute the specified operation. - 'resource-exhausted': Some resource has been exhausted, perhaps a per-user quota, or perhaps the entire file system is out of space. - 'failed-precondition': Operation was rejected because the system is not in a state required for the operation's execution. - 'aborted': The operation was aborted, typically due to a concurrency issue like transaction aborts, etc. - 'out-of-range': Operation was attempted past the valid range. - 'unimplemented': Operation is not implemented or not supported/enabled. - 'internal': Internal errors. Means some invariants expected by underlying system has been broken. If you see one of these errors, something is very broken. - 'unavailable': The service is currently unavailable. This is most likely a transient condition and may be corrected by retrying with a backoff. - 'data-loss': Unrecoverable data loss or corruption. - 'unauthenticated': The request does not have valid authentication credentials for the operation. |
 |  [FirestoreLocalCache](./firestore_.md#firestorelocalcache) | Union type from all supported SDK cache layer. |
+|  [ListenSource](./firestore_.md#listensource) | Describe the source a query listens to.<code>default</code>: listens to both cache and server changes <code>cache</code>: listens to changes in cache only |
 |  [MemoryGarbageCollector](./firestore_.md#memorygarbagecollector) | Union type from all support gabage collectors for memory local cache. |
 |  [NestedUpdateFields](./firestore_.md#nestedupdatefields) | For each field (e.g. 'bar'), find all nested keys (e.g. {<!-- -->'bar.baz': T1, 'bar.qux': T2<!-- -->}<!-- -->). Intersect them together to make a single map containing all possible keys that are all marked as optional |
 |  [OrderByDirection](./firestore_.md#orderbydirection) | The direction of a [orderBy()](./firestore_.md#orderby_006d61f) clause is specified as 'desc' or 'asc' (descending or ascending). |
@@ -2557,6 +2552,18 @@ Union type from all supported SDK cache layer.
 export declare type FirestoreLocalCache = MemoryLocalCache | PersistentLocalCache;
 ```
 
+## ListenSource
+
+Describe the source a query listens to.
+
+`default`<!-- -->: listens to both cache and server changes `cache`<!-- -->: listens to changes in cache only
+
+<b>Signature:</b>
+
+```typescript
+export declare type ListenSource = 'default' | 'cache';
+```
+
 ## MemoryGarbageCollector
 
 Union type from all support gabage collectors for memory local cache.
@@ -2722,21 +2729,3 @@ export declare type WithFieldValue<T> = T | (T extends Primitive ? T : T extends
     [K in keyof T]: WithFieldValue<T[K]> | FieldValue;
 } : never);
 ```
-
-## ListenSource
-
-Describe the source a query listens to.
-
-<b>Signature:</b>
-
-```typescript
-export declare const enum ListenSource 
-```
-
-## Enumeration Members
-
-|  Member | Value | Description |
-|  --- | --- | --- |
-|  Cache | <code>1</code> | Listen to changes in cache only |
-|  Default | <code>0</code> | Listen to both cache and server changes |
-

docs-devsite/firestore_.snapshotlistenoptions.md

@@ -23,7 +23,7 @@ export declare interface SnapshotListenOptions
 |  Property | Type | Description |
 |  --- | --- | --- |
 |  [includeMetadataChanges](./firestore_.snapshotlistenoptions.md#snapshotlistenoptionsincludemetadatachanges) | boolean | Include a change even if only the metadata of the query or of a document changed. Default is false. |
-|  [source](./firestore_.snapshotlistenoptions.md#snapshotlistenoptionssource) | [ListenSource](./firestore_.md#listensource) | Set the source the query listens to. Default to ListenSource.Default, which listens to both cache and server. |
+|  [source](./firestore_.snapshotlistenoptions.md#snapshotlistenoptionssource) | [ListenSource](./firestore_.md#listensource) | Set the source the query listens to. Default to "default", which listens to both cache and server. |
 
 ## SnapshotListenOptions.includeMetadataChanges
 
@@ -37,7 +37,7 @@ readonly includeMetadataChanges?: boolean;
 
 ## SnapshotListenOptions.source
 
-Set the source the query listens to. Default to ListenSource.Default, which listens to both cache and server.
+Set the source the query listens to. Default to "default", which listens to both cache and server.
 
 <b>Signature:</b>
 

packages/firestore/src/api/reference_impl.ts

@@ -24,6 +24,7 @@ import {
   NextFn,
   PartialObserver
 } from '../api/observer';
+import { ListenerDataSource } from '../core/event_manager';
 import {
   firestoreClientAddSnapshotsInSyncListener,
   firestoreClientGetDocumentFromLocalCache,
@@ -80,20 +81,18 @@ export interface SnapshotListenOptions {
   readonly includeMetadataChanges?: boolean;
 
   /**
-   * Set the source the query listens to. Default to ListenSource.Default, which
+   * Set the source the query listens to. Default to "default", which
    * listens to both cache and server.
    */
   readonly source?: ListenSource;
 }
 
-/** Describe the source a query listens to. */
-export const enum ListenSource {
-  /** Listen to both cache and server changes */
-  Default,
-
-  /** Listen to changes in cache only */
-  Cache
-}
+/** Describe the source a query listens to.
+ *
+ * `default`: listens to both cache and server changes
+ * `cache`: listens to changes in cache only
+ */
+export type ListenSource = 'default' | 'cache';
 
 /**
  * Reads the document referred to by this `DocumentReference`.
@@ -684,7 +683,7 @@ export function onSnapshot<AppModelType, DbModelType extends DocumentData>(
 
   let options: SnapshotListenOptions = {
     includeMetadataChanges: false,
-    source: ListenSource.Default
+    source: 'default'
   };
   let currArg = 0;
   if (typeof args[currArg] === 'object' && !isPartialObserver(args[currArg])) {
@@ -694,7 +693,7 @@ export function onSnapshot<AppModelType, DbModelType extends DocumentData>(
 
   const internalOptions = {
     includeMetadataChanges: options.includeMetadataChanges,
-    source: options.source
+    source: options.source as ListenerDataSource
   };
 
   if (isPartialObserver(args[currArg])) {

packages/firestore/src/core/event_manager.ts

@@ -15,7 +15,6 @@
  * limitations under the License.
  */
 
-import { ListenSource } from '../api/reference_impl';
 import { debugAssert, debugCast } from '../util/assert';
 import { wrapInUserErrorIfRecoverable } from '../util/async_queue';
 import { FirestoreError } from '../util/error';
@@ -342,6 +341,14 @@ function raiseSnapshotsInSyncEvent(eventManagerImpl: EventManagerImpl): void {
   });
 }
 
+export enum ListenerDataSource {
+  /** Listen to both cache and server changes */
+  Default = 'default',
+
+  /** Listen to changes in cache only */
+  Cache = 'cache'
+}
+
 export interface ListenOptions {
   /** Raise events even when only the metadata changes */
   readonly includeMetadataChanges?: boolean;
@@ -353,7 +360,7 @@ export interface ListenOptions {
   readonly waitForSyncWhenOnline?: boolean;
 
   /** Set the source events raised from. */
-  readonly source?: ListenSource;
+  readonly source?: ListenerDataSource;
 }
 
 /**
@@ -528,6 +535,6 @@ export class QueryListener {
   }
 
   listensToRemoteStore(): boolean {
-    return this.options.source !== ListenSource.Cache;
+    return this.options.source !== ListenerDataSource.Cache;
   }
 }

packages/firestore/test/integration/api/snasphot_listener_source.test.ts

@@ -17,6 +17,7 @@
 
 import { expect } from 'chai';
 
+import { ListenerDataSource as Source } from '../../../src/core/event_manager';
 import { EventsAccumulator } from '../util/events_accumulator';
 import {
   addDoc,
@@ -28,7 +29,6 @@ import {
   getDocs,
   limit,
   limitToLast,
-  ListenSource,
   onSnapshot,
   orderBy,
   query,
@@ -59,7 +59,7 @@ apiDescribe('Snapshot Listener source options ', persistence => {
           const storeEvent = new EventsAccumulator<QuerySnapshot>();
           const unsubscribe = onSnapshot(
             coll,
-            { source: ListenSource.Cache },
+            { source: Source.Cache },
             storeEvent.storeEvent
           );
 
@@ -83,7 +83,7 @@ apiDescribe('Snapshot Listener source options ', persistence => {
             const storeEvent = new EventsAccumulator<DocumentSnapshot>();
             const unsubscribe = onSnapshot(
               docRef,
-              { source: ListenSource.Cache },
+              { source: Source.Cache },
               storeEvent.storeEvent
             );
 
@@ -107,7 +107,7 @@ apiDescribe('Snapshot Listener source options ', persistence => {
           const storeEvent = new EventsAccumulator<QuerySnapshot>();
           const unsubscribe = onSnapshot(
             coll,
-            { includeMetadataChanges: true, source: ListenSource.Cache },
+            { includeMetadataChanges: true, source: Source.Cache },
             storeEvent.storeEvent
           );
 
@@ -139,13 +139,13 @@ apiDescribe('Snapshot Listener source options ', persistence => {
           const storeEvent = new EventsAccumulator<QuerySnapshot>();
           const unsubscribe1 = onSnapshot(
             testQuery,
-            { source: ListenSource.Cache },
+            { source: Source.Cache },
             storeEvent.storeEvent
           );
 
           const unsubscribe2 = onSnapshot(
             testQuery,
-            { source: ListenSource.Cache },
+            { source: Source.Cache },
             storeEvent.storeEvent
           );
 
@@ -207,15 +207,15 @@ apiDescribe('Snapshot Listener source options ', persistence => {
           const storeLimitEvent = new EventsAccumulator<QuerySnapshot>();
           let limitUnlisten = onSnapshot(
             query(coll, orderBy('sort', 'asc'), limit(2)),
-            { source: ListenSource.Cache },
+            { source: Source.Cache },
             storeLimitEvent.storeEvent
           );
 
           // Setup mirroring `limitToLast` query
           const storeLimitToLastEvent = new EventsAccumulator<QuerySnapshot>();
           let limitToLastUnlisten = onSnapshot(
             query(coll, orderBy('sort', 'desc'), limitToLast(2)),
-            { source: ListenSource.Cache },
+            { source: Source.Cache },
             storeLimitToLastEvent.storeEvent
           );
 
@@ -235,7 +235,7 @@ apiDescribe('Snapshot Listener source options ', persistence => {
           limitUnlisten();
           limitUnlisten = onSnapshot(
             query(coll, orderBy('sort', 'asc'), limit(2)),
-            { source: ListenSource.Cache },
+            { source: Source.Cache },
             storeLimitEvent.storeEvent
           );
           snapshot = await storeLimitEvent.awaitEvent();
@@ -269,7 +269,7 @@ apiDescribe('Snapshot Listener source options ', persistence => {
           await updateDoc(doc(coll, 'a'), { k: 'a', sort: -2 });
           limitToLastUnlisten = onSnapshot(
             query(coll, orderBy('sort', 'desc'), limitToLast(2)),
-            { source: ListenSource.Cache },
+            { source: Source.Cache },
             storeLimitToLastEvent.storeEvent
           );
 
@@ -320,7 +320,7 @@ apiDescribe('Snapshot Listener source options ', persistence => {
           const storeCacheEvent = new EventsAccumulator<QuerySnapshot>();
           const cacheUnlisten = onSnapshot(
             testQuery,
-            { source: ListenSource.Cache },
+            { source: Source.Cache },
             storeCacheEvent.storeEvent
           );
           snapshot = await storeCacheEvent.awaitEvent();
@@ -352,7 +352,7 @@ apiDescribe('Snapshot Listener source options ', persistence => {
 
           const cacheUnlisten = onSnapshot(
             testQuery,
-            { source: ListenSource.Cache },
+            { source: Source.Cache },
             storeCacheEvent.storeEvent
           );
           let snapshot = await storeCacheEvent.awaitEvent();
@@ -401,7 +401,7 @@ apiDescribe('Snapshot Listener source options ', persistence => {
           const storeEvent = new EventsAccumulator<QuerySnapshot>();
           const unsubscribe = onSnapshot(
             testQuery,
-            { includeMetadataChanges: true, source: ListenSource.Cache },
+            { includeMetadataChanges: true, source: Source.Cache },
             storeEvent.storeEvent
           );
 
@@ -443,7 +443,7 @@ apiDescribe('Snapshot Listener source options ', persistence => {
           const storeCacheEvent = new EventsAccumulator<QuerySnapshot>();
           const cacheUnlisten = onSnapshot(
             testQuery,
-            { includeMetadataChanges: true, source: ListenSource.Cache },
+            { includeMetadataChanges: true, source: Source.Cache },
             storeCacheEvent.storeEvent
           );
           let snapshot = await storeCacheEvent.awaitEvent();
@@ -523,7 +523,7 @@ apiDescribe('Snapshot Listener source options ', persistence => {
           const storeCacheEvent = new EventsAccumulator<QuerySnapshot>();
           const cacheUnlisten = onSnapshot(
             testQuery,
-            { source: ListenSource.Cache },
+            { source: Source.Cache },
             storeCacheEvent.storeEvent
           );
           await storeCacheEvent.awaitEvent();
@@ -568,7 +568,7 @@ apiDescribe('Snapshot Listener source options ', persistence => {
           const storeCacheEvent = new EventsAccumulator<QuerySnapshot>();
           const cacheUnlisten = onSnapshot(
             testQuery,
-            { source: ListenSource.Cache },
+            { source: Source.Cache },
             storeCacheEvent.storeEvent
           );
           await storeCacheEvent.awaitEvent();
@@ -617,7 +617,7 @@ apiDescribe('Snapshot Listener source options ', persistence => {
           const storeCacheEvent = new EventsAccumulator<QuerySnapshot>();
           let cacheUnlisten = onSnapshot(
             testQuery,
-            { source: ListenSource.Cache },
+            { source: Source.Cache },
             storeCacheEvent.storeEvent
           );
           snapshot = await storeCacheEvent.awaitEvent();
@@ -651,7 +651,7 @@ apiDescribe('Snapshot Listener source options ', persistence => {
 
           cacheUnlisten = onSnapshot(
             testQuery,
-            { source: ListenSource.Cache },
+            { source: Source.Cache },
             storeCacheEvent.storeEvent
           );
 
@@ -679,7 +679,7 @@ apiDescribe('Snapshot Listener source options ', persistence => {
           const storeEvent = new EventsAccumulator<QuerySnapshot>();
           const unsubscribe = onSnapshot(
             testQuery,
-            { source: ListenSource.Cache },
+            { source: Source.Cache },
             storeEvent.storeEvent
           );
 
@@ -695,11 +695,7 @@ apiDescribe('Snapshot Listener source options ', persistence => {
           expect(toDataArray(snapshot)).to.deep.equal([]); // Precondition check.
 
           const storeEvent = new EventsAccumulator<QuerySnapshot>();
-          onSnapshot(
-            coll,
-            { source: ListenSource.Cache },
-            storeEvent.storeEvent
-          );
+          onSnapshot(coll, { source: Source.Cache }, storeEvent.storeEvent);
           snapshot = await storeEvent.awaitEvent();
           expect(snapshot.metadata.fromCache).to.be.true;
           expect(toDataArray(snapshot)).to.deep.equal([]);
@@ -711,7 +707,7 @@ apiDescribe('Snapshot Listener source options ', persistence => {
           const accumulator = new EventsAccumulator<QuerySnapshot>();
           const unsubscribe = onSnapshot(
             coll,
-            { source: ListenSource.Cache },
+            { source: Source.Cache },
             accumulator.storeEvent
           );
 
@@ -756,7 +752,7 @@ apiDescribe('Snapshot Listener source options ', persistence => {
           const storeCacheEvent = new EventsAccumulator<QuerySnapshot>();
           const cacheUnlisten = onSnapshot(
             testQuery,
-            { source: ListenSource.Cache },
+            { source: Source.Cache },
             storeCacheEvent.storeEvent
           );
           snapshot = await storeCacheEvent.awaitEvent();