drizzle-multitenant 1.0.2 → 1.0.3

package/README.md

@@ -134,7 +134,7 @@ import { TenantModule, InjectTenantDb } from 'drizzle-multitenant/nestjs';
 })
 export class AppModule {}
 
-@Injectable()
+@Injectable({ scope: Scope.REQUEST })
 export class UserService {
   constructor(@InjectTenantDb() private readonly db: TenantDb) {}
 
@@ -144,6 +144,59 @@ export class UserService {
 }
 ```
 
+#### Singleton Services (Cron Jobs, Event Handlers)
+
+Use `TenantDbFactory` when you need to access tenant databases from singleton services:
+
+```typescript
+import { TenantDbFactory, InjectTenantDbFactory } from 'drizzle-multitenant/nestjs';
+
+@Injectable() // Singleton - no scope needed
+export class ReportService {
+  constructor(@InjectTenantDbFactory() private dbFactory: TenantDbFactory) {}
+
+  async generateReport(tenantId: string) {
+    const db = this.dbFactory.getDb(tenantId);
+    return db.select().from(reports);
+  }
+}
+
+// Cron job example
+@Injectable()
+export class DailyReportCron {
+  constructor(@InjectTenantDbFactory() private dbFactory: TenantDbFactory) {}
+
+  @Cron('0 8 * * *')
+  async run() {
+    const tenants = await this.getTenantIds();
+    for (const tenantId of tenants) {
+      const db = this.dbFactory.getDb(tenantId);
+      await this.processReports(db);
+    }
+  }
+}
+```
+
+#### Debugging
+
+The injected `TenantDb` provides debug utilities:
+
+```typescript
+// Console output shows useful info
+console.log(tenantDb);
+// [TenantDb] tenant=123 schema=empresa_123
+
+// Access debug information
+console.log(tenantDb.__debug);
+// { tenantId: '123', schemaName: 'empresa_123', isProxy: true, poolCount: 5 }
+
+// Quick access
+console.log(tenantDb.__tenantId); // '123'
+
+// In tests
+expect(tenantDb.__tenantId).toBe('expected-tenant');
+```
+
 ## CLI Commands
 
 ```bash
@@ -222,13 +275,24 @@ const result = await query
 
 | Decorator | Description |
 |-----------|-------------|
-| `@InjectTenantDb()` | Inject tenant database |
+| `@InjectTenantDb()` | Inject tenant database (request-scoped) |
+| `@InjectTenantDbFactory()` | Inject factory for singleton services |
 | `@InjectSharedDb()` | Inject shared database |
 | `@InjectTenantContext()` | Inject tenant context |
 | `@InjectTenantManager()` | Inject tenant manager |
 | `@RequiresTenant()` | Mark route as requiring tenant |
 | `@PublicRoute()` | Mark route as public |
 
+### TenantDbFactory Methods
+
+| Method | Description |
+|--------|-------------|
+| `getDb(tenantId)` | Get Drizzle instance for tenant |
+| `getSharedDb()` | Get shared database instance |
+| `getSchemaName(tenantId)` | Get schema name for tenant |
+| `getDebugInfo(tenantId)` | Get debug info (tenantId, schema, pool stats) |
+| `getManager()` | Get underlying TenantManager |
+
 ## Requirements
 
 - Node.js 18+

package/dist/integrations/nestjs/index.d.ts

@@ -1,8 +1,7 @@
 import * as _nestjs_common from '@nestjs/common';
 import { ModuleMetadata, Type, InjectionToken, DynamicModule, CanActivate, ExecutionContext, NestInterceptor, CallHandler, Provider } from '@nestjs/common';
 import { Request } from 'express';
-import { C as Config, T as TenantManager } from '../../types-DKVaTaIb.js';
-export { S as SharedDb, a as TenantDb } from '../../types-DKVaTaIb.js';
+import { C as Config, a as TenantDb, T as TenantManager, S as SharedDb } from '../../types-DKVaTaIb.js';
 import { Reflector } from '@nestjs/core';
 import { Observable } from 'rxjs';
 import 'pg';
@@ -70,6 +69,32 @@ interface TenantRequest extends Request {
     tenantContext?: NestTenantContext;
     tenantId?: string;
 }
+/**
+ * Debug information available on TenantDb proxy
+ */
+interface TenantDbDebugInfo$1 {
+    /** Current tenant ID (null if not resolved) */
+    tenantId: string | null;
+    /** Schema name for the tenant (null if not resolved) */
+    schemaName: string | null;
+    /** Whether this is a proxy object */
+    isProxy: boolean;
+    /** Number of active connection pools */
+    poolCount: number;
+}
+/**
+ * Extended TenantDb interface with debug utilities
+ *
+ * Available when using @InjectTenantDb() - provides debugging helpers
+ */
+interface TenantDbWithDebug<T extends Record<string, unknown> = Record<string, unknown>> extends TenantDb<T> {
+    /** Debug information about the current tenant connection */
+    __debug: TenantDbDebugInfo$1;
+    /** Current tenant ID (null if not resolved) */
+    __tenantId: string | null;
+    /** Whether this is a proxy object */
+    __isProxy: true;
+}
 
 /**
  * NestJS module for multi-tenant support
@@ -127,6 +152,95 @@ declare class TenantModule {
  */
 declare const DrizzleMultitenantModule: typeof TenantModule;
 
+/**
+ * Debug information for tenant database connections
+ */
+interface TenantDbDebugInfo {
+    tenantId: string;
+    schemaName: string;
+    isProxy: boolean;
+    poolCount: number;
+}
+/**
+ * Factory for creating tenant database connections
+ *
+ * Use this when you need to access tenant databases in singleton services
+ * (cron jobs, event handlers, background workers, etc.)
+ *
+ * @example
+ * ```typescript
+ * // Service stays singleton - no scope change needed
+ * @Injectable()
+ * export class ReportService {
+ *   constructor(private dbFactory: TenantDbFactory) {}
+ *
+ *   async generateReport(tenantId: string) {
+ *     const db = this.dbFactory.getDb(tenantId);
+ *     return db.select().from(reports);
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Cron job usage
+ * @Injectable()
+ * export class DailyReportCron {
+ *   constructor(private dbFactory: TenantDbFactory) {}
+ *
+ *   @Cron('0 8 * * *')
+ *   async generateDailyReports() {
+ *     const tenants = await this.getTenantIds();
+ *     for (const tenantId of tenants) {
+ *       const db = this.dbFactory.getDb(tenantId);
+ *       await this.processReports(db);
+ *     }
+ *   }
+ * }
+ * ```
+ */
+declare class TenantDbFactory<TTenantSchema extends Record<string, unknown> = Record<string, unknown>, TSharedSchema extends Record<string, unknown> = Record<string, unknown>> {
+    private readonly manager;
+    constructor(manager: TenantManager<TTenantSchema, TSharedSchema>);
+    /**
+     * Get a tenant database connection by tenant ID
+     *
+     * @param tenantId - The tenant identifier
+     * @returns The tenant-scoped Drizzle database instance
+     *
+     * @throws Error if tenantId is empty or invalid
+     */
+    getDb(tenantId: string): TenantDb<TTenantSchema>;
+    /**
+     * Get the shared database connection
+     *
+     * @returns The shared Drizzle database instance
+     */
+    getSharedDb(): SharedDb<TSharedSchema>;
+    /**
+     * Get the schema name for a tenant
+     *
+     * @param tenantId - The tenant identifier
+     * @returns The schema name for the tenant
+     */
+    getSchemaName(tenantId: string): string;
+    /**
+     * Get debug information for a tenant database
+     *
+     * @param tenantId - The tenant identifier
+     * @returns Debug information including schema name and pool stats
+     */
+    getDebugInfo(tenantId: string): TenantDbDebugInfo;
+    /**
+     * Get the underlying TenantManager instance
+     *
+     * Use this for advanced operations like pool management
+     *
+     * @returns The TenantManager instance
+     */
+    getManager(): TenantManager<TTenantSchema, TSharedSchema>;
+}
+
 /**
  * Inject the tenant database for the current request
  *
@@ -256,6 +370,46 @@ declare const RequiresTenant: () => ClassDecorator & MethodDecorator;
  * ```
  */
 declare const PublicRoute: () => MethodDecorator;
+/**
+ * Inject the TenantDbFactory for singleton services
+ *
+ * Use this when you need to access tenant databases in singleton services
+ * (cron jobs, event handlers, background workers, etc.) without requiring
+ * request scope.
+ *
+ * @example
+ * ```typescript
+ * // Service stays singleton - no scope change needed
+ * @Injectable()
+ * export class ReportService {
+ *   constructor(@InjectTenantDbFactory() private dbFactory: TenantDbFactory) {}
+ *
+ *   async generateReport(tenantId: string) {
+ *     const db = this.dbFactory.getDb(tenantId);
+ *     return db.select().from(reports);
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Cron job usage
+ * @Injectable()
+ * export class DailyReportCron {
+ *   constructor(@InjectTenantDbFactory() private dbFactory: TenantDbFactory) {}
+ *
+ *   @Cron('0 8 * * *')
+ *   async generateDailyReports() {
+ *     const tenants = await this.getTenantIds();
+ *     for (const tenantId of tenants) {
+ *       const db = this.dbFactory.getDb(tenantId);
+ *       await this.processReports(db);
+ *     }
+ *   }
+ * }
+ * ```
+ */
+declare const InjectTenantDbFactory: () => ParameterDecorator;
 
 /**
  * Guard that extracts and validates tenant ID from requests
@@ -382,5 +536,7 @@ declare const TENANT_ID_EXTRACTOR: unique symbol;
 declare const REQUIRES_TENANT_KEY = "requires_tenant";
 /** Metadata key for public routes (no tenant required) */
 declare const IS_PUBLIC_KEY = "is_public_tenant";
+/** Token for injecting the TenantDbFactory */
+declare const TENANT_DB_FACTORY: unique symbol;
 
-export { Config, DrizzleMultitenantModule, IS_PUBLIC_KEY, InjectSharedDb, InjectTenantContext, InjectTenantDb, InjectTenantManager, type NestTenantContext, PublicRoute, REQUIRES_TENANT_KEY, RequireTenantGuard, RequiresTenant, SHARED_DB, TENANT_CONTEXT, TENANT_DB, TENANT_ID_EXTRACTOR, TENANT_MANAGER, TENANT_MODULE_OPTIONS, TenantContextInterceptor, TenantCtx, TenantGuard, TenantId, type TenantIdExtractor, TenantLoggingInterceptor, TenantManager, TenantModule, type TenantModuleAsyncOptions, type TenantModuleOptions, type TenantModuleOptionsFactory, type TenantRequest, type TenantValidator, createAsyncProviders, createTenantProviders };
+export { Config, DrizzleMultitenantModule, IS_PUBLIC_KEY, InjectSharedDb, InjectTenantContext, InjectTenantDb, InjectTenantDbFactory, InjectTenantManager, type NestTenantContext, PublicRoute, REQUIRES_TENANT_KEY, RequireTenantGuard, RequiresTenant, SHARED_DB, SharedDb, TENANT_CONTEXT, TENANT_DB, TENANT_DB_FACTORY, TENANT_ID_EXTRACTOR, TENANT_MANAGER, TENANT_MODULE_OPTIONS, TenantContextInterceptor, TenantCtx, TenantDb, type TenantDbDebugInfo$1 as TenantDbDebugInfo, TenantDbFactory, type TenantDbWithDebug, TenantGuard, TenantId, type TenantIdExtractor, TenantLoggingInterceptor, TenantManager, TenantModule, type TenantModuleAsyncOptions, type TenantModuleOptions, type TenantModuleOptionsFactory, type TenantRequest, type TenantValidator, createAsyncProviders, createTenantProviders };

package/dist/integrations/nestjs/index.js

@@ -9212,6 +9212,7 @@ var TENANT_MODULE_OPTIONS = /* @__PURE__ */ Symbol("TENANT_MODULE_OPTIONS");
 var TENANT_ID_EXTRACTOR = /* @__PURE__ */ Symbol("TENANT_ID_EXTRACTOR");
 var REQUIRES_TENANT_KEY = "requires_tenant";
 var IS_PUBLIC_KEY = "is_public_tenant";
+var TENANT_DB_FACTORY = /* @__PURE__ */ Symbol("TENANT_DB_FACTORY");
 
 // src/types.ts
 var DEFAULT_CONFIG = {
@@ -9484,24 +9485,54 @@ function createTenantProviders() {
       provide: TENANT_DB,
       scope: Scope.REQUEST,
       useFactory: (request, manager, options) => {
+        const resolveTenantId = () => {
+          let tenantId = request.tenantContext?.tenantId ?? request.tenantId;
+          if (!tenantId && options.extractTenantId) {
+            const extracted = options.extractTenantId(request);
+            if (typeof extracted === "string") {
+              tenantId = extracted;
+            }
+          }
+          return tenantId;
+        };
+        const inspectSymbol = /* @__PURE__ */ Symbol.for("nodejs.util.inspect.custom");
+        const debugProps = ["__debug", "__tenantId", "__isProxy"];
         return new Proxy({}, {
           get(_target, prop) {
-            let tenantId = request.tenantContext?.tenantId ?? request.tenantId;
-            if (!tenantId && options.extractTenantId) {
-              const extracted = options.extractTenantId(request);
-              if (typeof extracted === "string") {
-                tenantId = extracted;
-              }
+            if (prop === Symbol.toStringTag) return "TenantDb";
+            const resolvedTenantId = resolveTenantId();
+            if (prop === inspectSymbol || prop === "toString") {
+              return () => {
+                if (resolvedTenantId) {
+                  return `[TenantDb] tenant=${resolvedTenantId} schema=${manager.getSchemaName(resolvedTenantId)}`;
+                }
+                return "[TenantDb] (no tenant context)";
+              };
             }
-            if (!tenantId) {
+            if (prop === "__debug") {
+              return {
+                tenantId: resolvedTenantId ?? null,
+                schemaName: resolvedTenantId ? manager.getSchemaName(resolvedTenantId) : null,
+                isProxy: true,
+                poolCount: manager.getPoolCount()
+              };
+            }
+            if (prop === "__tenantId") {
+              return resolvedTenantId ?? null;
+            }
+            if (prop === "__isProxy") {
+              return true;
+            }
+            if (!resolvedTenantId) {
               throw new Error(
                 "[drizzle-multitenant] No tenant context found. Ensure the route has a tenant ID or use @PublicRoute() decorator."
               );
             }
-            const db = manager.getDb(tenantId);
+            const db = manager.getDb(resolvedTenantId);
             return db[prop];
           },
           has(_target, prop) {
+            if (debugProps.includes(prop)) return true;
             const tenantId = request.tenantContext?.tenantId ?? request.tenantId;
             if (!tenantId) return false;
             const db = manager.getDb(tenantId);
@@ -9509,11 +9540,16 @@ function createTenantProviders() {
           },
           ownKeys() {
             const tenantId = request.tenantContext?.tenantId ?? request.tenantId;
-            if (!tenantId) return [];
+            if (!tenantId) {
+              return [...debugProps];
+            }
             const db = manager.getDb(tenantId);
-            return Reflect.ownKeys(db);
+            return [.../* @__PURE__ */ new Set([...debugProps, ...Reflect.ownKeys(db)])];
           },
           getOwnPropertyDescriptor(_target, prop) {
+            if (debugProps.includes(prop)) {
+              return { configurable: true, enumerable: true, writable: false };
+            }
             const tenantId = request.tenantContext?.tenantId ?? request.tenantId;
             if (!tenantId) return void 0;
             const db = manager.getDb(tenantId);
@@ -9537,40 +9573,80 @@ function createTenantProviders() {
       provide: TENANT_CONTEXT,
       scope: Scope.REQUEST,
       useFactory: (request, manager, options) => {
+        const inspectSymbol = /* @__PURE__ */ Symbol.for("nodejs.util.inspect.custom");
+        const resolveContext = () => {
+          if (request.tenantContext) {
+            return {
+              tenantId: request.tenantContext.tenantId,
+              schemaName: request.tenantContext.schemaName
+            };
+          }
+          let tenantId = request.tenantId;
+          if (!tenantId && options.extractTenantId) {
+            const extracted = options.extractTenantId(request);
+            if (typeof extracted === "string") {
+              tenantId = extracted;
+            }
+          }
+          if (!tenantId) return null;
+          return {
+            tenantId,
+            schemaName: manager.getSchemaName(tenantId)
+          };
+        };
         return new Proxy({}, {
           get(_target, prop) {
-            if (request.tenantContext) {
-              return request.tenantContext[prop];
+            if (prop === Symbol.toStringTag) return "TenantContext";
+            const ctx = resolveContext();
+            if (prop === inspectSymbol || prop === "toString") {
+              return () => {
+                if (ctx) {
+                  return `[TenantContext] tenant=${ctx.tenantId} schema=${ctx.schemaName}`;
+                }
+                return "[TenantContext] (no tenant context)";
+              };
             }
-            let tenantId = request.tenantId;
-            if (!tenantId && options.extractTenantId) {
-              const extracted = options.extractTenantId(request);
-              if (typeof extracted === "string") {
-                tenantId = extracted;
-              }
+            if (prop === "__debug") {
+              return {
+                tenantId: ctx?.tenantId ?? null,
+                schemaName: ctx?.schemaName ?? null,
+                isProxy: true,
+                hasContext: !!request.tenantContext
+              };
             }
-            if (!tenantId) {
+            if (prop === "__isProxy") {
+              return true;
+            }
+            if (!ctx) {
               throw new Error(
                 "[drizzle-multitenant] No tenant context found. Ensure the route has a tenant ID or use @PublicRoute() decorator."
               );
             }
-            const schemaName = manager.getSchemaName(tenantId);
-            const context = { tenantId, schemaName };
-            return context[prop];
+            if (prop === "tenantId") return ctx.tenantId;
+            if (prop === "schemaName") return ctx.schemaName;
+            if (request.tenantContext) {
+              return request.tenantContext[prop];
+            }
+            return void 0;
           },
           has(_target, prop) {
+            if (prop === "__debug" || prop === "__isProxy") return true;
             if (request.tenantContext) {
               return prop in request.tenantContext;
             }
             return prop === "tenantId" || prop === "schemaName";
           },
           ownKeys() {
+            const baseKeys = ["tenantId", "schemaName", "__debug", "__isProxy"];
             if (request.tenantContext) {
-              return Reflect.ownKeys(request.tenantContext);
+              return [.../* @__PURE__ */ new Set([...baseKeys, ...Reflect.ownKeys(request.tenantContext)])];
             }
-            return ["tenantId", "schemaName"];
+            return baseKeys;
           },
           getOwnPropertyDescriptor(_target, prop) {
+            if (prop === "__debug" || prop === "__isProxy") {
+              return { configurable: true, enumerable: true, writable: false };
+            }
             if (request.tenantContext) {
               return Object.getOwnPropertyDescriptor(request.tenantContext, prop);
             }
@@ -9788,6 +9864,73 @@ var TenantLoggingInterceptor = class {
 TenantLoggingInterceptor = __decorateClass([
   Injectable()
 ], TenantLoggingInterceptor);
+var TenantDbFactory = class {
+  constructor(manager) {
+    this.manager = manager;
+  }
+  /**
+   * Get a tenant database connection by tenant ID
+   *
+   * @param tenantId - The tenant identifier
+   * @returns The tenant-scoped Drizzle database instance
+   *
+   * @throws Error if tenantId is empty or invalid
+   */
+  getDb(tenantId) {
+    if (!tenantId || typeof tenantId !== "string") {
+      throw new Error(
+        "[drizzle-multitenant] TenantDbFactory.getDb() requires a valid tenantId string."
+      );
+    }
+    return this.manager.getDb(tenantId);
+  }
+  /**
+   * Get the shared database connection
+   *
+   * @returns The shared Drizzle database instance
+   */
+  getSharedDb() {
+    return this.manager.getSharedDb();
+  }
+  /**
+   * Get the schema name for a tenant
+   *
+   * @param tenantId - The tenant identifier
+   * @returns The schema name for the tenant
+   */
+  getSchemaName(tenantId) {
+    return this.manager.getSchemaName(tenantId);
+  }
+  /**
+   * Get debug information for a tenant database
+   *
+   * @param tenantId - The tenant identifier
+   * @returns Debug information including schema name and pool stats
+   */
+  getDebugInfo(tenantId) {
+    return {
+      tenantId,
+      schemaName: this.manager.getSchemaName(tenantId),
+      isProxy: false,
+      // Factory returns direct db, not proxy
+      poolCount: this.manager.getPoolCount()
+    };
+  }
+  /**
+   * Get the underlying TenantManager instance
+   *
+   * Use this for advanced operations like pool management
+   *
+   * @returns The TenantManager instance
+   */
+  getManager() {
+    return this.manager;
+  }
+};
+TenantDbFactory = __decorateClass([
+  Injectable(),
+  __decorateParam(0, Inject(TENANT_MANAGER))
+], TenantDbFactory);
 
 // src/integrations/nestjs/tenant.module.ts
 var TenantModule = class {
@@ -9803,7 +9946,8 @@ var TenantModule = class {
       ...createTenantProviders(),
       Reflector,
       TenantGuard,
-      TenantContextInterceptor
+      TenantContextInterceptor,
+      TenantDbFactory
     ];
     if (options.isGlobal) {
       providers.push(
@@ -9824,7 +9968,8 @@ var TenantModule = class {
         TENANT_MODULE_OPTIONS,
         ...createTenantProviders(),
         TenantGuard,
-        TenantContextInterceptor
+        TenantContextInterceptor,
+        TenantDbFactory
       ]
     };
     if (options.isGlobal) {
@@ -9845,7 +9990,8 @@ var TenantModule = class {
       ...createTenantProviders(),
       Reflector,
       TenantGuard,
-      TenantContextInterceptor
+      TenantContextInterceptor,
+      TenantDbFactory
     ];
     const module = {
       module: TenantModule,
@@ -9855,7 +10001,8 @@ var TenantModule = class {
         TENANT_MODULE_OPTIONS,
         ...createTenantProviders(),
         TenantGuard,
-        TenantContextInterceptor
+        TenantContextInterceptor,
+        TenantDbFactory
       ]
     };
     if (options.isGlobal) {
@@ -9897,7 +10044,8 @@ var TenantId = createParamDecorator(
 );
 var RequiresTenant = () => SetMetadata(REQUIRES_TENANT_KEY, true);
 var PublicRoute = () => SetMetadata(IS_PUBLIC_KEY, true);
+var InjectTenantDbFactory = () => Inject(TenantDbFactory);
 
-export { DrizzleMultitenantModule, IS_PUBLIC_KEY, InjectSharedDb, InjectTenantContext, InjectTenantDb, InjectTenantManager, PublicRoute, REQUIRES_TENANT_KEY, RequireTenantGuard, RequiresTenant, SHARED_DB, TENANT_CONTEXT, TENANT_DB, TENANT_ID_EXTRACTOR, TENANT_MANAGER, TENANT_MODULE_OPTIONS, TenantContextInterceptor, TenantCtx, TenantGuard, TenantId, TenantLoggingInterceptor, TenantModule, createAsyncProviders, createTenantProviders };
+export { DrizzleMultitenantModule, IS_PUBLIC_KEY, InjectSharedDb, InjectTenantContext, InjectTenantDb, InjectTenantDbFactory, InjectTenantManager, PublicRoute, REQUIRES_TENANT_KEY, RequireTenantGuard, RequiresTenant, SHARED_DB, TENANT_CONTEXT, TENANT_DB, TENANT_DB_FACTORY, TENANT_ID_EXTRACTOR, TENANT_MANAGER, TENANT_MODULE_OPTIONS, TenantContextInterceptor, TenantCtx, TenantDbFactory, TenantGuard, TenantId, TenantLoggingInterceptor, TenantModule, createAsyncProviders, createTenantProviders };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map