@getcircuit/patcher

@getcircuit/patcher

This package contains the methods necessary for resolving and applying patches to a document or collection.

Note: Currently, this package only implements the browser version of the patcher.

Usage

Creating a Patcher instance

The main export is the createPatcher function. It takes a firestore instance, a patches collection reference and an actor and returns a patcher object.

With a patcher, one can patch documents in multiple ways:

const patcher = createPatcher({
  firestore,
  patchesCollectionRef: firestore.collection('../../some/collection'),
  actor: 'user',
})

// patcher.addDocument(...)
// patcher.modifyDocument(...)
// patcher.moveDocument(...)
// patcher.deleteDocument(...)
// patcher.duplicateDocument(...)

Adding a document via patches

When we talk about adding a document via patches, we're actually talking about registering that a document was added to a collection. This means that patcher.addDocument doesn't create a new document in the database, but rather registers that a document was added by creating an added patch pointing to the document.

const docRef = firestore.collection('some-collection').doc('some-document')
await docRef.set({ title: 'Some title' })

// an `added` patch is created pointing to the newly created document
await patcher.addDocument({ documentRef: docRef })

Modifying a document via patches

When we talk about modifying a document via patches, we're actually talking about registering that a document was modified. This means that patcher.modifyDocument doesn't modify a document in the database, but rather registers that a document was modified by creating a modified patch pointing to the document.

Note: if there's already a modified patch pointing to the document, the new patch will be merged with the existing one.

const docRef = firestore.collection('some-collection').doc('some-document')
await docRef.set({ title: 'Some title' })

// a `modified` patch is created pointing to the modified document
await patcher.modifyDocument({
  documentRef: docRef,
  changes: {
    title: 'Some new title',
  },
})

// later on...
// the existing `modified` patch is merged with the new one
await patcher.modifyDocument({
  documentRef: docRef,
  changes: {
    description: 'Some description',
  },
})

Deleting a document via patches

When we talk about deleting a document via patches, we're actually talking about registering that a document was deleted. This means that patcher.deleteDocument doesn't delete a document in the database, but rather registers that a document was deleted by creating a deleted patch pointing to the document.

const docRef = firestore.collection('some-collection').doc('some-document')
await docRef.set({ title: 'Some title' })

// a `deleted` patch is created pointing to the deleted document
await patcher.deleteDocument({ documentRef: docRef })

Moving a document via patches

When we talk about moving a document via patches, we're actually talking about registering that a document was moved from one collection to another. This means that patcher.moveDocument doesn't move a document in the database, but rather registers that a document was moved by creating a moved patch pointing to the document.

const docRef = firestore.collection('some-collection').doc('some-document')

// a `moved` patch is created pointing to the moved document
await patcher.moveDocument({
  documentRef: docRef,
  destinationCollectionRef: firestore.collection('some-other-collection'),
})

Duplicating a document via patches

When we talk about duplicating a document via patches, we're actually talking about registering that a document was duplicated. This means that patcher.duplicateDocument doesn't duplicate a document in the database, but rather registers that a document was duplicated by creating a duplicated patch pointing to the document.

Note: the duplicateDocument method also takes account any existing modified patches pointing to the document being dulplicated.

const docRef = firestore.collection('some-collection').doc('some-document')

// a `duplicated` patch is created pointing to the duplicated document
await patcher.duplicateDocument({
  documentRef: docRef,
  destinationCollectionRef: firestore.collection('some-other-collection'),
})

Patching in batches

All the patching methods can be batched by using the patcher.inBatch method. The inBatch method takes a callback that receives a single object with all patching methods automatically bound to a batch.

const docRef = firestore.collection('some-collection').doc('some-document')

// `inBatch` will execute all patching methods in a single batch
await patcher.inBatch(({ addDocument, deleteDocument }) => {
  for (const ref of docsToAdd) {
    await addDocument({ documentRef: ref })
  }

  for (const ref of docsToDelete) {
    await deleteDocument({ documentRef: ref })
  }
})

Loading patches reactively

The package exports a signals entrypoint that contains the high-level API for patching documents and collections.

import {
  usePatchContext,
  providePatchContext,
  resolvePatchesFromCollection,
  createPatchedDocumentSnap,
  createPatchedCollectionDocumentSnaps,
  createUserAffectedDocumentIdsByAction,
} from '@getcircuit/patcher/signals'

Low-level internal utilities

The main exported module contains the low-level patching utilities to resolve and apply patches.

import {
  resolveDocumentPatches,
  resolvePatchList,
  applyPatchesToCollectionDocuments,
  queryPatches,
} from '@getcircuit/patcher'