pg-promise 11.7.7 → 11.8.0

package/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

package/lib/helpers/column-set.js

@@ -43,7 +43,7 @@ const npm = {
  *
  * @param {object} [options]
  *
- * @param {helpers.TableName|string|{table,schema}} [options.table]
+ * @param {helpers.TableName|Table|string} [options.table]
  * Table details.
  *
  * When it is a non-null value, and not a {@link helpers.TableName TableName} object, a new {@link helpers.TableName TableName} is constructed from the value.
@@ -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'}
  *     {
@@ -386,14 +387,14 @@ ColumnSet.prototype.assign = function (options) {
  *
  * @example
  *
- * const cs = new pgp.helpers.ColumnSet(['id', 'city', 'street']);
+ * const cs = new ColumnSet(['id', 'city', 'street']);
  *
  * cs.assignColumns({from: 'EXCLUDED', skip: 'id'})
  * //=> "city"=EXCLUDED."city","street"=EXCLUDED."street"
  *
  * @example
  *
- * const cs = new pgp.helpers.ColumnSet(['?id', 'city', 'street']);
+ * const cs = new ColumnSet(['?id', 'city', 'street']);
  *
  * cs.assignColumns({from: 'source', to: 'target', skip: c => c.cnd})
  * //=> target."city"=source."city",target."street"=source."street"
@@ -495,8 +496,9 @@ ColumnSet.prototype.extend = function (columns) {
  * @example
  *
  * const pgp = require('pg-promise')();
+ * const {ColumnSet} = pgp.helpers;
  *
- * const cs = new pgp.helpers.ColumnSet(['?one', 'two:json'], {table: 'my-table'});
+ * const cs = new ColumnSet(['?one', 'two:json'], {table: 'my-table'});
  * console.log(cs);
  * //=>
  * // ColumnSet {

package/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',
      *     {

package/lib/helpers/methods/insert.js

@@ -42,7 +42,7 @@ const npm = {
  * When the final {@link helpers.ColumnSet ColumnSet} is empty (no columns in it), the method will throw
  * {@link external:Error Error} = `Cannot generate an INSERT without any columns.`
  *
- * @param {helpers.TableName|string|{table,schema}} [table]
+ * @param {helpers.TableName|Table|string} [table]
  * Destination table.
  *
  * It is normally a required parameter. But when `columns` is passed in as a {@link helpers.ColumnSet ColumnSet} object
@@ -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!')
  *
  */

package/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'
  *
  */

package/lib/helpers/methods/update.js

@@ -46,7 +46,7 @@ const npm = {
  * When the final {@link helpers.ColumnSet ColumnSet} is empty (no columns in it), the method will throw
  * {@link external:Error Error} = `Cannot generate an UPDATE without any columns.`, unless option `emptyUpdate` was specified.
  *
- * @param {helpers.TableName|string|{table,schema}} [table]
+ * @param {helpers.TableName|Table|string} [table]
  * Table to be updated.
  *
  * It is normally a required parameter. But when `columns` is passed in as a {@link helpers.ColumnSet ColumnSet} object
@@ -87,6 +87,7 @@ 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!'}];
@@ -94,7 +95,7 @@ const npm = {
  * // 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,7 +105,7 @@ 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
@@ -112,17 +113,18 @@ const npm = {
  * // 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
  *
@@ -130,16 +132,17 @@ const npm = {
  *
  * // 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.

package/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!')
  *
  */

package/lib/helpers/table-name.js

@@ -26,11 +26,11 @@ const npm = {
  *
  * Filter `:alias` is an alternative approach to splitting an SQL name into multiple ones.
  *
- * @param {string|object} table
+ * @param {string|Table} table
  * Table name details, depending on the type:
  *
  * - table name, if `table` is a string
- * - object `{table, [schema]}`
+ * - {@link Table} object
  *
  * @property {string} name
  * Formatted/escaped full table name, combining `schema` + `table`.
@@ -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`
@@ -127,13 +127,21 @@ npm.utils.addInspection(TableName, function () {
 });
 
 /**
- *
  * @interface Table
  * @description
  * Structure for any table name/path.
  *
+ * Function {@link helpers._TN _TN} can help you construct it from a string.
+ *
  * @property {string} [schema] - schema name, if specified
  * @property {string} table - table name
+ *
+ * @see {@link helpers.TableName TableName}, {@link helpers._TN _TN}
+ */
+
+/**
+ * @external TemplateStringsArray
+ * @see https://microsoft.github.io/PowerBI-JavaScript/interfaces/_node_modules_typedoc_node_modules_typescript_lib_lib_es5_d_.templatestringsarray.html
  */
 
 /**
@@ -142,6 +150,9 @@ npm.utils.addInspection(TableName, function () {
  * Table-Name helper function, to convert any `"schema.table"` string
  * into `{schema, table}` object. It also works as a template-tag function.
  *
+ * @param {string|TemplateStringsArray} path
+ * Table-name path, as a simple string or a template string (with parameters).
+ *
  * @example
  * const {ColumnSet, _TN} = pgp.helpers;
  *
@@ -153,12 +164,14 @@ npm.utils.addInspection(TableName, function () {
  * const cs2 = new ColumnSet(['id', 'name'], {table: _TN`${schema}.table`});
  *
  * @returns {Table}
+ *
+ * @see {@link helpers.TableName TableName}, {@link external:TemplateStringsArray TemplateStringsArray}
  */
-function _TN(a, ...args) {
-    if (Array.isArray(a) && a.raw) {
-        a = a.map((b, i) => b + (i < args.length ? args[i] ?? '' : '')).join('');
-    } // else 'a' is a string
-    const [schema, table] = a.split('.');
+function _TN(path, ...args) {
+    if (Array.isArray(path)) {
+        path = path.reduce((a, c, i) => a + c + (args[i] ?? ''), '');
+    } // else 'path' is a string
+    const [schema, table] = path.split('.');
     if (table === undefined) {
         return {table: schema};
     }

package/lib/main.js

@@ -36,7 +36,7 @@ let originalClientConnect;
  * @module pg-promise
  *
  * @description
- * ## pg-promise v11.7
+ * ## pg-promise v11.8
  * All documentation here is for the latest official release only.
  *
  * ### Initialization Options

package/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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pg-promise",
-  "version": "11.7.7",
+  "version": "11.8.0",
   "description": "PostgreSQL interface for Node.js",
   "main": "lib/index.js",
   "typings": "typescript/pg-promise.d.ts",
@@ -47,12 +47,12 @@
     "spex": "3.3.0"
   },
   "devDependencies": {
-    "@eslint/js": "9.3.0",
-    "@types/node": "20.12.12",
+    "@eslint/js": "9.4.0",
+    "@types/node": "20.13.0",
     "bluebird": "3.7.2",
     "coveralls": "3.1.1",
     "cspell": "8.8.3",
-    "eslint": "9.3.0",
+    "eslint": "9.4.0",
     "globals": "15.3.0",
     "istanbul": "0.4.5",
     "jasmine-node": "3.0.0",

package/typescript/pg-promise.d.ts

@@ -349,6 +349,16 @@ declare namespace pgPromise {
         readonly ctx: ITaskContext
     }
 
+    interface ITaskIfOptions<Ext = {}> {
+        cnd?: boolean | ((t: ITask<Ext> & Ext) => boolean)
+        tag?: any
+    }
+
+    interface ITxIfOptions<Ext = {}> extends ITaskIfOptions<Ext> {
+        mode?: _txMode.TransactionMode | null
+        reusable?: boolean | ((t: ITask<Ext> & Ext) => boolean)
+    }
+
     // Base database protocol
     // API: https://vitaly-t.github.io/pg-promise/Database.html
     interface IBaseProtocol<Ext> {
@@ -405,46 +415,38 @@ declare namespace pgPromise {
 
         // Tasks;
         // API: https://vitaly-t.github.io/pg-promise/Database.html#task
-        task<T = any>(cb: (t: ITask<Ext> & Ext) => T | XPromise<T>): XPromise<T>
+        task<T>(cb: (t: ITask<Ext> & Ext) => T | XPromise<T>): XPromise<T>
 
-        task<T = any>(tag: string | number, cb: (t: ITask<Ext> & Ext) => T | XPromise<T>): XPromise<T>
+        task<T>(tag: string | number, cb: (t: ITask<Ext> & Ext) => T | XPromise<T>): XPromise<T>
 
-        task<T = any>(options: { tag?: any }, cb: (t: ITask<Ext> & Ext) => T | XPromise<T>): XPromise<T>
+        task<T>(options: { tag?: any }, cb: (t: ITask<Ext> & Ext) => T | XPromise<T>): XPromise<T>
 
         // Conditional Tasks;
         // API: https://vitaly-t.github.io/pg-promise/Database.html#taskIf
-        taskIf<T = any>(cb: (t: ITask<Ext> & Ext) => T | XPromise<T>): XPromise<T>
+        taskIf<T>(cb: (t: ITask<Ext> & Ext) => T | XPromise<T>): XPromise<T>
 
-        taskIf<T = any>(tag: string | number, cb: (t: ITask<Ext> & Ext) => T | XPromise<T>): XPromise<T>
+        taskIf<T>(tag: string | number, cb: (t: ITask<Ext> & Ext) => T | XPromise<T>): XPromise<T>
 
-        taskIf<T = any>(options: {
-            tag?: any,
-            cnd?: boolean | ((t: ITask<Ext> & Ext) => boolean)
-        }, cb: (t: ITask<Ext> & Ext) => T | XPromise<T>): XPromise<T>
+        taskIf<T>(options: ITaskIfOptions<Ext>, cb: (t: ITask<Ext> & Ext) => T | XPromise<T>): XPromise<T>
 
         // Transactions;
         // API: https://vitaly-t.github.io/pg-promise/Database.html#tx
-        tx<T = any>(cb: (t: ITask<Ext> & Ext) => T | XPromise<T>): XPromise<T>
+        tx<T>(cb: (t: ITask<Ext> & Ext) => T | XPromise<T>): XPromise<T>
 
-        tx<T = any>(tag: string | number, cb: (t: ITask<Ext> & Ext) => T | XPromise<T>): XPromise<T>
+        tx<T>(tag: string | number, cb: (t: ITask<Ext> & Ext) => T | XPromise<T>): XPromise<T>
 
-        tx<T = any>(options: {
+        tx<T>(options: {
             tag?: any,
             mode?: _txMode.TransactionMode | null
         }, cb: (t: ITask<Ext> & Ext) => T | XPromise<T>): XPromise<T>
 
         // Conditional Transactions;
         // API: https://vitaly-t.github.io/pg-promise/Database.html#txIf
-        txIf<T = any>(cb: (t: ITask<Ext> & Ext) => T | XPromise<T>): XPromise<T>
+        txIf<T>(cb: (t: ITask<Ext> & Ext) => T | XPromise<T>): XPromise<T>
 
-        txIf<T = any>(tag: string | number, cb: (t: ITask<Ext> & Ext) => T | XPromise<T>): XPromise<T>
+        txIf<T>(tag: string | number, cb: (t: ITask<Ext> & Ext) => T | XPromise<T>): XPromise<T>
 
-        txIf<T = any>(options: {
-            tag?: any,
-            mode?: _txMode.TransactionMode | null,
-            reusable?: boolean | ((t: ITask<Ext> & Ext) => boolean),
-            cnd?: boolean | ((t: ITask<Ext> & Ext) => boolean)
-        }, cb: (t: ITask<Ext> & Ext) => T | XPromise<T>): XPromise<T>
+        txIf<T>(options: ITxIfOptions<Ext>, cb: (t: ITask<Ext> & Ext) => T | XPromise<T>): XPromise<T>
     }
 
     // Database object in connected state;
@@ -708,8 +710,9 @@ declare namespace pgPromise {
         ColumnSet: typeof ColumnSet
         TableName: typeof TableName
 
-        _TN(data: TemplateStringsArray, ...args: Array<any>): ITable
-        _TN(s: string) :ITable
+        _TN(path: TemplateStringsArray, ...args: Array<any>): ITable
+
+        _TN(path: string): ITable
     }
 
     interface IGenericPromise {