firestore.js.md

firestore

Interface to Google Cloud Firestore Database using high-level interface objects. All Firestore document I/O is performed in the security context of the logged-in user and the specific app you have built.

It is important to understand the structure of a Firestore because it is not a file tree. A single document may contain a set of properties, but not another document. A document may also contain collections. A collection is a set of documents, but not properties. Therefore a document is always a member of a collection, and a collection is a member of a document. You can describe a specific path to a document, and it must always be an even number of path components since the document parent will be a collection, except for the root document of the Firestore. If you follow only this interface for access to the Firestore, you will not have direct access to the root document.

See

• https://firebase.google.com/docs/firestore/manage-data/structure-data
• https://firebase.google.com/docs/firestore/data-model

Once a firestore object is defined, all document I/O is performed relative to (constrained to) this top-level document, so your code can't wander astray into other parts of the Firestore where you don't belong. Each API starts with a docPath parameter, and if null will refer to the top-level doc, into which you can read and write fields. If you want to create or work with documents, the docPath parameter must have an even number of path segments, e.g. "/maps/chicago" in which case the collection "maps" will be automatically created if it doesn't exist.

After initialization three objects are available from this module:

• .doc - A Firestore subtree (/users//) for the signed-in user's documents in Firestore

• .app - A Firestore subtree (/apps//) for the app being used, accessible to all users

• .public - A Firestore subtree (/apps/public/) that any user or app and read or write to

• firestore

  • initialize(userid, projectId) ⏏
    • ~firestoreDoc
      • new firestoreDoc(rootCollectionName, topLevelDocument)
      • .about(docPath) ⇒ Promise.<DocumentSnapshot>
      • .read(docPath) ⇒ Promise.<object>
      • .write(docPath, [contents]) ⇒ Promise.<DocumentReference>
      • .merge(docPath, [contents]) ⇒ Promise.<DocumentReference>
      • .update(docPath, [contents]) ⇒ Promise.<DocumentReference>
      • .delete(docPath) ⇒ Promise.<void>
      • .query(collectionPath, fieldName, fieldMatch, [matchOperator]) ⇒ Promise.<QuerySnapshot>
      • .field(docPath, fieldName) ⇒ Promise.<any>
      • .union(docPath, arrayName, newValue) ⇒ Promise.<array>
      • .splice(docPath, arrayName, newValue) ⇒ Promise.<array>
      • .push(docPath, arrayName, newValue) ⇒ Promise.<array>
      • .pop(docPath, arrayName) ⇒ Promise.<(string|number|object)>

initialize(userid, projectId) ⏏

Firestore interfaces are defined when your app starts:

• .doc - A Firestore subtree (/users/userid/) for the signed-in user's documents in Firestore
• .app - A Firestore subtree (/apps/projectId/) for the app being used, accessible to all users
• .public - A Firestore subtree (/apps/public/) that any user or app and read or write to

Kind: Exported function

Param	Type	Description
userid	string	The Firebase assigned userId from authentication process
projectId	string	Unique string for this application, typically the Firebase projectId

initialize~firestoreDoc

Kind: inner class of initialize

• ~firestoreDoc
  • new firestoreDoc(rootCollectionName, topLevelDocument)
  • .about(docPath) ⇒ Promise.<DocumentSnapshot>
  • .read(docPath) ⇒ Promise.<object>
  • .write(docPath, [contents]) ⇒ Promise.<DocumentReference>
  • .merge(docPath, [contents]) ⇒ Promise.<DocumentReference>
  • .update(docPath, [contents]) ⇒ Promise.<DocumentReference>
  • .delete(docPath) ⇒ Promise.<void>
  • .query(collectionPath, fieldName, fieldMatch, [matchOperator]) ⇒ Promise.<QuerySnapshot>
  • .field(docPath, fieldName) ⇒ Promise.<any>
  • .union(docPath, arrayName, newValue) ⇒ Promise.<array>
  • .splice(docPath, arrayName, newValue) ⇒ Promise.<array>
  • .push(docPath, arrayName, newValue) ⇒ Promise.<array>
  • .pop(docPath, arrayName) ⇒ Promise.<(string|number|object)>

new firestoreDoc(rootCollectionName, topLevelDocument)

Create a top-level Firestore db/collection/doc/, into which you can segment your Firestore.

Param	Type	Description
rootCollectionName	string	Top level segmentation of your Firestore, e.g. "users"
topLevelDocument	string	A specific name (i.e. constraint) for this document tree, e.g. userId

firestoreDoc.about(docPath) ⇒ Promise.<DocumentSnapshot>

Gets a DocumentSnapshot for the Firestore document which contains meta information and functions to get data, test existence, etc.

Kind: instance method of firestoreDoc
Returns: Promise.<DocumentSnapshot> - An object which can be used to get further information and data about the document: .exists, .id, .metadata, .get(), .data(), .isEqual()
See: DocumentSnapshot

Param	Type	Description
docPath	string	Relative path to a Firebase document within the root collection

firestoreDoc.read(docPath) ⇒ Promise.<object>

Reads the Firestore document at the requested path and returns an object representing the content.

Kind: instance method of firestoreDoc
Returns: Promise.<object> - The contents of the requested document

Param	Type	Description
docPath	string	Path to a Firebase document

firestoreDoc.write(docPath, [contents]) ⇒ Promise.<DocumentReference>

Creates a new document in the Firestore at the requested path, else updates an existing document if it already exists, overwriting all fields.

Kind: instance method of firestoreDoc
Returns: Promise.<DocumentReference> - DocumentReference for the docPath
See: https://firebase.google.com/docs/reference/node/firebase.firestore.DocumentSnapshot

Param	Type	Description
docPath	string	Path to a Firebase document
[contents]	object	Content to write into new document, or merge into existing document

firestoreDoc.merge(docPath, [contents]) ⇒ Promise.<DocumentReference>

Creates a new document in the Firestore at the requested path, else updates an existing document if it already exists, merging all fields.

Kind: instance method of firestoreDoc
Returns: Promise.<DocumentReference> - DocumentReference for the docPath
See: https://firebase.google.com/docs/reference/node/firebase.firestore.DocumentSnapshot

Param	Type	Description
docPath	string	Path to a Firebase document
[contents]	object	Content to write into new document, or merge into existing document

firestoreDoc.update(docPath, [contents]) ⇒ Promise.<DocumentReference>

Updates an existing document in the Firestore at the requested path with the given contents. Like merge() except it will fail if the document does not exist.

Kind: instance method of firestoreDoc
Returns: Promise.<DocumentReference> - DocumentReference for the docPath
See: https://firebase.google.com/docs/reference/node/firebase.firestore.DocumentSnapshot

Param	Type	Description
docPath	string	Path to a Firebase document
[contents]	object	Content to write into new document, or merge into existing document

firestoreDoc.delete(docPath) ⇒ Promise.<void>

Deletes the Firestore document at the given path.

Kind: instance method of firestoreDoc
Returns: Promise.<void> - Returns a promise that resolves once the document is deleted
See: DocumentReference delete()

Param	Type	Description
docPath	string	Path to a Firebase document

firestoreDoc.query(collectionPath, fieldName, fieldMatch, [matchOperator]) ⇒ Promise.<QuerySnapshot>

Queries a collection to find a match for a specific field name with optional matching operator.

Kind: instance method of firestoreDoc
See

• Query where()
• QuerySnapshot

Param	Type	Default	Description
collectionPath	string		The path to a collection, cannot be blank
fieldName	string		The name of a document field to search against all of the collection documents
fieldMatch	string		The value of the fieldName to match against
[matchOperator]	string	"=="	Optional comparison operator, defaults to "=="

firestoreDoc.field(docPath, fieldName) ⇒ Promise.<any>

Gets the value of a specified field within a Firestore document.

Kind: instance method of firestoreDoc
Returns: Promise.<any> - The data at the specified field location or undefined if no such field exists in the document
See: DocumentSnapshot get()

Param	Type	Description
docPath	string	Path to a Firebase document
fieldName	string	The name of a top-level field within the Firebase document

firestoreDoc.union(docPath, arrayName, newValue) ⇒ Promise.<array>

This function will insert a new value, or multiple values, onto an array field of the Firestore document. Each specified element that doesn't already exist in the array will be added to the end. If the field being modified is not already an array it will be overwritten with an array containing exactly the specified elements.

Kind: instance method of firestoreDoc
Returns: Promise.<array> - - The array after the new value is inserted
See: FieldValue union

Param	Type	Description
docPath	string	Path to a Firebase document
arrayName	string	The name of the array field to be updated
newValue	*	The new value to push on the array field

firestoreDoc.splice(docPath, arrayName, newValue) ⇒ Promise.<array>

This function will remove a value, or multiple values, from an array field of the Firestore document.

Kind: instance method of firestoreDoc
Returns: Promise.<array> - - The array after the value is removed
See: FieldValue remove

Param	Type	Description
docPath	string	Path to a Firebase document
arrayName	string	The name of the array field to be updated
newValue	*	The new value to push on the array field

firestoreDoc.push(docPath, arrayName, newValue) ⇒ Promise.<array>

This function will push a new value onto the end of an array field of the Firestore document.

Kind: instance method of firestoreDoc
Returns: Promise.<array> - The updated array field

Param	Type	Description
docPath	string	Path to a Firebase document
arrayName	string	The name of the array field to be updated
newValue	*	The new value to push on the array field

firestoreDoc.pop(docPath, arrayName) ⇒ Promise.<(string|number|object)>

This function will pop a value from the end of an array field of the Firestore document.

Kind: instance method of firestoreDoc
Returns: Promise.<(string|number|object)> - The popped value

Param	Type	Description
docPath	string	Path to a Firebase document
arrayName	string	The name of the array field to be updated