@depup/pg-promise 12.6.2-depup.0

package/lib/types/prepared-statement.js

@@ -0,0 +1,298 @@
+/*
+ * 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 {PreparedStatementError} = 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 PreparedStatement
+ * @description
+ * Constructs a new $[Prepared Statement] object. All properties can also be set after the object's construction.
+ *
+ * This type extends the basic `{name, text, values}` object, i.e. when the basic object is used
+ * with a query method, a new {@link PreparedStatement} 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.PreparedStatement`.
+ *
+ * @param {Object} [options]
+ * Object configuration options / properties.
+ *
+ * @param {string} [options.name] - See property {@link PreparedStatement#name name}.
+ * @param {string|QueryFile} [options.text] - See property {@link PreparedStatement#text text}.
+ * @param {array} [options.values] - See property {@link PreparedStatement#values values}.
+ * @param {boolean} [options.binary] - See property {@link PreparedStatement#binary binary}.
+ * @param {string} [options.rowMode] - See property {@link PreparedStatement#rowMode rowMode}.
+ * @param {number} [options.rows] - See property {@link PreparedStatement#rows rows}.
+ * @param {ITypes} [options.types] - See property {@link PreparedStatement#types types}.
+ *
+ * @returns {PreparedStatement}
+ *
+ * @see
+ * {@link errors.PreparedStatementError PreparedStatementError},
+ * {@link https://www.postgresql.org/docs/17/sql-prepare.html PostgreSQL Prepared Statements}
+ *
+ * @example
+ *
+ * const {PreparedStatement: PS} = require('pg-promise');
+ *
+ * // Creating a complete Prepared Statement with parameters:
+ * const findUser = new PS({name: 'find-user', text: 'SELECT * FROM Users WHERE id = $1', values: [123]});
+ *
+ * db.one(findUser)
+ *     .then(user => {
+ *         // user found;
+ *     })
+ *     .catch(error => {
+ *         // error;
+ *     });
+ *
+ * @example
+ *
+ * const {PreparedStatement: PS} = require('pg-promise');
+ *
+ * // Creating a reusable Prepared Statement without values:
+ * const addUser = new PS({name: 'add-user', text: '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 PreparedStatement extends ServerFormatting {
+    constructor(options) {
+        options = assert(options, ['name', 'text', 'values', 'binary', 'rowMode', 'rows', 'types']);
+        super(options);
+    }
+
+    /**
+     * @name PreparedStatement#name
+     * @type {string}
+     * @description
+     * An arbitrary name given to this particular prepared statement. It must be unique within a single session and is
+     * subsequently used to execute or deallocate a previously prepared statement.
+     */
+    get name() {
+        return this._inner.options.name;
+    }
+
+    set name(value) {
+        const _i = this._inner;
+        if (value !== _i.options.name) {
+            _i.options.name = value;
+            _i.changed = true;
+        }
+    }
+
+    /**
+     * @name PreparedStatement#rows
+     * @type {number}
+     * @description
+     * Number of rows to return at a time from a Prepared Statement's portal.
+     * The default is 0, which means that all rows must be returned at once.
+     */
+    get rows() {
+        return this._inner.options.rows;
+    }
+
+    set rows(value) {
+        const _i = this._inner;
+        if (value !== _i.options.rows) {
+            _i.options.rows = value;
+            _i.changed = true;
+        }
+    }
+}
+
+/**
+ * @method PreparedStatement#parse
+ * @description
+ * Parses the current object and returns a simple `{name, text, values}`, if successful,
+ * or else it returns a {@link errors.PreparedStatementError PreparedStatementError} object.
+ *
+ * This method is primarily for internal use by the library.
+ *
+ * @returns {{name, text, values}|errors.PreparedStatementError}
+ */
+PreparedStatement.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 = {
+        name: options.name,
+        text: options.text
+    };
+    _i.changed = true;
+    _i.currentError = undefined;
+
+    if (!npm.utils.isText(_i.target.name)) {
+        errors.push('Property \'name\' must be a non-empty text string.');
+    }
+
+    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.rows !== undefined) {
+        _i.target.rows = options.rows;
+    }
+
+    if (options.types !== undefined) {
+        _i.target.types = options.types;
+    }
+
+    if (errors.length) {
+        return _i.currentError = new PreparedStatementError(errors[0], _i.target);
+    }
+
+    _i.changed = false;
+
+    return _i.target;
+};
+
+npm.utils.addInspection(PreparedStatement, function () {
+    const pq = this.parse();
+    const obj = {
+        name: this.name
+    };
+    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.rows !== undefined) {
+        obj.rows = this.rows;
+    }
+    if (this.error !== undefined) {
+        obj.error = this.error.message;
+    }
+    return 'PreparedStatement ' + npm.inspect(obj, {breakLength: 100, depth: 5, colors: true});
+});
+
+module.exports = {PreparedStatement};
+
+/**
+ * @name PreparedStatement#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 $[Prepared Statements]
+ * are formatted on the server side.
+ *
+ * Changing this property for the same {@link PreparedStatement#name name} will have no effect, because queries
+ * for Prepared Statements are cached by the server, with {@link PreparedStatement#name name} being the cache key.
+ */
+
+/**
+ * @name PreparedStatement#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 PreparedStatement#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 PreparedStatement#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 PreparedStatement#types
+ * @type {ITypes}
+ * @default undefined
+ * @description
+ * Custom type parsers just for this query result.
+ */
+
+/**
+ * @name PreparedStatement#error
+ * @type {errors.PreparedStatementError}
+ * @default undefined
+ * @description
+ * When in an error state, it is set to a {@link errors.PreparedStatementError PreparedStatementError} object. Otherwise, it is `undefined`.
+ *
+ * This property is primarily for internal use by the library.
+ */

