Skip to content

LeadDreamer/firebase-wrapper

BranchesTags

Repository files navigation

view on npm

@leaddreamer/firebase-wrapper

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. NOTE: Most helpers return PROMISE.REJECT if no documents are returned. it is assumed projects using this library might want to have an explicitly error trap for such events.

FirebaseAuthWrapper/authAdmin

A set of helpers around Firebase admin SDK auth. Specific to use in Cloud Functions

FirebaseAuthWrapper/authClient

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.

FirebaseStorageAdminEmulator

A set of helper-wrapper functions around firebase storage Intent is to treat Firestore as a hierarchical record-oriented database and Storage as a parallel structure 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. NOTE: Most helpers return PROMISE.REJECT if no documents are returned. it is assumed projects using this library might want to have an explicitly error trap for such events.

Constants

PAGINATE_INIT : number
PAGINATE_PENDING : number
PAGINATE_UPDATED : number
PAGINATE_END : number
PAGINATE_DEFAULT : number
PAGINATE_CHOICES : number

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. NOTE: Most helpers return PROMISE.REJECT if no documents are returned. it is assumed projects using this library might want to have an explicitly error trap for such events.

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
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~FirebaseConfigObject : Object

only authDomain, databaseURL and storageBucket are present when called from a cloud environment

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

only authDomain, databaseURL and storageBucket are present when called from a cloud environment

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/authAdmin

A set of helpers around Firebase admin SDK auth. Specific to use in Cloud Functions

FirebaseAuthWrapper/authAdmin.FirebaseAuthAdminWrapper(firebase)

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

Kind: static method of FirebaseAuthWrapper/authAdmin

Param Type
firebase firebase

FirebaseAuthWrapper/authAdmin~getUser(userID) ⇒ Promise.<userData>

asynchronously fetches user data from Firestore Authentication

Kind: inner method of FirebaseAuthWrapper/authAdmin

Param Type
userID string

FirebaseAuthWrapper/authAdmin~DeleteUser(userID) ⇒ Promise

deletes a single user from the authentication system, identified by user ID

Kind: inner method of FirebaseAuthWrapper/authAdmin

Param Type
userID string

FirebaseAuthWrapper/authAdmin~setCustomClaims(uid, customClaim)

sets custom claims on user object overwrites other needed settings

Kind: inner method of FirebaseAuthWrapper/authAdmin

Param Type Description
uid string user ID
customClaim Object claims object, less than 1000 Bytes. null clears

FirebaseAuthWrapper/authAdmin~addCustomClaims(uid, customClaim)

adds/merges to new claims to user customClaims

Kind: inner method of FirebaseAuthWrapper/authAdmin

Param Type Description
uid string user ID
customClaim Object claims object to be merged with existing claims

FirebaseAuthWrapper/authAdmin~clearCustomClaims(uid)

removes all current customClaims on user (sets to null)

Kind: inner method of FirebaseAuthWrapper/authAdmin

Param Type Description
uid string user ID

FirebaseAuthWrapper/authAdmin~PageUsers(pageSize, pageToken)

pages through the full list of users. Woefully inefficient.

Kind: inner method of FirebaseAuthWrapper/authAdmin

Param Type Description
pageSize number default 1000
pageToken object default null

FirebaseAuthWrapper/authClient

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.

Example

import * as firebase from "firebase/app";
import "firebase/auth";
import FirebaseAuth from "@leaddreamer/firebase-wrapper/FirebaseAuthWrapper";
//the next is optional - if you want the React component
import StyledFirebaseAuth from "react-firebaseui/StyledFirebaseAuth";
import {config} from "wherever-you-put-it";

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

FirebaseAuthWrapper/authClient.FirebaseAuth : object

Kind: static property of FirebaseAuthWrapper/authClient

FirebaseAuthWrapper/authClient.FirebaseAuthSignInOptions : string

Kind: static property of FirebaseAuthWrapper/authClient

FirebaseAuthWrapper/authClient.FirebaseAuthClient(firebase)

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

Kind: static method of FirebaseAuthWrapper/authClient

Param Type
firebase firebase

FirebaseAuthWrapper/authClient.fetchToken(user) ⇒ external:promise

fetches our specific custom claim values from firebase auth

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

Param Type
user FirebaseAuthUser

FirebaseAuthWrapper/authClient.fetchJWT(user) ⇒ Promise.<JWT>

Fetch a JWT token for authenticated signed requests

Kind: static method of FirebaseAuthWrapper/authClient
Fulfil: Returnsa JWT token
Reject: returns an err

Param Type
user FirebaseAuthUser

FirebaseAuthWrapper/authClient.refreshAuthUser() ⇒ Promise.<void>

triggers an update of the Firebase Auth user object. A listener can be set to monitor these changes

Kind: static method of FirebaseAuthWrapper/authClient

FirebaseAuthWrapper/authClient.doCreateUserWithEmailAndPassword(email, password) ⇒ Promise.<UserCredential>

Creates AND SIGNS IN an authenticated user with the provided email and password Creates a new user account associated with the specified email address and password. On successful creation of the user account, this user will also be signed in to your application. User account creation can fail if the account already exists or the password is invalid. Note: The email address acts as a unique identifier for the user and enables an email-based password reset. This function will create a new user account and set the initial user password.

Kind: static method of FirebaseAuthWrapper/authClient

Param Type
email string
password string

FirebaseAuthWrapper/authClient.doSignInWithEmailAndPassword(email, password) ⇒ Promise.<UserCredential>

