@depup/pg-promise 12.6.2-depup.0

package/lib/helpers/table-name.js

@@ -0,0 +1,175 @@
+/*
+ * 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 {assert} = require('../assert');
+
+const npm = {
+    utils: require('../utils'),
+    format: require('../formatting').as // formatting namespace
+};
+
+/**
+ * @class helpers.TableName
+ * @description
+ * Represents a full table name that can be injected into queries directly.
+ *
+ * This is a read-only type that can be used wherever parameter `table` is supported.
+ *
+ * It supports $[Custom Type Formatting], which means you can use the type directly as a formatting
+ * parameter, without specifying any escaping.
+ *
+ * Filter `:alias` is an alternative approach to splitting an SQL name into multiple ones.
+ *
+ * @param {string|Table} table
+ * Table name details, depending on the type:
+ *
+ * - table name, if `table` is a string
+ * - {@link Table} object
+ *
+ * @property {string} name
+ * Escaped full table name, combining `schema` + `table`.
+ *
+ * @property {string} table
+ * Table name.
+ *
+ * @property {string} schema
+ * Database schema name.
+ *
+ * It is `undefined` when no valid schema was specified.
+ *
+ * @returns {helpers.TableName}
+ *
+ * @see
+ * {@link helpers._TN _TN},
+ * {@link helpers.TableName#toPostgres toPostgres}
+ *
+ * @example
+ *
+ * const table = new pgp.helpers.TableName({table: 'my-table', schema: 'my-schema'});
+ * console.log(table);
+ * //=> "my-schema"."my-table"
+ *
+ * // Formatting the type directly:
+ * pgp.as.format('SELECT * FROM $1', table);
+ * //=> SELECT * FROM "my-schema"."my-table"
+ *
+ */
+class TableName {
+
+    constructor(table) {
+        if (typeof table === 'string') {
+            this.table = table;
+        } else {
+            const config = assert(table, ['table', 'schema']);
+            this.table = config.table;
+            if (npm.utils.isText(config.schema)) {
+                this.schema = config.schema;
+            }
+        }
+        if (!npm.utils.isText(this.table)) {
+            throw new TypeError('Table name must be a non-empty text string.');
+        }
+        this.name = npm.format.name(this.table);
+        if (this.schema) {
+            this.name = npm.format.name(this.schema) + '.' + this.name;
+        }
+        Object.freeze(this);
+    }
+}
+
+/**
+ * @method helpers.TableName#toPostgres
+ * @description
+ * $[Custom Type Formatting], based on $[Symbolic CTF], i.e. the actual method is available only via {@link external:Symbol Symbol}:
+ *
+ * ```js
+ * const {toPostgres} = pgp.as.ctf; // Custom Type Formatting symbols namespace
+ * const fullName = tn[toPostgres]; // tn = an object of type TableName
+ * ```
+ *
+ * This is a raw formatting type (`rawType = true`), i.e. when used as a query-formatting parameter, type `TableName`
+ * injects full table name as raw text.
+ *
+ * @param {helpers.TableName} [self]
+ * Optional self-reference, for ES6 arrow functions.
+ *
+ * @returns {string}
+ * Escaped full table name that includes optional schema name, if specified.
+ */
+TableName.prototype[npm.format.ctf.toPostgres] = function (self) {
+    self = this instanceof TableName && this || self;
+    return self.name;
+};
+
+TableName.prototype[npm.format.ctf.rawType] = true; // use as pre-formatted
+
+/**
+ * @method helpers.TableName#toString
+ * @description
+ * Redirects into `name` property, for a fully escaped table name.
+ *
+ * @returns {string}
+ */
+TableName.prototype.toString = function () {
+    return this.name;
+};
+
+/**
+ * @interface Table
+ * @description
+ * Structure for any table name/path.
+ *
+ * Function {@link helpers._TN _TN} can help you construct it from a string.
+ *
+ * @property {string} [schema] - schema name, if specified
+ * @property {string} table - table name
+ *
+ * @see {@link helpers.TableName TableName}, {@link helpers._TN _TN}
+ */
+
+/**
+ * @external TemplateStringsArray
+ * @see https://microsoft.github.io/PowerBI-JavaScript/interfaces/_node_modules_typedoc_node_modules_typescript_lib_lib_es5_d_.templatestringsarray.html
+ */
+
+/**
+ * @function helpers._TN
+ * @description
+ * Table-Name helper function, to convert any `"schema.table"` string
+ * into `{schema, table}` object. It also works as a template-tag function.
+ *
+ * @param {string|TemplateStringsArray} path
+ * Table-name path, as a simple string or a template string (with parameters).
+ *
+ * @example
+ * const {ColumnSet, _TN} = pgp.helpers;
+ *
+ * // Using as a regular function:
+ * const cs1 = new ColumnSet(['id', 'name'], {table: _TN('schema.table')});
+ *
+ * // Using as a template-tag function:
+ * const schema = 'schema';
+ * const cs2 = new ColumnSet(['id', 'name'], {table: _TN`${schema}.table`});
+ *
+ * @returns {Table}
+ *
+ * @see {@link helpers.TableName TableName}, {@link external:TemplateStringsArray TemplateStringsArray}
+ */
+function _TN(path, ...args) {
+    if (Array.isArray(path)) {
+        path = path.reduce((a, c, i) => a + c + (args[i] ?? ''), '');
+    } // else 'path' is a string
+    const [schema, table] = path.split('.');
+    if (table === undefined) {
+        return {table: schema};
+    }
+    return schema ? {schema, table} : {table};
+}
+
+module.exports = {TableName, _TN};

