pg-promise 10.15.3 → 11.0.0

package/README.md

@@ -34,7 +34,6 @@ PostgreSQL interface for Node.js
     - [Configurable Transactions]
     - [Conditional Transactions]    
   - [Library de-initialization]
-* [History](#history)
 
 ---
 
@@ -1030,15 +1029,6 @@ will be rejecting with [Error] = `Connection pool of the database object has bee
 
 See the relevant API: [pgp.end], [Database.$pool]
 
-### update
-
-Version 10.11.0 added support for connection option `allowExitOnIdle`, to let process exit when pool is idle.
-
-# History
-
-Although this project formally maintains a [CHANGELOG], for a short list of the top-level changes,
-for detailed changes between versions you should see the corresponding release notes.
-
 <!-- Internal Menu Links -->
 
 [Usage]:#usage
@@ -1131,6 +1121,6 @@ for detailed changes between versions you should see the corresponding release n
 [Bluebird]:https://github.com/petkaantonov/bluebird
 [SQL injection]:https://en.wikipedia.org/wiki/SQL_injection
 [Symbol]:https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol
-[idleTimeoutMillis]:https://github.com/brianc/node-postgres/blob/master/packages/pg/lib/defaults.js#L46
-[connection pool]:https://github.com/brianc/node-pg-pool
+[idleTimeoutMillis]:https://github.com/brianc/node-postgres/blob/master/packages/pg/lib/defaults.js
+[connection pool]:https://github.com/brianc/node-postgres/tree/master/packages/pg-pool
 [Error]:https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error

package/lib/database.js

@@ -1608,15 +1608,8 @@ function Database(cn, dc, config) {
             }
         }
 
-        // lock all default properties to read-only,
-        // to prevent override by the client.
-        npm.utils.lock(obj, false, ctx.options);
-
-        // extend the protocol;
+        // extending the protocol;
         Events.extend(ctx.options, obj, ctx.dc);
-
-        // freeze the protocol permanently;
-        npm.utils.lock(obj, true, ctx.options);
     }
 
 }

package/lib/events.js

@@ -28,14 +28,16 @@ class Events {
      *
      * The library will suppress any error thrown by the handler and write it into the console.
      *
-     * @param {external:Client} client
+     * @param {{}} e Event Properties
+     *
+     * @param {external:Client} e.client
      * $[pg.Client] object that represents the connection.
      *
-     * @param {*} dc
+     * @param {*} e.dc
      * Database Context that was used when creating the database object (see {@link Database}).
      *
-     * @param {number} useCount
-     * Number of times the connection has been previously used, starting with 0 for a freshly
+     * @param {number} e.useCount
+     * Number of times the connection has been previously used, starting with 0, for a freshly
      * allocated physical connection.
      *
      * This parameter is always 0 for direct connections (created by calling {@link Database#connect Database.connect}
@@ -47,8 +49,8 @@ class Events {
      *
      *     // pg-promise initialization options...
      *
-     *     connect(client, dc, useCount) {
-     *         const cp = client.connectionParameters;
+     *     connect(e) {
+     *         const cp = e.client.connectionParameters;
      *         console.log('Connected to database:', cp.database);
      *     }
      *
@@ -57,7 +59,7 @@ class Events {
     static connect(ctx, client, useCount) {
         if (typeof ctx.options.connect === `function`) {
             try {
-                ctx.options.connect(client, ctx.dc, useCount);
+                ctx.options.connect({client, dc: ctx.dc, useCount});
             } catch (e) {
                 // have to silence errors here;
                 // cannot allow unhandled errors while connecting to the database,
@@ -77,9 +79,11 @@ class Events {
      *
      * The library will suppress any error thrown by the handler and write it into the console.
      *
-     * @param {external:Client} client - $[pg.Client] object that represents connection with the database.
+     * @param {{}} e Event Properties
+     *
+     * @param {external:Client} e.client - $[pg.Client] object that represents connection with the database.
      *
-     * @param {*} dc - Database Context that was used when creating the database object (see {@link Database}).
+     * @param {*} e.dc - Database Context that was used when creating the database object (see {@link Database}).
      *
      * @example
      *
@@ -87,8 +91,8 @@ class Events {
      *
      *     // pg-promise initialization options...
      *
-     *     disconnect(client, dc) {
-     *        const cp = client.connectionParameters;
+     *     disconnect(e) {
+     *        const cp = e.client.connectionParameters;
      *        console.log('Disconnecting from database:', cp.database);
      *     }
      *
@@ -97,7 +101,7 @@ class Events {
     static disconnect(ctx, client) {
         if (typeof ctx.options.disconnect === `function`) {
             try {
-                ctx.options.disconnect(client, ctx.dc);
+                ctx.options.disconnect({client, dc: ctx.dc});
             } catch (e) {
                 // have to silence errors here;
                 // cannot allow unhandled errors while disconnecting from the database,
@@ -161,18 +165,20 @@ class Events {
      * this event is called for every result that's returned. And for method {@link Database#stream Database.stream},
      * the event occurs for every record.
      *
-     * @param {Array<Object>} data
+     * @param {{}} e Event Properties
+     *
+     * @param {Array<Object>} e.data
      * Array of received objects/rows.
      *
      * If any of those objects are modified during notification, the client will receive the modified data.
      *
-     * @param {external:Result} result
+     * @param {external:Result} e.result
      * - Original $[Result] object, if the data is from a non-stream query, in which case `data = result.rows`.
      *   For single-query requests, $[Result] object is extended with property `duration` - number of milliseconds
      *   it took to send the query, execute it and get the result back.
      * - It is `undefined` when the data comes from a stream (method {@link Database#stream Database.stream}).
      *
-     * @param {EventContext} e
+     * @param {EventContext} e.ctx
      * Event Context Object.
      *
      * @example
@@ -184,8 +190,8 @@ class Events {
      *
      *     // pg-promise initialization options...
      *
-     *     receive(data, result, e) {
-     *         camelizeColumns(data);
+     *     receive(e) {
+     *         camelizeColumns(e.data);
      *     }
      * };
      *
@@ -203,10 +209,10 @@ class Events {
      *     }
      * }
      */
-    static receive(options, data, result, context) {
+    static receive(options, data, result, ctx) {
         if (typeof options.receive === `function`) {
             try {
-                options.receive(data, result, context);
+                options.receive({data, result, ctx});
             } catch (e) {
                 // throwing an error during event 'receive'
                 // will result in a reject for the request.
@@ -527,5 +533,4 @@ module.exports = {Events};
  * This property is always set for events {@link event:task task} and {@link event:transact transact}, while for events
  * {@link event:query query}, {@link event:receive receive} and {@link event:error error} it is only set when they occur
  * inside a task or transaction.
- *
  */

package/lib/formatting.js

@@ -669,7 +669,7 @@ const $as = {
      * Converts an array of values into its PostgreSQL presentation as an Array-Type constructor string: `array[]`.
      *
      * Top-level empty arrays are formatted as literal `{}`, to avoid the necessity of explicit type casting,
-     * as the server cannot automatically infer type of an empty non-literal array.
+     * as the server cannot automatically infer type of empty non-literal array.
      *
      * @param {Array|function} arr
      * Array to be converted, or a function that returns one.

package/lib/helpers/index.js

@@ -11,7 +11,6 @@ const {Column} = require(`./column`);
 const {ColumnSet} = require(`./column-set`);
 const {TableName} = require(`./table-name`);
 const method = require(`./methods`);
-const utils = require(`../utils`);
 
 /**
  * @namespace helpers
@@ -68,6 +67,5 @@ module.exports = config => {
         ColumnSet,
         Column
     };
-    utils.lock(res, true, config.options);
     return res;
 };

package/lib/index.js

@@ -12,16 +12,17 @@ var v = process.versions.node.split(`.`),
     highVer = +v[0];
 
 // istanbul ignore next
-if (highVer < 12) {
+if (highVer < 14) {
 
-    // From pg-promise v10.15.0, the oldest supported Node.js is v12.0.0
+    // From pg-promise v11.0.0, the oldest supported Node.js is v14.0.0
 
+    // Node.js v12.0.0 was supported up to pg-promise v10.15.4
     // Node.js v8.0.0 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 12.0.0`);