SIGNS IN an existing authenticated user with the provided email and password Creates a new user account associated with the specified email address and password. On successful creation of the user account, this user will also be signed in to your application. User account creation can fail if the account already exists or the password is invalid. Note: The email address acts as a unique identifier for the user and enables an email-based password reset. This function will create a new user account and set the initial user password.

Kind: static method of FirebaseAuthWrapper/authClient

Param Type
email string
password string

FirebaseAuthWrapper/authClient.doSignInWithGoogle()

Kind: static method of FirebaseAuthWrapper/authClient

FirebaseAuthWrapper/authClient.doSignInWithFacebook()

Kind: static method of FirebaseAuthWrapper/authClient

FirebaseAuthWrapper/authClient.doSignInWithTwitter()

Kind: static method of FirebaseAuthWrapper/authClient

FirebaseAuthWrapper/authClient.doSignOut()

Kind: static method of FirebaseAuthWrapper/authClient

FirebaseAuthWrapper/authClient.doPasswordReset()

Kind: static method of FirebaseAuthWrapper/authClient

FirebaseAuthWrapper/authClient.doSendEmailVerification()

Kind: static method of FirebaseAuthWrapper/authClient

FirebaseAuthWrapper/authClient.doPasswordUpdate()

Kind: static method of FirebaseAuthWrapper/authClient

FirebaseAuthWrapper/authClient.createAnonymousUser() ⇒ Promise.<UserCredential>

Kind: static method of FirebaseAuthWrapper/authClient

FirebaseAuthWrapper/authClient.attachAuthUserListener() ⇒ callback

Kind: static method of FirebaseAuthWrapper/authClient
Returns: callback - unsubscribe function
Properties

Name Type
next AuthChangeProcess

FirebaseAuthWrapper/authClient.setPersistence()

Kind: static method of FirebaseAuthWrapper/authClient

FirebaseAuthWrapper/authClient~fromJSON() : object

Kind: inner method of FirebaseAuthWrapper/authClient
Properties

Name Type
providerId string
signInMethod string

FirebaseAuthWrapper/authClient~AdditionalUserInfo : object

Kind: inner typedef of FirebaseAuthWrapper/authClient
Properties

Name Type
isNewUser boolean
profile object
providerId string
username string

FirebaseAuthWrapper/authClient~User : object

See https://firebase.google.com/docs/reference/js/firebase.User

Kind: inner typedef of FirebaseAuthWrapper/authClient

FirebaseAuthWrapper/authClient~UserCredential : object

Kind: inner typedef of FirebaseAuthWrapper/authClient
Properties

Name Type
additionalUserInfo AdditionalUserInfo
credential AuthCredential
operationType "signin" | "link" | "reauthenticate"
user "User"

FirebaseAuthWrapper/authClient~AuthChangeProcess : function

Kind: inner typedef of FirebaseAuthWrapper/authClient

Param Type
user User

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)

Initializes the FirebaseCLoud function support

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);

FirebaseCloudFunctionsWrapper.treeFromParams(Params) ⇒ RecordTree

Kind: static method of FirebaseCloudFunctionsWrapper
Sync:

Param Type
Params object

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.MAX_CONCURRENCY : number

maximum concurrent writes

Kind: static constant of FirebaseFirestoreWrapper

FirebaseFirestoreWrapper.FirebaseFirestore(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.createUniqueReference(tablePath, refPath) ⇒ DocumentReference

Creates a DocumentReference document to the collection referenced in parameter tablePath (relative to optional refPath). This is can be 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

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

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
Returns: Promise.<Record> - - a copy of the written record

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 existing 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
data.refPath string required to be present
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(tablePath, refPath, [filterArray], [sortArray], limit) ⇒ Promise.<Array.<Record>>

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

Param Type Description
tablePath string a properly formatted string representing the requested collection - always an ODD number of elements
refPath string (optional) allows "table" parameter to reference a sub-collection of an existing document reference (I use a LOT of structured collections)
[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.
[sortArray] sortObject a 2xn array of sort (i.e. "orderBy") conditions
limit number limit result to this number (if at all)

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], [sortArray], limit) ⇒ 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 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.
[sortArray] sortObject a 2xn array of sort (i.e. "orderBy") conditions
limit number limit result to this number (if at all)

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 optional - used to chain transactions

FirebaseFirestoreWrapper.localBatchReturn(incomingBatch, internalBatch) ⇒ WriteBatch | Transaction

Kind: static method of FirebaseFirestoreWrapper
Returns: WriteBatch | Transaction - WriteBatch, Transaction or Void

Param Type Description
incomingBatch WriteBatch | Transaction a batching object passed into the subroutine Internal Transaction will be added to the incoming batch
internalBatch WriteBatch | Transaction a batching object as built in the routine, built on the incomingBatch if it exists

Example

export const suboperation = (data, batch = null) => {
 let myBatch = batch || openWriteBatch(); //note short circuit
 //stuff that happens in the routine
 writeRecord(table, data, parent, myBatch);
 writeRecord(otherTable, otherData, otherParent, myBatch);
 return localBatchReturn(batch, myBatch);
}

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
Category: Batch

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

Creates a WriteBatch object tocollect actions for Batch writing to backend

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

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

Dispatches an asynchronous Closure to submit Batch

Kind: static method of FirebaseFirestoreWrapper
Category: Batch

Param Type Description
batch WriteBatch WriteBatch to close

