# firebase-decorators

> This module provides a set of decorators for your firebase project.

Latest version **1.0.3** (published 2023-09-25) · MIT license · 0 weekly downloads

## Install

```sh
npm install firebase-decorators
pnpm add firebase-decorators
yarn add firebase-decorators
bun add firebase-decorators
```

## Health

**Score 30/100 (F)** — status: abandoned.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.0.3 |
| Published | 2023-09-25 |
| First published | 2023-09-10 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 2 |
| Unpacked size | 25.8 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 1 |
| Author | Anurag Mandal |
| Maintainers | crypticminds |
| Keywords | decorators, firebase, typescript, database, firestore |

## Links

- npm: https://www.npmjs.com/package/firebase-decorators
- Repository: https://github.com/anuragmandal0110/firebase-decorators
- Homepage: https://github.com/anuragmandal0110/firebase-decorators#readme
- Issues: https://github.com/anuragmandal0110/firebase-decorators/issues
- npm.io page: https://npm.io/package/firebase-decorators

## Dependencies (2)

- [firebase](https://npm.io/package/firebase.md) ^10.3.1
- [firebase-admin](https://npm.io/package/firebase-admin.md) ^11.10.1

## Alternatives

- [@openai/codex-sdk](https://npm.io/package/@openai/codex-sdk.md) — 731.4K weekly downloads
- [babel-plugin-transform-react-jsx](https://npm.io/package/babel-plugin-transform-react-jsx.md) — 565.0K weekly downloads
- [babel-helper-remove-or-void](https://npm.io/package/babel-helper-remove-or-void.md) — 508.5K weekly downloads
- [@pnpm/store-controller-types](https://npm.io/package/@pnpm/store-controller-types.md) — 186.9K weekly downloads
- [react-native-signature-canvas](https://npm.io/package/react-native-signature-canvas.md) — 155.6K weekly downloads

## Recent versions

- 1.0.3 (latest) — 2023-09-25
- 1.0.2 — 2023-09-25
- 1.0.1 — 2023-09-24
- 1.0.0 — 2023-09-24
- 0.2.7 — 2023-09-23
- 0.2.6 — 2023-09-23
- 0.2.5 — 2023-09-23
- 0.2.4 — 2023-09-23
- 0.2.3 — 2023-09-23
- 0.2.2 — 2023-09-23
- 0.2.1 — 2023-09-23
- 0.2.0 — 2023-09-23
- 0.1.9 — 2023-09-23
- 0.1.8 — 2023-09-23
- 0.1.7 — 2023-09-11
- … 15 more at https://npm.io/package/firebase-decorators/versions

## README

# Firebase Decorators
[![contributions welcome](https://img.shields.io/badge/contributions-welcome-brightgreen.svg?style=flat)](https://github.com/dwyl/esta/issues) [![HitCount](https://hits.dwyl.com/anuragmandal0110/firebase-decorators.svg?style=flat-square)](http://hits.dwyl.com/anuragmandal0110/firebase-decorators) [![Coverage Status](https://coveralls.io/repos/github/anuragmandal0110/firebase-decorators/badge.svg?branch=CI_CD_test)](https://coveralls.io/github/anuragmandal0110/firebase-decorators?branch=CI_CD_test)

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
```typescript
import  { initializeApp }  from  'firebase/app';  
  
const firebaseConfig =  {  //...  
};  
  
const app = initializeApp(firebaseConfig);
```
#### Admin SDK

```typescript
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**. 

```typescript
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
```typescript
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
```typescript
Class User extends BaseFirebaseModel {

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

	role!:  "USER"  |  "ADMIN";

	joinDate!:  number;
}
```
### @DataKey Decorator
Mark the fields of the model using DataKey decorator. 
```typescript
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](#initialize-firebase-app)

```typescript
@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.
```typescript
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()
 
```
## New features to come very soon!!
Contributers and feature requests are welcome!!

---
_Source: https://npm.io/package/firebase-decorators · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._