@depup/pg-promise 12.6.2-depup.0

package/lib/errors/README.md

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

package/lib/errors/index.js

@@ -0,0 +1,51 @@
+/*
+ * 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 {QueryResultError, queryResultErrorCode} = require('./query-result-error');
+const {PreparedStatementError} = require('./prepared-statement-error');
+const {ParameterizedQueryError} = require('./parameterized-query-error');
+const {QueryFileError} = require('./query-file-error');
+
+/**
+ * @namespace errors
+ * @description
+ * Error types namespace, available as `pgp.errors`, before and after initializing the library.
+ *
+ * @property {function} PreparedStatementError
+ * {@link errors.PreparedStatementError PreparedStatementError} class constructor.
+ *
+ * Represents all errors that can be reported by class {@link PreparedStatement}.
+ *
+ * @property {function} ParameterizedQueryError
+ * {@link errors.ParameterizedQueryError ParameterizedQueryError} class constructor.
+ *
+ * Represents all errors that can be reported by class {@link ParameterizedQuery}.
+ *
+ * @property {function} QueryFileError
+ * {@link errors.QueryFileError QueryFileError} class constructor.
+ *
+ * Represents all errors that can be reported by class {@link QueryFile}.
+ *
+ * @property {function} QueryResultError
+ * {@link errors.QueryResultError QueryResultError} class constructor.
+ *
+ * Represents all result-specific errors from query methods.
+ *
+ * @property {errors.queryResultErrorCode} queryResultErrorCode
+ * Error codes `enum` used by class {@link errors.QueryResultError QueryResultError}.
+ *
+ */
+
+module.exports = {
+    QueryResultError,
+    queryResultErrorCode,
+    PreparedStatementError,
+    ParameterizedQueryError,
+    QueryFileError
+};

package/lib/errors/parameterized-query-error.js

@@ -0,0 +1,71 @@
+/*
+ * 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 {QueryFileError} = require('./query-file-error');
+
+const npm = {
+    os: require('os'),
+    utils: require('../utils'),
+    inspect: require('util').inspect
+};
+
+/**
+ * @class errors.ParameterizedQueryError
+ * @augments external:Error
+ * @description
+ * {@link errors.ParameterizedQueryError ParameterizedQueryError} class, available from the {@link errors} namespace.
+ *
+ * This type represents all errors that can be reported by class {@link ParameterizedQuery}, whether it is used
+ * explicitly or implicitly (via a simple `{text, values}` object).
+ *
+ * @property {string} name
+ * Standard {@link external:Error Error} property - error type name = `ParameterizedQueryError`.
+ *
+ * @property {string} message
+ * Standard {@link external:Error Error} property - the error message.
+ *
+ * @property {string} stack
+ * Standard {@link external:Error Error} property - the stack trace.
+ *
+ * @property {errors.QueryFileError} error
+ * Internal {@link errors.QueryFileError} object.
+ *
+ * It is set only when the source {@link ParameterizedQuery} used a {@link QueryFile} which threw the error.
+ *
+ * @property {object} result
+ * Resulting Parameterized Query object.
+ *
+ * @see ParameterizedQuery
+ */
+class ParameterizedQueryError extends Error {
+    constructor(error, pq) {
+        const isQueryFileError = error instanceof QueryFileError;
+        const message = isQueryFileError ? 'Failed to initialize \'text\' from a QueryFile.' : error;
+        super(message);
+        this.name = this.constructor.name;
+        if (isQueryFileError) {
+            this.error = error;
+        }
+        this.result = pq;
+        Error.captureStackTrace(this, this.constructor);
+    }
+}
+
+npm.utils.addInspection(ParameterizedQueryError, function () {
+    const obj = {
+        message: this.message,
+        result: this.result
+    };
+    if (this.error) {
+        obj.error = this.error;
+    }
+    return 'ParameterizedQueryError ' + npm.inspect(obj, {breakLength: 100, depth: 5, colors: true});
+});
+
+module.exports = {ParameterizedQueryError};

package/lib/errors/prepared-statement-error.js

