pogi 2.11.0

package/docs/API/QueryOptions.md

@@ -0,0 +1,77 @@
+##SqlQueryOption, InsertOption
+You can set the logger.
+```js
+export interface SqlQueryOptions {
+    logger?: PgDbLogger;
+}
+```
+
+##QueryOptions
+Query (`select`) option has to follow the following interface:
+
+```js
+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.
+    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) 
+or a free text string with all the possibilities.
+
+logger can be specified for the current query only.
+
+```js
+await pgdb.users.find({medal:['g','s','b']}, {orderBy:'sum(*)', groupBy:['country'], fields:'sum(*) as numberOfMedals, country'});
+```
+### orderBy
+You can do as you like:
+```js
+await pgdb.users.find({}, {orderBy:{name:'desc', ageCategory:'asc'}});
+await pgdb.users.find({}, {orderBy:['name desc', 'ageCategory asc']});
+await pgdb.users.find({}, {orderBy:['-name', '+ageCategory']});
+await pgdb.users.find({}, {orderBy:['name', 'ageCategory']});
+await pgdb.users.find({}, {orderBy:'name dec, "ageCategory" asc'});
+```
+### groupBy
+```js
+await pgdb.users.find({}, {groupBy:'name, "ageCategory", count(*)'});
+await pgdb.users.find({}, {groupBy:['name', 'ageCategory', 'count(*)']});
+```
+
+### skipUndefined
+```js
+await pgdb.users.find({}, {name:'joe', password:undefined}); //raise error
+await pgdb.users.find({}, {name:'joe', password:undefined}, {skipUndefined:true}); //return the record with name 'joe'
+```
+
+##UpdateDeleteOption
+```js
+export interface SqlQueryOptions {
+    skipUndefined?:boolean; //if there is an undefined value in the conditions, shall it be skipped. Default raise error.
+    logger?: PgDbLogger;
+}
+```
+
+## & Return, & Stream
+Additional interfaces to set return value type.
+
+With `stream:true` query will return with stream instead of the populated result.
+
+With `return *` insert / update / delete query will return the affected rows (this is the default).
+
+`return string[]` is the same as '*' but only return with the specified columns
+```js
+export interface Return {
+    return?:string[]|'*';
+}
+export interface Stream {
+    stream: true;
+}
+```

package/docs/API/condition.md

@@ -0,0 +1,133 @@
+#Conditions and operators
+
+##Basic examples
+
+| Condition         | SQL                      
+| -------------     |:-------------- 
+| {id: 2}           | "id" = 2  
+| {'id <': 2}       | "id" < 2      
+| {'id >': 2}       | "id" > 2
+| {'id <=': 2}      | "id" <= 2      
+| {'id >=': 2}      | "id" >= 2
+| {'id !=': 2}      | "id" != 2
+| {'id <>': 2}      | "id" != 2
+| {'id': null}      | "id" is null
+| {'id !=': null}   | "id" is not null
+| {'id is not': null}| "id" is not null
+| {'id in':[1,2,3]} | "id" in (1,2,3)
+| {'id not in':[1,2,3]}| "id" not in (1,2,3)
+
+###Extended
+
+| Condition          | SQL                      
+| -------------      |:-------------- 
+| {id: [1,2,3]}      | "id" in (1,2,3)
+| {'id <>': [1,2,3]} | "id" not in (1,2,3) 
+| {'id =*':'gamma'}  | LOWER("id") = LOWER('gamma')
+| {'fruits =*':'KiWi'}  | LOWER("fruits") && '{kiwi}' //Has to have the LOWER function defined see below. (It uses GIN index if defined on fruits)
+
+##Pattern matching
+[PostgreSQL Documentation](https://www.postgresql.org/docs/9.6/static/functions-matching.html)
+
+| Condition             | SQL                      
+| -------------         |:-------------- 
+| {'id ~~': 'a%'}       | "id" LIKE 'a%'
+| {'id !~~': 'a%'}      | "id" NOT LIKE 'a%'
+| {'id like': 'a%'}     | "id" LIKE 'a%'
+| {'id not like': 'a%'} | "id" NOT LIKE 'a%'
+| {'id ~~*': 'a%'}      | "id" ILIKE 'a%'
+| {'id !~~*': 'a%'}     | "id" NOT ILIKE 'a%'
+| {'id ilike': 'a%'}    | "id" ILIKE 'a%'
+| {'id not ilike': 'a%'} | "id" NOT ILIKE 'a%'
+| {'id similar to': 'a%'} | "id" SIMILAR TO 'a%'
+| {'id not similar to': 'a%'} | "id" NOT SIMILAR TO 'a%'
+| {'id ~': '^a'}        | "id" ~ '^a'
+| {'id !~': '^a'}       | "id" !~ '^a'
+| {'id ~*': '^a'}       | "id" ~* '^a'
+| {'id !~*': '^a'}      | "id" !~* '^a'
+| {'id is distinct from': '^a'}| "id" IS DISTINCT FROM '^a'
+| {'id is not distinct from': '^a'}| "id" IS NOT DISTINCT FROM '^a'
+
+###Extended
+
+| Condition                   | SQL                      
+| -------------               |:-------------- 
+| {'id ~~': ['1%','2%','3%']} | "id" LIKE ANY('{1%,2%,3%}')
+| {'id !~~': ['1%','2%','3%']}| "id" NOT LIKE ALL('{1%,2%,3%}') 
+| {'id ~': ['^1','^2','^3']}  | "id" LIKE ANY('{^1,^2,^3}')
+| {'id !~': ['^1','^2','^3']} | "id" NOT LIKE ALL('{^1,^2,^3}') 
+
+
+##Array type 
+[PostgreSQL Documentation](https://www.postgresql.org/docs/current/static/functions-array.html)
+
+| Condition          | SQL                 | note                     
+| -------------      |:--------------      | :-------------- 
+| {'ids @>':[1,2,3]} | "ids" @> '{1,2,3}'  | ids contains all of 1,2,3     
+| {'ids <@':[1,2,3]} | "ids" <@ '{1,2,3}'  | ids is a subset of {1,2,3}
+| {'ids &&':[1,2,3]} | "ids" && '{1,2,3}'  | ids overlaps with {1,2,3}
+| {'ids': [1,2,3]}   | "ids" = '{1,2,3}'   | 
+| {'ids': 'a'}       | 'a' = ANY("ids")    | 
+| {'ids <>': 'a'}    | 'a' <> ANY("ids")   | 
+
+Please note that as-of-9.5 `'a' = ANY("ids")` is not using the index in psql. So if have a `GIN` index is defined on the column "ids",
+You should use `{'ids &&': ['a']}` (that is translated to `"ids" && '{a}'`).
+
+###Extended
+| Condition          | SQL                      
+| -------------      |:-------------- 
+| {'ids ~': 'a%'}    | EXISTS (SELECT * FROM (SELECT UNNEST("ids") _el) _arr WHERE _arr._el ~ 'a%')'; //same with all pattern matching operator
+| {'names &&*': ['A','B','C']}    | LOWER("names") && '{a, b, c}' //case insensitive overlap operator, has to have the LOWER function defined for arrays (see below) 
+
+##Jsonb type
+[PostgreSQL Documentation](https://www.postgresql.org/docs/current/static/functions-json.html)
+
+| Condition               | SQL                                 | NOTE
+| -------------           |:--------------                      |:---
+| {'jdata @>':[1,2,3]}       | "jdata" @> '[1,2,3]'                   |
+| {'jdata @>':{a:1}}         | "jdata" @> '{a:1}'                     |
+| {'jdata <@':[1,2,3]}       | "jdata" <@ '[1,2,3]'                   |
+| {'jdata <@':{a:1}}         | "jdata" <@ '{a:1}'                     |
+| {'jdata ?':'a'}            | "jdata" ? 'a'                          |
+| {'jdata ?&#124;':['a','b']}| "jdata" ?&#124; '{a,b}'                |
+| {'jdata ?&':['a','b']}     | "jdata" ?& '{a,b}'                     |
+| {'jdata -> a':{a:3}}       | "jdata" -> 'a' = '{"a":3}'::jsonb      |
+| {'jdata -> 3':{a:3}}       | "jdata" ->  3  = '{"a":3}'::jsonb      |if the field is a number, the quote wont apply as it could refer index also 
+| {"jdata -> '3'":{a:3}}     | "jdata" -> '3' = '{"a":3}'::jsonb      |... so you have to apply that manually
+| {'jdata ->> a':3}          | "jdata" ->>'a' = 3                     |
+| {'jdata ->> 3':3}          | "jdata" ->> 3  = 3                     |if the field is a number, the quote wont apply as it could refer index also
+| {'jdata ->> '3'":'{"a": 3}'}   | "jdata"->>3 = '{"a": 3}'           |... so you have to apply that manually
+| {"jdata #> '{a,3}'":{a:3}}     | "jdata"#>'{a,3}' = '{"a":3}'::jsonb|surronding {} with ' is possible but not obligatory 
+| {"jdata #>> {a,3}":'{"a": 3}'} | "jdata"#>>'{a,3}' = '{"a": 3}'     |
+| {"jdata #>> {a} >":'a'          | "jdata"#>>'{a}' > 'a'             |
+
+Note: 
+ 
+ `->`,`#>` returns as a JsonObject
+ 
+ `->>`, `#>>` returns as a string. 
+
+At the moment they are not converted automatically thou, for `->>` you should use JSON.stringify if needed.
+(this is a later todo, you can help us! :), same goes for `->`, it not converted automaticaly if not an object passed in, but a number or string) 
+
+## AND - OR
+condition-expressions can be joined together e.g.:
+
+| Condition                | SQL                      
+| -------------            |:-------------- 
+| {id:1, name:'a'}         | id=1 AND name='a'
+| {or: [{id:1}, {name:'a'}]} | id=1 OR  name='a'
+| {and: [<br/>&nbsp;&nbsp;&nbsp;&nbsp; or: [{id:1}, {'port >':'1024'}], <br/>&nbsp;&nbsp;&nbsp;&nbsp; or: [{host:'localhost', os:'linux'}, {host:'127.0.0.1'}]<br>]} | (.. OR ..) AND ((.. AND ..) OR ..)
+
+
+# Definition of LOWER function for array type
+ CREATE OR REPLACE FUNCTION LOWER(text[]) RETURNS text[] LANGUAGE SQL IMMUTABLE AS
+ $$
+     SELECT array_agg(LOWER(value)) FROM unnest($1) value;
+ $$;
+
+
+
+
+
+

