fireorm🔥


Fireorm is a tiny wrapper on top of firebase-admin that makes life easier when dealing with a Firestore database. Fireorm tries to ease the development of apps that rely on Firestore at the database layer by abstracting the access layer providing a familiar repository pattern. It basically helps us not worry about Firestore details and focus on what matters: adding cool new features!

You can read more about the motivations and features of fireorm on its introductory post. Also, the API documentation is available.

Usage

1. Install the npm package:

``bash
yarn add fireorm reflect-metadata #or npm install fireorm reflect-metadata

note: the reflect-metadata shim is required


`

2. Initialize your Firestore application:

`typescript
import * as admin from 'firebase-admin';
import * as fireorm from 'fireorm';

const serviceAccount = require('../firestore.creds.json');

admin.initializeApp({
credential: admin.credential.cert(serviceAccount),
databaseURL: https://${serviceAccount.project_id}.firebaseio.com,
});

const firestore = admin.firestore();
fireorm.initialize(firestore);
`

3. Create your Firestore models:

`typescript
import { Collection } from 'fireorm';

@Collection()
class Todo {
id: string;
text: string;
done: Boolean;
}
`

4. Do cool stuff with fireorm!

`typescript
import { Collection, getRepository } from 'fireorm';

@Collection()
class Todo {
id: string;
text: string;
done: Boolean;
}

const todoRepository = getRepository(Todo);

const todo = new Todo();
todo.text = "Check fireorm's Github Repository";
todo.done = false;

const todoDocument = await todoRepository.create(todo); // Create todo
const mySuperTodoDocument = await todoRepository.findById(todoDocument.id); // Read todo
await todoRepository.update(mySuperTodoDocument); // Update todo
await todoRepository.delete(mySuperTodoDocument.id); // Delete todo
`

$3

Firestore has support for complex data types such as GeoPoint and Reference. Full handling of complex data types is being handled in this issue. Temporarily, fireorm will export Class Transformer's @Type decorator. It receives a lamda where you return the type you want to cast to. See GeoPoint Example.

#### Limitations

If you want to cast GeoPoints to your custom class, it must have latitude: number and longitude: number as public class fields. Hopefully this won't be a limitation in v1.

Development

$3

1. Clone the project from github:

`bash
git clone git@github.com:wovalle/fireorm.git
`

2. Install the dependencies:

`bash
yarn # npm install
`

$3

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.

$3

This repo uses Conventional Commits as the commit messages convention.

$3

This repo uses Sematic 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
`

$3

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

`bash
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 search the issues to prevent duplication. If you couldn't find what you were looking for, proceed to open a new one. 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 💻

This project follows the all-contributors specification. Contributions of any kind welcome!

License

MIT © Willy Ovalle. See LICENSE for details.