bunsane 0.2.4 → 0.2.7

package/tests/integration/query/Query.explainAnalyze.test.ts

@@ -0,0 +1,233 @@
+/**
+ * Integration tests for Query.explainAnalyze() and debugMode()
+ * Tests query plan analysis and debug output
+ */
+import { describe, test, expect, beforeAll, beforeEach } from 'bun:test';
+import { Query, FilterOp } from '../../../query/Query';
+import { TestUser, TestProduct } from '../../fixtures/components';
+import { createTestContext, ensureComponentsRegistered } from '../../utils';
+
+describe('Query EXPLAIN ANALYZE', () => {
+    const ctx = createTestContext();
+
+    beforeAll(async () => {
+        await ensureComponentsRegistered(TestUser, TestProduct);
+    });
+
+    beforeEach(async () => {
+        // Create test data for queries
+        const entity = ctx.tracker.create();
+        entity.add(TestUser, { name: 'ExplainTest', email: 'explain@example.com', age: 30 });
+        await entity.save();
+    });
+
+    describe('explainAnalyze()', () => {
+        test('returns query execution plan', async () => {
+            const plan = await new Query()
+                .with(TestUser)
+                .explainAnalyze();
+
+            expect(plan).toBeDefined();
+            expect(typeof plan).toBe('string');
+            expect(plan.length).toBeGreaterThan(0);
+        });
+
+        test('plan contains execution timing', async () => {
+            const plan = await new Query()
+                .with(TestUser)
+                .explainAnalyze();
+
+            // EXPLAIN ANALYZE includes actual timing
+            expect(plan).toMatch(/actual time=/i);
+        });
+
+        test('plan contains buffer statistics by default', async () => {
+            const plan = await new Query()
+                .with(TestUser)
+                .explainAnalyze(true);
+
+            // BUFFERS option includes shared/local buffer info
+            expect(plan).toMatch(/Buffers:|shared hit|shared read/i);
+        });
+
+        test('plan without buffers when buffers=false', async () => {
+            const plan = await new Query()
+                .with(TestUser)
+                .explainAnalyze(false);
+
+            expect(plan).toBeDefined();
+            // Should still have timing info
+            expect(plan).toMatch(/actual time=/i);
+        });
+
+        test('explains filtered query', async () => {
+            const plan = await new Query()
+                .with(TestUser, {
+                    filters: [Query.filter('name', FilterOp.EQ, 'ExplainTest')]
+                })
+                .explainAnalyze();
+
+            expect(plan).toBeDefined();
+            // Filter should show in the plan
+            expect(plan.length).toBeGreaterThan(0);
+        });
+
+        test('explains query with multiple components', async () => {
+            // Create entity with multiple components
+            const entity = ctx.tracker.create();
+            entity.add(TestUser, { name: 'MultiComp', email: 'multi@example.com', age: 25 });
+            entity.add(TestProduct, { sku: 'EXPLAIN-SKU', name: 'Explain Product', price: 100, inStock: true });
+            await entity.save();
+
+            const plan = await new Query()
+                .with(TestUser)
+                .with(TestProduct)
+                .explainAnalyze();
+
+            expect(plan).toBeDefined();
+            expect(plan.length).toBeGreaterThan(0);
+        });
+
+        test('explains query with sorting', async () => {
+            const plan = await new Query()
+                .with(TestUser)
+                .sortBy(TestUser, 'age', 'DESC')
+                .explainAnalyze();
+
+            expect(plan).toBeDefined();
+            // Sort should show in plan
+            expect(plan).toMatch(/Sort|sort/i);
+        });
+
+        test('explains query with limit', async () => {
+            const plan = await new Query()
+                .with(TestUser)
+                .take(10)
+                .explainAnalyze();
+
+            expect(plan).toBeDefined();
+            // Limit should show in plan
+            expect(plan).toMatch(/Limit|limit/i);
+        });
+
+        test('explains count query equivalent', async () => {
+            // explainAnalyze on a regular query shows the underlying query plan
+            // For count analysis, one would wrap the query differently
+            const plan = await new Query()
+                .with(TestUser)
+                .explainAnalyze();
+
+            expect(plan).toBeDefined();
+        });
+    });
+
+    describe('debugMode()', () => {
+        test('debugMode does not throw', async () => {
+            const results = await new Query()
+                .with(TestUser)
+                .debugMode(true)
+                .exec();
+
+            expect(Array.isArray(results)).toBe(true);
+        });
+
+        test('debugMode can be disabled', async () => {
+            const results = await new Query()
+                .with(TestUser)
+                .debugMode(true)
+                .debugMode(false)
+                .exec();
+
+            expect(Array.isArray(results)).toBe(true);
+        });
+
+        test('debugMode works with count()', async () => {
+            const count = await new Query()
+                .with(TestUser)
+                .debugMode(true)
+                .count();
+
+            expect(typeof count).toBe('number');
+        });
+
+        test('debugMode works with explainAnalyze()', async () => {
+            const plan = await new Query()
+                .with(TestUser)
+                .debugMode(true)
+                .explainAnalyze();
+
+            expect(plan).toBeDefined();
+            expect(typeof plan).toBe('string');
+        });
+
+        test('debugMode works with sum()', async () => {
+            const entity = ctx.tracker.create();
+            entity.add(TestProduct, { sku: 'DEBUG-SUM', name: 'Debug Sum', price: 50, inStock: true });
+            await entity.save();
+
+            const sum = await new Query()
+                .with(TestProduct)
+                .debugMode(true)
+                .sum(TestProduct, 'price');
+
+            expect(typeof sum).toBe('number');
+        });
+
+        test('debugMode works with average()', async () => {
+            const entity = ctx.tracker.create();
+            entity.add(TestProduct, { sku: 'DEBUG-AVG', name: 'Debug Avg', price: 75, inStock: true });
+            await entity.save();
+
+            const avg = await new Query()
+                .with(TestProduct)
+                .debugMode(true)
+                .average(TestProduct, 'price');
+
+            expect(typeof avg).toBe('number');
+        });
+    });
+
+    describe('query plan analysis patterns', () => {
+        test('index scan shows when filtering on indexed field', async () => {
+            // Create several entities to make index usage more likely
+            for (let i = 0; i < 10; i++) {
+                const entity = ctx.tracker.create();
+                entity.add(TestUser, {
+                    name: `IndexTest${i}`,
+                    email: `index${i}@example.com`,
+                    age: 20 + i
+                });
+                await entity.save();
+            }
+
+            const plan = await new Query()
+                .with(TestUser, {
+                    filters: [Query.filter('email', FilterOp.EQ, 'index5@example.com')]
+                })
+                .explainAnalyze();
+
+            expect(plan).toBeDefined();
+            // Plan should show some form of scan
+            expect(plan).toMatch(/Scan|scan/i);
+        });
+
+        test('plan shows rows estimation', async () => {
+            const plan = await new Query()
+                .with(TestUser)
+                .explainAnalyze();
+
+            // EXPLAIN ANALYZE shows estimated vs actual rows
+            expect(plan).toMatch(/rows=/i);
+        });
+
+        test('plan shows execution time', async () => {
+            const plan = await new Query()
+                .with(TestUser)
+                .take(5)
+                .explainAnalyze();
+
+            // Planning and execution time at the end
+            expect(plan).toMatch(/Planning Time:|Execution Time:/i);
+        });
+    });
+});

