feat: add queryFirst, queryOne queries which return only one result

add distinct, forUpdate query options

Author: Laszlo Radics

docs/API/PgDb.md

@@ -87,6 +87,19 @@ Executes an arbitrary sql string with parameters / named parameters.
 let res1 = await schema.query('SELECT MAX(point) from game1.scores WHERE name=$1 ', ['player1']);
 let res2 = await schema.query('SELECT MAX(point) from !:schema.scores WHERE name=:name ', {schema:'game1', name:'player1'});
 ```
+---
+##queryFirst
+<span class="def"><span class="func">queryFirst</span>(sql:<span class="type">string</span>, params?:<span class="type">any[]|{}</span>, options?:<span class="type">SqlQueryOptions</span>):Promise&lt;<span class="type">any</span>&gt;</span>
+<a name="query"></a>
+
+Executes an arbitrary sql string with parameters / named parameters. Return the first record. 
+
+---
+##queryOne
+<span class="def"><span class="func">query</span>(sql:<span class="type">string</span>, params?:<span class="type">any[]|{}</span>, options?:<span class="type">SqlQueryOptions</span>):Promise&lt;<span class="type">any</span>&gt;</span>
+<a name="query"></a>
+ 
+Executes an arbitrary sql string with parameters / named parameters. Return the first record, throw Error if there are more. 
 
 ---
 ## queryOneField

docs/API/QueryOptions.md

@@ -14,10 +14,12 @@ interface QueryOptions {
     limit?:number;
     offset?: number;
     orderBy?: string|string[]|{[fieldName:string]:'asc'|'desc'};//free text or column list
-    groupBy?:string|string[];//free text or column list
-    fields?: string|string[];//free text or column list
-    skipUndefined?:boolean; //if there is an undefined value in the conditions, shall it be skipped. Default raise error.
+    groupBy?:string|string[]; //free text or column list
+    fields?: string|string[]; //free text or column list
+    skipUndefined?:boolean;   //if there is an undefined value in the conditions, shall it be skipped. Default raise error.
     logger?:PgDbLogger;
+    distinct?: boolean;       // SELECT DISTINCT statement
+    forUpdate?: boolean;      // FOR UPDATE statement
 }
 ```
 where orderBy/groupBy/fields can be either an array (in that case will get quotation if needed) 

src/pgTable.ts

@@ -4,6 +4,7 @@ import generateWhere from "./queryWhere";
 import {PgSchema} from "./pgSchema";
 import {pgUtils} from "./pgUtils";
 import * as _ from 'lodash';
+import * as stream from "stream";
 
 const util = require('util');
 
