@nestjs-kitchen/connextion-postgres 2.0.6 → 2.1.1

package/README.md

@@ -9,6 +9,13 @@ A flexible module to provide [node-postgres](https://node-postgres.com/) interfa
 
 ---
 
+## Feature
+
+- ✅ Transaction support
+- ✅ High availability (HA) support
+- ✅ Type intelligent
+
+
 ## Install
 
 ```bash
@@ -174,6 +181,40 @@ class SampleService {
 }
 ```
 
+### High availability (HA)
+
+Register postgres connection instance with multiple host.
+
+When enabled, `instance1` will attempt to connect db with each hosts/ports in sequence until a connection is successfully established.
+
+**Note: This is a temporary workaround and will change once `node-postgres` internally supports multiple hosts.**
+
+```typescript
+@Module({
+  imports: [
+    PostgresModule.register({
+      connections: [
+        {
+          name: 'instance1',
+          hosts: [
+            {
+              host: 'instance_1_host_1',
+              port: 1
+            },
+            {
+              host: 'instance_1_host_2',
+              port: 2
+            }
+          ]
+        }
+      ]
+    })
+  ],
+  providers: [SampleService]
+})
+export class SampleModule {} 
+```
+
 ## License
 
 MIT License

package/dist/define-postgres.d.ts

@@ -1,8 +1,7 @@
-import { type AsyncModuleOptions, type ConnectionOptionName, type ConnextionInstance, type ModuleOptions } from '@nestjs-kitchen/connextion';
 import type { DynamicModule, Type } from '@nestjs/common';
+import { type AsyncModuleOptions, type ConnectionOptionName, type ConnextionInstance, type ModuleOptions } from '@nestjs-kitchen/connextion';
 import { DEFAULT_INSTANCE_NAME } from './constants';
 import { PostgresInstance } from './postgres.instance';
-import type { PostgresInstanceOptions } from './types';
 /**
  * Creates a set of Postgres services, modules, and their associated Transaction decorator.
  */
@@ -22,8 +21,8 @@ export declare const definePostgres: <T extends string = typeof DEFAULT_INSTANCE
      */
     PostgresModule: {
         new (): {};
-        register(options: ModuleOptions<T, PostgresInstanceOptions>): DynamicModule;
-        registerAsync(options: AsyncModuleOptions<T, PostgresInstanceOptions>): DynamicModule;
+        register(options: ModuleOptions<T, import("./types").Options>): DynamicModule;
+        registerAsync(options: AsyncModuleOptions<T, import("./types").Options>): DynamicModule;
     };
     /**
      * A decorator that automatically enables transactions for the specific Postgres

package/dist/postgres.instance.d.ts

@@ -1,19 +1,21 @@
 import { AsyncLocalStorage } from 'node:async_hooks';
 import { ConnextionInstance } from '@nestjs-kitchen/connextion';
-import { type PoolClient, type QueryArrayConfig, type QueryArrayResult, type QueryConfig, type QueryConfigValues, type QueryResult, type QueryResultRow, type Submittable } from 'pg';
+import { Pool, type PoolClient, type QueryArrayConfig, type QueryArrayResult, type QueryConfig, type QueryConfigValues, type QueryResult, type QueryResultRow, type Submittable } from 'pg';
 import { ALS, GET_CLIENT } from './constants';
-import type { ALSType, PostgresInstanceOptions } from './types';
+import type { ALSType, Options, PostgresInstanceOptions } from './types';
 export declare class PostgresInstance extends ConnextionInstance<PostgresInstanceOptions> {
-    private pool;
+    private pools;
     private logger;
-    private debug;
+    private optionsArray;
     [ALS]: AsyncLocalStorage<ALSType>;
     private listener1;
     private listener2;
     constructor(name: string, options?: PostgresInstanceOptions);
     private end;
-    dispose(): Promise<void> | undefined;
-    create(options: PostgresInstanceOptions): void;
+    dispose(): Promise<void>;
+    createPool(options: Options): Pool | undefined;
+    create(options: PostgresInstanceOptions): Promise<void>;
+    private getAndTestClient;
     [GET_CLIENT](): Promise<PoolClient>;
     query<T extends Submittable>(queryStream: T): Promise<T>;
     query<R extends any[] = any[], I = any[]>(queryConfig: QueryArrayConfig<I>, values?: QueryConfigValues<I>): Promise<QueryArrayResult<R>>;

package/dist/postgres.instance.js

@@ -3,8 +3,8 @@ var _a;
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PostgresInstance = void 0;
 const node_async_hooks_1 = require("node:async_hooks");
-const connextion_1 = require("@nestjs-kitchen/connextion");
 const common_1 = require("@nestjs/common");
+const connextion_1 = require("@nestjs-kitchen/connextion");
 const pg_1 = require("pg");
 const uid_1 = require("uid");
 const constants_1 = require("./constants");
@@ -13,7 +13,8 @@ const utils_1 = require("./utils");
 class PostgresInstance extends connextion_1.ConnextionInstance {
     constructor(name, options) {
         super(name, options);
-        this.pool = undefined;
+        this.pools = [];
+        this.optionsArray = [];
         // Every instance should have its own als to avoid accessing wrong context.
         this[_a] = new node_async_hooks_1.AsyncLocalStorage();
         this.listener1 = (_cli) => {
@@ -23,10 +24,9 @@ class PostgresInstance extends connextion_1.ConnextionInstance {
             this.logger.error(err);
         };
         this.logger = new common_1.Logger(`Postgres][${name}`);
-        this.debug = Boolean(process.env[constants_1.CONNEXTION_POSTGRES_DEBUG]) || options?.debug;
     }
     async end(pool) {
-        if (!pool) {
+        if (!pool || pool.ending) {
             return;
         }
         try {
@@ -38,60 +38,90 @@ class PostgresInstance extends connextion_1.ConnextionInstance {
             this.logger.error(error);
         }
     }
-    dispose() {
-        if (!this.pool) {
+    async dispose() {
+        if (!this.pools) {
             return;
         }
-        const pool = this.pool;
-        this.pool = undefined;
-        return this.end(pool);
+        const pools = this.pools;
+        this.pools = [];
+        for (const pool of pools) {
+            await this.end(pool);
+        }
+        return;
     }
-    create(options) {
-        this.dispose();
+    createPool(options) {
         try {
             const pool = new pg_1.Pool(options);
             //https://github.com/brianc/node-postgres/issues/2439#issuecomment-757691278
             pool.on('connect', this.listener1);
             pool.on('error', this.listener2);
-            this.pool = pool;
+            return pool;
         }
         catch (error) {
             this.logger.error(error.message);
         }
     }
-    async [(_a = constants_1.ALS, constants_1.GET_CLIENT)]() {
-        if (!this.pool) {
-            throw new errors_1.PostgresError('pool not found');
+    async create(options) {
+        await this.dispose();
+        this.optionsArray = (0, utils_1.normalizeOptions)(options);
+        if (!this.optionsArray.length) {
+            throw new Error('cannot find available options');
         }
-        if (!this.debug) {
-            const [client, err] = await (0, utils_1.plainPromise)(this.pool.connect());
-            if (err) {
-                throw new errors_1.PostgresError(err, err);
-            }
-            if (!client) {
-                throw new errors_1.PostgresError('client not found');
-            }
+        this.pools = this.optionsArray.map((options) => this.createPool(options)).filter(Boolean);
+    }
+    async getAndTestClient(promise) {
+        const client = await promise;
+        if (!client) {
             return client;
         }
-        // Debug mode
-        const logger = (0, utils_1.createDebugLogger)(this.logger.debug.bind(this.logger), this.debug);
-        const debug = (0, utils_1.debugFactroy)(this.name, (0, uid_1.uid)(21), logger);
-        const [client, err] = await (0, utils_1.plainPromise)(debug.pool.connect(this.pool.connect.bind(this.pool))());
-        if (err) {
-            throw new errors_1.PostgresError(err, err);
+        try {
+            // test if current client is still alive.
+            await client.query('SELECT 1;');
+            return client;
         }
-        if (!client) {
-            throw new errors_1.PostgresError('client not found');
+        catch (error) {
+            client.release(error);
+            throw error;
         }
-        return new Proxy(client, {
-            get(target, prop, receiver) {
-                const value = Reflect.get(target, prop, receiver);
-                if (debug.client[prop]) {
-                    return debug.client[prop](value.bind(target));
+    }
+    async [(_a = constants_1.ALS, constants_1.GET_CLIENT)]() {
+        let error = 'failed to get client';
+        for (let i = 0; i < this.optionsArray.length; i++) {
+            const pool = this.pools[i];
+            const debugMode = this.optionsArray[i].debug || !!process.env[constants_1.CONNEXTION_POSTGRES_DEBUG];
+            if (!debugMode) {
+                const [client, err] = await (0, utils_1.plainPromise)(this.getAndTestClient(pool.connect()));
+                if (client) {
+                    return client;
+                }
+                error = err || 'client not found';
+                if (!(0, utils_1.isFailoverRequired)(error)) {
+                    break;
                 }
-                return value;
             }
-        });
+            else {
+                // Debug mode
+                const logger = (0, utils_1.createDebugLogger)(this.logger.debug.bind(this.logger), debugMode);
+                const debug = (0, utils_1.debugFactroy)(this.name, (0, uid_1.uid)(21), `${this.optionsArray[i].host}:${this.optionsArray[i].port}`, logger);
+                const [client, err] = await (0, utils_1.plainPromise)(this.getAndTestClient(debug.pool.connect(pool.connect.bind(pool))()));
+                if (client) {
+                    return new Proxy(client, {
+                        get(target, prop, receiver) {
+                            const value = Reflect.get(target, prop, receiver);
+                            if (debug.client[prop]) {
+                                return debug.client[prop](value.bind(target));
+                            }
+                            return value;
+                        }
+                    });
+                }
+                error = err || 'client not found';
+                if (!(0, utils_1.isFailoverRequired)(error)) {
+                    break;
+                }
+            }
+        }
+        throw new errors_1.PostgresError(error, typeof error === 'string' ? undefined : error);
     }
     async query(...rest) {
         if (!rest.length) {
@@ -116,7 +146,7 @@ class PostgresInstance extends connextion_1.ConnextionInstance {
             throw err;
         }
         finally {
-            client.release(err ?? true);
+            client.release(err);
         }
     }
     async transactionQueryWithConfig(...rest) {
@@ -156,13 +186,13 @@ class PostgresInstance extends connextion_1.ConnextionInstance {
                 };
                 const onEnd = () => {
                     res.off('error', onError);
-                    client.release(true);
+                    client.release();
                 };
                 res.once('end', onEnd);
                 res.once('error', onError);
             }
             else {
-                client.release(err ?? true);
+                client.release(err);
             }
         }
     }

package/dist/transaction.js

@@ -62,7 +62,7 @@ const createTransaction = (Postgres) => {
                         }
                     }
                 };
-                const releaseClients = async (err) => runWithClients((client) => client.release(err ?? true));
+                const releaseClients = async (err) => runWithClients((client) => client.release(err));
                 // Ensure all clients are available.
                 const [_, initErr] = await (0, utils_1.plainPromise)(initClients());
                 if (initErr) {

package/dist/types.d.ts

@@ -4,6 +4,19 @@ export interface ALSType {
     client: Promise<PoolClient>;
     queries: Promise<ALSQueryType>[];
 }
-export type PostgresInstanceOptions = PoolConfig & {
+export type Options = PoolConfig & {
     debug?: boolean | ((data: Record<any, any>) => void);
+} & {
+    /**
+     * Enable multi host connections for `High Availability` (HA).
+     *
+     *  This will find and switch to connect the availabe host.
+     *
+     * If provided, will ignore `Options.host` and `Options.port`
+     */
+    hosts?: {
+        host: PoolConfig['host'];
+        port: PoolConfig['port'];
+    }[];
 };
