Support for create a Firebase Document Reference and offset query

src/AbstractFirestoreRepository.ts

@@ -1,5 +1,5 @@
 import { plainToClass } from 'class-transformer';
-import { DocumentSnapshot, QuerySnapshot } from '@google-cloud/firestore';
+import { DocumentSnapshot, QuerySnapshot, DocumentReference } from '@google-cloud/firestore';
 import { ValidationError } from './Errors/ValidationError';
 
 import {
@@ -250,6 +250,24 @@ export abstract class AbstractFirestoreRepository<T extends IEntity> extends Bas
     return new QueryBuilder<T>(this).limit(limitVal);
   }
 
+  /**
+   * Returns a new QueryBuilder with the offset of the results
+   * to return. Can only be used once per query.
+   *
+   * @param {number} offsetVal number of results to return
+   * Must be greater or equal than 0
+   * @returns {IQueryBuilder<T>} QueryBuilder A new QueryBuilder with
+   * the specified limit applied
+   * @memberof AbstractFirestoreRepository
+   */
+  offset(offsetVal: number): IQueryBuilder<T> {
+    if (offsetVal < 0) {
+      throw new Error(`offsetVal must be greater than 0. It received: ${offsetVal}`);
+    }
+
+    return new QueryBuilder<T>(this).offset(offsetVal);
+  }
+
   /**
    * Returns a new QueryBuilder with an additional ascending order
    * specified by @param prop. Can only be used once per query.
@@ -349,6 +367,7 @@ export abstract class AbstractFirestoreRepository<T extends IEntity> extends Bas
   abstract execute(
     queries: IFireOrmQueryLine[],
     limitVal?: number,
+    offsetVal?: number,
     orderByObj?: IOrderByParams,
     single?: boolean
   ): Promise<T[]>;
@@ -397,4 +416,15 @@ export abstract class AbstractFirestoreRepository<T extends IEntity> extends Bas
    * @memberof AbstractFirestoreRepository
    */
   abstract delete(id: string): Promise<void>;
+
+  /**
+   * Return the firestore Document Reference
+   * Must be implemented by base repositores
+   *
+   * @abstract
+   * @param {string} id
+   * @returns {DocumentReference}
+   * @memberof AbstractFirestoreRepository
+   */
+  abstract getReference(id: string): DocumentReference;
 }

src/BaseFirestoreRepository.ts

@@ -1,6 +1,6 @@
 import 'reflect-metadata';
 
-import { CollectionReference, WhereFilterOp } from '@google-cloud/firestore';
+import { CollectionReference, DocumentReference, WhereFilterOp } from '@google-cloud/firestore';
 
 import { IRepository, IFireOrmQueryLine, IOrderByParams, IEntity, Constructor } from './types';
 
@@ -77,6 +77,10 @@ export class BaseFirestoreRepository<T extends IEntity> extends AbstractFirestor
     await this.firestoreColRef.doc(id).delete();
   }
 
+  getReference(id: string): DocumentReference {
+    return this.firestoreColRef.doc(id);
+  }
+
   async runTransaction<R>(executor: (tran: TransactionRepository<T>) => Promise<R>) {
     // Importing here to prevent circular dependency
     const { runTransaction } = await import('./helpers');
@@ -98,6 +102,7 @@ export class BaseFirestoreRepository<T extends IEntity> extends AbstractFirestor
   async execute(
     queries: Array<IFireOrmQueryLine>,
     limitVal?: number,
+    offsetVal?: number,
     orderByObj?: IOrderByParams,
     single?: boolean
   ): Promise<T[]> {
@@ -116,6 +121,10 @@ export class BaseFirestoreRepository<T extends IEntity> extends AbstractFirestor
       query = query.limit(limitVal);
     }
 
+    if (offsetVal) {
+      query.offset(offsetVal);
+    }
+
     return query.get().then(this.extractTFromColSnap);
   }
 }

src/QueryBuilder.ts

