Skip to content

README.md

Latest commit

 

History

History
997 lines (676 loc) · 40.6 KB

README.md

File metadata and controls

997 lines (676 loc) · 40.6 KB

@capgo/capacitor-firebase-firestore

Capgo - Instant updates for Capacitor

Unofficial Capacitor plugin for Firebase Cloud Firestore.1

Guides

Compatibility

Plugin Version Capacitor Version Status
8.x.x >=8.x.x Active support
7.x.x 7.x.x Deprecated
6.x.x 6.x.x Deprecated

Installation

npm install @capgo/capacitor-firebase-firestore
npx cap sync

Add Firebase to your project if you haven't already (Android / iOS / Web).

Android

Variables

If needed, you can define the following project variable in your app’s variables.gradle file to change the default version of the dependency:

  • $firebaseFirestoreVersion version of com.google.firebase:firebase-firestore (default: 26.0.2)

This can be useful if you encounter dependency conflicts with other plugins in your project.

Configuration

No configuration required for this plugin.

Demo

A working example can be found here: robingenz/capacitor-firebase-plugin-demo

Starter templates

The following starter templates are available:

Usage

import { FirebaseFirestore } from '@capgo/capacitor-firebase-firestore';

const addDocument = async () => {
  await FirebaseFirestore.addDocument({
    reference: 'users',
    data: { 
      first: 'Alan', 
      last: 'Turing', 
      born: 1912 
    },
  });
};

const setDocument = async () => {
  await FirebaseFirestore.setDocument({
    reference: 'users/Aorq09lkt1ynbR7xhTUx',
    data: { 
      first: 'Alan', 
      last: 'Turing', 
      born: 1912 
    },
    merge: true,
  });
};

const getDocument = async () => {
  const { snapshot } = await FirebaseFirestore.getDocument({
    reference: 'users/Aorq09lkt1ynbR7xhTUx',
  });
  return snapshot;
};

const updateDocument = async () => {
  await FirebaseFirestore.updateDocument({
    reference: 'users/Aorq09lkt1ynbR7xhTUx',
    data: { 
      first: 'Alan', 
      last: 'Turing', 
      born: 1912 
    },
  });
};

const deleteDocument = async () => {
  await FirebaseFirestore.deleteDocument({
    reference: 'users/Aorq09lkt1ynbR7xhTUx',
  });
};

const writeBatch = async () => {
  await FirebaseFirestore.writeBatch({
    operations: [
      {
        type: 'set',
        reference: 'users/Aorq09lkt1ynbR7xhTUx',
        data: { 
          first: 'Alan', 
          last: 'Turing', 
          born: 1912 
        },
        options: { merge: true },
      },
      {
        type: 'update',
        reference: 'users/Aorq09lkt1ynbR7xhTUx',
        data: { 
          first: 'Alan', 
          last: 'Turing', 
          born: 1912 
        },
      },
      {
        type: 'delete',
        reference: 'users/Aorq09lkt1ynbR7xhTUx',
      },
    ],
  });
};

const getCollection = async () => {
  const { snapshots } = await FirebaseFirestore.getCollection({
    reference: 'users',
    compositeFilter: {
      type: 'and',
      queryConstraints: [
        {
          type: 'where',
          fieldPath: 'born',
          opStr: '==',
          value: 1912,
        },
      ],
    },
    queryConstraints: [
      {
        type: 'orderBy',
        fieldPath: 'born',
        directionStr: 'desc',
      },
      {
        type: 'limit',
        limit: 10,
      },
    ],
  });
  return snapshots;
};

const getCollectionGroup = async () => {
  const { snapshots } = await FirebaseFirestore.getCollectionGroup({
    reference: 'users',
    compositeFilter: {
      type: 'and',
      queryConstraints: [
        {
          type: 'where',
          fieldPath: 'born',
          opStr: '==',
          value: 1912,
        },
      ],
    },
    queryConstraints: [
      {
        type: 'orderBy',
        fieldPath: 'born',
        directionStr: 'desc',
      },
      {
        type: 'limit',
        limit: 10,
      },
    ],
  });
  return snapshots;
};

const enableNetwork = async () => {
  await FirebaseFirestore.enableNetwork();
};

const disableNetwork = async () => {
  await FirebaseFirestore.disableNetwork();
};

const useEmulator = async () => {
  await FirebaseFirestore.useEmulator({
    host: '10.0.2.2',
    port: 9001,
  });
};

const addDocumentSnapshotListener = async () => {
  const callbackId = await FirebaseFirestore.addDocumentSnapshotListener(
    {
      reference: 'users/Aorq09lkt1ynbR7xhTUx',
    },
    (event, error) => {
      if (error) {
        console.error(error);
      } else {
        console.log(event);
      }
    }
  );
  return callbackId;
};