FirebaseFirestoreWrapper.openBulkWriter() ⇒ BulkWriter

Creates a bulkWriter object to collect actions for Bulk writing to backend offers parallel operations, writes only, does NOT check for contentions, admin/Node-side only.

Kind: static method of FirebaseFirestoreWrapper
Returns: BulkWriter - object that operations are added to for a bulk operation
Category: Batch

FirebaseFirestoreWrapper.closeBulkWriter(bulkWriter) ⇒ Promise.<void>

Dispatches an asynchronous Closure to complete BulkWriter

Kind: static method of FirebaseFirestoreWrapper
Category: Batch

Param Type Description
bulkWriter BulkWriter bulkWriter to close

FirebaseFirestoreWrapper.documentId : Object

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
Category: FieldPath

FirebaseFirestoreWrapper.deleteFieldValue : Object

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

Kind: static constant of FirebaseFirestoreWrapper
Category: FieldValue

FirebaseFirestoreWrapper.serverTimestampFieldValue : Object

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

Kind: static constant of FirebaseFirestoreWrapper
Category: FieldValue

FirebaseFirestoreWrapper.incrementFieldValue(n) ⇒

return a sentinel to incrment/decrement a field

Kind: static method of FirebaseFirestoreWrapper
Returns: a sentinel value
Category: FieldValue

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.decrementFieldValue(n) ⇒

return a sentinel to decrment/decrement a field NOT REALLY A FIREBASE FUNCTION Fire base has only increment; we implement this for legibility

Kind: static method of FirebaseFirestoreWrapper
Returns: a sentinel value
Category: FieldValue

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
Category: FieldValue

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
Category: FieldValue

Param Description
elements REST expanded list of elements to add

FirebaseFirestoreWrapper.ListenRecords(tablePath, refPath, dataCallback, errCallback) ⇒ unsubscribe

sets up a listener for changes to a single record

Kind: static method of FirebaseFirestoreWrapper
Returns: unsubscribe - function to be called to release subscription
Category: Listeners

Param Type Description
tablePath string string describing relative path to document
refPath string string describing path to parent document
dataCallback CollectionListener function to be called with changes to record
errCallback callback function to be called when an error occurs in listener

FirebaseFirestoreWrapper.ListenQuery(tablePath, refPath, dataCallback, errCallback, [filterArray], [sortArray]) ⇒ unsubscribe

Sets up a listener to a query

Kind: static method of FirebaseFirestoreWrapper
Returns: unsubscribe - function to be called to release subscription
Category: Listeners

Param Type Description
tablePath string Name of table to query too - may be sub-collection of optional reference
refPath string An optional Firestore DocumentReference. If present, the "table" parameter above is relative to this reference
dataCallback CollectionListener callback function with query results
errCallback callback callback function with error results
[filterArray] filterObject a 3xn array of filter(i.e. "where") conditions
[sortArray] sortObject an (optional) 2xn array of sort (i.e. "orderBy") conditions

FirebaseFirestoreWrapper.ListenCollectionGroupRecords(tablePath, refPath, dataCallback, errCallback) ⇒ callback

sets up a listener for changes to a collectionGroup

Kind: static method of FirebaseFirestoreWrapper
Returns: callback - function to be called to release subscription
Category: Listeners

Param Type Description
tablePath string string describing relative path to document
refPath string string describing path to parent document
dataCallback CollectionListener function to be called with changes to record
errCallback callback function to be called when an error occurs in listener

FirebaseFirestoreWrapper.ListenCollectionGroupQuery(table, [filterArray], [sortArray], dataCallback, errCallback) ⇒ unsubscribe

sets up a listener for changes to a collectionGroup by query

Kind: static method of FirebaseFirestoreWrapper
Returns: unsubscribe - function to be called to release subscription
Category: Listeners

Param Type Description
table string string describing the name of a collectionGroup
[filterArray] filterObject a 3xn array of filter(i.e. "where") conditions
[sortArray] sortObject an (optional) 2xn array of sort (i.e. "orderBy") conditions
dataCallback CollectionListener function to be called with changes to record
errCallback callback function to be called when an error occurs in listener

FirebaseFirestoreWrapper.ListenRecord(tablePath, Id, refPath, dataCallback, errCallback) ⇒ unsubscribe

Listen to changes to a single record

Kind: static method of FirebaseFirestoreWrapper
Returns: unsubscribe - function to be called to release subscription
Category: Listeners

Param Type Description
tablePath string string describing relative path to requested record
Id string string of Id of requested document
refPath string string od full path to parent document
dataCallback RecordListener callback to handle changes to requested document
errCallback callback callback to handle error reporting and operations

FirebaseFirestoreWrapper.PaginateFetch

Kind: static class of FirebaseFirestoreWrapper
Category: Paginator

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

constructs an object to paginate through large Firestore Tables

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

paginateFetch.limit : number

current limit of query results

Kind: instance property of PaginateFetch

paginateFetch.status : PagingStatus

current status of pagination -1 pending; 0 uninitialized; 1 updated;

Kind: instance property of PaginateFetch

paginateFetch.PageForward() ⇒ Promise.<RecordArray>

executes the query again to fetch the next set of records

Kind: instance method of PaginateFetch
Returns: Promise.<RecordArray> - returns an array of record - the next page

paginateFetch.PageBack() ⇒ Promise.<RecordArray>

executes the query again to fetch the previous set of records

