From 38093f67924eaf7a3710e08ed5bc91f84fd3920f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Eray=20Hano=C4=9Flu?= Date: Wed, 5 Oct 2022 09:54:36 +0300 Subject: [PATCH] Updated documentation --- DOCUMENTATION.md | 148 ++++++++++++++++++++++++++++++++++++++++++++-- src/Connection.ts | 5 +- src/Pool.ts | 6 +- 3 files changed, 148 insertions(+), 11 deletions(-) diff --git a/DOCUMENTATION.md b/DOCUMENTATION.md index 951a7d7..3190320 100644 --- a/DOCUMENTATION.md +++ b/DOCUMENTATION.md @@ -666,13 +666,102 @@ await connection.rollbackToSavepoint('my_save_point'); await connection.close(); ``` -#### Events +##### .listen() + +Registers the connection as a listener on the notification channel. + +`listen(channel: string, callback: NotificationCallback): Promise` + +| Argument | Type | Default | Description | +|--------------|-------------| ---------|----------------------------| +| channel | string | | Name of the channel | +| callback | NotificationCallback | | Listener callback function | + +```ts +await connection.listen('my_event', (msg: NotificationMessage)=>{ + console.log(msg.channel+ ' event fired!. processId:', msg.processId, ' payload:', msg.payload); +}); +``` + + +##### .unListen() + +Removes existing registration for NOTIFY events for given channel. + +`unListen(channel: string): Promise` + +| Argument | Type | Default | Description | +|--------------|-------------| ---------|----------------------------| +| channel | string | | Name of the channel | + +```ts +await connection.unListen('my_event'); +``` + + + +##### .unListenAll() + +Removes existing registration for NOTIFY events for all channels. + +`unListenAll(): Promise` + + +```ts +await connection.unListenAll(); +``` + + + +### Events + +#### ___error___ + + Triggered when an error occurs. + + `(err: Error) => void` + +| Argument | Type | Default | Description | +|--------|-------| ---------|----------------| +| err | Error | | Error instance | + + +##### ___close___ + + Triggered when after connection closed. + + `() => void` + + +#### ___connecting___ + + Triggered when establishing a connection. + + `() => void` + +#### ___ready___ + + Triggered when connection is ready. + + `() => void` + + +#### ___terminate___ + + Triggered when the connection is terminated unintentionally. + + `() => void` + +#### ___notification___ + + Triggered when notification is received from a registered channel. + + `(msg: NotificationMessage) => void` + +| Argument | Type | Default | Description | +|--------|-------| ---------|-------------------------------| +| msg | NotificationMessage | | Notification message instance | -* error -* close -* connecting -* ready -* terminate ### 2.1.2. Pool @@ -810,6 +899,53 @@ Releases a connection `release(connection: Connection): Promise` + + +##### .listen() + +Registers the pool as a listener on the notification channel. + +`listen(channel: string, callback: NotificationCallback): Promise` + +| Argument | Type | Default | Description | +|--------------|-------------| ---------|----------------------------| +| channel | string | | Name of the channel | +| callback | NotificationCallback | | Listener callback function | + +```ts +await pool.listen('my_event', (msg: NotificationMessage)=>{ + console.log(msg.channel+ ' event fired!. processId:', msg.processId, ' payload:', msg.payload); +}); +``` + + +##### .unListen() + +Removes existing registration for NOTIFY events for given channel. + +`unListen(channel: string): Promise` + +| Argument | Type | Default | Description | +|--------------|-------------| ---------|----------------------------| +| channel | string | | Name of the channel | + +```ts +await pool.unListen('my_event'); +``` + + +##### .unListenAll() + +Removes existing registration for NOTIFY events for all channels. + +`unListenAll(): Promise` + + +```ts +await pool.unListenAll(); +``` + + ### 2.1.3. Cursor ### 2.1.4. PreparedStatement diff --git a/src/Connection.ts b/src/Connection.ts index 6891543..9e27eed 100644 --- a/src/Connection.ts +++ b/src/Connection.ts @@ -22,6 +22,7 @@ import { SafeEventEmitter } from "./SafeEventEmitter.js"; const debug = _debug("pgc:intlcon"); export type NotificationMessage = Protocol.NotificationResponseMessage; +export type NotificationCallback = (msg: NotificationMessage) => any; export class Connection extends SafeEventEmitter { private readonly _pool?: Pool; @@ -217,11 +218,11 @@ export class Connection extends SafeEventEmitter { return this._intlCon.releaseSavepoint(name); } - async listen(channel: string, fn: (msg: NotificationMessage) => any) { + async listen(channel: string, callback: NotificationCallback) { if (!/^[A-Z]\w+$/i.test(channel)) throw new TypeError(`Invalid channel name`); const registered = !!this._notificationListeners.eventNames().length; - this._notificationListeners.on(channel, fn); + this._notificationListeners.on(channel, callback); if (!registered) await this.query('LISTEN ' + channel); } diff --git a/src/Pool.ts b/src/Pool.ts index 09fa1dc..3523e61 100644 --- a/src/Pool.ts +++ b/src/Pool.ts @@ -6,7 +6,7 @@ import { } from "lightning-pool"; import { coerceToBoolean, coerceToInt } from "putil-varhelpers"; import { getIntlConnection } from "./common.js"; -import { Connection, NotificationMessage } from "./Connection.js"; +import { Connection, NotificationCallback } from "./Connection.js"; import { ConnectionState, PoolConfiguration, @@ -159,10 +159,10 @@ export class Pool extends SafeEventEmitter { return this._pool.releaseAsync(getIntlConnection(connection)); } - async listen(channel: string, fn: (msg: NotificationMessage) => any) { + async listen(channel: string, callback: NotificationCallback) { if (!/^[A-Z]\w+$/i.test(channel)) throw new TypeError(`Invalid channel name`); - this._notificationListeners.on(channel, fn); + this._notificationListeners.on(channel, callback); await this._initNotificationConnection(); }