@depup/pg-promise 12.6.2-depup.0

package/lib/tx-mode.js

@@ -0,0 +1,194 @@
+/*
+ * 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 {InnerState} = require('./inner-state');
+const {assert} = require('./assert');
+
+const npm = {
+    addInspection: require('./utils').addInspection,
+    inspect: require('util').inspect
+};
+
+/**
+ * @enum {number}
+ * @alias txMode.isolationLevel
+ * @readonly
+ * @summary Transaction Isolation Level.
+ * @description
+ * The type is available from the {@link txMode} namespace.
+ *
+ * @see $[Transaction Isolation]
+ */
+const isolationLevel = {
+    /** Isolation level isn't specified. */
+    none: 0,
+
+    /** `ISOLATION LEVEL SERIALIZABLE` */
+    serializable: 1,
+
+    /** `ISOLATION LEVEL REPEATABLE READ` */
+    repeatableRead: 2,
+
+    /** `ISOLATION LEVEL READ COMMITTED` */
+    readCommitted: 3
+
+    // From the official documentation: https://www.postgresql.org/docs/17/sql-set-transaction.html
+    // The SQL standard defines one additional level, READ UNCOMMITTED. In PostgreSQL READ UNCOMMITTED is treated as READ COMMITTED.
+    // => skipping `READ UNCOMMITTED`.
+};
+
+/**
+ * @class txMode.TransactionMode
+ * @description
+ * Constructs a complete transaction-opening `BEGIN` command, from these options:
+ *  - isolation level
+ *  - access mode
+ *  - deferrable mode
+ *
+ * The type is available from the {@link txMode} namespace.
+ *
+ * @param {} [options]
+ * Transaction Mode options.
+ *
+ * @param {txMode.isolationLevel} [options.tiLevel]
+ * Transaction Isolation Level.
+ *
+ * @param {boolean} [options.readOnly]
+ * Sets transaction access mode based on the read-only flag:
+ *  - `undefined` - access mode not specified (default)
+ *  - `true` - access mode is set to `READ ONLY`
+ *  - `false` - access mode is set to `READ WRITE`
+ *
+ * @param {boolean} [options.deferrable]
+ * Sets transaction deferrable mode based on the boolean value:
+ *  - `undefined` - deferrable mode not specified (default)
+ *  - `true` - mode is set to `DEFERRABLE`
+ *  - `false` - mode is set to `NOT DEFERRABLE`
+ *
+ * It is used only when `tiLevel`=`isolationLevel.serializable`
+ * and `readOnly`=`true`, or else it is ignored.
+ *
+ * @returns {txMode.TransactionMode}
+ *
+ * @see $[BEGIN], {@link txMode.isolationLevel}
+ *
+ * @example
+ *
+ * const {TransactionMode, isolationLevel} = pgp.txMode;
+ *
+ * // Create a reusable transaction mode (serializable + read-only + deferrable):
+ * const mode = new TransactionMode({
+ *     tiLevel: isolationLevel.serializable,
+ *     readOnly: true,
+ *     deferrable: true
+ * });
+ *
+ * db.tx({mode}, t => {
+ *     return t.any('SELECT * FROM table');
+ * })
+ *     .then(data => {
+ *         // success;
+ *     })
+ *     .catch(error => {
+ *         // error
+ *     });
+ *
+ * // Instead of the default BEGIN, such transaction will start with:
+ *
+ * // BEGIN ISOLATION LEVEL SERIALIZABLE READ ONLY DEFERRABLE
+ *
+ */
+class TransactionMode extends InnerState {
+
+    constructor(options) {
+        options = assert(options, ['tiLevel', 'deferrable', 'readOnly']);
+        const {readOnly, deferrable} = options;
+        let {tiLevel} = options;
+        let level, accessMode, deferrableMode, begin = 'begin';
+        tiLevel = (tiLevel > 0) ? parseInt(tiLevel) : 0;
+
+        if (tiLevel > 0 && tiLevel < 4) {
+            const values = ['serializable', 'repeatable read', 'read committed'];
+            level = 'isolation level ' + values[tiLevel - 1];
+        }
+        if (readOnly) {
+            accessMode = 'read only';
+        } else {
+            if (readOnly !== undefined) {
+                accessMode = 'read write';
+            }
+        }
+        // From the official documentation: https://www.postgresql.org/docs/17/sql-set-transaction.html
+        // The DEFERRABLE transaction property has no effect unless the transaction is also SERIALIZABLE and READ ONLY
+        if (tiLevel === isolationLevel.serializable && readOnly) {
+            if (deferrable) {
+                deferrableMode = 'deferrable';
+            } else {
+                if (deferrable !== undefined) {
+                    deferrableMode = 'not deferrable';
+                }
+            }
+        }
+        if (level) {
+            begin += ' ' + level;
+        }
+        if (accessMode) {
+            begin += ' ' + accessMode;
+        }
+        if (deferrableMode) {
+            begin += ' ' + deferrableMode;
+        }
+
+        super({begin, capBegin: begin.toUpperCase()});
+    }
+
+    /**
+     * @method txMode.TransactionMode#begin
+     * @description
+     * Returns a complete BEGIN statement, according to all the parameters passed into the class.
+     *
+     * This method is primarily for internal use by the library.
+     *
+     * @param {boolean} [cap=false]
+     * Indicates whether the returned SQL must be capitalized.
+     *
+     * @returns {string}
+     */
+    begin(cap) {
+        return cap ? this._inner.capBegin : this._inner.begin;
+    }
+}
+
+npm.addInspection(TransactionMode, function () {
+    const obj = {SQL: this.begin(true)};
+    return 'TransactionMode ' + npm.inspect(obj, {breakLength: 100, depth: 5, colors: true});
+});
+
+/**
+ * @namespace txMode
+ * @description
+ * Transaction Mode namespace, available as `pgp.txMode`, before and after initializing the library.
+ *
+ * Extends the default `BEGIN` with Transaction Mode parameters:
+ *  - isolation level
+ *  - access mode
+ *  - deferrable mode
+ *
+ * @property {function} TransactionMode
+ * {@link txMode.TransactionMode TransactionMode} class constructor.
+ *
+ * @property {txMode.isolationLevel} isolationLevel
+ * Transaction Isolation Level enumerator
+ *
+ * @see $[BEGIN]
+ */
+module.exports = {
+    isolationLevel,
+    TransactionMode
+};

