🔥 FireORM24 🔥

Introduction

FireORM24 is a lightweight wrapper for firebase-admin designed to simplify interactions with Firestore databases. By abstracting the access layer and offering a familiar repository pattern, FireORM24 streamlines the development process for applications that use Firestore, allowing developers to concentrate on creating new features without dealing with the intricacies of Firestore.

Willy Ovalle (GH Profile), the original maintainer, stepped down from active support in March 2023. Since then, the project has been maintained through community contributions. The current effort, under the name FireORM24, focuses on updating the project with the latest security patches and new features to align with the latest Firebase advancements. The original project can be found here.

For more information on the motivations behind the project, you can read Willy's original introductory post on Medium. The API documentation is also available.

Usage

Install the npm package:

yarn add fireorm24 reflect-metadata #or npm install fireorm24 reflect-metadata

# note: the reflect-metadata shim is required

Initialize your Firestore application:

import { initializeApp } from "firebase/app";
import { getFirestore } from "firebase/firestore";
import serviceAccount from "../firestore.creds.json"; // Adjust path as necessary

const firebaseConfig = {
    apiKey: "YOUR_API_KEY",
    authDomain: "YOUR_PROJECT_ID.firebaseapp.com",
    projectId: "YOUR_PROJECT_ID",
    storageBucket: "YOUR_PROJECT_ID.appspot.com",
    messagingSenderId: "YOUR_MESSAGING_SENDER_ID",
    appId: "YOUR_APP_ID",
};

// Initialize Firebase
const app = initializeApp(firebaseConfig);

// Initialize Cloud Firestore and get a reference to the service
const db = getFirestore(app);
fireorm.initialize(db);

Create your Firestore models:

import { Collection } from 'fireorm24';

@Collection()
class Programmer {
  id: string;
  name: string;
  language: string;
}

Manage your Firestore data with ease!

import { Collection, getRepository } from 'fireorm24';

@Collection()
class Programmer {
  id: string;
  name: string;
  language: string;
}

const programmerRepository = getRepository(Programmer);

const willy = new Programmer();
willy.name = "Willy Ovale";
willy.language = "Typescript";

const programmerDocument = await programmerRepository.create(willy); // Create programmer

const mySuperProgrammerDocument = await programmerRepository.findById(programmerDocument.id); // Read programmer

mySuperProgrammerDocument.language = "Typescript, .NET";
await programmerRepository.update(mySuperProgrammerDocument); // Update programmer

await programmerRepository.delete(mySuperProgrammerDocument.id); // Delete programmer

Firebase Complex Data Types

Firestore supports complex data types such as GeoPoint and Reference. The integration of full support for these data types into the new FireORM project is currently in progress. This section will be updated with detailed information once the support is fully implemented.

Current Workaround

In the meantime, you can utilize Class Transformer's @Type decorator for handling nested objects. For example, refer to the GeoPoint Example.

Limitations

Currently, casting GeoPoints to a custom class requires latitude: number and longitude: number as public class fields. This limitation will be addressed in future updates.

Development

Initial Setup

Clone the project from github:

git clone https://github.com/elersong/fireorm24.git

Install the dependencies:

yarn # npm install

Testing

Fireorm has two types of tests:

Unit tests: yarn test # or npm test
Integration tests: yarn test:integration # or npm test:integration

To be able to run the integration tests you need to create a Firebase service account and declare some environment variables.

Test files must follow the naming convention *.test.ts and use jest as the test runner.

Committing

This repo uses Conventional Commits as the commit messages convention.

Release a new version

This repo uses Semantic Release to automatically release new versions as soon as they land on master.

Commits must follow Angular's Git Commit Guidelines.

Supported commit types (taken from here):

feat: A new feature
fix: A bug fix
docs: Documentation only changes
style: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)
refactor: A code change that neither fixes a bug nor adds a feature
perf: A code change that improves performance
test: Adding missing or correcting existing tests
chore: Changes to the build process or auxiliary tools and libraries such as documentation generation

Manual Release

If, by any reason, a manual release must be done, these are the instructions: - To release a new version to npm, first we have to create a new tag: ```bash npm version [ major | minor | patch ] -m "Relasing version" git push --follow-tags ``` - Then we can publish the package to npm registry: ```bash npm publish ``` - To deploy the documentation: ```bash yarn deploy:doc # or npm deploy:doc ```

Documentation

Fireorm uses typedoc to automatically build the API documentation, to generate it:

yarn build:doc # or npm build:doc

Documentation is automatically deployed on each commit to master and is hosted in Github Pages in this link.

Contributing

Have a bug or a feature request? Please visit the new issues page on the FireORM24 repository. To contribute, check the new issues page to find a problem you would like to solve. Additionally, you can review the old FireORM issues page to see if any requested features have not yet been reported to the new repository.

Pull requests are welcome!

Contributors

Thanks goes to these wonderful people (emoji key):

_{Willy Ovalle} 💻 📖 💡 🤔 👀 ⚠️	_{Maximo Dominguez} 🤔 💻	_{Nathan Jones} 💻	_{Sergii Kalashnyk} 💻	_{SaltyKawaiiNeko} 💻 🤔	_{z-hirschtritt} 💻 🤔	_{Joe McKie} 💻 🤔
_{Samed Düzçay} 💻	_stefdelec 💻	_{Łukasz Kuciel} 💻	_{Yaroslav Nekryach} 💻	_{Dmytro Nikitiuk} 💻	_JingWangTW 💻	_{Rink Stiekema} 💻
_Daniel 💻	_{Marko Zabreznik} 💻	_{Jose Mendez} 💻	_{Grey Elerson} 💻 🤔