+export type PostgresInstanceOptions = Options;

package/dist/utils.d.ts

@@ -1,4 +1,5 @@
 import { type PoolClient, type Submittable } from 'pg';
+import type { Options } from './types';
 export declare const isSubmittable: (val: any) => val is Submittable;
 export declare const isObject: (val: any) => val is object;
 export declare const normalizeStrings: (strs?: string[]) => string[];
@@ -9,7 +10,7 @@ export declare const getCurrentDateStr: () => string;
 export declare const formatArray: (arr?: any) => string;
 export declare const extraceQueryTextAndValues: (...rest: any[]) => [text: string, values: any[]];
 export declare const createDebugLogger: (defaultLogger: (...rest: any) => void, customFormater?: Boolean | ((data: Record<any, any>) => void)) => (data: Record<any, any>) => void;
-export declare const debugFactroy: (name: string, queryId: string, logger: (data: Record<any, any>) => void) => {
+export declare const debugFactroy: (name: string, queryId: string, host: string, logger: (data: Record<any, any>) => void) => {
     pool: {
         connect: <T extends () => Promise<PoolClient>>(callback: T) => () => Promise<PoolClient>;
     };
@@ -26,3 +27,7 @@ export declare const withResolvers: <T>() => {
     resolve: (value: T | PromiseLike<T>) => void;
     reject: (reason?: any) => void;
 };
+export declare const normalizeOptions: (options: Options) => Omit<Options, "hosts">[];
+export declare const isFailoverRequired: (err?: {
+    code?: string;
+}) => boolean;

package/dist/utils.js

@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.withResolvers = exports.setTransactionMetdata = exports.getTransactionMetdata = exports.copyMethodMetadata = exports.debugFactroy = exports.createDebugLogger = exports.extraceQueryTextAndValues = exports.formatArray = exports.getCurrentDateStr = exports.printTable = exports.truncateString = exports.plainPromise = exports.normalizeStrings = exports.isObject = exports.isSubmittable = void 0;
+exports.isFailoverRequired = exports.normalizeOptions = exports.withResolvers = exports.setTransactionMetdata = exports.getTransactionMetdata = exports.copyMethodMetadata = exports.debugFactroy = exports.createDebugLogger = exports.extraceQueryTextAndValues = exports.formatArray = exports.getCurrentDateStr = exports.printTable = exports.truncateString = exports.plainPromise = exports.normalizeStrings = exports.isObject = exports.isSubmittable = void 0;
 const dayjs_1 = __importDefault(require("dayjs"));
 const constants_1 = require("./constants");
 const isSubmittable = (val) => {
@@ -87,7 +87,7 @@ const createDebugLogger = (defaultLogger, customFormater) => {
     };
 };
 exports.createDebugLogger = createDebugLogger;
-const debugFactroy = (name, queryId, logger) => {
+const debugFactroy = (name, queryId, host, logger) => {
     return {
         pool: {
             connect: (callback) => {
@@ -104,12 +104,13 @@ const debugFactroy = (name, queryId, logger) => {
                     finally {
                         logger({
                             Instance: name,
+                            Host: host,
                             Client: queryId,
                             Type: 'Request new client',
                             'Started On': startOn,
                             'Ended On': (0, exports.getCurrentDateStr)(),
                             Status: err ? 'Failed' : 'Successful',
-                            Error: err
+                            Error: err?.code ? `[${err.code}]${err}` : err
                         });
                     }
                 };
@@ -126,6 +127,7 @@ const debugFactroy = (name, queryId, logger) => {
                         rest[0].on('end', () => {
                             logger({
                                 Instance: name,
+                                Host: host,
                                 Client: queryId,
                                 Type: 'Submittable',
                                 Text: text,
@@ -138,6 +140,7 @@ const debugFactroy = (name, queryId, logger) => {
                         rest[0].on('error', (err) => {
                             logger({
                                 Instance: name,
+                                Host: host,
                                 Client: queryId,
                                 Type: 'Submittable',
                                 Text: text,
@@ -145,7 +148,7 @@ const debugFactroy = (name, queryId, logger) => {
                                 'Started On': startOn,
                                 'Ended On': (0, exports.getCurrentDateStr)(),
                                 Status: 'Failed',
-                                Error: err
+                                Error: err?.code ? `[${err.code}]${err}` : err
                             });
                         });
                     }
@@ -160,6 +163,7 @@ const debugFactroy = (name, queryId, logger) => {
                         if (!submittable) {
                             logger({
                                 Instance: name,
+                                Host: host,
                                 Client: queryId,
                                 Type: 'Query',
                                 Text: text,
@@ -167,7 +171,7 @@ const debugFactroy = (name, queryId, logger) => {
                                 'Started On': startOn,
                                 'Ended On': (0, exports.getCurrentDateStr)(),
                                 Status: err ? 'Failed' : 'Successful',
-                                Error: err
+                                Error: err?.code ? `[${err.code}]${err}` : err
                             });
                         }
                     }
@@ -187,12 +191,13 @@ const debugFactroy = (name, queryId, logger) => {
                     finally {
                         logger({
                             Instance: name,
+                            Host: host,
                             Client: queryId,
                             Type: 'Release client',
                             'Started On': startOn,
                             'Ended On': (0, exports.getCurrentDateStr)(),
                             Status: err ? 'Failed' : 'Successful',
-                            Error: err
+                            Error: err?.code ? `[${err.code}]${err}` : err
                         });
                     }
                 };
@@ -228,3 +233,42 @@ const withResolvers = () => {
     return { promise, resolve: resolve, reject: reject };
 };
 exports.withResolvers = withResolvers;
+const normalizeOptions = (options) => {
+    const { host, hosts, port, ...rest } = options;
+    if (hosts) {
+        return hosts.map((ele) => ({
+            ...rest,
+            ...ele
+        }));
+    }
+    return [
+        {
+            ...rest,
+            host,
+            port
+        }
+    ];
+};
+exports.normalizeOptions = normalizeOptions;
+const failoverErrorCodes = new Set([
+    'ECONNREFUSED',
+    'ETIMEDOUT',
+    'EHOSTUNREACH',
+    'ENOTFOUND',
+    'EAI_AGAIN',
+    'ECONNRESET',
+    'EPIPE',
+    '57P01',
+    '57P02',
+    '57P03',
+    '55P03',
+    '55000',
+    '54000',
+    '53300',
+    '08006',
+    'XX000'
+]);
+const isFailoverRequired = (err) => {
+    return !!(err?.code && failoverErrorCodes.has(`${err.code}`));
+};
+exports.isFailoverRequired = isFailoverRequired;

package/package.json

@@ -2,7 +2,7 @@
   "name": "@nestjs-kitchen/connextion-postgres",
   "private": false,
   "description": "A flexible module to provide node-postgres interface in NextJS.",
-  "version": "2.0.6",
+  "version": "2.1.1",
   "homepage": "https://github.com/yikenman/nestjs-kitchen",
   "repository": "https://github.com/yikenman/nestjs-kitchen",
   "author": "yikenman",
@@ -23,15 +23,15 @@
   },
   "devDependencies": {
     "@nestjs/testing": "^11.0.0",
-    "@types/jest": "^29.5.14",
+    "@types/jest": "^30.0.0",
     "@types/node": "^22.13.9",
-    "jest": "^29.7.0",
+    "jest": "^30.0.5",
     "rimraf": "^6.0.1",
     "ts-jest": "^29.3.0",
     "ts-node": "^10.9.2",
     "tsconfig-paths": "^4.2.0",
     "typescript": "^5.8.2",
-    "@nestjs-kitchen/connextion": "2.0.5"
+    "@nestjs-kitchen/connextion": "2.0.6"
   },
   "engines": {
     "node": ">=20.13.0"
@@ -51,7 +51,7 @@
     "@types/pg": "^8.11.10",
     "pg": "^8.13.1",
     "reflect-metadata": "^0.2.2",
-    "@nestjs-kitchen/connextion": "2.0.5"
+    "@nestjs-kitchen/connextion": "2.0.6"
   },
   "scripts": {
     "build": "rimraf dist && tsc -p tsconfig.build.json",