@leaddreamer/firestore-wrapper

A set of helper-wrapper functions around firebase firestore. Includes support for various forms of Pagination. Intent is to treat Firestore as a hierarchical records-oriented database. Originally conceived to port from one database to another.

Usage no npm install needed!

<script type="module">
  import leaddreamerFirestoreWrapper from 'https://cdn.skypack.dev/@leaddreamer/firestore-wrapper';
</script>

README

view on npm

@leaddreamer/firebase-wrappers

A set of helper-wrapper functions around firebase firestore, storage and auth. Intent is to treat Firestore as a hierarchical record-oriented database; originally conceived to port from one database to another.

Modules

FirebaseWrapper

A set of helper-wrapper functions around firebase firestore, storage and auth. all-in-one wrapper for a solid subset of CLIENT-SIDE Firebase functions, with a consistent interface. There is a parallel set for ADMIN-SIDE functions as well. Intent is to treat Firestore as a hierarchical record-oriented database; originally conceived to port from one database to another.

FirebaseAuthWrapper

A set of helper-wrapper functions around firebase firestore, storage and auth. Intent is to treat Firestore as a hierarchical record-oriented database; originally conceived to port from one database to another.

FirebaseCloudFunctionsWrapper

A set of helper-wrapper functions around firebase firestore, storage and auth. Intent is to treat Firestore as a hierarchical record-oriented database; originally conceived to port from one database to another.

FirebaseFirestoreWrapper

A set of helper-wrapper functions around firebase firestore, storage and auth. Intent is to treat Firestore as a hierarchical record-oriented database; originally conceived to port from one database to another.

FirebaseStorageWrapper

A set of helper-wrapper functions around firebase firestore, storage and auth. Intent is to treat Firestore as a hierarchical record-oriented database; originally conceived to port from one database to another.

FirebaseWrapper

A set of helper-wrapper functions around firebase firestore, storage and auth. all-in-one wrapper for a solid subset of CLIENT-SIDE Firebase functions, with a consistent interface. There is a parallel set for ADMIN-SIDE functions as well. Intent is to treat Firestore as a hierarchical record-oriented database; originally conceived to port from one database to another.

FirebaseWrapper

A set of helper-wrapper functions around firebase firestore, storage and auth. all-in-one wrapper for a solid subset of CLIENT-SIDE Firebase functions, with a consistent interface. There is a parallel set for ADMIN-SIDE functions as well. Intent is to treat Firestore as a hierarchical record-oriented database; originally conceived to port from one database to another.

FirebaseWrapper.FirebaseWrapper(config) ⇒

Kind: static method of FirebaseWrapper Returns: none

Param Type Description
config FirebaseConfigObject Firebase Admin object

Example

//this specifically loads ALL the subsections, specifically for
//the Browser.  See later (tbd) notes for NodeJS

import FirebaseWrapper from "@leaddreamer/firebase-wrapper";
FirebaseWrapper(config); //see below
export * from "@leaddreamer/firebase-wrapper";

FirebaseWrapper.FirebaseWrapper(config)

Kind: static method of FirebaseWrapper

Param Type Description
config FirebaseConfigObject Firebase Admin object

Example this specifically loads ALL the subsections, specifically for the Browser. See later (tbd) notes for NodeJS

import FirebaseWrapper from "@leaddreamer/firebase-wrapper";
FirebaseWrapper(config); //see below
export * from "@leaddreamer/firebase-wrapper";

FirebaseWrapper~FirebaseConfigObject : Object

Kind: inner typedef of FirebaseWrapper Properties

Name Type Description
apiKey string required api Key from Firebase Console,
appId string required app ID from Firebase Console
projectId string required Firebase projectID from Firebase console
authDomain string (optional) auth domain from Firebase Console
databaseURL string (optional) Firestore database URL from Firebase console
storageBucket: string (optional) URL of Firestore Storage Bucket
messagingSenderId: string (optional) ID for Messaing service from Firebase Console
measurementId: string (optional) Analytics/Measurement ID from Firebase Console
mapsAPIKey string (optional) App ID for Google Maps API, from Google

FirebaseWrapper~FirebaseConfigObject : Object

Kind: inner typedef of FirebaseWrapper Properties