@@ -87,8 +88,8 @@ export class PgTable<T> extends QueryAble {
 
     async insertAndGet(records: T[], options?: InsertOption & Return): Promise<T[]>
     async insertAndGet(records: T, options?: InsertOption & Return): Promise<T>
-    async insertAndGet(records: any, options?: any): Promise<any> {
-        var returnSingle = false;
+    async insertAndGet(records: any, options?: InsertOption & Return): Promise<any> {
+        let returnSingle = false;
         options = options || {};
 
         if (!records) {
@@ -201,11 +202,10 @@ export class PgTable<T> extends QueryAble {
     }
 
     async find(conditions: { [k: string]: any }, options?: QueryOptions): Promise<T[]>
-    async find(conditions: { [k: string]: any }, options?: QueryOptions & Stream): Promise<{ on: any }>
+    async find(conditions: { [k: string]: any }, options?: QueryOptions & Stream): Promise<stream.Readable>
     async find(conditions: { [k: string]: any }, options?: any): Promise<any> {
         options = options || {};
         options.skipUndefined = options.skipUndefined === true || (options.skipUndefined === undefined && ['all', 'select'].indexOf(this.db.config.skipUndefined) > -1);
-
         let where = _.isEmpty(conditions) ? {
             where: " ",
             params: null
@@ -216,15 +216,15 @@ export class PgTable<T> extends QueryAble {
 
 
     async findWhere(where: string, params: any[] | {}, options?: QueryOptions): Promise<T[]>
-    async findWhere(where: string, params: any[] | {}, options?: QueryOptions & Stream): Promise<any> //Readable
+    async findWhere(where: string, params: any[] | {}, options?: QueryOptions & Stream): Promise<stream.Readable>
     async findWhere(where: string, params: any, options?: any): Promise<any> {
         options = options || {};
         let sql = `SELECT ${pgUtils.processQueryFields(options)} FROM ${this.qualifiedName} WHERE ${where} ${pgUtils.processQueryOptions(options)}`;
         return options.stream ? this.queryAsStream(sql, params, options) : this.query(sql, params, options);
     }
 
     public async findAll(options?: QueryOptions): Promise<T[]>
-    public async findAll(options?: QueryOptions & Stream): Promise<any> //Readable
+    public async findAll(options?: QueryOptions & Stream): Promise<stream.Readable>
     public async findAll(options?: any): Promise<any> {
         options = options || {};
         let sql = `SELECT ${pgUtils.processQueryFields(options)} FROM ${this.qualifiedName} ${pgUtils.processQueryOptions(options)}`;

src/pgUtils.ts

@@ -12,14 +12,15 @@ export let pgUtils = {
     },
 
     processQueryFields(options: QueryOptions): string {
+        let s = options && options.distinct ? ' DISTINCT ' : ' ';
         if (options && options.fields) {
             if (Array.isArray(options.fields)) {
-                return ' ' + options.fields.map(pgUtils.quoteField).join(',');
+                return s + options.fields.map(pgUtils.quoteField).join(', ');
             } else {
-                return ' ' + options.fields;
+                return s + options.fields;
             }
         } else {
-            return ' *';
+            return s + ' *';
         }
     },
 
@@ -97,6 +98,9 @@ export let pgUtils = {
         if (options.offset) {
             sql += util.format(' OFFSET %d', options.offset);
         }
+        if (options.forUpdate){
+            sql += ' FOR UPDATE';
+        }
         return sql;
     },
 

src/queryAble.ts

@@ -13,6 +13,8 @@ export interface QueryOptions {
     groupBy?: string | string[];//free text or column list
     fields?: string | string[];//free text or column list
     logger?: PgDbLogger;
+    forUpdate?: boolean;
+    distinct?: boolean;
     skipUndefined?: boolean;
 }
 
@@ -254,6 +256,19 @@ export class QueryAble {
         }
     }
 
+    async queryOne(sql: string, params?: any[] | {}, options?: SqlQueryOptions): Promise<any> {
+        let res = await this.query(sql, params, options);
+        if (res.length > 1) {
+            throw new Error('More then one rows exists');
+        }
+        return res[0];
+    }
+
+    async queryFirst(sql: string, params?: any[] | {}, options?: SqlQueryOptions): Promise<any> {
+        let res = await this.query(sql, params, options);
+        return res[0];
+    }
+
     /** @return one record's one field */
     async queryOneField(sql: string, params?: any[] | {}, options?: SqlQueryOptions): Promise<any> {
         let res = await this.query(sql, params, options);

src/test/pgDbSpec.ts

@@ -62,6 +62,7 @@ function parseComplexType(str) {
     return valList;
 }
 
+jasmine.DEFAULT_TIMEOUT_INTERVAL = 800000;
 
 describe("pgdb", () => {
     let pgdb: PgDb;
@@ -70,8 +71,6 @@ describe("pgdb", () => {
     let tableGroups: PgTable<any>;
 
     beforeAll(w(async () => {
-        jasmine.DEFAULT_TIMEOUT_INTERVAL = 800000;
-
         /**
          * Using environment variables, e.g.
          * PGUSER (defaults USER env var, so optional)
@@ -767,9 +766,46 @@ describe("pgdb", () => {
         let list = ["'A'", '"A"', '//', '\\', '""', "''", '--', '/*', '<!--'];
         await table.insert({name: 'A', textList: list});
         let rec: any = await table.findOne({name: 'A'});
-        console.log(list + '\n' + rec.textList);
+        // console.log(list + '\n' + rec.textList);
         let isDifferent = list.some((v, i) => rec.textList[i] !== v);
         expect(isDifferent).toBeFalsy();
     }));
 
+    it("Testing distinct", w(async () => {
+        await table.insert({name: 'A', aCategory: 'A'});
+        await table.insert({name: 'B', aCategory: 'A'});
+        let recs = await table.find({aCategory: 'A'}, {fields: ['aCategory'], distinct: true});
+        expect(recs.length).toEqual(1);
+    }));
+
+    it("Testing queryOne", w(async () => {
+        await table.insert({name: 'A', aCategory: 'A'});
+        await table.insert({name: 'B', aCategory: 'A'});
+        try {
+            let recs = await table.queryOne(`SELECT * FROM ${table} WHERE "aCategory" = 'A'`);
+            expect(false).toBeTruthy();
+        } catch (e) {
+            expect('' + e).toEqual("Error: More then one rows exists");
+        }
+    }));
+    it("Testing queryFirst", w(async () => {
+        await table.insert({name: 'A', aCategory: 'A'});
+        await table.insert({name: 'B', aCategory: 'A'});
+        let rec = await table.queryFirst(`SELECT * FROM ${table} WHERE "aCategory" = 'A'`);
+        expect(rec.aCategory).toEqual('A');
+    }));
+
+    it("Testing forUpdate", w(async () => {
+        await table.insert({name: 'A', aCategory: 'A'});
+        let pgdb1 = await table.db.transactionBegin();
+        await pgdb1.tables['users'].find({aCategory: 'A'},{forUpdate: true});
+        let p = table.update({aCategory: 'A'}, {name: 'C'});
+        await new Promise(resolve => setTimeout(resolve, 500));
+        await pgdb1.tables['users'].update({aCategory: 'A'}, {name: 'B'});
+        await pgdb1.transactionCommit();
+        await p;
+        let rec = await table.findFirst({aCategory: 'A'});
+        expect(rec.name).toEqual('C');
+    }));
+
 });