bunsane 0.1.4 → 0.2.0

package/tests/setup.ts

@@ -0,0 +1,164 @@
+/**
+ * Global test setup file for BunSane
+ *
+ * This file is preloaded before all tests run (configured in bunfig.toml).
+ * It ensures:
+ * 1. Environment variables are loaded from .env.test
+ * 2. Database connection is established and ready
+ * 3. Base tables exist
+ * 4. ApplicationLifecycle is set to DATABASE_READY
+ * 5. EntityManager is ready for operations
+ * 6. Proper cleanup on exit
+ */
+
+import { beforeAll, afterAll } from 'bun:test';
+import { file } from 'bun';
+
+// Load .env.test before anything else (skip when PGlite provides env vars)
+if (process.env.USE_PGLITE !== 'true') {
+    const envTestPath = new URL('../.env.test', import.meta.url).pathname.replace(/^\/([A-Z]:)/, '$1');
+    const envFile = file(envTestPath);
+    if (await envFile.exists()) {
+        const envContent = await envFile.text();
+        for (const line of envContent.split('\n')) {
+            const trimmed = line.trim();
+            if (trimmed && !trimmed.startsWith('#')) {
+                const [key, ...valueParts] = trimmed.split('=');
+                if (key) {
+                    const value = valueParts.join('=');
+                    process.env[key.trim()] = value.trim();
+                }
+            }
+        }
+    }
+}
+
+// Suppress verbose logging during tests unless LOG_LEVEL is explicitly set
+if (!process.env.LOG_LEVEL) {
+    process.env.LOG_LEVEL = 'warn';
+}
+
+// Now import the rest after env is loaded
+import db from '../database';
+import { PrepareDatabase, HasValidBaseTable } from '../database/DatabaseHelper';
+import ApplicationLifecycle, { ApplicationPhase } from '../core/ApplicationLifecycle';
+import EntityManager from '../core/EntityManager';
+import { ComponentRegistry } from '../core/components';
+import { CacheManager } from '../core/cache';
+import { logger } from '../core/Logger';
+import { preparedStatementCache } from '../database/PreparedStatementCache';
+
+let isSetupComplete = false;
+let setupError: Error | null = null;
+
+/**
+ * Initialize the test environment
+ */
+async function initializeTestEnvironment(): Promise<void> {
+    if (isSetupComplete) return;
+    if (setupError) throw setupError;
+
+    try {
+        logger.info({ scope: 'test-setup' }, 'Initializing test environment...');
+
+        // 1. Verify database connection by running a simple query
+        const connectionTest = await db`SELECT 1 as connected`;
+        if (!connectionTest || connectionTest.length === 0) {
+            throw new Error('Database connection failed');
+        }
+        logger.info({ scope: 'test-setup' }, 'Database connection verified');
+
+        // 2. Ensure base tables exist
+        const hasValidTables = await HasValidBaseTable();
+        if (!hasValidTables) {
+            logger.info({ scope: 'test-setup' }, 'Creating base database tables...');
+            await PrepareDatabase();
+            logger.info({ scope: 'test-setup' }, 'Base database tables created');
+        } else {
+            logger.info({ scope: 'test-setup' }, 'Base database tables already exist');
+        }
+
+        // 3. Set ApplicationLifecycle to DATABASE_READY
+        ApplicationLifecycle.setPhase(ApplicationPhase.DATABASE_READY);
+        logger.info({ scope: 'test-setup' }, 'ApplicationLifecycle set to DATABASE_READY');
+
+        // 4. Set EntityManager as ready
+        (EntityManager as any).dbReady = true;
+        logger.info({ scope: 'test-setup' }, 'EntityManager marked as ready');
+
+        // 5. Initialize CacheManager with memory provider for tests
+        const cacheManager = CacheManager.getInstance();
+        await cacheManager.initialize({
+            enabled: true,
+            provider: 'memory',
+            strategy: 'write-through',
+            defaultTTL: 3600000,
+            entity: { enabled: true, ttl: 3600000 },
+            component: { enabled: true, ttl: 1800000 },
+            query: { enabled: false, ttl: 300000, maxSize: 10000 }
+        });
+        logger.info({ scope: 'test-setup' }, 'CacheManager initialized with memory provider');
+
+        // 6. Clear prepared statement cache to ensure clean slate
+        preparedStatementCache.clear();
+
+        isSetupComplete = true;
+        logger.info({ scope: 'test-setup' }, 'Test environment initialization complete');
+
+    } catch (error) {
+        setupError = error instanceof Error ? error : new Error(String(error));
+        logger.error({ scope: 'test-setup', error: setupError }, 'Failed to initialize test environment');
+        throw setupError;
+    }
+}
+
+/**
+ * Clean up the test environment
+ */
+async function cleanupTestEnvironment(): Promise<void> {
+    try {
+        logger.info({ scope: 'test-setup' }, 'Cleaning up test environment...');
+
+        // Clear caches
+        try {
+            const cacheManager = CacheManager.getInstance();
+            await cacheManager.clear();
+        } catch {
+            // Ignore cache cleanup errors
+        }
+
+        // Clear prepared statement cache
+        try {
+            preparedStatementCache.clear();
+        } catch {
+            // Ignore errors
+        }
+
+        // Note: We don't close the database connection pool here because
+        // Bun's test runner may still need it for parallel test files.
+        // The connection pool will be cleaned up when the process exits.
+
+        logger.info({ scope: 'test-setup' }, 'Test environment cleanup complete');
+    } catch (error) {
+        logger.warn({ scope: 'test-setup', error }, 'Error during test environment cleanup');
+    }
+}
+
+// Register global hooks (skip for E2E tests that don't need DB)
+if (process.env.SKIP_TEST_DB_SETUP !== 'true') {
+    beforeAll(async () => {
+        await initializeTestEnvironment();
+    });
+
+    afterAll(async () => {
+        await cleanupTestEnvironment();
+    });
+}
+
+// Export utilities for tests that need them
+export { initializeTestEnvironment, cleanupTestEnvironment };
+
+// Export a helper to ensure setup is complete (for tests that run before beforeAll)
+export async function ensureTestSetup(): Promise<void> {
+    await initializeTestEnvironment();
+}

