Documentation and .d.ts improvements

MarkDuckworth · MarkDuckworth · commit 4b67f8a79645 · 2024-11-04T17:26:40.000-07:00
diff --git a/common/api-review/firestore-lite.api.md b/common/api-review/firestore-lite.api.md
@@ -1029,6 +1029,8 @@ export interface FindNearestOptions {
 // @public
 export class Firestore {
     get app(): FirebaseApp;
+    // Warning: (ae-incompatible-release-tags) The symbol "pipeline" is marked as @public, but its signature references "PipelineSource" which is marked as @beta
+    pipeline(): PipelineSource;
     toJSON(): object;
     type: 'firestore-lite' | 'firestore';
 }
@@ -1619,6 +1621,7 @@ export class Query<AppModelType = DocumentData, DbModelType extends DocumentData
     protected constructor();
     readonly converter: FirestoreDataConverter<AppModelType, DbModelType> | null;
     readonly firestore: Firestore;
+    pipeline(): Pipeline;
     readonly type: 'query' | 'collection';
     withConverter(converter: null): Query<DocumentData, DocumentData>;
     withConverter<NewAppModelType, NewDbModelType extends DocumentData = DocumentData>(converter: FirestoreDataConverter<NewAppModelType, NewDbModelType>): Query<NewAppModelType, NewDbModelType>;
@@ -2175,8 +2178,8 @@ export function xor(left: FilterExpr, ...right: FilterExpr[]): Xor;
 
 // Warnings were encountered during analysis:
 //
-// /Users/markduckworth/projects/firebase-js-sdk/packages/firestore/dist/lite/index.d.ts:9257:9 - (ae-incompatible-release-tags) The symbol "accumulators" is marked as @public, but its signature references "AccumulatorTarget" which is marked as @beta
-// /Users/markduckworth/projects/firebase-js-sdk/packages/firestore/dist/lite/index.d.ts:9258:9 - (ae-incompatible-release-tags) The symbol "groups" is marked as @public, but its signature references "Selectable" which is marked as @beta
-// /Users/markduckworth/projects/firebase-js-sdk/packages/firestore/dist/lite/index.d.ts:9287:9 - (ae-incompatible-release-tags) The symbol "orderings" is marked as @public, but its signature references "Ordering" which is marked as @beta
+// /Users/markduckworth/projects/firebase-js-sdk/packages/firestore/dist/lite/index.d.ts:9261:9 - (ae-incompatible-release-tags) The symbol "accumulators" is marked as @public, but its signature references "AccumulatorTarget" which is marked as @beta
+// /Users/markduckworth/projects/firebase-js-sdk/packages/firestore/dist/lite/index.d.ts:9262:9 - (ae-incompatible-release-tags) The symbol "groups" is marked as @public, but its signature references "Selectable" which is marked as @beta
+// /Users/markduckworth/projects/firebase-js-sdk/packages/firestore/dist/lite/index.d.ts:9291:9 - (ae-incompatible-release-tags) The symbol "orderings" is marked as @public, but its signature references "Ordering" which is marked as @beta
 
 ```
diff --git a/common/api-review/firestore.api.md b/common/api-review/firestore.api.md
@@ -1073,6 +1073,8 @@ export interface FindNearestOptions {
 // @public
 export class Firestore {
     get app(): FirebaseApp;
+    // Warning: (ae-incompatible-release-tags) The symbol "pipeline" is marked as @public, but its signature references "PipelineSource" which is marked as @beta
+    pipeline(): PipelineSource;
     toJSON(): object;
     type: 'firestore-lite' | 'firestore';
 }
@@ -1877,6 +1879,7 @@ export class Query<AppModelType = DocumentData, DbModelType extends DocumentData
     protected constructor();
     readonly converter: FirestoreDataConverter<AppModelType, DbModelType> | null;
     readonly firestore: Firestore;
+    pipeline(): Pipeline;
     readonly type: 'query' | 'collection';
     withConverter(converter: null): Query<DocumentData, DocumentData>;
     withConverter<NewAppModelType, NewDbModelType extends DocumentData = DocumentData>(converter: FirestoreDataConverter<NewAppModelType, NewDbModelType>): Query<NewAppModelType, NewDbModelType>;
@@ -2463,8 +2466,8 @@ export function xor(left: FilterExpr, ...right: FilterExpr[]): Xor;
 
 // Warnings were encountered during analysis:
 //
-// /Users/markduckworth/projects/firebase-js-sdk/packages/firestore/dist/index.d.ts:10107:9 - (ae-incompatible-release-tags) The symbol "accumulators" is marked as @public, but its signature references "AccumulatorTarget" which is marked as @beta
-// /Users/markduckworth/projects/firebase-js-sdk/packages/firestore/dist/index.d.ts:10108:9 - (ae-incompatible-release-tags) The symbol "groups" is marked as @public, but its signature references "Selectable" which is marked as @beta
-// /Users/markduckworth/projects/firebase-js-sdk/packages/firestore/dist/index.d.ts:10137:9 - (ae-incompatible-release-tags) The symbol "orderings" is marked as @public, but its signature references "Ordering" which is marked as @beta
+// /Users/markduckworth/projects/firebase-js-sdk/packages/firestore/dist/index.d.ts:10111:9 - (ae-incompatible-release-tags) The symbol "accumulators" is marked as @public, but its signature references "AccumulatorTarget" which is marked as @beta
+// /Users/markduckworth/projects/firebase-js-sdk/packages/firestore/dist/index.d.ts:10112:9 - (ae-incompatible-release-tags) The symbol "groups" is marked as @public, but its signature references "Selectable" which is marked as @beta
+// /Users/markduckworth/projects/firebase-js-sdk/packages/firestore/dist/index.d.ts:10141:9 - (ae-incompatible-release-tags) The symbol "orderings" is marked as @public, but its signature references "Ordering" which is marked as @beta
 
 ```
diff --git a/packages/firestore/lite/index.ts b/packages/firestore/lite/index.ts
@@ -33,7 +33,7 @@ export { PipelineResult } from '../src/lite-api/pipeline-result';
 
 export { Pipeline } from '../src/lite-api/pipeline';
 
-export { useFirestorePipelines } from '../src/lite-api/database-augmentation';
+export { useFirestorePipelines } from '../src/lite-api/database_augmentation';
 
 export {
   Stage,
diff --git a/packages/firestore/src/api.ts b/packages/firestore/src/api.ts
@@ -21,7 +21,7 @@ export { PipelineResult } from './lite-api/pipeline-result';
 
 export { Pipeline } from './lite-api/pipeline';
 
-export { useFirestorePipelines } from './api/database-augmentation';
+export { useFirestorePipelines } from './api/database_augmentation';
 
 export {
   Stage,
diff --git a/packages/firestore/src/api/database_augmentation.ts b/packages/firestore/src/api/database_augmentation.ts
@@ -7,18 +7,6 @@ import { Firestore } from './database';
 import { DocumentReference, Query } from './reference';
 import { ExpUserDataWriter } from './user_data_writer';
 
-declare module './database' {
-  interface Firestore {
-    pipeline(): PipelineSource;
-  }
-}
-
-declare module './reference' {
-  interface Query {
-    pipeline(): Pipeline;
-  }
-}
-
 export function useFirestorePipelines(): void {
   Firestore.prototype.pipeline = function (): PipelineSource {
     const firestore = this;
diff --git a/packages/firestore/src/lite-api/database.ts b/packages/firestore/src/lite-api/database.ts
@@ -41,12 +41,15 @@ import { cast } from '../util/input_validation';
 import { logWarn } from '../util/log';
 
 import { FirestoreService, removeComponents } from './components';
+import type { PipelineSource } from './pipeline-source';
 import {
   DEFAULT_HOST,
   FirestoreSettingsImpl,
   PrivateSettings,
   FirestoreSettings
 } from './settings';
+// `import type` to avoid bundling the source for
+// pipelines if `useFirestorePipelines()` is not called
 
 export { EmulatorMockTokenOptions } from '@firebase/util';
 
@@ -173,17 +176,16 @@ export class Firestore implements FirestoreService {
     removeComponents(this);
     return Promise.resolve();
   }
-}
 
-// Undocumented method of Firestore. This is only
-// in place to give developers a runtime error suggesting
-// how to correctly initialize Firestore for use with Pipelines.
-// @ts-ignore
-Firestore.prototype.pipeline = function (): unknown {
-  throw new Error(
-    'Pipelines not initialized. Your application must call `useFirestorePipelines()` before using Firestore Pipeline features.'
-  );
-};
+  /**
+   * Pipeline query.
+   */
+  pipeline(): PipelineSource {
+    throw new Error(
+      'Pipelines not initialized. Your application must call `useFirestorePipelines()` before using Firestore Pipeline features.'
+    );
+  }
+}
 
 /**
  * Initializes a new instance of Cloud Firestore with the provided settings.
diff --git a/packages/firestore/src/lite-api/database_augmentation.ts b/packages/firestore/src/lite-api/database_augmentation.ts
@@ -7,18 +7,6 @@ import { DocumentReference, Query } from './reference';
 import { LiteUserDataWriter } from './reference_impl';
 import { newUserDataReader } from './user_data_reader';
 
-declare module './database' {
-  interface Firestore {
-    pipeline(): PipelineSource;
-  }
-}
-
-declare module './reference' {
-  interface Query {
-    pipeline(): Pipeline;
-  }
-}
-
 export function useFirestorePipelines(): void {
   Firestore.prototype.pipeline = function (): PipelineSource {
     const userDataWriter = new LiteUserDataWriter(this);
diff --git a/packages/firestore/src/lite-api/reference.ts b/packages/firestore/src/lite-api/reference.ts
@@ -37,6 +37,7 @@ import { AutoId } from '../util/misc';
 import { Firestore } from './database';
 import { FieldPath } from './field_path';
 import { FieldValue } from './field_value';
+import type { Pipeline } from './pipeline';
 import { FirestoreDataConverter } from './snapshot';
 import { NestedUpdateFields, Primitive } from './types';
 
@@ -177,17 +178,16 @@ export class Query<
       this._query
     );
   }
-}
 
-// Undocumented method of Query. This is only
-// in place to give developers a runtime error suggesting
-// how to correctly initialize Firestore for use with Pipelines.
-// @ts-ignore
-Query.prototype.pipeline = function () {
-  throw new Error(
-    'Pipelines not initialized. Your application must call `useFirestorePipelines()` before using Firestore Pipeline features.'
-  );
-};
+  /**
+   * Pipeline query.
+   */
+  pipeline(): Pipeline {
+    throw new Error(
+      'Pipelines not initialized. Your application must call `useFirestorePipelines()` before using Firestore Pipeline features.'
+    );
+  }
+}
 
 /**
  * A `DocumentReference` refers to a document location in a Firestore database