Name Type Description
apiKey string required api Key from Firebase Console,
appId string required app ID from Firebase Console
projectId string required Firebase projectID from Firebase console
authDomain string (optional) auth domain from Firebase Console
databaseURL string (optional) Firestore database URL from Firebase console
storageBucket: string (optional) URL of Firestore Storage Bucket
messagingSenderId: string (optional) ID for Messaing service from Firebase Console
measurementId: string (optional) Analytics/Measurement ID from Firebase Console
mapsAPIKey string (optional) App ID for Google Maps API, from Google

FirebaseAuthWrapper

A set of helper-wrapper functions around firebase firestore, storage and auth. Intent is to treat Firestore as a hierarchical record-oriented database; originally conceived to port from one database to another.

FirebaseAuthWrapper.FirebaseAuth : object

Kind: static property of FirebaseAuthWrapper

FirebaseAuthWrapper.FirebaseAuthSignInOptions : string

Kind: static property of FirebaseAuthWrapper

FirebaseAuthWrapper.doCreateUserWithEmailAndPassword

Kind: static constant of FirebaseAuthWrapper

FirebaseAuthWrapper.doSignInWithEmailAndPassword

Kind: static constant of FirebaseAuthWrapper

FirebaseAuthWrapper.doSignInWithGoogle

Kind: static constant of FirebaseAuthWrapper

FirebaseAuthWrapper.doSignInWithFacebook

Kind: static constant of FirebaseAuthWrapper

FirebaseAuthWrapper.doSignInWithTwitter

Kind: static constant of FirebaseAuthWrapper

FirebaseAuthWrapper.doSignOut

Kind: static constant of FirebaseAuthWrapper

FirebaseAuthWrapper.doPasswordReset

Kind: static constant of FirebaseAuthWrapper

FirebaseAuthWrapper.doSendEmailVerification

Kind: static constant of FirebaseAuthWrapper

FirebaseAuthWrapper.doPasswordUpdate

Kind: static constant of FirebaseAuthWrapper

FirebaseAuthWrapper.createAnonymousUser

Kind: static constant of FirebaseAuthWrapper

FirebaseAuthWrapper.attachAuthUserListener

Kind: static constant of FirebaseAuthWrapper

FirebaseAuthWrapper.setPersistence

Kind: static constant of FirebaseAuthWrapper

FirebaseAuthWrapper.FirebaseAuthWrapper(firebase)

Initializes the Auth service of the provided firebase app. Also instantiates various constants and helper functions

Kind: static method of FirebaseAuthWrapper

Param Type
firebase firebase

Example

import * as firebase from "firebase/app";
import "firebase/auth";
import FirebaseAuth from "@leaddreamer/firebase-wrapper/FirebaseAuthWrapper";
import {config} from "wherever-you-put-it";

((myconfig) {
try {
  firebase.app();
} catch (err) {
  firebase.initializeApp(myconfig);
}
FirebaseAuth(firebase);
})(config)

FirebaseAuthWrapper.fetchClaims(user) ⇒ external:promise

Kind: static method of FirebaseAuthWrapper Fulfil: Returns a user token object Reject: returns err

Param Type
user FirebaseAuthUser

FirebaseAuthWrapper.refreshAuthUser() ⇒ Promise.<void>

Kind: static method of FirebaseAuthWrapper

FirebaseCloudFunctionsWrapper

A set of helper-wrapper functions around firebase firestore, storage and auth. Intent is to treat Firestore as a hierarchical record-oriented database; originally conceived to port from one database to another.

FirebaseCloudFunctionsWrapper.FirebaseCloudFunctions(firebase)

Kind: static method of FirebaseCloudFunctionsWrapper

Param Type
firebase firebase

Example

import * as firebase from "firebase/app";
import "firebase/functions";
import FirebaseFunctions from "@leaddreamer/firebase-wrapper/FirebaseCloudFunctionsWrapper";
import {config} from "whereever-you-put-it";

((myconfig) {
try {
  firebase.app();
} catch (err) {
  firebase.initializeApp(myconfig);
}
FirebaseFunctions(firebase);
})(config)

FirebaseCloudFunctionsWrapper.CloudFunctions() ⇒ external:promise

