bunsane 0.3.1 → 0.4.0

package/tests/benchmark/fixtures/RelationTracker.ts

@@ -1,159 +0,0 @@
-/**
- * Tracks entity IDs during benchmark seeding for foreign key references.
- *
- * Provides methods to retrieve random IDs for establishing relationships
- * between entities (User -> Order -> OrderItem, Product -> Review, etc.)
- */
-import type { SeededRandom } from './EcommerceDataGenerators';
-
-export class RelationTracker {
-    private userIds: string[] = [];
-    private productIds: string[] = [];
-    private orderIds: string[] = [];
-    private orderUserMap: Map<string, string> = new Map();
-
-    /**
-     * Add a user ID to the tracker
-     */
-    addUser(entityId: string): void {
-        this.userIds.push(entityId);
-    }
-
-    /**
-     * Add multiple user IDs
-     */
-    addUsers(entityIds: string[]): void {
-        this.userIds.push(...entityIds);
-    }
-
-    /**
-     * Add a product ID to the tracker
-     */
-    addProduct(entityId: string): void {
-        this.productIds.push(entityId);
-    }
-
-    /**
-     * Add multiple product IDs
-     */
-    addProducts(entityIds: string[]): void {
-        this.productIds.push(...entityIds);
-    }
-
-    /**
-     * Add an order ID with its associated user ID
-     */
-    addOrder(entityId: string, userId: string): void {
-        this.orderIds.push(entityId);
-        this.orderUserMap.set(entityId, userId);
-    }
-
-    /**
-     * Add multiple order IDs (without user mapping - use addOrder for relationship tracking)
-     */
-    addOrders(entityIds: string[]): void {
-        this.orderIds.push(...entityIds);
-    }
-
-    /**
-     * Get a random user ID using the provided RNG
-     */
-    getRandomUserId(rng: SeededRandom): string {
-        if (this.userIds.length === 0) {
-            throw new Error('No user IDs available. Seed users first.');
-        }
-        return this.userIds[Math.floor(rng.next() * this.userIds.length)]!;
-    }
-
-    /**
-     * Get a random product ID using the provided RNG
-     */
-    getRandomProductId(rng: SeededRandom): string {
-        if (this.productIds.length === 0) {
-            throw new Error('No product IDs available. Seed products first.');
-        }
-        return this.productIds[Math.floor(rng.next() * this.productIds.length)]!;
-    }
-
-    /**
-     * Get a random order ID using the provided RNG
-     */
-    getRandomOrderId(rng: SeededRandom): string {
-        if (this.orderIds.length === 0) {
-            throw new Error('No order IDs available. Seed orders first.');
-        }
-        return this.orderIds[Math.floor(rng.next() * this.orderIds.length)]!;
-    }
-
-    /**
-     * Get the user ID associated with an order
-     */
-    getOrderUserId(orderId: string): string | undefined {
-        return this.orderUserMap.get(orderId);
-    }
-
-    /**
-     * Get user IDs with power-law distribution (some users more active)
-     */
-    getActiveUserId(rng: SeededRandom): string {
-        if (this.userIds.length === 0) {
-            throw new Error('No user IDs available. Seed users first.');
-        }
-        // Power-law: top 20% of users are selected 80% of the time
-        const idx = Math.floor(Math.pow(rng.next(), 2) * this.userIds.length);
-        return this.userIds[idx]!;
-    }
-
-    /**
-     * Get product IDs with power-law distribution (popular products)
-     */
-    getPopularProductId(rng: SeededRandom): string {
-        if (this.productIds.length === 0) {
-            throw new Error('No product IDs available. Seed products first.');
-        }
-        const idx = Math.floor(Math.pow(rng.next(), 1.5) * this.productIds.length);
-        return this.productIds[idx]!;
-    }
-
-    /**
-     * Get counts for reporting
-     */
-    getCounts(): { users: number; products: number; orders: number } {
-        return {
-            users: this.userIds.length,
-            products: this.productIds.length,
-            orders: this.orderIds.length
-        };
-    }
-
-    /**
-     * Get all user IDs (for batch operations)
-     */
-    getAllUserIds(): string[] {
-        return [...this.userIds];
-    }
-
-    /**
-     * Get all product IDs (for batch operations)
-     */
-    getAllProductIds(): string[] {
-        return [...this.productIds];
-    }
-
-    /**
-     * Get all order IDs (for batch operations)
-     */
-    getAllOrderIds(): string[] {
-        return [...this.orderIds];
-    }
-
-    /**
-     * Clear all tracked IDs
-     */
-    clear(): void {
-        this.userIds = [];
-        this.productIds = [];
-        this.orderIds = [];
-        this.orderUserMap.clear();
-    }
-}

