@quazex/nestjs-postgres 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 quazex
+
+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,115 @@
+# NestJS Postgres Module
+
+Core features:
+
+- Based on [postgres library for NodeJS](https://github.com/porsager/postgres);
+- Covered with unit and e2e tests;
+- Basic module without unnecessary boilerplate.
+
+## Installation
+
+```sh
+npm install @quazex/nestjs-postgres postgres
+```
+
+## Usage
+
+### Importing the Module
+
+```typescript
+import { Module } from '@nestjs/common';
+import { PostgresModule } from '@quazex/nestjs-postgres';
+
+@Module({
+  imports: [
+    PostgresModule.forRoot({
+      host: 'localhost',
+      port: 5432,
+      user: 'test',
+      password: 'test',
+      database: 'test',
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+### Injecting the Client
+
+```typescript
+import { Injectable } from '@nestjs/common';
+import { InjectPostgres } from '@quazex/nestjs-postgres';
+import type { Sql } from 'postgres';
+
+@Injectable()
+export class DatabaseService {
+  constructor(@InjectPostgres() private readonly sql: Sql) {}
+
+  async insert(document: object) {
+    await this.sql`INSERT INTO table ${this.sql(document)}`;
+  }
+
+  async select(id: string) {
+    const [row] = await this.sql`SELECT * FROM table WHERE id = ${id}`;
+    return row;
+  }
+}
+```
+
+### Async Configuration
+
+```typescript
+import { Module } from '@nestjs/common';
+import { PostgresModule } from '@quazex/nestjs-postgres';
+
+@Module({
+  imports: [
+    PostgresModule.forRootAsync({
+      useFactory: (config: SomeConfigProvider) => ({
+        host: config.PG_HOST,
+        port: config.PG_PORT,
+        user: config.PG_USER,
+        password: config.PG_PASSWORD,
+        database: config.PG_DATABASE,
+      }),
+      inject: [
+        SomeConfigProvider,
+      ],
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+### Connection and graceful shutdown
+
+By default, this module doesn't manage the client connection on application shutdown. You can read more about lifecycle hooks on the NestJS [documentation page](https://docs.nestjs.com/fundamentals/lifecycle-events#application-shutdown).
+
+```typescript
+// main.ts
+const app = await NestFactory.create(AppModule);
+
+app.enableShutdownHooks();
+
+await app.listen(process.env.PORT ?? 3000);
+```
+
+```typescript
+// app.bootstrap.ts
+import { Injectable, OnApplicationShutdown } from '@nestjs/common';
+import { InjectPostgres } from '@quazex/nestjs-postgres';
+import type { Sql } from 'postgres';
+
+@Injectable()
+export class AppBootstrap implements OnApplicationShutdown {
+  constructor(@InjectPostgres() private readonly sql: Sql) {}
+
+  public async onApplicationShutdown(): Promise<void> {
+    await this.sql.end();
+  }
+}
+```
+
+## License
+
+MIT

package/lib/index.d.ts

@@ -0,0 +1,6 @@
+export * from './postgres.decorators';
+export * from './postgres.interfaces';
+export * from './postgres.module';
+export * from './postgres.providers';
+export * from './postgres.tokens';
+export * from './postgres.types';

package/lib/index.js

@@ -0,0 +1,22 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./postgres.decorators"), exports);
+__exportStar(require("./postgres.interfaces"), exports);
+__exportStar(require("./postgres.module"), exports);
+__exportStar(require("./postgres.providers"), exports);
+__exportStar(require("./postgres.tokens"), exports);
+__exportStar(require("./postgres.types"), exports);

package/lib/postgres.decorators.d.ts

@@ -0,0 +1,2 @@
+import { Inject } from '@nestjs/common';
+export declare const InjectPostgres: () => ReturnType<typeof Inject>;

package/lib/postgres.decorators.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InjectPostgres = void 0;
+const common_1 = require("@nestjs/common");
+const postgres_tokens_1 = require("./postgres.tokens");
+const InjectPostgres = () => ((0, common_1.Inject)(postgres_tokens_1.PostgresTokens.CLIENT));
+exports.InjectPostgres = InjectPostgres;

package/lib/postgres.interfaces.d.ts

@@ -0,0 +1,10 @@
+import { InjectionToken, ModuleMetadata, OptionalFactoryDependency, Type } from '@nestjs/common';
+import { TPostgresOptions } from './postgres.types';
+export interface TPostgresOptionsFactory {
+    createPostgresOptions(): Promise<TPostgresOptions> | TPostgresOptions;
+}
+export interface TPostgresAsyncOptions extends Pick<ModuleMetadata, 'imports'> {
+    inject?: Array<InjectionToken | OptionalFactoryDependency>;
+    useExisting?: Type<TPostgresOptionsFactory>;
+    useFactory?: (...args: any[]) => Promise<TPostgresOptions> | TPostgresOptions;
+}

package/lib/postgres.interfaces.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/postgres.module.d.ts

@@ -0,0 +1,11 @@
+import { DynamicModule, OnApplicationShutdown } from '@nestjs/common';
+import { Sql } from 'postgres';
+import { TPostgresAsyncOptions } from './postgres.interfaces';
+import { TPostgresOptions } from './postgres.types';
+export declare class PostgresModule implements OnApplicationShutdown {
+    private readonly client;
+    constructor(client: Sql);
+    onApplicationShutdown(): Promise<void>;
+    static forRoot(options: TPostgresOptions): DynamicModule;
+    static forRootAsync(asyncOptions: TPostgresAsyncOptions): DynamicModule;
+}

package/lib/postgres.module.js

@@ -0,0 +1,64 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+var PostgresModule_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PostgresModule = void 0;
+const postgres_decorators_1 = require("./postgres.decorators");
+const postgres_providers_1 = require("./postgres.providers");
+let PostgresModule = PostgresModule_1 = class PostgresModule {
+    constructor(client) {
+        this.client = client;
+    }
+    async onApplicationShutdown() {
+        await this.client.end();
+    }
+    static forRoot(options) {
+        const optionsProvider = postgres_providers_1.PostgresProviders.getOptions(options);
+        const clientProvider = postgres_providers_1.PostgresProviders.getClient();
+        const dynamicModule = {
+            module: PostgresModule_1,
+            global: true,
+            providers: [
+                optionsProvider,
+                clientProvider,
+            ],
+            exports: [
+                clientProvider,
+            ],
+        };
+        return dynamicModule;
+    }
+    static forRootAsync(asyncOptions) {
+        const optionsProvider = postgres_providers_1.PostgresProviders.getAsyncOptions(asyncOptions);
+        const clientProvider = postgres_providers_1.PostgresProviders.getClient();
+        const dynamicModule = {
+            module: PostgresModule_1,
+            global: true,
+            imports: asyncOptions.imports,
+            providers: [
+                optionsProvider,
+                clientProvider,
+            ],
+            exports: [
+                clientProvider,
+            ],
+        };
+        return dynamicModule;
+    }
+};
+exports.PostgresModule = PostgresModule;
+exports.PostgresModule = PostgresModule = PostgresModule_1 = __decorate([
+    __param(0, (0, postgres_decorators_1.InjectPostgres)()),
+    __metadata("design:paramtypes", [Function])
+], PostgresModule);

package/lib/postgres.providers.d.ts

@@ -0,0 +1,9 @@
+import { FactoryProvider, Provider, ValueProvider } from '@nestjs/common';
+import { Sql } from 'postgres';
+import { TPostgresAsyncOptions } from './postgres.interfaces';
+import { TPostgresOptions } from './postgres.types';
+export declare class PostgresProviders {
+    static getOptions(options: TPostgresOptions): ValueProvider<TPostgresOptions>;
+    static getAsyncOptions(options: TPostgresAsyncOptions): Provider<TPostgresOptions>;
+    static getClient(): FactoryProvider<Sql>;
+}

package/lib/postgres.providers.js

@@ -0,0 +1,46 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PostgresProviders = void 0;
+const postgres_1 = __importDefault(require("postgres"));
+const postgres_tokens_1 = require("./postgres.tokens");
+class PostgresProviders {
+    static getOptions(options) {
+        return {
+            provide: postgres_tokens_1.PostgresTokens.OPTIONS,
+            useValue: options,
+        };
+    }
+    static getAsyncOptions(options) {
+        if (options.useFactory) {
+            return {
+                provide: postgres_tokens_1.PostgresTokens.OPTIONS,
+                useFactory: options.useFactory,
+                inject: options.inject,
+            };
+        }
+        if (options.useExisting) {
+            return {
+                provide: postgres_tokens_1.PostgresTokens.OPTIONS,
+                useFactory: async (factory) => {
+                    const client = await factory.createPostgresOptions();
+                    return client;
+                },
+                inject: [options.useExisting],
+            };
+        }
+        throw new Error('Must provide useFactory or useClass');
+    }
+    static getClient() {
+        return {
+            provide: postgres_tokens_1.PostgresTokens.CLIENT,
+            useFactory: (config) => (0, postgres_1.default)(config),
+            inject: [
+                postgres_tokens_1.PostgresTokens.OPTIONS,
+            ],
+        };
+    }
+}
+exports.PostgresProviders = PostgresProviders;

package/lib/postgres.tokens.d.ts

@@ -0,0 +1,4 @@
+export declare enum PostgresTokens {
+    OPTIONS = "postgres_module_options",
+    CLIENT = "postgres_module_client"
+}

package/lib/postgres.tokens.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PostgresTokens = void 0;
+var PostgresTokens;
+(function (PostgresTokens) {
+    PostgresTokens["OPTIONS"] = "postgres_module_options";
+    PostgresTokens["CLIENT"] = "postgres_module_client";
+})(PostgresTokens || (exports.PostgresTokens = PostgresTokens = {}));

package/lib/postgres.types.d.ts

@@ -0,0 +1,2 @@
+import { Options, PostgresType } from 'postgres';
+export type TPostgresOptions = Options<Record<string, PostgresType>>;

package/lib/postgres.types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@quazex/nestjs-postgres",
+  "repository": {
+    "type": "git",
+    "url": "git://github.com/quazex/nestjs-postgres.git"
+  },
+  "description": "NestJS module for Postgres library",
+  "version": "1.0.0",
+  "author": "Alexander Smirnov",
+  "license": "MIT",
+  "engines": {
+    "node": ">= 24.x"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "files": [
+    "lib/**"
+  ],
+  "keywords": [
+    "postgres",
+    "postgresql",
+    "nestjs",
+    "nest",
+    "typescript",
+    "nodejs",
+    "node"
+  ],
+  "scripts": {
+    "build:clear": "rimraf lib",
+    "build:compile": "npm run build:clear && tsc --project tsconfig.build.json",
+    "dev:watch": "tsc --watch",
+    "dev:check": "tsc --noEmit",
+    "dev:lint": "eslint",
+    "dev:format": "npm run dev:lint -- --fix",
+    "dev:test": "jest",
+    "prepare": "husky"
+  },
+  "peerDependencies": {
+    "@nestjs/common": ">=9.0.0 <12.0.0",
+    "postgres": ">=3.0.0"
+  },
+  "devDependencies": {
+    "@faker-js/faker": "9.8.0",
+    "@jest/globals": "29.7.0",
+    "@nestjs/common": "11.1.17",
+    "@nestjs/testing": "11.1.17",
+    "@quazex/eslint-config": "1.1.2",
+    "@testcontainers/postgresql": "11.13.0",
+    "husky": "9.1.7",
+    "jest": "29.7.0",
+    "postgres": "3.4.8",
+    "rimraf": "6.0.1",
+    "testcontainers": "11.13.0",
+    "ts-jest": "29.4.0",
+    "ts-node": "10.9.2",
+    "typescript": "5.9.3"
+  }
+}