@veloxts/orm 0.6.27 → 0.6.31

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # @veloxts/orm
 
+## 0.6.31
+
+### Patch Changes
+
+- npm must use concurrently for run dev script
+- Updated dependencies
+  - @veloxts/core@0.6.31
+
+## 0.6.30
+
+### Patch Changes
+
+- disable source maps for published packages
+- Updated dependencies
+  - @veloxts/core@0.6.30
+
+## 0.6.29
+
+### Patch Changes
+
+- add multi-tenancy and PostgreSQL support - test and lint fix
+- Updated dependencies
+  - @veloxts/core@0.6.29
+
+## 0.6.28
+
+### Patch Changes
+
+- add multi-tenancy support and postgresql database
+- Updated dependencies
+  - @veloxts/core@0.6.28
+
 ## 0.6.27
 
 ### Patch Changes

package/GUIDE.md

@@ -43,7 +43,7 @@ const db = new PrismaClient({ adapter });
 ## Using in Procedures
 
 ```typescript
-export const userProcedures = defineProcedures('users', {
+export const userProcedures = procedures('users', {
   getUser: procedure()
     .input(z.object({ id: z.string().uuid() }))
     .query(async ({ input, ctx }) => {
@@ -68,6 +68,107 @@ npx prisma migrate deploy                # Apply migrations
 velox migrate                            # VeloxTS CLI shortcut
 ```
 
+## Multi-Tenancy (Schema-per-Tenant)
+
+For SaaS applications requiring tenant isolation, import from `@veloxts/orm/tenant`:
+
+```typescript
+import {
+  createTenantClientPool,
+  createTenantSchemaManager,
+  createTenantProvisioner,
+  createTenant,
+} from '@veloxts/orm/tenant';
+```
+
+### Setup
+
+```typescript
+// 1. Schema manager (DDL operations)
+const schemaManager = createTenantSchemaManager({
+  databaseUrl: process.env.DATABASE_URL!,
+  schemaPrefix: 'tenant_', // PostgreSQL schema prefix
+});
+
+// 2. Client pool (manages PrismaClient per tenant)
+const clientPool = createTenantClientPool({
+  baseDatabaseUrl: process.env.DATABASE_URL!,
+  createClient: (schemaName) => {
+    const url = `${process.env.DATABASE_URL}?schema=${schemaName}`;
+    const adapter = new PrismaPg({ connectionString: url });
+    return new PrismaClient({ adapter });
+  },
+  maxClients: 50, // LRU eviction when exceeded
+});
+
+// 3. Tenant middleware namespace
+const tenant = createTenant({
+  loadTenant: (id) => publicDb.tenant.findUnique({ where: { id } }),
+  clientPool,
+  publicClient: publicDb, // For shared data in 'public' schema
+});
+```
+
+### Using in Procedures
+
+```typescript
+const getUsers = procedure()
+  .use(auth.requireAuth())
+  .use(tenant.middleware()) // Adds ctx.tenant, ctx.db (scoped)
+  .query(({ ctx }) => ctx.db.user.findMany());
+```
+
+The middleware:
+1. Extracts `tenantId` from JWT claims (`ctx.auth.token.tenantId`)
+2. Loads tenant from public schema
+3. Validates tenant status (must be `active`)
+4. Gets tenant-scoped database client from pool
+5. Adds `ctx.tenant`, `ctx.db`, and optionally `ctx.publicDb`
+
+### Provisioning Tenants
+
+```typescript
+const provisioner = createTenantProvisioner({
+  schemaManager,
+  publicClient: publicDb,
+  clientPool,
+});
+
+// Create new tenant (creates schema + runs migrations)
+const result = await provisioner.provision({
+  slug: 'acme-corp',
+  name: 'Acme Corporation',
+});
+// result.tenant.schemaName === 'tenant_acme_corp'
+
+// Migrate all tenant schemas
+await provisioner.migrateAll();
+```
+
+### Architecture
+
+```
+PostgreSQL Database
+├── public schema (shared)
+│   └── tenants table
+└── tenant_acme_corp schema (isolated)
+    ├── users
+    ├── posts
+    └── ...
+```
+
+### JWT Integration
+
+Add `tenantId` to your JWT payload when generating tokens:
+
+```typescript
+const tokens = await jwt.generateTokens({
+  sub: user.id,
+  email: user.email,
+  tenantId: user.tenantId, // Include tenant ID
+});
+```
+
 ## Learn More
 
 See [@veloxts/velox](https://www.npmjs.com/package/@veloxts/velox) for complete documentation.

package/dist/client.d.ts

@@ -111,4 +111,3 @@ export interface Database<TClient extends DatabaseClient> {
  * ```
  */
 export declare function createDatabase<TClient extends DatabaseClient>(config: DatabaseWrapperConfig<TClient>): Database<TClient>;
-//# sourceMappingURL=client.d.ts.map

package/dist/client.js

@@ -153,4 +153,3 @@ export function createDatabase(config) {
     };
     return database;
 }
-//# sourceMappingURL=client.js.map

package/dist/index.d.ts

@@ -111,4 +111,3 @@ export {
  * ```
  */
 databasePlugin, } from './plugin.js';
-//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -87,4 +87,3 @@ export {
  * ```
  */
 databasePlugin, } from './plugin.js';
-//# sourceMappingURL=index.js.map

package/dist/plugin.d.ts

@@ -114,4 +114,3 @@ declare module '@veloxts/core' {
  * ```
  */
 export declare function databasePlugin<TClient extends DatabaseClient>(config: OrmPluginConfig<TClient>): import("@veloxts/core").VeloxPlugin<import("fastify").FastifyPluginOptions>;
-//# sourceMappingURL=plugin.d.ts.map

package/dist/plugin.js

@@ -135,4 +135,3 @@ export function databasePlugin(config) {
         },
     });
 }
