@depup/pg-promise 12.6.2-depup.0

package/lib/database.js

@@ -0,0 +1,1643 @@
+/*
+ * Copyright (c) 2015-present, Vitaly Tomilov
+ *
+ * See the LICENSE file at the top-level directory of this distribution
+ * for licensing information.
+ *
+ * Removal or modification of this copyright notice is prohibited.
+ */
+
+const {Events} = require('./events');
+const {assert} = require('./assert');
+const {resultQuery, multiResultQuery, streamQuery} = require('./special-query');
+const {ConnectionContext} = require('./context');
+const {DatabasePool} = require('./database-pool');
+const {queryResult} = require('./query-result');
+
+const npm = {
+    utils: require('./utils'),
+    pubUtils: require('./utils/public'),
+    connect: require('./connect'),
+    query: require('./query').query,
+    task: require('./task'),
+    text: require('./text')
+};
+
+/**
+ * @class Database
+ * @description
+ *
+ * Represents the database protocol, extensible via event {@link event:extend extend}.
+ * This type is not available directly, it can only be created via the library's base call.
+ *
+ * **IMPORTANT:**
+ *
+ * For any given connection, you should only create a single {@link Database} object in a separate module,
+ * to be shared in your application (see the code example below). If instead you keep creating the {@link Database}
+ * object dynamically, your application will suffer from loss in performance, and will be getting a warning in a
+ * development environment (when `NODE_ENV` = `development`):
+ *
+ * `WARNING: Creating a duplicate database object for the same connection.`
+ *
+ * If you ever see this warning, rectify your {@link Database} object initialization, so there is only one object
+ * per connection details. See the example provided below.
+ *
+ * See also: property `noWarnings` in {@link module:pg-promise Initialization Options}.
+ *
+ * Note however, that in special cases you may need to re-create the database object, if its connection pool has been
+ * shut-down externally. And in this case the library won't be showing any warning.
+ *
+ * @param {string|object} cn
+ * Database connection details, which can be:
+ *
+ * - a configuration object
+ * - a connection string
+ *
+ * For details see {@link https://github.com/vitaly-t/pg-promise/wiki/Connection-Syntax Connection Syntax}.
+ *
+ * The value can be accessed from the database object via property {@link Database.$cn $cn}.
+ *
+ * @param {*} [dc]
+ * Database Context.
+ *
+ * Any object or value to be propagated through the protocol, to allow implementations and event handling
+ * that depend on the database context.
+ *
+ * This is mainly to facilitate the use of multiple databases which may need separate protocol extensions,
+ * or different implementations within a single task / transaction callback, depending on the database context.
+ *
+ * This parameter also adds uniqueness to the connection context that's used in combination with the connection
+ * parameters, i.e. use of unique database context will prevent getting the warning about creating a duplicate
+ * Database object.
+ *
+ * The value can be accessed from the database object via property {@link Database#$dc $dc}.
+ *
+ * @returns {Database}
+ *
+ * @see
+ *
+ * {@link Database#query query},
+ * {@link Database#none none},
+ * {@link Database#one one},
+ * {@link Database#oneOrNone oneOrNone},
+ * {@link Database#many many},
+ * {@link Database#manyOrNone manyOrNone},
+ * {@link Database#any any},
+ * {@link Database#func func},
+ * {@link Database#proc proc},
+ * {@link Database#result result},
+ * {@link Database#multiResult multiResult},
+ * {@link Database#multi multi},
+ * {@link Database#map map},
+ * {@link Database#each each},
+ * {@link Database#stream stream},
+ * {@link Database#task task},
+ * {@link Database#taskIf taskIf},
+ * {@link Database#tx tx},
+ * {@link Database#txIf txIf},
+ * {@link Database#connect connect},
+ * {@link Database#$config $config},
+ * {@link Database#$cn $cn},
+ * {@link Database#$dc $dc},
+ * {@link Database#$pool $pool},
+ * {@link event:extend extend}
+ *
+ * @example
+ * // Proper way to initialize and share the Database object
+ *
+ * // Loading and initializing the library:
+ * const pgp = require('pg-promise')({
+ *     // Initialization Options
+ * });
+ *
+ * // Preparing the connection details:
+ * const cn = 'postgres://username:password@host:port/database';
+ *
+ * // Creating a new database instance from the connection details:
+ * const db = pgp(cn);
+ *
+ * // Exporting the database object for shared use:
+ * module.exports = db;
+ */
+function Database(cn, dc, config) {
+
+    const dbThis = this,
+        poolConnection = typeof cn === 'string' ? {connectionString: cn} : cn,
+        pool = new config.pgp.pg.Pool(poolConnection),
+        endMethod = pool.end;
+
+    let destroyed;
+
+    pool.end = cb => {
+        const res = endMethod.call(pool, cb);
+        dbThis.$destroy();
+        return res;
+    };
+
+    pool.on('error', onError);
+
+    /**
+     * @method Database#connect
+     *
+     * @description
+     * Acquires a new or existing connection, depending on the current state of the connection pool, and parameter `direct`.
+     *
+     * This method creates a shared connection for executing a chain of queries against it. The connection must be released
+     * in the end of the chain by calling `done()` on the connection object.
+     *
+     * Method `done` takes one optional parameter - boolean `kill` flag, to signal the connection pool that you want it to kill
+     * the physical connection. This flag is ignored for direct connections, as they always close when released.
+     *
+     * It should not be used just for chaining queries on the same connection, methods {@link Database#task task} and
+     * {@link Database#tx tx} (for transactions) are to be used for that. This method is primarily for special cases, like
+     * `LISTEN` notifications.
+     *
+     * **NOTE:** Even though this method exposes a {@link external:Client Client} object via property `client`,
+     * you cannot call `client.end()` directly, or it will print an error into the console:
+     * `Abnormal client.end() call, due to invalid code or failed server connection.`
+     * You should only call method `done()` to release the connection.
+     *
+     * @param {object} [options]
+     * Connection Options.
+     *
+     * @param {boolean} [options.direct=false]
+     * Creates a new connection directly, as a stand-alone {@link external:Client Client} object, bypassing the connection pool.
+     *
+     * By default, all connections are acquired from the connection pool. But if you set this option, the library will instead
+     * create a new {@link external:Client Client} object directly (separately from the pool), and then call its `connect` method.
+     *
+     * Note that specifically for direct connections, method `done` returns a {@link external:Promise Promise}, because those connections
+     * are closed physically, which may take time.
+     *
+     * **WARNING:**
+     *
+     * Do not use this option for regular query execution, because it exclusively occupies one physical channel, and it cannot scale.
+     * This option is only suitable for global connection usage, such as event listeners.
+     *
+     * @param {function} [options.onLost]
+     * Notification callback of the lost/broken connection, called with the following parameters:
+     *  - `err` - the original connectivity error
+     *  - `e` - error context object, which contains:
+     *    - `cn` - safe connection string/config (with the password hashed);
+     *    - `dc` - Database Context, as was used during {@link Database} construction;
+     *    - `start` - Date/Time (`Date` type) when the connection was established;
+     *    - `client` - {@link external:Client Client} object that has lost the connection.
+     *
+     * The notification is mostly valuable with `direct: true`, to be able to re-connect direct/permanent connections by calling
+     * method {@link Database#connect connect} again.
+     *
+     * You do not need to call `done` on lost connections, as it happens automatically. However, if you had event listeners
+     * set up on the connection's `client` object, you should remove them to avoid leaks:
+     *
+     * ```js
+     * function onLostConnection(err, e) {
+     *     e.client.removeListener('my-event', myHandler);
+     * }
+     * ```
+     *
+     * For a complete example see $[Robust Listeners].
+     *
+     * @returns {external:Promise}
+     * A promise object that represents the connection result:
+     *  - resolves with the complete {@link Database} protocol, extended with:
+     *    - property `client` of type {@link external:Client Client} that represents the open connection
+     *    - method `done` that must be called in the end, in order to release the connection (returns a {@link external:Promise Promise}
+     *      in case of direct connections)
+     *    - methods `batch`, `page` and `sequence`, same as inside a {@link Task}
+     *  - rejects with a connection-related error when it fails to connect.
+     *
+     * @see
+     * {@link Database#task Database.task},
+     * {@link Database#taskIf Database.taskIf},
+     * {@link Database#tx Database.tx},
+     * {@link Database#txIf Database.txIf}
+     *
+     * @example
+     *
+     * let sco; // shared connection object;
+     *
+     * db.connect()
+     *     .then(obj => {
+     *         // obj.client = new connected Client object;
+     *
+     *         sco = obj; // save the connection object;
+     *
+     *         // execute all the queries you need:
+     *         return sco.any('SELECT * FROM Users');
+     *     })
+     *     .then(data => {
+     *         // success
+     *     })
+     *     .catch(error => {
+     *         // error
+     *     })
+     *     .finally(() => {
+     *         // release the connection, if it was successful:
+     *         if (sco) {
+     *             // if you pass `true` into method done, i.e. done(true),
+     *             // it will make the pool kill the physical connection.
+     *             sco.done();
+     *         }
+     *     });
+     *
+     */
+    this.connect = function (options) {
+        options = options || {};
+        const ctx = createContext();
+        ctx.cnOptions = options;
+        const self = {
+            query(query, values, qrm) {
+                if (!ctx.db) {
+                    return Promise.reject(new Error(npm.text.queryDisconnected));
+                }
+                return config.$npm.query.call(this, ctx, query, values, qrm);
+            },
+            done(kill) {
+                if (!ctx.db) {
+                    throw new Error(npm.text.looseQuery);
+                }
+                return ctx.disconnect(kill);
+            },
+            batch(values, opt) {
+                return config.$npm.spex.batch.call(this, values, opt);
+            },
+            page(source, opt) {
+                return config.$npm.spex.page.call(this, source, opt);
+            },
+            sequence(source, opt) {
+                return config.$npm.spex.sequence.call(this, source, opt);
+            }
+        };
+        const connection = options.direct ? config.$npm.connect.direct(ctx) : config.$npm.connect.pool(ctx, dbThis);
+        return connection
+            .then(db => {
+                ctx.connect(db);
+                self.client = db.client;
+                extend(ctx, self);
+                return self;
+            });
+    };
+
+    /**
+     * @method Database#query
+     *
+     * @description
+     * Base query method that executes a generic query, expecting the return data according to parameter `qrm`.
+     *
+     * It performs the following steps:
+     *
+     *  1. Validates and formats the query via {@link formatting.format as.format}, according to the `query` and `values` passed in;
+     *  2. For a root-level query (against the {@link Database} object), it requests a new connection from the pool;
+     *  3. Executes the query;
+     *  4. For a root-level query (against the {@link Database} object), it releases the connection back to the pool;
+     *  5. Resolves/rejects, according to the data returned from the query and the value of `qrm`.
+     *
+     * Direct use of this method is not suitable for chaining queries, for performance reasons. It should be done
+     * through either task or transaction context, see $[Chaining Queries].
+     *
+     * When receiving a multi-query result, only the last result is processed, ignoring the rest.
+     *
+     * @param {string|function|object} query
+     * Query to be executed, which can be any of the following types:
+     * - A non-empty query string
+     * - A function that returns a query string or another function, i.e. recursive resolution
+     *   is supported, passing in `values` as `this`, and as the first parameter.
+     * - Prepared Statement `{name, text, values, ...}` or {@link PreparedStatement} object
+     * - Parameterized Query `{text, values, ...}` or {@link ParameterizedQuery} object
+     * - {@link QueryFile} object
+     *
+     * @param {array|value|function} [values]
+     * Query formatting parameter(s), or a function that returns it.
+     *
+     * When `query` is of type `string` or a {@link QueryFile} object, the `values` can be:
+     * - a single value - to replace all `$1` occurrences
+     * - an array of values - to replace all `$1`, `$2`, ... variables
+     * - an object - to apply $[Named Parameters] formatting
+     *
+     * When `query` is a Prepared Statement or a Parameterized Query (or their class types),
+     * and `values` is not `null` or `undefined`, it is automatically set within such object,
+     * as an override for its internal `values`.
+     *
+     * @param {queryResult} [qrm=queryResult.any]
+     * {@link queryResult Query Result Mask}
+     *
+     * @returns {external:Promise}
+     * A promise object that represents the query result according to `qrm`.
+     */
+    this.query = function (query, values, qrm) {
+        const self = this, ctx = createContext();
+        return config.$npm.connect.pool(ctx, dbThis)
+            .then(db => {
+                ctx.connect(db);
+                return config.$npm.query.call(self, ctx, query, values, qrm);
+            })
+            .then(data => {
+                ctx.disconnect();
+                return data;
+            })
+            .catch(error => {
+                ctx.disconnect();
+                return Promise.reject(error);
+            });
+    };
+
+    /**
+     * @member {object} Database#$config
+     * @readonly
+     * @description
+     * This is a hidden property, to help integrating type {@link Database} directly with third-party libraries.
+     *
+     * Properties available in the object:
+     * - `pgp` - instance of the entire library after initialization
+     * - `options` - the library's {@link module:pg-promise Initialization Options} object
+     * - `version` - this library's version
+     * - `$npm` _(hidden property)_ - internal module cache
+     */
+    npm.utils.addReadProp(this, '$config', config, true);
+
+    /**
+     * @member {string|object} Database#$cn
+     * @readonly
+     * @description
+     * Database connection, as was passed in during the object's construction.
+     *
+     * This is a hidden property, to help integrating type {@link Database} directly with third-party libraries.
+     *
+     * @see Database
+     */
+    npm.utils.addReadProp(this, '$cn', cn, true);
+
+    /**
+     * @member {*} Database#$dc
+     * @readonly
+     * @description
+     * Database Context, as was passed in during the object's construction.
+     *
+     * This is a hidden property, to help integrating type {@link Database} directly with third-party libraries.
+     *
+     * @see Database
+     */
+    npm.utils.addReadProp(this, '$dc', dc, true);
+
+    /**
+     * @member {external:pg-pool} Database#$pool
+     * @readonly
+     * @description
+     * A $[pg-pool] object associated with the database object, as each {@link Database} creates its own $[pg-pool] instance.
+     *
+     * This is a hidden property, primarily for integrating type {@link Database} with third-party libraries that support
+     * $[pg-pool] directly. Note however, that if you pass the pool object into a library that calls `pool.end()`, you will no longer be able
+     * to use this {@link Database} object, and each query method will be rejecting with {@link external:Error Error} =
+     * `Connection pool of the database object has been destroyed.`
+     *
+     * You can also use this object to shut down the pool, by calling `$pool.end()`.
+     *
+     * For more details see $[Library de-initialization].
+     *
+     * @see
+     * {@link Database}
+     * {@link module:pg-promise~end pgp.end}
+     *
+     * @example
+     *
+     * // Shutting down the connection pool of this database object,
+     * // after all queries have finished in a run-though process:
+     *
+     * .then(() => {}) // processing the data
+     * .catch() => {}) // handling the error
+     * .finally(db.$pool.end); // shutting down the pool
+     *
+     */
+    npm.utils.addReadProp(this, '$pool', pool, true);
+
+    /**
+     * @member {function} Database.$destroy
+     * @readonly
+     * @private
+     * @description
+     * Permanently shuts down the database object.
+     */
+    npm.utils.addReadProp(this, '$destroy', () => {
+        if (!destroyed) {
+            if (!pool.ending) {
+                endMethod.call(pool);
+            }
+            DatabasePool.unregister(dbThis);
+            pool.removeListener('error', onError);
+            destroyed = true;
+        }
+    }, true);
+
+    DatabasePool.register(this);
+
+    extend(createContext(), this); // extending root protocol;
+
+    function createContext() {
+        return new ConnectionContext({cn, dc, options: config.options});
+    }
+
+    // Optional value-transformation helper:
+    function transform(value, cb, thisArg) {
+        return typeof cb === 'function' ? value.then(data => cb.call(thisArg, data)) : value;
+    }
+
+    ////////////////////////////////////////////////////
+    // Injects additional methods into an access object,
+    // extending the protocol's base method 'query'.
+    function extend(ctx, obj) {
+
+        /**
+         * @method Database#none
+         * @description
+         * Executes a query that expects no data to be returned. If the query returns any data,
+         * the method rejects.
+         *
+         * When receiving a multi-query result, only the last result is processed, ignoring the rest.
+         *
+         * @param {string|function|object} query
+         * Query to be executed, which can be any of the following types:
+         * - A non-empty query string
+         * - A function that returns a query string or another function, i.e. recursive resolution
+         *   is supported, passing in `values` as `this`, and as the first parameter.
+         * - Prepared Statement `{name, text, values, ...}` or {@link PreparedStatement} object
+         * - Parameterized Query `{text, values, ...}` or {@link ParameterizedQuery} object
+         * - {@link QueryFile} object
+         *
+         * @param {array|value|function} [values]
+         * Query formatting parameter(s), or a function that returns it.
+         *
+         * When `query` is of type `string` or a {@link QueryFile} object, the `values` can be:
+         * - a single value - to replace all `$1` occurrences
+         * - an array of values - to replace all `$1`, `$2`, ... variables
+         * - an object - to apply $[Named Parameters] formatting
+         *
+         * When `query` is a Prepared Statement or a Parameterized Query (or their class types),
+         * and `values` is not `null` or `undefined`, it is automatically set within such object,
+         * as an override for its internal `values`.
+         *
+         * @returns {external:Promise<null>}
+         * A promise object that represents the query result:
+         * - When no records are returned, it resolves with `null`.
+         * - When any data is returned, it rejects with {@link errors.QueryResultError QueryResultError}:
+         *   - `.message` = `No return data was expected.`
+         *   - `.code` = {@link errors.queryResultErrorCode.notEmpty queryResultErrorCode.notEmpty}
+         */
+        obj.none = function (query, values) {
+            return obj.query.call(this, query, values, queryResult.none);
+        };
+
+        /**
+         * @method Database#one
+         * @description
+         * Executes a query that expects exactly 1 row to be returned. When 0 or more than 1 rows are returned,
+         * the method rejects.
+         *
+         * When receiving a multi-query result, only the last result is processed, ignoring the rest.
+         *
+         * @param {string|function|object} query
+         * Query to be executed, which can be any of the following types:
+         * - A non-empty query string
+         * - A function that returns a query string or another function, i.e. recursive resolution
+         *   is supported, passing in `values` as `this`, and as the first parameter.
+         * - Prepared Statement `{name, text, values, ...}` or {@link PreparedStatement} object
+         * - Parameterized Query `{text, values, ...}` or {@link ParameterizedQuery} object
+         * - {@link QueryFile} object
+         *
+         * @param {array|value|function} [values]
+         * Query formatting parameter(s), or a function that returns it.
+         *
+         * When `query` is of type `string` or a {@link QueryFile} object, the `values` can be:
+         * - a single value - to replace all `$1` occurrences
+         * - an array of values - to replace all `$1`, `$2`, ... variables
+         * - an object - to apply $[Named Parameters] formatting
+         *
+         * When `query` is a Prepared Statement or a Parameterized Query (or their class types),
+         * and `values` is not `null` or `undefined`, it is automatically set within such object,
+         * as an override for its internal `values`.
+         *
+         * @param {function} [cb]
+         * Value-transformation callback, to allow in-line value change.
+         * When specified, the returned value replaces the original one.
+         *
+         * The function takes only one parameter - value resolved from the query.
+         *
+         * @param {*} [thisArg]
+         * Value to use as `this` when executing the transformation callback.
+         *
+         * @returns {external:Promise}
+         * A promise object that represents the query result:
+         * - When 1 row is returned, it resolves with that row as a single object.
+         * - When no rows are returned, it rejects with {@link errors.QueryResultError QueryResultError}:
+         *   - `.message` = `No data returned from the query.`
+         *   - `.code` = {@link errors.queryResultErrorCode.noData queryResultErrorCode.noData}
+         * - When multiple rows are returned, it rejects with {@link errors.QueryResultError QueryResultError}:
+         *   - `.message` = `Multiple rows were not expected.`
+         *   - `.code` = {@link errors.queryResultErrorCode.multiple queryResultErrorCode.multiple}
+         * - Resolves with the new value, if transformation callback `cb` was specified.
+         *
+         * @see
+         * {@link Database#oneOrNone oneOrNone}
+         *
+         * @example
+         *
+         * // a query with in-line value transformation:
+         * db.one('INSERT INTO Events VALUES($1) RETURNING id', [123], event => event.id)
+         *     .then(data => {
+         *         // data = a new event id, rather than an object with it
+         *     });
+         *
+         * @example
+         *
+         * // a query with in-line value transformation + conversion:
+         * db.one('SELECT count(*) FROM Users', [], c => +c.count)
+         *     .then(count => {
+         *         // count = a proper integer value, rather than an object with a string
+         *     });
+         *
+         */
+        obj.one = function (query, values, cb, thisArg) {
+            const v = obj.query.call(this, query, values, queryResult.one);
+            return transform(v, cb, thisArg);
+        };
+
+        /**
+         * @method Database#many
+         * @description
+         * Executes a query that expects one or more rows to be returned. When the query returns no rows, the method rejects.
+         *
+         * When receiving a multi-query result, only the last result is processed, ignoring the rest.
+         *
+         * @param {string|function|object} query
+         * Query to be executed, which can be any of the following types:
+         * - A non-empty query string
+         * - A function that returns a query string or another function, i.e. recursive resolution
+         *   is supported, passing in `values` as `this`, and as the first parameter.
+         * - Prepared Statement `{name, text, values, ...}` or {@link PreparedStatement} object
+         * - Parameterized Query `{text, values, ...}` or {@link ParameterizedQuery} object
+         * - {@link QueryFile} object
+         *
+         * @param {array|value|function} [values]
+         * Query formatting parameter(s), or a function that returns it.
+         *
+         * When `query` is of type `string` or a {@link QueryFile} object, the `values` can be:
+         * - a single value - to replace all `$1` occurrences
+         * - an array of values - to replace all `$1`, `$2`, ... variables
+         * - an object - to apply $[Named Parameters] formatting
+         *
+         * When `query` is a Prepared Statement or a Parameterized Query (or their class types),
+         * and `values` is not `null` or `undefined`, it is automatically set within such object,
+         * as an override for its internal `values`.
+         *
+         * @returns {external:Promise}
+         * A promise object that represents the query result:
+         * - When 1 or more rows are returned, it resolves with the array of rows.
+         * - When no rows are returned, it rejects with {@link errors.QueryResultError QueryResultError}:
+         *   - `.message` = `No data returned from the query.`
+         *   - `.code` = {@link errors.queryResultErrorCode.noData queryResultErrorCode.noData}
+         */
+        obj.many = function (query, values) {
+            return obj.query.call(this, query, values, queryResult.many);
+        };
+
+        /**
+         * @method Database#oneOrNone
+         * @description
+         * Executes a query that expects 0 or 1 rows to be returned. It resolves with the row-object when 1 row is returned,
+         * or with `null` when nothing is returned. When the query returns more than 1 row, the method rejects.
+         *
+         * When receiving a multi-query result, only the last result is processed, ignoring the rest.
+         *
+         * @param {string|function|object} query
+         * Query to be executed, which can be any of the following types:
+         * - A non-empty query string
+         * - A function that returns a query string or another function, i.e. recursive resolution
+         *   is supported, passing in `values` as `this`, and as the first parameter.
+         * - Prepared Statement `{name, text, values, ...}` or {@link PreparedStatement} object
+         * - Parameterized Query `{text, values, ...}` or {@link ParameterizedQuery} object
+         * - {@link QueryFile} object
+         *
+         * @param {array|value|function} [values]
+         * Query formatting parameter(s), or a function that returns it.
+         *
+         * When `query` is of type `string` or a {@link QueryFile} object, the `values` can be:
+         * - a single value - to replace all `$1` occurrences
+         * - an array of values - to replace all `$1`, `$2`, ... variables
+         * - an object - to apply $[Named Parameters] formatting
+         *
+         * When `query` is a Prepared Statement or a Parameterized Query (or their class types),
+         * and `values` is not `null` or `undefined`, it is automatically set within such object,
+         * as an override for its internal `values`.
+         *
+         * @param {function} [cb]
+         * Value-transformation callback, to allow in-line value change.
+         * When specified, the returned value replaces the original one.
+         *
+         * The function takes only one parameter - value resolved from the query.
+         *
+         * @param {*} [thisArg]
+         * Value to use as `this` when executing the transformation callback.
+         *
+         * @returns {external:Promise}
+         * A promise object that represents the query result:
+         * - When no rows are returned, it resolves with `null`.
+         * - When 1 row is returned, it resolves with that row as a single object.
+         * - When multiple rows are returned, it rejects with {@link errors.QueryResultError QueryResultError}:
+         *   - `.message` = `Multiple rows were not expected.`
+         *   - `.code` = {@link errors.queryResultErrorCode.multiple queryResultErrorCode.multiple}
+         * - Resolves with the new value, if transformation callback `cb` was specified.
+         *
+         * @see
+         * {@link Database#one one},
+         * {@link Database#none none},
+         * {@link Database#manyOrNone manyOrNone}
+         *
+         * @example
+         *
+         * // a query with in-line value transformation:
+         * db.oneOrNone('SELECT id FROM Events WHERE type = $1', ['entry'], e => e && e.id)
+         *     .then(data => {
+         *         // data = the event id or null (rather than object or null)
+         *     });
+         *
+         */
+        obj.oneOrNone = function (query, values, cb, thisArg) {
+            const v = obj.query.call(this, query, values, queryResult.one | queryResult.none);
+            return transform(v, cb, thisArg);
+        };
+
+        /**
+         * @method Database#manyOrNone
+         * @description
+         * Executes a query that can return any number of rows.
+         *
+         * When receiving a multi-query result, only the last result is processed, ignoring the rest.
+         *
+         * @param {string|function|object} query
+         * Query to be executed, which can be any of the following types:
+         * - A non-empty query string
+         * - A function that returns a query string or another function, i.e. recursive resolution
+         *   is supported, passing in `values` as `this`, and as the first parameter.
+         * - Prepared Statement `{name, text, values, ...}` or {@link PreparedStatement} object
+         * - Parameterized Query `{text, values, ...}` or {@link ParameterizedQuery} object
+         * - {@link QueryFile} object
+         *
+         * @param {array|value|function} [values]
+         * Query formatting parameter(s), or a function that returns it.
+         *
+         * When `query` is of type `string` or a {@link QueryFile} object, the `values` can be:
+         * - a single value - to replace all `$1` occurrences
+         * - an array of values - to replace all `$1`, `$2`, ... variables
+         * - an object - to apply $[Named Parameters] formatting
+         *
+         * When `query` is a Prepared Statement or a Parameterized Query (or their class types),
+         * and `values` is not `null` or `undefined`, it is automatically set within such object,
+         * as an override for its internal `values`.
+         *
+         * @returns {external:Promise<Array>}
+         * A promise object that represents the query result:
+         * - When no rows are returned, it resolves with an empty array.
+         * - When 1 or more rows are returned, it resolves with the array of rows.
+         *
+         * @see
+         * {@link Database#any any},
+         * {@link Database#many many},
+         * {@link Database#none none}
+         *
+         */
+        obj.manyOrNone = function (query, values) {
+            return obj.query.call(this, query, values, queryResult.many | queryResult.none);
+        };
+
+        /**
+         * @method Database#any
+         * @description
+         * Executes a query that can return any number of rows.
+         * This is simply a shorter alias for method {@link Database#manyOrNone manyOrNone}.
+         *
+         * When receiving a multi-query result, only the last result is processed, ignoring the rest.
+         *
+         * @param {string|function|object} query
+         * Query to be executed, which can be any of the following types:
+         * - A non-empty query string
+         * - A function that returns a query string or another function, i.e. recursive resolution
+         *   is supported, passing in `values` as `this`, and as the first parameter.
+         * - Prepared Statement `{name, text, values, ...}` or {@link PreparedStatement} object
+         * - Parameterized Query `{text, values, ...}` or {@link ParameterizedQuery} object
+         * - {@link QueryFile} object
+         *
+         * @param {array|value|function} [values]
+         * Query formatting parameter(s), or a function that returns it.
+         *
+         * When `query` is of type `string` or a {@link QueryFile} object, the `values` can be:
+         * - a single value - to replace all `$1` occurrences
+         * - an array of values - to replace all `$1`, `$2`, ... variables
+         * - an object - to apply $[Named Parameters] formatting
+         *
+         * When `query` is a Prepared Statement or a Parameterized Query (or their class types),
+         * and `values` is not `null` or `undefined`, it is automatically set within such object,
+         * as an override for its internal `values`.
+         *
+         * @returns {external:Promise<Array>}
+         * A promise object that represents the query result:
+         * - When no rows are returned, it resolves with an empty array.
+         * - When 1 or more rows are returned, it resolves with the array of rows.
+         *
+         * @see
+         * {@link Database#manyOrNone manyOrNone},
+         * {@link Database#map map},
+         * {@link Database#each each}
+         *
+         */
+        obj.any = function (query, values) {
+            return obj.query.call(this, query, values, queryResult.any);
+        };
+
+        /**
+         * @method Database#result
+         * @description
+         * Executes a query without any expectation for the return data, and resolves with the
+         * original $[Result] object when successful.
+         *
+         * When receiving a multi-query result, only the last result is processed, ignoring the rest.
+         *
+         * @param {string|function|object} query
+         * Query to be executed, which can be any of the following types:
+         * - A non-empty query string
+         * - A function that returns a query string or another function, i.e. recursive resolution
+         *   is supported, passing in `values` as `this`, and as the first parameter.
+         * - Prepared Statement `{name, text, values, ...}` or {@link PreparedStatement} object
+         * - Parameterized Query `{text, values, ...}` or {@link ParameterizedQuery} object
+         * - {@link QueryFile} object
+         *
+         * @param {array|value|function} [values]
+         * Query formatting parameter(s), or a function that returns it.
+         *
+         * When `query` is of type `string` or a {@link QueryFile} object, the `values` can be:
+         * - a single value - to replace all `$1` occurrences
+         * - an array of values - to replace all `$1`, `$2`, ... variables
+         * - an object - to apply $[Named Parameters] formatting
+         *
+         * When `query` is a Prepared Statement or a Parameterized Query (or their class types),
+         * and `values` is not `null` or `undefined`, it is automatically set within such object,
+         * as an override for its internal `values`.
+         *
+         * @param {function} [cb]
+         * Value-transformation callback, to allow in-line value change.
+         * When specified, the returned value replaces the original one.
+         *
+         * The function takes only one parameter - value resolved from the query.
+         *
+         * @param {*} [thisArg]
+         * Value to use as `this` when executing the transformation callback.
+         *
+         * @returns {external:Promise}
+         * A promise object that represents the query result:
+         * - resolves with the original $[Result] object (by default);
+         * - resolves with the new value, if transformation callback `cb` was specified.
+         *
+         * @example
+         *
+         * // use of value transformation:
+         * // deleting rows and returning the number of rows deleted
+         * db.result('DELETE FROM Events WHERE id = $1', [123], r => r.rowCount)
+         *     .then(data => {
+         *         // data = number of rows that were deleted
+         *     });
+         *
+         * @example
+         *
+         * // use of value transformation:
+         * // getting only column details from a table
+         * db.result('SELECT * FROM Users LIMIT 0', null, r => r.fields)
+         *     .then(data => {
+         *         // data = array of column descriptors
+         *     });
+         *
+         */
+        obj.result = function (query, values, cb, thisArg) {
+            const v = obj.query.call(this, query, values, resultQuery);
+            return transform(v, cb, thisArg);
+        };
+
+        /**
+         * @method Database#multiResult
+         * @description
+         * Executes a multi-query string, without any expectation for the return data, and resolves with an array
+         * of the original $[Result] objects when successful.
+         *
+         * The operation is atomic, i.e. all queries are executed in a single transaction, unless there are explicit
+         * `BEGIN/COMMIT` commands included in the query string to divide it into multiple transactions.
+         *
+         * @param {string|function|object} query
+         * Multi-query string to be executed, which can be any of the following types:
+         * - A non-empty string that can contain any number of queries
+         * - A function that returns a query string or another function, i.e. recursive resolution
+         *   is supported, passing in `values` as `this`, and as the first parameter.
+         * - Prepared Statement `{name, text, values, ...}` or {@link PreparedStatement} object
+         * - Parameterized Query `{text, values, ...}` or {@link ParameterizedQuery} object
+         * - {@link QueryFile} object
+         *
+         * @param {array|value|function} [values]
+         * Query formatting parameter(s), or a function that returns it.
+         *
+         * When `query` is of type `string` or a {@link QueryFile} object, the `values` can be:
+         * - a single value - to replace all `$1` occurrences
+         * - an array of values - to replace all `$1`, `$2`, ... variables
+         * - an object - to apply $[Named Parameters] formatting
+         *
+         * When `query` is a Prepared Statement or a Parameterized Query (or their class types),
+         * and `values` is not `null` or `undefined`, it is automatically set within such object,
+         * as an override for its internal `values`.
+         *
+         * @returns {external:Promise<external:Result[]>}
+         *
+         * @see {@link Database#multi multi}
+         *
+         */
+        obj.multiResult = function (query, values) {
+            return obj.query.call(this, query, values, multiResultQuery);
+        };
+
+        /**
+         * @method Database#multi
+         * @description
+         * Executes a multi-query string, without any expectation for the return data, and resolves with an array
+         * of arrays of rows when successful.
+         *
+         * The operation is atomic, i.e. all queries are executed in a single transaction, unless there are explicit
+         * `BEGIN/COMMIT` commands included in the query string to divide it into multiple transactions.
+         *
+         * @param {string|function|object} query
+         * Multi-query string to be executed, which can be any of the following types:
+         * - A non-empty string that can contain any number of queries
+         * - A function that returns a query string or another function, i.e. recursive resolution
+         *   is supported, passing in `values` as `this`, and as the first parameter.
+         * - Prepared Statement `{name, text, values, ...}` or {@link PreparedStatement} object
+         * - Parameterized Query `{text, values, ...}` or {@link ParameterizedQuery} object
+         * - {@link QueryFile} object
+         *
+         * @param {array|value|function} [values]
+         * Query formatting parameter(s), or a function that returns it.
+         *
+         * When `query` is of type `string` or a {@link QueryFile} object, the `values` can be:
+         * - a single value - to replace all `$1` occurrences
+         * - an array of values - to replace all `$1`, `$2`, ... variables
+         * - an object - to apply $[Named Parameters] formatting
+         *
+         * When `query` is a Prepared Statement or a Parameterized Query (or their class types),
+         * and `values` is not `null` or `undefined`, it is automatically set within such object,
+         * as an override for its internal `values`.
+         *
+         * @returns {external:Promise<Array<Array>>}
+         *
+         * @see {@link Database#multiResult multiResult}
+         *
+         * @example
+         *
+         * // Get data from 2 tables in a single request:
+         * const [users, products] = await db.multi('SELECT * FROM users;SELECT * FROM products');
+         *
+         */
+        obj.multi = function (query, values) {
+            return obj.query.call(this, query, values, multiResultQuery)
+                .then(data => data.map(a => a.rows));
+        };
+
+        /**
+         * @method Database#stream
+         * @description
+         * Custom data streaming, with the help of $[pg-query-stream].
+         *
+         * This method doesn't work with the $[Native Bindings], and if option `pgNative`
+         * is set, it will reject with `Streaming doesn't work with Native Bindings.`
+         *
+         * @param {QueryStream} qs
+         * Stream object of type $[QueryStream].
+         *
+         * @param {Database.streamInitCB} initCB
+         * Stream initialization callback.
+         *
+         * It is invoked with the same `this` context as the calling method.
+         *
+         * @returns {external:Promise}
+         * Result of the streaming operation.
+         *
+         * Once the streaming has finished successfully, the method resolves with
+         * `{processed, duration}`:
+         * - `processed` - total number of rows processed;
+         * - `duration` - streaming duration, in milliseconds.
+         *
+         * Possible rejections messages:
+         * - `Invalid or missing stream object.`
+         * - `Invalid stream state.`
+         * - `Invalid or missing stream initialization callback.`
+         */
+        obj.stream = function (qs, init) {
+            return obj.query.call(this, qs, init, streamQuery);
+        };
+
+        /**
+         * @method Database#func
+         * @description
+         * Executes a database function that returns a table, abbreviating the full syntax
+         * of `query('SELECT * FROM $1:alias($2:csv)', [funcName, values], qrm)`.
+         *
+         * @param {string} funcName
+         * Name of the function to be executed.
+         * When it is not same-case, or contains extended symbols, it is double-quoted, as per the `:alias` filter,
+         * which also supports `.`, to auto-split into a composite name.
+         *
+         * @param {array|value|function} [values]
+         * Parameters for the function - one value | array of values | function returning value(s).
+         *
+         * @param {queryResult} [qrm=queryResult.any] - {@link queryResult Query Result Mask}.
+         *
+         * @returns {external:Promise}
+         *
+         * A promise object as returned from method {@link Database#query query}, according to parameter `qrm`.
+         *
+         * @see
+         * {@link Database#query query},
+         * {@link Database#proc proc}
+         */
+        obj.func = function (funcName, values, qrm) {
+            return obj.query.call(this, {entity: funcName, type: 'func'}, values, qrm);
+        };
+
+        /**
+         * @method Database#proc
+         * @description
+         * Executes a stored procedure by name, abbreviating the full syntax of
+         * `oneOrNone('CALL $1:alias($2:csv)', [procName, values], cb, thisArg)`.
+         *
+         * **NOTE:** This method uses the new `CALL` syntax that requires PostgreSQL v11 or later.
+         *
+         * @param {string} procName
+         * Name of the stored procedure to be executed.
+         * When it is not same-case, or contains extended symbols, it is double-quoted, as per the `:alias` filter,
+         * which also supports `.`, to auto-split into a composite SQL name.
+         *
+         * @param {array|value|function} [values]
+         * Parameters for the procedure - one value | array of values | function returning value(s).
+         *
+         * @param {function} [cb]
+         * Value-transformation callback, to allow in-line value change.
+         * When specified, the returned value replaces the original one.
+         *
+         * The function takes only one parameter - value resolved from the query.
+         *
+         * @param {*} [thisArg]
+         * Value to use as `this` when executing the transformation callback.
+         *
+         * @returns {external:Promise}
+         * When the procedure takes output parameters, a single object is returned, with
+         * properties for the output values. Otherwise, the method resolves with `null`.
+         * And if the value-transformation callback is provided, it overrides the result.
+         *
+         * @see
+         * {@link Database#func func}
+         */
+        obj.proc = function (procName, values, cb, thisArg) {
+            const v = obj.query.call(this, {
+                entity: procName,
+                type: 'proc'
+            }, values, queryResult.one | queryResult.none);
+            return transform(v, cb, thisArg);
+        };
+
+        /**
+         * @method Database#map
+         * @description
+         * Creates a new array with the results of calling a provided function on every element in the array of rows
+         * resolved by method {@link Database#any any}.
+         *
+         * It is a convenience method, to reduce the following code:
+         *
+         * ```js
+         * db.any(query, values)
+         *     .then(data => {
+         *         return data.map((row, index, data) => {
+         *              // return a new element
+         *         });
+         *     });
+         * ```
+         *
+         * When receiving a multi-query result, only the last result is processed, ignoring the rest.
+         *
+         * @param {string|function|object} query
+         * Query to be executed, which can be any of the following types:
+         * - A non-empty query string
+         * - A function that returns a query string or another function, i.e. recursive resolution
+         *   is supported, passing in `values` as `this`, and as the first parameter.
+         * - Prepared Statement `{name, text, values, ...}` or {@link PreparedStatement} object
+         * - Parameterized Query `{text, values, ...}` or {@link ParameterizedQuery} object
+         * - {@link QueryFile} object
+         *
+         * @param {array|value|function} values
+         * Query formatting parameter(s), or a function that returns it.
+         *
+         * When `query` is of type `string` or a {@link QueryFile} object, the `values` can be:
+         * - a single value - to replace all `$1` occurrences
+         * - an array of values - to replace all `$1`, `$2`, ... variables
+         * - an object - to apply $[Named Parameters] formatting
+         *
+         * When `query` is a Prepared Statement or a Parameterized Query (or their class types),
+         * and `values` is not `null` or `undefined`, it is automatically set within such object,
+         * as an override for its internal `values`.
+         *
+         * @param {function} cb
+         * Function that produces an element of the new array, taking three arguments:
+         * - `row` - the current row object being processed in the array
+         * - `index` - the index of the current row being processed in the array
+         * - `data` - the original array of rows resolved by method {@link Database#any any}
+         *
+         * @param {*} [thisArg]
+         * Value to use as `this` when executing the callback.
+         *
+         * @returns {external:Promise<Array>}
+         * Resolves with the new array of values returned from the callback.
+         *
+         * @see
+         * {@link Database#any any},
+         * {@link Database#each each},
+         * {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/map Array.map}
+         *
+         * @example
+         *
+         * db.map('SELECT id FROM Users WHERE status = $1', ['active'], row => row.id)
+         *     .then(data => {
+         *         // data = array of active user id-s
+         *     })
+         *     .catch(error => {
+         *        // error
+         *     });
+         *
+         * @example
+         *
+         * db.tx(t => {
+         *     return t.map('SELECT id FROM Users WHERE status = $1', ['active'], row => {
+         *        return t.none('UPDATE Events SET checked = $1 WHERE userId = $2', [true, row.id]);
+         *     }).then(t.batch);
+         * })
+         *     .then(data => {
+         *         // success
+         *     })
+         *     .catch(error => {
+         *         // error
+         *     });
+         *
+         * @example
+         *
+         * // Build a list of active users, each with the list of user events:
+         * db.task(t => {
+         *     return t.map('SELECT id FROM Users WHERE status = $1', ['active'], user => {
+         *         return t.any('SELECT * FROM Events WHERE userId = $1', user.id)
+         *             .then(events=> {
+         *                 user.events = events;
+         *                 return user;
+         *             });
+         *     }).then(t.batch);
+         * })
+         *     .then(data => {
+         *         // success
+         *     })
+         *     .catch(error => {
+         *         // error
+         *     });
+         *
+         */
+        obj.map = function (query, values, cb, thisArg) {
+            return obj.any.call(this, query, values)
+                .then(data => data.map(cb, thisArg));
+        };
+
+        /**
+         * @method Database#each
+         * @description
+         * Executes a provided function once per array element, for an array of rows resolved by method {@link Database#any any}.
+         *
+         * It is a convenience method to reduce the following code:
+         *
+         * ```js
+         * db.any(query, values)
+         *     .then(data => {
+         *         data.forEach((row, index, data) => {
+         *              // process the row
+         *         });
+         *         return data;
+         *     });
+         * ```
+         *
+         * When receiving a multi-query result, only the last result is processed, ignoring the rest.
+         *
+         * @param {string|function|object} query
+         * Query to be executed, which can be any of the following types:
+         * - A non-empty query string
+         * - A function that returns a query string or another function, i.e. recursive resolution
+         *   is supported, passing in `values` as `this`, and as the first parameter.
+         * - Prepared Statement `{name, text, values, ...}` or {@link PreparedStatement} object
+         * - Parameterized Query `{text, values, ...}` or {@link ParameterizedQuery} object
+         * - {@link QueryFile} object
+         *
+         * @param {array|value|function} [values]
+         * Query formatting parameter(s), or a function that returns it.
+         *
+         * When `query` is of type `string` or a {@link QueryFile} object, the `values` can be:
+         * - a single value - to replace all `$1` occurrences
+         * - an array of values - to replace all `$1`, `$2`, ... variables
+         * - an object - to apply $[Named Parameters] formatting
+         *
+         * When `query` is a Prepared Statement or a Parameterized Query (or their class types),
+         * and `values` is not `null` or `undefined`, it is automatically set within such object,
+         * as an override for its internal `values`.
+         *
+         * @param {function} cb
+         * Function to execute for each row, taking three arguments:
+         * - `row` - the current row object being processed in the array
+         * - `index` - the index of the current row being processed in the array
+         * - `data` - the array of rows resolved by method {@link Database#any any}
+         *
+         * @param {*} [thisArg]
+         * Value to use as `this` when executing the callback.
+         *
+         * @returns {external:Promise<Array<Object>>}
+         * Resolves with the original array of rows.
+         *
+         * @see
+         * {@link Database#any any},
+         * {@link Database#map map},
+         * {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/forEach Array.forEach}
+         *
+         * @example
+         *
+         * db.each('SELECT id, code, name FROM Events', [], row => {
+         *     row.code = parseInt(row.code);
+         * })
+         *     .then(data => {
+         *         // data = array of events, with 'code' converted into integer
+         *     })
+         *     .catch(error => {
+         *         // error
+         *     });
+         *
+         */
+        obj.each = function (query, values, cb, thisArg) {
+            return obj.any.call(this, query, values)
+                .then(data => {
+                    data.forEach(cb, thisArg);
+                    return data;
+                });
+        };
+
+        /**
+         * @method Database#task
+         * @description
+         * Executes a callback function with automatically managed connection.
+         *
+         * When invoked on the root {@link Database} object, the method allocates the connection from the pool,
+         * executes the callback, and once finished - releases the connection back to the pool.
+         * However, when invoked inside another task or transaction, the method reuses the parent connection.
+         *
+         * This method should be used whenever executing more than one query at once, so the allocated connection
+         * is reused between all queries, and released only after the task has finished (see $[Chaining Queries]).
+         *
+         * The callback function is called with one parameter - database protocol (same as `this`), extended with methods
+         * {@link Task#batch batch}, {@link Task#page page}, {@link Task#sequence sequence}, plus property {@link Task#ctx ctx} -
+         * the task context object. See class {@link Task} for more details.
+         *
+         * @param {string|number|Object} [options]
+         * This parameter is optional, and presumed skipped when the first parameter is a function (`cb` parameter).
+         *
+         * When it is of type `string` or `number`, it is assumed to be option `tag` passed in directly. Otherwise,
+         * it is expected to be an object with options as listed below.
+         *
+         * @param {} [options.tag]
+         * Traceable context for the task (see $[tags]).
+         *
+         * @param {function} cb
+         * Task callback function, to return the result that will determine either success or failure for the operation.
+         *
+         * The function can be either the first of the second parameter passed into the method.
+         *
+         * It also can be an ES7 `async` function.
+         *
+         * @returns {external:Promise}
+         * A promise object with the result from the callback function.
+         *
+         * @see
+         * {@link Task},
+         * {@link Database#taskIf taskIf},
+         * {@link Database#tx tx},
+         * $[tags],
+         * $[Chaining Queries]
+         *
+         * @example
+         *
+         * db.task('my-task', async t => {
+         *         // t.ctx = task context object
+         *
+         *         const user = await t.one('SELECT id FROM Users WHERE name = $1', ['John']);
+         *         return t.any('SELECT * FROM Events WHERE userId = $1', [user.id]);
+         *     })
+         *     .then(data => {
+         *         // success
+         *         // data = as returned from the task's callback
+         *     })
+         *     .catch(error => {
+         *         // error
+         *     });
+         *
+         */
+        obj.task = function () {
+            const args = npm.pubUtils.taskArgs(arguments);
+            assert(args.options, ['tag']);
+            return taskProcessor.call(this, args, false);
+        };
+
+        /**
+         * @method Database#taskIf
+         * @description
+         * Executes a conditional task that results in an actual new {@link Database#task task}, if either condition is met or
+         * when it is necessary (on the top level), or else it reuses the current connection context.
+         *
+         * The default condition is `not in task or transaction`, to start a task only if currently not inside another task or transaction,
+         * which is the same as calling the following:
+         *
+         * ```js
+         * db.taskIf({cnd: t => !t.ctx}, cb => {})
+         * ```
+         *
+         * It can be useful, if you want to simplify/reduce the task + log events footprint, by creating new tasks only when necessary.
+         *
+         * @param {string|number|Object} [options]
+         * This parameter is optional, and presumed skipped when the first parameter is a function (`cb` parameter).
+         *
+         * When it is of type `string` or `number`, it is assumed to be option `tag` passed in directly. Otherwise,
+         * it is expected to be an object with options as listed below.
+         *
+         * @param {} [options.tag]
+         * Traceable context for the task/transaction (see $[tags]).
+         *
+         * @param {boolean|function} [options.cnd]
+         * Condition for creating a ({@link Database#task task}), if it is met.
+         * It can be either a simple boolean, or a callback function that takes the task context as `this` and as the first parameter.
+         *
+         * Default condition (when it is not specified):
+         *
+         * ```js
+         * {cnd: t => !t.ctx}
+         * ```
+         *
+         * @param {function} cb
+         * Task callback function, to return the result that will determine either success or failure for the operation.
+         *
+         * The function can be either the first or the second parameter passed into the method.
+         *
+         * It also can be an ES7 `async` function.
+         *
+         * @returns {external:Promise}
+         * A promise object with the result from the callback function.
+         *
+         * @see
+         * {@link Task},
+         * {@link Database#task Database.task},
+         * {@link Database#tx Database.tx},
+         * {@link Database#txIf Database.txIf},
+         * {@link TaskContext}
+         *
+         */
+        obj.taskIf = function () {
+            const args = npm.pubUtils.taskArgs(arguments);
+            assert(args.options, ['tag', 'cnd']);
+            try {
+                let cnd = args.options.cnd;
+                if ('cnd' in args.options) {
+                    cnd = typeof cnd === 'function' ? cnd.call(obj, obj) : !!cnd;
+                } else {
+                    cnd = !obj.ctx; // create a task if it is the top level
+                }
+                // reusable only if the condition fails, and not top-level:
+                args.options.reusable = !cnd && !!obj.ctx;
+            } catch (e) {
+                return Promise.reject(e);
+            }
+            return taskProcessor.call(this, args, false);
+        };
+
+        /**
+         * @method Database#tx
+         * @description
+         * Executes a callback function as a transaction, with automatically managed connection.
+         *
+         * When invoked on the root {@link Database} object, the method allocates the connection from the pool,
+         * executes the callback, and once finished - releases the connection back to the pool.
+         * However, when invoked inside another task or transaction, the method reuses the parent connection.
+         *
+         * A transaction wraps a regular {@link Database#task task} into additional queries:
+         * - it executes `BEGIN` just before invoking the callback function
+         * - it executes `COMMIT`, if the callback didn't throw any error or return a rejected promise
+         * - it executes `ROLLBACK`, if the callback did throw an error or return a rejected promise
+         * - it executes corresponding `SAVEPOINT` commands when the method is called recursively.
+         *
+         * The callback function is called with one parameter - database protocol (same as `this`), extended with methods
+         * {@link Task#batch batch}, {@link Task#page page}, {@link Task#sequence sequence}, plus property {@link Task#ctx ctx} -
+         * the transaction context object. See class {@link Task} for more details.
+         *
+         * Note that transactions should be chosen over tasks only where necessary, because unlike regular tasks,
+         * transactions are blocking operations.
+         *
+         * @param {string|number|Object} [options]
+         * This parameter is optional, and presumed skipped when the first parameter is a function (`cb` parameter).
+         *
+         * When it is of type `string` or `number`, it is assumed to be option `tag` passed in directly. Otherwise,
+         * it is expected to be an object with options as listed below.
+         *
+         * @param {} [options.tag]
+         * Traceable context for the transaction (see $[tags]).
+         *
+         * @param {txMode.TransactionMode} [options.mode]
+         * Transaction Configuration Mode - extends the transaction-opening command with additional configuration.
+         *
+         * @param {function} cb
+         * Transaction callback function, to return the result that will determine either success or failure for the operation.
+         *
+         * The function can be either the first of the second parameter passed into the method.
+         *
+         * It also can be an ES7 `async` function.
+         *
+         * @returns {external:Promise}
+         * A promise object with the result from the callback function.
+         *
+         * @see
+         * {@link Task},
+         * {@link Database#task Database.task},
+         * {@link Database#taskIf Database.taskIf},
+         * {@link TaskContext},
+         * $[tags],
+         * $[Chaining Queries]
+         *
+         * @example
+         *
+         * db.tx('my-transaction', t => {
+         *         // t.ctx = transaction context object
+         *
+         *         return t.one('INSERT INTO Users(name, age) VALUES($1, $2) RETURNING id', ['Mike', 25])
+         *             .then(user => {
+         *                 return t.batch([
+         *                     t.none('INSERT INTO Events(userId, name) VALUES($1, $2)', [user.id, 'created']),
+         *                     t.none('INSERT INTO Events(userId, name) VALUES($1, $2)', [user.id, 'login'])
+         *                 ]);
+         *             });
+         *     })
+         *     .then(data => {
+         *         // success
+         *         // data = as returned from the transaction's callback
+         *     })
+         *     .catch(error => {
+         *         // error
+         *     });
+         *
+         * @example
+         *
+         * // using an ES7 syntax for the callback:
+         * db.tx('my-transaction', async t => {
+         *         // t.ctx = transaction context object
+         *
+         *         const user = await t.one('INSERT INTO Users(name, age) VALUES($1, $2) RETURNING id', ['Mike', 25]);
+         *         return t.none('INSERT INTO Events(userId, name) VALUES($1, $2)', [user.id, 'created']);
+         *     })
+         *     .then(data => {
+         *         // success
+         *         // data = as returned from the transaction's callback
+         *     })
+         *     .catch(error => {
+         *         // error
+         *     });
+         */
+        obj.tx = function () {
+            const args = npm.pubUtils.taskArgs(arguments);
+            assert(args.options, ['tag', 'mode']);
+            return taskProcessor.call(this, args, true);
+        };
+
+        /**
+         * @method Database#txIf
+         * @description
+         * Executes a conditional transaction that results in an actual transaction ({@link Database#tx tx}), if the condition is met,
+         * or else it executes a regular {@link Database#task task}.
+         *
+         * The default condition is `not in transaction`, to start a transaction only if currently not in transaction,
+         * or else start a task, which is the same as calling the following:
+         *
+         * ```js
+         * db.txIf({cnd: t => !t.ctx || !t.ctx.inTransaction}, cb => {})
+         * ```
+         *
+         * It is useful when you want to avoid $[Nested Transactions] - savepoints.
+         *
+         * @param {string|number|Object} [options]
+         * This parameter is optional, and presumed skipped when the first parameter is a function (`cb` parameter).
+         *
+         * When it is of type `string` or `number`, it is assumed to be option `tag` passed in directly. Otherwise,
+         * it is expected to be an object with options as listed below.
+         *
+         * @param {} [options.tag]
+         * Traceable context for the task/transaction (see $[tags]).
+         *
+         * @param {txMode.TransactionMode} [options.mode]
+         * Transaction Configuration Mode - extends the transaction-opening command with additional configuration.
+         *
+         * @param {boolean|function} [options.cnd]
+         * Condition for opening a transaction ({@link Database#tx tx}), if it is met, or a {@link Database#task task} when the condition is not met.
+         * It can be either a simple boolean, or a callback function that takes the task/tx context as `this` and as the first parameter.
+         *
+         * Default condition (when it is not specified):
+         *
+         * ```js
+         * {cnd: t => !t.ctx || !t.ctx.inTransaction}
+         * ```
+         *
+         * @param {boolean|function} [options.reusable=false]
+         * When `cnd` is/returns false, reuse context of the current task/transaction, if one exists.
+         * It can be either a simple boolean, or a callback function that takes the task/tx context as `this`
+         * and as the first parameter.
+         *
+         * By default, when `cnd` is/returns false, the method creates a new task. This option tells
+         * the method to reuse the current task/transaction context, and not create a new task.
+         *
+         * This option is ignored when executing against the top level of the protocol, because on
+         * that level, if no transaction is suddenly needed, a new task becomes necessary.
+         *
+         * @param {function} cb
+         * Transaction/task callback function, to return the result that will determine either
+         * success or failure for the operation.
+         *
+         * The function can be either the first or the second parameter passed into the method.
+         *
+         * It also can be an ES7 `async` function.
+         *
+         * @returns {external:Promise}
+         * A promise object with the result from the callback function.
+         *
+         * @see
+         * {@link Task},
+         * {@link Database#task Database.task},
+         * {@link Database#taskIf Database.taskIf},
+         * {@link Database#tx Database.tx},
+         * {@link TaskContext}
+         */
+        obj.txIf = function () {
+            const args = npm.pubUtils.taskArgs(arguments);
+            assert(args.options, ['tag', 'mode', 'cnd', 'reusable']);
+            try {
+                let cnd;
+                if ('cnd' in args.options) {
+                    cnd = args.options.cnd;
+                    cnd = typeof cnd === 'function' ? cnd.call(obj, obj) : !!cnd;
+                } else {
+                    cnd = !obj.ctx || !obj.ctx.inTransaction;
+                }
+                args.options.cnd = cnd;
+                const reusable = args.options.reusable;
+                args.options.reusable = !cnd && obj.ctx && typeof reusable === 'function' ? reusable.call(obj, obj) : !!reusable;
+            } catch (e) {
+                return Promise.reject(e);
+            }
+            return taskProcessor.call(this, args, args.options.cnd);
+        };
+
+        // Task method;
+        // Resolves with the result from the callback function;
+        function taskProcessor(params, isTX) {
+
+            if (typeof params.cb !== 'function') {
+                return Promise.reject(new TypeError('Callback function is required.'));
+            }
+
+            if (params.options.reusable) {
+                return config.$npm.task.callback(obj.ctx, obj, params.cb, config);
+            }
+
+            const taskCtx = ctx.clone(); // task context object;
+            if (isTX) {
+                taskCtx.txLevel = taskCtx.txLevel >= 0 ? (taskCtx.txLevel + 1) : 0;
+            }
+            taskCtx.inTransaction = taskCtx.txLevel >= 0;
+            taskCtx.level = taskCtx.level >= 0 ? (taskCtx.level + 1) : 0;
+            taskCtx.cb = params.cb; // callback function;
+            taskCtx.mode = params.options.mode; // transaction mode;
+            if (this !== obj) {
+                taskCtx.context = this; // calling context object;
+            }
+
+            const tsk = new config.$npm.task.Task(taskCtx, params.options.tag, isTX, config);
+            taskCtx.taskCtx = tsk.ctx;
+            extend(taskCtx, tsk);
+
+            if (taskCtx.db) {
+                // reuse existing connection;
+                npm.utils.addReadProp(tsk.ctx, 'useCount', taskCtx.db.useCount);
+                addServerVersion(tsk.ctx, taskCtx.db.client);
+                return config.$npm.task.execute(taskCtx, tsk, isTX, config);
+            }
+
+            // connection required;
+            return config.$npm.connect.pool(taskCtx, dbThis)
+                .then(db => {
+                    taskCtx.connect(db);
+                    npm.utils.addReadProp(tsk.ctx, 'useCount', db.useCount);
+                    addServerVersion(tsk.ctx, db.client);
+                    return config.$npm.task.execute(taskCtx, tsk, isTX, config);
+                })
+                .then(data => {
+                    taskCtx.disconnect();
+                    return data;
+                })
+                .catch(error => {
+                    taskCtx.disconnect();
+                    return Promise.reject(error);
+                });
+        }
+
+        function addServerVersion(target, client) {
+            // Exclude else-case from the coverage because it can only occur with Native Bindings.
+            // istanbul ignore else
+            if (client.serverVersion) {
+                npm.utils.addReadProp(target, 'serverVersion', client.serverVersion);
+            }
+        }
+
+        // extending the protocol;
+        Events.extend(ctx.options, obj, ctx.dc);
+    }
+
+}
+
+// this event only happens when the connection is lost physically,
+// which cannot be tested automatically; removing from coverage:
+// istanbul ignore next
+function onError(err) {
+    // this client was never seen by pg-promise, which
+    // can happen if it failed to initialize
+    if (!err.client.$ctx) {
+        return;
+    }
+    const ctx = err.client.$ctx;
+    Events.error(ctx.options, err, {
+        cn: npm.utils.getSafeConnection(ctx.cn),
+        dc: ctx.dc
+    });
+}
+
+module.exports = config => {
+    const npmLocal = config.$npm;
+    npmLocal.connect = npmLocal.connect || npm.connect(config);
+    npmLocal.query = npmLocal.query || npm.query;
+    npmLocal.task = npmLocal.task || npm.task(config);
+    return Database;
+};
+
+/**
+ * @callback Database.streamInitCB
+ * @description
+ * Stream initialization callback, used by {@link Database#stream Database.stream}.
+ *
+ * @param {external:Stream} stream
+ * Stream object to initialize streaming.
+ *
+ * @example
+ * const QueryStream = require('pg-query-stream');
+ * const JSONStream = require('JSONStream');
+ *
+ * // you can also use pgp.as.format(query, values, options)
+ * // to format queries properly, via pg-promise;
+ * const qs = new QueryStream('SELECT * FROM users');
+ *
+ * db.stream(qs, stream => {
+ *         // initiate streaming into the console:
+ *         stream.pipe(JSONStream.stringify()).pipe(process.stdout);
+ *     })
+ *     .then(data => {
+ *         console.log('Total rows processed:', data.processed,
+ *           'Duration in milliseconds:', data.duration);
+ *     })
+ *     .catch(error => {
+ *         // error;
+ *     });
+ */
+
+/**
+ * @external Stream
+ * @see https://nodejs.org/api/stream.html
+ */
+
+/**
+ * @external pg-pool
+ * @alias pg-pool
+ * @see https://github.com/brianc/node-pg-pool
+ */
+
+/**
+ * @external Result
+ * @see https://node-postgres.com/apis/result
+ */