nesthub 1.0.0

package/README.md

@@ -0,0 +1,108 @@
+# nesthub
+
+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 nesthub
+```
+
+## Available modules
+
+| Import path | Description | README |
+|---|---|---|
+| `nesthub` | Version constant (`VERSION`) | — |
+| `nesthub/typeorm` | TypeORM configuration helpers (RDS PostgreSQL, MySQL) | [README](src/typeorm/README.md) |
+| `nesthub/cache` | Global cache module with Valkey / Redis backend | [README](src/cache/README.md) |
+| `nesthub/queue` | BullMQ config factory for Valkey / Redis backend | [README](src/queue/README.md) |
+| `nesthub/notification` | Multi-channel notification module (email, SMS, Firebase, Telegram) with templates, queue, TypeORM persistence | [README](src/notification/README.md) |
+| `nesthub/excel` | Export JSON data to Excel (.xlsx) — fast, zero boilerplate | [README](src/excel/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 'nesthub/typeorm'
+
+TypeOrmModule.forRootAsync({
+  inject: [ConfigService],
+  useFactory: (config: ConfigService) =>
+    configTypeOrmRDSPostgres(config, { poolSize: 20 }),
+})
+```
+
+### Cache
+
+```typescript
+import { CacheModule } from 'nesthub/cache'
+
+@Module({
+  imports: [CacheModule.forRoot({ store: 'valkey' })],
+})
+export class AppModule {}
+```
+
+### Queue
+
+```typescript
+import { BullModule } from '@nestjs/bullmq'
+import { configBullMQ } from 'nesthub/queue'
+
+BullModule.forRootAsync({
+  inject: [ConfigService],
+  useFactory: configBullMQ,
+})
+```
+
+### Notification
+
+```typescript
+import { Module } from '@nestjs/common'
+import { NotificationModule } from 'nesthub/notification'
+
+@Module({
+  imports: [
+    NotificationModule.forRoot({
+      channels: {
+        email: { smtp: { host: 'smtp.example.com', port: 587 } },
+        sms: { provider: 'twilio', credentials: { accountSid: '...', authToken: '...' }, from: '+123' },
+      },
+      templates: { dir: './templates' },
+      queue: { enabled: true, connection: { url: 'valkey://localhost:6379' } },
+      storage: { enabled: true },
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+### Excel
+
+```typescript
+import { exportToBuffer, exportToFile, exportToResponse } from 'nesthub/excel'
+
+// Get buffer
+const buffer = await exportToBuffer(users, {
+  columns: ['name', 'email'],
+  formatters: { active: (v) => (v ? 'Yes' : 'No') },
+})
+
+// Write to file
+await exportToFile(users, './reports/users.xlsx')
+
+// Send as download in controller
+@Get('download')
+async download(@Res() res: any) {
+  await exportToResponse(users, res, 'users.xlsx')
+}
+```
+
+## License
+
+MIT

package/dist/cache/README.md

@@ -0,0 +1,91 @@
+# nesthub/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 nesthub 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 'nesthub/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 'nesthub/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/cache/index.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/cache/index.spec.js

@@ -0,0 +1,61 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const index_1 = require("./index");
+describe('@vn.chemgio/nestjs-utilities/cache', () => {
+    describe('CACHE_MANAGER', () => {
+        it('should be the string CACHE_MANAGER', () => {
+            expect(index_1.CACHE_MANAGER).toBe('CACHE_MANAGER');
+        });
+    });
+    describe('CacheModule.forRoot', () => {
+        it('should return a DynamicModule', () => {
+            const mod = index_1.CacheModule.forRoot();
+            expect(mod.module).toBe(index_1.CacheModule);
+            expect(mod.exports).toContain(index_1.CACHE_MANAGER);
+            expect(mod.providers).toHaveLength(1);
+        });
+        describe('with direct URL', () => {
+            it('should omit inject array', () => {
+                const mod = index_1.CacheModule.forRoot({ url: 'valkey://localhost:6379' });
+                const provider = mod.providers[0];
+                expect(provider.provide).toBe(index_1.CACHE_MANAGER);
+                expect(provider.inject).toBeUndefined();
+                expect(provider.useFactory).toBeInstanceOf(Function);
+            });
+            it('should accept redis store with URL', () => {
+                const mod = index_1.CacheModule.forRoot({
+                    store: 'redis',
+                    url: 'redis://localhost:6379',
+                    namespace: 'myapp',
+                });
+                const provider = mod.providers[0];
+                expect(provider.provide).toBe(index_1.CACHE_MANAGER);
+            });
+        });
+        describe('without URL (env-based)', () => {
+            it('should include ConfigService in inject array', () => {
+                const mod = index_1.CacheModule.forRoot({ store: 'valkey' });
+                const provider = mod.providers[0];
+                expect(provider.provide).toBe(index_1.CACHE_MANAGER);
+                expect(provider.inject).toBeDefined();
+                expect(provider.inject).toHaveLength(1);
+                expect(provider.useFactory).toBeInstanceOf(Function);
+            });
+            it('should throw on missing env var', async () => {
+                const mod = index_1.CacheModule.forRoot({ store: 'valkey' });
+                const provider = mod.providers[0];
+                const mockConfig = { get: jest.fn().mockReturnValue(undefined) };
+                await expect(provider.useFactory(mockConfig)).rejects.toThrow('Missing VALKEY_URL environment variable');
+                expect(mockConfig.get).toHaveBeenCalledWith('VALKEY_URL');
+            });
+            it('should read REDIS_URL for redis store', async () => {
+                const mod = index_1.CacheModule.forRoot({ store: 'redis' });
+                const provider = mod.providers[0];
+                const mockConfig = { get: jest.fn().mockReturnValue(undefined) };
+                await expect(provider.useFactory(mockConfig)).rejects.toThrow('REDIS_URL');
+                expect(mockConfig.get).toHaveBeenCalledWith('REDIS_URL');
+            });
+        });
+    });
+});
+//# sourceMappingURL=index.spec.js.map

package/dist/cache/index.spec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.spec.js","sourceRoot":"","sources":["../../src/cache/index.spec.ts"],"names":[],"mappings":"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"}

package/dist/excel/README.md

@@ -0,0 +1,132 @@
+# nesthub/excel
+
+Export JSON data to Excel (.xlsx) — fast, zero boilerplate.
+
+## Installation
+
+```bash
+npm install nesthub exceljs
+```
+
+## Functions
+
+### `exportToBuffer(data, options?)`
+
+Returns a `Buffer` of the .xlsx file.
+
+```typescript
+import { exportToBuffer } from 'nesthub/excel';
+
+const data = [
+  { name: 'Alice', age: 30 },
+  { name: 'Bob', age: 25 },
+];
+
+const buffer = await exportToBuffer(data);
+```
+
+### `exportToFile(data, filePath, options?)`
+
+Writes the .xlsx directly to disk.
+
+```typescript
+import { exportToFile } from 'nesthub/excel';
+
+await exportToFile(data, './reports/users.xlsx');
+```
+
+### `exportToResponse(data, res, filename?, options?)`
+
+Sends the .xlsx as a download response in a NestJS/Express controller.
+
+```typescript
+import { exportToResponse } from 'nesthub/excel';
+import { Response } from 'express';
+import { Controller, Get, Res } from '@nestjs/common';
+
+@Controller('reports')
+export class ReportController {
+  @Get('users')
+  async downloadUsers(@Res() res: Response) {
+    const data = await this.userService.findAll();
+    await exportToResponse(data, res, 'users.xlsx');
+  }
+}
+```
+
+## Options
+
+| Param | Type | Default |
+|-------|------|---------|
+| `data` | `Record<string, unknown>[]` | — |
+| `options.sheetName` | `string` | `'Sheet1'` |
+| `options.columns` | `(string \| ExcelColumn)[]` | All keys from the first data object |
+| `options.useAutoFilter` | `boolean` | `true` |
+| `options.headerFont` | `{ name, size, bold }` | `{ name: 'Calibri', size: 11, bold: true }` |
+| `options.headerBg` | `string` (ARGB hex) | `'4472C4'` |
+| `options.borderColor` | `string` (ARGB hex) | `'B0B0B0'` |
+| `options.formatters` | `Record<string, (value, row) => any>` | — |
+
+### `ExcelColumn`
+
+```typescript
+interface ExcelColumn {
+  key: string;                                         // field name in data
+  header?: string;                                     // default: capitalize(key)
+  width?: number;                                      // default: 18
+  formatter?: (value: unknown, row: object) => unknown; // transform cell value
+}
+```
+
+## Examples
+
+### Pick fields to export
+
+```typescript
+await exportToBuffer(data, {
+  columns: ['name', 'email'],
+});
+```
+
+### Custom header + column width
+
+```typescript
+await exportToBuffer(data, {
+  columns: [
+    { key: 'name',   header: 'Full Name', width: 25 },
+    { key: 'salary', header: 'Salary',    width: 15 },
+  ],
+});
+```
+
+### Format displayed values
+
+**Per-column formatter:**
+```typescript
+await exportToBuffer(data, {
+  columns: [
+    { key: 'name' },
+    {
+      key: 'salary',
+      header: 'Salary',
+      formatter: (v) => `$${(v as number).toLocaleString()}`,
+    },
+  ],
+});
+```
+
+**Global formatters:**
+```typescript
+await exportToBuffer(data, {
+  columns: ['name', 'active'],
+  formatters: {
+    active: (v) => (v ? 'Active' : 'Inactive'),
+  },
+});
+```
+
+### Disable auto filter
+
+```typescript
+await exportToBuffer(data, { useAutoFilter: false });
+```

package/dist/excel/excel.module.d.ts

@@ -0,0 +1,2 @@
+export declare class ExcelModule {
+}

package/dist/excel/excel.module.js

@@ -0,0 +1,21 @@
+"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;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ExcelModule = void 0;
+const common_1 = require("@nestjs/common");
+const excel_service_1 = require("./excel.service");
+let ExcelModule = class ExcelModule {
+};
+exports.ExcelModule = ExcelModule;
+exports.ExcelModule = ExcelModule = __decorate([
+    (0, common_1.Module)({
+        providers: [excel_service_1.ExcelService],
+        exports: [excel_service_1.ExcelService],
+    })
+], ExcelModule);
+//# sourceMappingURL=excel.module.js.map

package/dist/excel/excel.module.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"excel.module.js","sourceRoot":"","sources":["../../src/excel/excel.module.ts"],"names":[],"mappings":";;;;;;;;;AAAA,2CAAwC;AACxC,mDAA+C;AAMxC,IAAM,WAAW,GAAjB,MAAM,WAAW;CAAG,CAAA;AAAd,kCAAW;sBAAX,WAAW;IAJvB,IAAA,eAAM,EAAC;QACN,SAAS,EAAE,CAAC,4BAAY,CAAC;QACzB,OAAO,EAAE,CAAC,4BAAY,CAAC;KACxB,CAAC;GACW,WAAW,CAAG"}

package/dist/excel/excel.service.d.ts

@@ -0,0 +1,23 @@
+import type { ServerResponse } from 'node:http';
+export interface ExcelColumn {
+    key: string;
+    header?: string;
+    width?: number;
+    formatter?: (value: unknown, row: Record<string, unknown>) => unknown;
+}
+export interface ExcelExportOptions {
+    sheetName?: string;
+    columns?: (string | ExcelColumn)[];
+    useAutoFilter?: boolean;
+    headerFont?: {
+        name?: string;
+        size?: number;
+        bold?: boolean;
+    };
+    headerBg?: string;
+    borderColor?: string;
+    formatters?: Record<string, (value: unknown, row: Record<string, unknown>) => unknown>;
+}
+export declare function exportToBuffer(data: Record<string, unknown>[], options?: ExcelExportOptions): Promise<Buffer>;
+export declare function exportToFile(data: Record<string, unknown>[], filePath: string, options?: ExcelExportOptions): Promise<void>;
+export declare function exportToResponse(data: Record<string, unknown>[], res: ServerResponse, filename?: string, options?: ExcelExportOptions): Promise<void>;

package/dist/excel/excel.service.js

@@ -0,0 +1,124 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.exportToBuffer = exportToBuffer;
+exports.exportToFile = exportToFile;
+exports.exportToResponse = exportToResponse;
+const exceljs_1 = require("exceljs");
+const promises_1 = require("node:fs/promises");
+const DEFAULTS = {
+    sheetName: 'Sheet1',
+    useAutoFilter: true,
+    headerFont: { name: 'Calibri', size: 11, bold: true },
+    headerBg: '4472C4',
+    borderColor: 'B0B0B0',
+};
+function resolveCols(data, columns) {
+    if (!columns || columns.length === 0) {
+        if (data.length === 0)
+            return [];
+        return Object.keys(data[0]).map((key) => ({
+            key,
+            header: key.charAt(0).toUpperCase() + key.slice(1).replace(/_/g, ' '),
+        }));
+    }
+    return columns.map((c) => {
+        if (typeof c === 'string')
+            return { key: c, header: c };
+        return { ...c, header: c.header ?? c.key };
+    });
+}
+function pick(obj, cols) {
+    if (cols.length === 0)
+        return obj;
+    const result = {};
+    for (const col of cols) {
+        if (col.key in obj)
+            result[col.key] = obj[col.key];
+    }
+    return result;
+}
+function applyFormatters(row, cols, globalFormatters) {
+    const result = {};
+    for (const col of cols) {
+        const value = row[col.key];
+        const fn = col.formatter ?? globalFormatters?.[col.key];
+        result[col.key] = fn ? fn(value, row) : value;
+    }
+    return result;
+}
+function styleHeader(ws, colCount, font, bg, borderColor) {
+    const row = ws.getRow(1);
+    row.font = font;
+    row.alignment = { vertical: 'middle', horizontal: 'center' };
+    for (let c = 1; c <= colCount; c++) {
+        const cell = row.getCell(c);
+        cell.fill = { type: 'pattern', pattern: 'solid', fgColor: { argb: bg } };
+        cell.font = { ...font, color: { argb: 'FFFFFFFF' } };
+        cell.border = {
+            top: { style: 'thin', color: { argb: borderColor } },
+            left: { style: 'thin', color: { argb: borderColor } },
+            bottom: { style: 'thin', color: { argb: borderColor } },
+            right: { style: 'thin', color: { argb: borderColor } },
+        };
+    }
+}
+function styleRows(ws, rowCount, colCount, borderColor) {
+    for (let r = 2; r <= rowCount + 1; r++) {
+        const row = ws.getRow(r);
+        for (let c = 1; c <= colCount; c++) {
+            const cell = row.getCell(c);
+            cell.alignment = { vertical: 'middle', horizontal: 'left' };
+            cell.border = {
+                top: { style: 'thin', color: { argb: borderColor } },
+                left: { style: 'thin', color: { argb: borderColor } },
+                bottom: { style: 'thin', color: { argb: borderColor } },
+                right: { style: 'thin', color: { argb: borderColor } },
+            };
+        }
+    }
+}
+async function exportToBuffer(data, options) {
+    const workbook = new exceljs_1.Workbook();
+    const ws = workbook.addWorksheet(options?.sheetName ?? DEFAULTS.sheetName);
+    const cols = resolveCols(data, options?.columns);
+    if (cols.length === 0) {
+        const buf = await workbook.xlsx.writeBuffer();
+        return Buffer.from(buf);
+    }
+    ws.columns = cols.map((col) => ({
+        header: col.header,
+        key: col.key,
+        width: col.width ?? 18,
+    }));
+    const rows = data.map((item) => {
+        const picked = pick(item, cols);
+        return applyFormatters(picked, cols, options?.formatters);
+    });
+    ws.addRows(rows);
+    const headerFont = options?.headerFont ?? DEFAULTS.headerFont;
+    const headerBg = options?.headerBg ?? DEFAULTS.headerBg;
+    const borderColor = options?.borderColor ?? DEFAULTS.borderColor;
+    styleHeader(ws, cols.length, headerFont, headerBg, borderColor);
+    styleRows(ws, rows.length, cols.length, borderColor);
+    if (options?.useAutoFilter ?? DEFAULTS.useAutoFilter) {
+        ws.autoFilter = {
+            from: { row: 1, column: 1 },
+            to: { row: rows.length + 1, column: cols.length },
+        };
+    }
+    const buf = await workbook.xlsx.writeBuffer();
+    return Buffer.from(buf);
+}
+async function exportToFile(data, filePath, options) {
+    const buffer = await exportToBuffer(data, options);
+    await (0, promises_1.writeFile)(filePath, buffer);
+}
+async function exportToResponse(data, res, filename, options) {
+    const buffer = await exportToBuffer(data, options);
+    const name = filename ?? 'export.xlsx';
+    res.setHeader('Content-Type', 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet');
+    res.setHeader('Content-Disposition', `attachment; filename="${name}"`);
+    res.setHeader('Content-Length', buffer.length);
+    res.end(buffer);
+}
+//# sourceMappingURL=excel.service.js.map