@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