+    throw new Error(`Minimum Node.js version supported by pg-promise is 14.0.0`);
 }
 
 module.exports = require(`./main`);

package/lib/main.js

@@ -36,7 +36,7 @@ let originalClientConnect;
  * @module pg-promise
  *
  * @description
- * ## pg-promise v10.15
+ * ## pg-promise v11.0
  * All documentation here is for the latest official release only.
  *
  * ### Initialization Options
@@ -50,10 +50,10 @@ let originalClientConnect;
  * const pgp = require('pg-promise')(initOptions);
  * ```
  *
- * @param {{}} [options]
+ * @property {{}} [options]
  * Library Initialization Options.
  *
- * @param {boolean} [options.pgFormatting=false]
+ * @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.
@@ -63,13 +63,13 @@ let originalClientConnect;
  *
  * This option is dynamic (can be set before or after initialization).
  *
- * @param {boolean} [options.pgNative=false]
+ * @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).
  *
- * @param {object|function} [options.promiseLib=Promise]
+ * @property {object|function} [options.promiseLib=Promise]
  * Overrides the default (ES6 Promise) promise library for its internal use.
  *
  * Example below sets to use $[Bluebird] - the best and recommended promise library. It is the fastest one,
@@ -88,20 +88,7 @@ let originalClientConnect;
  *
  * This is a static option (can only be set prior to initialization).
  *
- * @param {boolean} [options.noLocking=false]
- * Prevents protocol locking.
- *
- * By default, the library locks much of its protocol to read-only access, as a fool-proof mechanism.
- * Specifically for the {@link event:extend extend} event this serves as a protection against overriding existing
- * properties or trying to set them at the wrong time.
- *
- * If this provision gets in the way of using a mock-up framework for your tests, you can force
- * the library to deactivate most of the locks by setting `noLocking` = `true` within the options.
- *
- * This option is dynamic (can be set before or after initialization). However, changing it after the library's
- * initialization will not affect {@link Database} objects that have already been created.
- *
- * @param {boolean} [options.capSQL=false]
+ * @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.
@@ -111,7 +98,7 @@ let originalClientConnect;
  *
  * This option is dynamic (can be set before or after initialization).
  *
- * @param {string|Array<string>|null|undefined|function} [options.schema]
+ * @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.
@@ -128,47 +115,47 @@ let originalClientConnect;
  *
  * This option is dynamic (can be set before or after initialization).
  *
- * @param {boolean} [options.noWarnings=false]
+ * @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).
  *
- * @param {function} [options.connect]
+ * @property {function} [options.connect]
  * Global event {@link event:connect connect} handler.
  *
  * This option is dynamic (can be set before or after initialization).
  *
- * @param {function} [options.disconnect]
+ * @property {function} [options.disconnect]
  * Global event {@link event:disconnect disconnect} handler.
  *
  * This option is dynamic (can be set before or after initialization).
  *
- * @param {function} [options.query]
+ * @property {function} [options.query]
  * Global event {@link event:query query} handler.
  *
  * This option is dynamic (can be set before or after initialization).
  *
- * @param {function} [options.receive]
+ * @property {function} [options.receive]
  * Global event {@link event:receive receive} handler.
  *
  * This option is dynamic (can be set before or after initialization).
  *
- * @param {function} [options.task]
+ * @property {function} [options.task]
  * Global event {@link event:task task} handler.
  *
  * This option is dynamic (can be set before or after initialization).
  *
- * @param {function} [options.transact]
+ * @property {function} [options.transact]
  * Global event {@link event:transact transact} handler.
  *
  * This option is dynamic (can be set before or after initialization).
  *
- * @param {function} [options.error]
+ * @property {function} [options.error]
  * Global event {@link event:error error} handler.
  *
  * This option is dynamic (can be set before or after initialization).
  *
- * @param {function} [options.extend]
+ * @property {function} [options.extend]
  * Global event {@link event:extend extend} handler.
  *
  * This option is dynamic (can be set before or after initialization).
@@ -191,7 +178,7 @@ let originalClientConnect;
  */
 function $main(options) {
 
-    options = assert(options, [`pgFormatting`, `pgNative`, `promiseLib`, `noLocking`, `capSQL`, `noWarnings`,
+    options = assert(options, [`pgFormatting`, `pgNative`, `promiseLib`, `capSQL`, `noWarnings`,
         `connect`, `disconnect`, `query`, `receive`, `task`, `transact`, `error`, `extend`, `schema`]);
 
     let pg = npm.pg;
@@ -303,7 +290,6 @@ function $main(options) {
     npm.utils.addReadProp(inst, `spex`, config.$npm.spex);
 
     config.pgp = inst;
-    npm.utils.lock(config, true, options);
 
     return inst;
 }

package/lib/query.js

@@ -160,8 +160,8 @@ function $query(ctx, query, values, qrm, config) {
                     if (npm.utils.isConnectivityError(err)) {
                         ctx.db.client.$connectionError = err;
                     }
-                    err.query = err.query || query;
-                    err.params = err.params || params;
+                    err.query ??= query;
+                    err.params ??= params;
                     error = err;
                 } else {
                     multiResult = Array.isArray(result);

package/lib/task.js

@@ -238,7 +238,6 @@ const execute = (ctx, obj, isTX, config) => {
             c.success = success;
             c.result = result;
             c.duration = c.finish - c.start;
-            npm.utils.lock(c, true);
         }
         (isTX ? Events.transact : Events.task)(ctx.options, {
             client: ctx.db && ctx.db.client, // loss of connectivity is possible at this point

package/lib/utils/index.js

@@ -10,8 +10,7 @@
 const npm = {
     path: require(`path`),
     util: require(`util`),
-    patterns: require(`../patterns`),
-    os: require(`os`)
+    patterns: require(`../patterns`)
 };
 
 ////////////////////////////////////////////
@@ -36,27 +35,6 @@ function isDev() {
     return env.toLowerCase().indexOf(`dev`) !== -1;
 }
 
-///////////////////////////////////////////////////
-// Locks all properties in an object to read-only,
-// or freezes the entire object for any changes.
-function lock(obj, freeze, options) {
-    if (options && options.noLocking) {
-        return;
-    }
-    if (freeze) {
-        Object.freeze(obj); // freeze the entire object, permanently;
-    } else {
-        const desc = {
-            writable: false,
-            configurable: false,
-            enumerable: true
-        };
-        for (const p in obj) {
-            Object.defineProperty(obj, p, desc);
-        }
-    }
-}
-
 /////////////////////////////////////////////
 // Adds properties from source to the target,
 // making them read-only and enumerable.
@@ -203,22 +181,15 @@ function toJson(data) {
     }
 }
 
-const platform = npm.os.platform();
-
 const exp = {
     toJson,
     getIfHas,
     addInspection,
     InternalError,
     getLocalStack,
-    lock,
     isText,
     isNull,
     isDev,
-    platform: {
-        isWindows: platform === `win32`,
-        isMac: platform === `darwin`
-    },
     addReadProp,
     addReadProperties,
     getSafeConnection,

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "pg-promise",
-  "version": "10.15.3",
+  "version": "11.0.0",
   "description": "PostgreSQL interface for Node.js",
   "main": "lib/index.js",
   "typings": "typescript/pg-promise.d.ts",
   "scripts": {
-    "check-spelling": "cspell --config=.cspell.json \"**/*.{md,ts,js}\" --no-progress",
+    "spelling": "cspell --config=.cspell.json \"**/*.{md,ts,js}\" --no-progress",
     "coverage": "istanbul cover ./node_modules/jasmine-node/bin/jasmine-node test",
     "doc": "jsdoc -c ./jsdoc/jsdoc.js ./jsdoc/README.md -t ./jsdoc/templates/custom",
     "lint": "eslint ./lib ./test/*.js ./test/db --fix",
@@ -37,7 +37,7 @@
   },
   "license": "MIT",
   "engines": {
-    "node": ">=12.0"
+    "node": ">=14.0"
   },
   "dependencies": {
     "assert-options": "0.8.0",
@@ -46,17 +46,18 @@
     "spex": "3.2.0"
   },
   "devDependencies": {
-    "@types/node": "18.11.9",
+    "@babel/eslint-parser": "7.19.1",
+    "@types/node": "18.11.18",
     "bluebird": "3.7.2",
     "coveralls": "3.1.1",
-    "cspell": "6.14.3",
-    "eslint": "8.28.0",
+    "cspell": "6.18.1",
+    "eslint": "8.30.0",
     "istanbul": "0.4.5",
     "jasmine-node": "3.0.0",
-    "jsdoc": "3.6.11",
+    "jsdoc": "4.0.0",
     "JSONStream": "1.3.5",
     "pg-query-stream": "4.2.4",
     "tslint": "6.1.3",
-    "typescript": "4.9.3"
+    "typescript": "4.9.4"
   }
 }

package/typescript/pg-promise.d.ts

@@ -8,7 +8,7 @@
  */
 
 /////////////////////////////////////////
-// Requires pg-promise v10.14.0 or later.
+// Requires pg-promise v11.0.0 or later.
 /////////////////////////////////////////
 
 // We use ES6 as static promise here, because generic promises are still not supported.
@@ -573,18 +573,17 @@ declare namespace pgPromise {
         pgFormatting?: boolean
         pgNative?: boolean
         promiseLib?: any
-        noLocking?: boolean
         capSQL?: boolean
         schema?: ValidSchema | ((dc: any) => ValidSchema)
 
-        connect?(client: C, dc: any, useCount: number): void
+        connect?(e: { client: C, dc: any, useCount: number }): void
 
-        disconnect?(client: C, dc: any): void
+        disconnect?(e: { client: C, dc: any }): void
 
         query?(e: IEventContext<C>): void
 
         // NOTE: result is undefined when data comes from QueryStream, i.e. via method Database.stream
-        receive?(data: any[], result: IResultExt | void, e: IEventContext<C>): void
+        receive?(e: { data: any[], result: IResultExt | void, ctx: IEventContext<C> }): void
 
         task?(e: IEventContext<C>): void
 

package/typescript/pg-subset.d.ts

@@ -293,15 +293,15 @@ declare namespace pg {
 
     interface IClient extends EventEmitter {
 
-        query<T>(config: any, values: any[], callback: (err: Error, result: IResult<T>) => void): undefined
+        query<T>(config: any, values: any[], callback: (err: Error, result: IResult<T>) => void): void
 
-        query<T>(config: any, callback: (err: Error, result: IResult<T>) => void): undefined
+        query<T>(config: any, callback: (err: Error, result: IResult<T>) => void): void
 
         query<T>(config: any, values: any[]): Promise<IResult<T>>
 
         query<T>(config: any): Promise<IResult<T>>
 
-        release();
+        release(): void
 
         connectionParameters: IConnectionParameters
         database: string