Merge pull request #115 from wovalle/chore/transactions-refactor

chore: transactions refactor

.travis.yml

@@ -1,6 +1,6 @@
 language: node_js
 node_js:
-  - '10'
+  - '12'
 
 stages:
   - test

docgen/Batches.md

@@ -0,0 +1,63 @@
+# Batches
+
+Fireorm also has support for Firestore's [Batched Writes](https://firebase.google.com/docs/firestore/manage-data/transactions#batched-writes).
+
+## Batches inside repositories
+
+Fireorm [repositories](CORE_CONCEPTS.md#FireormRepositories) have a [createBatch](Classes/BaseFirestoreRepository.md#CreateBatch) method that returns a [BatchRepository](Classes/FirestoreBatchRepository.md). The [BatchRepository](Classes/FirestoreBatchRepository.md) is an special type of repository that has methods to create, update and delete documents inside a batch. After adding all the operations that we want to run to the batch, we have to call the [commit](Classes/FirestoreBatchRepository.md#Commit) method to execute them.
+
+```typescript
+import { getRepository, Collection } from 'fireorm';
+import Band from './wherever-our-models-are';
+
+const bandRepository = getRepository(Band);
+const dt = new Band();
+dt.id = 'dream-theater';
+dt.name = 'DreamTheater';
+dt.formationYear = 1985;
+
+const batch = bandRepository.createBatch();
+
+batch.create(dt);
+
+await batch.commit();
+```
+
+## Batches in multiple repositories
+
+Fireorm exports a [createBatch](Classes/BaseFirestoreRepository.md#CreateBatch) method that can be used to create batches with one or multiple repositories. It receives a lamda function where the first parameter corresponds to a [FirestoreBatch](Classes/FirestoreBatch.md) class. This class exposes a `getRepository` method that receives an [Model class](CORE_CONCEPTS.md#FireormModels) and returns a [BatchRepository](Classes/BatchRepository.md) of the given entity and can be used to create, update and delete documents. Once all operations are defined, we have to call the `commit` method of our BatchRepository to commit all the operations.
+
+```typescript
+import { createBatch } from 'fireorm';
+import { Band, Album } from './wherever-our-models-are';
+
+const band = new Band();
+band.id = 'dream-theater';
+band.name = 'DreamTheater';
+band.formationYear = 1985;
+
+const album1 = new Album();
+album1.name = 'When Dream and Day Unite';
+album1.releaseDate = new Date('1989-03-06T00:00:00.000Z');
+album1.bandId = band.id;
+
+const album2 = new Album();
+album2.name = 'Images and Words';
+album2.releaseDate = new Date('1992-07-07T00:00:00.000Z');
+album2.bandId = band.id;
+
+const batch = createBatch();
+
+const bandBatchRepository = batch.getRepository(Band);
+const albumBatchRepository = batch.getRepository(Album);
+
+bandBatchRepository.create(band);
+albumBatchRepository.create(album1);
+albumBatchRepository.create(album2);
+
+await batch.commit();
+```
+
+## Limitations
+
+Please be aware that Firestore has many limitations when working with BatchedWrites. You can learn more [here](https://firebase.google.com/docs/firestore/manage-data/transactions).

docgen/Transactions.md

@@ -1,6 +1,10 @@
 # Transactions
 
-Fireorm also has support for [Firestore Transactions](https://firebase.google.com/docs/firestore/manage-data/transactions) with the [runTransaction](Classes/BaseFirestoreRepository.md#RunTransaction) methods in repositories. It receives a lamda function where the first parameter corresponds to a [TransactionRepository](Classes/TransactionRepository.md). The [TransactionRepository](Classes/TransactionRepository.md) is an special type of repository that has methods to create, retrieve, update and delete documents inside a transaction.
+Fireorm also has support for [Firestore Transactions](https://firebase.google.com/docs/firestore/manage-data/transactions) inside a single [repository]() and between multiple repositories.
+
+## Transactions inside repositories
+
+Fireorm [repositories](CORE_CONCEPTS.md#FireormRepositories) have a [runTransaction](Classes/BaseFirestoreRepository.md#RunTransaction) method. It receives a lamda function where the first parameter corresponds to a [TransactionRepository](Classes/TransactionRepository.md). The [TransactionRepository](Classes/TransactionRepository.md) is an special type of repository that has methods to create, retrieve, update and delete documents inside a transaction.
 
 ```typescript
 import { getRepository, Collection } from 'fireorm';
@@ -17,27 +21,60 @@ bandRepository.runTransaction(async tran => {
 });
 ```
 
-## Batched Writes
+## Transactions in multiple repositories
 
-Fireorm also has support for Firestore's [Batched Writes](https://firebase.google.com/docs/firestore/manage-data/transactions#batched-writes). Fireorm repositories have a [createBatch](Classes/BaseFirestoreRepository.md#CreateBatch) method that returns a [BatchRepository](Classes/FirestoreBatchRepository.md). The [BatchRepository](Classes/FirestoreBatchRepository.md) is an special type of repository that has methods to create, update and delete documents inside a batch. After adding all the operations that we want to run to the batch, we have to call the [commit](Classes/FirestoreBatchRepository.md#Commit) method to execute them.
+Fireorm exports a [runTransaction](Classes/BaseFirestoreRepository.md#RunTransaction) method that can be used to create transactions with one or multiple repositories. It receives a lamda function where the first parameter corresponds to a [FirestoreTransaction](Classes/FirestoreTransaction.md) class. This class exposes a `getRepository` method that receives an [Model class](CORE_CONCEPTS.md#FireormModels) and returns a [TransactionRepository](Classes/TransactionRepository.md) of the given entity and can be used to create, retrieve, update and delete documents inside a transaction.
 
 ```typescript
-import { getRepository, Collection } from 'fireorm';
-import Band from './wherever-our-models-are';
+import { runTransaction } from 'fireorm';
+import { Band, Album } from './wherever-our-models-are';
 
-const bandRepository = getRepository(Band);
-const dt = new Band();
-dt.id = 'dream-theater';
-dt.name = 'DreamTheater';
-dt.formationYear = 1985;
+const band = new Band();
+band.id = 'dream-theater';
+band.name = 'DreamTheater';
+band.formationYear = 1985;
+
+const album1 = new Album();
+album1.name = 'When Dream and Day Unite';
+album1.releaseDate = new Date('1989-03-06T00:00:00.000Z');
+album1.bandId = band.id;
 
-const batch = bandRepository.createBatch();
+const album2 = new Album();
+album2.name = 'Images and Words';
+album2.releaseDate = new Date('1992-07-07T00:00:00.000Z');
+album2.bandId = band.id;
 
-batch.create(dt);
+await runTransaction(async tran => {
+  const bandTranRepository = tran.getRepository(Band);
+  const albumTranRepository = tran.getRepository(Album);
 
-await batch.commit();
+  await bandTranRepository.create(band);
+  await albumTranRepository.create(album1);
+  await albumTranRepository.create(album2);
+});
+```
+
+## Returning values from transactions
+
+If you need to return data from transactions, [runTransaction](Classes/BaseFirestoreRepository.md#RunTransaction) receives a [type parameter](https://www.typescriptlang.org/docs/handbook/generics.html#using-type-parameters-in-generic-constraints) of the output value of your transaction.
+
+```typescript
+import { runTransaction } from 'fireorm';
+import { Band } from './wherever-our-models-are';
+
+const band = new Band();
+band.id = 'dream-theater';
+band.name = 'DreamTheater';
+band.formationYear = 1985;
+
+await runTransaction<Band>(async tran => {
+  const bandTranRepository = tran.getRepository(Band);
+  const albumTranRepository = tran.getRepository(Album);
+
+  return bandTranRepository.create(band);
+});
 ```
 
 ## Limitations
 
-Please be aware that Firestore has many limitations when working with Transactions and BatchedWrites. You can learn more [here](https://firebase.google.com/docs/firestore/manage-data/transactions).
+Please be aware that Firestore has many limitations when working with transactions. You can learn more [here](https://firebase.google.com/docs/firestore/manage-data/transactions).

docgen/sidebar.md

@@ -9,5 +9,6 @@
   - [Manage Data](Manage_Data.md)
   - [SubCollections](Subcollections.md)
   - [Transactions](Transactions.md)
+  - [Batches](Batches.md)
   - [Custom Repositories](Custom_Repositories.md)
-  - [Validation](Validation.md)
+  - [Validation](Validation.md)

docgen/typedoc.json

@@ -7,7 +7,6 @@
   "gaSite": "Fireorm Type Documentation",
   "excludeExternals": true,
   "excludeNotExported": true,
-  "categorizeByGroups": false,
   "hideBreadcrumbs": true,
   "plugins": ["typedoc-plugin-markdown"],
   "theme": "docgen/typedoc-docsify",

package.json

@@ -3,7 +3,7 @@
   "description": "ORM for Firestore",
   "version": "0.0.0-development",
   "author": "Willy Ovalle <[email protected]>",
-  "homepage": "https://wovalle.github.io/fireorm/",
+  "homepage": "https://fireorm.js.org",
   "license": "ISC",
   "main": "lib/src/index.js",
   "types": "lib/src/index.d.ts",
@@ -43,29 +43,31 @@
     "@commitlint/cli": "^8.2.0",
     "@commitlint/config-conventional": "^8.2.0",
     "@commitlint/travis-cli": "^8.2.0",
-    "@google-cloud/firestore": "^2.4.0",
+    "@google-cloud/firestore": "^3.5.0",
     "@types/chai": "^4.1.7",
     "@types/chai-as-promised": "^7.1.2",
-    "@types/mocha": "^5.2.7",
+    "@types/mocha": "^7.0.1",
     "@types/pluralize": "^0.0.29",
+    "@types/sinon": "^7.5.1",
     "@types/uuid": "^3.4.5",
     "chai": "^4.2.0",
-    "class-validator": "^0.10.2",
+    "class-validator": "^0.11.0",
     "docsify-cli": "^4.3.0",
     "dotenv": "^8.1.0",
     "firebase-admin": "^8.1.0",
     "gh-pages-deploy": "^0.5.1",
-    "husky": "^3.0.8",
-    "mocha": "^6.1.4",
-    "mock-cloud-firestore": "^0.10.0",
+    "husky": "^4.2.3",
+    "mocha": "^7.0.1",
+    "mock-cloud-firestore": "^0.11.0",
     "reflect-metadata": "^0.1.13",
     "rimraf": "^3.0.0",
-    "semantic-release": "^15.13.12",
+    "semantic-release": "^17.0.3",
+    "sinon": "^9.0.0",
     "ts-node": "^8.3.0",
-    "tslint": "^5.12.0",
-    "typedoc": "^0.15.0",
+    "tslint": "^6.0.0",
+    "typedoc": "^0.16.10",
     "typedoc-plugin-markdown": "^2.2.7",
-    "typescript": "^3.2.2"
+    "typescript": "^3.7.5"
   },
   "peerDependencies": {
     "reflect-metadata": "^0.1.13"