bunsane 0.2.7 → 0.2.9

package/CLAUDE.md

@@ -134,6 +134,32 @@ class UserService extends BaseService {
 - PGlite: `CREATE INDEX CONCURRENTLY` must check `process.env.USE_PGLITE`
 - PGlite JSONB: pass JS objects directly, never `JSON.stringify() + ::jsonb`
 
+### Running Tests with PGlite
+
+**IMPORTANT**: To run tests with PGlite, always use `tests/pglite-setup.ts` as the entry point. This script starts an in-memory PostgreSQL server before spawning the test runner.
+
+```bash
+# Correct - uses pglite-setup.ts wrapper
+bun run test:pglite                              # All tests
+bun run test:pglite:unit                         # Unit tests only
+bun tests/pglite-setup.ts tests/unit/            # Specific directory
+bun tests/pglite-setup.ts path/to/file.test.ts   # Single file
+
+# WRONG - will fail with connection errors
+USE_PGLITE=true bun test path/to/file.test.ts    # Won't work!
+```
+
+The wrapper script:
+1. Starts PGlite Socket server on port 54321
+2. Sets required env vars (`USE_PGLITE`, `POSTGRES_*`)
+3. Spawns `bun test` with correct configuration
+4. Cleans up server on exit
+
+**PGlite limitations:**
+- `?|` and `?&` operators not supported (use `@>` / `<@` instead)
+- `CREATE INDEX CONCURRENTLY` not supported
+- Single connection only (`POSTGRES_MAX_CONNECTIONS=1`)
+
 ## Directory Structure
 
 ```

package/docs/SCALABILITY_PLAN.md

@@ -160,9 +160,9 @@ WHERE component_types @> ARRAY[$1, $2]::text[]
 ## Migration Strategy
 
 1. New indexes are additive (no breaking changes)
-2. Query changes behind feature flag: `BUNSANE_QUERY_V2=true`
-3. Gradual rollout with A/B testing on query performance
-4. Deprecate old patterns after validation
+2. Query optimizations are **always on** (no feature flag needed)
+3. INTERSECT + scalar subquery patterns enabled by default since v0.2.7
+4. LATERAL joins disabled for INTERSECT queries to fix SQL generation bug (2026-03-14)
 
 ## Files to Modify
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "bunsane",
-    "version": "0.2.7",
+    "version": "0.2.9",
     "author": {
         "name": "yaaruu"
     },

package/query/ComponentInclusionNode.ts

@@ -54,11 +54,15 @@ export class ComponentInclusionNode extends QueryNode {
 
         let sql = "";
         const componentCount = componentIds.length;
-        const useLateralJoins = Boolean(shouldUseLateralJoins());
 
         // Check if CTE is available and use it to avoid redundant entity_components scans
         const useCTE = Boolean(context.hasCTE && context.cteName);
 
+        // LATERAL joins don't work correctly with INTERSECT queries (non-CTE multi-component)
+        // because the SQL insertion logic places joins inside the INTERSECT subqueries
+        const isIntersectQuery = componentCount > 1 && !useCTE;
+        const useLateralJoins = Boolean(shouldUseLateralJoins()) && !isIntersectQuery;
+
         // Collect LATERAL join fragments if using LATERAL joins
         const lateralJoins: string[] = [];
         const lateralConditions: string[] = [];
@@ -430,11 +434,11 @@ export class ComponentInclusionNode extends QueryNode {
             } else if (typeof filter.value === 'boolean') {
                 condition = `(${jsonPath})::boolean ${filter.operator} $${context.addParam(filter.value)}`;
             } else if (filter.operator === 'IN' || filter.operator === 'NOT IN') {
-                if (Array.isArray(filter.value)) {
+                if (Array.isArray(filter.value) && filter.value.length > 0) {
                     const placeholders = filter.value.map((v: any) => `$${context.addParam(v)}`).join(', ');
                     condition = `${jsonPath} ${filter.operator} (${placeholders})`;
                 } else {
-                    return null; // Invalid - fall back to normal path
+                    return null; // Invalid or empty array - fall back to normal path
                 }
             } else if (filter.operator === 'LIKE' || filter.operator === 'NOT LIKE' || filter.operator === 'ILIKE') {
                 condition = `${jsonPath} ${filter.operator} $${context.addParam(filter.value)}::text`;
@@ -445,6 +449,9 @@ export class ComponentInclusionNode extends QueryNode {
             filterConditions.push(condition);
         }
 
+        // Guard: if no conditions were built, fall back to normal path
+        if (filterConditions.length === 0) return null;
+
         const nullsClause = sortOrder.nullsFirst ? 'NULLS FIRST' : 'NULLS LAST';
         const isNumeric = isNumericProperty(sortOrder.component, sortOrder.property);
         const sortExpr = isNumeric
@@ -622,9 +629,12 @@ export class ComponentInclusionNode extends QueryNode {
                         condition = `${jsonPath} ${filter.operator} $${context.addParam(filter.value)}`;
                     } else if (filter.operator === 'IN' || filter.operator === 'NOT IN') {
                         // IN/NOT IN comparison - handle arrays properly
-                        if (Array.isArray(filter.value)) {
+                        if (Array.isArray(filter.value) && filter.value.length > 0) {
                             const placeholders = Array.from({length: filter.value.length}, (_, i) => `$${context.addParam(filter.value[i])}`).join(', ');
                             condition = `${jsonPath} ${filter.operator} (${placeholders})`;
+                        } else if (Array.isArray(filter.value) && filter.value.length === 0) {
+                            // Empty array: IN () is always false, NOT IN () is always true
+                            condition = filter.operator === 'IN' ? 'FALSE' : 'TRUE';
                         } else {
                             throw new Error(`${filter.operator} operator requires an array of values`);
                         }

package/query/FilterBuilder.ts

@@ -65,6 +65,31 @@ export function buildJSONPath(field: string, alias: string): string {
     }
 }
 
+/**
+ * Build a JSON path expression that returns a JSONB node (not text)
+ *
+ * Unlike buildJSONPath which uses ->> (text extraction) at the leaf,
+ * this uses -> throughout, preserving the JSONB type. Required for
+ * JSONB operators like @>, <@, ?|, ?& that operate on JSONB values.
+ *
+ * @param field - The field path (e.g., "tags" or "metadata.tags")
+ * @param alias - The table alias (e.g., "c")
+ * @returns PostgreSQL JSONB path expression
+ *
+ * @example
+ * buildJSONBPath("tags", "c")          // "c.data->'tags'"
+ * buildJSONBPath("metadata.tags", "c") // "c.data->'metadata'->'tags'"
+ */
+export function buildJSONBPath(field: string, alias: string): string {
+    if (field.includes('.')) {
+        const parts = field.split('.');
+        const lastPart = parts.pop()!;
+        const nestedPath = parts.map(p => `'${p}'`).join('->');
+        return `${alias}.data->${nestedPath}->'${lastPart}'`;
+    }
+    return `${alias}.data->'${field}'`;
+}
+
 /**
  * Compose multiple filter builders into a single builder that applies all conditions
  *

package/query/Query.ts

@@ -25,7 +25,11 @@ export const FilterOp = {
     LIKE: "LIKE" as FilterOperator,
     ILIKE: "ILIKE" as FilterOperator,
     IN: "IN" as FilterOperator,
-    NOT_IN: "NOT IN" as FilterOperator
+    NOT_IN: "NOT IN" as FilterOperator,
+    CONTAINS: "CONTAINS" as FilterOperator,
+    CONTAINED_BY: "CONTAINED_BY" as FilterOperator,
+    HAS_ANY: "HAS_ANY" as FilterOperator,
+    HAS_ALL: "HAS_ALL" as FilterOperator,
 }
 
 export interface QueryFilter {

package/query/builders/JsonbArrayBuilder.ts

@@ -0,0 +1,116 @@
+/**
+ * JSONB Array Filter Builders
+ *
+ * Provides PostgreSQL JSONB array containment and existence operators
+ * as custom filter builders for the BunSane Query system.
+ *
+ * Operators:
+ * - CONTAINS (@>)      — array contains value(s)
+ * - CONTAINED_BY (<@)  — array is subset of given values
+ * - HAS_ANY (?|)       — array has any of the given values
+ * - HAS_ALL (?&)       — array has all of the given values
+ */
+
+import type { FilterBuilder, FilterBuilderOptions } from "../FilterBuilder";
+import { buildJSONBPath } from "../FilterBuilder";
+import type { QueryFilter } from "../QueryContext";
+import type { QueryContext } from "../QueryContext";
+
+export const JSONB_ARRAY_OPS = {
+    CONTAINS: "CONTAINS",
+    CONTAINED_BY: "CONTAINED_BY",
+    HAS_ANY: "HAS_ANY",
+    HAS_ALL: "HAS_ALL",
+} as const;
+
+function normalizeToArray(value: any): any[] {
+    return Array.isArray(value) ? value : [value];
+}
+
+function validateJsonbArrayFilter(filter: QueryFilter): boolean {
+    if (filter.value === null || filter.value === undefined) return false;
+    const arr = normalizeToArray(filter.value);
+    return arr.length > 0 && arr.every(
+        (v: any) => typeof v === 'string' || typeof v === 'number' || typeof v === 'boolean'
+    );
+}
+
+/**
+ * CONTAINS (@>) — "array contains value(s)"
+ *
+ * Single value: Query.filter("tags", FilterOp.CONTAINS, "urgent")
+ * Multiple:     Query.filter("tags", FilterOp.CONTAINS, ["urgent", "high"])
+ */
+export const jsonbContainsBuilder: FilterBuilder = (
+    filter: QueryFilter, alias: string, context: QueryContext
+): { sql: string; addedParams: number } => {
+    const jsonbPath = buildJSONBPath(filter.field, alias);
+    const values = normalizeToArray(filter.value);
+    const paramIndex = context.addParam(values);
+    return {
+        sql: `${jsonbPath} @> $${paramIndex}::jsonb`,
+        addedParams: 1,
+    };
+};
+
+/**
+ * CONTAINED_BY (<@) — "array is subset of given values"
+ *
+ * Query.filter("tags", FilterOp.CONTAINED_BY, ["urgent", "high", "low"])
+ */
+export const jsonbContainedByBuilder: FilterBuilder = (
+    filter: QueryFilter, alias: string, context: QueryContext
+): { sql: string; addedParams: number } => {
+    const jsonbPath = buildJSONBPath(filter.field, alias);
+    const values = normalizeToArray(filter.value);
+    const paramIndex = context.addParam(values);
+    return {
+        sql: `${jsonbPath} <@ $${paramIndex}::jsonb`,
+        addedParams: 1,
+    };
+};
+
+/**
+ * HAS_ANY (?|) — "array has any of the given values"
+ *
+ * Query.filter("tags", FilterOp.HAS_ANY, ["urgent", "high"])
+ *
+ * Note: ?| operates on text[], so values are cast to strings.
+ */
+export const jsonbHasAnyBuilder: FilterBuilder = (
+    filter: QueryFilter, alias: string, context: QueryContext
+): { sql: string; addedParams: number } => {
+    const jsonbPath = buildJSONBPath(filter.field, alias);
+    const values = normalizeToArray(filter.value).map(String);
+    const paramIndex = context.addParam(values);
+    return {
+        sql: `${jsonbPath} ?| $${paramIndex}::text[]`,
+        addedParams: 1,
+    };
+};
+
+/**
+ * HAS_ALL (?&) — "array has all of the given values"
+ *
+ * Query.filter("tags", FilterOp.HAS_ALL, ["urgent", "high"])
+ *
+ * Note: ?& operates on text[], so values are cast to strings.
+ */
+export const jsonbHasAllBuilder: FilterBuilder = (
+    filter: QueryFilter, alias: string, context: QueryContext
+): { sql: string; addedParams: number } => {
+    const jsonbPath = buildJSONBPath(filter.field, alias);
+    const values = normalizeToArray(filter.value).map(String);
+    const paramIndex = context.addParam(values);
+    return {
+        sql: `${jsonbPath} ?& $${paramIndex}::text[]`,
+        addedParams: 1,
+    };
+};
+
+export const jsonbArrayOptions: FilterBuilderOptions = {
+    supportsLateral: true,
+    requiresIndex: false,
+    complexityScore: 1,
+    validate: validateJsonbArrayFilter,
+};

package/query/index.ts

@@ -17,5 +17,31 @@ export type FilterSchema<T = any> = {
 
 // Custom Filter Builder exports
 export type { FilterBuilder, FilterResult, FilterBuilderOptions } from "./FilterBuilder";
-export { buildJSONPath } from "./FilterBuilder";
-export { FilterBuilderRegistry } from "./FilterBuilderRegistry";
+export { buildJSONPath, buildJSONBPath } from "./FilterBuilder";
+export { FilterBuilderRegistry } from "./FilterBuilderRegistry";
+
+// JSONB Array Builder exports
+export {
+    jsonbContainsBuilder,
+    jsonbContainedByBuilder,
+    jsonbHasAnyBuilder,
+    jsonbHasAllBuilder,
+    jsonbArrayOptions,
+    JSONB_ARRAY_OPS,
+} from "./builders/JsonbArrayBuilder";
+
+// Auto-register JSONB array builders (core framework feature)
+import { FilterBuilderRegistry } from "./FilterBuilderRegistry";
+import {
+    jsonbContainsBuilder,
+    jsonbContainedByBuilder,
+    jsonbHasAnyBuilder,
+    jsonbHasAllBuilder,
+    jsonbArrayOptions,
+    JSONB_ARRAY_OPS,
+} from "./builders/JsonbArrayBuilder";
+
+FilterBuilderRegistry.register(JSONB_ARRAY_OPS.CONTAINS, jsonbContainsBuilder, jsonbArrayOptions, "bunsane-jsonb-array", "1.0.0");
+FilterBuilderRegistry.register(JSONB_ARRAY_OPS.CONTAINED_BY, jsonbContainedByBuilder, jsonbArrayOptions, "bunsane-jsonb-array", "1.0.0");
+FilterBuilderRegistry.register(JSONB_ARRAY_OPS.HAS_ANY, jsonbHasAnyBuilder, jsonbArrayOptions, "bunsane-jsonb-array", "1.0.0");
+FilterBuilderRegistry.register(JSONB_ARRAY_OPS.HAS_ALL, jsonbHasAllBuilder, jsonbArrayOptions, "bunsane-jsonb-array", "1.0.0");

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

@@ -0,0 +1,372 @@
+/**
+ * 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);
+    });
+});