@@ -0,0 +1,71 @@
+/*
+ * 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 {QueryFileError} = require('./query-file-error');
+
+const npm = {
+    os: require('os'),
+    utils: require('../utils'),
+    inspect: require('util').inspect
+};
+
+/**
+ * @class errors.PreparedStatementError
+ * @augments external:Error
+ * @description
+ * {@link errors.PreparedStatementError PreparedStatementError} class, available from the {@link errors} namespace.
+ *
+ * This type represents all errors that can be reported by class {@link PreparedStatement}, whether it is used
+ * explicitly or implicitly (via a simple `{name, text, values}` object).
+ *
+ * @property {string} name
+ * Standard {@link external:Error Error} property - error type name = `PreparedStatementError`.
+ *
+ * @property {string} message
+ * Standard {@link external:Error Error} property - the error message.
+ *
+ * @property {string} stack
+ * Standard {@link external:Error Error} property - the stack trace.
+ *
+ * @property {errors.QueryFileError} error
+ * Internal {@link errors.QueryFileError} object.
+ *
+ * It is set only when the source {@link PreparedStatement} used a {@link QueryFile} which threw the error.
+ *
+ * @property {object} result
+ * Resulting Prepared Statement object.
+ *
+ * @see PreparedStatement
+ */
+class PreparedStatementError extends Error {
+    constructor(error, ps) {
+        const isQueryFileError = error instanceof QueryFileError;
+        const message = isQueryFileError ? 'Failed to initialize \'text\' from a QueryFile.' : error;
+        super(message);
+        this.name = this.constructor.name;
+        if (isQueryFileError) {
+            this.error = error;
+        }
+        this.result = ps;
+        Error.captureStackTrace(this, this.constructor);
+    }
+}
+
+npm.utils.addInspection(PreparedStatementError, function () {
+    const obj = {
+        message: this.message,
+        result: this.result
+    };
+    if (this.error) {
+        obj.error = this.error;
+    }
+    return 'PreparedStatementError ' + npm.inspect(obj, {breakLength: 100, depth: 5, colors: true});
+});
+
+module.exports = {PreparedStatementError};

package/lib/errors/query-file-error.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 npm = {
+    os: require('os'),
+    utils: require('../utils'),
+    minify: require('pg-minify'),
+    inspect: require('util').inspect
+};
+
+/**
+ * @class errors.QueryFileError
+ * @augments external:Error
+ * @description
+ * {@link errors.QueryFileError QueryFileError} class, available from the {@link errors} namespace.
+ *
+ * This type represents all errors related to {@link QueryFile}.
+ *
+ * @property {string} name
+ * Standard {@link external:Error Error} property - error type name = `QueryFileError`.
+ *
+ * @property {string} message
+ * Standard {@link external:Error Error} property - the error message.
+ *
+ * @property {string} stack
+ * Standard {@link external:Error Error} property - the stack trace.
+ *
+ * @property {string} file
+ * File path/name that was passed into the {@link QueryFile} constructor.
+ *
+ * @property {object} options
+ * Set of options that was used by the {@link QueryFile} object.
+ *
+ * @property {SQLParsingError} error
+ * Internal $[SQLParsingError] object.
+ *
+ * It is set only when the error was thrown by $[pg-minify] while parsing the SQL file.
+ *
+ * @see QueryFile
+ *
+ */
+class QueryFileError extends Error {
+    constructor(error, qf) {
+        const isSqlError = error instanceof npm.minify.SQLParsingError;
+        const message = isSqlError ? 'Failed to parse the SQL.' : error.message;
+        super(message);
+        this.name = this.constructor.name;
+        if (isSqlError) {
+            this.error = error;
+        }
+        this.file = qf.file;
+        this.options = qf.options;
+        Error.captureStackTrace(this, this.constructor);
+    }
+}
+
+npm.utils.addInspection(QueryFileError, function () {
+    const obj = {
+        message: this.message,
+        file: this.file,
+        options: this.options
+    };
+    if (this.error) {
+        obj.error = this.error;
+    }
+    return 'QueryFileError ' + npm.inspect(obj, {breakLength: 100, depth: 5, colors: true});
+});
+
+module.exports = {QueryFileError};

package/lib/errors/query-result-error.js

