drizzle-multitenant 1.0.7 → 1.0.9

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2024 Mateus Florez
+Copyright (c) 2024 Mateus Flores
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,30 +1,20 @@
 # drizzle-multitenant
 
 [![npm version](https://img.shields.io/npm/v/drizzle-multitenant.svg)](https://www.npmjs.com/package/drizzle-multitenant)
-[![GitHub](https://img.shields.io/github/stars/mateusflorez/drizzle-multitenant?style=social)](https://github.com/mateusflorez/drizzle-multitenant)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Documentation](https://img.shields.io/badge/docs-online-blue.svg)](https://mateusflorez.github.io/drizzle-multitenant/)
 
 Multi-tenancy toolkit for Drizzle ORM with schema isolation, tenant context, and parallel migrations.
 
-```
-┌─────────────────────────────────────────────────────────────────────┐
-│  ╔═══════════════════════════════════════════════════════════════╗  │
-│  ║   drizzle-multitenant                                         ║  │
-│  ║   ━━━━━━━━━━━━━━━━━━━━                                        ║  │
-│  ║                                                               ║  │
-│  ║   Schema isolation  •  Context propagation  •  Migrations     ║  │
-│  ╚═══════════════════════════════════════════════════════════════╝  │
-└─────────────────────────────────────────────────────────────────────┘
-```
-
 ## Features
 
-- **Schema Isolation** - Automatic PostgreSQL schema-per-tenant with LRU pool management
-- **Context Propagation** - AsyncLocalStorage-based tenant context across your entire stack
-- **Parallel Migrations** - Apply migrations to all tenants concurrently with progress tracking
-- **Cross-Schema Queries** - Type-safe queries joining tenant and shared schemas
-- **Framework Integrations** - Express, Fastify, NestJS, and Hono middleware/plugins
-- **CLI Tools** - Generate migrations, manage tenants, check status
+- **Schema Isolation** - PostgreSQL schema-per-tenant with LRU pool management
+- **Context Propagation** - AsyncLocalStorage-based tenant context
+- **Parallel Migrations** - Concurrent migrations with progress tracking
+- **Cross-Schema Queries** - Type-safe joins between tenant and shared tables
+- **Connection Retry** - Automatic retry with exponential backoff
+- **Framework Support** - Express, Fastify, NestJS middleware/plugins
+- **CLI Tools** - Generate, migrate, status, tenant management
 
 ## Installation
 
@@ -34,43 +24,23 @@ npm install drizzle-multitenant drizzle-orm pg
 
 ## Quick Start
 
-### 1. Define your configuration
-
 ```typescript
 // tenant.config.ts
 import { defineConfig } from 'drizzle-multitenant';
 import * as tenantSchema from './schemas/tenant';
-import * as sharedSchema from './schemas/shared';
 
 export default defineConfig({
-  connection: {
-    url: process.env.DATABASE_URL!,
-  },
+  connection: { url: process.env.DATABASE_URL! },
   isolation: {
     strategy: 'schema',
-    schemaNameTemplate: (tenantId) => `tenant_${tenantId}`,
-    maxPools: 50,
-    poolTtlMs: 60 * 60 * 1000,
-  },
-  schemas: {
-    tenant: tenantSchema,
-    shared: sharedSchema,
-  },
-  // Optional: CLI migrations config
-  migrations: {
-    tenantFolder: './drizzle/tenant',
-    migrationsTable: '__drizzle_migrations', // Custom table name
-    tenantDiscovery: async () => {
-      // Return list of tenant IDs for migrations
-      return ['tenant-1', 'tenant-2'];
-    },
+    schemaNameTemplate: (id) => `tenant_${id}`,
   },
+  schemas: { tenant: tenantSchema },
 });
 ```
 
-### 2. Create the tenant manager
-
 ```typescript
+// app.ts
 import { createTenantManager } from 'drizzle-multitenant';
 import config from './tenant.config';
 
@@ -80,329 +50,47 @@ const tenants = createTenantManager(config);
 const db = tenants.getDb('tenant-123');
 const users = await db.select().from(schema.users);
 
-// Get shared DB (public schema)
-const shared = tenants.getSharedDb();
-const plans = await shared.select().from(sharedSchema.plans);
+// With retry and validation
+const db = await tenants.getDbAsync('tenant-123');
 ```
 
-### 3. Use context propagation
+## CLI
 
-```typescript
-import { createTenantContext } from 'drizzle-multitenant';
-
-const ctx = createTenantContext(tenants);
-
-// Run code within tenant context
-await ctx.runWithTenant({ tenantId: 'tenant-123' }, async () => {
-  const db = ctx.getTenantDb();
-  // All queries automatically scoped to tenant
-  const users = await db.select().from(schema.users);
-});
+```bash
+npx drizzle-multitenant init                    # Setup wizard
+npx drizzle-multitenant generate --name=users   # Create migration
+npx drizzle-multitenant migrate --all           # Apply to all tenants
+npx drizzle-multitenant status                  # Check status
 ```
 
 ## Framework Integrations
 
-### Express
-
 ```typescript
+// Express
 import { createExpressMiddleware } from 'drizzle-multitenant/express';
+app.use(createExpressMiddleware({ manager: tenants, extractTenantId: (req) => req.headers['x-tenant-id'] }));
 
-const middleware = createExpressMiddleware({
-  manager: tenants,
-  extractTenantId: (req) => req.headers['x-tenant-id'] as string,
-  validateTenant: async (id) => checkTenantExists(id),
-});
-
-app.use('/api/:tenantId/*', middleware);
-```
-
-### Fastify
-
-```typescript
+// Fastify
 import { fastifyTenantPlugin } from 'drizzle-multitenant/fastify';
+fastify.register(fastifyTenantPlugin, { manager: tenants, extractTenantId: (req) => req.headers['x-tenant-id'] });
 
-await fastify.register(fastifyTenantPlugin, {
-  manager: tenants,
-  extractTenantId: (req) => req.headers['x-tenant-id'] as string,
-});
-```
-
-### NestJS
-
-```typescript
+// NestJS
 import { TenantModule, InjectTenantDb } from 'drizzle-multitenant/nestjs';
-
-@Module({
-  imports: [
-    TenantModule.forRoot({
-      config: tenantConfig,
-      extractTenantId: (req) => req.headers['x-tenant-id'],
-      isGlobal: true,
-    }),
-  ],
-})
-export class AppModule {}
-
-@Injectable({ scope: Scope.REQUEST })
-export class UserService {
-  constructor(@InjectTenantDb() private readonly db: TenantDb) {}
-
-  async findAll() {
-    return this.db.select().from(users);
-  }
-}
-```
-
-#### 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);
-    }
-  }
-}
+@Module({ imports: [TenantModule.forRoot({ config, extractTenantId: (req) => req.headers['x-tenant-id'] })] })
 ```
 
-#### 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');
-```
+## Documentation
 
-## CLI Commands
+**[Read the full documentation →](https://mateusflorez.github.io/drizzle-multitenant/)**
 
-```bash
-# Initialize configuration (interactive wizard)
-npx drizzle-multitenant init
-
-# Generate a new migration
-npx drizzle-multitenant generate --name=add-users-table
-
-# Apply migrations to all tenants (with progress bar)
-npx drizzle-multitenant migrate --all --concurrency=10
-
-# Interactive tenant selection
-npx drizzle-multitenant migrate  # Shows checkbox to select tenants
-
-# Check migration status
-npx drizzle-multitenant status
-
-# Create a new tenant schema
-npx drizzle-multitenant tenant:create --id=new-tenant
-
-# Drop a tenant schema
-npx drizzle-multitenant tenant:drop --id=old-tenant --force
-
-# Convert migration table format
-npx drizzle-multitenant convert-format --to=name --dry-run
-
-# Generate shell completions
-npx drizzle-multitenant completion bash >> ~/.bashrc
-npx drizzle-multitenant completion zsh >> ~/.zshrc
-```
-
-### Global Options
-
-```bash
---json       # Output as JSON (for scripts/CI)
---verbose    # Show detailed output
---quiet      # Only show errors
---no-color   # Disable colored output
-```
-
-### JSON Output
-
-```bash
-# Get status as JSON for scripting
-npx drizzle-multitenant status --json | jq '.tenants[] | select(.pending > 0)'
-
-# Parse migration results
-npx drizzle-multitenant migrate --all --json | jq '.summary'
-```
-
-### Status Output
-
-```
-┌──────────────────┬──────────────┬────────────┬─────────┬─────────┬──────────┐
-│ Tenant           │ Schema       │ Format     │ Applied │ Pending │ Status   │
-├──────────────────┼──────────────┼────────────┼─────────┼─────────┼──────────┤
-│ abc-123          │ tenant_abc   │ drizzle-kit│ 45      │ 3       │ Behind   │
-│ def-456          │ tenant_def   │ name       │ 48      │ 0       │ OK       │
-│ ghi-789          │ tenant_ghi   │ (new)      │ 0       │ 48      │ Behind   │
-└──────────────────┴──────────────┴────────────┴─────────┴─────────┴──────────┘
-```
-
-## Migration Table Formats
-
-`drizzle-multitenant` supports multiple migration table formats for compatibility with existing databases:
-
-### Supported Formats
-
-| Format | Identifier | Timestamp | Compatible With |
-|--------|------------|-----------|-----------------|
-| `name` | Filename | `applied_at` (timestamp) | drizzle-multitenant native |
-| `hash` | SHA-256 | `created_at` (timestamp) | Custom scripts |
-| `drizzle-kit` | SHA-256 | `created_at` (bigint) | drizzle-kit migrate |
-
-### Configuration
-
-```typescript
-// tenant.config.ts
-export default defineConfig({
-  // ...
-  migrations: {
-    tenantFolder: './drizzle/tenant',
-    tenantDiscovery: async () => getTenantIds(),
-
-    /**
-     * Table format for tracking migrations
-     * - "auto": Auto-detect existing format (default)
-     * - "name": Filename-based (drizzle-multitenant native)
-     * - "hash": SHA-256 hash
-     * - "drizzle-kit": Exact drizzle-kit format
-     */
-    tableFormat: 'auto',
-
-    /**
-     * Format to use when creating new tables (only for "auto" mode)
-     * @default "name"
-     */
-    defaultFormat: 'name',
-  },
-});
-```
-
-### Migrating from drizzle-kit
-
-If you have existing databases with migrations applied via `drizzle-kit migrate`, the CLI will automatically detect the format:
-
-```bash
-# Check current format for all tenants
-npx drizzle-multitenant status
-
-# Apply new migrations (works with any format)
-npx drizzle-multitenant migrate --all
-```
-
-### Converting Between Formats
-
-Use the `convert-format` command to standardize all tenants to a single format:
-
-```bash
-# Preview conversion (dry-run)
-npx drizzle-multitenant convert-format --to=name --dry-run
-
-# Convert all tenants to name format
-npx drizzle-multitenant convert-format --to=name
-
-# Convert specific tenant
-npx drizzle-multitenant convert-format --to=name --tenant=abc-123
-
-# Convert to drizzle-kit format (for compatibility)
-npx drizzle-multitenant convert-format --to=drizzle-kit
-```
-
-## Cross-Schema Queries
-
-```typescript
-import { createCrossSchemaQuery } from 'drizzle-multitenant/cross-schema';
-
-const query = createCrossSchemaQuery({
-  tenantDb: tenants.getDb('tenant-123'),
-  sharedDb: tenants.getSharedDb(),
-  tenantSchema: 'tenant_123',
-  sharedSchema: 'public',
-});
-
-// Type-safe join between tenant and shared tables
-const result = await query
-  .select({
-    orderId: orders.id,
-    planName: subscriptionPlans.name,
-  })
-  .from(orders)
-  .leftJoin(subscriptionPlans, eq(orders.planId, subscriptionPlans.id));
-```
-
-## API Reference
-
-### Core
-
-| Export | Description |
-|--------|-------------|
-| `defineConfig()` | Create typed configuration |
-| `createTenantManager()` | Create pool manager instance |
-| `createTenantContext()` | Create AsyncLocalStorage context |
-
-### Manager Methods
-
-| Method | Description |
-|--------|-------------|
-| `getDb(tenantId)` | Get Drizzle instance for tenant |
-| `getSharedDb()` | Get Drizzle instance for shared schema |
-| `getSchemaName(tenantId)` | Get schema name for tenant |
-| `hasPool(tenantId)` | Check if pool exists |
-| `evictPool(tenantId)` | Force evict a pool |
-| `dispose()` | Cleanup all pools |
-
-### NestJS Decorators
-
-| Decorator | Description |
-|-----------|-------------|
-| `@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 |
+- [Getting Started](https://mateusflorez.github.io/drizzle-multitenant/guide/getting-started)
+- [Configuration](https://mateusflorez.github.io/drizzle-multitenant/guide/configuration)
+- [Framework Integrations](https://mateusflorez.github.io/drizzle-multitenant/guide/frameworks/express)
+- [CLI Commands](https://mateusflorez.github.io/drizzle-multitenant/guide/cli)
+- [Cross-Schema Queries](https://mateusflorez.github.io/drizzle-multitenant/guide/cross-schema)
+- [Advanced Features](https://mateusflorez.github.io/drizzle-multitenant/guide/advanced)
+- [API Reference](https://mateusflorez.github.io/drizzle-multitenant/api/reference)
+- [Examples](https://mateusflorez.github.io/drizzle-multitenant/examples/)
 
 ## Requirements
 
@@ -410,30 +98,6 @@ const result = await query
 - PostgreSQL 12+
 - Drizzle ORM 0.29+
 
-## Tech Stack
-
-| Package | Purpose |
-|---------|---------|
-| `drizzle-orm` | Type-safe ORM |
-| `pg` | PostgreSQL driver |
-| `lru-cache` | Pool management |
-| `commander` | CLI framework |
-| `chalk` | Terminal styling |
-| `ora` | Loading spinners |
-| `cli-table3` | Table formatting |
-| `cli-progress` | Progress bars |
-| `@inquirer/prompts` | Interactive prompts |
-
-## Comparison
-
-| Feature | drizzle-multitenant | Manual Implementation |
-|---------|---------------------|----------------------|
-| Pool management | Automatic LRU | Manual |
-| Context propagation | AsyncLocalStorage | Pass through params |
-| Parallel migrations | Built-in CLI | Custom scripts |
-| Cross-schema queries | Type-safe builder | Raw SQL |
-| Framework support | Express/Fastify/NestJS/Hono | DIY |
-
 ## License
 
 MIT