drizzle-multitenant 1.0.8 → 1.0.10

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,36 @@
-# drizzle-multitenant
+<p align="center">
+  <img src="./assets/banner.svg" alt="drizzle-multitenant" width="500" />
+</p>
 
-[![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)
+<p align="center">
+  <strong>Multi-tenancy toolkit for Drizzle ORM</strong>
+</p>
 
-Multi-tenancy toolkit for Drizzle ORM with schema isolation, tenant context, and parallel migrations.
+<p align="center">
+  Schema isolation, tenant context propagation, and parallel migrations for PostgreSQL
+</p>
 
-```
-┌─────────────────────────────────────────────────────────────────────┐
-│  ╔═══════════════════════════════════════════════════════════════╗  │
-│  ║   drizzle-multitenant                                         ║  │
-│  ║   ━━━━━━━━━━━━━━━━━━━━                                        ║  │
-│  ║                                                               ║  │
-│  ║   Schema isolation  •  Context propagation  •  Migrations     ║  │
-│  ╚═══════════════════════════════════════════════════════════════╝  │
-└─────────────────────────────────────────────────────────────────────┘
-```
+<p align="center">
+  <a href="https://www.npmjs.com/package/drizzle-multitenant"><img src="https://img.shields.io/npm/v/drizzle-multitenant.svg?style=flat-square&color=4A9A98" alt="npm version"></a>
+  <a href="https://www.npmjs.com/package/drizzle-multitenant"><img src="https://img.shields.io/npm/dm/drizzle-multitenant.svg?style=flat-square&color=3D5A80" alt="npm downloads"></a>
+  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-6AADAB.svg?style=flat-square" alt="License"></a>
+  <a href="https://mateusflorez.github.io/drizzle-multitenant/"><img src="https://img.shields.io/badge/docs-online-2B3E5C.svg?style=flat-square" alt="Documentation"></a>
+</p>
+
+<br />
 
 ## 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
+| Feature | Description |
+|---------|-------------|
+| **Schema Isolation** | PostgreSQL schema-per-tenant with automatic 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 joins between tenant and shared tables |
+| **Connection Retry** | Automatic retry with exponential backoff for transient failures |
+| **Framework Support** | First-class Express, Fastify, and NestJS integrations |
+
+<br />
 
 ## Installation
 
@@ -32,6 +38,8 @@ Multi-tenancy toolkit for Drizzle ORM with schema isolation, tenant context, and
 npm install drizzle-multitenant drizzle-orm pg
 ```
 
+<br />
+
 ## Quick Start
 
 ### 1. Define your configuration
@@ -40,94 +48,89 @@ npm install drizzle-multitenant drizzle-orm pg
 // 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';
 
 const tenants = createTenantManager(config);
 
-// Get typed DB for a tenant
-const db = tenants.getDb('tenant-123');
+// Type-safe database for each tenant
+const db = tenants.getDb('acme');
 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);
 ```
 
-### 3. Use context propagation
-
-```typescript
-import { createTenantContext } from 'drizzle-multitenant';
+<br />
 
-const ctx = createTenantContext(tenants);
+## CLI Commands
 
-// 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                     # Interactive setup wizard
+npx drizzle-multitenant generate --name=users    # Generate migration
+npx drizzle-multitenant migrate --all            # Apply to all tenants
+npx drizzle-multitenant status                   # Check migration status
+npx drizzle-multitenant tenant:create --id=acme  # Create new tenant
 ```
 
+<br />
+
 ## Framework Integrations
 
-### Express
+<details>
+<summary><strong>Express</strong></summary>
 
 ```typescript
 import { createExpressMiddleware } from 'drizzle-multitenant/express';
 
-const middleware = createExpressMiddleware({
+app.use(createExpressMiddleware({
   manager: tenants,
   extractTenantId: (req) => req.headers['x-tenant-id'] as string,
-  validateTenant: async (id) => checkTenantExists(id),
-});
+}));
 
-app.use('/api/:tenantId/*', middleware);
+app.get('/users', async (req, res) => {
+  const db = req.tenantContext.db;
+  const users = await db.select().from(schema.users);
+  res.json(users);
+});
 ```
 
-### Fastify
+</details>
+
+<details>
+<summary><strong>Fastify</strong></summary>
 
 ```typescript
 import { fastifyTenantPlugin } from 'drizzle-multitenant/fastify';
 
-await fastify.register(fastifyTenantPlugin, {
+fastify.register(fastifyTenantPlugin, {
   manager: tenants,
   extractTenantId: (req) => req.headers['x-tenant-id'] as string,
 });
+
+fastify.get('/users', async (req, reply) => {
+  const db = req.tenantContext.db;
+  const users = await db.select().from(schema.users);
+  return users;
+});
 ```
 
-### NestJS
+</details>
+
+<details>
+<summary><strong>NestJS</strong></summary>
 
 ```typescript
 import { TenantModule, InjectTenantDb } from 'drizzle-multitenant/nestjs';
@@ -135,9 +138,8 @@ import { TenantModule, InjectTenantDb } from 'drizzle-multitenant/nestjs';
 @Module({
   imports: [
     TenantModule.forRoot({
-      config: tenantConfig,
+      config,
       extractTenantId: (req) => req.headers['x-tenant-id'],
-      isGlobal: true,
     }),
   ],
 })
@@ -145,264 +147,39 @@ export class AppModule {}
 
 @Injectable({ scope: Scope.REQUEST })
 export class UserService {
-  constructor(@InjectTenantDb() private readonly db: TenantDb) {}
+  constructor(@InjectTenantDb() private db: TenantDb) {}
 
-  async findAll() {
+  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);
-    }
-  }
-}
-```
-
-#### 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
-# 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
+</details>
 
-# Check migration status
-npx drizzle-multitenant status
+<br />
 
-# Create a new tenant schema
-npx drizzle-multitenant tenant:create --id=new-tenant
+## Documentation
 
-# 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));
-```
+<table>
+  <tr>
+    <td><a href="https://mateusflorez.github.io/drizzle-multitenant/guide/getting-started">Getting Started</a></td>
+    <td><a href="https://mateusflorez.github.io/drizzle-multitenant/guide/configuration">Configuration</a></td>
+    <td><a href="https://mateusflorez.github.io/drizzle-multitenant/guide/cli">CLI Commands</a></td>
+  </tr>
+  <tr>
+    <td><a href="https://mateusflorez.github.io/drizzle-multitenant/guide/frameworks/express">Express</a></td>
+    <td><a href="https://mateusflorez.github.io/drizzle-multitenant/guide/frameworks/fastify">Fastify</a></td>
+    <td><a href="https://mateusflorez.github.io/drizzle-multitenant/guide/frameworks/nestjs">NestJS</a></td>
+  </tr>
+  <tr>
+    <td><a href="https://mateusflorez.github.io/drizzle-multitenant/guide/cross-schema">Cross-Schema Queries</a></td>
+    <td><a href="https://mateusflorez.github.io/drizzle-multitenant/guide/advanced">Advanced Features</a></td>
+    <td><a href="https://mateusflorez.github.io/drizzle-multitenant/api/reference">API Reference</a></td>
+  </tr>
+</table>
 
-## 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 |
+<br />
 
 ## Requirements
 
@@ -410,29 +187,7 @@ 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 |
+<br />
 
 ## License