package/lib/types/server-formatting.js

@@ -0,0 +1,92 @@
+const {InnerState} = require('../inner-state');
+const utils = require('../utils');
+
+/**
+ * @private
+ * @class ServerFormatting
+ */
+class ServerFormatting extends InnerState {
+
+    constructor(options) {
+        const _inner = {
+            options,
+            changed: true,
+            currentError: undefined,
+            target: {}
+        };
+        super(_inner);
+        setValues.call(this, options.values);
+    }
+
+    get error() {
+        return this._inner.currentError;
+    }
+
+    get text() {
+        return this._inner.options.text;
+    }
+
+    set text(value) {
+        const _i = this._inner;
+        if (value !== _i.options.text) {
+            _i.options.text = value;
+            _i.changed = true;
+        }
+    }
+
+    get binary() {
+        return this._inner.options.binary;
+    }
+
+    set binary(value) {
+        const _i = this._inner;
+        if (value !== _i.options.binary) {
+            _i.options.binary = value;
+            _i.changed = true;
+        }
+    }
+
+    get rowMode() {
+        return this._inner.options.rowMode;
+    }
+
+    set rowMode(value) {
+        const _i = this._inner;
+        if (value !== _i.options.rowMode) {
+            _i.options.rowMode = value;
+            _i.changed = true;
+        }
+    }
+
+    get values() {
+        return this._inner.target.values;
+    }
+
+    set values(values) {
+        setValues.call(this, values);
+    }
+
+}
+
+/**
+ * @member ServerFormatting#parse
+ */
+
+function setValues(v) {
+    const target = this._inner.target;
+    if (Array.isArray(v)) {
+        if (v.length) {
+            target.values = v;
+        } else {
+            delete target.values;
+        }
+    } else {
+        if (utils.isNull(v)) {
+            delete target.values;
+        } else {
+            target.values = [v];
+        }
+    }
+}
+
+module.exports = {ServerFormatting};

package/lib/utils/README.md

@@ -0,0 +1,13 @@
+### `utils` namespace
+
+This folder contains everything that's available via the [utils] namespace, before and after initialization:
+
+```js
+const pgpLib = require('pg-promise');
+const pgp = pgpLib(/*initialization options*/);
+
+pgpLib.utils; // `utils` namespace
+pgp.utils; // `utils` namespace
+```
+
+[utils]:http://vitaly-t.github.io/pg-promise/utils.html

package/lib/utils/color.js