Kind: instance method of PaginateFetch
Returns: Promise.<RecordArray> - returns an array of record - the next page

FirebaseFirestoreWrapper.PaginateGroupFetch

Kind: static class of FirebaseFirestoreWrapper
Category: Paginator

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

constructs an object to paginate through large Firestore Tables

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)

paginateGroupFetch.limit : number

current limit basis for listener query

Kind: instance property of PaginateGroupFetch

paginateGroupFetch.status : PagingStatus

current status of listener -1 pending; 0 uninitialized; 1 updated;

Kind: instance property of PaginateGroupFetch

paginateGroupFetch.PageForward() ⇒ Promise.<RecordArray>

executes the query again to fetch the next set of records

Kind: instance method of PaginateGroupFetch
Returns: Promise.<RecordArray> - returns an array of record - the next page

paginateGroupFetch.PageBack() ⇒ Promise.<RecordArray>

executes the query again to fetch the previous set of records

Kind: instance method of PaginateGroupFetch
Returns: Promise.<RecordArray> - returns an array of record - the next page

FirebaseFirestoreWrapper.PaginatedListener

Kind: static class of FirebaseFirestoreWrapper
Category: Paginator

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

Creates 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

Param Type Default Description
tablePath string a properly formatted string representing the requested collection - always an ODD number of elements
refPath refPath (optional) allows "table" parameter to reference a sub-collection of an existing document reference (I use a LOT of structured collections)
dataCallback callback
errCallback callback
limit number (optional)
[filterArray] filterObject an (optional) 3xn array of filter(i.e. "where") conditions
[sortArray] sortObject a 2xn array of sort (i.e. "orderBy") conditions defaults to [{ fieldRef: "name", dirStr: "asc" }] as pagination requires a sort 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.

paginatedListener.limit : number

current limit basis for listener query

Kind: instance property of PaginatedListener

paginatedListener.status : number

current status of listener

Kind: instance property of PaginatedListener

paginatedListener.PageForward() ⇒ unsubscribe

resets the listener query to the next page of results. Unsubscribes from the current listener, constructs a new query, and sets it as the new listener

Kind: instance method of PaginatedListener
Returns: unsubscribe - returns the unsubscriber function (for lifecycle events)

paginatedListener.PageBack() ⇒ unsubscribe

resets the listener query to the next page of results. Unsubscribes from the current listener, constructs a new query, and sets it
as the new listener

Kind: instance method of PaginatedListener
Returns: unsubscribe - returns the unsubscriber function (for lifecycle events)

paginatedListener.ChangeLimit(newLimit) ⇒ unsubscribe

sets page size limit to new value, and restarts the paged listener

Kind: instance method of PaginatedListener
Returns: unsubscribe - returns the unsubscriber function (for lifecycle events)

Param Type
newLimit number

paginatedListener.ChangeFilter([filterArray]) ⇒ unsubscribe

changes the filter on the subscription This has to unsubscribe the current listener, create a new query, then apply it as the listener

Kind: instance method of PaginatedListener
Returns: unsubscribe - returns the unsubscriber function (for lifecycle events)

Param Type Description
[filterArray] filterObject an array of filter descriptors

paginatedListener.unsubscribe()

IF unsubscribe function is set, run it.

Kind: instance method of PaginatedListener

FirebaseFirestoreWrapper.ownerFilter(owner, queryFilter) ⇒ filterObject

Contructs a filter that selects only the "owner" section of a collectionGroup query - in other words, descendents of a particular top=level document. This takes advantage of Firestore's indexing, which "names"/indexes all documents using the FULL PATH to the document, starting from the top-most, i.e.: TOP_COLLECTION/{dociId}/NEXT_COLLECTION/{docId}/NEXT_NEXT_COLLECTION/{etc} This functions knowns NOTHING about the actual schema; it simply uses the path of the indicated "owner" as starting portion of ALL the "child" documents of the owner. It also takes advantage of the strictly alpha-numeric nature of the path string. As such, ALL children paths strings MUST be "greater than" the owner bare path, and MUST be LESS THAN the alpha-numerically "next" value: e.g. if the "owner" path is TOP_COLLECTION/abcdefg, then

/TOP_COLLECTION/abcdefh > name > //TOP_COLLECTION/abcdefg (assuming LEXICAL SORT) IMPORTANT NOTE: Because this filter uses an INEQUALITY, .sortBy() conditions are not supported

Kind: static method of FirebaseFirestoreWrapper
Category: Tree Slice

Param Type Description
owner Record
queryFilter filterObject additional filter parameters

FirebaseFirestoreWrapper.listenSlice(owner, collectionName, dataCallback, response, errCallback, response) ⇒ callback

Uses the ownerFilter (above) to establish a listener to "just" the parts of a collectionGroup that are descendants of the passed "owner" record.

Kind: static method of FirebaseFirestoreWrapper
Returns: callback - function to be called to release subscription
Category: Tree Slice

Param Type Description
owner Record
owner.refPath string string representing the full path to the Firestore document.
collectionName string name of the desired collectionGroup
dataCallback callback function to be called with changes to record
response QuerySnapshot
errCallback callback function to be called when an error occurs in listener
response string

FirebaseFirestoreWrapper.fetchSlice(owner, collectionName) ⇒ QuerySnapshot

Wrapper around database fetch, using ownerFilter above to select/fetch just an "owner" parent document's descendants from a collectionGroup

Kind: static method of FirebaseFirestoreWrapper
Returns: QuerySnapshot - response
Category: Tree Slice

