@vn.chemgio/nestjs-utilities 2.0.0

package/README.md

@@ -0,0 +1,78 @@
+# @vn.chemgio/nestjs-utilities
+
+A collection of modular NestJS utility packages. Each module can be imported independently via sub-path exports so you only install what you need.
+
+## Installation
+
+```bash
+npm install @vn.chemgio/nestjs-utilities
+```
+
+## Available modules
+
+| Import path | Description | README |
+|---|---|---|
+| `@vn.chemgio/nestjs-utilities` | Version constant (`VERSION`) | — |
+| `@vn.chemgio/nestjs-utilities/typeorm` | TypeORM configuration helpers (RDS PostgreSQL, MySQL) | [README](src/typeorm/README.md) |
+| `@vn.chemgio/nestjs-utilities/cache` | Global cache module with Valkey / Redis backend | [README](src/cache/README.md) |
+| `@vn.chemgio/nestjs-utilities/queue` | BullMQ config factory for Valkey / Redis backend | [README](src/queue/README.md) |
+
+Click each README link above for detailed usage, environment variables, and options specific to that module.
+
+## Quick examples
+
+### TypeORM
+
+```typescript
+import { TypeOrmModule } from '@nestjs/typeorm'
+import { ConfigService } from '@nestjs/config'
+import { configTypeOrmRDSPostgres } from '@vn.chemgio/nestjs-utilities/typeorm'
+
+TypeOrmModule.forRootAsync({
+  inject: [ConfigService],
+  useFactory: (config: ConfigService) =>
+    configTypeOrmRDSPostgres(config, { poolSize: 20 }),
+})
+```
+
+### Cache
+
+```typescript
+import { CacheModule } from '@vn.chemgio/nestjs-utilities/cache'
+
+@Module({
+  imports: [CacheModule.forRoot({ store: 'valkey' })],
+})
+export class AppModule {}
+```
+
+### Queue
+
+```typescript
+import { BullModule } from '@nestjs/bullmq'
+import { configBullMQ } from '@vn.chemgio/nestjs-utilities/queue'
+
+BullModule.forRootAsync({
+  inject: [ConfigService],
+  useFactory: configBullMQ,
+})
+```
+
+## Development
+
+```bash
+npm install
+npm run build
+npm test
+```
+
+## Publishing
+
+```bash
+npm login
+npm publish --access public
+```
+
+## License
+
+MIT

package/dist/cache/README.md

