Markduckworth/or queries

.changeset/lucky-games-arrive.md

@@ -0,0 +1,8 @@
+---
+"@firebase/firestore": minor
+"firebase": minor
+---
+
+Functions in the Firestore package that return QueryConstraints (for example: `where(...)`, `limit(...)`, and `orderBy(...)`)
+now return a more specific type, which extends QueryConstraint. Refactoring and code that supports future features is also
+included in this release.

common/api-review/firestore-lite.api.md

@@ -140,16 +140,16 @@ export class DocumentSnapshot<T = DocumentData> {
 export { EmulatorMockTokenOptions }
 
 // @public
-export function endAt(snapshot: DocumentSnapshot<unknown>): QueryConstraint;
+export function endAt(snapshot: DocumentSnapshot<unknown>): QueryEndAtConstraint;
 
 // @public
-export function endAt(...fieldValues: unknown[]): QueryConstraint;
+export function endAt(...fieldValues: unknown[]): QueryEndAtConstraint;
 
 // @public
-export function endBefore(snapshot: DocumentSnapshot<unknown>): QueryConstraint;
+export function endBefore(snapshot: DocumentSnapshot<unknown>): QueryEndAtConstraint;
 
 // @public
-export function endBefore(...fieldValues: unknown[]): QueryConstraint;
+export function endBefore(...fieldValues: unknown[]): QueryEndAtConstraint;
 
 // @public
 export class FieldPath {
@@ -222,10 +222,10 @@ export function increment(n: number): FieldValue;
 export function initializeFirestore(app: FirebaseApp, settings: Settings): Firestore;
 
 // @public
-export function limit(limit: number): QueryConstraint;
+export function limit(limit: number): QueryLimitConstraint;
 
 // @public
-export function limitToLast(limit: number): QueryConstraint;
+export function limitToLast(limit: number): QueryLimitConstraint;
 
 export { LogLevel }
 
@@ -235,7 +235,7 @@ export type NestedUpdateFields<T extends Record<string, unknown>> = UnionToInter
 }[keyof T & string]>;
 
 // @public
-export function orderBy(fieldPath: string | FieldPath, directionStr?: OrderByDirection): QueryConstraint;
+export function orderBy(fieldPath: string | FieldPath, directionStr?: OrderByDirection): QueryOrderByConstraint;
 
 // @public
 export type OrderByDirection = 'desc' | 'asc';
@@ -275,9 +275,32 @@ export class QueryDocumentSnapshot<T = DocumentData> extends DocumentSnapshot<T>
     data(): T;
 }
 
+// @public
+export class QueryEndAtConstraint extends QueryConstraint {
+    readonly type: 'endBefore' | 'endAt';
+}
+
 // @public
 export function queryEqual<T>(left: Query<T>, right: Query<T>): boolean;
 