-//# sourceMappingURL=plugin.js.map

package/dist/tenant/client-pool.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Tenant client pool for managing PrismaClient instances per schema
+ *
+ * Features:
+ * - LRU eviction when pool reaches capacity
+ * - Idle timeout cleanup
+ * - Connection lifecycle management
+ */
+import type { DatabaseClient } from '../types.js';
+import type { TenantClientPool as ITenantClientPool, TenantClientPoolConfig } from './types.js';
+/**
+ * Tenant client pool implementation
+ *
+ * Manages a pool of PrismaClient instances, one per tenant schema.
+ * Uses LRU eviction when the pool reaches maximum capacity.
+ *
+ * @example
+ * ```typescript
+ * const pool = createTenantClientPool({
+ *   baseDatabaseUrl: process.env.DATABASE_URL!,
+ *   createClient: (schemaName) => {
+ *     const url = `${process.env.DATABASE_URL}?schema=${schemaName}`;
+ *     const adapter = new PrismaPg({ connectionString: url });
+ *     return new PrismaClient({ adapter });
+ *   },
+ *   maxClients: 50,
+ * });
+ *
+ * const client = await pool.getClient('tenant_acme');
+ * // Use client...
+ * pool.releaseClient('tenant_acme');
+ * ```
+ */
+export declare function createTenantClientPool<TClient extends DatabaseClient>(config: TenantClientPoolConfig<TClient>): ITenantClientPool<TClient>;
+/**
+ * Type alias for the client pool
+ */
+export type { ITenantClientPool as TenantClientPool };

package/dist/tenant/client-pool.js

