@depup/pg-promise 12.6.2-depup.0

package/lib/helpers/column.js

@@ -0,0 +1,406 @@
+/*
+ * 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 = {
+    os: require('os'),
+    utils: require('../utils'),
+    formatting: require('../formatting'),
+    patterns: require('../patterns')
+};
+
+/**
+ *
+ * @class helpers.Column
+ * @description
+ *
+ * Read-only structure with details for a single column. Used primarily by {@link helpers.ColumnSet ColumnSet}.
+ *
+ * The class parses details into a template, to be used for query generation.
+ *
+ * @param {string|helpers.ColumnConfig} col
+ * Column details, depending on the type.
+ *
+ * When it is a string, it is expected to contain a name for both the column and the source property, assuming that the two are the same.
+ * The name must adhere to JavaScript syntax for variable names. The name can be appended with any format modifier as supported by
+ * {@link formatting.format as.format} (`^`, `~`, `#`, `:csv`, `:list`, `:json`, `:alias`, `:name`, `:raw`, `:value`), which is then removed from the name and put
+ * into property `mod`. If the name starts with `?`, it is removed, while setting flag `cnd` = `true`.
+ *
+ * If the string doesn't adhere to the above requirements, the method will throw {@link external:TypeError TypeError} = `Invalid column syntax`.
+ *
+ * When `col` is a simple {@link helpers.ColumnConfig ColumnConfig}-like object, it is used as an input configurator to set all the properties
+ * of the class.
+ *
+ * @property {string} name
+ * Destination column name + source property name (if `prop` is skipped). The name must adhere to JavaScript syntax for variables,
+ * unless `prop` is specified, in which case `name` represents only the column name, and therefore can be any non-empty string.
+ *
+ * @property {string} [prop]
+ * Source property name, if different from the column's name. It must adhere to JavaScript syntax for variables.
+ *
+ * It is ignored when it is the same as `name`.
+ *
+ * @property {string} [mod]
+ * Formatting modifier, as supported by method {@link formatting.format as.format}: `^`, `~`, `#`, `:csv`, `:list`, `:json`, `:alias`, `:name`, `:raw`, `:value`.
+ *
+ * @property {string} [cast]
+ * Server-side type casting, without `::` in front.
+ *
+ * @property {boolean} [cnd]
+ * Conditional column flag.
+ *
+ * Used by methods {@link helpers.update update} and {@link helpers.sets sets}, ignored by methods {@link helpers.insert insert} and
+ * {@link helpers.values values}. It indicates that the column is reserved for a `WHERE` condition, not to be set or updated.
+ *
+ * It can be set from a string initialization, by adding `?` in front of the name.
+ *
+ * @property {*} [def]
+ * Default value for the property, to be used only when the source object doesn't have the property.
+ * It is ignored when property `init` is set.
+ *
+ * @property {helpers.initCB} [init]
+ * Override callback for the value.
+ *
+ * @property {helpers.skipCB} [skip]
+ * An override for skipping columns dynamically.
+ *
+ * Used by methods {@link helpers.update update} (for a single object) and {@link helpers.sets sets}, ignored by methods
+ * {@link helpers.insert insert} and {@link helpers.values values}.
+ *
+ * It is also ignored when conditional flag `cnd` is set.
+ *
+ * @returns {helpers.Column}
+ *
+ * @see
+ * {@link helpers.ColumnConfig ColumnConfig},
+ * {@link helpers.Column#castText castText},
+ * {@link helpers.Column#escapedName escapedName},
+ * {@link helpers.Column#variable variable}
+ *
+ * @example
+ *
+ * const pgp = require('pg-promise')({
+ *     capSQL: true // if you want all generated SQL capitalized
+ * });
+ *
+ * const {Column} = pgp.helpers;
+ *
+ * // creating a column from just a name:
+ * const col1 = new Column('colName');
+ * console.log(col1);
+ * //=>
+ * // Column {
+ * //    name: "colName"
+ * // }
+ *
+ * // creating a column from a name + modifier:
+ * const col2 = new Column('colName:csv');
+ * console.log(col2);
+ * //=>
+ * // Column {
+ * //    name: "colName"
+ * //    mod: ":csv"
+ * // }
+ *
+ * // creating a column from a configurator:
+ * const col3 = new Column({
+ *     name: 'colName', // required
+ *     prop: 'propName', // optional
+ *     mod: '^', // optional
+ *     def: 123 // optional
+ * });
+ * console.log(col3);
+ * //=>
+ * // Column {
+ * //    name: "colName"
+ * //    prop: "propName"
+ * //    mod: "^"
+ * //    def: 123
+ * // }
+ *
+ */
+class Column extends InnerState {
+
+    constructor(col) {
+        super();
+
+        if (typeof col === 'string') {
+            const info = parseColumn(col);
+            this.name = info.name;
+            if ('mod' in info) {
+                this.mod = info.mod;
+            }
+            if ('cnd' in info) {
+                this.cnd = info.cnd;
+            }
+        } else {
+            col = assert(col, ['name', 'prop', 'mod', 'cast', 'cnd', 'def', 'init', 'skip']);
+            if ('name' in col) {
+                if (!npm.utils.isText(col.name)) {
+                    throw new TypeError(`Invalid 'name' value: ${npm.utils.toJson(col.name)}. A non-empty string was expected.`);
+                }
+                if (npm.utils.isNull(col.prop) && !isValidVariable(col.name)) {
+                    throw new TypeError(`Invalid 'name' syntax: ${npm.utils.toJson(col.name)}.`);
+                }
+                this.name = col.name; // column name + property name (if 'prop' isn't specified)
+
+                if (!npm.utils.isNull(col.prop)) {
+                    if (!npm.utils.isText(col.prop)) {
+                        throw new TypeError(`Invalid 'prop' value: ${npm.utils.toJson(col.prop)}. A non-empty string was expected.`);
+                    }
+                    if (!isValidVariable(col.prop)) {
+                        throw new TypeError(`Invalid 'prop' syntax: ${npm.utils.toJson(col.prop)}.`);
+                    }
+                    if (col.prop !== col.name) {
+                        // optional property name, if different from the column's name;
+                        this.prop = col.prop;
+                    }
+                }
+                if (!npm.utils.isNull(col.mod)) {
+                    if (typeof col.mod !== 'string' || !isValidMod(col.mod)) {
+                        throw new TypeError(`Invalid 'mod' value: ${npm.utils.toJson(col.mod)}.`);
+                    }
+                    this.mod = col.mod; // optional format modifier;
+                }
+                if (!npm.utils.isNull(col.cast)) {
+                    this.cast = parseCast(col.cast); // optional SQL type casting
+                }
+                if ('cnd' in col) {
+                    this.cnd = !!col.cnd;
+                }
+                if ('def' in col) {
+                    this.def = col.def; // optional default
+                }
+                if (typeof col.init === 'function') {
+                    this.init = col.init; // optional value override (overrides 'def' also)
+                }
+                if (typeof col.skip === 'function') {
+                    this.skip = col.skip;
+                }
+            } else {
+                throw new TypeError('Invalid column details.');
+            }
+        }
+
+        const variable = '${' + (this.prop || this.name) + (this.mod || '') + '}';
+        const castText = this.cast ? ('::' + this.cast) : '';
+        const escapedName = npm.formatting.as.name(this.name);
+
+        this.extendState({variable, castText, escapedName});
+        Object.freeze(this);
+    }
+
+    /**
+     * @name helpers.Column#variable
+     * @type string
+     * @readonly
+     * @description
+     * Full-syntax formatting variable, ready for direct use in query templates.
+     *
+     * @example
+     *
+     * const cs = new ColumnSet([
+     *     'id',
+     *     'coordinate:json',
+     *     {
+     *         name: 'places',
+     *         mod: ':csv',
+     *         cast: 'int[]'
+     *     }
+     * ]);
+     *
+     * // cs.columns[0].variable = ${id}
+     * // cs.columns[1].variable = ${coordinate:json}
+     * // cs.columns[2].variable = ${places:csv}::int[]
+     */
+    get variable() {
+        return this._inner.variable;
+    }
+
+    /**
+     * @name helpers.Column#castText
+     * @type string
+     * @readonly
+     * @description
+     * Full-syntax sql type casting, if there is any, or else an empty string.
+     */
+    get castText() {
+        return this._inner.castText;
+    }
+
+    /**
+     * @name helpers.Column#escapedName
+     * @type string
+     * @readonly
+     * @description
+     * Escaped name of the column, ready to be injected into queries directly.
+     *
+     */
+    get escapedName() {
+        return this._inner.escapedName;
+    }
+
+}
+
+function parseCast(name) {
+    if (typeof name === 'string') {
+        const s = name.replace(/^[:\s]*|\s*$/g, '');
+        if (s) {
+            return s;
+        }
+    }
+    throw new TypeError(`Invalid 'cast' value: ${npm.utils.toJson(name)}.`);
+}
+
+function parseColumn(name) {
+    const m = name.match(npm.patterns.validColumn);
+    if (m && m[0] === name) {
+        const res = {};
+        if (name[0] === '?') {
+            res.cnd = true;
+            name = name.substring(1);
+        }
+        const mod = name.match(npm.patterns.hasValidModifier);
+        if (mod) {
+            res.name = name.substring(0, mod.index);
+            res.mod = mod[0];
+        } else {
+            res.name = name;
+        }
+        return res;
+    }
+    throw new TypeError(`Invalid column syntax: ${npm.utils.toJson(name)}.`);
+}
+
+function isValidMod(mod) {
+    return npm.patterns.validModifiers.indexOf(mod) !== -1;
+}
+
+function isValidVariable(name) {
+    const m = name.match(npm.patterns.validVariable);
+    return !!m && m[0] === name;
+}
+
+/**
+ * @typedef helpers.ColumnConfig
+ * @description
+ * A simple structure with column details, to be passed into the {@link helpers.Column Column} constructor for initialization.
+ *
+ * @property {string} name
+ * Destination column name + source property name (if `prop` is skipped). The name must adhere to JavaScript syntax for variables,
+ * unless `prop` is specified, in which case `name` represents only the column name, and therefore can be any non-empty string.
+ *
+ * @property {string} [prop]
+ * Source property name, if different from the column's name. It must adhere to JavaScript syntax for variables.
+ *
+ * It is ignored when it is the same as `name`.
+ *
+ * @property {string} [mod]
+ * Formatting modifier, as supported by method {@link formatting.format as.format}: `^`, `~`, `#`, `:csv`, `:list`, `:json`, `:alias`, `:name`, `:raw`, `:value`.
+ *
+ * @property {string} [cast]
+ * Server-side type casting. Leading `::` is allowed, but not needed (automatically removed when specified).
+ *
+ * @property {boolean} [cnd]
+ * Conditional column flag.
+ *
+ * Used by methods {@link helpers.update update} and {@link helpers.sets sets}, ignored by methods {@link helpers.insert insert} and
+ * {@link helpers.values values}. It indicates that the column is reserved for a `WHERE` condition, not to be set or updated.
+ *
+ * It can be set from a string initialization by adding `?` in front of the name.
+ *
+ * @property {*} [def]
+ * Default value for the property, to be used only when the source object doesn't have the property.
+ * It is ignored when property `init` is set.
+ *
+ * @property {helpers.initCB} [init]
+ * Override callback for the value.
+ *
+ * @property {helpers.skipCB} [skip]
+ * An override for skipping columns dynamically.
+ *
+ * Used by methods {@link helpers.update update} (for a single object) and {@link helpers.sets sets}, ignored by methods
+ * {@link helpers.insert insert} and {@link helpers.values values}.
+ *
+ * It is also ignored when the conditional flag `cnd` is set.
+ *
+ */
+
+/**
+ * @callback helpers.initCB
+ * @description
+ * A callback function type used by parameter `init` within {@link helpers.ColumnConfig ColumnConfig}.
+ *
+ * It works as an override for the corresponding property value in the `source` object.
+ *
+ * The function is called with `this` set to the `source` object.
+ *
+ * @param {*} col
+ * Column-to-property descriptor.
+ *
+ * @param {object} col.source
+ * The source object, equals to `this` that's passed into the function.
+ *
+ * @param {string} col.name
+ * Resolved name of the property within the `source` object, i.e. the value of `name` when `prop` is not used
+ * for the column, or the value of `prop` when it is specified.
+ *
+ * @param {*} col.value
+ *
+ * Property value, set to one of the following:
+ *
+ * - Value of the property within the `source` object (`value` = `source[name]`), if the property exists
+ * - If the property doesn't exist and `def` is set in the column, then `value` is set to the value of `def`
+ * - If the property doesn't exist and `def` is not set in the column, then `value` is set to `undefined`
+ *
+ * @param {boolean} col.exists
+ * Indicates whether the property exists in the `source` object (`exists = name in source`).
+ *
+ * @returns {*}
+ * The new value to be used for the corresponding column.
+ */
+
+/**
+ * @callback helpers.skipCB
+ * @description
+ * A callback function type used by parameter `skip` within {@link helpers.ColumnConfig ColumnConfig}.
+ *
+ * It is to dynamically determine when the property with specified `name` in the `source` object is to be skipped.
+ *
+ * The function is called with `this` set to the `source` object.
+ *
+ * @param {*} col
+ * Column-to-property descriptor.
+ *
+ * @param {object} col.source
+ * The source object, equals to `this` that's passed into the function.
+ *
+ * @param {string} col.name
+ * Resolved name of the property within the `source` object, i.e. the value of `name` when `prop` is not used
+ * for the column, or the value of `prop` when it is specified.
+ *
+ * @param {*} col.value
+ *
+ * Property value, set to one of the following:
+ *
+ * - Value of the property within the `source` object (`value` = `source[name]`), if the property exists
+ * - If the property doesn't exist and `def` is set in the column, then `value` is set to the value of `def`
+ * - If the property doesn't exist and `def` is not set in the column, then `value` is set to `undefined`
+ *
+ * @param {boolean} col.exists
+ * Indicates whether the property exists in the `source` object (`exists = name in source`).
+ *
+ * @returns {boolean}
+ * A truthy value that indicates whether the column is to be skipped.
+ *
+ */
+
+module.exports = {Column};