package/tests/benchmark/fixtures/index.ts

@@ -1,6 +0,0 @@
-/**
- * Benchmark fixtures barrel export
- */
-export * from './EcommerceComponents';
-export * from './EcommerceDataGenerators';
-export * from './RelationTracker';

package/tests/benchmark/index.ts

@@ -1,22 +0,0 @@
-/**
- * PGlite Persistent Benchmark Databases
- *
- * Provides pre-generated databases at various tiers for consistent
- * query performance benchmarking.
- *
- * Usage:
- *   # Generate a database tier
- *   bun run bench:generate:xs
- *
- *   # Run benchmarks against a tier
- *   bun run bench:run:xs
- *
- * Database Tiers:
- *   xs:  10k entities  (1k users, 2k products, 3k orders, 3k items, 1k reviews)
- *   sm:  50k entities  (5k users, 10k products, 15k orders, 15k items, 5k reviews)
- *   md: 100k entities (10k users, 20k products, 30k orders, 30k items, 10k reviews)
- *   lg: 500k entities (50k users, 100k products, 150k orders, 150k items, 50k reviews)
- *   xl:   1M entities (100k users, 200k products, 300k orders, 300k items, 100k reviews)
- */
-export * from './fixtures';
-export * from './runners';

package/tests/benchmark/noop-preload.ts

@@ -1,3 +0,0 @@
-// Minimal preload for benchmarks - does nothing
-// This replaces tests/setup.ts to avoid env var conflicts
-export {};

package/tests/benchmark/query-lateral-benchmark.test.ts