Kind: static method of FirebaseCloudFunctionsWrapper Fulfil: result as returns from call Reject: err as returned from call Example

result = await CloudFunctions("MyGloriousFunction")(argumentToFunction);

FirebaseFirestoreWrapper

A set of helper-wrapper functions around firebase firestore, storage and auth. Intent is to treat Firestore as a hierarchical record-oriented database; originally conceived to port from one database to another.

FirebaseFirestoreWrapper.PaginateFetch

An object to allow for paginating a table read from Firestore. REQUIRES a sorting choice

Kind: static class of FirebaseFirestoreWrapper Properties

Name Type Description
Query Query that forms basis for the table read
limit number page size
snapshot QuerySnapshot last successful snapshot/page fetched
status PagingStatus status of pagination object
PageForward function pages the fetch forward
PageBack function pages the fetch backward

new exports.PaginateFetch(table, filterArray, sortArray, refPath, limit)

Param Type Default Description
table string a properly formatted string representing the requested collection - always an ODD number of elements
filterArray array an (optional) 3xn array of filter(i.e. "where") conditions The array is assumed to be sorted in the correct order - i.e. filterArray[0] is added first; filterArray[length-1] last returns data as an array of objects (not dissimilar to Redux State objects) with both the documentID and documentReference added as fields.
sortArray array a 2xn array of sort (i.e. "orderBy") conditions
refPath string null (optional) allows "table" parameter to reference a sub-collection of an existing document reference (I use a LOT of structured collections)
limit number page size

FirebaseFirestoreWrapper.PaginateGroupFetch

An object to allow for paginating a query for table read from Firestore.

Kind: static class of FirebaseFirestoreWrapper Properties

Name Type Description
Query Query that forms basis for the table read
limit number page size
snapshot QuerySnapshot last successful snapshot/page fetched
status PagingStatus status of pagination object
PageForward function Changes the listener to the next page forward
PageBack function Changes the listener to the next page backward
Unsubscribe function returns the unsubscribe function

new exports.PaginateGroupFetch(group, [filterArray], [sortArray], limit)

Param Type Default Description
group string a properly formatted string representing the requested collection - always an ODD number of elements
[filterArray] filterObject an (optional) 3xn array of filter(i.e. "where") conditions
[sortArray] sortObject a 2xn array of sort (i.e. "orderBy") conditions The array(s) are assumed to be sorted in the correct order - i.e. filterArray[0] is added first; filterArray[length-1] last returns data as an array of objects (not dissimilar to Redux State objects) with both the documentID and documentReference added as fields.
limit number (optional)

FirebaseFirestoreWrapper.PaginatedListener

An object to allow for paginating a listener for table read from Firestore. REQUIRES a sorting choice masks some subscribe/unsubscribe action for paging forward/backward

Kind: static class of FirebaseFirestoreWrapper Properties

Name Type Description
Query Query that forms basis for the table read
limit number page size
snapshot QuerySnapshot last successful snapshot/page fetched
status PagingStatus status of pagination object
PageForward function Changes the listener to the next page forward
PageBack function Changes the listener to the next page backward

new exports.PaginatedListener(table, [filterArray], [sortArray], refPath, limit, dataCallback, errCallback)

Param Type Default Description
table string a properly formatted string representing the requested collection - always an ODD number of elements
[filterArray] filterObject an (optional) 3xn array of filter(i.e. "where") conditions
[sortArray] sortObject a 2xn array of sort (i.e. "orderBy") conditions
refPath refPath (optional) allows "table" parameter to reference a sub-collection of an existing document reference (I use a LOT of structered collections) The array is assumed to be sorted in the correct order - i.e. filterArray[0] is added first; filterArray[length-1] last returns data as an array of objects (not dissimilar to Redux State objects) with both the documentID and documentReference added as fields.
limit number (optional)
dataCallback callback
errCallback callback

FirebaseFirestoreWrapper.PAGINATE_CHOICES : enum

[PAGINATE_CHOICES]

Kind: static enum of FirebaseFirestoreWrapper

FirebaseFirestoreWrapper.documentId

  • a fieldPath value to represent the document Id - WARNING Google Firestore has a bug, and this actually represents the FULL PATH to the document

Kind: static constant of FirebaseFirestoreWrapper