package/tests/stress/fixtures/RealisticComponents.ts

@@ -0,0 +1,235 @@
+/**
+ * Realistic E-commerce Components for Stress Testing
+ *
+ * These components simulate a real-world e-commerce scenario with:
+ * - Products with metadata
+ * - Inventory tracking
+ * - Pricing with discounts
+ * - Vendor relationships
+ * - Analytics/metrics
+ */
+import { BaseComponent } from '../../../core/components/BaseComponent';
+import { Component, CompData } from '../../../core/components/Decorators';
+import { IndexedField } from '../../../core/decorators/IndexedField';
+
+/**
+ * Product component - core product information
+ */
+@Component
+export class Product extends BaseComponent {
+    @CompData({ indexed: true })
+    @IndexedField('btree')
+    name!: string;
+
+    @CompData({ indexed: true })
+    @IndexedField('btree')
+    sku!: string;
+
+    @CompData()
+    description!: string;
+
+    @CompData({ indexed: true })
+    @IndexedField('btree')
+    category!: string;
+
+    @CompData()
+    @IndexedField('btree')
+    subcategory!: string;
+
+    @CompData()
+    tags!: string[];
+
+    @CompData({ indexed: true })
+    @IndexedField('btree')
+    status!: 'active' | 'inactive' | 'discontinued' | 'pending';
+
+    @CompData()
+    @IndexedField('numeric')
+    rating!: number;
+
+    @CompData()
+    @IndexedField('numeric')
+    reviewCount!: number;
+
+    @CompData()
+    @IndexedField('btree', true)
+    createdAt!: Date;
+
+    @CompData()
+    @IndexedField('btree', true)
+    updatedAt!: Date;
+}
+
+/**
+ * Inventory component - stock tracking
+ */
+@Component
+export class Inventory extends BaseComponent {
+    @CompData()
+    @IndexedField('numeric')
+    quantity!: number;
+
+    @CompData()
+    @IndexedField('numeric')
+    reservedQuantity!: number;
+
+    @CompData()
+    @IndexedField('btree')
+    warehouseId!: string;
+
+    @CompData()
+    @IndexedField('numeric')
+    reorderPoint!: number;
+
+    @CompData()
+    @IndexedField('numeric')
+    maxStock!: number;
+
+    @CompData({ indexed: true })
+    @IndexedField('btree')
+    stockStatus!: 'in_stock' | 'low_stock' | 'out_of_stock' | 'backordered';
+
+    @CompData()
+    @IndexedField('btree', true)
+    lastRestocked!: Date;
+}
+
+/**
+ * Pricing component - price and discount information
+ */
+@Component
+export class Pricing extends BaseComponent {
+    @CompData()
+    @IndexedField('numeric')
+    basePrice!: number;
+
+    @CompData()
+    @IndexedField('numeric')
+    salePrice!: number;
+
+    @CompData()
+    @IndexedField('numeric')
+    costPrice!: number;
+
+    @CompData()
+    @IndexedField('btree')
+    currency!: string;
+
+    @CompData()
+    @IndexedField('numeric')
+    discountPercent!: number;
+
+    @CompData({ indexed: true })
+    @IndexedField('gin')
+    isOnSale!: boolean;
+
+    @CompData()
+    @IndexedField('btree', true)
+    saleStartDate!: Date | null;
+
+    @CompData()
+    @IndexedField('btree', true)
+    saleEndDate!: Date | null;
+
+    @CompData()
+    @IndexedField('numeric')
+    profit!: number;
+}
+
+/**
+ * Vendor component - supplier/seller information
+ */
+@Component
+export class Vendor extends BaseComponent {
+    @CompData({ indexed: true })
+    @IndexedField('btree')
+    vendorId!: string;
+
+    @CompData({ indexed: true })
+    @IndexedField('btree')
+    vendorName!: string;
+
+    @CompData()
+    @IndexedField('btree')
+    region!: string;
+
+    @CompData()
+    @IndexedField('numeric')
+    vendorRating!: number;
+
+    @CompData({ indexed: true })
+    @IndexedField('gin')
+    isVerified!: boolean;
+
+    @CompData()
+    @IndexedField('numeric')
+    totalSales!: number;
+
+    @CompData()
+    @IndexedField('btree')
+    tier!: 'bronze' | 'silver' | 'gold' | 'platinum';
+}
+
+/**
+ * ProductMetrics component - analytics data
+ */
+@Component
+export class ProductMetrics extends BaseComponent {
+    @CompData()
+    @IndexedField('numeric')
+    viewCount!: number;
+
+    @CompData()
+    @IndexedField('numeric')
+    purchaseCount!: number;
+
+    @CompData()
+    @IndexedField('numeric')
+    cartAddCount!: number;
+
+    @CompData()
+    @IndexedField('numeric')
+    wishlistCount!: number;
+
+    @CompData()
+    @IndexedField('numeric')
+    returnCount!: number;
+
+    @CompData()
+    @IndexedField('numeric')
+    conversionRate!: number;
+
+    @CompData()
+    @IndexedField('btree', true)
+    lastPurchased!: Date | null;
+
+    @CompData()
+    @IndexedField('btree')
+    popularityScore!: string;
+}
+
+// Categories for realistic data generation
+export const CATEGORIES = [
+    'Electronics', 'Clothing', 'Home & Garden', 'Sports', 'Books',
+    'Toys', 'Beauty', 'Automotive', 'Food', 'Health'
+] as const;
+
+export const SUBCATEGORIES: Record<string, string[]> = {
+    'Electronics': ['Smartphones', 'Laptops', 'Tablets', 'Accessories', 'Audio'],
+    'Clothing': ['Men', 'Women', 'Kids', 'Shoes', 'Accessories'],
+    'Home & Garden': ['Furniture', 'Decor', 'Kitchen', 'Garden', 'Bedding'],
+    'Sports': ['Fitness', 'Outdoor', 'Team Sports', 'Water Sports', 'Winter'],
+    'Books': ['Fiction', 'Non-Fiction', 'Technical', 'Children', 'Comics'],
+    'Toys': ['Action Figures', 'Board Games', 'Educational', 'Outdoor', 'Puzzles'],
+    'Beauty': ['Skincare', 'Makeup', 'Haircare', 'Fragrance', 'Tools'],
+    'Automotive': ['Parts', 'Accessories', 'Tools', 'Care', 'Electronics'],
+    'Food': ['Snacks', 'Beverages', 'Organic', 'International', 'Specialty'],
+    'Health': ['Vitamins', 'Supplements', 'Personal Care', 'Medical', 'Fitness']
+};
+
+export const REGIONS = ['North', 'South', 'East', 'West', 'Central', 'International'];
+export const WAREHOUSES = ['WH-001', 'WH-002', 'WH-003', 'WH-004', 'WH-005'];
+export const CURRENCIES = ['USD', 'EUR', 'GBP', 'JPY', 'CAD'];
+export const VENDOR_TIERS = ['bronze', 'silver', 'gold', 'platinum'] as const;
+export const PRODUCT_STATUSES = ['active', 'inactive', 'discontinued', 'pending'] as const;
+export const STOCK_STATUSES = ['in_stock', 'low_stock', 'out_of_stock', 'backordered'] as const;