@getcircuit/firestore-utils

@getcircuit/firestore-utils

A collection of utilities to work with Circuit's Firestore. This package is intended to be used by both client and server Firebase instances.

Utilities

isFirestoreError(error?: unknown, code?: FirebaseErrorCode): boolean

Checks if the given error is a Firestore error with the given code. If the code is not provided, it will check if the error is a Firestore error.

isModelDocumentRef(modelName: string, ref: DocumentReference): boolean

Checks if the given reference is a reference to a document of the given model and asserts the reference type.

function myFunction(rootRef: DocumentReference<Team | User>) {
  if (isModelDocumentRef('Team', rootRef)) {
    // rootRef is a DocumentReference<Team>
  } else if (isModelDocumentRef('User', rootRef)) {
    // rootRef is a DocumentReference<User>
  }
}

isModelCollectionRef(modelName: string, ref: CollectionReference): boolean

Checks if the given reference is a reference to a collection of the given model and asserts the reference type.

function myFunction(rootRef: CollectionReference<Team | User>) {
  if (isModelCollectionRef('Team', rootRef)) {
    // rootRef is a CollectionReference<Team>
  } else if (isModelCollectionRef('User', rootRef)) {
    // rootRef is a CollectionReference<User>
  }
}

isEqualDocumentData<Data>(data1: Data, data2: Data): boolean

Compare two document data objects and return true if they are equivalent.

• Firestore refs are compared by their path.
• Dates are compared by their timestamp.
• Objects are shallowly compared.
• Arrays and deep nested objects are compared deeply.

getQueryId(query: Query): string

Returns a unique ID for the given query. This is useful to uniquely identify a query, as in a cache.

Note: mostly used internally by our custom query snapshot watcher in Snappy.

normalizeRefPath(path: string): string

Normalizes a string Firestore path by removing leading and trailing slashes.

normalizeRefPath('/users/123/') // 'users/123'

getRefId(ref: DocumentReference | CollectionReference | string): string

Returns the ID of the given reference. If the reference is a string, it is assumed to be a Firestore path and the ID is extracted from the last segment of the path.

getRefId(userRef) // '123'
getRefId('users/123') // '123'

getRefPath(ref: DocumentReference | CollectionReference | string): string

Returns the path of the given reference. If the reference is a string path, it is assumed to be a Firestore path and the path is normalized via normalizeRefPath.

getRefPath(userRef) // 'users/123'
getRefPath('users/123') // 'users/123'

isSameRef(ref1: DocumentReference | CollectionReference | string, ref2: DocumentReference | CollectionReference | string): boolean

Checks if two references are the same by comparing their path. If the references are string paths, they are assumed to be Firestore paths and are normalized via normalizeRefPath.

const userRef = doc(firestore, 'users/123')
isSameRef(userRef, 'users/123') // true
isSameRef(userRef, 'users/456') // false

isFirestoreRef(ref: unknown): boolean

Type guard to check if the given reference is a Firestore reference. It doesn't use instance checks, but rather checks if the reference has the expected properties of a Firestore reference: firestore, id and path.