package/lib/helpers/index.js

@@ -0,0 +1,75 @@
+/*
+ * 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 {Column} = require('./column');
+const {ColumnSet} = require('./column-set');
+const {TableName, _TN} = require('./table-name');
+const method = require('./methods');
+
+/**
+ * @namespace helpers
+ * @description
+ * Namespace for query-formatting generators, available as {@link module:pg-promise~helpers pgp.helpers}, after initializing the library.
+ *
+ * It unifies the approach to generating multi-row `INSERT` / `UPDATE` queries with the single-row ones.
+ *
+ * See also: $[Performance Boost].
+ *
+ * @property {function} TableName
+ * {@link helpers.TableName TableName} class constructor.
+ *
+ * @property {function} _TN
+ * {@link helpers._TN _TN} Table-Name conversion function.
+ *
+ * @property {function} ColumnSet
+ * {@link helpers.ColumnSet ColumnSet} class constructor.
+ *
+ * @property {function} Column
+ * {@link helpers.Column Column} class constructor.
+ *
+ * @property {function} insert
+ * {@link helpers.insert insert} static method.
+ *
+ * @property {function} update
+ * {@link helpers.update update} static method.
+ *
+ * @property {function} values
+ * {@link helpers.values values} static method.
+ *
+ * @property {function} sets
+ * {@link helpers.sets sets} static method.
+ *
+ * @property {function} concat
+ * {@link helpers.concat concat} static method.
+ */
+module.exports = config => {
+    const capSQL = () => config.options && config.options.capSQL;
+    const res = {
+        insert(data, columns, table) {
+            return method.insert(data, columns, table, capSQL());
+        },
+        update(data, columns, table, options) {
+            return method.update(data, columns, table, options, capSQL());
+        },
+        concat(queries) {
+            return method.concat(queries, capSQL());
+        },
+        values(data, columns) {
+            return method.values(data, columns, capSQL());
+        },
+        sets(data, columns) {
+            return method.sets(data, columns, capSQL());
+        },
+        TableName,
+        _TN,
+        ColumnSet,
+        Column
+    };
+    return res;
+};

