add docs

lib/formatting.js

@@ -376,14 +376,14 @@ const $as = {
      * Property name for the $[Custom Type Formatting] flag `rawType`.
      *
      * @example
-     * const ctf = pgp.as.ctf; // Custom Type Formatting symbols
+     * const {toPostgres, rawType} = pgp.as.ctf; // Custom Type Formatting symbols
      *
      * class MyType {
      *     constructor() {
-     *         this[ctf.rawType] = true; // set it only when toPostgres returns a pre-formatted result
+     *         this[rawType] = true; // set it only when toPostgres returns a pre-formatted result
      *     }
      *
-     *     [ctf.toPostgres](self) {
+     *     [toPostgres](self) {
      *         // self = this
      *
      *         // return the custom/actual value here

lib/helpers/column-set.js

@@ -86,8 +86,9 @@ const npm = {
  * // 6. Property 'amount' needs to be set to 100, if it is 0
  * // 7. Property 'total' must be skipped during updates, if 'amount' was 0, plus its
  * //    column name is 'total-val'
+ * const {ColumnSet} = pgp.helpers;
  *
- * const cs = new pgp.helpers.ColumnSet([
+ * const cs = new ColumnSet([
  *     '?id', // ColumnConfig equivalent: {name: 'id', cnd: true}
  *     'list:csv', // ColumnConfig equivalent: {name: 'list', mod: ':csv'}
  *     {

lib/helpers/column.js

@@ -91,7 +91,7 @@ const npm = {
  *     capSQL: true // if you want all generated SQL capitalized
  * });
  *
- * const Column = pgp.helpers.Column;
+ * const {Column} = pgp.helpers;
  *
  * // creating a column from just a name:
  * const col1 = new Column('colName');
@@ -207,7 +207,7 @@ class Column extends InnerState {
      *
      * @example
      *
-     * const cs = new pgp.helpers.ColumnSet([
+     * const cs = new ColumnSet([
      *     'id',
      *     'coordinate:json',
      *     {

lib/helpers/methods/insert.js

@@ -62,29 +62,32 @@ const npm = {
  * const pgp = require('pg-promise')({
  *    capSQL: true // if you want all generated SQL capitalized
  * });
+ * const {insert} = pgp.helpers;
  *
  * const dataSingle = {val: 123, msg: 'hello'};
  * const dataMulti = [{val: 123, msg: 'hello'}, {val: 456, msg: 'world!'}];
  *
  * // Column details can be taken from the data object:
  *
- * pgp.helpers.insert(dataSingle, null, 'my-table');
+ * insert(dataSingle, null, 'my-table');
  * //=> INSERT INTO "my-table"("val","msg") VALUES(123,'hello')
  *
  * @example
  *
  * // Column details are required for a multi-row `INSERT`:
+ * const {insert} = pgp.helpers;
  *
- * pgp.helpers.insert(dataMulti, ['val', 'msg'], 'my-table');
+ * insert(dataMulti, ['val', 'msg'], 'my-table');
  * //=> INSERT INTO "my-table"("val","msg") VALUES(123,'hello'),(456,'world!')
  *
  * @example
  *
  * // Column details from a reusable ColumnSet (recommended for performance):
+ * const {ColumnSet, insert} = pgp.helpers;
  *
- * const cs = new pgp.helpers.ColumnSet(['val', 'msg'], {table: 'my-table'});
+ * const cs = new ColumnSet(['val', 'msg'], {table: 'my-table'});
  *
- * pgp.helpers.insert(dataMulti, cs);
+ * insert(dataMulti, cs);
  * //=> INSERT INTO "my-table"("val","msg") VALUES(123,'hello'),(456,'world!')
  *
  */

lib/helpers/methods/sets.js

@@ -57,10 +57,11 @@ const npm = {
  *
  * // Column details from a reusable ColumnSet (recommended for performance);
  * // NOTE: Conditional columns (start with '?') are skipped:
+ * const {ColumnSet, sets} = pgp.helpers;
  *
- * const cs = new pgp.helpers.ColumnSet(['?id','val', 'msg']);
+ * const cs = new ColumnSet(['?id','val', 'msg']);
  *
- * pgp.helpers.sets(data, cs);
+ * sets(data, cs);
  * //=> "val"=123,"msg"='hello'
  *
  */

lib/helpers/methods/update.js

@@ -87,14 +87,15 @@ const npm = {
  * const pgp = require('pg-promise')({
  *    capSQL: true // if you want all generated SQL capitalized
  * });
+ * const {update} = pgp.helpers;
  *
  * const dataSingle = {id: 1, val: 123, msg: 'hello'};
  * const dataMulti = [{id: 1, val: 123, msg: 'hello'}, {id: 2, val: 456, msg: 'world!'}];
  *
  * // Although column details can be taken from the data object, it is not
  * // a likely scenario for an update, unless updating the whole table:
  *
- * pgp.helpers.update(dataSingle, null, 'my-table');
+ * update(dataSingle, null, 'my-table');
  * //=> UPDATE "my-table" SET "id"=1,"val"=123,"msg"='hello'
  *
  * @example
@@ -104,42 +105,44 @@ const npm = {
  * // Dynamic conditions must be escaped/formatted properly:
  * const condition = pgp.as.format(' WHERE id = ${id}', dataSingle);
  *
- * pgp.helpers.update(dataSingle, ['val', 'msg'], 'my-table') + condition;
+ * update(dataSingle, ['val', 'msg'], 'my-table') + condition;
  * //=> UPDATE "my-table" SET "val"=123,"msg"='hello' WHERE id = 1
  *
  * @example
  *
  * // Column details are required for a multi-row `UPDATE`;
  * // Adding '?' in front of a column name means it is only for a WHERE condition:
  *
- * pgp.helpers.update(dataMulti, ['?id', 'val', 'msg'], 'my-table') + ' WHERE v.id = t.id';
+ * update(dataMulti, ['?id', 'val', 'msg'], 'my-table') + ' WHERE v.id = t.id';
  * //=> UPDATE "my-table" AS t SET "val"=v."val","msg"=v."msg" FROM (VALUES(1,123,'hello'),(2,456,'world!'))
  * //   AS v("id","val","msg") WHERE v.id = t.id
  *
  * @example
  *
  * // Column details from a reusable ColumnSet (recommended for performance):
+ * const {ColumnSet, update} = pgp.helpers;
  *
- * const cs = new pgp.helpers.ColumnSet(['?id', 'val', 'msg'], {table: 'my-table'});
+ * const cs = new ColumnSet(['?id', 'val', 'msg'], {table: 'my-table'});
  *
- * pgp.helpers.update(dataMulti, cs) + ' WHERE v.id = t.id';
+ * update(dataMulti, cs) + ' WHERE v.id = t.id';
  * //=> UPDATE "my-table" AS t SET "val"=v."val","msg"=v."msg" FROM (VALUES(1,123,'hello'),(2,456,'world!'))
  * //   AS v("id","val","msg") WHERE v.id = t.id
  *
  * @example
  *
  * // Using parameter `options` to change the default alias names:
  *
- * pgp.helpers.update(dataMulti, cs, null, {tableAlias: 'X', valueAlias: 'Y'}) + ' WHERE Y.id = X.id';
+ * update(dataMulti, cs, null, {tableAlias: 'X', valueAlias: 'Y'}) + ' WHERE Y.id = X.id';
  * //=> UPDATE "my-table" AS X SET "val"=Y."val","msg"=Y."msg" FROM (VALUES(1,123,'hello'),(2,456,'world!'))
  * //   AS Y("id","val","msg") WHERE Y.id = X.id
  *
  * @example
  *
  * // Handling an empty update
+ * const {ColumnSet, update} = pgp.helpers;
  *
- * const cs = new pgp.helpers.ColumnSet(['?id', '?name'], {table: 'tt'}); // no actual update-able columns
- * const result = pgp.helpers.update(dataMulti, cs, null, {emptyUpdate: 123});
+ * const cs = new ColumnSet(['?id', '?name'], {table: 'tt'}); // no actual update-able columns
+ * const result = update(dataMulti, cs, null, {emptyUpdate: 123});
  * if(result === 123) {
  *    // We know the update is empty, i.e. no columns that can be updated;
  *    // And it didn't throw because we specified `emptyUpdate` option.

lib/helpers/methods/values.js

@@ -72,10 +72,11 @@ const npm = {
  * @example
  *
  * // Column details from a reusable ColumnSet (recommended for performance):
+ * const {ColumnSet, values} = pgp.helpers;
  *
- * const cs = new pgp.helpers.ColumnSet(['val', 'msg']);
+ * const cs = new ColumnSet(['val', 'msg']);
  *
- * pgp.helpers.values(dataMulti, cs);
+ * values(dataMulti, cs);
  * //=> (123,'hello'),(456,'world!')
  *
  */

lib/helpers/table-name.js

@@ -89,8 +89,8 @@ class TableName {
  * $[Custom Type Formatting], based on $[Symbolic CTF], i.e. the actual method is available only via {@link external:Symbol Symbol}:
  *
  * ```js
- * const ctf = pgp.as.ctf; // Custom Type Formatting symbols namespace
- * const fullName = tn[ctf.toPostgres]; // tn = an object of type TableName
+ * const {toPostgres} = pgp.as.ctf; // Custom Type Formatting symbols namespace
+ * const fullName = tn[toPostgres]; // tn = an object of type TableName
  * ```
  *
  * This is a raw formatting type (`rawType = true`), i.e. when used as a query-formatting parameter, type `TableName`

lib/query-file.js

@@ -287,8 +287,8 @@ QueryFile.$query = file$query;
  * $[Custom Type Formatting], based on $[Symbolic CTF], i.e. the actual method is available only via {@link external:Symbol Symbol}:
  *
  * ```js
- * const ctf = pgp.as.ctf; // Custom Type Formatting symbols namespace
- * const query = qf[ctf.toPostgres](); // qf = an object of type QueryFile
+ * const {toPostgres} = pgp.as.ctf; // Custom Type Formatting symbols namespace
+ * const query = qf[toPostgres](); // qf = an object of type QueryFile
  * ```
  *
  * This is a raw formatting type (`rawType = true`), i.e. when used as a query-formatting parameter, type `QueryFile` injects SQL as raw text.

test/format.spec.js

@@ -1350,32 +1350,32 @@ describe('Custom Type Formatting', () => {
     });
 
     describe('for pre-defined ctf symbols', () => {
-        const ctf = pgp.as.ctf;
+        const {toPostgres, rawType} = pgp.as.ctf;
         it('must recognize symbolic ctf', () => {
-            expect(pgp.as.format('$1', {[ctf.toPostgres]: () => 'ok'})).toBe('\'ok\'');
+            expect(pgp.as.format('$1', {[toPostgres]: () => 'ok'})).toBe('\'ok\'');
         });
         it('must recognize symbolic ctf for simple types', () => {
             const value = 0;
-            Number.prototype[ctf.toPostgres] = () => 'ok';
+            Number.prototype[toPostgres] = () => 'ok';
             expect(pgp.as.format('$1', value)).toBe('\'ok\'');
-            delete Number.prototype[ctf.toPostgres];
+            delete Number.prototype[toPostgres];
         });
         it('must support symbolic rawType', () => {
-            expect(pgp.as.format('$1', {[ctf.toPostgres]: () => 'ok', [ctf.rawType]: true})).toBe('ok');
+            expect(pgp.as.format('$1', {[toPostgres]: () => 'ok', [rawType]: true})).toBe('ok');
         });
         it('must ignore explicit rawType for symbolic ctf', () => {
-            expect(pgp.as.format('$1', {[ctf.toPostgres]: () => 'ok', rawType: true})).toBe('\'ok\'');
+            expect(pgp.as.format('$1', {[toPostgres]: () => 'ok', rawType: true})).toBe('\'ok\'');
         });
         it('must ignore symbolic rawType for explicit ctf', () => {
-            expect(pgp.as.format('$1', {toPostgres: () => 'ok', [ctf.rawType]: true})).toBe('\'ok\'');
+            expect(pgp.as.format('$1', {toPostgres: () => 'ok', [rawType]: true})).toBe('\'ok\'');
         });
     });
 
     describe('for global ctf symbols', () => {
-        const ctf = pgp.as.ctf;
+        const {toPostgres, rawType} = pgp.as.ctf;
         it('must be equal the pre-defined symbols', () => {
-            expect(Symbol.for('ctf.toPostgres')).toBe(ctf.toPostgres);
-            expect(Symbol.for('ctf.rawType')).toBe(ctf.rawType);
+            expect(Symbol.for('ctf.toPostgres')).toBe(toPostgres);
+            expect(Symbol.for('ctf.rawType')).toBe(rawType);
         });
     });