@depup/pg-promise 12.6.2-depup.0

package/lib/special-query.js

@@ -0,0 +1,30 @@
+/*
+ * 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 specialQueryType = {
+    result: 0,
+    multiResult: 1,
+    stream: 2
+};
+
+class SpecialQuery {
+    constructor(type) {
+        this.isResult = type === specialQueryType.result; // type used implicitly
+        this.isStream = type === specialQueryType.stream;
+        this.isMultiResult = type === specialQueryType.multiResult;
+    }
+}
+
+const cache = {
+    resultQuery: new SpecialQuery(specialQueryType.result),
+    multiResultQuery: new SpecialQuery(specialQueryType.multiResult),
+    streamQuery: new SpecialQuery(specialQueryType.stream)
+};
+
+module.exports = {SpecialQuery, ...cache};

package/lib/stream.js

@@ -0,0 +1,125 @@
+/*
+ * 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 npm = {
+    utils: require('./utils'),
+    text: require('./text')
+};
+
+////////////////////////////////////////////
+// Streams query data into any destination,
+// with the help of pg-query-stream library.
+function $stream(ctx, qs, initCB) {
+
+    // istanbul ignore next:
+    // we do not provide code coverage for the Native Bindings specifics
+    if (ctx.options.pgNative) {
+        return Promise.reject(new Error(npm.text.nativeStreaming));
+    }
+    // Stream class was renamed again, see the following issue:
+    // https://github.com/brianc/node-postgres/issues/2412
+    if (!qs || !qs.constructor || qs.constructor.name !== 'QueryStream') {
+        // invalid or missing stream object;
+        return Promise.reject(new TypeError(npm.text.invalidStream));
+    }
+    if (qs._reading || qs._closed) {
+        // stream object is in the wrong state;
+        return Promise.reject(new Error(npm.text.invalidStreamState));
+    }
+    if (typeof initCB !== 'function') {
+        // parameter `initCB` must be passed as the initialization callback;
+        return Promise.reject(new TypeError(npm.text.invalidStreamCB));
+    }
+
+    let error = Events.query(ctx.options, getContext());
+
+    if (error) {
+        error = getError(error);
+        Events.error(ctx.options, error, getContext());
+        return Promise.reject(error);
+    }
+
+    const stream = ctx.db.client.query(qs);
+
+    stream.on('data', onData);
+    stream.on('error', onError);
+    stream.on('end', onEnd);
+
+    try {
+        initCB.call(this, stream); // the stream must be initialized during the call;
+    } catch (e) {
+        release();
+        error = getError(e);
+        Events.error(ctx.options, error, getContext());
+        return Promise.reject(error);
+    }
+
+    const start = Date.now();
+    let resolve, reject, nRows = 0;
+
+    function onData(data) {
+        nRows++;
+        error = Events.receive(ctx.options, [data], undefined, getContext());
+        if (error) {
+            onError(error);
+        }
+    }
+
+    function onError(e) {
+        release();
+        stream.destroy();
+        e = getError(e);
+        Events.error(ctx.options, e, getContext());
+        reject(e);
+    }
+
+    function onEnd() {
+        release();
+        resolve({
+            processed: nRows, // total number of rows processed;
+            duration: Date.now() - start // duration, in milliseconds;
+        });
+    }
+
+    function release() {
+        stream.removeListener('data', onData);
+        stream.removeListener('error', onError);
+        stream.removeListener('end', onEnd);
+    }
+
+    function getError(e) {
+        return e instanceof npm.utils.InternalError ? e.error : e;
+    }
+
+    function getContext() {
+        let client;
+        if (ctx.db) {
+            client = ctx.db.client;
+        } else {
+            error = new Error(npm.text.looseQuery);
+        }
+        return {
+            client,
+            dc: ctx.dc,
+            query: qs.cursor.text,
+            params: qs.cursor.values,
+            ctx: ctx.ctx
+        };
+    }
+
+    return new Promise((res, rej) => {
+        resolve = res;
+        reject = rej;
+    });
+
+}
+
+module.exports = {stream: $stream};

package/lib/task.js

@@ -0,0 +1,404 @@
+/*
+ * 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 npm = {
+    spex: require('spex'),
+    utils: require('./utils'),
+    mode: require('./tx-mode'),
+    query: require('./query').query,
+    text: require('./text')
+};
+
+/**
+ * @interface Task
+ * @description
+ * Extends {@link Database} for an automatic connection session, with methods for executing multiple database queries.
+ *
+ * The type isn't available directly, it can only be created via methods {@link Database#task Database.task}, {@link Database#tx Database.tx},
+ * or their derivations.
+ *
+ * When executing more than one request at a time, one should allocate and release the connection only once,
+ * while executing all the required queries within the same connection session. More importantly, a transaction
+ * can only work within a single connection.
+ *
+ * This is an interface for tasks/transactions to implement a connection session, during which you can
+ * execute multiple queries against the same connection that's released automatically when the task/transaction is finished.
+ *
+ * Each task/transaction manages the connection automatically. When executed on the root {@link Database} object, the connection
+ * is allocated from the pool, and once the method's callback has finished, the connection is released back to the pool.
+ * However, when invoked inside another task or transaction, the method reuses the parent connection.
+ *
+ * @see
+ * {@link Task#ctx ctx},
+ * {@link Task#batch batch},
+ * {@link Task#sequence sequence},
+ * {@link Task#page page}
+ *
+ * @example
+ * db.task(t => {
+ *       // t = task protocol context;
+ *       // t.ctx = Task Context;
+ *       return t.one('select * from users where id=$1', 123)
+ *           .then(user => {
+ *               return t.any('select * from events where login=$1', user.name);
+ *           });
+ *   })
+ * .then(events => {
+ *       // success;
+ *   })
+ * .catch(error => {
+ *       // error;
+ *   });
+ *
+ */
+function Task(ctx, tag, isTX, config) {
+
+    /**
+     * @member {TaskContext} Task#ctx
+     * @readonly
+     * @description
+     * Task/Transaction Context object - contains individual properties for each task/transaction.
+     *
+     * @see event {@link event:query query}
+     *
+     * @example
+     *
+     * db.task(t => {
+     *     return t.ctx; // task context object
+     * })
+     *     .then(ctx => {
+     *         console.log('Task Duration:', ctx.duration);
+     *     });
+     *
+     * @example
+     *
+     * db.tx(t => {
+     *     return t.ctx; // transaction context object
+     * })
+     *     .then(ctx => {
+     *         console.log('Transaction Duration:', ctx.duration);
+     *     });
+     */
+    this.ctx = ctx.ctx = {}; // task context object;
+
+    npm.utils.addReadProp(this.ctx, 'isTX', isTX);
+
+    if ('context' in ctx) {
+        npm.utils.addReadProp(this.ctx, 'context', ctx.context);
+    }
+
+    npm.utils.addReadProp(this.ctx, 'connected', !ctx.db);
+    npm.utils.addReadProp(this.ctx, 'tag', tag);
+    npm.utils.addReadProp(this.ctx, 'dc', ctx.dc);
+    npm.utils.addReadProp(this.ctx, 'level', ctx.level);
+    npm.utils.addReadProp(this.ctx, 'inTransaction', ctx.inTransaction);
+
+    if (isTX) {
+        npm.utils.addReadProp(this.ctx, 'txLevel', ctx.txLevel);
+    }
+
+    npm.utils.addReadProp(this.ctx, 'parent', ctx.parentCtx);
+
+    // generic query method;
+    this.query = function (query, values, qrm) {
+        if (!ctx.db) {
+            return Promise.reject(new Error(npm.text.looseQuery));
+        }
+        return config.$npm.query.call(this, ctx, query, values, qrm);
+    };
+
+    /**
+     * @method Task#batch
+     * @description
+     * Settles a predefined array of mixed values by redirecting to method $[spex.batch].
+     *
+     * **NOTE:**
+     * Consider using `async/await` syntax instead, or if you must have
+     * pre-generated promises, then $[Promise.allSettled].
+     *
+     * @param {array} values
+     * @param {Object} [options]
+     * Optional Parameters.
+     * @param {function} [options.cb]
+     *
+     * @returns {external:Promise}
+     */
+    this.batch = function (values, options) {
+        return config.$npm.spex.batch.call(this, values, options);
+    };
+
+    /**
+     * @method Task#page
+     * @description
+     * Resolves a dynamic sequence of arrays/pages with mixed values, by redirecting to method $[spex.page].
+     *
+     * For complete method documentation see $[spex.page].
+     *
+     * @param {function} source
+     * @param {Object} [options]
+     * Optional Parameters.
+     * @param {function} [options.dest]
+     * @param {number} [options.limit=0]
+     *
+     * @returns {external:Promise}
+     */
+    this.page = function (source, options) {
+        return config.$npm.spex.page.call(this, source, options);
+    };
+
+    /**
+     * @method Task#sequence
+     * @description
+     * Resolves a dynamic sequence of mixed values by redirecting to method $[spex.sequence].
+     *
+     * For complete method documentation see $[spex.sequence].
+     *
+     * @param {function} source
+     * @param {Object} [options]
+     * Optional Parameters.
+     * @param {function} [options.dest]
+     * @param {number} [options.limit=0]
+     * @param {boolean} [options.track=false]
+     *
+     * @returns {external:Promise}
+     */
+    this.sequence = function (source, options) {
+        return config.$npm.spex.sequence.call(this, source, options);
+    };
+
+}
+
+/**
+ * @private
+ * @method Task.callback
+ * Callback invocation helper.
+ *
+ * @param ctx
+ * @param obj
+ * @param cb
+ * @param config
+ * @returns {Promise.<TResult>}
+ */
+const callback = (ctx, obj, cb) => {
+
+    let result;
+
+    try {
+        if (cb.constructor.name === 'GeneratorFunction') {
+            throw new TypeError('ES6 generator functions are not supported!');
+        }
+        result = cb.call(obj, obj); // invoking the callback function;
+    } catch (err) {
+        Events.error(ctx.options, err, {
+            client: ctx.db && ctx.db.client, // the error can be due to loss of connectivity
+            dc: ctx.dc,
+            ctx: ctx.ctx
+        });
+        return Promise.reject(err); // reject with the error;
+    }
+    if (result instanceof Promise) {
+        return result; // result is a valid promise object;
+    }
+    return Promise.resolve(result);
+};
+
+/**
+ * @private
+ * @method Task.execute
+ * Executes a task.
+ *
+ * @param ctx
+ * @param obj
+ * @param isTX
+ * @param config
+ * @returns {Promise.<TResult>}
+ */
+const execute = (ctx, obj, isTX, config) => {
+
+    // updates the task context and notifies the client;
+    function update(start, success, result) {
+        const c = ctx.ctx;
+        if (start) {
+            npm.utils.addReadProp(c, 'start', new Date());
+        } else {
+            c.finish = new Date();
+            c.success = success;
+            c.result = result;
+            c.duration = c.finish - c.start;
+        }
+        (isTX ? Events.transact : Events.task)(ctx.options, {
+            client: ctx.db && ctx.db.client, // loss of connectivity is possible at this point
+            dc: ctx.dc,
+            ctx: c
+        });
+    }
+
+    let cbData, cbReason, success,
+        spName; // Save-Point Name;
+
+    const capSQL = ctx.options.capSQL; // capitalize sql;
+
+    update(true);
+
+    if (isTX) {
+        // executing a transaction;
+        spName = `sp_${ctx.txLevel}_${ctx.nextTxCount}`;
+        return begin()
+            .then(() => callback(ctx, obj, ctx.cb, config)
+                .then(data => {
+                    cbData = data; // save callback data;
+                    success = true;
+                    return commit();
+                }, err => {
+                    cbReason = err; // save callback failure reason;
+                    return rollback();
+                })
+                .then(() => {
+                    if (success) {
+                        update(false, true, cbData);
+                        return cbData;
+                    }
+                    update(false, false, cbReason);
+                    return Promise.reject(cbReason);
+                },
+                err => {
+                    // either COMMIT or ROLLBACK has failed, which is impossible
+                    // to replicate in a test environment, so skipping from the test;
+                    // istanbul ignore next:
+                    update(false, false, err);
+                    // istanbul ignore next:
+                    return Promise.reject(err);
+                }),
+            err => {
+                // BEGIN has failed, which is impossible to replicate in a test
+                // environment, so skipping the whole block from the test;
+                // istanbul ignore next:
+                update(false, false, err);
+                // istanbul ignore next:
+                return Promise.reject(err);
+            });
+    }
+
+    function begin() {
+        if (!ctx.txLevel && ctx.mode instanceof npm.mode.TransactionMode) {
+            return exec(ctx.mode.begin(capSQL), 'savepoint');
+        }
+        return exec('begin', 'savepoint');
+    }
+
+    function commit() {
+        return exec('commit', 'release savepoint');
+    }
+
+    function rollback() {
+        return exec('rollback', 'rollback to savepoint');
+    }
+
+    function exec(top, nested) {
+        if (ctx.txLevel) {
+            return obj.none((capSQL ? nested.toUpperCase() : nested) + ' ' + spName);
+        }
+        return obj.none(capSQL ? top.toUpperCase() : top);
+    }
+
+    // executing a task;
+    return callback(ctx, obj, ctx.cb, config)
+        .then(data => {
+            update(false, true, data);
+            return data;
+        })
+        .catch(error => {
+            update(false, false, error);
+            return Promise.reject(error);
+        });
+};
+
+module.exports = config => {
+    const npmLocal = config.$npm;
+    npmLocal.query = npmLocal.query || npm.query;
+    npmLocal.spex = npmLocal.spex || npm.spex;
+    return {
+        Task, execute, callback
+    };
+};
+
+/**
+ * @typedef TaskContext
+ * @description
+ * Task/Transaction Context used via property {@link Task#ctx ctx} inside tasks (methods {@link Database#task Database.task} and {@link Database#taskIf Database.taskIf})
+ * and transactions (methods {@link Database#tx Database.tx} and {@link Database#txIf Database.txIf}).
+ *
+ * Properties `context`, `connected`, `parent`, `level`, `dc`, `isTX`, `tag`, `start`, `useCount` and `serverVersion` are set just before the operation has started,
+ * while properties `finish`, `duration`, `success` and `result` are set immediately after the operation has finished.
+ *
+ * @property {*} context
+ * If the operation was invoked with a calling context - `task.call(context,...)` or `tx.call(context,...)`,
+ * this property is set with the context that was passed in. Otherwise, the property doesn't exist.
+ *
+ * @property {*} dc
+ * _Database Context_ that was passed into the {@link Database} object during construction.
+ *
+ * @property {boolean} isTX
+ * Indicates whether this operation is a transaction (as opposed to a regular task).
+ *
+ * @property {number} duration
+ * Number of milliseconds consumed by the operation.
+ *
+ * Set after the operation has finished, it is simply a shortcut for `finish - start`.
+ *
+ * @property {number} level
+ * Task nesting level, starting from 0, counting both regular tasks and transactions.
+ *
+ * @property {number} txLevel
+ * Transaction nesting level, starting from 0. Transactions on level 0 use `BEGIN/COMMIT/ROLLBACK`,
+ * while transactions on nested levels use the corresponding `SAVEPOINT` commands.
+ *
+ * This property exists only within the context of a transaction (`isTX = true`).
+ *
+ * @property {boolean} inTransaction
+ * Available in both tasks and transactions, it simplifies checking when there is a transaction
+ * going on either on this level or above.
+ *
+ * For example, when you want to check for a containing transaction while inside a task, and
+ * only start a transaction when there is none yet.
+ *
+ * @property {TaskContext} parent
+ * Parent task/transaction context, or `null` when it is top-level.
+ *
+ * @property {boolean} connected
+ * Indicates when the task/transaction acquired the connection on its own (`connected = true`), and will release it once
+ * the operation has finished. When the value is `false`, the operation is reusing an existing connection.
+ *
+ * @property {*} tag
+ * Tag value as it was passed into the task. See methods {@link Database#task task} and {@link Database#tx tx}.
+ *
+ * @property {Date} start
+ * Date/Time of when this operation started the execution.
+ *
+ * @property {number} useCount
+ * Number of times the connection has been previously used, starting with 0 for a freshly
+ * allocated physical connection.
+ *
+ * @property {string} serverVersion
+ * Version of the PostgreSQL server to which we are connected.
+ * Not available with $[Native Bindings].
+ *
+ * @property {Date} finish
+ * Once the operation has finished, this property is set to the Data/Time of when it happened.
+ *
+ * @property {boolean} success
+ * Once the operation has finished, this property indicates whether it was successful.
+ *
+ * @property {*} result
+ * Once the operation has finished, this property contains the result, depending on property `success`:
+ * - data resolved by the operation, if `success = true`
+ * - error / rejection reason, if `success = false`
+ */