const addCollectionSnapshotListener = async () => {
  const callbackId = await FirebaseFirestore.addCollectionSnapshotListener(
    {
      reference: 'users',
      compositeFilter: {
        type: 'and',
        queryConstraints: [
          {
            type: 'where',
            fieldPath: 'born',
            opStr: '==',
            value: 1912,
          },
        ],
      },
      queryConstraints: [
        {
          type: 'orderBy',
          fieldPath: 'born',
          directionStr: 'desc',
        },
        {
          type: 'limit',
          limit: 10,
        },
      ],
    },
    (event, error) => {
      if (error) {
        console.error(error);
      } else {
        console.log(event);
      }
    }
  );
  return callbackId;
};

const addCollectionGroupSnapshotListener = async () => {
  const callbackId = await FirebaseFirestore.addCollectionGroupSnapshotListener(
    {
      reference: 'users',
      compositeFilter: {
        type: 'and',
        queryConstraints: [
          {
            type: 'where',
            fieldPath: 'born',
            opStr: '==',
            value: 1912,
          },
        ],
      },
      queryConstraints: [
        {
          type: 'orderBy',
          fieldPath: 'born',
          directionStr: 'desc',
        },
        {
          type: 'limit',
          limit: 10,
        },
      ],
    },
    (event, error) => {
      if (error) {
        console.error(error);
      } else {
        console.log(event);
      }
    }
  );
  return callbackId;
};

const removeSnapshotListener = async (callbackId: string) => {
  await FirebaseFirestore.removeSnapshotListener({
    callbackId,
  });
};

const removeAllListeners = async () => {
  await FirebaseFirestore.removeAllListeners();
};

API

addDocument(...)

addDocument(options: AddDocumentOptions) => Promise<AddDocumentResult>

Adds a new document to a collection with the given data.

Param Type
options AddDocumentOptions

Returns: Promise<AddDocumentResult>

Since: 5.2.0

setDocument(...)

setDocument(options: SetDocumentOptions) => Promise<void>

Writes to the document referred to by the specified reference. If the document does not yet exist, it will be created.

Param Type
options SetDocumentOptions

Since: 5.2.0

getDocument(...)

getDocument<T extends DocumentData = DocumentData>(options: GetDocumentOptions) => Promise<GetDocumentResult<T>>

Reads the document referred to by the specified reference.

Param Type
options GetDocumentOptions

Returns: Promise<GetDocumentResult<T>>

Since: 5.2.0

updateDocument(...)

updateDocument(options: UpdateDocumentOptions) => Promise<void>

Updates fields in the document referred to by the specified reference.

Param Type
options UpdateDocumentOptions

Since: 5.2.0

deleteDocument(...)

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

Deletes the document referred to by the specified reference.

Param Type
options DeleteDocumentOptions

Since: 5.2.0

writeBatch(...)

writeBatch(options: WriteBatchOptions) => Promise<void>

Execute multiple write operations as a single batch.

Param Type
options WriteBatchOptions

Since: 6.1.0

getCollection(...)

getCollection<T extends DocumentData = DocumentData>(options: GetCollectionOptions) => Promise<GetCollectionResult<T>>

Reads the collection referenced by the specified reference.

Param Type
options GetCollectionOptions

Returns: Promise<GetCollectionResult<T>>

Since: 5.2.0

getCollectionGroup(...)

getCollectionGroup<T extends DocumentData = DocumentData>(options: GetCollectionGroupOptions) => Promise<GetCollectionGroupResult<T>>

Reads the collection group referenced by the specified reference.

Param Type
options GetCollectionGroupOptions

Returns: Promise<GetCollectionGroupResult<T>>

getCountFromServer(...)

getCountFromServer(options: GetCountFromServerOptions) => Promise<GetCountFromServerResult>

Fetches the number of documents in a collection.

Param Type
options GetCountFromServerOptions

Returns: Promise<GetCountFromServerResult>

Since: 6.4.0

clearPersistence()

clearPersistence() => Promise<void>

Clears the persistent storage. This includes pending writes and cached documents.

Must be called after the app is shutdown or when the app is first initialized.

Since: 5.2.0

enableNetwork()

enableNetwork() => Promise<void>

Re-enables use of the network.

Since: 5.2.0

disableNetwork()

disableNetwork() => Promise<void>

Disables use of the network.

Since: 5.2.0

useEmulator(...)

useEmulator(options: UseEmulatorOptions) => Promise<void>

Instrument your app to talk to the Firestore emulator.

Param Type
options UseEmulatorOptions

Since: 6.1.0

addDocumentSnapshotListener(...)

addDocumentSnapshotListener<T extends DocumentData = DocumentData>(options: AddDocumentSnapshotListenerOptions, callback: AddDocumentSnapshotListenerCallback<T>) => Promise<CallbackId>