Param Type Description
owner Record
owner.refPath string string representing the full path to the Firestore document.
collectionName string name of the desired collectionGroup

FirebaseFirestoreWrapper.querySlice(owner, collectionName, queryFilter) ⇒ QuerySnapshot

Wrapper around database fetch, using ownerFilter above to select/fetch just an "owner" parent document's descendants from a collectionGroup

Kind: static method of FirebaseFirestoreWrapper
Returns: QuerySnapshot - response
Category: Tree Slice

Param Type Description
owner Record
owner.refPath string string representing the full path to the Firestore document.
collectionName string name of the desired collectionGroup
queryFilter filterObject filter parameters

FirebaseFirestoreWrapper.listenQuerySlice(owner, collectionName, filterArray, dataCallback, response, errCallback, response) ⇒ callback

Uses the ownerFilter (above) to establish a listener to "just" the parts of a collectionGroup that are descendants of the passed "owner" record.

Kind: static method of FirebaseFirestoreWrapper
Returns: callback - function to be called to release subscription
Category: Tree Slice

Param Type Description
owner Record
owner.refPath string string representing the full path to the Firestore document.
collectionName string name of the desired collectionGroup
filterArray filterObject filter parameters
dataCallback callback function to be called with changes to record
response QuerySnapshot
errCallback callback function to be called when an error occurs in listener
response string

FirebaseFirestoreWrapper.ownerType(record) ⇒ string

Returns the "type" (collection name) of the top-most parent of a record, derived from the refPath

Kind: static method of FirebaseFirestoreWrapper
Returns: string - the collection name
Category: Tree Slice

Param Type
record Record

FirebaseFirestoreWrapper.ownerId(record) ⇒ string

Returns the Id (documentId) of the top-most parent of a record, derived from the refPath

Kind: static method of FirebaseFirestoreWrapper
Returns: string - the Id
Category: Tree Slice

Param Type
record Record

FirebaseFirestoreWrapper.ownerRefPath(record) ⇒ string

Returns the Id (documentId) of the top-most parent of a record, derived from the refPath

Kind: static method of FirebaseFirestoreWrapper
Returns: string - the Id
Category: Tree Slice

Param Type
record Record

FirebaseFirestoreWrapper.ownerByChild(record) ⇒ Record

Returns the bare owner record reference to the parent (root) of a provided child

Kind: static method of FirebaseFirestoreWrapper
Returns: Record - reference to the parent (root) record
Category: Tree Slice

Param Type Description
record Record child record

FirebaseFirestoreWrapper.ownerByOwnerType(ownerId, ownerType) ⇒ Record

Kind: static method of FirebaseFirestoreWrapper
Returns: Record - reference to the parent (root) record
Category: Tree Slice

Param Type Description
ownerId string Document ID of owner account
ownerType string "type" (top-level collection) of owner account

FirebaseFirestoreWrapper.fetchOwner(record) ⇒ Document

returns the record for the top-most parent of a record, derived from the refPath

Kind: static method of FirebaseFirestoreWrapper
Category: Tree Slice

Param Type
record Record

FirebaseFirestoreWrapper.recordType(record) ⇒ string

Returns the "type" (collection name) the passed record is stored in, derived from the refPath

Kind: static method of FirebaseFirestoreWrapper
Returns: string - the collection name
Category: Typed

Param Type
record Record

FirebaseFirestoreWrapper.recordId() ⇒ string

Returns the Id (documentId) of the passed record derived from the refPath

Kind: static method of FirebaseFirestoreWrapper
Returns: string - the Id
Category: Typed

FirebaseFirestoreWrapper.typedWrite(data, parent, type, batch) ⇒ Promise.<Record>

optionally batched record update - abstracts batch process from specific types

Kind: static method of FirebaseFirestoreWrapper
Returns: Promise.<Record> - record, with Id & refpath
Category: Typed

Param Type Description
data Record the data object/record to update. This will create a new one if it doesn't exist
data.refPath string only part used
parent Record parent object (if any) this belongs to
parent.refPath string full path to parent document
type string name of type of object - i.e. the sub-collection name
batch WriteBatch | Transaction batching object. Transaction will be added to the batch

FirebaseFirestoreWrapper.typedWriteByTree(data, tree, type, batch) ⇒ Promise

optionally batched record update - abstracts batch process from specific types

Kind: static method of FirebaseFirestoreWrapper
Returns: Promise - record, with Id & refpath
Category: Typed

Param Type Description
data Record the data object/record to update. This will create a new one if it doesn't exist
tree ArtistTree Object with properties of refPath segments
type string name of type of object - i.e. the sub-collection name
batch WriteBatch | Transaction batching object. Transaction will be added to the batch

FirebaseFirestoreWrapper.typedWriteByChild(data, tree, type, batch) ⇒ Promise

optionally batched record update - abstracts batch process from specific types

Kind: static method of FirebaseFirestoreWrapper
Returns: Promise - WriteBatch, Transaction or Void
Category: Typed

Param Type Description
data Record the data object/record to update. This will create a new one if it doesn't exist
tree ArtistTree Object with properties of refPath segments
type string name of type of object - i.e. the sub-collection name
batch WriteBatch | Transaction batching object. Transaction will be added to the batch

FirebaseFirestoreWrapper.typedCreate(data, parent, type, batch) ⇒ Promise