package/lib/index.js

@@ -0,0 +1,29 @@
+/*
+ * 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.
+ */
+
+/* eslint no-var: off */
+var v = process.versions.node.split('.'),
+    highVer = +v[0];
+
+// istanbul ignore next
+if (highVer < 16) {
+
+    // From pg-promise v11.15.0, the oldest supported Node.js is v16.0.0
+
+    // Node.js v14.x was supported up to pg-promise v11.14.0
+    // Node.js v12.x was supported up to pg-promise v10.15.4
+    // Node.js v8.x was supported up to pg-promise v10.14.2
+    // Node.js v7.6.0 was supported up to pg-promise v10.3.5
+    // Node.js v4.5.0 was supported up to pg-promise v8.7.5
+    // Node.js v0.10 was supported up to pg-promise v5.5.8
+
+    throw new Error('Minimum Node.js version supported by pg-promise is 16.0.0');
+}
+
+module.exports = require('./main');

package/lib/inner-state.js

@@ -0,0 +1,39 @@
+const {addReadProp} = require('./utils');
+
+/**
+ * @private
+ * @class InnerState
+ * @description
+ * Implements support for private/inner state object inside the class,
+ * which can be accessed by a derived class via hidden read-only property _inner.
+ */
+class InnerState {
+
+    constructor(initialState) {
+        addReadProp(this, '_inner', {}, true);
+        if (initialState && typeof initialState === 'object') {
+            this.extendState(initialState);
+        }
+    }
+
+    /**
+     * Extends or overrides inner state with the specified properties.
+     *
+     * Only own properties are used, i.e. inherited ones are skipped.
+     */
+    extendState(state) {
+        for (const a in state) {
+            // istanbul ignore else
+            if (Object.prototype.hasOwnProperty.call(state, a)) {
+                this._inner[a] = state[a];
+            }
+        }
+    }
+}
+
+/**
+ * @member InnerState#_inner
+ * Private/Inner object state.
+ */
+
+module.exports = {InnerState};

package/lib/main.js