@@ -1,372 +0,0 @@
-/**
- * Benchmark: LATERAL joins vs EXISTS subqueries for multi-component queries
- *
- * Tests the performance impact of the INTERSECT query fix that disables
- * LATERAL joins for multi-component non-CTE queries.
- */
-import { describe, test, expect, beforeAll, afterAll } from 'bun:test';
-import { Entity } from '../../core/Entity';
-import { Query, FilterOp } from '../../query/Query';
-import { Component, CompData, BaseComponent } from '../../core/components';
-import { ComponentRegistry } from '../../core/components/ComponentRegistry';
-import { ensureComponentsRegistered } from '../utils';
-
-// Benchmark components
-@Component
-class BenchUser extends BaseComponent {
-    @CompData({ indexed: true }) name: string = '';
-    @CompData({ indexed: true }) email: string = '';
-    @CompData() age: number = 0;
-    @CompData() status: string = 'active';
-}
-
-@Component
-class BenchProfile extends BaseComponent {
-    @CompData({ indexed: true }) username: string = '';
-    @CompData() bio: string = '';
-    @CompData() verified: boolean = false;
-}
-
-@Component
-class BenchSettings extends BaseComponent {
-    @CompData() theme: string = 'light';
-    @CompData() notifications: boolean = true;
-    @CompData() language: string = 'en';
-}
-
-// Test configuration
-const DATASET_SIZES = {
-    small: 100,
-    medium: 1000,
-    large: 5000
-};
-
-const ITERATIONS = 5; // Number of times to run each query for averaging
-
-interface BenchmarkResult {
-    name: string;
-    datasetSize: number;
-    avgTimeMs: number;
-    minTimeMs: number;
-    maxTimeMs: number;
-    resultCount: number;
-}
-
-async function runBenchmark(
-    name: string,
-    datasetSize: number,
-    queryFn: () => Promise<Entity[]>
-): Promise<BenchmarkResult> {
-    const times: number[] = [];
-    let resultCount = 0;
-
-    for (let i = 0; i < ITERATIONS; i++) {
-        const start = performance.now();
-        const results = await queryFn();
-        const end = performance.now();
-        times.push(end - start);
-        resultCount = results.length;
-    }
-
-    return {
-        name,
-        datasetSize,
-        avgTimeMs: times.reduce((a, b) => a + b, 0) / times.length,
-        minTimeMs: Math.min(...times),
-        maxTimeMs: Math.max(...times),
-        resultCount
-    };
-}
-
-describe('Query Performance Benchmark', () => {
-    const createdEntityIds: string[] = [];
-    const datasetSize = DATASET_SIZES.large; // 5000 entities
-
-    beforeAll(async () => {
-        await ensureComponentsRegistered(BenchUser, BenchProfile, BenchSettings);
-
-        console.log(`\n📊 Creating ${datasetSize} test entities...`);
-        const startCreate = performance.now();
-
-        // Create entities with various component combinations
-        for (let i = 0; i < datasetSize; i++) {
-            const entity = Entity.Create();
-
-            // All entities have BenchUser
-            entity.add(BenchUser, {
-                name: `User ${i}`,
-                email: `user${i}@test.com`,
-                age: 18 + (i % 60),
-                status: i % 3 === 0 ? 'active' : (i % 3 === 1 ? 'inactive' : 'pending')
-            });
-
-            // 80% have BenchProfile
-            if (i % 5 !== 0) {
-                entity.add(BenchProfile, {
-                    username: `user_${i}`,
-                    bio: `Bio for user ${i}`,
-                    verified: i % 2 === 0
-                });
-            }
-
-            // 60% have BenchSettings
-            if (i % 5 < 3) {
-                entity.add(BenchSettings, {
-                    theme: i % 2 === 0 ? 'light' : 'dark',
-                    notifications: i % 3 !== 0,
-                    language: ['en', 'es', 'fr', 'de'][i % 4]!
-                });
-            }
-
-            await entity.save();
-            createdEntityIds.push(entity.id);
-        }
-
-        const endCreate = performance.now();
-        console.log(`✅ Created ${datasetSize} entities in ${(endCreate - startCreate).toFixed(0)}ms\n`);
-    }, 120000); // 2 minute timeout for setup
-
-    afterAll(async () => {
-        // Cleanup
-        console.log(`\n🧹 Cleaning up ${createdEntityIds.length} entities...`);
-        for (const id of createdEntityIds) {
-            try {
-                const entity = await Entity.findById(id);
-                if (entity) {
-                    await entity.delete();
-                }
-            } catch {
-                // Ignore cleanup errors
-            }
-        }
-    }, 120000);
-
-    describe('Single component queries (baseline)', () => {
-        test('single component, no filter', async () => {
-            const result = await runBenchmark(
-                'Single component, no filter',
-                datasetSize,
-                () => new Query().with(BenchUser).take(100).exec()
-            );
-            console.log(`  ${result.name}: ${result.avgTimeMs.toFixed(2)}ms avg (${result.resultCount} results)`);
-            expect(result.avgTimeMs).toBeLessThan(1000);
-        });
-
-        test('single component, with filter', async () => {
-            const result = await runBenchmark(
-                'Single component, with filter',
-                datasetSize,
-                () => new Query()
-                    .with(BenchUser, {
-                        filters: [Query.filter('status', FilterOp.EQ, 'active')]
-                    })
-                    .take(100)
-                    .exec()
-            );
-            console.log(`  ${result.name}: ${result.avgTimeMs.toFixed(2)}ms avg (${result.resultCount} results)`);
-            expect(result.avgTimeMs).toBeLessThan(1000);
-        });
-    });
-
-    describe('Two component queries (affected by fix)', () => {
-        test('2 components, no filter', async () => {
-            const result = await runBenchmark(
-                '2 components, no filter',
-                datasetSize,
-                () => new Query()
-                    .with(BenchUser)
-                    .with(BenchProfile)
-                    .take(100)
-                    .exec()
-            );
-            console.log(`  ${result.name}: ${result.avgTimeMs.toFixed(2)}ms avg (${result.resultCount} results)`);
-            expect(result.avgTimeMs).toBeLessThan(2000);
-        });
-
-        test('2 components, filter on first (bug pattern)', async () => {
-            const result = await runBenchmark(
-                '2 components, filter on first',
-                datasetSize,
-                () => new Query()
-                    .with(BenchUser, {
-                        filters: [Query.filter('status', FilterOp.EQ, 'active')]
-                    })
-                    .with(BenchProfile)
-                    .take(100)
-                    .exec()
-            );
-            console.log(`  ${result.name}: ${result.avgTimeMs.toFixed(2)}ms avg (${result.resultCount} results)`);
-            expect(result.avgTimeMs).toBeLessThan(2000);
-        });
-
-        test('2 components, filter on second (bug pattern)', async () => {
-            const result = await runBenchmark(
-                '2 components, filter on second',
-                datasetSize,
-                () => new Query()
-                    .with(BenchUser)
-                    .with(BenchProfile, {
-                        filters: [Query.filter('verified', FilterOp.EQ, true)]
-                    })
-                    .take(100)
-                    .exec()
-            );
-            console.log(`  ${result.name}: ${result.avgTimeMs.toFixed(2)}ms avg (${result.resultCount} results)`);
-            expect(result.avgTimeMs).toBeLessThan(2000);
-        });
-
-        test('2 components, filters on both', async () => {
-            const result = await runBenchmark(
-                '2 components, filters on both',
-                datasetSize,
-                () => new Query()
-                    .with(BenchUser, {
-                        filters: [Query.filter('status', FilterOp.EQ, 'active')]
-                    })
-                    .with(BenchProfile, {
-                        filters: [Query.filter('verified', FilterOp.EQ, true)]
-                    })
-                    .take(100)
-                    .exec()
-            );
-            console.log(`  ${result.name}: ${result.avgTimeMs.toFixed(2)}ms avg (${result.resultCount} results)`);
-            expect(result.avgTimeMs).toBeLessThan(2000);
-        });
-
-        test('2 components, IN filter (bug pattern)', async () => {
-            const result = await runBenchmark(
-                '2 components, IN filter',
-                datasetSize,
-                () => new Query()
-                    .with(BenchUser, {
-                        filters: [Query.filter('status', FilterOp.IN, ['active', 'pending'])]
-                    })
-                    .with(BenchProfile)
-                    .take(100)
-                    .exec()
-            );
-            console.log(`  ${result.name}: ${result.avgTimeMs.toFixed(2)}ms avg (${result.resultCount} results)`);
-            expect(result.avgTimeMs).toBeLessThan(2000);
-        });
-    });
-
-    describe('Three component queries', () => {
-        test('3 components, no filter', async () => {
-            const result = await runBenchmark(
-                '3 components, no filter',
-                datasetSize,
-                () => new Query()
-                    .with(BenchUser)
-                    .with(BenchProfile)
-                    .with(BenchSettings)
-                    .take(100)
-                    .exec()
-            );
-            console.log(`  ${result.name}: ${result.avgTimeMs.toFixed(2)}ms avg (${result.resultCount} results)`);
-            expect(result.avgTimeMs).toBeLessThan(3000);
-        });
-
-        test('3 components, filter on one', async () => {
-            const result = await runBenchmark(
-                '3 components, filter on one',
-                datasetSize,
-                () => new Query()
-                    .with(BenchUser, {
-                        filters: [Query.filter('age', FilterOp.GTE, 30)]
-                    })
-                    .with(BenchProfile)
-                    .with(BenchSettings)
-                    .take(100)
-                    .exec()
-            );
-            console.log(`  ${result.name}: ${result.avgTimeMs.toFixed(2)}ms avg (${result.resultCount} results)`);
-            expect(result.avgTimeMs).toBeLessThan(3000);
-        });
-
-        test('3 components, filters on all', async () => {
-            const result = await runBenchmark(
-                '3 components, filters on all',
-                datasetSize,
-                () => new Query()
-                    .with(BenchUser, {
-                        filters: [Query.filter('status', FilterOp.EQ, 'active')]
-                    })
-                    .with(BenchProfile, {
-                        filters: [Query.filter('verified', FilterOp.EQ, true)]
-                    })
-                    .with(BenchSettings, {
-                        filters: [Query.filter('theme', FilterOp.EQ, 'dark')]
-                    })
-                    .take(100)
-                    .exec()
-            );
-            console.log(`  ${result.name}: ${result.avgTimeMs.toFixed(2)}ms avg (${result.resultCount} results)`);
-            expect(result.avgTimeMs).toBeLessThan(3000);
-        });
-    });
-
-    describe('Sorting with multi-component (affected by fix)', () => {
-        test('2 components, sort on first', async () => {
-            const result = await runBenchmark(
-                '2 components, sort on first',
-                datasetSize,
-                () => new Query()
-                    .with(BenchUser)
-                    .with(BenchProfile)
-                    .sortBy(BenchUser, 'age', 'DESC')
-                    .take(100)
-                    .exec()
-            );
-            console.log(`  ${result.name}: ${result.avgTimeMs.toFixed(2)}ms avg (${result.resultCount} results)`);
-            expect(result.avgTimeMs).toBeLessThan(3000);
-        });
-
-        test('2 components, filter + sort on different components', async () => {
-            const result = await runBenchmark(
-                '2 components, filter + sort different',
-                datasetSize,
-                () => new Query()
-                    .with(BenchUser)
-                    .with(BenchProfile, {
-                        filters: [Query.filter('verified', FilterOp.EQ, true)]
-                    })
-                    .sortBy(BenchUser, 'age', 'ASC')
-                    .take(100)
-                    .exec()
-            );
-            console.log(`  ${result.name}: ${result.avgTimeMs.toFixed(2)}ms avg (${result.resultCount} results)`);
-            expect(result.avgTimeMs).toBeLessThan(3000);
-        });
-    });
-
-    describe('Count operations', () => {
-        test('2 components count with filter', async () => {
-            const times: number[] = [];
-            let count = 0;
-
-            for (let i = 0; i < ITERATIONS; i++) {
-                const start = performance.now();
-                count = await new Query()
-                    .with(BenchUser, {
-                        filters: [Query.filter('status', FilterOp.EQ, 'active')]
-                    })
-                    .with(BenchProfile)
-                    .count();
-                const end = performance.now();
-                times.push(end - start);
-            }
-
-            const avgTime = times.reduce((a, b) => a + b, 0) / times.length;
-            console.log(`  2 components count with filter: ${avgTime.toFixed(2)}ms avg (count: ${count})`);
-            expect(avgTime).toBeLessThan(2000);
-        });
-    });
-
-    test('Performance summary', () => {
-        console.log('\n📈 Benchmark Summary:');
-        console.log(`   Dataset size: ${datasetSize} entities`);
-        console.log(`   Iterations per query: ${ITERATIONS}`);
-        console.log('   All queries completed within acceptable thresholds');
-        expect(true).toBe(true);
-    });
-});