package/lib/helpers/methods/concat.js

@@ -0,0 +1,103 @@
+/*
+ * 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 {QueryFile} = require('../../query-file');
+
+const npm = {
+    formatting: require('../../formatting')
+};
+
+/**
+ * @method helpers.concat
+ * @description
+ * Formats and concatenates multiple queries into a single query string.
+ *
+ * Before joining the queries, the method does the following:
+ *  - Formats each query, if `values` are provided;
+ *  - Removes all leading and trailing spaces, tabs and semi-colons;
+ *  - Automatically skips all empty queries.
+ *
+ * @param {array<string|helpers.QueryFormat|QueryFile>} queries
+ * Array of mixed-type elements:
+ * - a simple query string, to be used as is
+ * - a {@link helpers.QueryFormat QueryFormat}-like object = `{query, [values], [options]}`
+ * - a {@link QueryFile} object
+ *
+ * @returns {string}
+ * Concatenated string with all queries.
+ *
+ * @example
+ *
+ * const pgp = require('pg-promise')();
+ *
+ * const qf1 = new pgp.QueryFile('./query1.sql', {minify: true});
+ * const qf2 = new pgp.QueryFile('./query2.sql', {minify: true});
+ *
+ * const query = pgp.helpers.concat([
+ *     {query: 'INSERT INTO Users(name, age) VALUES($1, $2)', values: ['John', 23]}, // QueryFormat-like object
+ *     {query: qf1, values: [1, 'Name']}, // QueryFile with formatting parameters
+ *     'SELECT count(*) FROM Users', // a simple-string query,
+ *     qf2 // direct QueryFile object
+ * ]);
+ *
+ * // query = concatenated string with all the queries
+ */
+function concat(queries, capSQL) {
+    if (!Array.isArray(queries)) {
+        throw new TypeError('Parameter \'queries\' must be an array.');
+    }
+    const fmOptions = {capSQL};
+    const all = queries.map((q, index) => {
+        if (typeof q === 'string') {
+            // a simple query string without parameters:
+            return clean(q);
+        }
+        if (q && typeof q === 'object') {
+            if (q instanceof QueryFile) {
+                // QueryFile object:
+                return clean(q[npm.formatting.as.ctf.toPostgres]());
+            }
+            if ('query' in q) {
+                // object {query, values, options}:
+                let opt = q.options && typeof q.options === 'object' ? q.options : {};
+                opt = opt.capSQL === undefined ? Object.assign(opt, fmOptions) : opt;
+                return clean(npm.formatting.as.format(q.query, q.values, opt));
+            }
+        }
+        throw new Error(`Invalid query element at index ${index}.`);
+    });
+
+    return all.filter(q => q).join(';');
+}
+
+function clean(q) {
+    // removes from the query all leading and trailing symbols ' ', '\t' and ';'
+    return q.replace(/^[\s;]*|[\s;]*$/g, '');
+}
+
+module.exports = {concat};
+
+/**
+ * @typedef helpers.QueryFormat
+ * @description
+ * A simple structure of parameters to be passed into method {@link formatting.format as.format} exactly as they are,
+ * used by {@link helpers.concat}.
+ *
+ * @property {string|value|object} query
+ * A query string or a value/object that implements $[Custom Type Formatting], to be formatted according to `values`.
+ *
+ * @property {array|object|value} [values]
+ * Query-formatting values.
+ *
+ * @property {object} [options]
+ * Query-formatting options, as supported by method {@link formatting.format as.format}.
+ *
+ * @see
+ * {@link formatting.format as.format}
+ */

package/lib/helpers/methods/index.js

@@ -0,0 +1,13 @@
+const {concat} = require('./concat');
+const {insert} = require('./insert');
+const {update} = require('./update');
+const {values} = require('./values');
+const {sets} = require('./sets');
+
+module.exports = {
+    concat,
+    insert,
+    update,
+    values,
+    sets
+};