@@ -0,0 +1,394 @@
+/*
+ * 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 {DatabasePool} = require('./database-pool');
+const {PreparedStatement, ParameterizedQuery} = require('./types');
+const {QueryFile} = require('./query-file');
+const {queryResult} = require('./query-result');
+const {assert} = require('./assert');
+
+const npm = {
+    path: require('path'),
+    pg: require('pg'),
+    minify: require('pg-minify'),
+    formatting: require('./formatting'),
+    helpers: require('./helpers'),
+    errors: require('./errors'),
+    utils: require('./utils'),
+    pubUtils: require('./utils/public'),
+    mode: require('./tx-mode'),
+    package: require('../package.json'),
+    text: require('./text')
+};
+
+let originalClientConnect;
+
+/**
+ * @author Vitaly Tomilov
+ * @module pg-promise
+ *
+ * @description
+ * ## pg-promise v12.5
+ * All documentation here is for the latest official release only.
+ *
+ * ### Initialization Options
+ *
+ * Below is the complete list of _Initialization Options_ for the library that can be passed in during
+ * the library's initialization:
+ *
+ * ```js
+ * const initOptions = {/* options as documented below */};
+ *
+ * const pgp = require('pg-promise')(initOptions);
+ * ```
+ *
+ * @property {{}} [options]
+ * Library Initialization Options.
+ *
+ * @property {boolean} [options.pgFormatting=false]
+ * Redirects all query formatting to the $[pg] driver.
+ *
+ * By default (`false`), the library uses its own advanced query-formatting engine.
+ * If you set this option to a truthy value, query formatting will be done entirely by the
+ * $[pg] driver, which means you won't be able to use any of the feature-rich query formatting
+ * that this library implements, restricting yourself to the very basic `$1, $2,...` syntax.
+ *
+ * This option is dynamic (can be set before or after initialization).
+ *
+ * @property {boolean} [options.pgNative=false]
+ * Use $[Native Bindings]. Library $[pg-native] must be included and installed independently, or else there will
+ * be an error thrown: {@link external:Error Error} = `Failed to initialize Native Bindings.`
+ *
+ * This is a static option (can only be set prior to initialization).
+ *
+ * @property {boolean} [options.capSQL=false]
+ * Capitalizes any SQL generated by the library.
+ *
+ * By default, all internal SQL within the library is generated using the low case.
+ * If, however, you want all SQL to be capitalized instead, set `capSQL` = `true`.
+ *
+ * It is purely a cosmetic feature.
+ *
+ * This option is dynamic (can be set before or after initialization).
+ *
+ * @property {string|Array<string>|null|undefined|function} [options.schema]
+ * Forces change of the default database schema(s) for every fresh connection, i.e.
+ * the library will execute `SET search_path TO schema_1, schema_2, ...` in the background
+ * whenever a fresh physical connection is allocated.
+ *
+ * Normally, one changes the default schema(s) by $[changing the database or the role], but sometimes you
+ * may want to switch the default schema(s) without persisting the change, and then use this option.
+ *
+ * It can be a string, an array of strings, or a callback function that takes `dc` (database context)
+ * as the only parameter (and as `this`), and returns schema(s) according to the database context. A callback function
+ * can also return nothing (`undefined` or `null`), if no schema change needed for the specified database context.
+ *
+ * The order of schema names matters, so if a table name exists in more than one schema, its default access resolves
+ * to the table from the first such schema on the list.
+ *
+ * This option is dynamic (can be set before or after initialization).
+ *
+ * @property {boolean} [options.noWarnings=false]
+ * Disables all diagnostic warnings in the library (it is ill-advised).
+ *
+ * This option is dynamic (can be set before or after initialization).
+ *
+ * @property {function} [options.connect]
+ * Global event {@link event:connect connect} handler.
+ *
+ * This option is dynamic (can be set before or after initialization).
+ *
+ * @property {function} [options.disconnect]
+ * Global event {@link event:disconnect disconnect} handler.
+ *
+ * This option is dynamic (can be set before or after initialization).
+ *
+ * @property {function} [options.query]
+ * Global event {@link event:query query} handler.
+ *
+ * This option is dynamic (can be set before or after initialization).
+ *
+ * @property {function} [options.receive]
+ * Global event {@link event:receive receive} handler.
+ *
+ * This option is dynamic (can be set before or after initialization).
+ *
+ * @property {function} [options.task]
+ * Global event {@link event:task task} handler.
+ *
+ * This option is dynamic (can be set before or after initialization).
+ *
+ * @property {function} [options.transact]
+ * Global event {@link event:transact transact} handler.
+ *
+ * This option is dynamic (can be set before or after initialization).
+ *
+ * @property {function} [options.error]
+ * Global event {@link event:error error} handler.
+ *
+ * This option is dynamic (can be set before or after initialization).
+ *
+ * @property {function} [options.extend]
+ * Global event {@link event:extend extend} handler.
+ *
+ * This option is dynamic (can be set before or after initialization).
+ *
+ * @see
+ * {@link module:pg-promise~end end},
+ * {@link module:pg-promise~as as},
+ * {@link module:pg-promise~errors errors},
+ * {@link module:pg-promise~helpers helpers},
+ * {@link module:pg-promise~minify minify},
+ * {@link module:pg-promise~ParameterizedQuery ParameterizedQuery},
+ * {@link module:pg-promise~PreparedStatement PreparedStatement},
+ * {@link module:pg-promise~pg pg},
+ * {@link module:pg-promise~QueryFile QueryFile},
+ * {@link module:pg-promise~queryResult queryResult},
+ * {@link module:pg-promise~spex spex},
+ * {@link module:pg-promise~txMode txMode},
+ * {@link module:pg-promise~utils utils}
+ *
+ */
+function $main(options) {
+
+    options = assert(options, ['pgFormatting', 'pgNative', 'capSQL', 'noWarnings',
+        'connect', 'disconnect', 'query', 'receive', 'task', 'transact', 'error', 'extend', 'schema']);
+
+    let pg = npm.pg;
+
+    const config = {
+        version: npm.package.version
+    };
+
+    npm.utils.addReadProp(config, '$npm', {}, true);
+
+    // Locking properties that cannot be changed later:
+    npm.utils.addReadProp(options, 'pgNative', !!options.pgNative);
+
+    config.options = options;
+
+    // istanbul ignore next:
+    // we do not cover code specific to Native Bindings
+    if (options.pgNative) {
+        pg = npm.pg.native;
+        if (npm.utils.isNull(pg)) {
+            throw new Error(npm.text.nativeError);
+        }
+    } else {
+        if (!originalClientConnect) {
+            originalClientConnect = pg.Client.prototype.connect;
+            pg.Client.prototype.connect = function () {
+                const handler = msg => {
+                    if (msg.parameterName === 'server_version') {
+                        this.serverVersion = msg.parameterValue;
+                        this.connection.removeListener('parameterStatus', handler);
+                    }
+                };
+                this.connection.on('parameterStatus', handler);
+                return originalClientConnect.call(this, ...arguments);
+            };
+        }
+    }
+
+    const Database = require('./database')(config);
+
+    const inst = (cn, dc) => {
+        if (npm.utils.isText(cn) || (cn && typeof cn === 'object')) {
+            return new Database(cn, dc, config);
+        }
+        throw new TypeError('Invalid connection details: ' + npm.utils.toJson(cn));
+    };
+
+    npm.utils.addReadProperties(inst, rootNameSpace);
+
+    /**
+     * @member {external:PG} pg
+     * @description
+     * Instance of the $[pg] library being used, depending on initialization option `pgNative`:
+     *  - regular `pg` module instance, without option `pgNative`, or equal to `false` (default)
+     *  - `pg` module instance with $[Native Bindings], if option `pgNative` was set.
+     *
+     * Available as `pgp.pg`, after initializing the library.
+     */
+    inst.pg = pg; // keep it modifiable, so the protocol can be mocked
+
+    /**
+     * @member {function} end
+     * @readonly
+     * @description
+     * Shuts down all connection pools created in the process, so it can terminate without delay.
+     * It is available as `pgp.end`, after initializing the library.
+     *
+     * All {@link Database} objects created previously can no longer be used, and their query methods will be rejecting
+     * with {@link external:Error Error} = `Connection pool of the database object has been destroyed.`
+     *
+     * And if you want to shut down only a specific connection pool, you do so via the {@link Database}
+     * object that owns the pool: `db.$pool.end()` (see {@link Database#$pool Database.$pool}).
+     *
+     * For more details see $[Library de-initialization].
+     */
+    npm.utils.addReadProp(inst, 'end', () => {
+        DatabasePool.shutDown();
+    });
+
+    /**
+     * @member {helpers} helpers
+     * @readonly
+     * @description
+     * Namespace for {@link helpers all query-formatting helper functions}.
+     *
+     * Available as `pgp.helpers`, after initializing the library.
+     *
+     * @see {@link helpers}.
+     */
+    npm.utils.addReadProp(inst, 'helpers', npm.helpers(config));
+
+    /**
+     * @member {external:spex} spex
+     * @readonly
+     * @description
+     * Initialized instance of the $[spex] module, used by the library within tasks and transactions.
+     *
+     * Available as `pgp.spex`, after initializing the library.
+     *
+     * @see
+     * {@link Task#batch},
+     * {@link Task#page},
+     * {@link Task#sequence}
+     */
+    npm.utils.addReadProp(inst, 'spex', config.$npm.spex);
+
+    config.pgp = inst;
+
+    return inst;
+}
+
+const rootNameSpace = {
+
+    /**
+     * @member {formatting} as
+     * @readonly
+     * @description
+     * Namespace for {@link formatting all query-formatting functions}.
+     *
+     * Available as `pgp.as`, before and after initializing the library.
+     *
+     * @see {@link formatting}.
+     */
+    as: npm.formatting.as,
+
+    /**
+     * @member {external:pg-minify} minify
+     * @readonly
+     * @description
+     * Instance of the $[pg-minify] library used internally to minify SQL scripts.
+     *
+     * Available as `pgp.minify`, before and after initializing the library.
+     */
+    minify: npm.minify,
+
+    /**
+     * @member {queryResult} queryResult
+     * @readonly
+     * @description
+     * Query Result Mask enumerator.
+     *
+     * Available as `pgp.queryResult`, before and after initializing the library.
+     */
+    queryResult,
+
+    /**
+     * @member {ParameterizedQuery} ParameterizedQuery
+     * @readonly
+     * @description
+     * {@link ParameterizedQuery} class.
+     *
+     * Available as `pgp.ParameterizedQuery`, before and after initializing the library.
+     */
+    ParameterizedQuery,
+
+    /**
+     * @member {PreparedStatement} PreparedStatement
+     * @readonly
+     * @description
+     * {@link PreparedStatement} class.
+     *
+     * Available as `pgp.PreparedStatement`, before and after initializing the library.
+     */
+    PreparedStatement,
+
+    /**
+     * @member {QueryFile} QueryFile
+     * @readonly
+     * @description
+     * {@link QueryFile} class.
+     *
+     * Available as `pgp.QueryFile`, before and after initializing the library.
+     */
+    QueryFile,
+
+    /**
+     * @member {errors} errors
+     * @readonly
+     * @description
+     * {@link errors} - namespace for all error types.
+     *
+     * Available as `pgp.errors`, before and after initializing the library.
+     */
+    errors: npm.errors,
+
+    /**
+     * @member {utils} utils
+     * @readonly
+     * @description
+     * {@link utils} - namespace for utility functions.
+     *
+     * Available as `pgp.utils`, before and after initializing the library.
+     */
+    utils: npm.pubUtils,
+
+    /**
+     * @member {txMode} txMode
+     * @readonly
+     * @description
+     * {@link txMode Transaction Mode} namespace.
+     *
+     * Available as `pgp.txMode`, before and after initializing the library.
+     */
+    txMode: npm.mode
+};
+
+npm.utils.addReadProperties($main, rootNameSpace);
+
+module.exports = $main;
+
+/**
+ * @external Promise
+ * @see https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Promise
+ */
+
+/**
+ * @external PG
+ * @see https://node-postgres.com
+ */
+
+/**
+ * @external Client
+ * @see https://node-postgres.com/apis/client
+ */
+
+/**
+ * @external pg-minify
+ * @see https://github.com/vitaly-t/pg-minify
+ */
+
+/**
+ * @external spex
+ * @see https://github.com/vitaly-t/spex
+ */

package/lib/patterns.js

@@ -0,0 +1,43 @@
+/*
+ * 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.
+ */
+
+/*
+  The most important regular expressions and data as used by the library,
+  isolated here to help with possible edge cases during integration.
+*/
+
+module.exports = {
+    // Searches for all Named Parameters, supporting any of the following syntax:
+    // ${propName}, $(propName), $[propName], $/propName/, $<propName>
+    // Nested property names are also supported: ${propName.abc}
+    namedParameters: /\$(?:({)|(\()|(<)|(\[)|(\/))\s*[a-zA-Z0-9$_.]+(\^|~|#|:raw|:alias|:name|:json|:csv|:list|:value)?\s*(?:(?=\2)(?=\3)(?=\4)(?=\5)}|(?=\1)(?=\3)(?=\4)(?=\5)\)|(?=\1)(?=\2)(?=\4)(?=\5)>|(?=\1)(?=\2)(?=\3)(?=\5)]|(?=\1)(?=\2)(?=\3)(?=\4)\/)/g,
+
+    // Searches for all variables $1, $2, ...$100000, and while it will find greater than $100000
+    // variables, the formatting engine is expected to throw an error for those.
+    multipleValues: /\$([1-9][0-9]{0,16}(?![0-9])(\^|~|#|:raw|:alias|:name|:json|:csv|:list|:value)?)/g,
+
+    // Searches for all occurrences of variable $1
+    singleValue: /\$1(?![0-9])(\^|~|#|:raw|:alias|:name|:json|:csv|:list|:value)?/g,
+
+    // Matches a valid column name for the Column type parser, according to the following rules:
+    // - can contain: any combination of a-z, A-Z, 0-9, $ or _
+    // - can contain ? at the start
+    // - can contain one of the supported filters/modifiers
+    validColumn: /\??[a-zA-Z0-9$_]+(\^|~|#|:raw|:alias|:name|:json|:csv|:list|:value)?/,
+
+    // Matches a valid open-name JavaScript variable, according to the following rules:
+    // - can contain: any combination of a-z, A-Z, 0-9, $ or _
+    validVariable: /[a-zA-Z0-9$_]+/,
+
+    // Matches a valid modifier in a column/property:
+    hasValidModifier: /\^|~|#|:raw|:alias|:name|:json|:csv|:list|:value/,
+
+    // List of all supported formatting modifiers:
+    validModifiers: ['^', '~', '#', ':raw', ':alias', ':name', ':json', ':csv', ':list', ':value']
+};