Adds a listener for document snapshot events.

Param Type
options AddDocumentSnapshotListenerOptions
callback AddDocumentSnapshotListenerCallback<T>

Returns: Promise<string>

Since: 5.2.0

addCollectionSnapshotListener(...)

addCollectionSnapshotListener<T extends DocumentData = DocumentData>(options: AddCollectionSnapshotListenerOptions, callback: AddCollectionSnapshotListenerCallback<T>) => Promise<CallbackId>

Adds a listener for collection snapshot events.

Param Type
options AddCollectionSnapshotListenerOptions
callback AddCollectionSnapshotListenerCallback<T>

Returns: Promise<string>

Since: 5.2.0

addCollectionGroupSnapshotListener(...)

addCollectionGroupSnapshotListener<T extends DocumentData = DocumentData>(options: AddCollectionGroupSnapshotListenerOptions, callback: AddCollectionGroupSnapshotListenerCallback<T>) => Promise<CallbackId>

Adds a listener for collection group snapshot events.

Param Type
options AddCollectionGroupSnapshotListenerOptions
callback AddCollectionGroupSnapshotListenerCallback<T>

Returns: Promise<string>

Since: 6.1.0

removeSnapshotListener(...)

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

Remove a listener for document or collection snapshot events.

Param Type
options RemoveSnapshotListenerOptions

Since: 5.2.0

removeAllListeners()

removeAllListeners() => Promise<void>

Remove all listeners for this plugin.

Since: 5.2.0

getPluginVersion()

getPluginVersion() => Promise<GetPluginVersionResult>

Get the version of this plugin.

Returns: Promise<GetPluginVersionResult>

Since: 8.0.1

Interfaces

AddDocumentResult

Prop Type Description Since
reference DocumentReference The reference of the newly added document. 5.2.0

DocumentReference

Prop Type Description Since
id string The document's identifier within its collection. 5.2.0
path string The path of the document. 5.2.0

AddDocumentOptions

Prop Type Description Since
reference string The reference as a string, with path components separated by a forward slash (/). 5.2.0
data DocumentData An object containing the data for the new document. 5.2.0

DocumentData

SetDocumentOptions

Prop Type Description Default Since
reference string The reference as a string, with path components separated by a forward slash (/). 5.2.0
data DocumentData An object containing the data for the new document. 5.2.0
merge boolean Whether to merge the provided data with an existing document. false 5.2.0

GetDocumentResult

Prop Type Description Since
snapshot DocumentSnapshot<T> The current document contents. 5.2.0

DocumentSnapshot

Prop Type Description Since
id string The document's identifier within its collection. 5.2.0
path string The path of the document. 5.2.0
data T | null An object containing the data for the document. Returns null if the document doesn't exist. 5.2.0
metadata SnapshotMetadata Metadata about the snapshot, concerning its source and if it has local modifications. 6.2.0

SnapshotMetadata

Prop Type Description Since
fromCache boolean True if the snapshot was created from cached data. 6.2.0
hasPendingWrites boolean True if the snapshot was created from pending write data. 6.2.0

GetDocumentOptions

Prop Type Description Since
reference string The reference as a string, with path components separated by a forward slash (/). 5.2.0

UpdateDocumentOptions

Prop Type Description Since
reference string The reference as a string, with path components separated by a forward slash (/). 5.2.0
data DocumentData An object containing the data for the new document. 5.2.0

DeleteDocumentOptions

Prop Type Description Since
reference string The reference as a string, with path components separated by a forward slash (/). 5.2.0

WriteBatchOptions

Prop Type Description Since
operations WriteBatchOperation[] The operations to execute in the batch. 6.1.0

WriteBatchOperation

Prop Type Description Since
type 'set' | 'update' | 'delete' The type of operation. 6.1.0
reference string The reference as a string, with path components separated by a forward slash (/). 6.1.0
data DocumentData An object containing the data for the new document. 6.1.0
options SetOptions An object to configure the set behavior. 7.3.0

SetOptions

Prop Type Description Default Since
merge boolean Whether a merge should be performed or the document should be overwritten. false 7.3.0

GetCollectionResult

Prop Type Description Since
snapshots DocumentSnapshot<T>[] The documents in the collection. 5.2.0

GetCollectionOptions

Prop Type Description Since
reference string The reference as a string, with path components separated by a forward slash (/). 5.2.0
compositeFilter QueryCompositeFilterConstraint The filter to apply. 5.2.0
queryConstraints QueryNonFilterConstraint[] Narrow or order the set of documents to retrieve, but do not explicitly filter for document fields. 5.2.0

QueryCompositeFilterConstraint

Prop Type Description Since
type 'and' | 'or' The type of the constraint. 5.2.0
queryConstraints QueryFilterConstraint[] The filters to apply. 5.2.0