@@ -0,0 +1,233 @@
+/**
+ * Tenant client pool for managing PrismaClient instances per schema
+ *
+ * Features:
+ * - LRU eviction when pool reaches capacity
+ * - Idle timeout cleanup
+ * - Connection lifecycle management
+ */
+import { ClientCreateError, ClientDisconnectError, ClientPoolExhaustedError } from './errors.js';
+/**
+ * Default configuration values
+ */
+const DEFAULTS = {
+    maxClients: 50,
+    idleTimeoutMs: 5 * 60 * 1000, // 5 minutes
+    cleanupIntervalMs: 60 * 1000, // 1 minute
+};
+/**
+ * Tenant client pool implementation
+ *
+ * Manages a pool of PrismaClient instances, one per tenant schema.
+ * Uses LRU eviction when the pool reaches maximum capacity.
+ *
+ * @example
+ * ```typescript
+ * const pool = createTenantClientPool({
+ *   baseDatabaseUrl: process.env.DATABASE_URL!,
+ *   createClient: (schemaName) => {
+ *     const url = `${process.env.DATABASE_URL}?schema=${schemaName}`;
+ *     const adapter = new PrismaPg({ connectionString: url });
+ *     return new PrismaClient({ adapter });
+ *   },
+ *   maxClients: 50,
+ * });
+ *
+ * const client = await pool.getClient('tenant_acme');
+ * // Use client...
+ * pool.releaseClient('tenant_acme');
+ * ```
+ */
+export function createTenantClientPool(config) {
+    const maxClients = config.maxClients ?? DEFAULTS.maxClients;
+    const idleTimeoutMs = config.idleTimeoutMs ?? DEFAULTS.idleTimeoutMs;
+    // Pool state
+    const clients = new Map();
+    let totalCreated = 0;
+    let totalEvicted = 0;
+    let cleanupTimer = null;
+    /**
+     * Start the idle cleanup timer
+     */
+    function startCleanupTimer() {
+        if (cleanupTimer)
+            return;
+        cleanupTimer = setInterval(() => {
+            void cleanupIdleClients();
+        }, DEFAULTS.cleanupIntervalMs);
+        // Don't block process exit
+        if (cleanupTimer.unref) {
+            cleanupTimer.unref();
+        }
+    }
+    /**
+     * Stop the cleanup timer
+     */
+    function stopCleanupTimer() {
+        if (cleanupTimer) {
+            clearInterval(cleanupTimer);
+            cleanupTimer = null;
+        }
+    }
+    /**
+     * Cleanup clients that have been idle too long
+     */
+    async function cleanupIdleClients() {
+        const now = Date.now();
+        const toEvict = [];
+        for (const [schemaName, cached] of clients) {
+            if (now - cached.lastAccessedAt > idleTimeoutMs) {
+                toEvict.push(schemaName);
+            }
+        }
+        for (const schemaName of toEvict) {
+            await evictClient(schemaName);
+        }
+    }
+    /**
+     * Evict a client from the pool
+     */
+    async function evictClient(schemaName) {
+        const cached = clients.get(schemaName);
+        if (!cached)
+            return;
+        clients.delete(schemaName);
+        totalEvicted++;
+        try {
+            await cached.client.$disconnect();
+        }
+        catch (error) {
+            // Log but don't throw - eviction should be best-effort
+            console.warn(`[TenantClientPool] Failed to disconnect client for ${schemaName}:`, error);
+        }
+    }
+    /**
+     * Find and evict the least recently used client
+     */
+    async function evictLRU() {
+        let oldest = null;
+        for (const [schemaName, cached] of clients) {
+            if (!oldest || cached.lastAccessedAt < oldest.lastAccessedAt) {
+                oldest = { schemaName, lastAccessedAt: cached.lastAccessedAt };
+            }
+        }
+        if (oldest) {
+            await evictClient(oldest.schemaName);
+        }
+    }
+    /**
+     * Create a new client for a schema
+     */
+    async function createClient(schemaName) {
+        try {
+            const client = config.createClient(schemaName);
+            // Connect the client
+            await client.$connect();
+            return client;
+        }
+        catch (error) {
+            throw new ClientCreateError(schemaName, error instanceof Error ? error : new Error(String(error)));
+        }
+    }
+    // Start cleanup timer
+    startCleanupTimer();
+    return {
+        /**
+         * Get or create a client for a tenant schema
+         */
+        async getClient(schemaName) {
+            // Check if client exists in pool
+            const cached = clients.get(schemaName);
+            if (cached) {
+                // Update last accessed time (LRU tracking)
+                cached.lastAccessedAt = Date.now();
+                return cached.client;
+            }
+            // Check if pool is at capacity
+            if (clients.size >= maxClients) {
+                // Try to evict idle clients first
+                await cleanupIdleClients();
+                // If still at capacity, evict LRU
+                if (clients.size >= maxClients) {
+                    await evictLRU();
+                }
+                // If still at capacity (shouldn't happen), throw
+                if (clients.size >= maxClients) {
+                    throw new ClientPoolExhaustedError(maxClients);
+                }
+            }
+            // Create new client
+            const client = await createClient(schemaName);
+            const now = Date.now();
+            clients.set(schemaName, {
+                client,
+                schemaName,
+                lastAccessedAt: now,
+                createdAt: now,
+            });
+            totalCreated++;
+            return client;
+        },
+        /**
+         * Release a client back to the pool
+         *
+         * Note: This doesn't actually remove the client, it just marks
+         * it as available for LRU eviction if needed.
+         */
+        releaseClient(schemaName) {
+            const cached = clients.get(schemaName);
+            if (cached) {
+                cached.lastAccessedAt = Date.now();
+            }
+        },
+        /**
+         * Check if a client exists in the pool without creating it
+         * Useful for health checks
+         */
+        hasClient(schemaName) {
+            return clients.has(schemaName);
+        },
+        /**
+         * Stop the cleanup timer without disconnecting clients
+         *
+         * Use this when you need to stop the timer but keep clients connected.
+         * For full cleanup, use `disconnectAll()` instead.
+         */
+        close() {
+            stopCleanupTimer();
+        },
+        /**
+         * Disconnect all clients and clear the pool
+         *
+         * IMPORTANT: This also stops the cleanup timer.
+         * Always call this method during application shutdown.
+         */
+        async disconnectAll() {
+            stopCleanupTimer();
+            const errors = [];
+            for (const [schemaName, cached] of clients) {
+                try {
+                    await cached.client.$disconnect();
+                }
+                catch (error) {
+                    errors.push(new ClientDisconnectError(schemaName, error instanceof Error ? error : new Error(String(error))));
+                }
+            }
+            clients.clear();
+            if (errors.length > 0) {
+                throw new AggregateError(errors, 'Failed to disconnect some clients');
+            }
+        },
+        /**
+         * Get current pool statistics
+         */
+        getStats() {
+            return {
+                activeClients: clients.size,
+                maxClients,
+                totalCreated,
+                totalEvicted,
+            };
+        },
+    };
+}

