@refpool/nestjs 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Atul Singh
+
+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,159 @@
+# @refpool/nestjs
+
+NestJS integration for [`@refpool/core`](../core): a dynamic module, an injectable
+service with lifecycle hooks, multi-tenant connection middleware, and a
+connection-health controller.
+
+## Install
+
+```bash
+npm install @refpool/nestjs @refpool/core
+```
+
+Peer dependencies (required): `@nestjs/common`, `@nestjs/core`,
+`reflect-metadata`, `rxjs`.
+
+## Module wiring
+
+`RefPoolModule.forRoot` takes the same [`PoolOptions`](../core#pooloptionst) as the
+core pool, plus a few module-level flags (`isGlobal`, `warmOnInit`, `middleware`).
+
+```ts
+import { Module } from '@nestjs/common';
+import { RefPoolModule } from '@refpool/nestjs';
+import { Pool } from 'pg';
+
+@Module({
+  imports: [
+    RefPoolModule.forRoot<Pool>({
+      isGlobal: true,
+      max: 20,
+      idleTtlMs: 60_000,
+      factory: async (tenantId) =>
+        new Pool({ connectionString: `postgres://localhost:5432/tenant_${tenantId}` }),
+      dispose: async (pool) => pool.end(),
+      middleware: { header: 'x-tenant-id', onMissing: 'error' },
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+Async configuration (inject config/other providers):
+
+```ts
+RefPoolModule.forRootAsync<Pool>({
+  inject: [ConfigService],
+  useFactory: (config: ConfigService) => ({
+    max: config.get('REFPOOL_MAX', 20),
+    factory: async (tenantId) => new Pool({ connectionString: config.urlFor(tenantId) }),
+    dispose: async (pool) => pool.end(),
+  }),
+});
+```
+
+`RefPoolService` starts the pool on `OnModuleInit` (and runs `warm()` when
+`prewarm` is set or `warmOnInit: true`) and drains it on `OnApplicationShutdown`.
+Enable shutdown hooks in `main.ts` with `app.enableShutdownHooks()`.
+
+## RefPoolService
+
+Inject it anywhere to use the pool:
+
+```ts
+import { Injectable } from '@nestjs/common';
+import { RefPoolService } from '@refpool/nestjs';
+import type { Pool } from 'pg';
+
+@Injectable()
+export class ReportService {
+  constructor(private readonly refpool: RefPoolService<Pool>) {}
+
+  run(tenantId: string) {
+    // acquire → run → release (released even on throw)
+    return this.refpool.withResource(tenantId, (pool) => pool.query('select now()'));
+  }
+
+  stats() {
+    return this.refpool.getStats();
+  }
+}
+```
+
+`RefPoolService<T>` exposes `acquire(key)`, `withResource(key, fn)`, `getStats()`,
+and the underlying `.pool` (for event subscription, etc.).
+
+## Tenant middleware
+
+`TenantConnectionMiddleware` reads the tenant key from a request header
+(default `x-tenant-id`), acquires that tenant's resource for the lifetime of the
+request, and releases it when the response finishes/closes. The resource is
+attached to the request (default property `tenantResource`, plus
+`tenantResourceKey`).
+
+### Drop-in (auto-applied)
+
+`RefPoolModule` implements `NestModule` and wires the middleware for you when you
+opt in via `applyMiddleware: true` or `middleware.routes`. No `configure()` in
+your `AppModule` required:
+
+```ts
+@Module({
+  imports: [
+    RefPoolModule.forRoot<Pool>({
+      max: 20,
+      factory: async (tenantId) => new Pool({ /* ... */ }),
+      // Opt in to auto-wiring. Either flag works:
+      applyMiddleware: true,                       // applies to '*' (all routes)
+      middleware: {
+        header: 'x-tenant-id',
+        onMissing: 'error',
+        routes: ['tenant/*'],                      // or scope to specific routes
+      },
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+`applyMiddleware` defaults to `true` when `middleware.routes` is set, otherwise
+`false`. When enabled without explicit `routes`, the middleware is applied to
+`'*'`.
+
+### Manual wiring
+
+You can still apply it yourself for full control over the route configuration:
+
+```ts
+import { MiddlewareConsumer, Module, NestModule } from '@nestjs/common';
+import { TenantConnectionMiddleware } from '@refpool/nestjs';
+
+@Module({ /* imports: [RefPoolModule.forRoot(...)] */ })
+export class AppModule implements NestModule {
+  configure(consumer: MiddlewareConsumer) {
+    consumer.apply(TenantConnectionMiddleware).forRoutes('tenant/*');
+  }
+}
+```
+
+Middleware options (set via `forRoot({ middleware })`): `header`,
+`onMissing` (`'next' | 'error'`), `requestProperty`, `routes`. Plus the
+module-level `applyMiddleware` flag.
+
+## Health route
+
+`RefPoolModule` automatically mounts `ConnectionHealthController`, exposing:
+
+```
+GET /health/connections   →   PoolStats (live, idle, inUse, waiters, hits, …)
+```
+
+## Exports
+
+`RefPoolModule`, `RefPoolService`, `TenantConnectionMiddleware`,
+`ConnectionHealthController`, the DI tokens `REFPOOL_OPTIONS` /
+`REFPOOL_MIDDLEWARE_OPTIONS`, and the option types.
+
+## License
+
+MIT © Atul Singh

package/dist/index.cjs

@@ -0,0 +1,230 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var __decorateClass = (decorators, target, key, kind) => {
+  var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc(target, key) : target;
+  for (var i = decorators.length - 1, decorator; i >= 0; i--)
+    if (decorator = decorators[i])
+      result = (kind ? decorator(target, key, result) : decorator(result)) || result;
+  if (kind && result) __defProp(target, key, result);
+  return result;
+};
+var __decorateParam = (index, decorator) => (target, key) => decorator(target, key, index);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  ConnectionHealthController: () => ConnectionHealthController,
+  REFPOOL_MIDDLEWARE_OPTIONS: () => REFPOOL_MIDDLEWARE_OPTIONS,
+  REFPOOL_OPTIONS: () => REFPOOL_OPTIONS,
+  RefPoolModule: () => RefPoolModule,
+  RefPoolService: () => RefPoolService,
+  TenantConnectionMiddleware: () => TenantConnectionMiddleware
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/ref-pool.module.ts
+var import_common4 = require("@nestjs/common");
+
+// src/health.controller.ts
+var import_common2 = require("@nestjs/common");
+
+// src/ref-pool.service.ts
+var import_common = require("@nestjs/common");
+var import_core = require("@refpool/core");
+
+// src/tokens.ts
+var REFPOOL_OPTIONS = /* @__PURE__ */ Symbol.for("refpool:options");
+var REFPOOL_MIDDLEWARE_OPTIONS = /* @__PURE__ */ Symbol.for("refpool:middleware-options");
+
+// src/ref-pool.service.ts
+var RefPoolService = class {
+  constructor(options) {
+    this.options = options;
+    this.pool = new import_core.RefCountedLruPool(options);
+  }
+  async onModuleInit() {
+    this.pool.start();
+    const shouldWarm = this.options.warmOnInit ?? Boolean(this.options.prewarm);
+    if (shouldWarm) {
+      await this.pool.warm();
+    }
+  }
+  async onApplicationShutdown() {
+    await this.pool.stop();
+  }
+  acquire(key) {
+    return this.pool.acquire(key);
+  }
+  /** Acquire a resource for `key`, run `fn`, and release the handle regardless of outcome. */
+  async withResource(key, fn) {
+    const handle = await this.pool.acquire(key);
+    try {
+      return await fn(handle.resource);
+    } finally {
+      handle.release();
+    }
+  }
+  getStats() {
+    return this.pool.getStats();
+  }
+};
+RefPoolService = __decorateClass([
+  (0, import_common.Injectable)(),
+  __decorateParam(0, (0, import_common.Inject)(REFPOOL_OPTIONS))
+], RefPoolService);
+
+// src/health.controller.ts
+var ConnectionHealthController = class {
+  constructor(service) {
+    this.service = service;
+  }
+  connections() {
+    return this.service.getStats();
+  }
+};
+__decorateClass([
+  (0, import_common2.Get)("connections")
+], ConnectionHealthController.prototype, "connections", 1);
+ConnectionHealthController = __decorateClass([
+  (0, import_common2.Controller)("health"),
+  __decorateParam(0, (0, import_common2.Inject)(RefPoolService))
+], ConnectionHealthController);
+
+// src/tenant-connection.middleware.ts
+var import_common3 = require("@nestjs/common");
+var DEFAULT_HEADER = "x-tenant-id";
+var DEFAULT_PROPERTY = "tenantResource";
+var TenantConnectionMiddleware = class {
+  constructor(service, options) {
+    this.service = service;
+    this.options = options;
+  }
+  async use(req, res, next) {
+    const header = (this.options.header ?? DEFAULT_HEADER).toLowerCase();
+    const property = this.options.requestProperty ?? DEFAULT_PROPERTY;
+    const onMissing = this.options.onMissing ?? "next";
+    const raw = req.headers?.[header];
+    const tenantId = Array.isArray(raw) ? raw[0] : raw;
+    if (!tenantId) {
+      if (onMissing === "error") {
+        next(new Error(`Missing required tenant header "${header}"`));
+        return;
+      }
+      next();
+      return;
+    }
+    let handle;
+    try {
+      handle = await this.service.acquire(tenantId);
+    } catch (error) {
+      next(error);
+      return;
+    }
+    let released = false;
+    const release = () => {
+      if (released) return;
+      released = true;
+      handle.release();
+    };
+    res.on("finish", release);
+    res.on("close", release);
+    req[property] = handle.resource;
+    req[`${property}Key`] = tenantId;
+    next();
+  }
+};
+TenantConnectionMiddleware = __decorateClass([
+  (0, import_common3.Injectable)(),
+  __decorateParam(0, (0, import_common3.Inject)(RefPoolService)),
+  __decorateParam(1, (0, import_common3.Inject)(REFPOOL_MIDDLEWARE_OPTIONS))
+], TenantConnectionMiddleware);
+
+// src/ref-pool.module.ts
+var SHARED = [RefPoolService, TenantConnectionMiddleware];
+var EXPORTS = [
+  RefPoolService,
+  TenantConnectionMiddleware,
+  REFPOOL_OPTIONS,
+  REFPOOL_MIDDLEWARE_OPTIONS
+];
+var RefPoolModule = class {
+  constructor(options) {
+    this.options = options;
+  }
+  /**
+   * Auto-wires {@link TenantConnectionMiddleware} when the drop-in multi-tenant
+   * path is opted into via `applyMiddleware` or `middleware.routes`. Defaults to
+   * `'*'` (all routes) when enabled without explicit routes.
+   */
+  configure(consumer) {
+    const routes = this.options.middleware?.routes;
+    const shouldApply = this.options.applyMiddleware ?? routes !== void 0;
+    if (!shouldApply) return;
+    const forRoutes = routes === void 0 ? ["*"] : Array.isArray(routes) ? routes : [routes];
+    consumer.apply(TenantConnectionMiddleware).forRoutes(...forRoutes);
+  }
+  static forRoot(options) {
+    const providers = [
+      { provide: REFPOOL_OPTIONS, useValue: options },
+      { provide: REFPOOL_MIDDLEWARE_OPTIONS, useValue: options.middleware ?? {} },
+      ...SHARED
+    ];
+    return {
+      module: RefPoolModule,
+      global: options.isGlobal ?? false,
+      providers,
+      controllers: [ConnectionHealthController],
+      exports: EXPORTS
+    };
+  }
+  static forRootAsync(options) {
+    const optionsProvider = {
+      provide: REFPOOL_OPTIONS,
+      useFactory: options.useFactory,
+      inject: options.inject ?? []
+    };
+    const middlewareOptionsProvider = {
+      provide: REFPOOL_MIDDLEWARE_OPTIONS,
+      useFactory: (resolved) => resolved.middleware ?? {},
+      inject: [REFPOOL_OPTIONS]
+    };
+    return {
+      module: RefPoolModule,
+      global: options.isGlobal ?? false,
+      imports: options.imports ?? [],
+      providers: [optionsProvider, middlewareOptionsProvider, ...SHARED],
+      controllers: [ConnectionHealthController],
+      exports: EXPORTS
+    };
+  }
+};
+RefPoolModule = __decorateClass([
+  (0, import_common4.Module)({}),
+  __decorateParam(0, (0, import_common4.Inject)(REFPOOL_OPTIONS))
+], RefPoolModule);
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ConnectionHealthController,
+  REFPOOL_MIDDLEWARE_OPTIONS,
+  REFPOOL_OPTIONS,
+  RefPoolModule,
+  RefPoolService,
+  TenantConnectionMiddleware
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/ref-pool.module.ts","../src/health.controller.ts","../src/ref-pool.service.ts","../src/tokens.ts","../src/tenant-connection.middleware.ts"],"sourcesContent":["export { RefPoolModule } from './ref-pool.module.js';\nexport { RefPoolService } from './ref-pool.service.js';\nexport { TenantConnectionMiddleware } from './tenant-connection.middleware.js';\nexport { ConnectionHealthController } from './health.controller.js';\nexport { REFPOOL_OPTIONS, REFPOOL_MIDDLEWARE_OPTIONS } from './tokens.js';\nexport type {\n  RefPoolModuleOptions,\n  RefPoolModuleAsyncOptions,\n  TenantMiddlewareOptions,\n  MissingTenantBehavior,\n} from './interfaces.js';\n","import { Inject, Module } from '@nestjs/common';\nimport type {\n  DynamicModule,\n  MiddlewareConsumer,\n  NestModule,\n  Provider,\n} from '@nestjs/common';\nimport { ConnectionHealthController } from './health.controller.js';\nimport { RefPoolService } from './ref-pool.service.js';\nimport { TenantConnectionMiddleware } from './tenant-connection.middleware.js';\nimport { REFPOOL_MIDDLEWARE_OPTIONS, REFPOOL_OPTIONS } from './tokens.js';\nimport type {\n  RefPoolModuleAsyncOptions,\n  RefPoolModuleOptions,\n  TenantMiddlewareOptions,\n} from './interfaces.js';\n\nconst SHARED = [RefPoolService, TenantConnectionMiddleware];\nconst EXPORTS = [\n  RefPoolService,\n  TenantConnectionMiddleware,\n  REFPOOL_OPTIONS,\n  REFPOOL_MIDDLEWARE_OPTIONS,\n];\n\n@Module({})\nexport class RefPoolModule implements NestModule {\n  constructor(\n    @Inject(REFPOOL_OPTIONS) private readonly options: RefPoolModuleOptions,\n  ) {}\n\n  /**\n   * Auto-wires {@link TenantConnectionMiddleware} when the drop-in multi-tenant\n   * path is opted into via `applyMiddleware` or `middleware.routes`. Defaults to\n   * `'*'` (all routes) when enabled without explicit routes.\n   */\n  configure(consumer: MiddlewareConsumer): void {\n    const routes = this.options.middleware?.routes;\n    const shouldApply = this.options.applyMiddleware ?? routes !== undefined;\n    if (!shouldApply) return;\n    const forRoutes = routes === undefined ? ['*'] : Array.isArray(routes) ? routes : [routes];\n    consumer.apply(TenantConnectionMiddleware).forRoutes(...forRoutes);\n  }\n\n  static forRoot<T = unknown>(options: RefPoolModuleOptions<T>): DynamicModule {\n    const providers: Provider[] = [\n      { provide: REFPOOL_OPTIONS, useValue: options },\n      { provide: REFPOOL_MIDDLEWARE_OPTIONS, useValue: options.middleware ?? {} },\n      ...SHARED,\n    ];\n    return {\n      module: RefPoolModule,\n      global: options.isGlobal ?? false,\n      providers,\n      controllers: [ConnectionHealthController],\n      exports: EXPORTS,\n    };\n  }\n\n  static forRootAsync<T = unknown>(options: RefPoolModuleAsyncOptions<T>): DynamicModule {\n    const optionsProvider: Provider = {\n      provide: REFPOOL_OPTIONS,\n      useFactory: options.useFactory,\n      inject: options.inject ?? [],\n    };\n    const middlewareOptionsProvider: Provider = {\n      provide: REFPOOL_MIDDLEWARE_OPTIONS,\n      useFactory: (resolved: RefPoolModuleOptions<T>): TenantMiddlewareOptions =>\n        resolved.middleware ?? {},\n      inject: [REFPOOL_OPTIONS],\n    };\n    return {\n      module: RefPoolModule,\n      global: options.isGlobal ?? false,\n      imports: options.imports ?? [],\n      providers: [optionsProvider, middlewareOptionsProvider, ...SHARED],\n      controllers: [ConnectionHealthController],\n      exports: EXPORTS,\n    };\n  }\n}\n","import { Controller, Get, Inject } from '@nestjs/common';\nimport type { PoolStats } from '@refpool/core';\nimport { RefPoolService } from './ref-pool.service.js';\n\n@Controller('health')\nexport class ConnectionHealthController {\n  constructor(@Inject(RefPoolService) private readonly service: RefPoolService) {}\n\n  @Get('connections')\n  connections(): PoolStats {\n    return this.service.getStats();\n  }\n}\n","import { Inject, Injectable } from '@nestjs/common';\nimport type { OnApplicationShutdown, OnModuleInit } from '@nestjs/common';\nimport { RefCountedLruPool } from '@refpool/core';\nimport type { AcquireHandle, PoolStats } from '@refpool/core';\nimport { REFPOOL_OPTIONS } from './tokens.js';\nimport type { RefPoolModuleOptions } from './interfaces.js';\n\n@Injectable()\nexport class RefPoolService<T = unknown> implements OnModuleInit, OnApplicationShutdown {\n  /** The underlying pool. Exposed for advanced use (event subscription, etc.). */\n  readonly pool: RefCountedLruPool<T>;\n\n  constructor(@Inject(REFPOOL_OPTIONS) private readonly options: RefPoolModuleOptions<T>) {\n    this.pool = new RefCountedLruPool<T>(options);\n  }\n\n  async onModuleInit(): Promise<void> {\n    this.pool.start();\n    const shouldWarm = this.options.warmOnInit ?? Boolean(this.options.prewarm);\n    if (shouldWarm) {\n      await this.pool.warm();\n    }\n  }\n\n  async onApplicationShutdown(): Promise<void> {\n    await this.pool.stop();\n  }\n\n  acquire(key: string): Promise<AcquireHandle<T>> {\n    return this.pool.acquire(key);\n  }\n\n  /** Acquire a resource for `key`, run `fn`, and release the handle regardless of outcome. */\n  async withResource<R>(key: string, fn: (resource: T) => R | Promise<R>): Promise<R> {\n    const handle = await this.pool.acquire(key);\n    try {\n      return await fn(handle.resource);\n    } finally {\n      handle.release();\n    }\n  }\n\n  getStats(): PoolStats {\n    return this.pool.getStats();\n  }\n}\n","/** DI token holding the resolved {@link RefPoolModuleOptions}. */\nexport const REFPOOL_OPTIONS = Symbol.for('refpool:options');\n\n/** DI token holding the resolved {@link TenantMiddlewareOptions}. */\nexport const REFPOOL_MIDDLEWARE_OPTIONS = Symbol.for('refpool:middleware-options');\n","import { Inject, Injectable } from '@nestjs/common';\nimport type { NestMiddleware } from '@nestjs/common';\nimport type { AcquireHandle } from '@refpool/core';\nimport { RefPoolService } from './ref-pool.service.js';\nimport { REFPOOL_MIDDLEWARE_OPTIONS } from './tokens.js';\nimport type { TenantMiddlewareOptions } from './interfaces.js';\n\nconst DEFAULT_HEADER = 'x-tenant-id';\nconst DEFAULT_PROPERTY = 'tenantResource';\n\ninterface MinimalRequest {\n  headers?: Record<string, string | string[] | undefined>;\n  [key: string]: unknown;\n}\n\ninterface MinimalResponse {\n  on(event: string, listener: () => void): unknown;\n}\n\ntype NextFn = (error?: unknown) => void;\n\n@Injectable()\nexport class TenantConnectionMiddleware implements NestMiddleware {\n  constructor(\n    @Inject(RefPoolService) private readonly service: RefPoolService,\n    @Inject(REFPOOL_MIDDLEWARE_OPTIONS) private readonly options: TenantMiddlewareOptions,\n  ) {}\n\n  async use(req: MinimalRequest, res: MinimalResponse, next: NextFn): Promise<void> {\n    const header = (this.options.header ?? DEFAULT_HEADER).toLowerCase();\n    const property = this.options.requestProperty ?? DEFAULT_PROPERTY;\n    const onMissing = this.options.onMissing ?? 'next';\n\n    const raw = req.headers?.[header];\n    const tenantId = Array.isArray(raw) ? raw[0] : raw;\n\n    if (!tenantId) {\n      if (onMissing === 'error') {\n        next(new Error(`Missing required tenant header \"${header}\"`));\n        return;\n      }\n      next();\n      return;\n    }\n\n    let handle: AcquireHandle<unknown>;\n    try {\n      handle = await this.service.acquire(tenantId);\n    } catch (error) {\n      next(error);\n      return;\n    }\n\n    let released = false;\n    const release = (): void => {\n      if (released) return;\n      released = true;\n      handle.release();\n    };\n    res.on('finish', release);\n    res.on('close', release);\n\n    req[property] = handle.resource;\n    req[`${property}Key`] = tenantId;\n    next();\n  }\n}\n"],"mappings":"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","names":["import_common","import_common","import_common"]}