Creates a new document reference of the indicated type, and writes it to the backend. Specific intent is when the Id needs to be pre-specified, or shared outside this function. Normal writing action will silently create a new document, which has to then be found by query

Kind: static method of FirebaseFirestoreWrapper
Returns: Promise - WriteBatch, Transaction or Void
Category: Typed

Param Type Description
data Record the data object/record to create. This will create a new one if it doesn't exist
parent Record parent object (if any) this belongs to
parent.refPath string full path to parent document
type string name of type of object - i.e. the sub-collection name
batch WriteBatch | Transaction batching object. Transaction will be added to the batch

FirebaseFirestoreWrapper.treeFromChild(child) ⇒ RecordTree

Extracts a tree of document ID's from a child document (assumes is a child)

Kind: static method of FirebaseFirestoreWrapper
Category: Typed

Param Type Description
child Record document (regardless of depth) of a tree
child.refPath string

FirebaseFirestoreWrapper.typedTablePathFromTree(tree, type, branchType) ⇒ string

Builds a refPath down to a desired collection/type from an existing RecordTree Map.

Kind: static method of FirebaseFirestoreWrapper
Returns: string - constructed TablePath (collection)
Category: Typed

Param Type Description
tree RecordTree
type string
branchType string a collection name to start branching from. This is in case tree was built from a sister collection/document

FirebaseFirestoreWrapper.typedRefPathFromTree(tree, type) ⇒ string

Builds a refPath down to a desired collection/type from an existing RecordTree Map.

Kind: static method of FirebaseFirestoreWrapper
Returns: string - constructed refPath (document)
Category: Typed

Param Type
tree RecordTree
type string

FirebaseFirestoreWrapper.typedIdFromChild(child, type)

Looks up a "tree" to find the Id of the document at the requested collection level ("type")

Kind: static method of FirebaseFirestoreWrapper
Category: Typed

Param Type Description
child Record document (regardless of depth) of a tree
child.refPath string
type string name of desired type/collection level in tree

FirebaseFirestoreWrapper.typedTablePathFromChild(child, type) ⇒ string

Builds a refPath up to a desired collection/type from an existing child in a tree

Kind: static method of FirebaseFirestoreWrapper
Returns: string - constructed refPath (collection)
Category: Typed

Param Type Description
child Record document (regardless of depth) of a tree
child.refPath string
type string

FirebaseFirestoreWrapper.typedRefPathFromChild(child, type) ⇒ string

Builds a refPath up to a desired collection/type from an existing child in a tree

Kind: static method of FirebaseFirestoreWrapper
Returns: string - constructed refPath (document)
Category: Typed

Param Type Description
child Record document (regardless of depth) of a tree
child.refPath string
type string

FirebaseFirestoreWrapper.typedFetchFromChild(child, refPath, type, batch) ⇒ Promise.<RecordObject>

function to fetch a document from "up" the collection/document tree of a child document

Kind: static method of FirebaseFirestoreWrapper
Category: Typed

Param Type Description
child Record assumed to be an object in a collection/document Tree
refPath string
type string type/collection to fetch parent document from
batch WriteBatch | Transaction optional batch object to chain

FirebaseFirestoreWrapper.typedFetchFromTree(tree, refPath, type, batch) ⇒ Promise.<RecordObject>

function to fetch a document from "up" the collection/document tree of a child document

Kind: static method of FirebaseFirestoreWrapper
Category: Typed

Param Type Description
tree RecordTree assumed to be an object in a collection/document Tree
refPath string
type string type/collection to fetch parent document from
batch WriteBatch | Transaction optional batch object to chain

FirebaseFirestoreWrapper.typedCollectFromTree(tree, type, batch) ⇒ Promise.<RecordArray>

function to collect documents from "up" the collection/document tree of a child document

Kind: static method of FirebaseFirestoreWrapper
Category: Typed

Param Type Description
tree RecordTree assumed to be an object in a collection/document Tree
type string type/collection to fetch parent document from
batch WriteBatch | Transaction optional batch object to chain

FirebaseFirestoreWrapper.typedCollectFromChild(child, type, batch)

function to collect documents from "up" the collection/document tree of a child document

Kind: static method of FirebaseFirestoreWrapper
Category: Typed

Param Type Description
child Record assumed to be an object in a collection/document Tree
type string type/collection to fetch parent document from
batch WriteBatch | Transaction optional batch object to chain

FirebaseFirestoreWrapper~timestamp

Kind: inner class of FirebaseFirestoreWrapper

new timestamp()

class for a Firestore timestamp processor

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.

FirebaseStorageWrapper.FirebaseStorageWrapper(firebase)

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

Kind: static method of FirebaseStorageWrapper

Param Type
firebase firebase

Example

import * as firebase from "firebase/app";
import "firebase/storage";
import FirebaseStorage from "@leaddreamer/firebase-wrapper/FirebaseStorageWrapper";
import {config} from "whereever-you-put-it";

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

FirebaseStorageWrapper.makeStorageRefFromRecord(record, key, filename) ⇒ StorageReference

Kind: static method of FirebaseStorageWrapper
Returns: StorageReference - a Firestore Storage Reference

Param Type Description
record string A firestore document Record - the '/' separated collection/ document path is used as the path to the stored item.
key string An optional string identifying the specific field an stored item is associated with
filename string an optional name to be associated with the stored item.

FirebaseStorageWrapper.listReference(storageReference, optionsObject) ⇒ ListResult

Kind: static method of FirebaseStorageWrapper

