From cefd89d881572bb6e6c0820bc707cc3f9a76c10f Mon Sep 17 00:00:00 2001 From: Willy Ovalle Date: Wed, 6 Feb 2019 01:01:20 +0100 Subject: [PATCH 1/2] feat: new shiny README! --- README.md | 126 +++++++++++++++++++++++++++++++++++++++++++++++++-- package.json | 4 +- 2 files changed, 125 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 4a96bbd8..bea70811 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,130 @@ -# fireorm +# fireorm🔥 -ORM for firestore. +[![Build Status](https://travis-ci.com/wovalle/fireorm.svg?token=KsyisFHzgCusk2sapuJe&branch=master)](https://travis-ci.com/wovalle/fireorm) +[![NPM Version](https://img.shields.io/npm/v/fireorm.svg?style=flat)](https://www.npmjs.com/package/fireorm) +[![Typescript lang](https://img.shields.io/badge/Language-Typescript-Blue.svg)](https://www.typescriptlang.org) +[![License](https://img.shields.io/npm/l/fireorm.svg?style=flat)](https://www.npmjs.com/package/fireorm) -### Release a new version +_:warning::heavy_exclamation_mark: Caution: This project is in **active** development. Documentation may not be totally up to date. APIs may change until stable_ +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 and familiar repository pattern. It basically helps us not worrying about Firestore details and focusing in 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). + +## Usage + +1. Install the npm package: + +```bash +yarn add typeorm +``` + +2. Initialize your firestore application ([documentation](https://firebase.google.com/docs/firestore/quickstart#initialize)): + +```typescript +import * as admin from 'firebase-admin'; + +const serviceAccount = require('../firestore.creds.json'); + +admin.initializeApp({ + credential: admin.credential.cert(serviceAccount), + databaseURL: `https://${serviceAccount.project_id}.firebaseio.com`, +}); + +const firestore = admin.firestore(); +firestore.settings({ + timestampsInSnapshots: true, +}); +``` + +3. Do cool stuff with fireorm! + +```typescript +import { Collection, getRepository } from 'fireorm'; + +@Collection() +class Todo { + id: string; + text: string; + done: Boolean; +} + +const todoRepository = getRepository(Todo, firestore); + +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 + +mySuperTodoDocument.done = true; +await todoRepository.update(mySuperTodoDocument); // Update todo + +await todoRepository.delete(mySuperTodoDocument.id); // Delete todo +``` + +You can check the [API Documentation](https://wovalle.github.io/fireorm/) or a [tutorial](https://medium.com/p/ba7734644684). + +## Development + +#### Initial Setup + +1. Clone the project from github: + ``` + git clone git@github.com:wovalle/fireorm.git + ``` +2. Install the dependencies. + ``` + yarn install + ``` + +#### Testing + +You can run the tests with the following command: + +``` +yarn test ``` + +Test files must follow the naming convention `*.test.ts` and run with [Mocha Test Runner](https://mochajs.org/). + +#### Release a new version + +- 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 +``` + +#### Update documentation + +- Fireorm uses [typedoc](https://typedoc.org/) to automatically generate API documentation, to run it: + +```bash +yarn build:documentation +``` + +#### Deploy documentation + +- API documentation is hosted in [Github Pages](https://pages.github.com/), to deploy a new version: + +```bash +yarn deploy:documentation +``` + +## 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 what you were looking for, [proceed to open a new one](https://github.com/wovalle/fireorm/issues/new). Pull requests are welcome but they must be accomp + +# License + +MIT © [Willy Ovalle](https://github.com/wovalle). See [LICENSE](https://github.com/wovalle/fireorm/blob/master/LICENSE) for details. diff --git a/package.json b/package.json index 1998aeee..6a642309 100644 --- a/package.json +++ b/package.json @@ -31,8 +31,8 @@ "build:watch": "tsc -w", "test": "mocha --require ts-node/register src/*.spec.ts --recursively", "test:watch": "mocha --require ts-node/register src/*.spec.ts --watch-extensions ts --recursively -w", - "build:documentation": "typedoc --out docs --name fireorm --readme README.md --mode file --gaID UA-133856278-1 --excludeNotExported", - "deploy": "gh-pages-deploy" + "build:documentation": "typedoc --out docs --name fireorm --readme README.md --mode file --gaID UA-133856278-1 --excludeNotExported --exclude examples --exclude test", + "deploy:documentation": "gh-pages-deploy" }, "repository": { "type": "git", From 67446f01da76360573bef143a24f24e8da551f3b Mon Sep 17 00:00:00 2001 From: Willy Ovalle Date: Wed, 6 Feb 2019 19:51:45 +0100 Subject: [PATCH 2/2] chore: more changes to readme --- README.md | 53 ++++++++++++++++++++++++++++++----------------------- 1 file changed, 30 insertions(+), 23 deletions(-) diff --git a/README.md b/README.md index bea70811..51f5dfda 100644 --- a/README.md +++ b/README.md @@ -5,21 +5,21 @@ [![Typescript lang](https://img.shields.io/badge/Language-Typescript-Blue.svg)](https://www.typescriptlang.org) [![License](https://img.shields.io/npm/l/fireorm.svg?style=flat)](https://www.npmjs.com/package/fireorm) -_:warning::heavy_exclamation_mark: Caution: This project is in **active** development. Documentation may not be totally up to date. APIs may change until stable_ +_:warning::heavy_exclamation_mark: Caution: This project is in **active** development. Documentation may not be totally up to date. APIs may change until 1.0._ 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 and familiar repository pattern. It basically helps us not worrying about Firestore details and focusing in 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). +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. ## Usage 1. Install the npm package: ```bash -yarn add typeorm +yarn add typeorm #or npm install typeorm ``` -2. Initialize your firestore application ([documentation](https://firebase.google.com/docs/firestore/quickstart#initialize)): +2. [Initialize](https://firebase.google.com/docs/firestore/quickstart#initialize) your firestore application: ```typescript import * as admin from 'firebase-admin'; @@ -37,7 +37,20 @@ firestore.settings({ }); ``` -3. Do cool stuff with fireorm! +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'; @@ -56,39 +69,33 @@ 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 - -mySuperTodoDocument.done = true; await todoRepository.update(mySuperTodoDocument); // Update todo - await todoRepository.delete(mySuperTodoDocument.id); // Delete todo ``` -You can check the [API Documentation](https://wovalle.github.io/fireorm/) or a [tutorial](https://medium.com/p/ba7734644684). - ## Development #### Initial Setup 1. Clone the project from github: - ``` - git clone git@github.com:wovalle/fireorm.git - ``` +```bash +git clone git@github.com:wovalle/fireorm.git +``` 2. Install the dependencies. - ``` - yarn install - ``` +```bash +yarn install # npm install +``` #### Testing You can run the tests with the following command: -``` -yarn test +```bash +yarn test # or npm test ``` -Test files must follow the naming convention `*.test.ts` and run with [Mocha Test Runner](https://mochajs.org/). +Test files must follow the naming convention `*.test.ts` and use [mocha](https://mochajs.org/) as the test runner. #### Release a new version @@ -107,10 +114,10 @@ npm publish #### Update documentation -- Fireorm uses [typedoc](https://typedoc.org/) to automatically generate API documentation, to run it: +- Fireorm uses [typedoc](https://typedoc.org/) to automatically build the API documentation, to generate it: ```bash -yarn build:documentation +yarn build:documentation # or npm build:documentation ``` #### Deploy documentation @@ -118,7 +125,7 @@ yarn build:documentation - API documentation is hosted in [Github Pages](https://pages.github.com/), to deploy a new version: ```bash -yarn deploy:documentation +yarn deploy:documentation # or npm deploy:documentation ``` ## Contributing