package/dist/index.d.cts

@@ -0,0 +1,92 @@
+import { ModuleMetadata, InjectionToken, OptionalFactoryDependency, NestModule, MiddlewareConsumer, DynamicModule, OnModuleInit, OnApplicationShutdown, NestMiddleware } from '@nestjs/common';
+import { PoolOptions, RefCountedLruPool, AcquireHandle, PoolStats } from '@refpool/core';
+
+/** Behavior when an incoming request lacks the configured tenant header. */
+type MissingTenantBehavior = 'next' | 'error';
+interface TenantMiddlewareOptions {
+    /** Request header carrying the tenant key. Default `x-tenant-id`. */
+    header?: string;
+    /** What to do when the header is absent. Default `next` (skip acquisition). */
+    onMissing?: MissingTenantBehavior;
+    /** Property on the request used to attach the acquired resource. Default `tenantResource`. */
+    requestProperty?: string;
+    /**
+     * Routes to auto-apply {@link TenantConnectionMiddleware} to. Setting this
+     * opts into wiring; omit it (or pass `applyMiddleware`) to fall back to `'*'`.
+     */
+    routes?: string | string[];
+}
+interface RefPoolModuleOptions<T = unknown> extends PoolOptions<T> {
+    /** Register the module globally so its exports are available app-wide. */
+    isGlobal?: boolean;
+    /** Run `pool.warm()` during `OnModuleInit`. Defaults to `true` when `prewarm` is set. */
+    warmOnInit?: boolean;
+    /** Defaults for {@link TenantConnectionMiddleware}. */
+    middleware?: TenantMiddlewareOptions;
+    /**
+     * Auto-apply {@link TenantConnectionMiddleware} for the whole app. Defaults to
+     * `true` when `middleware.routes` is set, otherwise `false`. When enabled
+     * without explicit `routes`, the middleware is applied to `'*'`.
+     */
+    applyMiddleware?: boolean;
+}
+interface RefPoolModuleAsyncOptions<T = unknown> extends Pick<ModuleMetadata, 'imports'> {
+    inject?: Array<InjectionToken | OptionalFactoryDependency>;
+    useFactory: (...args: any[]) => RefPoolModuleOptions<T> | Promise<RefPoolModuleOptions<T>>;
+    /** Register the module globally so its exports are available app-wide. */
+    isGlobal?: boolean;
+}
+
+declare class RefPoolModule implements NestModule {
+    private readonly options;
+    constructor(options: RefPoolModuleOptions);
+    /**
+     * Auto-wires {@link TenantConnectionMiddleware} when the drop-in multi-tenant
+     * path is opted into via `applyMiddleware` or `middleware.routes`. Defaults to
+     * `'*'` (all routes) when enabled without explicit routes.
+     */
+    configure(consumer: MiddlewareConsumer): void;
+    static forRoot<T = unknown>(options: RefPoolModuleOptions<T>): DynamicModule;
+    static forRootAsync<T = unknown>(options: RefPoolModuleAsyncOptions<T>): DynamicModule;
+}
+
+declare class RefPoolService<T = unknown> implements OnModuleInit, OnApplicationShutdown {
+    private readonly options;
+    /** The underlying pool. Exposed for advanced use (event subscription, etc.). */
+    readonly pool: RefCountedLruPool<T>;
+    constructor(options: RefPoolModuleOptions<T>);
+    onModuleInit(): Promise<void>;
+    onApplicationShutdown(): Promise<void>;
+    acquire(key: string): Promise<AcquireHandle<T>>;
+    /** Acquire a resource for `key`, run `fn`, and release the handle regardless of outcome. */
+    withResource<R>(key: string, fn: (resource: T) => R | Promise<R>): Promise<R>;
+    getStats(): PoolStats;
+}
+
+interface MinimalRequest {
+    headers?: Record<string, string | string[] | undefined>;
+    [key: string]: unknown;
+}
+interface MinimalResponse {
+    on(event: string, listener: () => void): unknown;
+}
+type NextFn = (error?: unknown) => void;
+declare class TenantConnectionMiddleware implements NestMiddleware {
+    private readonly service;
+    private readonly options;
+    constructor(service: RefPoolService, options: TenantMiddlewareOptions);
+    use(req: MinimalRequest, res: MinimalResponse, next: NextFn): Promise<void>;
+}
+
+declare class ConnectionHealthController {
+    private readonly service;
+    constructor(service: RefPoolService);
+    connections(): PoolStats;
+}
+
+/** DI token holding the resolved {@link RefPoolModuleOptions}. */
+declare const REFPOOL_OPTIONS: unique symbol;
+/** DI token holding the resolved {@link TenantMiddlewareOptions}. */
+declare const REFPOOL_MIDDLEWARE_OPTIONS: unique symbol;
+
+export { ConnectionHealthController, type MissingTenantBehavior, REFPOOL_MIDDLEWARE_OPTIONS, REFPOOL_OPTIONS, RefPoolModule, type RefPoolModuleAsyncOptions, type RefPoolModuleOptions, RefPoolService, TenantConnectionMiddleware, type TenantMiddlewareOptions };