QueryFieldFilterConstraint

Prop Type Description Since
type 'where' The type of the constraint. 5.2.0
fieldPath string The path to compare. 5.2.0
opStr QueryOperator The operation string to apply. 5.2.0
value any The value for comparison. 5.2.0

QueryOrderByConstraint

Prop Type Description Since
type 'orderBy' The type of the constraint. 5.2.0
fieldPath string The path to compare. 5.2.0
directionStr OrderByDirection The direction to sort by. 5.2.0

QueryLimitConstraint

Prop Type Description Since
type 'limit' | 'limitToLast' The type of the constraint. 5.2.0
limit number The maximum number of items to return. 5.2.0

QueryStartAtConstraint

Prop Type Description Since
type 'startAt' | 'startAfter' The type of the constraint. 5.2.0
reference string The reference to start at or after as a string, with path components separated by a forward slash (/). Attention: This requires an additional document read. 5.2.0

QueryEndAtConstraint

Prop Type Description Since
type 'endAt' | 'endBefore' The type of the constraint. 5.2.0
reference string The reference as to end at or before as a string, with path components separated by a forward slash (/). Attention: This requires an additional document read. 5.2.0

GetCollectionGroupResult

Prop Type Description Since
snapshots DocumentSnapshot<T>[] The documents in the collection. 5.2.0

GetCollectionGroupOptions

Prop Type Description Since
reference string The reference as a string, with path components separated by a forward slash (/). 5.2.0
compositeFilter QueryCompositeFilterConstraint The filter to apply. 5.2.0
queryConstraints QueryNonFilterConstraint[] Narrow or order the set of documents to retrieve, but do not explicitly filter for document fields. 5.2.0

GetCountFromServerResult

Prop Type Description Since
count number The number of documents in the collection. 6.4.0

GetCountFromServerOptions

Prop Type Description Since
reference string The reference as a string, with path components separated by a forward slash (/). 6.4.0

UseEmulatorOptions

Prop Type Description Default Since
host string The emulator host without any port or scheme. Note when using a Android Emulator device: 10.0.2.2 is the special IP address to connect to the 'localhost' of the host computer. 6.1.0
port number The emulator port. 8080 6.1.0

AddDocumentSnapshotListenerOptions

Prop Type Description Since
reference string The reference as a string, with path components separated by a forward slash (/). 5.2.0

AddCollectionSnapshotListenerOptions

Prop Type Description Since
reference string The reference as a string, with path components separated by a forward slash (/). 5.2.0
compositeFilter QueryCompositeFilterConstraint The filter to apply. 5.2.0
queryConstraints QueryNonFilterConstraint[] Narrow or order the set of documents to retrieve, but do not explicitly filter for document fields. 5.2.0

AddCollectionGroupSnapshotListenerOptions

Prop Type Description Since
reference string The reference as a string, with path components separated by a forward slash (/). 6.1.0
compositeFilter QueryCompositeFilterConstraint The filter to apply. 6.1.0
queryConstraints QueryNonFilterConstraint[] Narrow or order the set of documents to retrieve, but do not explicitly filter for document fields. 6.1.0

RemoveSnapshotListenerOptions

Prop Type Since
callbackId CallbackId 5.2.0

GetPluginVersionResult

Prop Type Description Since
version string The semantic version of this plugin. 8.0.1

Type Aliases

QueryFilterConstraint

QueryFieldFilterConstraint | QueryCompositeFilterConstraint

QueryOperator

'<' | '<=' | '==' | '>=' | '>' | '!=' | 'array-contains' | 'array-contains-any' | 'in' | 'not-in'

QueryNonFilterConstraint

QueryOrderByConstraint | QueryLimitConstraint | QueryStartAtConstraint | QueryEndAtConstraint

OrderByDirection

'desc' | 'asc'

AddDocumentSnapshotListenerCallback

(event: AddDocumentSnapshotListenerCallbackEvent<T> | null, error: any): void

AddDocumentSnapshotListenerCallbackEvent

GetDocumentResult<T>

CallbackId

string

AddCollectionSnapshotListenerCallback

(event: AddCollectionSnapshotListenerCallbackEvent<T> | null, error: any): void

AddCollectionSnapshotListenerCallbackEvent

GetCollectionResult<T>

AddCollectionGroupSnapshotListenerCallback

(event: AddCollectionGroupSnapshotListenerCallbackEvent<T> | null, error: any): void

AddCollectionGroupSnapshotListenerCallbackEvent

GetCollectionGroupResult<T>

Limitations

This plugin currently has the following limitations:

Changelog

See CHANGELOG.md.

License

See LICENSE.

Footnotes

  1. This project is not affiliated with, endorsed by, sponsored by, or approved by Google LLC or any of their affiliates or subsidiaries. ↩