+// @public
+export class QueryFieldFilterConstraint extends QueryConstraint {
+    readonly type = "where";
+}
+
+// @public
+export class QueryLimitConstraint extends QueryConstraint {
+    readonly type: 'limit' | 'limitToLast';
+}
+
+// @public
+export type QueryNonFilterConstraint = QueryOrderByConstraint | QueryLimitConstraint | QueryStartAtConstraint | QueryEndAtConstraint;
+
+// @public
+export class QueryOrderByConstraint extends QueryConstraint {
+    readonly type = "orderBy";
+}
+
 // @public
 export class QuerySnapshot<T = DocumentData> {
     get docs(): Array<QueryDocumentSnapshot<T>>;
@@ -287,6 +310,11 @@ export class QuerySnapshot<T = DocumentData> {
     get size(): number;
 }
 
+// @public
+export class QueryStartAtConstraint extends QueryConstraint {
+    readonly type: 'startAt' | 'startAfter';
+}
+
 // @public
 export function refEqual<T>(left: DocumentReference<T> | CollectionReference<T>, right: DocumentReference<T> | CollectionReference<T>): boolean;
 
@@ -323,16 +351,16 @@ export interface Settings {
 export function snapshotEqual<T>(left: DocumentSnapshot<T> | QuerySnapshot<T>, right: DocumentSnapshot<T> | QuerySnapshot<T>): boolean;
 
 // @public
-export function startAfter(snapshot: DocumentSnapshot<unknown>): QueryConstraint;
+export function startAfter(snapshot: DocumentSnapshot<unknown>): QueryStartAtConstraint;
 
 // @public
-export function startAfter(...fieldValues: unknown[]): QueryConstraint;
+export function startAfter(...fieldValues: unknown[]): QueryStartAtConstraint;
 
 // @public
-export function startAt(snapshot: DocumentSnapshot<unknown>): QueryConstraint;
+export function startAt(snapshot: DocumentSnapshot<unknown>): QueryStartAtConstraint;
 
 // @public
-export function startAt(...fieldValues: unknown[]): QueryConstraint;
+export function startAt(...fieldValues: unknown[]): QueryStartAtConstraint;
 
 // @public
 export function terminate(firestore: Firestore): Promise<void>;
@@ -388,7 +416,7 @@ export function updateDoc<T>(reference: DocumentReference<T>, data: UpdateData<T
 export function updateDoc(reference: DocumentReference<unknown>, field: string | FieldPath, value: unknown, ...moreFieldsAndValues: unknown[]): Promise<void>;
 
 // @public
-export function where(fieldPath: string | FieldPath, opStr: WhereFilterOp, value: unknown): QueryConstraint;
+export function where(fieldPath: string | FieldPath, opStr: WhereFilterOp, value: unknown): QueryFieldFilterConstraint;
 
 // @public
 export type WhereFilterOp = '<' | '<=' | '==' | '!=' | '>=' | '>' | 'array-contains' | 'in' | 'array-contains-any' | 'not-in';

common/api-review/firestore.api.md

@@ -170,16 +170,16 @@ export function enableMultiTabIndexedDbPersistence(firestore: Firestore): Promis
 export function enableNetwork(firestore: Firestore): Promise<void>;
 
 // @public
-export function endAt(snapshot: DocumentSnapshot<unknown>): QueryConstraint;
+export function endAt(snapshot: DocumentSnapshot<unknown>): QueryEndAtConstraint;
 
 // @public
-export function endAt(...fieldValues: unknown[]): QueryConstraint;
+export function endAt(...fieldValues: unknown[]): QueryEndAtConstraint;
 
 // @public
-export function endBefore(snapshot: DocumentSnapshot<unknown>): QueryConstraint;
+export function endBefore(snapshot: DocumentSnapshot<unknown>): QueryEndAtConstraint;
 
 // @public
-export function endBefore(...fieldValues: unknown[]): QueryConstraint;
+export function endBefore(...fieldValues: unknown[]): QueryEndAtConstraint;
 
 // @public
 export class FieldPath {
@@ -298,10 +298,10 @@ export interface IndexField {
 export function initializeFirestore(app: FirebaseApp, settings: FirestoreSettings, databaseId?: string): Firestore;
 
 // @public
-export function limit(limit: number): QueryConstraint;
+export function limit(limit: number): QueryLimitConstraint;
 
 // @public
-export function limitToLast(limit: number): QueryConstraint;
+export function limitToLast(limit: number): QueryLimitConstraint;
 
 // @public
 export function loadBundle(firestore: Firestore, bundleData: ReadableStream<Uint8Array> | ArrayBuffer | string): LoadBundleTask;
@@ -383,7 +383,7 @@ export function onSnapshotsInSync(firestore: Firestore, observer: {
 export function onSnapshotsInSync(firestore: Firestore, onSync: () => void): Unsubscribe;
 
 // @public
-export function orderBy(fieldPath: string | FieldPath, directionStr?: OrderByDirection): QueryConstraint;
+export function orderBy(fieldPath: string | FieldPath, directionStr?: OrderByDirection): QueryOrderByConstraint;
 
 // @public
 export type OrderByDirection = 'desc' | 'asc';
@@ -428,9 +428,32 @@ export class QueryDocumentSnapshot<T = DocumentData> extends DocumentSnapshot<T>
     data(options?: SnapshotOptions): T;
 }
 
+// @public
+export class QueryEndAtConstraint extends QueryConstraint {
+    readonly type: 'endBefore' | 'endAt';
+}
+
 // @public
 export function queryEqual<T>(left: Query<T>, right: Query<T>): boolean;
 
+// @public
+export class QueryFieldFilterConstraint extends QueryConstraint {
+    readonly type = "where";
+}
+
+// @public
+export class QueryLimitConstraint extends QueryConstraint {
+    readonly type: 'limit' | 'limitToLast';
+}
+
+// @public
+export type QueryNonFilterConstraint = QueryOrderByConstraint | QueryLimitConstraint | QueryStartAtConstraint | QueryEndAtConstraint;
+
+// @public
+export class QueryOrderByConstraint extends QueryConstraint {
+    readonly type = "orderBy";
+}
+
 // @public
 export class QuerySnapshot<T = DocumentData> {
     docChanges(options?: SnapshotListenOptions): Array<DocumentChange<T>>;
@@ -442,6 +465,11 @@ export class QuerySnapshot<T = DocumentData> {
     get size(): number;
 }
 
+// @public
+export class QueryStartAtConstraint extends QueryConstraint {
+    readonly type: 'startAt' | 'startAfter';
+}
+
 // @public
 export function refEqual<T>(left: DocumentReference<T> | CollectionReference<T>, right: DocumentReference<T> | CollectionReference<T>): boolean;
 
@@ -494,16 +522,16 @@ export interface SnapshotOptions {
 }
 
 // @public
-export function startAfter(snapshot: DocumentSnapshot<unknown>): QueryConstraint;
+export function startAfter(snapshot: DocumentSnapshot<unknown>): QueryStartAtConstraint;
 
 // @public
-export function startAfter(...fieldValues: unknown[]): QueryConstraint;
+export function startAfter(...fieldValues: unknown[]): QueryStartAtConstraint;
 
 // @public
-export function startAt(snapshot: DocumentSnapshot<unknown>): QueryConstraint;
+export function startAt(snapshot: DocumentSnapshot<unknown>): QueryStartAtConstraint;
 
 // @public
-export function startAt(...fieldValues: unknown[]): QueryConstraint;
+export function startAt(...fieldValues: unknown[]): QueryStartAtConstraint;
 
 // @public
 export type TaskState = 'Error' | 'Running' | 'Success';
@@ -570,7 +598,7 @@ export function updateDoc(reference: DocumentReference<unknown>, field: string |
 export function waitForPendingWrites(firestore: Firestore): Promise<void>;
 
 // @public
-export function where(fieldPath: string | FieldPath, opStr: WhereFilterOp, value: unknown): QueryConstraint;
+export function where(fieldPath: string | FieldPath, opStr: WhereFilterOp, value: unknown): QueryFieldFilterConstraint;
 
 // @public
 export type WhereFilterOp = '<' | '<=' | '==' | '!=' | '>=' | '>' | 'array-contains' | 'in' | 'array-contains-any' | 'not-in';

packages/firestore/lite/index.ts

@@ -68,19 +68,29 @@ export {
 } from '../src/lite-api/reference';
 
 export {
+  and,
   endAt,
   endBefore,
   startAt,
   startAfter,
   limit,
   limitToLast,
-  orderBy,
-  OrderByDirection,
   where,
-  WhereFilterOp,
+  or,
+  orderBy,
   query,
   QueryConstraint,
-  QueryConstraintType
+  QueryConstraintType,
+  QueryCompositeFilterConstraint,
+  QueryFilterConstraint,
+  QueryFieldFilterConstraint,
+  QueryOrderByConstraint,
+  QueryLimitConstraint,
+  QueryNonFilterConstraint,
+  QueryStartAtConstraint,
+  QueryEndAtConstraint,
+  OrderByDirection,
+  WhereFilterOp
 } from '../src/lite-api/query';
 
 export {

packages/firestore/package.json

@@ -30,6 +30,8 @@
     "test:all:ci": "run-p test:browser test:lite:browser test:travis",
     "test:all": "run-p test:browser test:lite:browser test:travis test:minified",
     "test:browser": "karma start --single-run",
+    "test:browser:emulator:debug": "karma start --browsers=Chrome --local",
+    "test:browser:emulator": "karma start --single-run --local",
     "test:browser:unit": "karma start --single-run --unit",
     "test:browser:debug": "karma start --browsers=Chrome --auto-watch",
     "test:node": "node ./scripts/run-tests.js  --main=test/register.ts  --emulator 'test/{,!(browser|lite)/**/}*.test.ts'",

packages/firestore/src/api.ts

@@ -85,17 +85,27 @@ export {
 } from './api/reference';
 
 export {
+  and,
   endAt,
   endBefore,
   startAt,
   startAfter,
   limit,
   limitToLast,
   where,
+  or,
   orderBy,
   query,
   QueryConstraint,
   QueryConstraintType,
+  QueryCompositeFilterConstraint,
+  QueryFilterConstraint,
+  QueryFieldFilterConstraint,
+  QueryOrderByConstraint,
+  QueryLimitConstraint,
+  QueryNonFilterConstraint,
+  QueryStartAtConstraint,
+  QueryEndAtConstraint,
   OrderByDirection,
   WhereFilterOp
 } from './api/filter';

packages/firestore/src/api/filter.ts

@@ -16,17 +16,27 @@
  */
 
 export {
+  and,
   endAt,
   endBefore,
   startAfter,
   startAt,
   limitToLast,
   limit,
+  or,
   orderBy,
   OrderByDirection,
   where,
   WhereFilterOp,
   query,
+  QueryCompositeFilterConstraint,
   QueryConstraint,
-  QueryConstraintType
+  QueryConstraintType,
+  QueryFilterConstraint,
+  QueryFieldFilterConstraint,
+  QueryOrderByConstraint,
+  QueryLimitConstraint,
+  QueryStartAtConstraint,
+  QueryEndAtConstraint,
+  QueryNonFilterConstraint
 } from '../lite-api/query';