Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/wovalle/fireorm

ORM for firestore 🔥
https://github.com/wovalle/fireorm

firebase firebase-firestore firestore google-firebase orm-framework typescript typescript-orm willy-im

Last synced: 3 months ago
JSON representation

ORM for firestore 🔥

Host: GitHub
URL: https://github.com/wovalle/fireorm
Owner: wovalle
License: mit
Created: 2019-01-08T22:50:14.000Z (almost 6 years ago)
Default Branch: master
Last Pushed: 2024-04-24T09:04:38.000Z (7 months ago)
Last Synced: 2024-04-24T14:45:00.716Z (7 months ago)
Topics: firebase, firebase-firestore, firestore, google-firebase, orm-framework, typescript, typescript-orm, willy-im
Language: TypeScript
Homepage: https://fireorm.js.org
Size: 2.42 MB
Stars: 539
Watchers: 19
Forks: 72
Open Issues: 64
Metadata Files:
- Readme: README.md
- License: LICENSE

Awesome Lists containing this project

awesome-list - fireorm

README

        # fireorm🔥

[![NPM Version](https://img.shields.io/npm/v/fireorm.svg?style=flat)](https://www.npmjs.com/package/fireorm)

[![Build Status](https://travis-ci.com/wovalle/fireorm.svg?token=KsyisFHzgCusk2sapuJe&branch=master)](https://travis-ci.com/wovalle/fireorm)

[![Typescript lang](https://img.shields.io/badge/Language-Typescript-Blue.svg)](https://www.typescriptlang.org)

[![All Contributors](https://img.shields.io/badge/all_contributors-7-orange.svg?style=flat-square)](#contributors)

[![License](https://img.shields.io/npm/l/fireorm.svg?style=flat)](https://www.npmjs.com/package/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](https://medium.com/p/ba7734644684). Also, the [API documentation](https://wovalle.github.io/fireorm) is available.

> :warning: Due to personal and professional reasons, I am unable to continue active development and support for this project.

>

>However, I want to assure you that the project will remain available for use and that I will still check pull requests if needed. I encourage the community to continue to use and contribute to this project, and I hope that it will continue to be a valuable resource for developers.

## 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](https://firebase.google.com/docs/firestore/quickstart#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

```

### Firebase Complex Data Types

Firestore has support for [complex data types](https://firebase.google.com/docs/firestore/manage-data/data-types) such as GeoPoint and Reference. Full handling of complex data types is [being handled in this issue](https://github.com/wovalle/fireorm/issues/58). Temporarily, fireorm will export [Class Transformer's @Type](https://github.com/typestack/class-transformer#working-with-nested-objects) decorator. It receives a lamda where you return the type you want to cast to. [See GeoPoint Example](https://github.com/wovalle/fireorm/blob/d8f79090b7006675f2cb5014bb5ca7a9dfbfa8c1/src/BaseFirestoreRepository.spec.ts#L471-L476).

#### 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

### Initial Setup

1.  Clone the project from github:

```bash

git clone [email protected]:wovalle/fireorm.git

```

2.  Install the dependencies:

```bash

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](https://firebase.google.com/docs/admin/setup#initialize_the_sdk) and declare some [environment variables](https://github.com/wovalle/fireorm/blob/master/test/setup.ts#L5-L13).

Test files must follow the naming convention `*.test.ts` and use [jest](https://jestjs.io/) as the test runner.

### Committing

This repo uses [Conventional Commits](https://www.conventionalcommits.org/) as the commit messages convention.

### Release a new version

This repo uses [Semantic Release](https://github.com/semantic-release/semantic-release) to automatically release new versions as soon as they land on master.

Commits must follow [Angular's Git Commit Guidelines](https://github.com/angular/angular.js/blob/master/DEVELOPERS.md#-git-commit-guidelines).

Supported commit types (taken from [here](https://github.com/angular/angular.js/blob/master/DEVELOPERS.md#type)):

- **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](https://typedoc.org/) 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](https://pages.github.com/) in this [link](https://wovalle.github.io/fireorm).

## Contributing

Have a bug or a feature request? Please search [the issues](https://github.com/wovalle/fireorm/issues) to prevent duplication. If you couldn't find what you were looking for, [proceed to open a new one](https://github.com/wovalle/fireorm/issues/new). Pull requests are welcome!

## Contributors

Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/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](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!

## License

MIT © [Willy Ovalle](https://github.com/wovalle). See [LICENSE](https://github.com/wovalle/fireorm/blob/master/LICENSE) for details.