Firebase-decorators NPM

Firebase Decorators

Write cleaner code using decorators in your next firebase project.

(Work in progress)

Usage

Installation

Important Typescript > 5.0.0 This package uses the latest typescript decorator APIs and thus requires typescript version > 5.0

$ npm install --save firebase-decorators

Initialize Firebase app

import  { initializeApp }  from  'firebase/app';  
  
const firebaseConfig =  {  //...  
};  
  
const app = initializeApp(firebaseConfig);

Admin SDK

import {initializeApp} from  "firebase-admin/app";
    
const firebaseConfig =  {  //...  
};  
  
const app = initializeApp(firebaseConfig);

Create a model

Create a model which reflects the data on the database.

Let's create a user model which we will use to store user data in Firestore. We will extend the Class with BaseFirebaseModel.

Class User extends BaseFirebaseModel {

	userId!:  string;

	role!:  "USER"  |  "ADMIN";

	joinDate!:  number;

	constructor(userId:string) {
		super();
		this.userId  =  userId;
		// initialize other fields as required.
	}
}

@PrimaryKey Decorator

The document id to read the document from can be marked as the primary key in the model.

This field should be initialized for all the functionalities to work, Otherwise an error will be thrown during runtime. The field can be initialized either using the constructor or directly.

Constructor

Class User extends BaseFirebaseModel {

	@PrimaryKey()
	private  userId!:  string;

	role!:  "USER"  |  "ADMIN";

	joinDate!:  number;

	constructor(userId:string) {
		super();
		this.userId  =  userId;
		// initialize other fields as required.
	}
}

Direct initialization

Class User extends BaseFirebaseModel {

	@PrimaryKey()
	userId!:  string = "documentId";

	role!:  "USER"  |  "ADMIN";

	joinDate!:  number;
}

@DataKey Decorator

Mark the fields of the model using DataKey decorator.

Class User extends BaseFirebaseModel {

	@PrimaryKey()
	private  userId!:  string;
	
	@DataKey()
	role!:  "USER"  |  "ADMIN";
	
	@DataKey("join_date")
	joinDate!:  number;

	// since this field is not marked,
	// it will be ignored during any read/write operation.
	thisFieldWillBeIgnored! : string;

	constructor(userId:string) {
		super();
		this.userId  =  userId;
		// initialize other fields as required.
	}
}

The Firestore model fields will be mapped to the model fields join_date -> joinDate (since we explicitly pass the remote key name) role -> role (since no value for the remote key was passed) thisFieldWillBeIgnored -> this field will be ignored since it is not marked as a data field.

@FirestoreModel Decorator

Finally mark the model with @FirestoreModel and provide the collection name and whether to use the admin SDK or not. The value for useAdminSdk should be set depending on whether the admin app was initialized or not. Firebase app Initialization

@FirestoreModel("user",false)
Class User extends BaseFirebaseModel {

	@PrimaryKey()
	private userId!:  string;
	
	@DataKey()
	role!:  "USER"  |  "ADMIN";
	
	@DataKey("join_date")
	joinDate!:  number;
	
	// since this field is not marked,
	// it will be ignored during any read/write operation.
	thisFieldWillBeIgnored! : string;

	constructor(userId:string) {
		super();
		this.userId  =  userId;
		// initialize other fields as required.
	}
}

Use the model

Simply use the model to read, write and sync data to the database.

const user = new User("this_is_the_user_id");

// wait for model to get initialized.
// this value resolves when the model has synced
// its data with firestore document
await user.ready;

// set values into the model;;
user.role = "USER"
user.joinDate = 1234

// write the data to the database
// this will create a new document if it doesnt exist
// or overwrtire old document
await user.write()

// sync data from the remote
await user.sync()

// change any value
user.role = "ADMIN"

// update the model
await user.update()