package/lib/text.js

@@ -0,0 +1,40 @@
+/*
+ * 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.
+ */
+
+/* All error messages used in the module */
+
+const streamVersion = require('../package.json')
+    .devDependencies['pg-query-stream'];
+
+module.exports = {
+    nativeError: 'Failed to initialize Native Bindings.',
+
+    /* Database errors */
+    queryDisconnected: 'Cannot execute a query on a disconnected client.',
+    invalidQuery: 'Invalid query format.',
+    invalidFunction: 'Invalid function name.',
+    invalidProc: 'Invalid procedure name.',
+    invalidMask: 'Invalid Query Result Mask specified.',
+    looseQuery: 'Querying against a released or lost connection.',
+
+    /* result errors */
+    notEmpty: 'No return data was expected.',
+    noData: 'No data returned from the query.',
+    multiple: 'Multiple rows were not expected.',
+
+    /* streaming support */
+    nativeStreaming: 'Streaming doesn\'t work with Native Bindings.',
+    invalidStream: `Invalid or missing stream object: pg-query-stream >= v${streamVersion} was expected`,
+    invalidStreamState: 'Invalid stream state.',
+    invalidStreamCB: 'Invalid or missing stream initialization callback.',
+
+    /* connection errors */
+    poolDestroyed: 'Connection pool of the database object has been destroyed.',
+    clientEnd: 'Abnormal client.end() call, due to invalid code or failed server connection.'
+};