package/tests/benchmark/runners/BenchmarkLoader.ts

@@ -1,132 +0,0 @@
-/**
- * Loads pre-generated PGlite benchmark databases for running benchmarks.
- *
- * Starts a PGLiteSocketServer connected to the persistent database,
- * allowing the BunSane framework to connect via standard PostgreSQL protocol.
- */
-import { PGlite } from '@electric-sql/pglite';
-import { PGLiteSocketServer } from '@electric-sql/pglite-socket';
-import { existsSync } from 'node:fs';
-import { join, dirname } from 'node:path';
-import { fileURLToPath } from 'node:url';
-
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const DATABASES_DIR = join(__dirname, '..', 'databases');
-
-export type BenchmarkTier = 'xs' | 'sm' | 'md' | 'lg' | 'xl';
-
-export interface BenchmarkLoaderOptions {
-    tier: BenchmarkTier;
-    port?: number;
-}
-
-export interface LoadedBenchmark {
-    pg: PGlite;
-    server: PGLiteSocketServer;
-    port: number;
-    tier: BenchmarkTier;
-    stop: () => Promise<void>;
-}
-
-const TIER_ENTITY_COUNTS: Record<BenchmarkTier, number> = {
-    xs: 10_000,
-    sm: 50_000,
-    md: 100_000,
-    lg: 500_000,
-    xl: 1_000_000
-};
-
-/**
- * Load a pre-generated benchmark database and start the socket server.
- *
- * @throws Error if database doesn't exist (prompts to generate)
- */
-export async function loadBenchmarkDatabase(options: BenchmarkLoaderOptions): Promise<LoadedBenchmark> {
-    const { tier, port = 54321 } = options;
-    const dbPath = join(DATABASES_DIR, tier);
-
-    if (!existsSync(dbPath)) {
-        throw new Error(
-            `Benchmark database for tier '${tier}' not found at ${dbPath}\n\n` +
-            `Generate it first with:\n` +
-            `  bun tests/benchmark/scripts/generate-db.ts ${tier}\n\n` +
-            `Or generate all tiers:\n` +
-            `  bun tests/benchmark/scripts/generate-db.ts --all`
-        );
-    }
-
-    console.log(`[benchmark] Loading ${tier.toUpperCase()} tier database from ${dbPath}...`);
-
-    // Open persistent database (read-only would be ideal but PGlite doesn't support it)
-    const pg = new PGlite(dbPath);
-    await pg.waitReady;
-
-    // Verify database has data
-    const countResult = await pg.query<{ count: string }>('SELECT COUNT(*) as count FROM entities');
-    const entityCount = parseInt(countResult.rows[0]?.count || '0');
-
-    if (entityCount === 0) {
-        await pg.close();
-        throw new Error(
-            `Benchmark database for tier '${tier}' exists but is empty.\n` +
-            `Regenerate with:\n` +
-            `  bun tests/benchmark/scripts/generate-db.ts ${tier} --force`
-        );
-    }
-
-    console.log(`[benchmark] Loaded ${entityCount.toLocaleString()} entities`);
-
-    // Start socket server
-    const server = new PGLiteSocketServer({ db: pg, port });
-    await server.start();
-    console.log(`[benchmark] Socket server running on port ${port}`);
-
-    const stop = async () => {
-        console.log('[benchmark] Stopping server...');
-        try { await server.stop(); } catch {}
-        try { await pg.close(); } catch {}
-    };
-
-    return { pg, server, port, tier, stop };
-}
-
-/**
- * Get expected entity count for a tier
- */
-export function getTierEntityCount(tier: BenchmarkTier): number {
-    return TIER_ENTITY_COUNTS[tier];
-}
-
-/**
- * Get tier from environment variable BENCHMARK_TIER
- */
-export function getTierFromEnv(): BenchmarkTier {
-    const tier = process.env.BENCHMARK_TIER || 'xs';
-    if (!['xs', 'sm', 'md', 'lg', 'xl'].includes(tier)) {
-        console.warn(`Invalid BENCHMARK_TIER '${tier}', defaulting to 'xs'`);
-        return 'xs';
-    }
-    return tier as BenchmarkTier;
-}
-
-/**
- * Get database path for a tier
- */
-export function getDatabasePath(tier: BenchmarkTier): string {
-    return join(DATABASES_DIR, tier);
-}
-
-/**
- * Check if a tier's database exists
- */
-export function databaseExists(tier: BenchmarkTier): boolean {
-    return existsSync(getDatabasePath(tier));
-}
-
-/**
- * Get all available (generated) tiers
- */
-export function getAvailableTiers(): BenchmarkTier[] {
-    const tiers: BenchmarkTier[] = ['xs', 'sm', 'md', 'lg', 'xl'];
-    return tiers.filter(tier => databaseExists(tier));
-}

package/tests/benchmark/runners/index.ts

@@ -1,4 +0,0 @@
-/**
- * Benchmark runners barrel export
- */
-export * from './BenchmarkLoader';