@@ -14,6 +14,7 @@ import {
 export default class QueryBuilder<T extends IEntity> implements IQueryBuilder<T> {
   protected queries: Array<IFireOrmQueryLine> = [];
   protected limitVal: number;
+  protected offsetVal: number;
   protected orderByObj: IOrderByParams;
 
   constructor(protected executor: IQueryExecutor<T>) {}
@@ -117,6 +118,16 @@ export default class QueryBuilder<T extends IEntity> implements IQueryBuilder<T>
     return this;
   }
 
+  offset(offsetVal: number): QueryBuilder<T> {
+    if (this.offsetVal) {
+      throw new Error(
+        'A offset function cannot be called more than once in the same query expression'
+      );
+    }
+    this.offsetVal = offsetVal;
+    return this;
+  }
+
   orderByAscending(prop: IWherePropParam<T>): QueryBuilder<T> {
     if (this.orderByObj) {
       throw new Error(
@@ -148,13 +159,14 @@ export default class QueryBuilder<T extends IEntity> implements IQueryBuilder<T>
   }
 
   find(): Promise<T[]> {
-    return this.executor.execute(this.queries, this.limitVal, this.orderByObj);
+    return this.executor.execute(this.queries, this.limitVal, this.offsetVal, this.orderByObj);
   }
 
   async findOne(): Promise<T | null> {
     const queryResult = await this.executor.execute(
       this.queries,
       this.limitVal,
+      this.offsetVal,
       this.orderByObj,
       true
     );

src/Transaction/BaseFirestoreTransactionRepository.ts

@@ -1,4 +1,4 @@
-import { CollectionReference, Transaction, WhereFilterOp } from '@google-cloud/firestore';
+import { CollectionReference, Transaction, WhereFilterOp, DocumentReference } from '@google-cloud/firestore';
 
 import {
   IEntity,
@@ -85,6 +85,10 @@ export class TransactionRepository<T extends IEntity> extends AbstractFirestoreR
     this.transaction.delete(this.firestoreColRef.doc(id));
   }
 
+  getReference(id: string): DocumentReference {
+    return this.firestoreColRef.doc(id);
+  }
+
   limit(): IQueryBuilder<T> {
     throw new Error('`limit` is not available for transactions');
   }

src/types.ts

@@ -53,6 +53,7 @@ export interface IOrderable<T extends IEntity> {
 
 export interface ILimitable<T extends IEntity> {
   limit(limitVal: number): IQueryBuilder<T>;
+  offset(offsetVal: number): IQueryBuilder<T>;
 }
 
 export type IQueryBuilder<T extends IEntity> = IQueryable<T> & IOrderable<T> & ILimitable<T>;
@@ -61,6 +62,7 @@ export interface IQueryExecutor<T> {
   execute(
     queries: IFireOrmQueryLine[],
     limitVal?: number,
+    offsetVal?: number,
     orderByObj?: IOrderByParams,
     single?: boolean
   ): Promise<T[]>;
@@ -71,6 +73,7 @@ export interface IBaseRepository<T extends IEntity> {
   create(item: PartialBy<T, 'id'>): Promise<T>;
   update(item: T): Promise<T>;
   delete(id: string): Promise<void>;
+  getReference(id: string): DocumentReference;
 }
 
 export type IRepository<T extends IEntity> = IBaseRepository<T> &

test/functional/6-document-references.int-spec.ts

@@ -60,4 +60,17 @@ describe('Integration test: Using Document References', () => {
     expect(band.length).toEqual(1);
     expect(band[0].name).toEqual('Steven Wilson');
   });
+
+  it('should document reference be the same', async () => {
+    const pt = new Band();
+    pt.id = 'porcupine-tree';
+    pt.name = 'Porcupine Tree';
+    pt.formationYear = 1987;
+    pt.genres = ['psychedelic-rock', 'progressive-rock', 'progressive-metal'];
+
+    await bandRepository.create(pt);
+    const ptRef = firestore.collection(colName).doc(pt.id);
+
+    expect(bandRepository.getReference(pt.id)).toEqual(ptRef);
+  });
 });