@proteansoftware/capacitor-firestore

Capacitor Plugin for Native Firestore

Install

npm install @proteansoftware/capacitor-firestore
npx cap sync

API

• getPendingActions()
• initializeFirestore(...)
• signInWithCustomToken(...)
• signOut()
• getDocument(...)
• updateDocument(...)
• setDocument(...)
• deleteDocument(...)
• addDocument(...)
• addDocumentSnapshotListener(...)
• getCollection(...)
• addCollectionSnapshotListener(...)
• removeSnapshotListener(...)
• clearAllSnapshotListeners()
• enableNetwork()
• disableNetwork()
• Interfaces
• Type Aliases

getPendingActions()

getPendingActions() => Promise<PendingActions>

Gets the number of pending write actions (i.e. setDocument, addDocument, updateDocument, deleteDocument)

Returns: Promise<PendingActions>

---

initializeFirestore(...)

initializeFirestore(options: FirestoreConfig) => Promise<void>

Configure the firestore instance with new configuration options.

Param	Type
options	FirestoreConfig

---

signInWithCustomToken(...)

signInWithCustomToken(options: CustomToken) => Promise<void>

Login to firestore using a customer JWT token.

Param	Type
options	CustomToken

---

signOut()

signOut() => Promise<void>

Sign out of firestore.

---

getDocument(...)

getDocument<T>(options: DocumnentQuery) => Promise<DocumentSnapshot<T>>

Reads the document referred to by this DocumnentQuery

Param	Type
options	DocumnentQuery

Returns: Promise<DocumentSnapshot<T>>

---

updateDocument(...)

updateDocument<T>(options: UpdateDocument<T>) => Promise<void>

Updates fields in the document referred to by the specified DocumnentQuery. The update will fail if applied to a document that does not exist.

Param	Type
options	UpdateDocument<T>

---

setDocument(...)

setDocument<T>(options: SetDocument<T>) => Promise<void>

Writes to the document referred to by the specified DocumnentQuery. If the document does not yet exist, it will be created. If you provide merge or mergeFields, the provided data can be merged into an existing document.

Param	Type
options	SetDocument<T>

---

deleteDocument(...)

deleteDocument(options: DocumnentQuery) => Promise<void>

Deletes the document referred to by the specified DocumnentQuery.

Param	Type
options	DocumnentQuery

---

addDocument(...)

addDocument<T>(options: AddDocument<T>) => Promise<DocumentReference>

Add a new document to specified CollectionQuery with the given data, assigning it a document ID automatically.

Param	Type
options	AddDocument<T>

Returns: Promise<DocumentReference>

---

addDocumentSnapshotListener(...)

addDocumentSnapshotListener<T>(options: DocumnentQuery, callback: DocumentSnapshotCallback<T>) => Promise<CallbackId>

Listen for snapshot changes on a document.

Param	Type
options	DocumnentQuery
callback	DocumentSnapshotCallback<T>

Returns: Promise<string>

---

getCollection(...)

getCollection<T>(options: CollectionQuery) => Promise<CollectionSnapshot<T>>

Executes the query and returns the results as a CollectionSnapshot

Param	Type
options	CollectionQuery

Returns: Promise<CollectionSnapshot<T>>

---

addCollectionSnapshotListener(...)

addCollectionSnapshotListener<T>(options: CollectionQuery, callback: CollectionSnapshotCallback<T>) => Promise<CallbackId>

Listen for snapshot changes on a collection.

Param	Type
options	CollectionQuery
callback	CollectionSnapshotCallback<T>

Returns: Promise<string>

---

removeSnapshotListener(...)

removeSnapshotListener(options: RemoveSnapshotListener) => Promise<void>

Stop listening for snapshot changes on a document or collection.

Param	Type
options	RemoveSnapshotListener

---

clearAllSnapshotListeners()

clearAllSnapshotListeners() => Promise<void>

Remove all active snapshot listners

---

enableNetwork()

enableNetwork() => Promise<void>

Re-enables use of the network for this Firestore instance after a prior call to {@link disableNetwork}.

---

disableNetwork()

disableNetwork() => Promise<void>

Disables network usage for this instance. It can be re-enabled via {@link enableNetwork}. While the network is disabled, any snapshot listeners, {@link getDocument} or {@link getCollection} calls will return results from cache, and any write operations will be queued until the network is restored.

---

Interfaces

PendingActions

Prop	Type
count	number

FirestoreConfig

Prop	Type	Description	Since
projectId	string	Set the GCP/Firebase project id	1.0.0
applicationId	string	Set the Firebase application id	1.0.0
apiKey	string	Set the Firebase api key	1.0.0

CustomToken

Prop	Type
token	string

DocumentSnapshot

Prop	Type	Description	Since
data	T | null	The fields of the document or null if the document doesn't exist.	1.0.0

DocumnentQuery

Prop	Type	Description
reference	string	A reference to the document/collection

UpdateDocument

Prop	Type	Description
data	Partial<T>	An object containing the fields and values with which to update the document. Fields can contain dots to reference nested fields within the document

SetDocument

Prop	Type	Description
data	T	A map of the fields and values for the document.
merge	boolean	Changes the behavior of a setDocument() call to only replace the values specified in its data argument. Fields omitted from the setDocument() call remain untouched. If your input sets any field to an empty map, all nested fields are overwritten.

DocumentReference

Prop	Type	Description	Since
id	string	The id of the document.	1.0.0
path	string	A string representing the path of the referenced document (relative to the root of the database).	1.0.0

AddDocument

Prop	Type	Description
data	T	An Object containing the data for the new document.

CollectionSnapshot

Prop	Type
collection	DocumentSnapshot<T>[]

CollectionQuery

Prop	Type
queryConstraints	QueryConstraint[]

QueryConstraint

A QueryConstraint is used to narrow the set of documents returned by a Firestore query.

Prop	Type	Description
fieldPath	string	The path to compare
opStr	QueryOperators	The operation string (e.g "<", "<=", "==", "<", "<=", "!=", "array-contains")
value	any	The value for comparison

RemoveSnapshotListener

Prop	Type
callbackId	CallbackId

Type Aliases

Partial

Make all properties in T optional

{ [P in keyof T]?: T[P]; }

DocumentSnapshotCallback

(data: DocumentSnapshot<T> | null, err?: any): void

CallbackId

string

QueryOperators

Filter conditions in a {@link QueryConstraint} clause are specified using the strings '<', '<=', '==', '>=', '>', 'array-contains'

"==" | ">=" | "<=" | "<" | ">" | "array-contains"

CollectionSnapshotCallback

(data: CollectionSnapshot<T> | null, err?: any): void