@@ -0,0 +1,68 @@
+const {format} = require('util');
+
+class ColorConsole {
+
+    static log() {
+        ColorConsole.writeNormal([...arguments], 39); // white
+    }
+
+    static info() {
+        ColorConsole.writeNormal([...arguments], 36); // cyan
+    }
+
+    static success() {
+        ColorConsole.writeNormal([...arguments], 32); // green
+    }
+
+    static warn() {
+        ColorConsole.writeNormal([...arguments], 33); // yellow
+    }
+
+    static error() {
+        ColorConsole.writeError([...arguments], 31); // red
+    }
+
+    static writeNormal(params, color) {
+        // istanbul ignore else
+        if (process.stdout.isTTY) {
+            console.log.apply(null, ColorConsole.formatColor(params, color)); // eslint-disable-line no-console
+        } else {
+            console.log.apply(null, params); // eslint-disable-line no-console
+        }
+    }
+
+    static writeError(params, color) {
+        // istanbul ignore else
+        if (process.stderr.isTTY) {
+            console.error.apply(null, ColorConsole.formatColor(params, color)); // eslint-disable-line no-console
+        } else {
+            console.error.apply(null, params); // eslint-disable-line no-console
+        }
+    }
+
+    static formatColor(args, color) {
+        return args.map(a => `\x1b[${color}m${format(a)}\x1b[0m`);
+    }
+}
+
+ColorConsole.log.bright = function () {
+    ColorConsole.writeNormal([...arguments], 97); // light white
+};
+
+ColorConsole.info.bright = function () {
+    ColorConsole.writeNormal([...arguments], 93); // light cyan
+};
+
+ColorConsole.success.bright = function () {
+    ColorConsole.writeNormal([...arguments], 92); // light green
+};
+
+ColorConsole.warn.bright = function () {
+    ColorConsole.writeNormal([...arguments], 93); // light yellow
+};
+
+ColorConsole.error.bright = function () {
+    ColorConsole.writeError([...arguments], 91); // light red
+};
+
+module.exports = {ColorConsole};

package/lib/utils/index.js