@@ -0,0 +1,157 @@
+/*
+ * 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 = {
+    os: require('os'),
+    utils: require('../utils'),
+    text: require('../text'),
+    inspect: require('util').inspect
+};
+
+/**
+ * @enum {number}
+ * @alias errors.queryResultErrorCode
+ * @readonly
+ * @description
+ * `queryResultErrorCode` enumerator, available from the {@link errors} namespace.
+ *
+ * Represents an integer code for each type of error supported by type {@link errors.QueryResultError}.
+ *
+ * @see {@link errors.QueryResultError}
+ */
+const queryResultErrorCode = {
+    /** No data returned from the query. */
+    noData: 0,
+
+    /** No return data was expected. */
+    notEmpty: 1,
+
+    /** Multiple rows were not expected. */
+    multiple: 2
+};
+
+const errorMessages = [
+    {name: 'noData', message: npm.text.noData},
+    {name: 'notEmpty', message: npm.text.notEmpty},
+    {name: 'multiple', message: npm.text.multiple}
+];
+
+/**
+ * @class errors.QueryResultError
+ * @augments external:Error
+ * @description
+ *
+ * This error is specified as the rejection reason for all result-specific methods when the result doesn't match
+ * the expectation, i.e. when a query result doesn't match its Query Result Mask - the value of {@link queryResult}.
+ *
+ * The error applies to the result from the following methods: {@link Database#none none},
+ * {@link Database#one one}, {@link Database#oneOrNone oneOrNone} and {@link Database#many many}.
+ *
+ * Supported errors:
+ *
+ * - `No return data was expected.`, method {@link Database#none none}
+ * - `No data returned from the query.`, methods {@link Database#one one} and {@link Database#many many}
+ * - `Multiple rows were not expected.`, methods {@link Database#one one} and {@link Database#oneOrNone oneOrNone}
+ *
+ * Like any other error, this one is notified with through the global event {@link event:error error}.
+ *
+ * The type is available from the {@link errors} namespace.
+ *
+ * @property {string} name
+ * Standard {@link external:Error Error} property - error type name = `QueryResultError`.
+ *
+ * @property {string} message
+ * Standard {@link external:Error Error} property - the error message.
+ *
+ * @property {string} stack
+ * Standard {@link external:Error Error} property - the stack trace.
+ *
+ * @property {object} result
+ * The original $[Result] object that was received.
+ *
+ * @property {number} received
+ * Total number of rows received. It is simply the value of `result.rows.length`.
+ *
+ * @property {number} code
+ * Error code - {@link errors.queryResultErrorCode queryResultErrorCode} value.
+ *
+ * @property {string} query
+ * Query that was executed.
+ *
+ * Normally, it is the query already formatted with values, if there were any.
+ * But if you are using initialization option `pgFormatting`, then the query string is before formatting.
+ *
+ * @property {*} values
+ * Values passed in as query parameters. Available only when initialization option `pgFormatting` is used.
+ * Otherwise, the values are within the pre-formatted `query` string.
+ *
+ * @example
+ *
+ * const QueryResultError = pgp.errors.QueryResultError;
+ * const qrec = pgp.errors.queryResultErrorCode;
+ *
+ * const initOptions = {
+ *
+ *   // pg-promise initialization options...
+ *
+ *   error(err, e) {
+ *       if (err instanceof QueryResultError) {
+ *           // A query returned unexpected number of records, and thus rejected;
+ *
+ *           // we can check the error code, if we want specifics:
+ *           if(err.code === qrec.noData) {
+ *               // expected some data, but received none;
+ *           }
+ *
+ *           // If you write QueryResultError into the console,
+ *           // you will get a nicely formatted output.
+ *
+ *           console.log(err);
+ *
+ *           // See also: err, e.query, e.params, etc.
+ *       }
+ *   }
+ * };
+ *
+ * @see
+ * {@link queryResult}, {@link Database#none none}, {@link Database#one one},
+ * {@link Database#oneOrNone oneOrNone}, {@link Database#many many}
+ *
+ */
+class QueryResultError extends Error {
+    constructor(code, result, query, values) {
+        const message = errorMessages[code].message;
+        super(message);
+        this.name = this.constructor.name;
+        this.code = code;
+        this.result = result;
+        this.query = query;
+        this.values = values;
+        this.received = result.rows.length;
+        Error.captureStackTrace(this, this.constructor);
+    }
+}
+
+npm.utils.addInspection(QueryResultError, function () {
+    const obj = {
+        code: 'queryResultErrorCode.' + errorMessages[this.code].name,
+        message: this.message,
+        received: this.received,
+        query: typeof this.query === 'string' ? this.query : npm.utils.toJson(this.query)
+    };
+    if (this.values !== undefined) {
+        obj.values = this.values;
+    }
+    return 'QueryResultError ' + npm.inspect(obj, {breakLength: 100, depth: 5, colors: true});
+});
+
+module.exports = {
+    QueryResultError,
+    queryResultErrorCode
+};