package/dist/index.d.ts

@@ -0,0 +1,92 @@
+import { ModuleMetadata, InjectionToken, OptionalFactoryDependency, NestModule, MiddlewareConsumer, DynamicModule, OnModuleInit, OnApplicationShutdown, NestMiddleware } from '@nestjs/common';
+import { PoolOptions, RefCountedLruPool, AcquireHandle, PoolStats } from '@refpool/core';
+
+/** Behavior when an incoming request lacks the configured tenant header. */
+type MissingTenantBehavior = 'next' | 'error';
+interface TenantMiddlewareOptions {
+    /** Request header carrying the tenant key. Default `x-tenant-id`. */
+    header?: string;
+    /** What to do when the header is absent. Default `next` (skip acquisition). */
+    onMissing?: MissingTenantBehavior;
+    /** Property on the request used to attach the acquired resource. Default `tenantResource`. */
+    requestProperty?: string;
+    /**
+     * Routes to auto-apply {@link TenantConnectionMiddleware} to. Setting this
+     * opts into wiring; omit it (or pass `applyMiddleware`) to fall back to `'*'`.
+     */
+    routes?: string | string[];
+}
+interface RefPoolModuleOptions<T = unknown> extends PoolOptions<T> {
+    /** Register the module globally so its exports are available app-wide. */
+    isGlobal?: boolean;
+    /** Run `pool.warm()` during `OnModuleInit`. Defaults to `true` when `prewarm` is set. */
+    warmOnInit?: boolean;
+    /** Defaults for {@link TenantConnectionMiddleware}. */
+    middleware?: TenantMiddlewareOptions;
+    /**
+     * Auto-apply {@link TenantConnectionMiddleware} for the whole app. Defaults to
+     * `true` when `middleware.routes` is set, otherwise `false`. When enabled
+     * without explicit `routes`, the middleware is applied to `'*'`.
+     */
+    applyMiddleware?: boolean;
+}
+interface RefPoolModuleAsyncOptions<T = unknown> extends Pick<ModuleMetadata, 'imports'> {
+    inject?: Array<InjectionToken | OptionalFactoryDependency>;
+    useFactory: (...args: any[]) => RefPoolModuleOptions<T> | Promise<RefPoolModuleOptions<T>>;
+    /** Register the module globally so its exports are available app-wide. */
+    isGlobal?: boolean;
+}
+
+declare class RefPoolModule implements NestModule {
+    private readonly options;
+    constructor(options: RefPoolModuleOptions);
+    /**
+     * Auto-wires {@link TenantConnectionMiddleware} when the drop-in multi-tenant
+     * path is opted into via `applyMiddleware` or `middleware.routes`. Defaults to
+     * `'*'` (all routes) when enabled without explicit routes.
+     */
+    configure(consumer: MiddlewareConsumer): void;
+    static forRoot<T = unknown>(options: RefPoolModuleOptions<T>): DynamicModule;
+    static forRootAsync<T = unknown>(options: RefPoolModuleAsyncOptions<T>): DynamicModule;
+}
+
+declare class RefPoolService<T = unknown> implements OnModuleInit, OnApplicationShutdown {
+    private readonly options;
+    /** The underlying pool. Exposed for advanced use (event subscription, etc.). */
+    readonly pool: RefCountedLruPool<T>;
+    constructor(options: RefPoolModuleOptions<T>);
+    onModuleInit(): Promise<void>;
+    onApplicationShutdown(): Promise<void>;
+    acquire(key: string): Promise<AcquireHandle<T>>;
+    /** Acquire a resource for `key`, run `fn`, and release the handle regardless of outcome. */
+    withResource<R>(key: string, fn: (resource: T) => R | Promise<R>): Promise<R>;
+    getStats(): PoolStats;
+}
+
+interface MinimalRequest {
+    headers?: Record<string, string | string[] | undefined>;
+    [key: string]: unknown;
+}
+interface MinimalResponse {
+    on(event: string, listener: () => void): unknown;
+}
+type NextFn = (error?: unknown) => void;
+declare class TenantConnectionMiddleware implements NestMiddleware {
+    private readonly service;
+    private readonly options;
+    constructor(service: RefPoolService, options: TenantMiddlewareOptions);
+    use(req: MinimalRequest, res: MinimalResponse, next: NextFn): Promise<void>;
+}
+
+declare class ConnectionHealthController {
+    private readonly service;
+    constructor(service: RefPoolService);
+    connections(): PoolStats;
+}
+
+/** DI token holding the resolved {@link RefPoolModuleOptions}. */
+declare const REFPOOL_OPTIONS: unique symbol;
+/** DI token holding the resolved {@link TenantMiddlewareOptions}. */
+declare const REFPOOL_MIDDLEWARE_OPTIONS: unique symbol;
+
+export { ConnectionHealthController, type MissingTenantBehavior, REFPOOL_MIDDLEWARE_OPTIONS, REFPOOL_OPTIONS, RefPoolModule, type RefPoolModuleAsyncOptions, type RefPoolModuleOptions, RefPoolService, TenantConnectionMiddleware, type TenantMiddlewareOptions };

