postgrejs 2.12.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2020 Panates, Eray Hanoglu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,200 @@
+## postgresql-client
+  
+[![NPM Version][npm-image]][npm-url]
+[![NPM Downloads][downloads-image]][downloads-url]
+[![CircleCI][circleci-image]][circleci-url]
+[![Test Coverage][coveralls-image]][coveralls-url]
+
+
+Enterprise level PostgreSQL client for NodeJs
+
+
+## Library
+
+- Pure JavaScript library completely written in TypeScript
+- Works with both CommonJS and ESM module systems
+- Well tested
+- Strictly typed
+- Asynchronous Promise based api
+
+## Features
+
+- Both single connection and advanced pooling support
+- Full binary wire protocol support for all data types
+- Named Prepared Statements
+- Cursors with fast double-link cache
+- High level implementation for notifications (LISTEN/NOTIFY)
+- Extensible data-types and type mapping
+- Bind parameters with OID mappings
+- Multidimensional arrays with fast binary encoding/decoding
+- Low memory utilization and boosted performance with Shared Buffers
+- Supports Clear text, MD5 and SASL password algorithms
+- Can return both array and object rows
+- Auto disposal with "using" syntax ([TC30 Explicit Resource Management](https://github.com/tc39/proposal-explicit-resource-management))
+
+
+## Installation
+
+```bash
+$ npm install postgresql-client --save
+```
+
+## Documentation
+Please read :small_orange_diamond: [DOCUMENTATION](DOCUMENTATION.md) :small_orange_diamond: for detailed usage.
+
+## Example usage
+
+### Establish a single connection, execute a simple query
+
+```ts
+import {Connection} from 'postgresql-client';
+// Create connection
+const connection = new Connection('postgres://localhost');
+// Connect to database server
+await connection.connect();
+
+// Execute query and fetch rows
+const result = await connection.query(
+    'select * from cities where name like $1',
+    {params: ['%york%']});
+const rows: any[] = result.rows;
+// Do what ever you want with rows
+
+// Disconnect from server
+await connection.close(); 
+```
+
+### Establish a pooled connection, create a cursor
+```ts
+import {Pool} from 'postgresql-client';
+
+// Create connection pool
+const db = new Pool({
+    host: 'postgres://localhost',
+    pool: {
+       min: 1,
+       max: 10,
+       idleTimeoutMillis: 5000
+    }
+});
+
+// Execute query and fetch cursor
+const result = await db.query(
+    'select * from cities where name like $1',
+    {params: ['%york%'], cursor: true});
+
+// Walk through the cursor, and do whatever you want with fetched rows
+const cursor = result.cursor;
+let row;
+while ((row = await cursor.next())) {
+  console.log(row);
+}
+// Close cursor, (Send connection back to the pool)
+await cursor.close();
+
+// Disconnect all connections and shutdown pool
+await db.close(); 
+```
+
+### Using prepared statements
+```ts
+import {DataTypeOIDs} from 'postgresql-client'; 
+
+// .....
+const statement = await connection.prepare( 
+    'insert into my_table(id, name) values ($1, $2)', {
+        paramTypes: [DataTypeOIDs.Int4, DataTypeOIDs.Varchar]
+    });
+
+for (let i = 0; i < 100; i++) {
+    await statement.execute({params: [i, ('name' + i)]});
+}
+await statement.close(); // When you done, close the statement to relase resources
+```
+
+#### Check [DOCUMENTATION](DOCUMENTATION.md) for other examples.
+
+
+
+## Type mappings
+The table below lists builtin data type mappings.
+
+| Posgtres type | JS type     | Receive     | Send   | 
+|---------------|:------------|-------------|--------|
+| bool          | boolean     | text,binary | binary | 
+| int2          | number      | text,binary | binary | 
+| int4          | number      | text,binary | binary | 
+| int8          | BigInt      | text,binary | binary | 
+| float4        | number      | text,binary | binary | 
+| float8        | number      | text,binary | binary | 
+| char          | string      | text,binary | binary | 
+| bpchar        | string      | text,binary | binary | 
+| varchar       | string      | text,binary | binary | 
+| date          | Date        | text,binary | binary | 
+| time          | Date        | text,binary | binary | 
+| timestamp     | Date        | text,binary | binary | 
+| timestamptz   | Date        | text,binary | binary | 
+| oid           | number      | text,binary | binary | 
+| bytea         | Buffer      | text,binary | binary | 
+| uuid          | string      | text,binary | binary | 
+| json          | object      | text,binary | binary | 
+| jsonb         | object      | text,binary | binary | 
+| xml           | string      | text,binary | binary | 
+| point         | Point       | text,binary | binary | 
+| circle        | Circle      | text,binary | binary | 
+| lseg          | Rectangle   | text,binary | binary | 
+| box           | Rectangle   | text,binary | binary | 
+| int2Vector    | number[]    | text,binary | binary | 
+| _bool         | boolean[]   | text,binary | binary | 
+| _int2         | number[]    | text,binary | binary | 
+| _int4         | number[]    | text,binary | binary | 
+| _int8         | BigInt[]    | text,binary | binary | 
+| _float4       | number[]    | text,binary | binary | 
+| _float8       | number[]    | text,binary | binary | 
+| _char         | string[]    | text,binary | binary | 
+| _bpchar       | string[]    | text,binary | binary | 
+| _varchar      | string[]    | text,binary | binary | 
+| _date         | Date[]      | text,binary | binary | 
+| _time         | Date[]      | text,binary | binary | 
+| _timestamp    | Date[]      | text,binary | binary | 
+| _timestamptz  | Date[]      | text,binary | binary | 
+| _uuid         | string[]    | text,binary | binary | 
+| _oid          | number[]    | text,binary | binary | 
+| _bytea        | Buffer[]    | text,binary | binary | 
+| _json         | object[]    | text,binary | binary | 
+| _jsonb        | object[]    | text,binary | binary | 
+| _xml          | string[]    | text,binary | binary | 
+| _point        | Point[]     | text,binary | binary | 
+| _circle       | Circle[]    | text,binary | binary | 
+| _lseg         | Rectangle[] | text,binary | binary | 
+| _box          | Rectangle[] | text,binary | binary | 
+| _int2Vector   | number[][]  | text,binary | binary | 
+
+
+## Support
+You can report bugs and discuss features on the [GitHub issues](https://github.com/panates/postgresql-client/issues) page
+When you open an issue please provide version of NodeJS and PostgreSQL server.
+
+## Node Compatibility
+- node >= 14.x
+ 
+  
+## License
+postgresql-client is available under [MIT](LICENSE) license.
+
+[npm-image]: https://img.shields.io/npm/v/postgresql-client
+[npm-url]: https://npmjs.org/package/postgresql-client
+[circleci-image]: https://circleci.com/gh/panates/postgresql-client/tree/master.svg?style=shield
+[circleci-url]: https://circleci.com/gh/panates/postgresql-client/tree/master
+[coveralls-image]: https://img.shields.io/coveralls/panates/postgresql-client/master.svg
+[coveralls-url]: https://coveralls.io/r/panates/postgresql-client
+[downloads-image]: https://img.shields.io/npm/dm/postgresql-client.svg
+[downloads-url]: https://npmjs.org/package/postgresql-client
+[gitter-image]: https://badges.gitter.im/panates/postgresql-client.svg
+[gitter-url]: https://gitter.im/panates/postgresql-client?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge
+[dependencies-image]: https://david-dm.org/panates/postgresql-client/status.svg
+[dependencies-url]:https://david-dm.org/panates/postgresql-client
+[devdependencies-image]: https://david-dm.org/panates/postgresql-client/dev-status.svg
+[devdependencies-url]:https://david-dm.org/panates/postgresql-client?type=dev
+[quality-image]: http://npm.packagequality.com/shield/postgresql-client.png
+[quality-url]: http://packagequality.com/#?package=postgresql-client

package/cjs/connection/bind-param.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BindParam = void 0;
+class BindParam {
+    constructor(oid, value) {
+        this.oid = oid;
+        this.value = value;
+    }
+}
+exports.BindParam = BindParam;

package/cjs/connection/connection.js

@@ -0,0 +1,279 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Connection = void 0;
+const constants_js_1 = require("../constants.js");
+const data_type_map_js_1 = require("../data-type-map.js");
+const safe_event_emitter_js_1 = require("../safe-event-emitter.js");
+const bind_param_js_1 = require("./bind-param.js");
+const intl_connection_js_1 = require("./intl-connection.js");
+const prepared_statement_js_1 = require("./prepared-statement.js");
+class Connection extends safe_event_emitter_js_1.SafeEventEmitter {
+    constructor(arg0, arg1) {
+        super();
+        this._notificationListeners = new safe_event_emitter_js_1.SafeEventEmitter();
+        this._closing = false;
+        if (arg0 && typeof arg0 === 'object' && typeof arg0.acquire === 'function') {
+            if (!(arg1 instanceof intl_connection_js_1.IntlConnection))
+                throw new TypeError('Invalid argument');
+            this._pool = arg0;
+            this._intlCon = arg1;
+        }
+        else {
+            this._intlCon = new intl_connection_js_1.IntlConnection(arg0);
+        }
+        this._intlCon.on('ready', (...args) => this.emit('ready', ...args));
+        this._intlCon.on('error', (...args) => this.emit('error', ...args));
+        this._intlCon.on('close', (...args) => this.emit('close', ...args));
+        this._intlCon.on('connecting', (...args) => this.emit('connecting', ...args));
+        this._intlCon.on('ready', (...args) => this.emit('ready', ...args));
+        this._intlCon.on('terminate', (...args) => this.emit('terminate', ...args));
+        this._intlCon.on('notification', (msg) => this._handleNotification(msg));
+    }
+    /**
+     * Returns configuration object
+     */
+    get config() {
+        return this._intlCon.config;
+    }
+    /**
+     * Returns true if connection is in a transaction
+     */
+    get inTransaction() {
+        return this._intlCon.inTransaction;
+    }
+    /**
+     * Returns current state of the connection
+     */
+    get state() {
+        return this._intlCon.state;
+    }
+    /**
+     * Returns processId of current session
+     */
+    get processID() {
+        return this._intlCon.processID;
+    }
+    /**
+     * Returns information parameters for current session
+     */
+    get sessionParameters() {
+        return this._intlCon.sessionParameters;
+    }
+    /**
+     * Returns secret key of current session
+     */
+    get secretKey() {
+        return this._intlCon.secretKey;
+    }
+    /**
+     * Connects to the server
+     */
+    async connect() {
+        await this._captureErrorStack(this._intlCon.connect());
+        if (this.state === constants_js_1.ConnectionState.READY)
+            this._closing = false;
+    }
+    /**
+     * Closes connection. You can define how long time the connection will
+     * wait for active queries before terminating the connection.
+     * On the end of the given time, it forces to close the socket and than emits `terminate` event.
+     *
+     * @param terminateWait {number} - Determines how long the connection will wait for active queries before terminating.
+     */
+    async close(terminateWait) {
+        this._notificationListeners.removeAllListeners();
+        this._intlCon.statementQueue.clearQueue();
+        if (this.state === constants_js_1.ConnectionState.CLOSED || this._closing)
+            return;
+        /* istanbul ignore next */
+        if (this.listenerCount('debug'))
+            this.emit('debug', {
+                location: 'Connection.close',
+                connection: this,
+                message: `[${this.processID}] closing`,
+            });
+        this._closing = true;
+        if (this._intlCon.refCount > 0 && typeof terminateWait === 'number' && terminateWait > 0) {
+            const startTime = Date.now();
+            return this._captureErrorStack(new Promise((resolve, reject) => {
+                /* istanbul ignore next */
+                if (this.listenerCount('debug'))
+                    this.emit('debug', {
+                        location: 'Connection.close',
+                        connection: this,
+                        message: `[${this.processID}] waiting active queries`,
+                    });
+                const timer = setInterval(() => {
+                    if (this._intlCon.refCount <= 0 || Date.now() > startTime + terminateWait) {
+                        clearInterval(timer);
+                        if (this._intlCon.refCount > 0) {
+                            /* istanbul ignore next */
+                            if (this.listenerCount('debug'))
+                                this.emit('debug', {
+                                    location: 'Connection.close',
+                                    connection: this,
+                                    message: `[${this.processID}] terminate`,
+                                });
+                            this.emit('terminate');
+                        }
+                        this._close().then(resolve).catch(reject);
+                    }
+                }, 50);
+            }));
+        }
+        await this._close();
+    }
+    /**
+     * Executes single or multiple SQL scripts using Simple Query protocol.
+     *
+     * @param sql {string} - SQL script that will be executed
+     * @param options {ScriptExecuteOptions} - Execute options
+     */
+    async execute(sql, options) {
+        return this._captureErrorStack(this._intlCon.execute(sql, options)).catch((e) => {
+            throw this._handleError(e, sql);
+        });
+    }
+    async query(sql, options) {
+        this._intlCon.assertConnected();
+        /* istanbul ignore next */
+        if (this.listenerCount('debug'))
+            this.emit('debug', {
+                location: 'Connection.query',
+                connection: this,
+                message: `[${this.processID}] query | ${sql}`,
+                sql,
+            });
+        const typeMap = options?.typeMap || data_type_map_js_1.GlobalTypeMap;
+        const paramTypes = options?.params?.map(prm => prm instanceof bind_param_js_1.BindParam ? prm.oid : typeMap.determine(prm));
+        const statement = await this.prepare(sql, { paramTypes, typeMap }).catch((e) => {
+            throw this._handleError(e, sql);
+        });
+        try {
+            const params = options?.params?.map(prm => (prm instanceof bind_param_js_1.BindParam ? prm.value : prm));
+            return await this._captureErrorStack(statement.execute({ ...options, params }));
+        }
+        finally {
+            await statement.close();
+        }
+    }
+    /**
+     * Creates a PreparedStatement instance
+     * @param sql {string} - SQL script that will be executed
+     * @param options {StatementPrepareOptions} - Options
+     */
+    async prepare(sql, options) {
+        /* istanbul ignore next */
+        if (this.listenerCount('debug'))
+            this.emit('debug', {
+                location: 'Connection.prepare',
+                connection: this,
+                message: `[${this.processID}] prepare | ${sql}`,
+                sql,
+            });
+        return await this._captureErrorStack(prepared_statement_js_1.PreparedStatement.prepare(this, sql, options));
+    }
+    /**
+     * Starts a transaction
+     */
+    startTransaction() {
+        return this._captureErrorStack(this._intlCon.startTransaction());
+    }
+    /**
+     * Commits current transaction
+     */
+    commit() {
+        return this._captureErrorStack(this._intlCon.commit());
+    }
+    /**
+     * Rolls back current transaction
+     */
+    rollback() {
+        return this._captureErrorStack(this._intlCon.rollback());
+    }
+    /**
+     * Starts transaction and creates a savepoint
+     * @param name {string} - Name of the savepoint
+     */
+    async savepoint(name) {
+        if (!this._intlCon.inTransaction)
+            await this._intlCon.startTransaction();
+        return this._captureErrorStack(this._intlCon.savepoint(name));
+    }
+    /**
+     * Rolls back current transaction to given savepoint
+     * @param name {string} - Name of the savepoint
+     */
+    rollbackToSavepoint(name) {
+        return this._captureErrorStack(this._intlCon.rollbackToSavepoint(name));
+    }
+    /**
+     * Releases savepoint
+     * @param name {string} - Name of the savepoint
+     */
+    releaseSavepoint(name) {
+        return this._captureErrorStack(this._intlCon.releaseSavepoint(name));
+    }
+    async listen(channel, callback) {
+        if (!/^[A-Z]\w+$/i.test(channel))
+            throw new TypeError(`Invalid channel name`);
+        const registered = !!this._notificationListeners.eventNames().length;
+        this._notificationListeners.on(channel, callback);
+        if (!registered)
+            await this._captureErrorStack(this.query('LISTEN ' + channel));
+    }
+    async unListen(channel) {
+        if (!/^[A-Z]\w+$/i.test(channel))
+            throw new TypeError(`Invalid channel name`);
+        this._notificationListeners.removeAllListeners(channel);
+        await this._captureErrorStack(this.query('UNLISTEN ' + channel));
+    }
+    async unListenAll() {
+        this._notificationListeners.removeAllListeners();
+        await this._captureErrorStack(this.query('UNLISTEN *'));
+    }
+    _handleNotification(msg) {
+        this.emit('notification', msg);
+        this._notificationListeners.emit(msg.channel, msg);
+    }
+    async _close() {
+        if (this._pool) {
+            await this._captureErrorStack(this._pool.release(this));
+            this.emit('release');
+        }
+        else
+            await this._captureErrorStack(this._intlCon.close());
+        this._closing = false;
+    }
+    _handleError(err, script) {
+        if (err.position) {
+            const i1 = script.lastIndexOf('\n', err.position) + 1;
+            let i2 = script.indexOf('\n', err.position);
+            if (i2 < 0)
+                i2 = Number.MAX_SAFE_INTEGER;
+            err.line = script.substring(i1, i2);
+            err.lineNr = [...script.substring(0, i1).matchAll(/\n/g)].length;
+            err.colNr = err.position - i1;
+            err.message +=
+                `\nAt line ${err.lineNr} column ${err.colNr}` +
+                    `\n |  ${err.line}\n |  ${' '.repeat(Math.max(err.colNr - 2, 0))}-^-`;
+        }
+        return err;
+    }
+    async _captureErrorStack(promise) {
+        const stack = new Error().stack;
+        return promise.catch(e => {
+            if (e instanceof Error && stack) {
+                e.stack = stack
+                    .split('\n')
+                    .filter(x => !x.includes('Connection._captureErrorStack'))
+                    .join('\n');
+            }
+            throw e;
+        });
+    }
+    [Symbol.asyncDispose]() {
+        return this.close();
+    }
+}
+exports.Connection = Connection;

package/cjs/connection/cursor.js

@@ -0,0 +1,93 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Cursor = void 0;
+const doublylinked_1 = __importDefault(require("doublylinked"));
+const power_tasks_1 = require("power-tasks");
+const safe_event_emitter_js_1 = require("../safe-event-emitter.js");
+const convert_row_to_object_js_1 = require("../util/convert-row-to-object.js");
+const parse_row_js_1 = require("../util/parse-row.js");
+class Cursor extends safe_event_emitter_js_1.SafeEventEmitter {
+    constructor(statement, portal, fields, parsers, queryOptions) {
+        super();
+        this._taskQueue = new power_tasks_1.TaskQueue({ concurrency: 1 });
+        this._rows = new doublylinked_1.default();
+        this._closed = false;
+        this._statement = statement;
+        this._portal = portal;
+        this._parsers = parsers;
+        this._queryOptions = queryOptions;
+        this.fields = fields;
+    }
+    get rowType() {
+        return this._queryOptions.objectRows ? 'object' : 'array';
+    }
+    get isClosed() {
+        return this._closed;
+    }
+    async next() {
+        if (!this._rows.length) {
+            if (this._closed)
+                return;
+            await this._fetchRows();
+        }
+        return this._rows.shift();
+    }
+    async fetch(nRows) {
+        const out = [];
+        if (this._closed)
+            return out;
+        for (let i = 0; i < nRows; i++) {
+            if (!this._rows.length)
+                await this._fetchRows();
+            if (this._rows.length)
+                out.push(this._rows.shift());
+            else
+                break;
+        }
+        return out;
+    }
+    async close() {
+        if (this._closed)
+            return;
+        await this._portal.close();
+        await this._statement.close();
+        this.emit('close');
+        this._closed = true;
+    }
+    async _fetchRows() {
+        if (this._closed)
+            return;
+        const portal = this._portal;
+        await this._taskQueue
+            .enqueue(async () => {
+            const queryOptions = this._queryOptions;
+            const r = await portal.execute(queryOptions.fetchCount || 100);
+            if (r && r.rows && r.rows.length) {
+                if (this._parsers) {
+                    const objectRows = queryOptions.objectRows;
+                    const fields = this.fields;
+                    const rows = r.rows;
+                    for (let i = 0; i < rows.length; i++) {
+                        const row = rows[i];
+                        (0, parse_row_js_1.parseRow)(this._parsers, row, this._queryOptions);
+                        if (objectRows)
+                            rows[i] = (0, convert_row_to_object_js_1.convertRowToObject)(fields, row);
+                    }
+                }
+                this._rows.push(...r.rows);
+                this.emit('fetch', r.rows);
+            }
+            else {
+                await this.close();
+            }
+        })
+            .toPromise();
+    }
+    [Symbol.asyncDispose]() {
+        return this.close();
+    }
+}
+exports.Cursor = Cursor;