@@ -0,0 +1,91 @@
+# @vn.chemgio/nestjs-utilities/cache
+
+A global NestJS cache module using [Keyv](https://keyv.org/) + [Cacheable](https://github.com/jaredwray/cacheable) with Valkey or Redis backend.
+
+## Installation
+
+```bash
+npm install @vn.chemgio/nestjs-utilities keyv cacheable
+```
+
+Depending on your store:
+
+- **Valkey**: `npm install @keyv/valkey`
+- **Redis**: `npm install @keyv/redis`
+
+## Quick start
+
+### Valkey (reads `VALKEY_URL` from env)
+
+```typescript
+// app.module.ts
+import { CacheModule } from '@vn.chemgio/nestjs-utilities/cache'
+
+@Module({
+  imports: [
+    CacheModule.forRoot({ store: 'valkey' }),
+    // Requires VALKEY_URL in your .env:
+    // VALKEY_URL=valkey://localhost:6379
+  ],
+})
+export class AppModule {}
+```
+
+### Redis (reads `REDIS_URL` from env)
+
+```typescript
+CacheModule.forRoot({ store: 'redis' })
+// Requires REDIS_URL in .env:
+// REDIS_URL=redis://localhost:6379
+```
+
+### Direct URL (no env vars needed)
+
+```typescript
+CacheModule.forRoot({
+  store: 'valkey',
+  url: 'valkey://user:pass@host:6379',
+})
+```
+
+## Usage in a service
+
+```typescript
+import { Inject } from '@nestjs/common'
+import { CACHE_MANAGER } from '@vn.chemgio/nestjs-utilities/cache'
+import { Cacheable } from 'cacheable'
+
+@Injectable()
+export class MyService {
+  constructor(
+    @Inject(CACHE_MANAGER) private readonly cache: Cacheable,
+  ) {}
+
+  async getData(key: string) {
+    return this.cache.get(key)
+  }
+
+  async setData(key: string, value: unknown, ttl?: number) {
+    await this.cache.set(key, value, ttl)
+  }
+}
+```
+
+## CacheModuleOptions
+
+| Option | Default | Description |
+|---|---|---|
+| `store` | `'valkey'` | Backend store: `'valkey'` or `'redis'` |
+| `namespace` | `'{default}'` | Cache namespace prefix |
+| `url` | — | Connection URL. If omitted, reads `VALKEY_URL` or `REDIS_URL` from env |
+
+## How it works
+
+```
+Cacheable  →  Keyv  →  KeyvValkey / KeyvRedis  →  Valkey / Redis
+```
+
+- `KeyvValkey` / `KeyvRedis` connects to the backend
+- `Keyv` wraps it with a uniform API
+- `Cacheable` adds TTL, namespace, and caching logic
+- The module is `@Global()`, so `CACHE_MANAGER` is available everywhere

package/dist/cache/index.d.ts

@@ -0,0 +1,10 @@
+import { DynamicModule } from '@nestjs/common';
+export declare const CACHE_MANAGER = "CACHE_MANAGER";
+export interface CacheModuleOptions {
+    namespace?: string;
+    store?: 'valkey' | 'redis';
+    url?: string;
+}
+export declare class CacheModule {
+    static forRoot(options?: CacheModuleOptions): DynamicModule;
+}

package/dist/cache/index.js

@@ -0,0 +1,75 @@
+"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 __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+var CacheModule_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CacheModule = exports.CACHE_MANAGER = void 0;
+const common_1 = require("@nestjs/common");
+const config_1 = require("@nestjs/config");
+const keyv_1 = __importDefault(require("keyv"));
+const cacheable_1 = require("cacheable");
+exports.CACHE_MANAGER = 'CACHE_MANAGER';
+async function loadAdapter(store, url) {
+    if (store === 'valkey') {
+        const { default: KeyvValkey } = await import('@keyv/valkey');
+        return new KeyvValkey(url);
+    }
+    const { default: KeyvRedis } = await import('@keyv/redis');
+    return new KeyvRedis(url);
+}
+function buildCacheable(adapter, namespace) {
+    const keyv = new keyv_1.default({ store: adapter });
+    return new cacheable_1.Cacheable({ primary: keyv, namespace });
+}
+let CacheModule = CacheModule_1 = class CacheModule {
+    static forRoot(options = {}) {
+        const { namespace = '{default}', store = 'valkey' } = options;
+        if (options.url) {
+            return {
+                module: CacheModule_1,
+                providers: [
+                    {
+                        provide: exports.CACHE_MANAGER,
+                        useFactory: async () => {
+                            const adapter = await loadAdapter(store, options.url);
+                            return buildCacheable(adapter, namespace);
+                        },
+                    },
+                ],
+                exports: [exports.CACHE_MANAGER],
+            };
+        }
+        return {
+            module: CacheModule_1,
+            providers: [
+                {
+                    provide: exports.CACHE_MANAGER,
+                    inject: [config_1.ConfigService],
+                    useFactory: async (configService) => {
+                        const envKey = store === 'valkey' ? 'VALKEY_URL' : 'REDIS_URL';
+                        const connectionUrl = configService.get(envKey);
+                        if (!connectionUrl) {
+                            throw new Error(`Missing ${envKey} environment variable. Set it or pass "url" to forRoot().`);
+                        }
+                        const adapter = await loadAdapter(store, connectionUrl);
+                        return buildCacheable(adapter, namespace);
+                    },
+                },
+            ],
+            exports: [exports.CACHE_MANAGER],
+        };
+    }
+};
+exports.CacheModule = CacheModule;
+exports.CacheModule = CacheModule = CacheModule_1 = __decorate([
+    (0, common_1.Global)(),
+    (0, common_1.Module)({})
+], CacheModule);
+//# sourceMappingURL=index.js.map

package/dist/cache/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/cache/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;AAAA,2CAA+D;AAC/D,2CAA+C;AAC/C,gDAAwB;AACxB,yCAAsC;AAEzB,QAAA,aAAa,GAAG,eAAe,CAAC;AAQ7C,KAAK,UAAU,WAAW,CAAC,KAAyB,EAAE,GAAW;IAC/D,IAAI,KAAK,KAAK,QAAQ,EAAE,CAAC;QACvB,MAAM,EAAE,OAAO,EAAE,UAAU,EAAE,GAAG,MAAM,MAAM,CAAC,cAAc,CAAC,CAAC;QAC7D,OAAO,IAAI,UAAU,CAAC,GAAG,CAAC,CAAC;IAC7B,CAAC;IACD,MAAM,EAAE,OAAO,EAAE,SAAS,EAAE,GAAG,MAAM,MAAM,CAAC,aAAa,CAAC,CAAC;IAC3D,OAAO,IAAI,SAAS,CAAC,GAAG,CAAC,CAAC;AAC5B,CAAC;AAED,SAAS,cAAc,CAAC,OAAgB,EAAE,SAAiB;IACzD,MAAM,IAAI,GAAG,IAAI,cAAI,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC,CAAC;IAC1C,OAAO,IAAI,qBAAS,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC,CAAC;AACrD,CAAC;AAIM,IAAM,WAAW,mBAAjB,MAAM,WAAW;IACtB,MAAM,CAAC,OAAO,CAAC,UAA8B,EAAE;QAC7C,MAAM,EAAE,SAAS,GAAG,WAAW,EAAE,KAAK,GAAG,QAAQ,EAAE,GAAG,OAAO,CAAC;QAE9D,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC;YAChB,OAAO;gBACL,MAAM,EAAE,aAAW;gBACnB,SAAS,EAAE;oBACT;wBACE,OAAO,EAAE,qBAAa;wBACtB,UAAU,EAAE,KAAK,IAAI,EAAE;4BACrB,MAAM,OAAO,GAAG,MAAM,WAAW,CAAC,KAAK,EAAE,OAAO,CAAC,GAAI,CAAC,CAAC;4BACvD,OAAO,cAAc,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC;wBAC5C,CAAC;qBACF;iBACF;gBACD,OAAO,EAAE,CAAC,qBAAa,CAAC;aACzB,CAAC;QACJ,CAAC;QAED,OAAO;YACL,MAAM,EAAE,aAAW;YACnB,SAAS,EAAE;gBACT;oBACE,OAAO,EAAE,qBAAa;oBACtB,MAAM,EAAE,CAAC,sBAAa,CAAC;oBACvB,UAAU,EAAE,KAAK,EAAE,aAA4B,EAAE,EAAE;wBACjD,MAAM,MAAM,GAAG,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,WAAW,CAAC;wBAC/D,MAAM,aAAa,GAAG,aAAa,CAAC,GAAG,CAAS,MAAM,CAAC,CAAC;wBACxD,IAAI,CAAC,aAAa,EAAE,CAAC;4BACnB,MAAM,IAAI,KAAK,CACb,WAAW,MAAM,2DAA2D,CAC7E,CAAC;wBACJ,CAAC;wBACD,MAAM,OAAO,GAAG,MAAM,WAAW,CAAC,KAAK,EAAE,aAAa,CAAC,CAAC;wBACxD,OAAO,cAAc,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC;oBAC5C,CAAC;iBACF;aACF;YACD,OAAO,EAAE,CAAC,qBAAa,CAAC;SACzB,CAAC;IACJ,CAAC;CACF,CAAA;AA1CY,kCAAW;sBAAX,WAAW;IAFvB,IAAA,eAAM,GAAE;IACR,IAAA,eAAM,EAAC,EAAE,CAAC;GACE,WAAW,CA0CvB"}

package/dist/index.d.ts

@@ -0,0 +1 @@
+export declare const VERSION = "2.0.0";

package/dist/index.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VERSION = void 0;
+exports.VERSION = '2.0.0';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAa,QAAA,OAAO,GAAG,OAAO,CAAC"}

package/dist/queue/README.md

@@ -0,0 +1,82 @@
+# @vn.chemgio/nestjs-utilities/queue
+
+RDS-style config factory for [BullMQ](https://bullmq.io) (via `@nestjs/bullmq`).
+
+Works with either Valkey (`VALKEY_URL`) or Redis (`REDIS_URL`) environment variables.
+
+## Installation
+
+```bash
+npm install @vn.chemgio/nestjs-utilities @nestjs/bullmq bullmq
+```
+
+## Usage
+
+```typescript
+import { BullModule } from '@nestjs/bullmq';
+import { configBullMQ } from '@vn.chemgio/nestjs-utilities/queue';
+
+@Module({
+  imports: [
+    BullModule.forRootAsync({
+      useFactory: configBullMQ,
+      inject: [ConfigService],
+    }),
+    BullModule.registerQueue({ name: 'email' }),
+  ],
+})
+export class AppModule {}
+```
+
+### Valkey (reads `VALKEY_URL` from env)
+
+```typescript
+BullModule.forRootAsync({
+  // Requires VALKEY_URL in .env:
+  // VALKEY_URL=valkey://localhost:6379
+  useFactory: configBullMQ,
+  inject: [ConfigService],
+})
+```
+
+### Redis (reads `REDIS_URL` from env)
+
+```typescript
+BullModule.forRootAsync({
+  useFactory: (config: ConfigService) =>
+    configBullMQ(config, { store: 'redis' }),
+  inject: [ConfigService],
+})
+```
+
+### With custom prefix and default job options
+
+```typescript
+BullModule.forRootAsync({
+  useFactory: (config: ConfigService) =>
+    configBullMQ(config, {
+      prefix: '{myapp}',
+      defaultJobOptions: { attempts: 3, removeOnComplete: 100 },
+    }),
+  inject: [ConfigService],
+})
+```
+
+### Direct URL (no env vars)
+
+```typescript
+BullModule.forRootAsync({
+  useFactory: () => ({
+    connection: { url: 'redis://user:pass@host:6379' },
+    prefix: '{default}',
+  }),
+})
+```
+
+## QueueModuleOptions
+
+| Option | Default | Description |
+|---|---|---|
+| `store` | `'valkey'` | Backend store: `'valkey'` or `'redis'` |
+| `prefix` | `'{default}'` | BullMQ key prefix |
+| `defaultJobOptions` | — | Default job options for all queues (e.g. `{ attempts: 3 }`) |

package/dist/queue/index.d.ts

@@ -0,0 +1,14 @@
+import type { ConfigService } from '@nestjs/config';
+export interface QueueModuleOptions {
+    store?: 'valkey' | 'redis';
+    prefix?: string;
+    defaultJobOptions?: Record<string, unknown>;
+}
+export interface BullMQModuleOptions {
+    connection: {
+        url: string;
+    };
+    prefix: string;
+    defaultJobOptions?: Record<string, unknown>;
+}
+export declare function configBullMQ(configService: ConfigService, options?: QueueModuleOptions): BullMQModuleOptions;

package/dist/queue/index.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.configBullMQ = configBullMQ;
+function configBullMQ(configService, options) {
+    const { store = 'valkey', prefix, defaultJobOptions } = options ?? {};
+    const envKey = store === 'valkey' ? 'VALKEY_URL' : 'REDIS_URL';
+    const url = configService.get(envKey);
+    if (!url) {
+        throw new Error(`Missing ${envKey} environment variable.`);
+    }
+    return {
+        connection: { url },
+        prefix: prefix ?? '{default}',
+        defaultJobOptions,
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/queue/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/queue/index.ts"],"names":[],"mappings":";;AAcA,oCAeC;AAfD,SAAgB,YAAY,CAC1B,aAA4B,EAC5B,OAA4B;IAE5B,MAAM,EAAE,KAAK,GAAG,QAAQ,EAAE,MAAM,EAAE,iBAAiB,EAAE,GAAG,OAAO,IAAI,EAAE,CAAC;IACtE,MAAM,MAAM,GAAG,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,WAAW,CAAC;IAC/D,MAAM,GAAG,GAAG,aAAa,CAAC,GAAG,CAAS,MAAM,CAAC,CAAC;IAC9C,IAAI,CAAC,GAAG,EAAE,CAAC;QACT,MAAM,IAAI,KAAK,CAAC,WAAW,MAAM,wBAAwB,CAAC,CAAC;IAC7D,CAAC;IACD,OAAO;QACL,UAAU,EAAE,EAAE,GAAG,EAAE;QACnB,MAAM,EAAE,MAAM,IAAI,WAAW;QAC7B,iBAAiB;KAClB,CAAC;AACJ,CAAC"}