package/dist/index.js

@@ -0,0 +1,201 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __decorateClass = (decorators, target, key, kind) => {
+  var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc(target, key) : target;
+  for (var i = decorators.length - 1, decorator; i >= 0; i--)
+    if (decorator = decorators[i])
+      result = (kind ? decorator(target, key, result) : decorator(result)) || result;
+  if (kind && result) __defProp(target, key, result);
+  return result;
+};
+var __decorateParam = (index, decorator) => (target, key) => decorator(target, key, index);
+
+// src/ref-pool.module.ts
+import { Inject as Inject4, Module } from "@nestjs/common";
+
+// src/health.controller.ts
+import { Controller, Get, Inject as Inject2 } from "@nestjs/common";
+
+// src/ref-pool.service.ts
+import { Inject, Injectable } from "@nestjs/common";
+import { RefCountedLruPool } from "@refpool/core";
+
+// src/tokens.ts
+var REFPOOL_OPTIONS = /* @__PURE__ */ Symbol.for("refpool:options");
+var REFPOOL_MIDDLEWARE_OPTIONS = /* @__PURE__ */ Symbol.for("refpool:middleware-options");
+
+// src/ref-pool.service.ts
+var RefPoolService = class {
+  constructor(options) {
+    this.options = options;
+    this.pool = new RefCountedLruPool(options);
+  }
+  async onModuleInit() {
+    this.pool.start();
+    const shouldWarm = this.options.warmOnInit ?? Boolean(this.options.prewarm);
+    if (shouldWarm) {
+      await this.pool.warm();
+    }
+  }
+  async onApplicationShutdown() {
+    await this.pool.stop();
+  }
+  acquire(key) {
+    return this.pool.acquire(key);
+  }
+  /** Acquire a resource for `key`, run `fn`, and release the handle regardless of outcome. */
+  async withResource(key, fn) {
+    const handle = await this.pool.acquire(key);
+    try {
+      return await fn(handle.resource);
+    } finally {
+      handle.release();
+    }
+  }
+  getStats() {
+    return this.pool.getStats();
+  }
+};
+RefPoolService = __decorateClass([
+  Injectable(),
+  __decorateParam(0, Inject(REFPOOL_OPTIONS))
+], RefPoolService);
+
+// src/health.controller.ts
+var ConnectionHealthController = class {
+  constructor(service) {
+    this.service = service;
+  }
+  connections() {
+    return this.service.getStats();
+  }
+};
+__decorateClass([
+  Get("connections")
+], ConnectionHealthController.prototype, "connections", 1);
+ConnectionHealthController = __decorateClass([
+  Controller("health"),
+  __decorateParam(0, Inject2(RefPoolService))
+], ConnectionHealthController);
+
+// src/tenant-connection.middleware.ts
+import { Inject as Inject3, Injectable as Injectable2 } from "@nestjs/common";
+var DEFAULT_HEADER = "x-tenant-id";
+var DEFAULT_PROPERTY = "tenantResource";
+var TenantConnectionMiddleware = class {
+  constructor(service, options) {
+    this.service = service;
+    this.options = options;
+  }
+  async use(req, res, next) {
+    const header = (this.options.header ?? DEFAULT_HEADER).toLowerCase();
+    const property = this.options.requestProperty ?? DEFAULT_PROPERTY;
+    const onMissing = this.options.onMissing ?? "next";
+    const raw = req.headers?.[header];
+    const tenantId = Array.isArray(raw) ? raw[0] : raw;
+    if (!tenantId) {
+      if (onMissing === "error") {
+        next(new Error(`Missing required tenant header "${header}"`));
+        return;
+      }
+      next();
+      return;
+    }
+    let handle;
+    try {
+      handle = await this.service.acquire(tenantId);
+    } catch (error) {
+      next(error);
+      return;
+    }
+    let released = false;
+    const release = () => {
+      if (released) return;
+      released = true;
+      handle.release();
+    };
+    res.on("finish", release);
+    res.on("close", release);
+    req[property] = handle.resource;
+    req[`${property}Key`] = tenantId;
+    next();
+  }
+};
+TenantConnectionMiddleware = __decorateClass([
+  Injectable2(),
+  __decorateParam(0, Inject3(RefPoolService)),
+  __decorateParam(1, Inject3(REFPOOL_MIDDLEWARE_OPTIONS))
+], TenantConnectionMiddleware);
+
+// src/ref-pool.module.ts
+var SHARED = [RefPoolService, TenantConnectionMiddleware];
+var EXPORTS = [
+  RefPoolService,
+  TenantConnectionMiddleware,
+  REFPOOL_OPTIONS,
+  REFPOOL_MIDDLEWARE_OPTIONS
+];
+var RefPoolModule = class {
+  constructor(options) {
+    this.options = options;
+  }
+  /**
+   * Auto-wires {@link TenantConnectionMiddleware} when the drop-in multi-tenant
+   * path is opted into via `applyMiddleware` or `middleware.routes`. Defaults to
+   * `'*'` (all routes) when enabled without explicit routes.
+   */
+  configure(consumer) {
+    const routes = this.options.middleware?.routes;
+    const shouldApply = this.options.applyMiddleware ?? routes !== void 0;
+    if (!shouldApply) return;
+    const forRoutes = routes === void 0 ? ["*"] : Array.isArray(routes) ? routes : [routes];
+    consumer.apply(TenantConnectionMiddleware).forRoutes(...forRoutes);
+  }
+  static forRoot(options) {
+    const providers = [
+      { provide: REFPOOL_OPTIONS, useValue: options },
+      { provide: REFPOOL_MIDDLEWARE_OPTIONS, useValue: options.middleware ?? {} },
+      ...SHARED
+    ];
+    return {
+      module: RefPoolModule,
+      global: options.isGlobal ?? false,
+      providers,
+      controllers: [ConnectionHealthController],
+      exports: EXPORTS
+    };
+  }
+  static forRootAsync(options) {
+    const optionsProvider = {
+      provide: REFPOOL_OPTIONS,
+      useFactory: options.useFactory,
+      inject: options.inject ?? []
+    };
+    const middlewareOptionsProvider = {
+      provide: REFPOOL_MIDDLEWARE_OPTIONS,
+      useFactory: (resolved) => resolved.middleware ?? {},
+      inject: [REFPOOL_OPTIONS]
+    };
+    return {
+      module: RefPoolModule,
+      global: options.isGlobal ?? false,
+      imports: options.imports ?? [],
+      providers: [optionsProvider, middlewareOptionsProvider, ...SHARED],
+      controllers: [ConnectionHealthController],
+      exports: EXPORTS
+    };
+  }
+};
+RefPoolModule = __decorateClass([
+  Module({}),
+  __decorateParam(0, Inject4(REFPOOL_OPTIONS))
+], RefPoolModule);
+export {
+  ConnectionHealthController,
+  REFPOOL_MIDDLEWARE_OPTIONS,
+  REFPOOL_OPTIONS,
+  RefPoolModule,
+  RefPoolService,
+  TenantConnectionMiddleware
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/ref-pool.module.ts","../src/health.controller.ts","../src/ref-pool.service.ts","../src/tokens.ts","../src/tenant-connection.middleware.ts"],"sourcesContent":["import { Inject, Module } from '@nestjs/common';\nimport type {\n  DynamicModule,\n  MiddlewareConsumer,\n  NestModule,\n  Provider,\n} from '@nestjs/common';\nimport { ConnectionHealthController } from './health.controller.js';\nimport { RefPoolService } from './ref-pool.service.js';\nimport { TenantConnectionMiddleware } from './tenant-connection.middleware.js';\nimport { REFPOOL_MIDDLEWARE_OPTIONS, REFPOOL_OPTIONS } from './tokens.js';\nimport type {\n  RefPoolModuleAsyncOptions,\n  RefPoolModuleOptions,\n  TenantMiddlewareOptions,\n} from './interfaces.js';\n\nconst SHARED = [RefPoolService, TenantConnectionMiddleware];\nconst EXPORTS = [\n  RefPoolService,\n  TenantConnectionMiddleware,\n  REFPOOL_OPTIONS,\n  REFPOOL_MIDDLEWARE_OPTIONS,\n];\n\n@Module({})\nexport class RefPoolModule implements NestModule {\n  constructor(\n    @Inject(REFPOOL_OPTIONS) private readonly options: RefPoolModuleOptions,\n  ) {}\n\n  /**\n   * Auto-wires {@link TenantConnectionMiddleware} when the drop-in multi-tenant\n   * path is opted into via `applyMiddleware` or `middleware.routes`. Defaults to\n   * `'*'` (all routes) when enabled without explicit routes.\n   */\n  configure(consumer: MiddlewareConsumer): void {\n    const routes = this.options.middleware?.routes;\n    const shouldApply = this.options.applyMiddleware ?? routes !== undefined;\n    if (!shouldApply) return;\n    const forRoutes = routes === undefined ? ['*'] : Array.isArray(routes) ? routes : [routes];\n    consumer.apply(TenantConnectionMiddleware).forRoutes(...forRoutes);\n  }\n\n  static forRoot<T = unknown>(options: RefPoolModuleOptions<T>): DynamicModule {\n    const providers: Provider[] = [\n      { provide: REFPOOL_OPTIONS, useValue: options },\n      { provide: REFPOOL_MIDDLEWARE_OPTIONS, useValue: options.middleware ?? {} },\n      ...SHARED,\n    ];\n    return {\n      module: RefPoolModule,\n      global: options.isGlobal ?? false,\n      providers,\n      controllers: [ConnectionHealthController],\n      exports: EXPORTS,\n    };\n  }\n\n  static forRootAsync<T = unknown>(options: RefPoolModuleAsyncOptions<T>): DynamicModule {\n    const optionsProvider: Provider = {\n      provide: REFPOOL_OPTIONS,\n      useFactory: options.useFactory,\n      inject: options.inject ?? [],\n    };\n    const middlewareOptionsProvider: Provider = {\n      provide: REFPOOL_MIDDLEWARE_OPTIONS,\n      useFactory: (resolved: RefPoolModuleOptions<T>): TenantMiddlewareOptions =>\n        resolved.middleware ?? {},\n      inject: [REFPOOL_OPTIONS],\n    };\n    return {\n      module: RefPoolModule,\n      global: options.isGlobal ?? false,\n      imports: options.imports ?? [],\n      providers: [optionsProvider, middlewareOptionsProvider, ...SHARED],\n      controllers: [ConnectionHealthController],\n      exports: EXPORTS,\n    };\n  }\n}\n","import { Controller, Get, Inject } from '@nestjs/common';\nimport type { PoolStats } from '@refpool/core';\nimport { RefPoolService } from './ref-pool.service.js';\n\n@Controller('health')\nexport class ConnectionHealthController {\n  constructor(@Inject(RefPoolService) private readonly service: RefPoolService) {}\n\n  @Get('connections')\n  connections(): PoolStats {\n    return this.service.getStats();\n  }\n}\n","import { Inject, Injectable } from '@nestjs/common';\nimport type { OnApplicationShutdown, OnModuleInit } from '@nestjs/common';\nimport { RefCountedLruPool } from '@refpool/core';\nimport type { AcquireHandle, PoolStats } from '@refpool/core';\nimport { REFPOOL_OPTIONS } from './tokens.js';\nimport type { RefPoolModuleOptions } from './interfaces.js';\n\n@Injectable()\nexport class RefPoolService<T = unknown> implements OnModuleInit, OnApplicationShutdown {\n  /** The underlying pool. Exposed for advanced use (event subscription, etc.). */\n  readonly pool: RefCountedLruPool<T>;\n\n  constructor(@Inject(REFPOOL_OPTIONS) private readonly options: RefPoolModuleOptions<T>) {\n    this.pool = new RefCountedLruPool<T>(options);\n  }\n\n  async onModuleInit(): Promise<void> {\n    this.pool.start();\n    const shouldWarm = this.options.warmOnInit ?? Boolean(this.options.prewarm);\n    if (shouldWarm) {\n      await this.pool.warm();\n    }\n  }\n\n  async onApplicationShutdown(): Promise<void> {\n    await this.pool.stop();\n  }\n\n  acquire(key: string): Promise<AcquireHandle<T>> {\n    return this.pool.acquire(key);\n  }\n\n  /** Acquire a resource for `key`, run `fn`, and release the handle regardless of outcome. */\n  async withResource<R>(key: string, fn: (resource: T) => R | Promise<R>): Promise<R> {\n    const handle = await this.pool.acquire(key);\n    try {\n      return await fn(handle.resource);\n    } finally {\n      handle.release();\n    }\n  }\n\n  getStats(): PoolStats {\n    return this.pool.getStats();\n  }\n}\n","/** DI token holding the resolved {@link RefPoolModuleOptions}. */\nexport const REFPOOL_OPTIONS = Symbol.for('refpool:options');\n\n/** DI token holding the resolved {@link TenantMiddlewareOptions}. */\nexport const REFPOOL_MIDDLEWARE_OPTIONS = Symbol.for('refpool:middleware-options');\n","import { Inject, Injectable } from '@nestjs/common';\nimport type { NestMiddleware } from '@nestjs/common';\nimport type { AcquireHandle } from '@refpool/core';\nimport { RefPoolService } from './ref-pool.service.js';\nimport { REFPOOL_MIDDLEWARE_OPTIONS } from './tokens.js';\nimport type { TenantMiddlewareOptions } from './interfaces.js';\n\nconst DEFAULT_HEADER = 'x-tenant-id';\nconst DEFAULT_PROPERTY = 'tenantResource';\n\ninterface MinimalRequest {\n  headers?: Record<string, string | string[] | undefined>;\n  [key: string]: unknown;\n}\n\ninterface MinimalResponse {\n  on(event: string, listener: () => void): unknown;\n}\n\ntype NextFn = (error?: unknown) => void;\n\n@Injectable()\nexport class TenantConnectionMiddleware implements NestMiddleware {\n  constructor(\n    @Inject(RefPoolService) private readonly service: RefPoolService,\n    @Inject(REFPOOL_MIDDLEWARE_OPTIONS) private readonly options: TenantMiddlewareOptions,\n  ) {}\n\n  async use(req: MinimalRequest, res: MinimalResponse, next: NextFn): Promise<void> {\n    const header = (this.options.header ?? DEFAULT_HEADER).toLowerCase();\n    const property = this.options.requestProperty ?? DEFAULT_PROPERTY;\n    const onMissing = this.options.onMissing ?? 'next';\n\n    const raw = req.headers?.[header];\n    const tenantId = Array.isArray(raw) ? raw[0] : raw;\n\n    if (!tenantId) {\n      if (onMissing === 'error') {\n        next(new Error(`Missing required tenant header \"${header}\"`));\n        return;\n      }\n      next();\n      return;\n    }\n\n    let handle: AcquireHandle<unknown>;\n    try {\n      handle = await this.service.acquire(tenantId);\n    } catch (error) {\n      next(error);\n      return;\n    }\n\n    let released = false;\n    const release = (): void => {\n      if (released) return;\n      released = true;\n      handle.release();\n    };\n    res.on('finish', release);\n    res.on('close', release);\n\n    req[property] = handle.resource;\n    req[`${property}Key`] = tenantId;\n    next();\n  }\n}\n"],"mappings":"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","names":["Inject","Inject","Inject","Inject","Injectable","Injectable","Inject","Inject"]}

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "@refpool/nestjs",
+  "version": "0.1.0",
+  "description": "NestJS integration for refpool: dynamic module, injectable service, multi-tenant connection middleware, and a connection health controller.",
+  "license": "MIT",
+  "author": "Atul Singh <atulsingh.harsh@gmail.com> (https://atulsingh.io)",
+  "type": "module",
+  "sideEffects": false,
+  "keywords": [
+    "nestjs",
+    "pool",
+    "resource-pool",
+    "reference-counting",
+    "multi-tenant",
+    "connection-pool",
+    "middleware"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/expedite-atul/refpool.git",
+    "directory": "packages/nestjs"
+  },
+  "homepage": "https://github.com/expedite-atul/refpool/tree/main/packages/nestjs#readme",
+  "bugs": {
+    "url": "https://github.com/expedite-atul/refpool/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@refpool/core": "0.1.0"
+  },
+  "peerDependencies": {
+    "@nestjs/common": "^10.0.0 || ^11.0.0",
+    "@nestjs/core": "^10.0.0 || ^11.0.0",
+    "reflect-metadata": "^0.1.13 || ^0.2.0",
+    "rxjs": "^7.8.0"
+  },
+  "devDependencies": {
+    "@nestjs/common": "^11.0.0",
+    "@nestjs/core": "^11.0.0",
+    "@nestjs/testing": "^11.0.0",
+    "@types/node": "^22.10.2",
+    "reflect-metadata": "^0.2.2",
+    "rxjs": "^7.8.1",
+    "tsup": "^8.3.5",
+    "typescript": "^5.6.3",
+    "vitest": "^2.1.8"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}