package/docs/connection.md

@@ -0,0 +1,91 @@
+##Connection
+
+### Connection with connectionString
+
+``` js
+let pgdb = await PgDb.connect({connectionString:'postgres://username@hostname/database', logger:console});
+```
+
+where username/hostname/database are all optional. It could be provided through environment variables (EXPORT).
+
+### Connection with Options Object
+``` js
+let pgdb = await PgDb.connect({
+        host: 'localhost',
+        user: 'localuser',
+        database: 'localdatabase',
+        password: 'localpassword', 
+        port: 5432, 
+        max: 10,
+        logger:console,
+    });
+```
+
+With the following options:
+``` js
+export interface ConnectionOptions {
+    //--- node-postgres specific ----------------------
+    host?:string;
+    user?:string;              //can be specified through PGUSER     env variable (defaults USER env var)
+    database?:string;          //can be specified through PGDATABASE env variable (defaults USER env var)
+    password?:string;          //can be specified through PGPASSWORD env variable
+    port?:number;              //can be specified through PGPORT     env variable
+    connectionString?:string;  //'postgres://username:password@hostname/database'
+    
+    poolSize?:number;            //number of connections to use in connection pool. 0 - disable pooling
+    min?:number;                 //minimum number of resources to keep in pool at any given time.  
+    max?:number;      
+    reapIntervalMillis?:number;  //frequency to check for idle clients within the client pool
+    poolLog?:boolean;            //pool log function / boolean
+    idleTimeoutMillis?:number;   // how long a client is allowed to remain idle before being closed
+    poolIdleTimeout?:number;
+        
+    rows?:number;                //number of rows to return at a time from a prepared statement's portal. 0 will return all rows at once
+    binary?:boolean;
+    client_encoding?:string;
+    ssl?:boolean| any;           // TlsOptions;
+    application_name?:string;
+    fallback_application_name?:string;
+    parseInputDatesAsUTC?:boolean; 
+    
+    //--- pogi specific ----------------------------
+    logger?:PgDbLogger;
+    skipUndefined?: 'all' | 'select' | 'none'; //if there is a undefined value in the query condition, what should pogi do. Default is 'none', meaning raise an error if a value is undefined.
+}
+```
+
+About node-postgres specific, more explanation can be found at
+https://github.com/brianc/node-postgres/blob/f6c40b9331c90d794d5fcbb1d4ae2f28eabd4d42/lib/defaults.js 
+and 
+https://github.com/coopernurse/node-pool
+
+##skipUndefined
+while most settings are self explanatory, this parameter is important. In the first version of pogi
+we ignored the condition if the value was undefined (null was not ignored) in order for ease the use e.g.:
+``` ts
+    let query = {
+        powerfull: params.powerfull,
+        wise: params.wise
+    }
+    await pgdb.users.find(query);
+```
+would return a result if e.g. the `form.wise` would be undefined. While this is comfortable
+in many situation, it can cause critical issues e.g. for update
+``` ts
+   await pgdb.users.update({id:user.id}, {password});
+```
+would update all users password, in case of the id is undefined. (Although this can be mitigated
+with the `updateOne` function as well.) Still the best if no undefined value is allowed in the conditions.
+Nevertheless to keep the compatibility, this parameter added, and skipUndefined can be set to `all` if needed.
+`select` would allow undefined values for selects/count only but would be strict for update/deletes.
+`none` is the new default value, meaning undefined value considered as programming error and will throw an exception.
+This setting can be specified on query level as well.
+
+
+### Static singleton
+If there is no reference kept to the object there is a static function to get the same object everywhere, 
+(so no need to keep recreating and set up every time). At the moment doesnt handle env variables beside password.
+
+``` js
+    let pgdb = await PgDb.getInstance({connectionString:'postgres://username@hostname/database', logger:console});
+```