@@ -0,0 +1,199 @@
+/*
+ * 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 npm = {
+    path: require('path'),
+    util: require('util'),
+    patterns: require('../patterns')
+};
+
+////////////////////////////////////////////
+// Simpler check for null/undefined;
+function isNull(value) {
+    return value === null || value === undefined;
+}
+
+////////////////////////////////////////////////////////
+// Verifies parameter for being a non-empty text string;
+function isText(txt) {
+    return txt && typeof txt === 'string' && /\S/.test(txt);
+}
+
+///////////////////////////////////////////////////////////
+// Approximates the environment as being for development.
+//
+// Proper configuration is having NODE_ENV = 'development', but this
+// method only checks for 'dev' being present, and regardless of the case.
+function isDev() {
+    const env = process.env.NODE_ENV || '';
+    return env.toLowerCase().indexOf('dev') !== -1;
+}
+
+/////////////////////////////////////////////
+// Adds properties from source to the target,
+// making them read-only and enumerable.
+function addReadProperties(target, source) {
+    for (const p in source) {
+        addReadProp(target, p, source[p]);
+    }
+}
+
+///////////////////////////////////////////////////////
+// Adds a read-only, non-deletable enumerable property.
+function addReadProp(obj, name, value, hidden) {
+    Object.defineProperty(obj, name, {
+        value,
+        configurable: false,
+        enumerable: !hidden,
+        writable: false
+    });
+}
+
+//////////////////////////////////////////////////////////////
+// Converts a connection string or object into its safe copy:
+// if a password is present, it is masked with the symbol '#'.
+function getSafeConnection(cn) {
+    const maskPassword = cs => cs.replace(/:(?![/])([^@]+)/, (_, m) => ':' + new Array(m.length + 1).join('#'));
+    if (typeof cn === 'object') {
+        const copy = {...cn};
+        if (typeof copy.password === 'string') {
+            copy.password = copy.password.replace(/./g, '#');
+        }
+        if (typeof copy.connectionString === 'string') {
+            copy.connectionString = maskPassword(copy.connectionString);
+        }
+        return copy;
+    }
+    return maskPassword(cn);
+}
+
+/////////////////////////////////////////
+// Provides platform-neutral inheritance;
+function inherits(child, parent) {
+    child.prototype.__proto__ = parent.prototype;
+}
+
+// istanbul ignore next
+function getLocalStack(startIdx, maxLines) {
+    // from the call stack, we take up to maximum lines,
+    // starting with the specified line index:
+    startIdx = startIdx || 0;
+    const endIdx = maxLines > 0 ? startIdx + maxLines : undefined;
+    return new Error().stack
+        .split('\n')
+        .filter(line => line.match(/\(.+\)/))
+        .slice(startIdx, endIdx)
+        .join('\n');
+}
+
+//////////////////////////////
+// Internal error container;
+function InternalError(error) {
+    this.error = error;
+}
+
+/////////////////////////////////////////////////////////////////
+// Parses a property name and gets its name from the object
+// if the property exists. Returns an object {valid, has, target, value}:
+//  - valid - true/false, whether the syntax is valid
+//  - has - a flag that property exists; set when 'valid' = true
+//  - target - the target object that contains the property; set when 'has' = true
+//  - value - the value; set when 'has' = true
+function getIfHas(obj, prop) {
+    const result = {valid: true};
+    if (prop.indexOf('.') === -1) {
+        result.has = prop in obj;
+        result.target = obj;
+        if (result.has) {
+            result.value = obj[prop];
+        }
+    } else {
+        const names = prop.split('.');
+        let missing, target;
+        for (let i = 0; i < names.length; i++) {
+            const n = names[i];
+            if (!n) {
+                result.valid = false;
+                return result;
+            }
+            if (!missing && hasProperty(obj, n)) {
+                target = obj;
+                obj = obj[n];
+            } else {
+                missing = true;
+            }
+        }
+        result.has = !missing;
+        if (result.has) {
+            result.target = target;
+            result.value = obj;
+        }
+    }
+    return result;
+}
+
+/////////////////////////////////////////////////////////////////////////
+// Checks if the property exists in the object or value or its prototype;
+function hasProperty(value, prop) {
+    return (value && typeof value === 'object' && prop in value) ||
+        value !== null && value !== undefined && value[prop] !== undefined;
+}
+
+////////////////////////////////////////////////////////
+// Adds prototype inspection
+function addInspection(type, cb) {
+    type.prototype[npm.util.inspect.custom] = cb;
+}
+
+/////////////////////////////////////////////////////////////////////////////////////////
+// Identifies a general connectivity error, after which no more queries can be executed.
+// This is for detecting when to skip executing ROLLBACK for a failed transaction.
+function isConnectivityError(err) {
+    const code = err && typeof err.code === 'string' && err.code;
+    const cls = code && code.substring(0, 2); // Error Class
+    // istanbul ignore next (we cannot test-cover all error cases):
+    return code === 'ECONNRESET' || (cls === '08' && code !== '08P01') || (cls === '57' && code !== '57014');
+    // Code 'ECONNRESET' - Connectivity issue handled by the driver.
+    // Class 08 - Connection Exception (except for 08P01, for protocol violation).
+    // Class 57 - Operator Intervention (except for 57014, for cancelled queries).
+    //
+    // ERROR CODES: https://www.postgresql.org/docs/17/errcodes-appendix.html
+}
+
+///////////////////////////////////////////////////////////////
+// Does JSON.stringify, with support for BigInt (irreversible)
+function toJson(data) {
+    if (data !== undefined) {
+        return JSON.stringify(data, (_, v) => typeof v === 'bigint' ? `${v}#bigint` : v)
+            .replace(/"(-?\d+)#bigint"/g, (_, a) => a);
+    }
+}
+
+const exp = {
+    toJson,
+    getIfHas,
+    addInspection,
+    InternalError,
+    getLocalStack,
+    isText,
+    isNull,
+    isDev,
+    addReadProp,
+    addReadProperties,
+    getSafeConnection,
+    inherits,
+    isConnectivityError
+};
+
+const mainFile = process.argv[1];
+
+// istanbul ignore next
+exp.startDir = mainFile ? npm.path.dirname(mainFile) : process.cwd();
+
+module.exports = exp;