package/tests/stress/BenchmarkRunner.ts

@@ -0,0 +1,203 @@
+/**
+ * Benchmark execution engine for stress testing
+ * Runs queries with statistical analysis
+ */
+import db from '../../database';
+
+export interface BenchmarkResult {
+    name: string;
+    iterations: number;
+    totalRecords: number;
+    timings: {
+        min: number;
+        max: number;
+        mean: number;
+        median: number;
+        p95: number;
+        p99: number;
+        stdDev: number;
+    };
+    rowsReturned: number;
+    queriesPerSecond: number;
+    memoryUsedMB: number;
+    passed: boolean;
+    target?: number;
+}
+
+export interface BenchmarkOptions {
+    iterations?: number;
+    warmupIterations?: number;
+    targetP95?: number;
+    collectMemory?: boolean;
+}
+
+export interface ConcurrentResult {
+    name: string;
+    concurrency: number;
+    totalQueries: number;
+    queriesPerSecond: number;
+    avgLatency: number;
+    errorRate: number;
+}
+
+export class BenchmarkRunner {
+    private results: BenchmarkResult[] = [];
+
+    async run(
+        name: string,
+        queryFn: () => Promise<any[]>,
+        options: BenchmarkOptions = {}
+    ): Promise<BenchmarkResult> {
+        const {
+            iterations = 20,
+            warmupIterations = 3,
+            targetP95,
+            collectMemory = true
+        } = options;
+
+        // Warmup phase
+        for (let i = 0; i < warmupIterations; i++) {
+            await queryFn();
+        }
+
+        // Force GC if available
+        if (typeof global.gc === 'function') {
+            global.gc();
+        }
+
+        const times: number[] = [];
+        let rowCount = 0;
+        const memBefore = process.memoryUsage().heapUsed;
+
+        // Benchmark phase
+        for (let i = 0; i < iterations; i++) {
+            const start = performance.now();
+            const results = await queryFn();
+            times.push(performance.now() - start);
+            rowCount = Array.isArray(results) ? results.length : 0;
+        }
+
+        const memAfter = process.memoryUsage().heapUsed;
+        const sortedTimes = [...times].sort((a, b) => a - b);
+
+        const timings = {
+            min: sortedTimes[0] ?? 0,
+            max: sortedTimes[sortedTimes.length - 1] ?? 0,
+            mean: times.reduce((a, b) => a + b, 0) / (times.length || 1),
+            median: sortedTimes[Math.floor(sortedTimes.length / 2)] ?? 0,
+            p95: sortedTimes[Math.floor(sortedTimes.length * 0.95)] ?? sortedTimes[sortedTimes.length - 1] ?? 0,
+            p99: sortedTimes[Math.floor(sortedTimes.length * 0.99)] ?? sortedTimes[sortedTimes.length - 1] ?? 0,
+            stdDev: this.calculateStdDev(times)
+        };
+
+        const result: BenchmarkResult = {
+            name,
+            iterations,
+            totalRecords: await this.getRecordCount(),
+            timings,
+            rowsReturned: rowCount,
+            queriesPerSecond: 1000 / (timings.mean || 1),
+            memoryUsedMB: collectMemory ? (memAfter - memBefore) / 1024 / 1024 : 0,
+            passed: targetP95 ? (timings.p95 ?? 0) <= targetP95 : true,
+            target: targetP95
+        };
+
+        this.results.push(result);
+        return result;
+    }
+
+    async runConcurrent(
+        name: string,
+        queryFn: () => Promise<any[]>,
+        concurrency: number,
+        duration: number = 10000
+    ): Promise<ConcurrentResult> {
+        const times: number[] = [];
+        let errors = 0;
+        const startTime = performance.now();
+
+        const worker = async () => {
+            while (performance.now() - startTime < duration) {
+                const queryStart = performance.now();
+                try {
+                    await queryFn();
+                    times.push(performance.now() - queryStart);
+                } catch {
+                    errors++;
+                }
+            }
+        };
+
+        await Promise.all(Array(concurrency).fill(null).map(() => worker()));
+
+        const totalTime = performance.now() - startTime;
+
+        return {
+            name,
+            concurrency,
+            totalQueries: times.length + errors,
+            queriesPerSecond: (times.length / totalTime) * 1000,
+            avgLatency: times.length > 0 ? times.reduce((a, b) => a + b, 0) / times.length : 0,
+            errorRate: (times.length + errors) > 0 ? errors / (times.length + errors) : 0
+        };
+    }
+
+    /**
+     * Run a benchmark and print detailed results
+     */
+    async runWithOutput(
+        name: string,
+        queryFn: () => Promise<any[]>,
+        options: BenchmarkOptions = {}
+    ): Promise<BenchmarkResult> {
+        console.log(`  Running: ${name}...`);
+        const result = await this.run(name, queryFn, options);
+
+        const status = result.passed ? '\x1b[32mPASS\x1b[0m' : '\x1b[31mFAIL\x1b[0m';
+        console.log(
+            `    ${status} p50=${result.timings.median.toFixed(1)}ms ` +
+            `p95=${result.timings.p95.toFixed(1)}ms ` +
+            `rows=${result.rowsReturned} ` +
+            `QPS=${result.queriesPerSecond.toFixed(0)}`
+        );
+
+        if (!result.passed && result.target) {
+            console.log(`    Target: p95 <= ${result.target}ms`);
+        }
+
+        return result;
+    }
+
+    private calculateStdDev(values: number[]): number {
+        if (values.length === 0) return 0;
+        const mean = values.reduce((a, b) => a + b) / values.length;
+        const squareDiffs = values.map(value => Math.pow(value - mean, 2));
+        return Math.sqrt(squareDiffs.reduce((a, b) => a + b) / values.length);
+    }
+
+    private async getRecordCount(): Promise<number> {
+        try {
+            const result = await db`SELECT COUNT(*) as count FROM entities WHERE deleted_at IS NULL`;
+            return parseInt(result[0].count);
+        } catch {
+            return 0;
+        }
+    }
+
+    getResults(): BenchmarkResult[] {
+        return [...this.results];
+    }
+
+    clearResults(): void {
+        this.results = [];
+    }
+
+    /**
+     * Get summary statistics
+     */
+    getSummary(): { passed: number; failed: number; total: number } {
+        const passed = this.results.filter(r => r.passed).length;
+        const failed = this.results.filter(r => !r.passed).length;
+        return { passed, failed, total: this.results.length };
+    }
+}