package/docs/css/docs.css

@@ -0,0 +1,164 @@
+.func{
+    color:black;
+}
+.type{
+    color:chocolate;
+}
+.def{
+    color:purple;
+    font-weight: bold;
+}
+
+
+/**
+ * Obsidian style
+ * ported by Alexander Marenin (http://github.com/ioncreature)
+ */
+
+.hljs {
+    display: block;
+    overflow-x: auto;
+    padding: 0.5em;
+    background: #282b2e;
+    -webkit-text-size-adjust: none;
+}
+
+.hljs-keyword,
+.hljs-literal,
+.hljs-change,
+.hljs-winutils,
+.hljs-flow,
+.nginx .hljs-title,
+.css .hljs-id,
+.tex .hljs-special {
+    color: #93c763;
+}
+
+.hljs-number {
+    color: #ffcd22;
+}
+
+.hljs {
+    color: #e0e2e4;
+}
+
+.css .hljs-tag,
+.css .hljs-pseudo {
+    color: #d0d2b5;
+}
+
+.hljs-attribute,
+.hljs .hljs-constant {
+    color: #668bb0;
+}
+
+.xml .hljs-attribute {
+    color: #b3b689;
+}
+
+.xml .hljs-tag .hljs-value {
+    color: #e8e2b7;
+}
+
+.hljs-code,
+.hljs-class .hljs-title,
+.hljs-header {
+    color: white;
+}
+
+.hljs-class,
+.hljs-hexcolor {
+    color: #93c763;
+}
+
+.hljs-regexp {
+    color: #d39745;
+}
+
+.hljs-at_rule,
+.hljs-at_rule .hljs-keyword {
+    color: #a082bd;
+}
+
+.hljs-doctype {
+    color: #557182;
+}
+
+.hljs-link_url,
+.hljs-tag,
+.hljs-tag .hljs-title,
+.hljs-bullet,
+.hljs-subst,
+.hljs-emphasis,
+.hljs-type,
+.hljs-preprocessor,
+.hljs-pragma,
+.ruby .hljs-class .hljs-parent,
+.hljs-built_in,
+.django .hljs-template_tag,
+.django .hljs-variable,
+.smalltalk .hljs-class,
+.django .hljs-filter .hljs-argument,
+.smalltalk .hljs-localvars,
+.smalltalk .hljs-array,
+.hljs-attr_selector,
+.hljs-pseudo,
+.hljs-addition,
+.hljs-stream,
+.hljs-envvar,
+.apache .hljs-tag,
+.apache .hljs-cbracket,
+.tex .hljs-command,
+.hljs-prompt,
+.hljs-name {
+    color: #8cbbad;
+}
+
+.hljs-string {
+    color: #ec7600;
+}
+
+.hljs-comment,
+.hljs-annotation,
+.hljs-blockquote,
+.hljs-horizontal_rule,
+.hljs-decorator,
+.hljs-pi,
+.hljs-deletion,
+.hljs-shebang,
+.apache .hljs-sqbracket,
+.tex .hljs-formula {
+    color: #818e96;
+}
+
+.hljs-keyword,
+.hljs-literal,
+.css .hljs-id,
+.hljs-doctag,
+.hljs-title,
+.hljs-header,
+.hljs-type,
+.vbscript .hljs-built_in,
+.rsl .hljs-built_in,
+.smalltalk .hljs-class,
+.diff .hljs-header,
+.hljs-chunk,
+.hljs-winutils,
+.bash .hljs-variable,
+.apache .hljs-tag,
+.tex .hljs-special,
+.hljs-request,
+.hljs-at_rule .hljs-keyword,
+.hljs-status {
+    font-weight: normal;
+}
+
+.coffeescript .javascript,
+.javascript .xml,
+.tex .hljs-formula,
+.xml .javascript,
+.xml .vbscript,
+.xml .css,
+.xml .hljs-cdata {
+    opacity: 0.5;
+}