electron-firebase

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

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.

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

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

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

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

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

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()

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

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()

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

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

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

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