package/lib/types/index.js

@@ -0,0 +1,18 @@
+/*
+ * 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 {ServerFormatting} = require('./server-formatting');
+const {PreparedStatement} = require('./prepared-statement');
+const {ParameterizedQuery} = require('./parameterized-query');
+
+module.exports = {
+    ServerFormatting,
+    PreparedStatement,
+    ParameterizedQuery
+};

package/lib/types/parameterized-query.js

@@ -0,0 +1,247 @@
+/*
+ * 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 {ServerFormatting} = require('./server-formatting');
+const {ParameterizedQueryError} = require('../errors');
+const {QueryFile} = require('../query-file');
+const {assert} = require('../assert');
+
+const npm = {
+    EOL: require('os').EOL,
+    utils: require('../utils'),
+    inspect: require('util').inspect
+};
+
+/**
+ * @class ParameterizedQuery
+ * @description
+ * Constructs a new {@link ParameterizedQuery} object. All properties can also be set after the object's construction.
+ *
+ * This type extends the basic `{text, values}` object, i.e. when the basic object is used with a query method,
+ * a new {@link ParameterizedQuery} object is created in its place.
+ *
+ * The type can be used in place of the `query` parameter, with any query method directly.
+ *
+ * The type is available from the library's root: `pgp.ParameterizedQuery`.
+ *
+ * @param {string|QueryFile|Object} [options]
+ * Object configuration options / properties.
+ *
+ * @param {string|QueryFile} [options.text] - See property {@link ParameterizedQuery#text text}.
+ * @param {array} [options.values] - See property {@link ParameterizedQuery#values values}.
+ * @param {boolean} [options.binary] - See property {@link ParameterizedQuery#binary binary}.
+ * @param {string} [options.rowMode] - See property {@link ParameterizedQuery#rowMode rowMode}.
+ * @param {ITypes} [options.types] - See property {@link ParameterizedQuery#types types}.
+ *
+ * @returns {ParameterizedQuery}
+ *
+ * @see
+ * {@link errors.ParameterizedQueryError ParameterizedQueryError}
+ *
+ * @example
+ *
+ * const {ParameterizedQuery: PQ} = require('pg-promise');
+ *
+ * // Creating a complete Parameterized Query with parameters:
+ * const findUser = new PQ({text: 'SELECT * FROM Users WHERE id = $1', values: [123]});
+ *
+ * db.one(findUser)
+ *     .then(user => {
+ *         // user found;
+ *     })
+ *     .catch(error => {
+ *         // error;
+ *     });
+ *
+ * @example
+ *
+ * const {ParameterizedQuery: PQ} = require('pg-promise');
+ *
+ * // Creating a reusable Parameterized Query without values:
+ * const addUser = new PQ('INSERT INTO Users(name, age) VALUES($1, $2)');
+ *
+ * // setting values explicitly:
+ * addUser.values = ['John', 30];
+ *
+ * db.none(addUser)
+ *     .then(() => {
+ *         // user added;
+ *     })
+ *     .catch(error=> {
+ *         // error;
+ *     });
+ *
+ * // setting values implicitly, by passing them into the query method:
+ * db.none(addUser, ['Mike', 25])
+ *     .then(() => {
+ *         // user added;
+ *     })
+ *     .catch(error=> {
+ *         // error;
+ *     });
+ */
+class ParameterizedQuery extends ServerFormatting {
+    constructor(options) {
+        if (typeof options === 'string' || options instanceof QueryFile) {
+            options = {
+                text: options
+            };
+        } else {
+            options = assert(options, ['text', 'values', 'binary', 'rowMode', 'types']);
+        }
+        super(options);
+    }
+}
+
+/**
+ * @method ParameterizedQuery#parse
+ * @description
+ * Parses the current object and returns a simple `{text, values}`, if successful,
+ * or else it returns a {@link errors.ParameterizedQueryError ParameterizedQueryError} object.
+ *
+ * This method is primarily for internal use by the library.
+ *
+ * @returns {{text, values}|errors.ParameterizedQueryError}
+ */
+ParameterizedQuery.prototype.parse = function () {
+
+    const _i = this._inner, options = _i.options;
+    const qf = options.text instanceof QueryFile ? options.text : null;
+
+    if (!_i.changed && !qf) {
+        return _i.target;
+    }
+
+    const errors = [], values = _i.target.values;
+    _i.target = {
+        text: options.text
+    };
+    _i.changed = true;
+    _i.currentError = undefined;
+
+    if (qf) {
+        qf.prepare();
+        if (qf.error) {
+            errors.push(qf.error);
+        } else {
+            _i.target.text = qf[QueryFile.$query];
+        }
+    }
+
+    if (!npm.utils.isText(_i.target.text)) {
+        errors.push('Property \'text\' must be a non-empty text string.');
+    }
+
+    if (!npm.utils.isNull(values)) {
+        _i.target.values = values;
+    }
+
+    if (options.binary !== undefined) {
+        _i.target.binary = !!options.binary;
+    }
+
+    if (options.rowMode !== undefined) {
+        _i.target.rowMode = options.rowMode;
+    }
+
+    if (options.types !== undefined) {
+        _i.target.types = options.types;
+    }
+
+    if (errors.length) {
+        return _i.currentError = new ParameterizedQueryError(errors[0], _i.target);
+    }
+
+    _i.changed = false;
+
+    return _i.target;
+};
+
+npm.utils.addInspection(ParameterizedQuery, function () {
+    const pq = this.parse();
+    const obj = {};
+    if (npm.utils.isText(pq.text)) {
+        obj.text = pq.text;
+    }
+    if (this.values !== undefined) {
+        obj.values = this.values;
+    }
+    if (this.binary !== undefined) {
+        obj.binary = this.binary;
+    }
+    if (this.rowMode !== undefined) {
+        obj.rowMode = this.rowMode;
+    }
+    if (this.error !== undefined) {
+        obj.error = this.error.message;
+    }
+    return 'ParameterizedQuery ' + npm.inspect(obj, {breakLength: 100, depth: 5, colors: true});
+});
+
+module.exports = {ParameterizedQuery};
+
+/**
+ * @name ParameterizedQuery#text
+ * @type {string|QueryFile}
+ * @description
+ * A non-empty query string or a {@link QueryFile} object.
+ *
+ * Only the basic variables (`$1`, `$2`, etc) can be used in the query, because _Parameterized Queries_
+ * are formatted on the server side.
+ */
+
+/**
+ * @name ParameterizedQuery#values
+ * @type {array}
+ * @description
+ * Query formatting parameters, depending on the type:
+ *
+ * - `null` / `undefined` means the query has no formatting parameters
+ * - `Array` - it is an array of formatting parameters
+ * - None of the above, means it is a single formatting value, which
+ *   is then automatically wrapped into an array
+ */
+
+/**
+ * @name ParameterizedQuery#binary
+ * @type {boolean}
+ * @default undefined
+ * @description
+ * Activates binary result mode. The default is the text mode.
+ *
+ * @see {@link http://www.postgresql.org/docs/devel/static/protocol-flow.html#PROTOCOL-FLOW-EXT-QUERY Extended Query}
+ */
+
+/**
+ * @name ParameterizedQuery#rowMode
+ * @type {string}
+ * @default undefined
+ * @description
+ * Changes the way data arrives to the client, with only one value supported by $[pg]:
+ *  - `array` will make all data rows arrive as arrays of values. By default, rows arrive as objects.
+ */
+
+/**
+ * @name ParameterizedQuery#types
+ * @type {ITypes}
+ * @default undefined
+ * @description
+ * Custom type parsers just for this query result.
+ */
+
+/**
+ * @name ParameterizedQuery#error
+ * @type {errors.ParameterizedQueryError}
+ * @default undefined
+ * @readonly
+ * @description
+ * When in an error state, it is set to a {@link errors.ParameterizedQueryError ParameterizedQueryError} object. Otherwise, it is `undefined`.
+ *
+ * This property is primarily for internal use by the library.
+ */