Updated documentation

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<void>`
+
+| 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<void>`
+
+| 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<void>`
+
+
+```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<void>`
 
+
+
+##### .listen()
+
+Registers the pool as a listener on the notification channel.
+
+`listen(channel: string, callback: NotificationCallback): Promise<void>`
+
+| 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<void>`
+
+| 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<void>`
+
+
+```ts
+await pool.unListenAll();
+```
+
+
 ### 2.1.3. Cursor
 
 ### 2.1.4. PreparedStatement

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);
   }

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();
   }