Firestore-sweet NPM

alt text

Firestore Sweet

Cloud Firestore made super easy with sweet syntactic sugar

firestore-sweet works with both client-side firebase and server-side firebase-admin.

Project Website / Documentation

https://warashibe.github.io/firestore-sweet/

Installation

yarn add firestore-sweet

Examples

client-side initialization : `firebase`

import sweet from "firestore-sweet"
import firebase from "firebase"

firebase.initializeApp({
  apiKey: '### FIREBASE API KEY ###',
  authDomain: '### FIREBASE AUTH DOMAIN ###',
  projectId: '### CLOUD FIRESTORE PROJECT ID ###'
});

const db = sweet(firebase.firestore)

server-side initialization : `firebase-admin`

import sweet from "firestore-sweet"
import admin from "firebase-admin"

const serviceAccount = require('path/to/serviceAccountKey.json');

admin.initializeApp({
  credential: admin.credential.cert(serviceAccount)
})

const db = sweet(admin.firestore)

`get`

firestore-sweet automatically knows whether the ref is a collection or a doc based on the position. It returns actual data instead of snapshot.

/* for comparisons with the original APIs
   const fs = firebase.firestore() */

// fs.collection("users").get()
await db.get("users")

// fs.collection("users").doc("Bob").get()
await db.get("users", "Bob")

// fs.collection("users").doc("Bob").collection("comments").get()
await db.get("users", "Bob", "comments")

// fs.collection("users").doc("Bob").collection("comments").doc("no3").get()
await db.get("users", "Bob", "comments", "no3")

`where` `orderBy` `limit`

firestore-sweet knows whether the argument is for where, orderBy, or limit based on the array length.

// fs.collection("users").where("age", "==", 20).get()
await db.get("users", ["age", "==", 20])

// fs.collection("users").where("age", "==", 20).orderBy("age", "desc").get()
await db.get("users", ["age", "==", 20], ["age", "desc"])

// fs.collection("users").where("age", "==", 20).orderBy("age", "desc").limit(5).get()
await db.get("users", ["age", "==", 20], ["age", "desc"], 5)

`startAt` `startAfter` `endAt` `endBefore`

// fs.collection("users").orderBy("age").startAt(20).get()
await db.get("users", ["age"], ["startAt", 20])

`add` `set` `upsert` `update` `delete`

// fs.collection("users").doc("Bob").set({name:"Bob", age: 30})
await db.set({name:"Bob", age: 30}, "users", "Bob")

// fs.collection("users").doc("Bob").set({name:"Bob", age: 30}, {merge: true})
await db.upsert({name:"Bob", age: 30}, "users", "Bob")

// fs.collection("users").doc("Bob").update({name:"Bob", age: 30})
await db.update({age: 40}, "users", "Bob")

// fs.collection("users").doc("Bob").delete()
await db.delete("users", "Bob")

delete field : `del`

// fs.collection("users").doc("Bob").update({age: firebase.firestore.FieldValue.delete()})
await db.update({age: db.del}, "users", "Bob")

increment field : `inc(n)`

// fs.collection("users").doc("Bob").update({age: firebase.firestore.FieldValue.increment(3)})
await db.update({age: db.inc(3)}, "users", "Bob")

serverTimestamp : `ts`

// fs.collection("users").doc("Bob").update({date: firebase.firestore.FieldValue.serverTimestamp()})
await db.update({date: db.ts}, "users", "Bob")

arrayUnion : `union`

// fs.collection("users").doc("Bob").update({favorites: firebase.firestore.FieldValue.arrayUnion("tomato")})
await db.update({favorites: db.union("tomato")}, "users", "Bob")

arrayRemove : `remove`

// fs.collection("users").doc("Bob").update({favorites: firebase.firestore.FieldValue.arrayRemove("tomato")})
await db.update({favorites: db.remove("tomato")}, "users", "Bob")

onSnapShot : `on`

const unsubscribe = db.on("users", (docs) => {
  for(const user of docs){
    console.log(`${user.name} : ${user.age}`)
  }
})

`drop`

This is a unique method only seen in firestore-sweet to delete everything in a collection.

Be careful using it since it's powerful and dangerous if misused.

await db.drop("users")

`ref`

Use ref to simply get a native ref object from the Firestore SDK.

await db.ref("users", "Bob")

Bulk write operations with query

With firestore sweet, multiple write operations are possible with queries in one method.

This is not something possible with the Firestore APIs. Firestore batch has 500 operations at a time limit, but firestore sweet automatically bypasses the limit by dividing the operations into chunks of 500 and parallelly executes those. It can execute 50,000 operations in a few seconds this way, but watch out for your bill.

add and upsert don't make sense with this operation. add doesn't do anything and upsert works the same as update in this context.

await db.update({age: 30}, "users", ["age", ">", 30])

await db.set({name: "John", age: 30}, "users", ["age", ">", 30])

await db.delete("users", ["age", ">", 30])

runTransaction : `tx`

await db.tx("users", "Bob", ({ref, t, data}) => {
  t.update(ref, {age: data.age + 10})
})

batch : `batch`

await db.batch([
  ["set, {name: "Bob", age: 30}, "users", "Bob"],
  ["update", {age: db.inc(3)}, "users", "Bob"],
  ["delete", "users", "Bob"]
])

Getting document ids and snapshots as return values

You can also get document id and snapshot with the actual data by adding K or S to the method names.

get => getK getS / tx => txK txS / on => onK onS

// getK returns document id and data
const users = await db.getK("users")
for(const id in users){
  console.log(`${users[id].name} : ${users[id].age}`)
}

// getS returns Object with snapshot, document id and data
for(const {id, ss , data} of await db.getS("users")){
    const user = ss.data() // same as data
	console.log(`${user.name} : ${user.age}`)
}
  
// getR returns a raw snapshot which is the same behavior as the original firestore API but as an array
(await db.getR("users")).forEach((ss) => {
    const user = ss.data()
	console.log(`${user.name} : ${user.age}`)
}

/* "txK", "txS" and "onK", "onS"
   return the same data as "getK", "getS" respectively */