package/dist/tenant/errors.d.ts

@@ -0,0 +1,141 @@
+/**
+ * Tenant-specific error classes for @veloxts/orm/tenant
+ */
+/**
+ * Base error class for tenant-related errors
+ */
+export declare class TenantError extends Error {
+    readonly code: TenantErrorCode;
+    readonly tenantId?: string;
+    readonly schemaName?: string;
+    constructor(message: string, code: TenantErrorCode, options?: {
+        tenantId?: string;
+        schemaName?: string;
+        cause?: Error;
+    });
+}
+/**
+ * Error codes for tenant operations
+ */
+export type TenantErrorCode = 'TENANT_NOT_FOUND' | 'TENANT_SUSPENDED' | 'TENANT_PENDING' | 'TENANT_MIGRATING' | 'TENANT_ID_MISSING' | 'TENANT_ACCESS_DENIED' | 'SCHEMA_CREATE_FAILED' | 'SCHEMA_DELETE_FAILED' | 'SCHEMA_MIGRATE_FAILED' | 'SCHEMA_NOT_FOUND' | 'SCHEMA_LIST_FAILED' | 'SCHEMA_ALREADY_EXISTS' | 'CLIENT_POOL_EXHAUSTED' | 'CLIENT_CREATE_FAILED' | 'CLIENT_DISCONNECT_FAILED' | 'INVALID_SLUG' | 'PROVISION_FAILED' | 'DEPROVISION_FAILED';
+/**
+ * Tenant not found in database
+ */
+export declare class TenantNotFoundError extends TenantError {
+    constructor(tenantId: string);
+}
+/**
+ * Tenant is suspended and cannot be accessed
+ */
+export declare class TenantSuspendedError extends TenantError {
+    constructor(tenantId: string);
+}
+/**
+ * Tenant is pending activation
+ */
+export declare class TenantPendingError extends TenantError {
+    constructor(tenantId: string);
+}
+/**
+ * Tenant is currently being migrated
+ */
+export declare class TenantMigratingError extends TenantError {
+    constructor(tenantId: string);
+}
+/**
+ * Tenant ID missing from request context
+ */
+export declare class TenantIdMissingError extends TenantError {
+    constructor();
+}
+/**
+ * User does not have access to the requested tenant
+ *
+ * SECURITY: This error is thrown when tenant access verification fails.
+ * It prevents tenant isolation bypass attacks where a user might try
+ * to access a tenant they don't belong to by manipulating JWT claims.
+ */
+export declare class TenantAccessDeniedError extends TenantError {
+    readonly userId?: string;
+    constructor(tenantId: string, userId?: string);
+}
+/**
+ * Schema creation failed
+ */
+export declare class SchemaCreateError extends TenantError {
+    constructor(schemaName: string, cause?: Error);
+}
+/**
+ * Schema deletion failed
+ */
+export declare class SchemaDeleteError extends TenantError {
+    constructor(schemaName: string, cause?: Error);
+}
+/**
+ * Schema migration failed
+ */
+export declare class SchemaMigrateError extends TenantError {
+    constructor(schemaName: string, cause?: Error);
+}
+/**
+ * Schema not found
+ */
+export declare class SchemaNotFoundError extends TenantError {
+    constructor(schemaName: string);
+}
+/**
+ * Schema list operation failed
+ */
+export declare class SchemaListError extends TenantError {
+    constructor(cause?: Error);
+}
+/**
+ * Schema already exists
+ */
+export declare class SchemaAlreadyExistsError extends TenantError {
+    constructor(schemaName: string);
+}
+/**
+ * Client pool has reached maximum capacity
+ */
+export declare class ClientPoolExhaustedError extends TenantError {
+    constructor(maxClients: number);
+}
+/**
+ * Failed to create database client
+ */
+export declare class ClientCreateError extends TenantError {
+    constructor(schemaName: string, cause?: Error);
+}
+/**
+ * Failed to disconnect database client
+ */
+export declare class ClientDisconnectError extends TenantError {
+    constructor(schemaName: string, cause?: Error);
+}
+/**
+ * Invalid tenant slug format
+ */
+export declare class InvalidSlugError extends TenantError {
+    constructor(slug: string, reason: string);
+}
+/**
+ * Tenant provisioning failed
+ */
+export declare class ProvisionError extends TenantError {
+    constructor(slug: string, cause?: Error);
+}
+/**
+ * Tenant deprovisioning failed
+ */
+export declare class DeprovisionError extends TenantError {
+    constructor(tenantId: string, cause?: Error);
+}
+/**
+ * Type guard to check if an error is a TenantError
+ */
+export declare function isTenantError(error: unknown): error is TenantError;
+/**
+ * Get error based on tenant status
+ */
+export declare function getTenantStatusError(tenantId: string, status: string): TenantError | null;