@depup/pg-promise 12.6.2-depup.0

package/lib/query-file.js

@@ -0,0 +1,379 @@
+/*
+ * 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 {QueryFileError} = require('./errors');
+const {assert} = require('./assert');
+const {ColorConsole} = require('./utils/color');
+
+const npm = {
+    fs: require('fs'),
+    os: require('os'),
+    path: require('path'),
+    minify: require('pg-minify'),
+    utils: require('./utils'),
+    formatting: require('./formatting'),
+    inspect: require('util').inspect
+};
+
+const file$query = Symbol('QueryFile.query');
+
+/**
+ * @class QueryFile
+ * @description
+ *
+ * Represents an external SQL file. The type is available from the library's root: `pgp.QueryFile`.
+ *
+ * Reads a file with SQL and prepares it for execution, also parses and minifies it, if required.
+ * The SQL can be of any complexity, with both single and multi-line comments.
+ *
+ * The type can be used in place of the `query` parameter, with any query method directly, plus as `text` in {@link PreparedStatement}
+ * and {@link ParameterizedQuery}.
+ *
+ * It never throws any error, leaving it for query methods to reject with {@link errors.QueryFileError QueryFileError}.
+ *
+ * **IMPORTANT:** You should only create a single reusable object per file, in order to avoid repeated file reads,
+ * as the IO is a very expensive resource. If you do not follow it, you will be seeing the following warning:
+ * `Creating a duplicate QueryFile object for the same file`, which signals a bad-use pattern.
+ *
+ * @param {string} file
+ * Path to the SQL file with the query, either absolute or relative to the application's entry point file.
+ *
+ * If there is any problem reading the file, it will be reported when executing the query.
+ *
+ * @param {QueryFile.Options} [options]
+ * Set of configuration options, as documented by {@link QueryFile.Options}.
+ *
+ * @returns {QueryFile}
+ *
+ * @see
+ * {@link errors.QueryFileError QueryFileError},
+ * {@link QueryFile#toPostgres toPostgres}
+ *
+ * @example
+ * // File sql.js
+ *
+ * // Proper way to organize an sql provider:
+ * //
+ * // - have all sql files for Users in ./sql/users
+ * // - have all sql files for Products in ./sql/products
+ * // - have your sql provider module as ./sql/index.js
+ *
+ * const {QueryFile} = require('pg-promise');
+ * const {join: joinPath} = require('path');
+ *
+ * // Helper for linking to external query files:
+ * function sql(file) {
+ *     const fullPath = joinPath(__dirname, file); // generating full path;
+ *     return new QueryFile(fullPath, {minify: true});
+ * }
+ *
+ * module.exports = {
+ *     // external queries for Users:
+ *     users: {
+ *         add: sql('users/create.sql'),
+ *         search: sql('users/search.sql'),
+ *         report: sql('users/report.sql'),
+ *     },
+ *     // external queries for Products:
+ *     products: {
+ *         add: sql('products/add.sql'),
+ *         quote: sql('products/quote.sql'),
+ *         search: sql('products/search.sql'),
+ *     }
+ * };
+ *
+ * @example
+ * // Testing our SQL provider
+ *
+ * const db = require('./db'); // our database module;
+ * const {users: sql} = require('./sql'); // sql for users;
+ *
+ * module.exports = {
+ *     addUser: (name, age) => db.none(sql.add, [name, age]),
+ *     findUser: name => db.any(sql.search, name)
+ * };
+ *
+ */
+class QueryFile extends InnerState {
+
+    constructor(file, options) {
+
+        let filePath = file;
+
+        options = assert(options, {
+            debug: npm.utils.isDev(),
+            minify: (options && options.compress && options.minify === undefined) ? true : undefined,
+            compress: undefined,
+            params: undefined,
+            noWarnings: undefined
+        });
+
+        if (npm.utils.isText(filePath) && !npm.path.isAbsolute(filePath)) {
+            filePath = npm.path.join(npm.utils.startDir, filePath);
+        }
+
+        const {usedPath} = QueryFile.instance;
+
+        // istanbul ignore next:
+        if (!options.noWarnings) {
+            if (filePath in usedPath) {
+                usedPath[filePath]++;
+                ColorConsole.warn(`WARNING: Creating a duplicate QueryFile object for the same file - \n    ${filePath}\n${npm.utils.getLocalStack(2, 3)}\n`);
+            } else {
+                usedPath[filePath] = 0;
+            }
+        }
+
+        const _inner = {
+            file,
+            filePath,
+            options,
+            sql: undefined,
+            error: undefined,
+            ready: undefined,
+            modTime: undefined
+        };
+
+        super(_inner);
+
+        this.prepare();
+    }
+
+    /**
+     * Global instance of the file-path repository.
+     *
+     * @return {{usedPath: {}}}
+     */
+    static get instance() {
+        const s = Symbol.for('pgPromiseQueryFile');
+        let scope = global[s];
+        if (!scope) {
+            scope = {
+                usedPath: {} // used-path look-up dictionary
+            };
+            global[s] = scope;
+        }
+        return scope;
+    }
+
+    /**
+     * @name QueryFile#Symbol(QueryFile.$query)
+     * @type {string}
+     * @default undefined
+     * @readonly
+     * @private
+     * @summary Prepared query string.
+     * @description
+     * When property {@link QueryFile#error error} is set, the query is `undefined`.
+     *
+     * **IMPORTANT:** This property is for internal use by the library only, never use this
+     * property directly from your code.
+     */
+    get [file$query]() {
+        return this._inner.sql;
+    }
+
+    /**
+     * @name QueryFile#error
+     * @type {errors.QueryFileError}
+     * @default undefined
+     * @readonly
+     * @description
+     * When in an error state, it is set to a {@link errors.QueryFileError QueryFileError} object. Otherwise, it is `undefined`.
+     */
+    get error() {
+        return this._inner.error;
+    }
+
+    /**
+     * @name QueryFile#file
+     * @type {string}
+     * @readonly
+     * @description
+     * File name that was passed into the constructor.
+     *
+     * This property is primarily for internal use by the library.
+     */
+    get file() {
+        return this._inner.file;
+    }
+
+    /**
+     * @name QueryFile#options
+     * @type {QueryFile.Options}
+     * @readonly
+     * @description
+     * Set of options, as configured during the object's construction.
+     *
+     * This property is primarily for internal use by the library.
+     */
+    get options() {
+        return this._inner.options;
+    }
+
+    /**
+     * @summary Prepares the query for execution.
+     * @description
+     * If the query hasn't been prepared yet, it will read the file and process the content according
+     * to the parameters passed into the constructor.
+     *
+     * This method is primarily for internal use by the library.
+     *
+     * @param {boolean} [throwErrors=false]
+     * Throw any error encountered.
+     */
+    prepare(throwErrors) {
+        const i = this._inner, options = i.options;
+        let lastMod;
+        if (options.debug && i.ready) {
+            try {
+                lastMod = npm.fs.statSync(i.filePath).mtime.getTime();
+                // istanbul ignore if;
+                if (lastMod === i.modTime) {
+                    return;
+                }
+                i.ready = false;
+            } catch (e) {
+                i.sql = undefined;
+                i.ready = false;
+                i.error = e;
+                if (throwErrors) {
+                    throw i.error;
+                }
+                return;
+            }
+        }
+        if (i.ready) {
+            return;
+        }
+        try {
+            i.sql = npm.fs.readFileSync(i.filePath, 'utf8');
+            i.modTime = lastMod || npm.fs.statSync(i.filePath).mtime.getTime();
+            if (options.minify && options.minify !== 'after') {
+                i.sql = npm.minify(i.sql, {compress: options.compress});
+            }
+            if (options.params !== undefined) {
+                i.sql = npm.formatting.as.format(i.sql, options.params, {partial: true});
+            }
+            if (options.minify && options.minify === 'after') {
+                i.sql = npm.minify(i.sql, {compress: options.compress});
+            }
+            i.ready = true;
+            i.error = undefined;
+        } catch (e) {
+            i.sql = undefined;
+            i.error = new QueryFileError(e, this);
+            if (throwErrors) {
+                throw i.error;
+            }
+        }
+    }
+
+}
+
+// Hiding the query as a symbol within the type,
+// to make it even more difficult to misuse it:
+QueryFile.$query = file$query;
+
+/**
+ * @method QueryFile#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 query = qf[toPostgres](); // qf = an object of type QueryFile
+ * ```
+ *
+ * This is a raw formatting type (`rawType = true`), i.e. when used as a query-formatting parameter, type `QueryFile` injects SQL as raw text.
+ *
+ * If you need to support type `QueryFile` outside of query methods, this is the only safe way to get the most current SQL.
+ * And you would want to use this method dynamically, as it reloads the SQL automatically, if option `debug` is set.
+ * See {@link QueryFile.Options Options}.
+ *
+ * @param {QueryFile} [self]
+ * Optional self-reference, for ES6 arrow functions.
+ *
+ * @returns {string}
+ * SQL string from the file, according to the {@link QueryFile.Options options} specified.
+ *
+ */
+QueryFile.prototype[npm.formatting.as.ctf.toPostgres] = function (self) {
+    self = this instanceof QueryFile && this || self;
+    self.prepare(true);
+    return self[QueryFile.$query];
+};
+
+QueryFile.prototype[npm.formatting.as.ctf.rawType] = true; // use as pre-formatted
+
+npm.utils.addInspection(QueryFile, function () {
+    const s = 'QueryFile ';
+    const obj = {
+        file: this.file,
+        options: this.options
+    };
+    this.prepare();
+    if (this.error) {
+        obj.error = this.error;
+    }
+    obj.query = this[QueryFile.$query];
+    return s + npm.inspect(obj, {breakLength: 100, depth: 5, colors: true});
+});
+
+module.exports = {QueryFile};
+
+/**
+ * @typedef QueryFile.Options
+ * @description
+ * A set of configuration options as passed into the {@link QueryFile} constructor.
+ *
+ * @property {boolean} debug
+ * When in debug mode, the query file is checked for its last modification time on every query request,
+ * so if it changes, the file is read afresh.
+ *
+ * The default for this property is `true` when `NODE_ENV` = `development`,
+ * or `false` otherwise.
+ *
+ * @property {boolean|string} minify=false
+ * Parses and minifies the SQL using $[pg-minify]:
+ * - `false` - do not use $[pg-minify]
+ * - `true` - use $[pg-minify] to parse and minify SQL
+ * - `'after'` - use $[pg-minify] after applying static formatting parameters
+ *   (option `params`), as opposed to before it (default)
+ *
+ * If option `compress` is set, then the default for `minify` is `true`.
+ *
+ * Failure to parse SQL will result in $[SQLParsingError].
+ *
+ * @property {boolean} compress=false
+ * Sets option `compress` as supported by $[pg-minify], to uglify the SQL:
+ * - `false` - no compression to be applied, keep minimum spaces for easier read
+ * - `true` - remove all unnecessary spaces from SQL
+ *
+ * This option has no meaning, if `minify` is explicitly set to `false`. However, if `minify` is not
+ * specified and `compress` is specified as `true`, then `minify` defaults to `true`.
+ *
+ * @property {array|object|value} params
+ *
+ * Static formatting parameters to be applied to the SQL, using the same method {@link formatting.format as.format},
+ * but with option `partial` = `true`.
+ *
+ * Most of the time query formatting is fully dynamic, and applied just before executing the query.
+ * In some cases though you may need to pre-format SQL with static values. Examples of it can be a
+ * schema name, or a configurable table name.
+ *
+ * This option makes two-step SQL formatting easy: you can pre-format the SQL initially, and then
+ * apply the second-step dynamic formatting when executing the query.
+ *
+ * @property {boolean} noWarnings=false
+ * Suppresses all warnings produced by the class. It is not recommended for general use, only in specific tests
+ * that may require it.
+ *
+ */

