@razaman2/collection-proxy

A custom firestore client that provides a simple and consistent interface for interacting with the database.

Install the dependencies

npm install --save @razaman2/collection-proxy

pnpm add @razaman2/collection-proxy

THINGS YOU SHOULD KNOW

All documents are created with the auto generated properties outlined by the following json object.

{
    "belongsTo": [
        "document-id collection-name"
    ],
    "createdAt": "serverTimestamp",
    "updatedAt": "serverTimestamp",
    "id": "document-id"
}

1. The belongsTo is an array that stores all the document id's that have a relationship with the current document. The convention is to list the document id followed by a space followed by the collection the document id is from. The relationship will always include the current document id.

A settings document with id 111, that belongs to a user with id 222, and a company with id 333, would look like this {belongsTo: ["111 settings", "222 users", "333 companies"]}. This relationship is intended to be queried using the array-contains or the array-contains-any operators. This approach provides the ability to run queries like get all settings documents that belong to user with id 222 or get all settings documents that belong to company with id 333 or even get all settings documents that belong to user with id 222 and company 333. The latter would require that when adding relationships, you concatenate the permutations you want to use for querying. {belongsTo: ["111 settings", "222 users", "333 companies", "222 users|333 companies]} now you can query a settings document that belongs to a specific user and company.

2. The createdAt key stores a firestore serverTimestamp that represents exactly when the document was created.
3. The updatedAt key stores a firestore serverTimestamp that represents the last time the document was updated. It will be automatically updated when the document is updated using the update method from the firestore-proxy.
4. The id key stores the assigned document id on the document data.

Initializing the Collection

The firestore-proxy is compatible with both the namespaced and the modular firestore api's. The collection has a static configuration which allows you to configure the api once in the entry point of your app.

be sure to initialize your firestore app!

Namespaced API, including the Admin SDK

All you need to do to configure the namespaced api is to provide it with your firestore instance.

import firebase from "firebase/compat/app";
import "firebase/compat/firestore";
import {Collection} from "@razaman2/collection-proxy";

firebase.initializeApp({projectId: "demo-app"});

Collection.proxy({
    getFirestore: firestore,
    // you can enable operation logging to console
    logging: true,
});

// And thats it!

Modular API

Import the functions from the firestore library and provide them to the collection config. You can provide only the functions that are needed for the operation you are trying to perform.

import {initializeApp} from "firebase/app";
import {getFirestore, collection, doc, getDoc, getDocs, collectionGroup, onSnapshot, setDoc, updateDoc, deleteDoc, deleteField, arrayUnion, serverTimestamp, writeBatch} from "firebase/firestore";
import {Collection} from "@razaman2/collection-proxy";

initializeApp({projectId: "demo-app"});

Collection.proxy({
    // base setup to start working with the collection
    modular: true,
    getFirestore: getFirestore(),
    collection,
    doc,

    // when reading single document
    getDoc,

    // when reading multiple documents
    getDocs,

    // when reading from a collection group
    collectionGroup,

    // when reading documents using a snapshot
    onSnapshot,

    // when creating, updating or deleting documents
    setDoc,

    // when updating documents
    updateDoc,

    // when deleting documents
    deleteDoc,

    // when you want to delete undefined document fields
    deleteField,

    // when creating documents
    arrayUnion,

    // when creating or updating documents
    serverTimestamp,

    // when updating documents
    writeBatch,

    // you can enable operation logging to console
    logging: true,
});

Reading Documents

// init with document id
const collection = await Collection.proxy("users").init(1);

const data = collection.getData();

// get document for provided id
const collection = await Collection.proxy("users").getDocument(1, {realtime: false});

const data = collection.getData();

// set
const collection = await Collection.proxy("users").setDoc(1).init();

Creating Documents

// create document with auto-generated id
await Collection.proxy("tests").create({
    data: {name: "john doe"},
});

// create document with id from setDoc
await Collection.proxy("tests").setDoc("123").create({
    data: {name: "john doe"},
});

// create document with id from payload data
await Collection.proxy("tests", {
    payload: {
        data: {id: "123", name: "john doe"},
    },
}).create();

// create document with id from document path
await Collection.proxy().setPath("tests/123").create({
    data: {name: "john doe"},
});

// create document with setPath and setDoc
await Collection.proxy().setPath("tests").setDoc("123").create({
    data: {name: "john doe"},
});

Updating Documents

// update document with auto-generated id
await Collection.proxy("tests").update({
    data: {name: "jane doe"},
});

// update document with id from setDoc
await Collection.proxy("tests").setDoc("123").update({
    data: {name: "jane doe"},
});

// update document with id from payload data
await Collection.proxy("tests", {
    payload: {
        data: {id: "123", name: "jane doe"},
    },
}).update();

// update document with id from document path
await Collection.proxy().setPath("tests/123").update({
    data: {name: "jane doe"},
});

// update document with setPath and setDoc
await Collection.proxy().setPath("tests").setDoc("123").update({
    data: {name: "jane doe"},
});

Deleting Documents

// delete document with id from setDoc
await Collection.proxy("tests").setDoc("123").delete();

// delete document with id from payload data
await Collection.proxy("tests", {
    payload: {
        data: {id: "123"},
    },
}).delete();

// delete document with id from document path
await Collection.proxy().setPath("tests/123").delete();

// delete document with setPath and setDoc
await Collection.proxy().setPath("tests").setDoc("123").delete();

Audit trail

you can attach built in audit trail to create, update and delete operations

import {Update} from "@razaman2/collection-proxy";

// audit trail any create, update or delete operations on the proxy
Collection.proxy("tests").onWrite({
   handler: (collection) => new Update(collection),
   triggers: ["create", "update", "delete"], // when you perform an operation listed in the triggers array, an associated update will be created to reflect the before and after state of the document.
});

// attach audit trail when creating a document
Collection.proxy("tests").create({
   data: {id: "123", name: "john doe"},
   update: (collection) => new Update(collection),
});

// attach audit trail when updating a document
Collection.proxy("tests").update({
   data: {id: "123", name: "jane doe"},
   update: (collection) => new Update(collection),
});

// attach audit trail when deleting a document
Collection.proxy("tests").delete({
   data: {id: "123", name: "jane doe"},
   update: (collection) => new Update(collection),
});