/var/www/qr4y.gr/server/delivery/node_modules/@google-cloud/firestore/build/src
Edit: /var/www/qr4y.gr/server/delivery/node_modules/@google-cloud/firestore/build/src/reference.d.ts (45610B)
/*!
* Copyright 2017 Google Inc. All Rights Reserved.
*
* 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.
*/
///
import * as firestore from '@google-cloud/firestore';
import * as protos from '../protos/firestore_v1_proto_api';
import { DocumentSnapshot, QueryDocumentSnapshot } from './document';
import { DocumentChange } from './document-change';
import { Firestore } from './index';
import { FieldPath, ResourcePath } from './path';
import { Serializable, Serializer } from './serializer';
import { Timestamp } from './timestamp';
import { WriteResult } from './write-batch';
import api = protos.google.firestore.v1;
/**
* onSnapshot() callback that receives a QuerySnapshot.
*
* @callback querySnapshotCallback
* @param {QuerySnapshot} snapshot A query snapshot.
*/
/**
* onSnapshot() callback that receives a DocumentSnapshot.
*
* @callback documentSnapshotCallback
* @param {DocumentSnapshot} snapshot A document snapshot.
*/
/**
* onSnapshot() callback that receives an error.
*
* @callback errorCallback
* @param {Error} err An error from a listen.
*/
/**
* A DocumentReference refers to a document location in a Firestore database
* and can be used to write, read, or listen to the location. The document at
* the referenced location may or may not exist. A DocumentReference can
* also be used to create a
* [CollectionReference]{@link CollectionReference} to a
* subcollection.
*
* @class DocumentReference
*/
export declare class DocumentReference
implements Serializable, firestore.DocumentReference {
private readonly _firestore;
readonly _path: ResourcePath;
readonly _converter: firestore.FirestoreDataConverter;
/**
* @hideconstructor
*
* @param _firestore The Firestore Database client.
* @param _path The Path of this reference.
* @param _converter The converter to use when serializing data.
*/
constructor(_firestore: Firestore, _path: ResourcePath, _converter?: firestore.FirestoreDataConverter);
/**
* The string representation of the DocumentReference's location.
* @private
* @internal
* @type {string}
* @name DocumentReference#formattedName
*/
get formattedName(): string;
/**
* The [Firestore]{@link Firestore} instance for the Firestore
* database (useful for performing transactions, etc.).
*
* @type {Firestore}
* @name DocumentReference#firestore
* @readonly
*
* @example
* ```
* let collectionRef = firestore.collection('col');
*
* collectionRef.add({foo: 'bar'}).then(documentReference => {
* let firestore = documentReference.firestore;
* console.log(`Root location for document is ${firestore.formattedName}`);
* });
* ```
*/
get firestore(): Firestore;
/**
* A string representing the path of the referenced document (relative
* to the root of the database).
*
* @type {string}
* @name DocumentReference#path
* @readonly
*
* @example
* ```
* let collectionRef = firestore.collection('col');
*
* collectionRef.add({foo: 'bar'}).then(documentReference => {
* console.log(`Added document at '${documentReference.path}'`);
* });
* ```
*/
get path(): string;
/**
* The last path element of the referenced document.
*
* @type {string}
* @name DocumentReference#id
* @readonly
*
* @example
* ```
* let collectionRef = firestore.collection('col');
*
* collectionRef.add({foo: 'bar'}).then(documentReference => {
* console.log(`Added document with name '${documentReference.id}'`);
* });
* ```
*/
get id(): string;
/**
* Returns a resource path for this document.
* @private
* @internal
*/
get _resourcePath(): ResourcePath;
/**
* A reference to the collection to which this DocumentReference belongs.
*
* @name DocumentReference#parent
* @type {CollectionReference}
* @readonly
*
* @example
* ```
* let documentRef = firestore.doc('col/doc');
* let collectionRef = documentRef.parent;
*
* collectionRef.where('foo', '==', 'bar').get().then(results => {
* console.log(`Found ${results.size} matches in parent collection`);
* }):
* ```
*/
get parent(): CollectionReference;
/**
* Reads the document referred to by this DocumentReference.
*
* @returns {Promise.} A Promise resolved with a
* DocumentSnapshot for the retrieved document on success. For missing
* documents, DocumentSnapshot.exists will be false. If the get() fails for
* other reasons, the Promise will be rejected.
*
* @example
* ```
* let documentRef = firestore.doc('col/doc');
*
* documentRef.get().then(documentSnapshot => {
* if (documentSnapshot.exists) {
* console.log('Document retrieved successfully.');
* }
* });
* ```
*/
get(): Promise>;
/**
* Gets a [CollectionReference]{@link CollectionReference} instance
* that refers to the collection at the specified path.
*
* @param {string} collectionPath A slash-separated path to a collection.
* @returns {CollectionReference} A reference to the new
* subcollection.
*
* @example
* ```
* let documentRef = firestore.doc('col/doc');
* let subcollection = documentRef.collection('subcollection');
* console.log(`Path to subcollection: ${subcollection.path}`);
* ```
*/
collection(collectionPath: string): CollectionReference;
/**
* Fetches the subcollections that are direct children of this document.
*
* @returns {Promise.>} A Promise that resolves
* with an array of CollectionReferences.
*
* @example
* ```
* let documentRef = firestore.doc('col/doc');
*
* documentRef.listCollections().then(collections => {
* for (let collection of collections) {
* console.log(`Found subcollection with id: ${collection.id}`);
* }
* });
* ```
*/
listCollections(): Promise>>;
/**
* Create a document with the provided object values. This will fail the write
* if a document exists at its location.
*
* @param {DocumentData} data An object that contains the fields and data to
* serialize as the document.
* @throws {Error} If the provided input is not a valid Firestore document.
* @returns {Promise.} A Promise that resolves with the
* write time of this create.
*
* @example
* ```
* let documentRef = firestore.collection('col').doc();
*
* documentRef.create({foo: 'bar'}).then((res) => {
* console.log(`Document created at ${res.updateTime}`);
* }).catch((err) => {
* console.log(`Failed to create document: ${err}`);
* });
* ```
*/
create(data: firestore.WithFieldValue): Promise;
/**
* Deletes the document referred to by this `DocumentReference`.
*
* A delete for a non-existing document is treated as a success (unless
* lastUptimeTime is provided).
*
* @param {Precondition=} precondition A precondition to enforce for this
* delete.
* @param {Timestamp=} precondition.lastUpdateTime If set, enforces that the
* document was last updated at lastUpdateTime. Fails the delete if the
* document was last updated at a different time.
* @param {boolean=} precondition.exists If set, enforces that the target
* document must or must not exist.
* @returns {Promise.} A Promise that resolves with the
* delete time.
*
* @example
* ```
* let documentRef = firestore.doc('col/doc');
*
* documentRef.delete().then(() => {
* console.log('Document successfully deleted.');
* });
* ```
*/
delete(precondition?: firestore.Precondition): Promise;
set(data: firestore.PartialWithFieldValue, options: firestore.SetOptions): Promise;
set(data: firestore.WithFieldValue): Promise;
/**
* Updates fields in the document referred to by this DocumentReference.
* If the document doesn't yet exist, the update fails and the returned
* Promise will be rejected.
*
* The update() method accepts either an object with field paths encoded as
* keys and field values encoded as values, or a variable number of arguments
* that alternate between field paths and field values.
*
* A Precondition restricting this update can be specified as the last
* argument.
*
* @param {UpdateData|string|FieldPath} dataOrField An object containing the
* fields and values with which to update the document or the path of the
* first field to update.
* @param {
* ...(*|string|FieldPath|Precondition)} preconditionOrValues An alternating
* list of field paths and values to update or a Precondition to restrict
* this update.
* @throws {Error} If the provided input is not valid Firestore data.
* @returns {Promise.} A Promise that resolves once the
* data has been successfully written to the backend.
*
* @example
* ```
* let documentRef = firestore.doc('col/doc');
*
* documentRef.update({foo: 'bar'}).then(res => {
* console.log(`Document updated at ${res.updateTime}`);
* });
* ```
*/
update(dataOrField: firestore.UpdateData | string | firestore.FieldPath, ...preconditionOrValues: Array): Promise;
/**
* Attaches a listener for DocumentSnapshot events.
*
* @param {documentSnapshotCallback} onNext A callback to be called every
* time a new `DocumentSnapshot` is available.
* @param {errorCallback=} onError A callback to be called if the listen fails
* or is cancelled. No further callbacks will occur. If unset, errors will be
* logged to the console.
*
* @returns {function()} An unsubscribe function that can be called to cancel
* the snapshot listener.
*
* @example
* ```
* let documentRef = firestore.doc('col/doc');
*
* let unsubscribe = documentRef.onSnapshot(documentSnapshot => {
* if (documentSnapshot.exists) {
* console.log(documentSnapshot.data());
* }
* }, err => {
* console.log(`Encountered error: ${err}`);
* });
*
* // Remove this listener.
* unsubscribe();
* ```
*/
onSnapshot(onNext: (snapshot: firestore.DocumentSnapshot) => void, onError?: (error: Error) => void): () => void;
/**
* Returns true if this `DocumentReference` is equal to the provided value.
*
* @param {*} other The value to compare against.
* @return {boolean} true if this `DocumentReference` is equal to the provided
* value.
*/
isEqual(other: firestore.DocumentReference): boolean;
/**
* Converts this DocumentReference to the Firestore Proto representation.
*
* @private
* @internal
*/
toProto(): api.IValue;
withConverter(converter: null): DocumentReference;
withConverter(converter: firestore.FirestoreDataConverter): DocumentReference;
}
/**
* A Query order-by field.
*
* @private
* @internal
* @class
*/
export declare class FieldOrder {
readonly field: FieldPath;
readonly direction: api.StructuredQuery.Direction;
/**
* @param field The name of a document field (member) on which to order query
* results.
* @param direction One of 'ASCENDING' (default) or 'DESCENDING' to
* set the ordering direction to ascending or descending, respectively.
*/
constructor(field: FieldPath, direction?: api.StructuredQuery.Direction);
/**
* Generates the proto representation for this field order.
* @private
* @internal
*/
toProto(): api.StructuredQuery.IOrder;
}
/**
* A field constraint for a Query where clause.
*
* @private
* @internal
* @class
*/
declare class FieldFilter {
private readonly serializer;
readonly field: FieldPath;
private readonly op;
private readonly value;
/**
* @param serializer The Firestore serializer
* @param field The path of the property value to compare.
* @param op A comparison operation.
* @param value The value to which to compare the field for inclusion in a
* query.
*/
constructor(serializer: Serializer, field: FieldPath, op: api.StructuredQuery.FieldFilter.Operator, value: unknown);
/**
* Returns whether this FieldFilter uses an equals comparison.
*
* @private
* @internal
*/
isInequalityFilter(): boolean;
/**
* Generates the proto representation for this field filter.
*
* @private
* @internal
*/
toProto(): api.StructuredQuery.IFilter;
isEqual(other: FieldFilter): boolean;
}
/**
* A QuerySnapshot contains zero or more
* [QueryDocumentSnapshot]{@link QueryDocumentSnapshot} objects
* representing the results of a query. The documents can be accessed as an
* array via the [documents]{@link QuerySnapshot#documents} property
* or enumerated using the [forEach]{@link QuerySnapshot#forEach}
* method. The number of documents can be determined via the
* [empty]{@link QuerySnapshot#empty} and
* [size]{@link QuerySnapshot#size} properties.
*
* @class QuerySnapshot
*/
export declare class QuerySnapshot implements firestore.QuerySnapshot {
private readonly _query;
private readonly _readTime;
private readonly _size;
private _materializedDocs;
private _materializedChanges;
private _docs;
private _changes;
/**
* @hideconstructor
*
* @param _query The originating query.
* @param _readTime The time when this query snapshot was obtained.
* @param _size The number of documents in the result set.
* @param docs A callback returning a sorted array of documents matching
* this query
* @param changes A callback returning a sorted array of document change
* events for this snapshot.
*/
constructor(_query: Query, _readTime: Timestamp, _size: number, docs: () => Array>, changes: () => Array>);
/**
* The query on which you called get() or onSnapshot() in order to get this
* QuerySnapshot.
*
* @type {Query}
* @name QuerySnapshot#query
* @readonly
*
* @example
* ```
* let query = firestore.collection('col').where('foo', '==', 'bar');
*
* query.limit(10).get().then(querySnapshot => {
* console.log(`Returned first batch of results`);
* let query = querySnapshot.query;
* return query.offset(10).get();
* }).then(() => {
* console.log(`Returned second batch of results`);
* });
* ```
*/
get query(): Query;
/**
* An array of all the documents in this QuerySnapshot.
*
* @type {Array.}
* @name QuerySnapshot#docs
* @readonly
*
* @example
* ```
* let query = firestore.collection('col').where('foo', '==', 'bar');
*
* query.get().then(querySnapshot => {
* let docs = querySnapshot.docs;
* for (let doc of docs) {
* console.log(`Document found at path: ${doc.ref.path}`);
* }
* });
* ```
*/
get docs(): Array>;
/**
* True if there are no documents in the QuerySnapshot.
*
* @type {boolean}
* @name QuerySnapshot#empty
* @readonly
*
* @example
* ```
* let query = firestore.collection('col').where('foo', '==', 'bar');
*
* query.get().then(querySnapshot => {
* if (querySnapshot.empty) {
* console.log('No documents found.');
* }
* });
* ```
*/
get empty(): boolean;
/**
* The number of documents in the QuerySnapshot.
*
* @type {number}
* @name QuerySnapshot#size
* @readonly
*
* @example
* ```
* let query = firestore.collection('col').where('foo', '==', 'bar');
*
* query.get().then(querySnapshot => {
* console.log(`Found ${querySnapshot.size} documents.`);
* });
* ```
*/
get size(): number;
/**
* The time this query snapshot was obtained.
*
* @type {Timestamp}
* @name QuerySnapshot#readTime
*
* @example
* ```
* let query = firestore.collection('col').where('foo', '==', 'bar');
*
* query.get().then((querySnapshot) => {
* let readTime = querySnapshot.readTime;
* console.log(`Query results returned at '${readTime.toDate()}'`);
* });
* ```
*/
get readTime(): Timestamp;
/**
* Returns an array of the documents changes since the last snapshot. If
* this is the first snapshot, all documents will be in the list as added
* changes.
*
* @return {Array.}
*
* @example
* ```
* let query = firestore.collection('col').where('foo', '==', 'bar');
*
* query.onSnapshot(querySnapshot => {
* let changes = querySnapshot.docChanges();
* for (let change of changes) {
* console.log(`A document was ${change.type}.`);
* }
* });
* ```
*/
docChanges(): Array>;
/**
* Enumerates all of the documents in the QuerySnapshot. This is a convenience
* method for running the same callback on each {@link QueryDocumentSnapshot}
* that is returned.
*
* @param {function} callback A callback to be called with a
* [QueryDocumentSnapshot]{@link QueryDocumentSnapshot} for each document in
* the snapshot.
* @param {*=} thisArg The `this` binding for the callback..
*
* @example
* ```
* let query = firestore.collection('col').where('foo', '==', 'bar');
*
* query.get().then(querySnapshot => {
* querySnapshot.forEach(documentSnapshot => {
* console.log(`Document found at path: ${documentSnapshot.ref.path}`);
* });
* });
* ```
*/
forEach(callback: (result: firestore.QueryDocumentSnapshot) => void, thisArg?: unknown): void;
/**
* Returns true if the document data in this `QuerySnapshot` is equal to the
* provided value.
*
* @param {*} other The value to compare against.
* @return {boolean} true if this `QuerySnapshot` is equal to the provided
* value.
*/
isEqual(other: firestore.QuerySnapshot): boolean;
}
/** Internal representation of a query cursor before serialization. */
interface QueryCursor {
before: boolean;
values: api.IValue[];
}
/*!
* Denotes whether a provided limit is applied to the beginning or the end of
* the result set.
*/
declare enum LimitType {
First = 0,
Last = 1
}
/**
* Internal class representing custom Query options.
*
* These options are immutable. Modified options can be created using `with()`.
* @private
* @internal
*/
export declare class QueryOptions {
readonly parentPath: ResourcePath;
readonly collectionId: string;
readonly converter: firestore.FirestoreDataConverter;
readonly allDescendants: boolean;
readonly fieldFilters: FieldFilter[];
readonly fieldOrders: FieldOrder[];
readonly startAt?: QueryCursor | undefined;
readonly endAt?: QueryCursor | undefined;
readonly limit?: number | undefined;
readonly limitType?: LimitType | undefined;
readonly offset?: number | undefined;
readonly projection?: api.StructuredQuery.IProjection | undefined;
readonly kindless: boolean;
readonly requireConsistency: boolean;
constructor(parentPath: ResourcePath, collectionId: string, converter: firestore.FirestoreDataConverter, allDescendants: boolean, fieldFilters: FieldFilter[], fieldOrders: FieldOrder[], startAt?: QueryCursor | undefined, endAt?: QueryCursor | undefined, limit?: number | undefined, limitType?: LimitType | undefined, offset?: number | undefined, projection?: api.StructuredQuery.IProjection | undefined, kindless?: boolean, requireConsistency?: boolean);
/**
* Returns query options for a collection group query.
* @private
* @internal
*/
static forCollectionGroupQuery(collectionId: string, converter?: firestore.FirestoreDataConverter): QueryOptions;
/**
* Returns query options for a single-collection query.
* @private
* @internal
*/
static forCollectionQuery(collectionRef: ResourcePath, converter?: firestore.FirestoreDataConverter): QueryOptions;
/**
* Returns query options for a query that fetches all descendants under the
* specified reference.
*
* @private
* @internal
*/
static forKindlessAllDescendants(parent: ResourcePath, id: string, requireConsistency?: boolean): QueryOptions;
/**
* Returns the union of the current and the provided options.
* @private
* @internal
*/
with(settings: Partial, 'converter'>>): QueryOptions;
withConverter(converter: firestore.FirestoreDataConverter): QueryOptions;
hasFieldOrders(): boolean;
isEqual(other: QueryOptions): boolean;
private fieldFiltersEqual;
}
/**
* A Query refers to a query which you can read or stream from. You can also
* construct refined Query objects by adding filters and ordering.
*
* @class Query
*/
export declare class Query implements firestore.Query {
readonly _firestore: Firestore;
protected readonly _queryOptions: QueryOptions;
private readonly _serializer;
protected readonly _allowUndefined: boolean;
/**
* @hideconstructor
*
* @param _firestore The Firestore Database client.
* @param _queryOptions Options that define the query.
*/
constructor(_firestore: Firestore, _queryOptions: QueryOptions);
/**
* Extracts field values from the DocumentSnapshot based on the provided
* field order.
*
* @private
* @internal
* @param documentSnapshot The document to extract the fields from.
* @param fieldOrders The field order that defines what fields we should
* extract.
* @return {Array.<*>} The field values to use.
* @private
* @internal
*/
static _extractFieldValues(documentSnapshot: DocumentSnapshot, fieldOrders: FieldOrder[]): unknown[];
/**
* The [Firestore]{@link Firestore} instance for the Firestore
* database (useful for performing transactions, etc.).
*
* @type {Firestore}
* @name Query#firestore
* @readonly
*
* @example
* ```
* let collectionRef = firestore.collection('col');
*
* collectionRef.add({foo: 'bar'}).then(documentReference => {
* let firestore = documentReference.firestore;
* console.log(`Root location for document is ${firestore.formattedName}`);
* });
* ```
*/
get firestore(): Firestore;
/**
* Creates and returns a new [Query]{@link Query} with the additional filter
* that documents must contain the specified field and that its value should
* satisfy the relation constraint provided.
*
* Returns a new Query that constrains the value of a Document property.
*
* This function returns a new (immutable) instance of the Query (rather than
* modify the existing instance) to impose the filter.
*
* @param {string|FieldPath} fieldPath The name of a property value to compare.
* @param {string} opStr A comparison operation in the form of a string
* (e.g., "<").
* @param {*} value The value to which to compare the field for inclusion in
* a query.
* @returns {Query} The created Query.
*
* @example
* ```
* let collectionRef = firestore.collection('col');
*
* collectionRef.where('foo', '==', 'bar').get().then(querySnapshot => {
* querySnapshot.forEach(documentSnapshot => {
* console.log(`Found document at ${documentSnapshot.ref.path}`);
* });
* });
* ```
*/
where(fieldPath: string | firestore.FieldPath, opStr: firestore.WhereFilterOp, value: unknown): Query;
/**
* Creates and returns a new [Query]{@link Query} instance that applies a
* field mask to the result and returns only the specified subset of fields.
* You can specify a list of field paths to return, or use an empty list to
* only return the references of matching documents.
*
* Queries that contain field masks cannot be listened to via `onSnapshot()`
* listeners.
*
* This function returns a new (immutable) instance of the Query (rather than
* modify the existing instance) to impose the field mask.
*
* @param {...(string|FieldPath)} fieldPaths The field paths to return.
* @returns {Query} The created Query.
*
* @example
* ```
* let collectionRef = firestore.collection('col');
* let documentRef = collectionRef.doc('doc');
*
* return documentRef.set({x:10, y:5}).then(() => {
* return collectionRef.where('x', '>', 5).select('y').get();
* }).then((res) => {
* console.log(`y is ${res.docs[0].get('y')}.`);
* });
* ```
*/
select(...fieldPaths: Array): Query;
/**
* Creates and returns a new [Query]{@link Query} that's additionally sorted
* by the specified field, optionally in descending order instead of
* ascending.
*
* This function returns a new (immutable) instance of the Query (rather than
* modify the existing instance) to impose the field mask.
*
* @param {string|FieldPath} fieldPath The field to sort by.
* @param {string=} directionStr Optional direction to sort by ('asc' or
* 'desc'). If not specified, order will be ascending.
* @returns {Query} The created Query.
*
* @example
* ```
* let query = firestore.collection('col').where('foo', '>', 42);
*
* query.orderBy('foo', 'desc').get().then(querySnapshot => {
* querySnapshot.forEach(documentSnapshot => {
* console.log(`Found document at ${documentSnapshot.ref.path}`);
* });
* });
* ```
*/
orderBy(fieldPath: string | firestore.FieldPath, directionStr?: firestore.OrderByDirection): Query;
/**
* Creates and returns a new [Query]{@link Query} that only returns the
* first matching documents.
*
* This function returns a new (immutable) instance of the Query (rather than
* modify the existing instance) to impose the limit.
*
* @param {number} limit The maximum number of items to return.
* @returns {Query} The created Query.
*
* @example
* ```
* let query = firestore.collection('col').where('foo', '>', 42);
*
* query.limit(1).get().then(querySnapshot => {
* querySnapshot.forEach(documentSnapshot => {
* console.log(`Found document at ${documentSnapshot.ref.path}`);
* });
* });
* ```
*/
limit(limit: number): Query;
/**
* Creates and returns a new [Query]{@link Query} that only returns the
* last matching documents.
*
* You must specify at least one orderBy clause for limitToLast queries,
* otherwise an exception will be thrown during execution.
*
* Results for limitToLast queries cannot be streamed via the `stream()` API.
*
* @param limit The maximum number of items to return.
* @return The created Query.
*
* @example
* ```
* let query = firestore.collection('col').where('foo', '>', 42);
*
* query.limitToLast(1).get().then(querySnapshot => {
* querySnapshot.forEach(documentSnapshot => {
* console.log(`Last matching document is ${documentSnapshot.ref.path}`);
* });
* });
* ```
*/
limitToLast(limit: number): Query;
/**
* Specifies the offset of the returned results.
*
* This function returns a new (immutable) instance of the
* [Query]{@link Query} (rather than modify the existing instance)
* to impose the offset.
*
* @param {number} offset The offset to apply to the Query results
* @returns {Query} The created Query.
*
* @example
* ```
* let query = firestore.collection('col').where('foo', '>', 42);
*
* query.limit(10).offset(20).get().then(querySnapshot => {
* querySnapshot.forEach(documentSnapshot => {
* console.log(`Found document at ${documentSnapshot.ref.path}`);
* });
* });
* ```
*/
offset(offset: number): Query;
/**
* Returns true if this `Query` is equal to the provided value.
*
* @param {*} other The value to compare against.
* @return {boolean} true if this `Query` is equal to the provided value.
*/
isEqual(other: firestore.Query): boolean;
/**
* Computes the backend ordering semantics for DocumentSnapshot cursors.
*
* @private
* @internal
* @param cursorValuesOrDocumentSnapshot The snapshot of the document or the
* set of field values to use as the boundary.
* @returns The implicit ordering semantics.
*/
private createImplicitOrderBy;
/**
* Builds a Firestore 'Position' proto message.
*
* @private
* @internal
* @param {Array.} fieldOrders The field orders to use for this
* cursor.
* @param {Array.} cursorValuesOrDocumentSnapshot The
* snapshot of the document or the set of field values to use as the boundary.
* @param before Whether the query boundary lies just before or after the
* provided data.
* @returns {Object} The proto message.
*/
private createCursor;
/**
* Validates that a value used with FieldValue.documentId() is either a
* string or a DocumentReference that is part of the query`s result set.
* Throws a validation error or returns a DocumentReference that can
* directly be used in the Query.
*
* @param val The value to validate.
* @throws If the value cannot be used for this query.
* @return If valid, returns a DocumentReference that can be used with the
* query.
* @private
* @internal
*/
private validateReference;
/**
* Creates and returns a new [Query]{@link Query} that starts at the provided
* set of field values relative to the order of the query. The order of the
* provided values must match the order of the order by clauses of the query.
*
* @param {...*|DocumentSnapshot} fieldValuesOrDocumentSnapshot The snapshot
* of the document the query results should start at or the field values to
* start this query at, in order of the query's order by.
* @returns {Query} A query with the new starting point.
*
* @example
* ```
* let query = firestore.collection('col');
*
* query.orderBy('foo').startAt(42).get().then(querySnapshot => {
* querySnapshot.forEach(documentSnapshot => {
* console.log(`Found document at ${documentSnapshot.ref.path}`);
* });
* });
* ```
*/
startAt(...fieldValuesOrDocumentSnapshot: Array | unknown>): Query;
/**
* Creates and returns a new [Query]{@link Query} that starts after the
* provided set of field values relative to the order of the query. The order
* of the provided values must match the order of the order by clauses of the
* query.
*
* @param {...*|DocumentSnapshot} fieldValuesOrDocumentSnapshot The snapshot
* of the document the query results should start after or the field values to
* start this query after, in order of the query's order by.
* @returns {Query} A query with the new starting point.
*
* @example
* ```
* let query = firestore.collection('col');
*
* query.orderBy('foo').startAfter(42).get().then(querySnapshot => {
* querySnapshot.forEach(documentSnapshot => {
* console.log(`Found document at ${documentSnapshot.ref.path}`);
* });
* });
* ```
*/
startAfter(...fieldValuesOrDocumentSnapshot: Array | unknown>): Query;
/**
* Creates and returns a new [Query]{@link Query} that ends before the set of
* field values relative to the order of the query. The order of the provided
* values must match the order of the order by clauses of the query.
*
* @param {...*|DocumentSnapshot} fieldValuesOrDocumentSnapshot The snapshot
* of the document the query results should end before or the field values to
* end this query before, in order of the query's order by.
* @returns {Query} A query with the new ending point.
*
* @example
* ```
* let query = firestore.collection('col');
*
* query.orderBy('foo').endBefore(42).get().then(querySnapshot => {
* querySnapshot.forEach(documentSnapshot => {
* console.log(`Found document at ${documentSnapshot.ref.path}`);
* });
* });
* ```
*/
endBefore(...fieldValuesOrDocumentSnapshot: Array | unknown>): Query;
/**
* Creates and returns a new [Query]{@link Query} that ends at the provided
* set of field values relative to the order of the query. The order of the
* provided values must match the order of the order by clauses of the query.
*
* @param {...*|DocumentSnapshot} fieldValuesOrDocumentSnapshot The snapshot
* of the document the query results should end at or the field values to end
* this query at, in order of the query's order by.
* @returns {Query} A query with the new ending point.
*
* @example
* ```
* let query = firestore.collection('col');
*
* query.orderBy('foo').endAt(42).get().then(querySnapshot => {
* querySnapshot.forEach(documentSnapshot => {
* console.log(`Found document at ${documentSnapshot.ref.path}`);
* });
* });
* ```
*/
endAt(...fieldValuesOrDocumentSnapshot: Array | unknown>): Query;
/**
* Executes the query and returns the results as a
* [QuerySnapshot]{@link QuerySnapshot}.
*
* @returns {Promise.} A Promise that resolves with the results
* of the Query.
*
* @example
* ```
* let query = firestore.collection('col').where('foo', '==', 'bar');
*
* query.get().then(querySnapshot => {
* querySnapshot.forEach(documentSnapshot => {
* console.log(`Found document at ${documentSnapshot.ref.path}`);
* });
* });
* ```
*/
get(): Promise>;
/**
* Internal get() method that accepts an optional transaction id.
*
* @private
* @internal
* @param {bytes=} transactionId A transaction ID.
*/
_get(transactionId?: Uint8Array): Promise>;
/**
* Executes the query and streams the results as
* [QueryDocumentSnapshots]{@link QueryDocumentSnapshot}.
*
* @returns {Stream.} A stream of
* QueryDocumentSnapshots.
*
* @example
* ```
* let query = firestore.collection('col').where('foo', '==', 'bar');
*
* let count = 0;
*
* query.stream().on('data', (documentSnapshot) => {
* console.log(`Found document with name '${documentSnapshot.id}'`);
* ++count;
* }).on('end', () => {
* console.log(`Total count is ${count}`);
* });
* ```
*/
stream(): NodeJS.ReadableStream;
/**
* Converts a QueryCursor to its proto representation.
*
* @param cursor The original cursor value
* @private
* @internal
*/
private toCursor;
/**
* Internal method for serializing a query to its RunQuery proto
* representation with an optional transaction id or read time.
*
* @param transactionIdOrReadTime A transaction ID or the read time at which
* to execute the query.
* @private
* @internal
* @returns Serialized JSON for the query.
*/
toProto(transactionIdOrReadTime?: Uint8Array | Timestamp): api.IRunQueryRequest;
/**
* Converts current Query to an IBundledQuery.
*
* @private
* @internal
*/
_toBundledQuery(): protos.firestore.IBundledQuery;
private toStructuredQuery;
/**
* Internal streaming method that accepts an optional transaction ID.
*
* @param transactionId A transaction ID.
* @private
* @internal
* @returns A stream of document results.
*/
_stream(transactionId?: Uint8Array): NodeJS.ReadableStream;
/**
* Attaches a listener for QuerySnapshot events.
*
* @param {querySnapshotCallback} onNext A callback to be called every time
* a new [QuerySnapshot]{@link QuerySnapshot} is available.
* @param {errorCallback=} onError A callback to be called if the listen
* fails or is cancelled. No further callbacks will occur.
*
* @returns {function()} An unsubscribe function that can be called to cancel
* the snapshot listener.
*
* @example
* ```
* let query = firestore.collection('col').where('foo', '==', 'bar');
*
* let unsubscribe = query.onSnapshot(querySnapshot => {
* console.log(`Received query snapshot of size ${querySnapshot.size}`);
* }, err => {
* console.log(`Encountered error: ${err}`);
* });
*
* // Remove this listener.
* unsubscribe();
* ```
*/
onSnapshot(onNext: (snapshot: firestore.QuerySnapshot) => void, onError?: (error: Error) => void): () => void;
/**
* Returns a function that can be used to sort QueryDocumentSnapshots
* according to the sort criteria of this query.
*
* @private
* @internal
*/
comparator(): (s1: QueryDocumentSnapshot, s2: QueryDocumentSnapshot) => number;
withConverter(converter: null): Query;
withConverter(converter: firestore.FirestoreDataConverter): Query;
}
/**
* A CollectionReference object can be used for adding documents, getting
* document references, and querying for documents (using the methods
* inherited from [Query]{@link Query}).
*
* @class CollectionReference
* @extends Query
*/
export declare class CollectionReference extends Query implements firestore.CollectionReference {
/**
* @hideconstructor
*
* @param firestore The Firestore Database client.
* @param path The Path of this collection.
*/
constructor(firestore: Firestore, path: ResourcePath, converter?: firestore.FirestoreDataConverter);
/**
* Returns a resource path for this collection.
* @private
* @internal
*/
get _resourcePath(): ResourcePath;
/**
* The last path element of the referenced collection.
*
* @type {string}
* @name CollectionReference#id
* @readonly
*
* @example
* ```
* let collectionRef = firestore.collection('col/doc/subcollection');
* console.log(`ID of the subcollection: ${collectionRef.id}`);
* ```
*/
get id(): string;
/**
* A reference to the containing Document if this is a subcollection, else
* null.
*
* @type {DocumentReference|null}
* @name CollectionReference#parent
* @readonly
*
* @example
* ```
* let collectionRef = firestore.collection('col/doc/subcollection');
* let documentRef = collectionRef.parent;
* console.log(`Parent name: ${documentRef.path}`);
* ```
*/
get parent(): DocumentReference | null;
/**
* A string representing the path of the referenced collection (relative
* to the root of the database).
*
* @type {string}
* @name CollectionReference#path
* @readonly
*
* @example
* ```
* let collectionRef = firestore.collection('col/doc/subcollection');
* console.log(`Path of the subcollection: ${collectionRef.path}`);
* ```
*/
get path(): string;
/**
* Retrieves the list of documents in this collection.
*
* The document references returned may include references to "missing
* documents", i.e. document locations that have no document present but
* which contain subcollections with documents. Attempting to read such a
* document reference (e.g. via `.get()` or `.onSnapshot()`) will return a
* `DocumentSnapshot` whose `.exists` property is false.
*
* @return {Promise} The list of documents in this
* collection.
*
* @example
* ```
* let collectionRef = firestore.collection('col');
*
* return collectionRef.listDocuments().then(documentRefs => {
* return firestore.getAll(...documentRefs);
* }).then(documentSnapshots => {
* for (let documentSnapshot of documentSnapshots) {
* if (documentSnapshot.exists) {
* console.log(`Found document with data: ${documentSnapshot.id}`);
* } else {
* console.log(`Found missing document: ${documentSnapshot.id}`);
* }
* }
* });
* ```
*/
listDocuments(): Promise>>;
doc(): DocumentReference;
doc(documentPath: string): DocumentReference;
/**
* Add a new document to this collection with the specified data, assigning
* it a document ID automatically.
*
* @param {DocumentData} data An Object containing the data for the new
* document.
* @throws {Error} If the provided input is not a valid Firestore document.
* @returns {Promise.} A Promise resolved with a
* [DocumentReference]{@link DocumentReference} pointing to the
* newly created document.
*
* @example
* ```
* let collectionRef = firestore.collection('col');
* collectionRef.add({foo: 'bar'}).then(documentReference => {
* console.log(`Added document with name: ${documentReference.id}`);
* });
* ```
*/
add(data: firestore.WithFieldValue): Promise>;
/**
* Returns true if this `CollectionReference` is equal to the provided value.
*
* @param {*} other The value to compare against.
* @return {boolean} true if this `CollectionReference` is equal to the
* provided value.
*/
isEqual(other: firestore.CollectionReference): boolean;
withConverter(converter: null): CollectionReference;
withConverter(converter: firestore.FirestoreDataConverter): CollectionReference;
}
/**
* Validates the input string as a field order direction.
*
* @private
* @internal
* @param arg The argument name or argument index (for varargs methods).
* @param op Order direction to validate.
* @throws when the direction is invalid
* @return a validated input value, which may be different from the provided
* value.
*/
export declare function validateQueryOrder(arg: string, op: unknown): firestore.OrderByDirection | undefined;
/**
* Validates the input string as a field comparison operator.
*
* @private
* @internal
* @param arg The argument name or argument index (for varargs methods).
* @param op Field comparison operator to validate.
* @param fieldValue Value that is used in the filter.
* @throws when the comparison operation is invalid
* @return a validated input value, which may be different from the provided
* value.
*/
export declare function validateQueryOperator(arg: string | number, op: unknown, fieldValue: unknown): firestore.WhereFilterOp;
/**
* Validates that 'value' is a DocumentReference.
*
* @private
* @internal
* @param arg The argument name or argument index (for varargs methods).
* @param value The argument to validate.
* @return the DocumentReference if valid
*/
export declare function validateDocumentReference(arg: string | number, value: unknown): DocumentReference;
export {};