/*
 * 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'),
    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,
        $p = config.promise,
        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 $p.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 $p.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
     * - `promiseLib` - instance of the promise library that's used
     * - `promise` - generic promise interface that uses `promiseLib` via 4 basic methods:
     *   - `promise((resolve, reject) => {})` - to create a new promise
     *   - `promise.resolve(value)` - to resolve with a value
     *   - `promise.reject(reason)` - to reject with a reason
     *   - `promise.all(iterable)` - to resolve an iterable list of promises
     * - `version` - this library's version
     * - `$npm` _(hidden property)_ - internal module cache
     *
     * @example
     *
     * // Using the promise protocol as configured by pg-promise:
     *
     * const $p = db.$config.promise;
     *
     * const resolvedPromise = $p.resolve('some data');
     * const rejectedPromise = $p.reject('some reason');
     *
     * const newPromise = $p((resolve, reject) => {
     *     // call either resolve(data) or reject(reason) here
     * });
     */
    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', t => {
         *         // t.ctx = task context object
         *
         *         return t.one('SELECT id FROM Users WHERE name = $1', 'John')
         *             .then(user => {
         *                 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
         *     });
         *
         * @example
         *
         * // using an ES7 syntax for the callback:
         * 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 task, if it is the top level
                }
                // reusable only if condition fails, and not top-level:
                args.options.reusable = !cnd && !!obj.ctx;
            } catch (e) {
                return $p.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 $p.reject(e);
            }
            return taskProcessor.call(this, args, args.options.cnd);
        };

        // Task method;
        // Resolves with result from the callback function;
        function taskProcessor(params, isTX) {

            if (typeof params.cb !== 'function') {
                return $p.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 $p.reject(error);
                });
        }

        function addServerVersion(target, client) {
            // Exclude else-case from 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(config);
    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/api/result
 */