FirebaseFirestoreWrapper.deleteFieldValue

a sentinel value used to delete a field during an update operation

Kind: static constant of FirebaseFirestoreWrapper

FirebaseFirestoreWrapper.serverTimestampFieldValue

a sentinel value to set a field to a server-generated timestamp during set(0 or update())

Kind: static constant of FirebaseFirestoreWrapper

FirebaseFirestoreWrapper.MAX_CONCURRENCY : number

maximum concurrent writes

Kind: static constant of FirebaseFirestoreWrapper

FirebaseFirestoreWrapper.PAGINATE_INIT : number

Kind: static constant of FirebaseFirestoreWrapper

FirebaseFirestoreWrapper.PAGINATE_PENDING : number

Kind: static constant of FirebaseFirestoreWrapper

FirebaseFirestoreWrapper.PAGINATE_UPDATED : number

Kind: static constant of FirebaseFirestoreWrapper

FirebaseFirestoreWrapper.PAGINATE_DEFAULT : number

Kind: static constant of FirebaseFirestoreWrapper

FirebaseFirestoreWrapper.initialize_firestore(firebase)

Initializes the Firestore service of the provided firebase app. Also instantiates various constants and helper functions

Kind: static method of FirebaseFirestoreWrapper

Param Type
firebase firebase

Example

import * as firebase from "firebase/app";
import "firebase/firestore";
import FirebaseFirestore from "@leaddreamer/firebase-wrapper/FirebaseFirestoreWrapper";
import {config} from "whereever-you-put-it";

((myconfig) {
try {
  firebase.app();
} catch (err) {
  firebase.initializeApp(myconfig);
}
FirebaseFirestore(firebase);
})(config)

FirebaseFirestoreWrapper.timestamp()

  • Firestore timestamp processor

Kind: static method of FirebaseFirestoreWrapper

FirebaseFirestoreWrapper.incrementFieldValue(n) ⇒

Kind: static method of FirebaseFirestoreWrapper Returns: a sentinel value

Param Description
n If either the operand or the current field value uses floating point precision, all arithmetic follows IEEE 754 semantics. If both values are integers, values outside of JavaScript's safe number range (Number.MIN_SAFE_INTEGER to Number.MAX_SAFE_INTEGER) are also subject to precision loss. Furthermore, once processed by the Firestore backend, all integer operations are capped between -2^63 and 2^63-1. If the current field value is not of type number, or if the field does not yet exist, the transformation sets the field to the given value.

FirebaseFirestoreWrapper.arrayRemoveFieldValue(elements) ⇒ sentinelValue

returns a sentinel to remove elements from array field

Kind: static method of FirebaseFirestoreWrapper Returns: sentinelValue - a sentinel value

Param Description
elements REST expanded list of elements to remove

FirebaseFirestoreWrapper.arrayUnionFieldValue(elements) ⇒

return a sentinel to add/join elements to array field

Kind: static method of FirebaseFirestoreWrapper Returns: a sentinel value

Param Description
elements REST expanded list of elements to add

FirebaseFirestoreWrapper.RecordFromSnapshot(Snap) ⇒ Record

returns an internal record structure from a firestore snapshot

Kind: static method of FirebaseFirestoreWrapper

Param Type
Snap Snapshot

FirebaseFirestoreWrapper.DocumentFromRecord(Record) ⇒ object

returns a Firestore document structure from an internal Record

Kind: static method of FirebaseFirestoreWrapper

Param Type Description
Record object cleans up internal document representation

FirebaseFirestoreWrapper.runTransaction(updateFunction) ⇒ Promise.<object>

creates and runs a series of record operations (executed in the param function) as an atomic operation. A transation object is passed to the callback parameter

Kind: static method of FirebaseFirestoreWrapper Returns: Promise.<object> - a promise with the result of updateFunction

Param Type Description
updateFunction callback callback function that expects a Transaction token as it's sole argument. either all the included/chained record operations will succeed, or none

FirebaseFirestoreWrapper.openWriteBatch() ⇒ WriteBatch

Kind: static method of FirebaseFirestoreWrapper Returns: WriteBatch - object that operations are added to for a bulk operation Sync:

FirebaseFirestoreWrapper.closeWriteBatch(batch) ⇒ Promise.<void>