package/tests/stress/DataSeeder.ts

@@ -0,0 +1,190 @@
+/**
+ * Data seeder for stress testing
+ * Performs optimized bulk inserts for maximum throughput
+ */
+import db from '../../database';
+import { sql } from 'bun';
+import { ComponentRegistry } from '../../core/components';
+import { getMetadataStorage } from '../../core/metadata';
+import { uuidv7 } from '../../utils/uuid';
+import type { BaseComponent } from '../../core/components/BaseComponent';
+
+export interface SeederOptions {
+    totalEntities: number;
+    batchSize: number;
+    onProgress?: (current: number, total: number, elapsedMs: number) => void;
+}
+
+export interface SeederResult {
+    entityIds: string[];
+    totalTime: number;
+    recordsPerSecond: number;
+}
+
+type ComponentConstructor = new () => BaseComponent;
+
+export class DataSeeder {
+    /**
+     * Seeds the database with test entities and components
+     * Uses optimized bulk inserts for maximum throughput
+     */
+    async seed<T extends BaseComponent>(
+        componentClass: ComponentConstructor,
+        dataGenerator: (index: number) => Record<string, any>,
+        options: SeederOptions
+    ): Promise<SeederResult> {
+        const { totalEntities, batchSize, onProgress } = options;
+        const entityIds: string[] = [];
+        const startTime = performance.now();
+
+        // Ensure component is registered (just wait for readiness, don't trigger registration)
+        const componentName = componentClass.name;
+        await ComponentRegistry.getReadyPromise(componentName);
+
+        const storage = getMetadataStorage();
+        const typeId = storage.getComponentId(componentName);
+
+        for (let i = 0; i < totalEntities; i += batchSize) {
+            const currentBatch = Math.min(batchSize, totalEntities - i);
+            const now = new Date();
+
+            // Build batch data arrays
+            const entitiesToInsert: { id: string; created_at: Date; updated_at: Date }[] = [];
+            const componentsToInsert: { id: string; entity_id: string; type_id: string; name: string; data: any; created_at: Date; updated_at: Date }[] = [];
+            const entityComponentsToInsert: { entity_id: string; type_id: string; component_id: string; created_at: Date; updated_at: Date }[] = [];
+
+            // Generate batch data
+            for (let j = 0; j < currentBatch; j++) {
+                const entityId = uuidv7();
+                const componentId = uuidv7();
+                const data = dataGenerator(i + j);
+
+                entitiesToInsert.push({
+                    id: entityId,
+                    created_at: now,
+                    updated_at: now
+                });
+
+                componentsToInsert.push({
+                    id: componentId,
+                    entity_id: entityId,
+                    type_id: typeId,
+                    name: componentName,
+                    data: data,
+                    created_at: now,
+                    updated_at: now
+                });
+
+                entityComponentsToInsert.push({
+                    entity_id: entityId,
+                    type_id: typeId,
+                    component_id: componentId,
+                    created_at: now,
+                    updated_at: now
+                });
+
+                entityIds.push(entityId);
+            }
+
+            // Bulk insert entities using Bun's sql helper
+            await db`INSERT INTO entities ${sql(entitiesToInsert, 'id', 'created_at', 'updated_at')}`;
+
+            // Bulk insert components
+            await db`INSERT INTO components ${sql(componentsToInsert, 'id', 'entity_id', 'type_id', 'name', 'data', 'created_at', 'updated_at')}`;
+
+            // Bulk insert entity_components index
+            await db`INSERT INTO entity_components ${sql(entityComponentsToInsert, 'entity_id', 'type_id', 'component_id', 'created_at', 'updated_at')} ON CONFLICT (entity_id, type_id) DO NOTHING`;
+
+            if (onProgress) {
+                onProgress(i + currentBatch, totalEntities, performance.now() - startTime);
+            }
+        }
+
+        const totalTime = performance.now() - startTime;
+
+        return {
+            entityIds,
+            totalTime,
+            recordsPerSecond: (totalEntities / totalTime) * 1000
+        };
+    }
+
+    /**
+     * Seeds multiple components for existing entities
+     */
+    async seedAdditionalComponent<T extends BaseComponent>(
+        entityIds: string[],
+        componentClass: ComponentConstructor,
+        dataGenerator: (index: number, entityId: string) => Record<string, any>,
+        batchSize: number = 5000
+    ): Promise<void> {
+        const componentName = componentClass.name;
+        await ComponentRegistry.getReadyPromise(componentName);
+
+        const storage = getMetadataStorage();
+        const typeId = storage.getComponentId(componentName);
+
+        for (let i = 0; i < entityIds.length; i += batchSize) {
+            const batchEntityIds = entityIds.slice(i, i + batchSize);
+            const now = new Date();
+
+            const componentsToInsert: { id: string; entity_id: string; type_id: string; name: string; data: any; created_at: Date; updated_at: Date }[] = [];
+            const entityComponentsToInsert: { entity_id: string; type_id: string; component_id: string; created_at: Date; updated_at: Date }[] = [];
+
+            for (let j = 0; j < batchEntityIds.length; j++) {
+                const entityId = batchEntityIds[j]!;
+                const componentId = uuidv7();
+                const data = dataGenerator(i + j, entityId);
+
+                componentsToInsert.push({
+                    id: componentId,
+                    entity_id: entityId,
+                    type_id: typeId,
+                    name: componentName,
+                    data: data,
+                    created_at: now,
+                    updated_at: now
+                });
+
+                entityComponentsToInsert.push({
+                    entity_id: entityId,
+                    type_id: typeId,
+                    component_id: componentId,
+                    created_at: now,
+                    updated_at: now
+                });
+            }
+
+            await db`INSERT INTO components ${sql(componentsToInsert, 'id', 'entity_id', 'type_id', 'name', 'data', 'created_at', 'updated_at')}`;
+            await db`INSERT INTO entity_components ${sql(entityComponentsToInsert, 'entity_id', 'type_id', 'component_id', 'created_at', 'updated_at')} ON CONFLICT (entity_id, type_id) DO NOTHING`;
+        }
+    }
+
+    /**
+     * Cleans up seeded data
+     */
+    async cleanup(entityIds: string[], batchSize: number = 10000): Promise<void> {
+        for (let i = 0; i < entityIds.length; i += batchSize) {
+            const batch = entityIds.slice(i, i + batchSize);
+            // Use individual deletes for reliability
+            await db`DELETE FROM entities WHERE id IN ${sql(batch.map(id => [id]))}`;
+        }
+    }
+
+    /**
+     * Runs VACUUM ANALYZE for optimal query planning
+     */
+    async optimize(): Promise<void> {
+        await db.unsafe('VACUUM ANALYZE entities');
+        await db.unsafe('VACUUM ANALYZE components');
+        await db.unsafe('VACUUM ANALYZE entity_components');
+    }
+
+    /**
+     * Gets the current record count
+     */
+    async getRecordCount(): Promise<number> {
+        const result = await db`SELECT COUNT(*) as count FROM entities WHERE deleted_at IS NULL`;
+        return parseInt(result[0].count);
+    }
+}