Param Type Description
storageReference StorageReference a storage reference to a "directory", not a file. More accurate to state that it is treated as a directory, since such niceties are a Firestore convention, not a physical reality
optionsObject ListOptions

FirebaseStorageWrapper.makeFileURLFromRecord(record, key, filename) ⇒ external:promise

Kind: static method of FirebaseStorageWrapper
Fulfil: string a "long-lived" URL to access the file.
Reject: string

Param Type Description
record RecordObject A firestore document Record - the '/' separated collection/ document path is used as the path to the stored item.
key string An optional string identifying the specific field an stored item is associated with
filename string an optional name to be associated with the stored item.

FirebaseStorageWrapper.makePrivateURLFromRecord(record, key) ⇒ string

Kind: static method of FirebaseStorageWrapper
Returns: string - The resulting Security-Rule-compliant URL

Param Type Description
record RecordObject A firestore document Record - the '/' separated collection/ document path is used as the path to the stored item.
key string An optional string identifying the specific field an stored item is associated with

FirebaseStorageWrapper.makePrivateURLFromReference(reference, key) ⇒ string

Kind: static method of FirebaseStorageWrapper
Returns: string - The resulting Security-Rule-compliant URL

Param Type Description
reference StorageReference A firestore document Record - the '/' separated collection/ document path is used as the path to the stored item.
key string An optional string identifying the specific field an stored item is associated with

FirebaseStorageWrapper.makePrivateURLFromPath(fullPath) ⇒ string

This function is part of a storage scheme that uses parallel structures between Firestore collection/documents and Storage paths. The concept here is all Storage items are part of/belong to Firestore documents. This function takes a full path to a Storage object and turns it into URL. If "type"is not included, the URL will return the metadata, not the contents. Note this simply makes the URL - it does not carry out any operations

Kind: static method of FirebaseStorageWrapper
Returns: string - constructed Security-Rule-compliant URL

Param Type Description
fullPath string required path to the stored item.

FirebaseStorageWrapper.storeBlobByRecord(blob, record, key, filename) ⇒ UploadTask

Firestore's document sizes can be limited - 1MB - so our system stores larger digital "blobs" in a parallel Firestore Storage.

Kind: static method of FirebaseStorageWrapper
Returns: UploadTask - Firestore Storage UploadTask Object

Param Type Description
blob blob A data blob in DataURI format to store in Storage
record RecordObject A firestore document Record - the '/' separated collection/ document path is used as the path to the stored item.
key string An optional string identifying the specific field an stored item is associated with
filename string an optional name to be associated with the stored item.

FirebaseStorageWrapper.storeDataURLByRecord(dataURL, record, key, filename) ⇒

Firestore's document sizes can be limited - 1MB - so our system stores larger digital "blobs" in a parallel Firestore Storage.

Kind: static method of FirebaseStorageWrapper
Returns: Firestore Storage UploadTask Object

Param Type Description
dataURL dataURL A data blob in DataURI format to store in Storage
record RecordObject A firestore document Record - the '/' separated collection/ document path is used as the path to the stored item.
key string An optional string identifying the specific field an stored item is associated with
filename string an optional name to be associated with the stored item.

FirebaseStorageWrapper.getDefaultImageURL(key) ⇒ string

Kind: static method of FirebaseStorageWrapper

Param Type Description
key string name/key of default image file

FirebaseStorageWrapper.getURLFromFilePath(filePath) ⇒ string

Kind: static method of FirebaseStorageWrapper

Param Type
filePath string

FirebaseStorageWrapper.dataURLToBlob(dataURL) ⇒ Object

Kind: static method of FirebaseStorageWrapper
Returns: Object - {ext: extension, base64: data}

Param Type
dataURL object

FirebaseStorageWrapper~File : object

Kind: inner typedef of FirebaseStorageWrapper
Properties

Name Type Description
metadata FileMetadata
acl object
name string //various methods

FirebaseStorageWrapper~FileMetadata : object

Kind: inner typedef of FirebaseStorageWrapper
Properties

Name Type Description
kind string:"storage#object"
id string
selfLink string
name string
bucket string
generation long
metageneration long
contentType string
timeCreated datetime
updated datetime
customTime datetime
timeDeleted datetime
temporaryHold boolean
eventBasedHold boolean
retentionExpirationTime datetime
storageClass string
timeStorageClassUpdated datetime
size ulong
md5Hash string
mediaLink string
contentEncoding string
contentDisposition string
contentLanguage string
cacheControl string
metadata object Custom metadata key:value pairs
metadata.firebaseStorageDownloadTokens string
metadata.key string
[acl] objectAccessControls
owner object
owner.entity string
owner.entityId string
crc32c string
componentCount integer
etag string
customerEncryption object
customerEncryption.encryptionAlgorithm string
customerEncryption.keySha256 string
kmsKeyName string