dispatches an asynchronous Closure to submit Batch

Kind: static method of FirebaseFirestoreWrapper

Param Type Description
batch WriteBatch WriteBatch to close

FirebaseFirestoreWrapper.createUniqueReference(tablePath, refPath) ⇒ DocumentReference

adds a blank document to the collection referenced in parameter tablePath (relative to optional refPath) and returns it's reference. This is useful for Transactions and Batches, which can only get(), set() or update() existing documents. Tricksie!

Kind: static method of FirebaseFirestoreWrapper Returns: DocumentReference - Firestore Document Reference Sync:

Param Description
tablePath string representing a valid path to a collection to create the new document in, relative to a document reference passed in
refPath an optional valid document reference to start the table path

FirebaseFirestoreWrapper.dbReference(refPath)

generates a document reference from a path if passed; else returns the db base reference

Kind: static method of FirebaseFirestoreWrapper Sync:

Param Type Description
refPath string Path to base actions from. May be null

FirebaseFirestoreWrapper.writeRecord(tablePath, data, refPath, batch, mergeOption) ⇒ Promise.<Record>

writes a Firestore record to collection indicated by tablePath relative to option DocumentReference refPath

Kind: static method of FirebaseFirestoreWrapper

Param Type Description
tablePath string string representing a valid path to a collection to create or update the document in, relative to a document reference passed in
data Record Data/Record object to write to database
refPath string an optional valid document reference to start the table path
batch WriteBatch | Transaction optional chain token to include this operation as part of an Atomic Transaction
mergeOption boolean whether to merge into existin data; default TRUE

FirebaseFirestoreWrapper.writeRecordByRefPath(data, refPath, Transaction, mergeOption) ⇒ Promise.<Record>

Writes given data object (or map) to the given documentReference

Kind: static method of FirebaseFirestoreWrapper Returns: Promise.<Record> - data record as written

Param Type Description
data Record Object/Map to be written back to the Firestore
refPath string DocumentReference to write document to
Transaction WriteBatch | Transaction Optional Transaction to enclose this action in
mergeOption boolean whether to merge into existin data; default TRUE

FirebaseFirestoreWrapper.writeBack(data, Transaction, mergeOption) ⇒ Promise.<Record>

Writes a local-schema document back to the Firestore. Assume object/map came from the firestore

Kind: static method of FirebaseFirestoreWrapper Returns: Promise.<Record> - record as written.

Param Type Description
data Record Object/Map to be written back to the Firestore
Transaction WriteBatch | Transaction Optional Transaction to enclose this action in
mergeOption boolean whether to merge into existin data; default TRUE

FirebaseFirestoreWrapper.collectRecords(tablePath, refPath) ⇒ Promise.<Array.<Record>>

query for a SET of records

Kind: static method of FirebaseFirestoreWrapper

Param Type Description
tablePath string string representing path ro requested collection
refPath string string representing a path to the relative PARENT of the requested collection

FirebaseFirestoreWrapper.collectRecordsByFilter(table, [filterArray], refPath) ⇒ Promise.<Array.<Record>>

Kind: static method of FirebaseFirestoreWrapper Descriptions: returns an array of documents from Firestore

Param Type Description
table string a properly formatted string representing the requested collection - always an ODD number of elements
[filterArray] filterObject an array of filterObjects The array is assumed to be sorted in the correct order - i.e. filterArray[0] is added first; filterArray[length-1] last returns data as an array of objects (not dissimilar to Redux State objects) with both the documentID and documentReference added as fields.
refPath string (optional) allows "table" parameter to reference a sub-collection of an existing document reference (I use a LOT of structured collections)

FirebaseFirestoreWrapper.collectRecordsInGroup(tableName) ⇒ Promise.<Array.<Record>>

query for a SET of records from a COLLECTIONGROUP - all collections of a similar name, regardless of parents. It is up to the User to ensure these are at a similar level/structure - Firestore just matches the name

Kind: static method of FirebaseFirestoreWrapper

Param Type Description
tableName string string describing the NAME of the collection group desired

FirebaseFirestoreWrapper.collectRecordsInGroupByFilter(tableName, [filterArray]) ⇒ Promise.<Array.<Record>>

queries for Records from a CollectionGroup, filtered by the passed array of filterObjects