package/lib/query-result.js

@@ -0,0 +1,39 @@
+/*
+ * 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.
+ */
+
+/**
+ * @enum {number}
+ * @alias queryResult
+ * @readonly
+ * @description
+ * **Query Result Mask**
+ *
+ * Binary mask that represents the number of rows expected from a query method,
+ * used by generic {@link Database#query query} method, plus {@link Database#func func}.
+ *
+ * The mask is always the last optional parameter, which defaults to `queryResult.any`.
+ *
+ * Any combination of flags is supported, except for `one + many`.
+ *
+ * The type is available from the library's root: `pgp.queryResult`.
+ *
+ * @see {@link Database#query Database.query}, {@link Database#func Database.func}
+ */
+const queryResult = {
+    /** Single row is expected, to be resolved as a single row-object. */
+    one: 1,
+    /** One or more rows expected, to be resolved as an array, with at least 1 row-object. */
+    many: 2,
+    /** Expecting no rows, to be resolved with `null`. */
+    none: 4,
+    /** `many|none` - any result is expected, to be resolved with an array of rows-objects. */
+    any: 6
+};
+
+module.exports = {queryResult};

package/lib/query.js

@@ -0,0 +1,273 @@
+/*
+ * 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 {QueryFile} = require('./query-file');
+const {ServerFormatting, PreparedStatement, ParameterizedQuery} = require('./types');
+const {SpecialQuery} = require('./special-query');
+const {queryResult} = require('./query-result');
+
+const npm = {
+    util: require('util'),
+    utils: require('./utils'),
+    formatting: require('./formatting'),
+    errors: require('./errors'),
+    stream: require('./stream').stream,
+    text: require('./text')
+};
+
+const QueryResultError = npm.errors.QueryResultError,
+    InternalError = npm.utils.InternalError,
+    qrec = npm.errors.queryResultErrorCode;
+
+const badMask = queryResult.one | queryResult.many; // unsupported combination bit-mask;
+
+//////////////////////////////
+// Generic query method;
+function $query(ctx, query, values, qrm) {
+
+    const special = qrm instanceof SpecialQuery && qrm;
+
+    if (special && special.isStream) {
+        return npm.stream.call(this, ctx, query, values);
+    }
+
+    const opt = ctx.options,
+        capSQL = opt.capSQL;
+
+    let error, entityType, queryFilePath,
+        pgFormatting = opt.pgFormatting,
+        params = pgFormatting ? values : undefined;
+
+    if (typeof query === 'function') {
+        try {
+            query = npm.formatting.resolveFunc(query, values);
+        } catch (e) {
+            error = e;
+            params = values;
+            query = npm.util.inspect(query);
+        }
+    }
+
+    if (!error && !query) {
+        error = new TypeError(npm.text.invalidQuery);
+    }
+
+    if (!error && typeof query === 'object') {
+        if (query instanceof QueryFile) {
+            query.prepare();
+            if (query.error) {
+                error = query.error;
+                query = query.file;
+            } else {
+                queryFilePath = query.file;
+                query = query[QueryFile.$query];
+            }
+        } else {
+            if ('entity' in query) {
+                entityType = query.type;
+                query = query.entity; // query is a function name;
+            } else {
+                if (query instanceof ServerFormatting) {
+                    pgFormatting = true;
+                } else {
+                    if ('name' in query) {
+                        query = new PreparedStatement(query);
+                        pgFormatting = true;
+                    } else {
+                        if ('text' in query) {
+                            query = new ParameterizedQuery(query);
+                            pgFormatting = true;
+                        }
+                    }
+                }
+                if (query instanceof ServerFormatting && !npm.utils.isNull(values)) {
+                    query.values = values;
+                }
+            }
+        }
+    }
+
+    if (!error) {
+        if (!pgFormatting && !npm.utils.isText(query)) {
+            const errTxt = entityType ? (entityType === 'func' ? npm.text.invalidFunction : npm.text.invalidProc) : npm.text.invalidQuery;
+            error = new TypeError(errTxt);
+        }
+        if (query instanceof ServerFormatting) {
+            const qp = query.parse();
+            if (qp instanceof Error) {
+                error = qp;
+            } else {
+                query = qp;
+            }
+        }
+    }
+
+    if (!error && !special) {
+        if (npm.utils.isNull(qrm)) {
+            qrm = queryResult.any; // default query result;
+        } else {
+            if (qrm !== parseInt(qrm) || (qrm & badMask) === badMask || qrm < 1 || qrm > 6) {
+                error = new TypeError(npm.text.invalidMask);
+            }
+        }
+    }
+
+    if (!error && (!pgFormatting || entityType)) {
+        try {
+            // use 'pg-promise' implementation of value formatting;
+            if (entityType) {
+                params = undefined;
+                query = npm.formatting.formatEntity(query, values, {capSQL, type: entityType});
+            } else {
+                query = npm.formatting.formatQuery(query, values);
+            }
+        } catch (e) {
+            if (entityType) {
+                let prefix = entityType === 'func' ? 'select * from' : 'call';
+                if (capSQL) {
+                    prefix = prefix.toUpperCase();
+                }
+                query = prefix + ' ' + query + '(...)';
+            } else {
+                params = values;
+            }
+            error = e instanceof Error ? e : new npm.utils.InternalError(e);
+        }
+    }
+
+    return new Promise((resolve, reject) => {
+
+        if (notifyReject()) {
+            return;
+        }
+        error = Events.query(opt, getContext());
+        if (notifyReject()) {
+            return;
+        }
+        try {
+            const start = Date.now();
+            ctx.db.client.query(query, params, (err, result) => {
+                let data, multiResult, lastResult = result;
+                if (err) {
+                    // istanbul ignore if (auto-testing connectivity issues is too problematic)
+                    if (npm.utils.isConnectivityError(err)) {
+                        ctx.db.client.$connectionError = err;
+                    }
+                    err.query = err.query || query;
+                    err.params = err.params || params;
+                    error = err;
+                } else {
+                    multiResult = Array.isArray(result);
+                    if (multiResult) {
+                        lastResult = result[result.length - 1];
+                        for (let i = 0; i < result.length; i++) {
+                            const r = result[i];
+                            makeIterable(r);
+                            error = Events.receive(opt, r.rows, r, getContext());
+                            if (error) {
+                                break;
+                            }
+                        }
+                    } else {
+                        makeIterable(result);
+                        result.duration = Date.now() - start;
+                        error = Events.receive(opt, result.rows, result, getContext());
+                    }
+                }
+                if (!error) {
+                    data = lastResult;
+                    if (special) {
+                        if (special.isMultiResult) {
+                            data = multiResult ? result : [result]; // method .multiResult() is called
+                        }
+                        // else, method .result() is called
+                    } else {
+                        data = data.rows;
+                        const len = data.length;
+                        if (len) {
+                            if (len > 1 && qrm & queryResult.one) {
+                                // one row was expected but returned multiple;
+                                error = new QueryResultError(qrec.multiple, lastResult, query, params);
+                            } else {
+                                if (!(qrm & (queryResult.one | queryResult.many))) {
+                                    // no data should have been returned;
+                                    error = new QueryResultError(qrec.notEmpty, lastResult, query, params);
+                                } else {
+                                    if (!(qrm & queryResult.many)) {
+                                        data = data[0];
+                                    }
+                                }
+                            }
+                        } else {
+                            // no data returned;
+                            if (qrm & queryResult.none) {
+                                if (qrm & queryResult.one) {
+                                    data = null;
+                                } else {
+                                    data = qrm & queryResult.many ? data : null;
+                                }
+                            } else {
+                                error = new QueryResultError(qrec.noData, lastResult, query, params);
+                            }
+                        }
+                    }
+                }
+
+                if (!notifyReject()) {
+                    resolve(data);
+                }
+            });
+        } catch (e) {
+            // this can only happen as a result of an internal failure within node-postgres,
+            // like during a sudden loss of communications, which is impossible to reproduce
+            // automatically, so removing it from the test coverage:
+            // istanbul ignore next
+            error = e;
+        }
+
+        function getContext() {
+            let client;
+            if (ctx.db) {
+                client = ctx.db.client;
+            } else {
+                error = new Error(npm.text.looseQuery);
+            }
+            return {
+                client, query, params, queryFilePath, values,
+                dc: ctx.dc,
+                ctx: ctx.ctx
+            };
+        }
+
+        notifyReject();
+
+        function notifyReject() {
+            const context = getContext();
+            if (error) {
+                if (error instanceof InternalError) {
+                    error = error.error;
+                }
+                Events.error(opt, error, context);
+                reject(error);
+                return true;
+            }
+        }
+    });
+}
+
+// Extends Result to provide iterable for the rows;
+// See: https://github.com/brianc/node-postgres/pull/2861
+function makeIterable(r) {
+    r[Symbol.iterator] = function () {
+        return this.rows.values();
+    };
+}
+
+module.exports = {query: $query};