FirebaseStorageAdminEmulator

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

  • FirebaseStorageAdminEmulator
    • static
    • inner
      • ~adminRef
      • [~child creates and returns a new adminRef object from existin path(path)](#module_FirebaseStorageAdminEmulator..child creates and returns a new adminRef object from existin path) ⇒ StorageRefEmulation
      • [~delete Deletes the referenced storage item()](#module_FirebaseStorageAdminEmulator..delete Deletes the referenced storage item) ⇒ Promise
      • [~getDownloadURL Generates a long-lived (essentially permanent until revoked) Public-Access URL for a storage item in FIREBASE (not Cloud Storage) format()](#module_FirebaseStorageAdminEmulator..getDownloadURL Generates a long-lived (essentially permanent until revoked) Public-Access URL for a storage item in FIREBASE (not Cloud Storage) format) ⇒ string
      • [~getToken Fetches (or creates as needed) a unique token for a storage object()](#module_FirebaseStorageAdminEmulator..getToken Fetches (or creates as needed) a unique token for a storage object) ⇒ Promise.<string>
      • [~getMetadata Fetches the FileMetadata for the storage object. Custom/Client metadata is located in FileMetadata.metadata()](#module_FirebaseStorageAdminEmulator..getMetadata Fetches the FileMetadata for the storage object. Custom/Client metadata is located in FileMetadata.metadata) ⇒ FileMetadata
      • ~put(data, metadata) ⇒ Promise.<object>
      • ~putString(dataString, stringFormat, metadata) ⇒ Promise.<object>

FirebaseStorageAdminEmulator.FirebaseStorageAdminEmulator(firebase)

Initializes the Storage service of the provided firebase app. Also instantiates various constants and helper functions. This is a WRAPPER around CLOUD STORAGE (admin) functions to emulate FIREBASE functionality, keeping a similar API between client & cloud code. NOTE: admin "references" ARE NOT the same as client references, and are NOT interchangeable. Do not mix client & admin code (not actually possible in this wrapper)

Kind: static method of FirebaseStorageAdminEmulator

Param Type
firebase firebase

FirebaseStorageAdminEmulator~adminRef

Kind: inner class of FirebaseStorageAdminEmulator

new adminRef(bucket, path)

Create a class that emulates a Firebase Storage storageRef using Firebase Admin Cloud Storage Functions. This is not an exact replica, but one with similar static members and methods. Intended for use with a higher-level Wrapper library This returns an object that has many of the same members and methods as a Firebase storageRef, but only in conjunction with the methods here, and likely only with the "wrapper" it is defined for.

Param Type Description
bucket StorageBucket A bucket instance
path string a string representing the "path" to the intended target document

adminRef.fileRef : storageRef

used to affect file operations to emulate Firebase Storage functions

Kind: instance property of adminRef

adminRef.fullPath : string

Full path, including file name

Kind: instance property of adminRef

adminRef.name : string

filename portion only

Kind: instance property of adminRef

adminRef.bucket : string

name of containing bucket

Kind: instance property of adminRef

adminRef.parent : storageRef

Cloud Storage object don't really have a parent or root

Kind: instance property of adminRef

adminRef.storage : storageApp

app instance

Kind: instance property of adminRef

adminRef.metadata : string

access token

Kind: instance property of adminRef

FirebaseStorageAdminEmulator~child

creates and returns a new adminRef object from existin path(path) ⇒ StorageRefEmulation Kind: inner method of FirebaseStorageAdminEmulator

Param Type Description
path string a relative path from the existing storageRef to create child

FirebaseStorageAdminEmulator~delete

Deletes the referenced storage item() ⇒ Promise Kind: inner method of FirebaseStorageAdminEmulator

FirebaseStorageAdminEmulator~getDownloadURL

Generates a long-lived (essentially permanent until revoked) Public-Access URL for a storage item in FIREBASE (not Cloud Storage) format() ⇒ string Kind: inner method of FirebaseStorageAdminEmulator

FirebaseStorageAdminEmulator~getToken

Fetches (or creates as needed) a unique token for a storage object() ⇒ Promise.<string> Kind: inner method of FirebaseStorageAdminEmulator

FirebaseStorageAdminEmulator~getMetadata

Fetches the FileMetadata for the storage object. Custom/Client metadata is located in FileMetadata.metadata() ⇒ FileMetadata Kind: inner method of FirebaseStorageAdminEmulator

FirebaseStorageAdminEmulator~put(data, metadata) ⇒ Promise.<object>

puts a block of data (and optional metadata) into storage at location specified by adminRef

Kind: inner method of FirebaseStorageAdminEmulator

Param Type
data blob
metadata object

FirebaseStorageAdminEmulator~putString(dataString, stringFormat, metadata) ⇒ Promise.<object>

puts a string (possibly encoded data) into a storage file described by the provided reference.

Kind: inner method of FirebaseStorageAdminEmulator

Param Type
dataString string
stringFormat string
metadata FileMetadata

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. NOTE: Most helpers return PROMISE.REJECT if no documents are returned. it is assumed projects using this library might want to have an explicitly error trap for such events.

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
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~FirebaseConfigObject : Object

only authDomain, databaseURL and storageBucket are present when called from a cloud environment

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

only authDomain, databaseURL and storageBucket are present when called from a cloud environment

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

PAGINATE_INIT : number

Kind: global constant
Category: Paginate Constants

PAGINATE_PENDING : number

Kind: global constant
Category: Paginate Constants

PAGINATE_UPDATED : number

Kind: global constant
Category: Paginate Constants

PAGINATE_END : number

Kind: global constant
Category: Paginate Constants

PAGINATE_DEFAULT : number

Kind: global constant
Category: Paginate Constants

PAGINATE_CHOICES : number

Kind: global constant
Category: Paginate Constants

© 2020-2021 Tracy Hall

About

Created with CodeSandbox

codesandbox.io/s/github/LeadDreamer/firebase-wrapper

Resources

Readme
Activity

Stars

2 stars

Watchers

1 watching

Forks

2 forks
Report repository

Releases

No releases published

Packages

No packages published

Languages