leylo
Installation | Requirements | Usage | Demo | 📚 API |
---|
Asynchronous utility functions for Firestore within Vue CLI 3.
demo site here with source code here
See a▸ Installation
npm install leylo
If not using Firebase Hosting, there's no need to npm install firebase
or npm install firebase-tools
. Just plug in the credentials within your .env
and you're good to go!
▸ Requirements
You must have a .env
file at the root of your Vue CLI 3 repo containing the following key/value pairs (template available in this repo):
VUE_APP_FIREBASE_APIKEY=...VUE_APP_FIREBASE_AUTHDOMAIN=...VUE_APP_FIREBASE_DATABASEURL=...VUE_APP_FIREBASE_PROJECTID=...VUE_APP_FIREBASE_STORAGEBUCKET=...VUE_APP_FIREBASE_MESSAGINGSENDERID=...VUE_APP_FIREBASE_APPID=...
No quotation marks needed in .env
values above
▸ Usage
📚 API
All methods are accessible as properties of leylo
, as in leylo.docExists(...)
.
📗 Global
📙 Retrieving Data
📘 Adding Data
📕 Deleting Data
◤ 📗 Global
◤ Click these arrows to return to the top of the API
.db
Returns Object
of interior Firestore
used for all queries.
console;// Returns Firestore {_queue: AsyncQueue, INTERNAL: {…}, _config: FirestoreConfig, _databaseId: DatabaseId, _dataConverter: UserDataConverter, …}
Can be used as an alias to any custom Firestore
query or method:
let query = leylodb; query ;
◤ 📙 Retreiving Data
- leylo.docExists()
- leylo.collectionExists()
- leylo.getPath()
- leylo.getCollection()
- leylo.getDocById()
- leylo.getDocByField()
- leylo.getDocByQuery()
- leylo.getAllDocsByField()
- leylo.getAllDocsByQuery()
- leylo.getDocIdByField()
- leylo.getDocPathByField()
- leylo.streamCollection()
- leylo.streamPath()
- leylo.streamDocChangesById()
- leylo.streamDocChangesByField()
- leylo.streamDocChangesByQuery()
▲ .docExists(collection, id)
▲ Click these arrows to return to the top of each segment
Returns Boolean
of whether document with specified id
is found in Firestore
collection
[String] - Name of collectionid
[String] - Name/ID of document within collection
// WITHIN ASYNC FUNCTIONlet validation = await leylo;console; // Returns true // OR THENABLEleylo;
▲ .collectionExists(collection)
Returns Boolean
of whether collection with specified name is found in Firestore
collection
[String] - Name of collection
let validation = await leylo;console; // Returns true
▲ .getPath(path[, getData?])
Returns Array
if collection, Object
if document, or Any
if field of specified path
or False
if not found
path
[String] - Path in the form collection or collection/documentgetData
[Boolean] (Default: true) - Iftrue
returnsdocumentSnapshot.data()
else returnsdocumentSnapshot
// Simple grab all documents within a collection:let userList = await leylo;console; // Returns [{…}, {…}, {…}, {…}, {…}] // Simple grab single document from specific collection/document path:let certainUser = await leylo;console; // Returns { name: 'Tom Scharstein', ... } // Simple grab value from specific collection/document/field path:let certainUserLocation = await leylo;console; // Returns 'Arizona' // Add all documents to a specified array in component's datalet doSomethingEveryUser = await leylo; doSomethingEveryUser; // When adding to pre-existing array, add items which don't already exist in that array:let addUsersAgain = await leylo;addUsersAgain;
▲ .getCollection(collection[, getData?])
Returns Array
of Object
s within specified collection or False
if not found
collection
[String] - Name of collectiongetData
[Boolean] (Default: true) - Iftrue
returnsdocumentSnapshot.data()
else returnsdocumentSnapshot
// Simple grab all documents within a collection:let userList = await leylo;console; // Returns [{…}, {…}, {…}, {…}, {…}] // If needing to grab the Document Reference, we can pass false to getData:let doSomethingEveryUser = leylo; let doSomethingAsyncForList = await leylo;console;Promiseall doSomethingAsyncEveryUser;console;// Now continue to next code
▲ .getDocById(collection, id[, getData?])
Returns Object
with specified id
in Firestore or False
if not found
collection
[String] - Name of collectionid
[String] - Name/ID of document within collectiongetData
[Boolean] (Default: true) - Iftrue
returnsdocumentSnapshot.data()
else returnsdocumentSnapshot
let user = await leylo;console; // Returns { name: 'Tom Scharstein', ... }
▲ .getDocByField(collection, field, value[, getData?])
Returns Object
with specified field
= value
in Firestore or False
if not found
collection
[String] - Name of collectionfield
[String] - Name of key/field of target documentvalue
[String] - Value of key/field of target documentgetData
[Boolean] (Default: true) - Iftrue
returnsdocumentSnapshot.data()
else returnsdocumentSnapshot
let user = await leylo;console; // Returns { name: 'Tom Scharstein', ... }
▲ .getAllDocsByField(collection, field, value[, getData?])
Returns Array
of every Object
with specified field
= value
in collection or False
if none found
collection
[String] - Name of collectionfield
[String] - Name of key/field of target documentvalue
[String] - Value of key/field of target documentgetData
[Boolean] (Default: true) - Iftrue
returnsdocumentSnapshot.data()
else returnsdocumentSnapshot
let usersInArizona = await leylo;// Returns [ {...}, {...}, {...} ]usersInArizona;
▲ .getDocIdByField(collection, field, value)
Same as using
await leylo.getDocByField("users", "name", "Tom Scharstein", false).id
Returns String
of specified field
= value
document's id
in collection or False
if not found
collection
[String] - Name of collectionfield
[String] - Name of key/field of target documentvalue
[String] - Value of key/field of target document
// If we don't know the path to our document, but know a certain key/value pair only it has:let userId = await leylo;console; // Returns 'Inventsable' // We can query it to return the Document.id, and know the path must be users/Inventsable let checkPath = await leylo;console; // Returns { name: 'Tom Scharstein', location: 'Arizona', ... }
▲ .getDocPathByField(collection, field, value)
Same as using
await leylo.getDocByField("users", "name", "Tom Scharstein", false).ref.path
Returns String
with specified field
= value
document's path in Firestore or False
if not found
collection
[String] - Name of collectionfield
[String] - Name of key/field of target documentvalue
[String] - Value of key/field of target document
let fullPathToUser = await leylo;console; // Returns 'users/Inventsable'
▲ .getDocByQuery(collection, field, query, value[, getData?])
Returns first Object
found with specified field
(query)
value
in Firestore or False
if not found
collection
[String] - Name of collectionfield
[String] - Name of key/field of target documentquery
[String] - One of==
,>=
,<=
,>
,<
,array_contains
or valid Firebase query stringvalue
[String] - Value of key/field of target documentgetData
[Boolean] (Default: true) - Iftrue
returnsdocumentSnapshot.data()
else returnsdocumentSnapshot
// Grab the first user containing key of temperature less than or equal to 10let userInAlaska = await leylo; console; // Returns { name: 'John Doe' } // Grab the first user where temperature is greator or equal to 10 as DocumentReferencelet userNotInAlaska = await leylo; console; // Returns 'users/Inventsable'
▲ .getAllDocsByQuery(collection, field, query, value[, getData?])
Returns Array
of every Object
with specified field
(query)
value
in Firestore or False
if none found
collection
[String] - Name of collectionfield
[String] - Name of key/field of target documentquery
[String] - One of==
,>=
,<=
,>
,<
,array_contains
or valid Firebase query stringvalue
[String] - Value of key/field of target documentgetData
[Boolean] (Default: true) - Iftrue
returnsdocumentSnapshot.data()
else returnsdocumentSnapshot
// Get Array of all documents where temperature field contains value greater or equal to 110let placeTooHotToLiveIn = await leylo;console // Returns [ {...}, {...}, {...} ] placeTooHotToLiveIn;
▲ .streamCollection(collection[, callback, changeType, getData?])
Cannot be detached -- if needing programmatic detachment use .streamPath() instead
Returns every matching result of passing document Object
as parameter to callback
every time the collection is modified. Initial results are same as this.getCollection()
but reactive and continuous to catch any docs added to this collection later and execute callback on them as well.
collection
[String] - Name of collectioncallback
[Function] (Default: null) - Function to execute on every change to document. Ifnull
, returns directObject
according togetData
parameterchangeType
[String] (Default: null) - Ifnull
listen to all, else one ofadded
,modified
, orremoved
getData
[Boolean] (Default: true) - Iftrue
passesquerySnapshot.docChanges().data()
tocallback
else passesquerySnapshot.docChanges()
// Simple usage:let streamUsers = await leylo; // From the demo page:let addUserStream = await leylo; // Above is the same as:let addUserStream = await leylo; // Automatically remove user from this.userList via method:async { this}methods: async { return await leylo; }
▲ .streamPath(path[, callback, changeType, getData?])
Returns Object
which can be programmatically detached, but still executes callback
on any document/data.
path
[String] - Any valid path fromcollection
tocollection/document
callback
[Function] (Default: null) - Function to execute on every change to document. Ifnull
, returns directObject
according togetData
parameterchangeType
[String] (Default: null) - Ifnull
listen to all, else one ofadded
,modified
, orremoved
getData
[Boolean] (Default: true) - Iftrue
passesquerySnapshot.docChanges().data()
tocallback
else passesquerySnapshot.docChanges()
async { // Starts the stream this; // The method below results in a `Hello NAME` statement for any user added until the stream is detached. }methods: async { thisuserStream = await leylo; } async { // Firestore's detachment is odd. You have to call the stream as a function: this; }
▲ .streamDocChangesById(collection, id[, callback, changeType, getData?])
Returns result of passing document Object
as parameter to callback
every time the document is modified
collection
[String] - Name of collectionid
[String] - Name/ID of document within collectioncallback
[Function] (Default: null) - Function to execute on every change to documentchangeType
[String] (Default: null) - Ifnull
listen to all, else one ofadded
,modified
, orremoved
getData
[Boolean] (Default: true) - Iftrue
passesquerySnapshot.docChanges().data()
tocallback
else passesquerySnapshot.docChanges()
// Can do this during created(), mounted() or some init functionlet messages = await leylo; let userList = await leylo; // Passing the data from above stream into one of our component's methods:methods: { console console }
▲ .streamDocChangesByField(collection, field, value[, callback, changeType, getData?])
Returns result of passing document Object
as parameter to callback
every time a document's field is modified
collection
[String] - Name of collectionfield
[String] - Name of key/field of target documentvalue
[String] - Value of key/field of target documentcallback
[Function] (Default: null) - Function to execute on every change to documentchangeType
[String] (Default: null) - Ifnull
listen to all, else one ofadded
,modified
, orremoved
getData
[Boolean] (Default: true) - Iftrue
passesquerySnapshot.docChanges().data()
tocallback
else passesquerySnapshot.docChanges()
let usersCurrentlyInArizona = await leylo;
▲ .streamDocChangesByQuery(collection, field, query, value[, callback, changeType, getData?])
Returns every matching result of passing document Object
as parameter to callback
every time the document is modified
collection
[String] - Name of collectionfield
[String] - Name of key/field of target documentquery
[String] - One of==
,>=
,<=
,>
,<
,array_contains
or valid Firebase query stringvalue
[String] - Value of key/field of target documentcallback
[Function] (Default: null) - Function to execute on every change to documentchangeType
[String] (Default: null) - Ifnull
listen to all, else one ofadded
,modified
, orremoved
getData
[Boolean] (Default: true) - Iftrue
passesquerySnapshot.docChanges().data()
tocallback
else passesquerySnapshot.docChanges()
let usersLeavingArizona = await leylo;
◤ 📘 Adding Data
- leylo.addDoc()
- leylo.addAllDocs()
- leylo.setPath()
- leylo.setDocByPath()
- leylo.setAllDocsByPath()
- leylo.setDocById()
- leylo.setAllDocsById()
- leylo.setFieldByPath()
- leylo.setFieldById()
▲ .addDoc(collection, data)
Returns DocumentReference
result of writing new document with auto-generated id to collection
collection
[String] - Name of collectiondata
[Object] - Contents of document to write
let user = await leylo; console; // Returns DocumentSnapshot{ ... }console; // Returns 'cmeJ6JeoTCIfvMvgE2ru', auto-generated idconsole; // Returns 'users/cmeJ6JeoTCIfvMvgE2ru'console; // Returns { name: 'Random', location: 'Random' }
▲ .addAllDocs(collection, ...docs)
Returns Array
of DocumentReference
s of newly written documents to collection
collection
[String] - Name of collectiondocs
[Array] - Array containingObject
s to be written as documents (without ids)
let newUsers = await leylo;console; // Returns [DocumentReference, DocumentReference]
▲ .setPath(path, data[, overwrite?])
Shorthand method for writing document or field, will parse
path
and redirect to either leylo.addDoc(), leylo.addDocById(), or leylo.setFieldByPath()
Returns Boolean
of whether the document/field was successfully written or Object
DocumentReference if path was only a collection
path
[String] - Path in the form collection/documentdata
[Any] - Contents of document to write or append. If writing document, should beObject
, but if field can be anything (except forArray
withinArray
per Firestore limitation)overwrite
[Boolean] (Default: false) - Iffalse
, merge newdata
with pre-existing document or overwrite if it already exists, but iftrue
replace document entirely with newdata
// Can be used to create new document or merge/add field into pre-existing documentlet setLocation = await leylo;console; // Returns true // If location already existed, rewrite it's contents to the new value:let newUser = await leylo;console; // Returns DocumentReference{ ... } // Rewrite individual field:let rewriteUserData = await leylo;console; // Returns true
▲ .setDocByPath(path, data[, overwrite?])
Unlike leylo.setPath(), this method will return an Error if path points to collection or field.
Returns Boolean
of whether the document was successfully written to collection
path
[String] - Path in the form collection/documentdata
[Object] - Contents of document to write or appendoverwrite
[Boolean] (Default: false) - Iffalse
, merge newdata
with pre-existing document or overwrite if it already exists, but iftrue
replace document entirely with newdata
// If user 'Inventsable' already has content but no location, merge it as a new field:let setLocation = await leylo;console; // Returns true // If location already existed, rewrite it's contents to the new value:let rewriteLocation = await leylo;console; // Returns true // If overwrite is true, replace document at path entirely:let rewriteUserData = await leylo; console; // Returns true
▲ .setAllDocsByPath(overwrite, ...docs)
Returns Array
of Boolean
s the length of docs
array for whether document was successfully written to Firestore
data
[Object] - Contents of document to write or appendoverwrite
[Boolean] (Default: false) - Iffalse
, merge newdata
with pre-existing document or overwrite if it already exists, but iftrue
replace document entirely with newdata
// Each data is an array in the form [ 'path', contents]let users = "users/Inventsable" name: "Tom" "users/somePerson" name: "John" "users/someOtherPerson" name: "Jane" ; let writeUsers = await leylo;console; // Returns [true, true, true] let newLocations = "users/Inventsable" location: "Arizona" "users/somePerson" location: "Arizona" "users/someOtherPerson" location: "Arizona" ; let mergeNewLocations = await leylo;console; // Returns [true, true, true]
▲ .setDocById(collection, id, data[, overwrite?])
Returns Boolean
of whether the document was successfully written to collection
collection
[String] - Name of collectionid
[String] - Name/ID of document within collectiondata
[Object] - Contents of document to writeoverwrite
[Boolean] (Default: false) - Iffalse
, merge newdata
with pre-existing document, but iftrue
replace document entirely with newdata
let setAnotherLocation = await leylo;console;
▲ .setAllDocsById(collection, overwrite, ...docs)
Returns Array
of Boolean
s the length of docs
array for whether document was successfully written to Firestore
collection
[String] - Name of collectionoverwrite
[Boolean] (Default: false) - Iffalse
, merge newdata
with pre-existing document, but iftrue
replace document entirely with newdata
docs
[Array] - Contents of document to write as[ 'id', contents ]
// Each document is an array in the form [ 'id', contents]let users = "Inventsable" name: "Tom" "SomeNameHere" name: "John" "ScreenName" name: "Jane" ; let writeUsers = await leylo;console; // Returns [true, true, true]
▲ .setFieldByPath(path, value)
Returns Boolean
of whether the field was successfully written to path
path
[String] - Path in the form collection/document/fieldvalue
[Any] - New value to write to specifiedpath
let updateUserLocation = await leylo;console; // Returns true
▲ .setFieldById(collection, id, field, value)
Returns Boolean
of whether the field was successfully written to path
collection
[String] - Name of collectionid
[String] - Name/ID of document within collectionfield
[String] - Name of key within documentvalue
[Any] - New value to write to specifiedpath
let setNewLocation = await leylo;console;
◤ 📕 Deleting Data
- leylo.deletePath()
- leylo.deleteCollection()
- leylo.deleteDocById()
- leylo.deleteAllDocsByField()
- leylo.deleteAllDocsByQuery()
- leylo.deleteFieldByDocId()
- leylo.deleteAllFieldsContainingValue()
- leylo.deleteAllFieldsByQuery()
▲ .deletePath(path)
NOTE: If deleting a collection which has a stream, the stream is automatically detached.
Returns Boolean
if path was successfully deleted
path
[String] - Any valid path fromcollection
tocollection/document/field
let deleteCertainUser = await leylo; if deleteCertainUser console; // Delete entire collection:leylo;
▲ .deleteCollection(collection)
Same as using
await leylo.deletePath(collection)
Returns Array
of Booleans
for number of documents successfully deleted
collection
[String] - Name of collection
// Delete entire collection:leylo; let fullDeletion = await leylo;console; // Returns false because collection doesn't exist, was deleted above
▲ .deleteDocById(collection, id)
Returns Boolean
collection
[String] - Name of collectionid
[String] - Name/ID of document within collection
let deleteCertainUser = await leylo;console; // Returns true
▲ .deleteAllDocsByField(collection, field, value)
Returns Array
of Booleans
for whether documents were successfully deleted
collection
[String] - Name of collectionfield
[String] - Name of key within documentvalue
[Any] - New value to write to specifiedpath
let deleteAllArizonaResidents = await leylo;console; // Returns [ true, true, true ] deleteAllArizonaResidents;
▲ .deleteAllDocsByQuery(collection, field, query, value)
Returns Array
of Booleans
for whether docs were successfully deleted
collection
[String] - Name of collectionfield
[String] - Name of key within documentquery
[String] - One of==
,>=
,<=
,>
,<
,array_contains
or valid Firebase query stringvalue
[Any] - New value to write to specifiedpath
let deleteAllArizonaResidents = await leylo;console; // Returns [ true, true, true ] deleteAllArizonaResidents;
▲ .deleteFieldByDocId(collection, id, field)
Returns Boolean
for whether field was successfully deleted from document
collection
[String] - Name of collectionid
[String] - Name/ID of document within collectionfield
[String] - Name of key within document
let deleteLocation = await leylo; console; // Returns true
▲ .deleteAllFieldsContainingValue(collection, field, value)
Returns Array
of Booleans
for whether fields were successfully deleted
collection
[String] - Name of collectionfield
[String] - Name of key within documentvalue
[Any] - New value to write to specifiedpath
let deleteAllArizonaLocations = await leylo;console; // Returns [ true, true, true ] deleteAllArizonaResidents; // Unlike leylo.deleteAllDocsByQuery() or like, this only deletes the field 'location' instead of entire doc.
▲ .deleteAllFieldsByQuery(collection, field, query, value)
Returns Array
of Booleans
for whether fields were successfully deleted
collection
[String] - Name of collectionfield
[String] - Name of key within documentquery
[String] - One of==
,>=
,<=
,>
,<
,array_contains
or valid Firebase query stringvalue
[Any] - New value to write to specifiedpath
let deleteAllArizonaLocations = await leylo;console; // Returns [ true, true, true ] deleteAllArizonaLocations; let deleteAllAlaskaLocations = await leylo;console; // Returns [ true, true, true ]deleteAllAlaskaLocations;