Kind: static method of FirebaseFirestoreWrapper

Param Type Description
tableName string string describing the Name of the collectiongroup
[filterArray] filterObject array of objects describing filter operations

FirebaseFirestoreWrapper.fetchRecord(tablePath, Id, refPath, batch) ⇒ Promise.<(Record|WriteBatch|Transaction)>

retrieve a record from the Firestore. If a Batch object is passed, returns a chained Btahc object

Kind: static method of FirebaseFirestoreWrapper

Param Type Description
tablePath string path to the enclosing collection
Id string Id of the specific document requested
refPath string optional document reference to base tablePath from
batch WriteBatch | Transaction optional batch reference

FirebaseFirestoreWrapper.fetchRecordByRefPath(docRefPath, batch) ⇒ Promise.<Record>

fetches a single record from the database, using just a refPath to identify the document

Kind: static method of FirebaseFirestoreWrapper

Param Type Description
docRefPath string string identifying the full path to the requested document
batch WriteBatch | Transaction object for collecting batched operations

FirebaseFirestoreWrapper.fetchRecordByFilter(table, [filterArray], refPath, batch) ⇒ Promise.<(Record|WriteBatch|Transaction)>

fetches a SINGLE record from the database, using just a filter to identify the document. DANGEROUSLY assumes the filter identifies a SINGLE document, even if the query always returns an array

Kind: static method of FirebaseFirestoreWrapper

Param Type Description
table string a properly formatted string representing the requested collection - always an ODD number of elements
[filterArray] filterObject array of objects describing filter operations
refPath string optional document reference to base tablePath from
batch WriteBatch | Transaction optional batch reference

FirebaseFirestoreWrapper.fetchRecordInGroupByFilter(table, [filterArray], batch) ⇒ Promise.<(Record|WriteBatch|Transaction)>

fetches a SINGLE record from the database, using just a filter to identify the document. DANGEROUSLY assumes the filter identifies a SINGLE document, even if the query always returns an array

Kind: static method of FirebaseFirestoreWrapper

Param Type Description
table string a properly formatted string representing the requested collection - always an ODD number of elements
[filterArray] filterObject array of objects describing filter operations
batch WriteBatch | Transaction optional batch reference

FirebaseFirestoreWrapper.deleteRecord(table, record, refPath, batch) ⇒ Promise.<(Record|WriteBatch|Transaction)>

deletes a single record from the database

Kind: static method of FirebaseFirestoreWrapper

Param Type Description
table string string naming the parent collection of the document
record Record
refPath string optional document reference to base tablePath from
batch WriteBatch | Transaction optional batch reference

FirebaseFirestoreWrapper.deleteRecordByRefPath(docRefPath, batch) ⇒ Promise.<(Record|WriteBatch|Transaction)>

deletes a single record from the database

Kind: static method of FirebaseFirestoreWrapper

Param Type Description
docRefPath string string identifying the full path to the requested document
batch WriteBatch | Transaction optional batch reference

FirebaseFirestoreWrapper.updateRecordFields(recordUpdate) ⇒ Promise.<Record>

update record by fields - Allows use of FieldPath options such as .delete(). Only specifically referenced fields will be affected. Assumes the originating docRef is passed as refPath: field

Kind: static method of FirebaseFirestoreWrapper

Param Type Description
recordUpdate Record object of field:value entries to update.
recordUpdate.refPath string full path to document/record

FirebaseFirestoreWrapper.updateRecordByRefPath(docRefPath, data, batch) ⇒ Promise.<(Record|WriteBatch|Transaction)>

Kind: static method of FirebaseFirestoreWrapper

Param Type Description
docRefPath string full path to document to update
data Record Record of values to update
data.Id string document Id of record
batch WriteBatch | Transaction batching object

FirebaseFirestoreWrapper.writeArrayValue(fieldName, fieldValue, docRefPath, batch) ⇒ Promise.<(Record|WriteBatch|Transaction)>

adds a new value to a firestore record array entry

Kind: static method of FirebaseFirestoreWrapper

Param Type Description
fieldName string the string name of the array to be updated
fieldValue any the value to add to the array
docRefPath string the reference path for the document to be updated
batch WriteBatch | Transaction option