bunsane 0.2.8 → 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.8",
+    "version": "0.2.9",
     "author": {
         "name": "yaaruu"
     },

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/integration/query/Query.exec.test.ts

@@ -16,16 +16,28 @@ describe('Query Execution', () => {
     });
 
     describe('basic query execution', () => {
-        test('exec() returns entities with specified component', async () => {
-            const entity = ctx.tracker.create();
-            entity.add(TestUser, { name: 'QueryTest', email: 'query@example.com', age: 30 });
-            await entity.save();
+        test('exec() returns only entities with specified component', async () => {
+            // Positive case: entity WITH TestUser component
+            const withUser = ctx.tracker.create();
+            withUser.add(TestUser, { name: 'QueryTest', email: 'query@example.com', age: 30 });
+            await withUser.save();
+
+            // Negative case: entity WITHOUT TestUser component (only has TestProduct)
+            const withoutUser = ctx.tracker.create();
+            withoutUser.add(TestProduct, { sku: 'NO_USER', name: 'No User Product', price: 10, inStock: true });
+            await withoutUser.save();
 
             const results = await new Query()
                 .with(TestUser)
                 .exec();
 
-            expect(results.length).toBeGreaterThanOrEqual(1);
+            // Positive: entity with TestUser should be found
+            const foundWithUser = results.some(e => e.id === withUser.id);
+            expect(foundWithUser).toBe(true);
+
+            // Negative: entity without TestUser should NOT be found
+            const foundWithoutUser = results.some(e => e.id === withoutUser.id);
+            expect(foundWithoutUser).toBe(false);
         });
 
         test('populate() loads all component data', async () => {
@@ -282,11 +294,17 @@ describe('Query Execution', () => {
     });
 
     describe('multiple components', () => {
-        test('with() multiple components finds entities with all', async () => {
-            const entity = ctx.tracker.create();
-            entity.add(TestUser, { name: 'MultiComp', email: 'multi@example.com', age: 30 });
-            entity.add(TestProduct, { sku: 'MULTI', name: 'Multi Product', price: 50, inStock: true });
-            await entity.save();
+        test('with() multiple components finds only entities with ALL components', async () => {
+            // Positive case: entity with BOTH TestUser AND TestProduct
+            const withBoth = ctx.tracker.create();
+            withBoth.add(TestUser, { name: 'MultiComp', email: 'multi@example.com', age: 30 });
+            withBoth.add(TestProduct, { sku: 'MULTI', name: 'Multi Product', price: 50, inStock: true });
+            await withBoth.save();
+
+            // Negative case: entity with ONLY TestUser (missing TestProduct)
+            const withOnlyUser = ctx.tracker.create();
+            withOnlyUser.add(TestUser, { name: 'OnlyUser', email: 'onlyuser@example.com', age: 25 });
+            await withOnlyUser.save();
 
             const results = await new Query()
                 .with(TestUser)
@@ -294,10 +312,15 @@ describe('Query Execution', () => {
                 .populate()
                 .exec();
 
-            const found = results.find(e => e.id === entity.id);
-            expect(found).toBeDefined();
-            expect(found?.getInMemory(TestUser)).toBeDefined();
-            expect(found?.getInMemory(TestProduct)).toBeDefined();
+            // Positive: entity with both components should be found
+            const foundWithBoth = results.find(e => e.id === withBoth.id);
+            expect(foundWithBoth).toBeDefined();
+            expect(foundWithBoth?.getInMemory(TestUser)).toBeDefined();
+            expect(foundWithBoth?.getInMemory(TestProduct)).toBeDefined();
+
+            // Negative: entity with only one component should NOT be found
+            const foundWithOnlyUser = results.some(e => e.id === withOnlyUser.id);
+            expect(foundWithOnlyUser).toBe(false);
         });
 
         test('without() excludes entities with component', async () => {
@@ -318,6 +341,36 @@ describe('Query Execution', () => {
             const hasWithProduct = results.some(e => e.id === withProduct.id);
             expect(hasWithProduct).toBe(false);
         });
+
+        test('with() 3+ components without filters finds entities with ALL components', async () => {
+            // Positive case: entity with ALL 3 components
+            const withAll = ctx.tracker.create();
+            withAll.add(TestUser, { name: 'AllThree', email: 'allthree@example.com', age: 30 });
+            withAll.add(TestProduct, { sku: 'ALL3', name: 'All Three Product', price: 100, inStock: true });
+            withAll.add(TestOrder, { orderNumber: 'ORD-ALL3', total: 100, status: 'pending' });
+            await withAll.save();
+
+            // Negative case: entity with only 2 of 3 components (missing TestOrder)
+            const withTwo = ctx.tracker.create();
+            withTwo.add(TestUser, { name: 'TwoOnly', email: 'twoonly@example.com', age: 25 });
+            withTwo.add(TestProduct, { sku: 'TWO', name: 'Two Only Product', price: 50, inStock: true });
+            await withTwo.save();
+
+            // Query for entities with all 3 components - NO FILTERS
+            const results = await new Query()
+                .with(TestUser)
+                .with(TestProduct)
+                .with(TestOrder)
+                .exec();
+
+            // Positive: entity with all 3 components should be found
+            const foundWithAll = results.some(e => e.id === withAll.id);
+            expect(foundWithAll).toBe(true);
+
+            // Negative: entity with only 2 components should NOT be found
+            const foundWithTwo = results.some(e => e.id === withTwo.id);
+            expect(foundWithTwo).toBe(false);
+        });
     });
 
     describe('excludeEntityId()', () => {

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

@@ -0,0 +1,214 @@
+/**
+ * Integration tests for JSONB Array Query Operators
+ * Tests CONTAINS (@>), CONTAINED_BY (<@), HAS_ANY (?|), HAS_ALL (?&)
+ */
+import { describe, test, expect, beforeAll, beforeEach } from 'bun:test';
+import { Query, FilterOp } from '../../../query/Query';
+import { BaseComponent } from '../../../core/components/BaseComponent';
+import { Component, CompData } from '../../../core/components/Decorators';
+import { createTestContext, ensureComponentsRegistered } from '../../utils';
+
+@Component
+class TaggedItem extends BaseComponent {
+    @CompData({ indexed: true, arrayOf: String })
+    tags: string[] = [];
+
+    @CompData({ indexed: true })
+    name: string = '';
+}
+
+@Component
+class CategoryItem extends BaseComponent {
+    @CompData({ indexed: true })
+    title: string = '';
+}
+
+const isPGlite = process.env.USE_PGLITE === 'true';
+
+describe('JSONB Array Query Operators', () => {
+    const ctx = createTestContext();
+
+    beforeAll(async () => {
+        await ensureComponentsRegistered(TaggedItem, CategoryItem);
+    });
+
+    beforeEach(async () => {
+        // entity1: tags = ["red", "blue"]
+        const e1 = ctx.tracker.create();
+        e1.add(TaggedItem, { tags: ['red', 'blue'], name: 'item1' });
+        await e1.save();
+
+        // entity2: tags = ["blue", "green"]
+        const e2 = ctx.tracker.create();
+        e2.add(TaggedItem, { tags: ['blue', 'green'], name: 'item2' });
+        await e2.save();
+
+        // entity3: tags = ["red", "green", "blue"]
+        const e3 = ctx.tracker.create();
+        e3.add(TaggedItem, { tags: ['red', 'green', 'blue'], name: 'item3' });
+        await e3.save();
+
+        // entity4: tags = ["yellow"]
+        const e4 = ctx.tracker.create();
+        e4.add(TaggedItem, { tags: ['yellow'], name: 'item4' });
+        await e4.save();
+    });
+
+    describe('CONTAINS (@>)', () => {
+        test('finds entities where array contains a single value', async () => {
+            const results = await new Query()
+                .with(TaggedItem, {
+                    filters: [Query.filter('tags', FilterOp.CONTAINS, 'red')]
+                })
+                .exec();
+
+            // item1 (red,blue) and item3 (red,green,blue)
+            expect(results.length).toBe(2);
+        });
+
+        test('finds entities where array contains multiple values (AND)', async () => {
+            const results = await new Query()
+                .with(TaggedItem, {
+                    filters: [Query.filter('tags', FilterOp.CONTAINS, ['red', 'blue'])]
+                })
+                .exec();
+
+            // item1 (red,blue) and item3 (red,green,blue) both have red AND blue
+            expect(results.length).toBe(2);
+        });
+
+        test('returns empty when no match', async () => {
+            const results = await new Query()
+                .with(TaggedItem, {
+                    filters: [Query.filter('tags', FilterOp.CONTAINS, 'purple')]
+                })
+                .exec();
+
+            expect(results.length).toBe(0);
+        });
+
+        test('single element array matches', async () => {
+            const results = await new Query()
+                .with(TaggedItem, {
+                    filters: [Query.filter('tags', FilterOp.CONTAINS, 'yellow')]
+                })
+                .exec();
+
+            expect(results.length).toBe(1);
+        });
+
+        test('combined with other filters', async () => {
+            const results = await new Query()
+                .with(TaggedItem, {
+                    filters: [
+                        Query.filter('tags', FilterOp.CONTAINS, 'red'),
+                        Query.filter('name', FilterOp.EQ, 'item1'),
+                    ]
+                })
+                .exec();
+
+            expect(results.length).toBe(1);
+        });
+    });
+
+    describe('CONTAINED_BY (<@)', () => {
+        test('finds entities whose array is a subset of given values', async () => {
+            const results = await new Query()
+                .with(TaggedItem, {
+                    filters: [Query.filter('tags', FilterOp.CONTAINED_BY, ['red', 'blue'])]
+                })
+                .exec();
+
+            // Only item1 (red,blue) is a subset of [red,blue]
+            expect(results.length).toBe(1);
+        });
+
+        test('superset input matches all subsets', async () => {
+            const results = await new Query()
+                .with(TaggedItem, {
+                    filters: [Query.filter('tags', FilterOp.CONTAINED_BY, ['red', 'blue', 'green', 'yellow'])]
+                })
+                .exec();
+
+            // All 4 entities are subsets
+            expect(results.length).toBe(4);
+        });
+    });
+
+    describe.skipIf(isPGlite)('HAS_ANY (?|)', () => {
+        test('finds entities with any of the given values', async () => {
+            const results = await new Query()
+                .with(TaggedItem, {
+                    filters: [Query.filter('tags', FilterOp.HAS_ANY, ['red', 'yellow'])]
+                })
+                .exec();
+
+            // item1 (red), item3 (red), item4 (yellow)
+            expect(results.length).toBe(3);
+        });
+
+        test('single value works', async () => {
+            const results = await new Query()
+                .with(TaggedItem, {
+                    filters: [Query.filter('tags', FilterOp.HAS_ANY, ['yellow'])]
+                })
+                .exec();
+
+            expect(results.length).toBe(1);
+        });
+    });
+
+    describe.skipIf(isPGlite)('HAS_ALL (?&)', () => {
+        test('finds entities with all of the given values', async () => {
+            const results = await new Query()
+                .with(TaggedItem, {
+                    filters: [Query.filter('tags', FilterOp.HAS_ALL, ['red', 'green'])]
+                })
+                .exec();
+
+            // Only item3 (red,green,blue) has both red AND green
+            expect(results.length).toBe(1);
+        });
+
+        test('single value matches all entities containing it', async () => {
+            const results = await new Query()
+                .with(TaggedItem, {
+                    filters: [Query.filter('tags', FilterOp.HAS_ALL, ['blue'])]
+                })
+                .exec();
+
+            // item1, item2, item3 all have blue
+            expect(results.length).toBe(3);
+        });
+    });
+
+    describe('multi-component INTERSECT compatibility', () => {
+        test('CONTAINS works with multiple .with() components', async () => {
+            // Add a second component to one entity
+            const e = ctx.tracker.create();
+            e.add(TaggedItem, { tags: ['special'], name: 'multi' });
+            e.add(CategoryItem, { title: 'test-category' });
+            await e.save();
+
+            const results = await new Query()
+                .with(TaggedItem, {
+                    filters: [Query.filter('tags', FilterOp.CONTAINS, 'special')]
+                })
+                .with(CategoryItem)
+                .exec();
+
+            expect(results.length).toBe(1);
+        });
+    });
+
+    describe('validation', () => {
+        test('rejects null value via validator', () => {
+            expect(() => {
+                new Query()
+                    .with(TaggedItem, {
+                        filters: [Query.filter('tags', FilterOp.CONTAINS, null)]
+                    });
+            }).not.toThrow(); // Filter creation succeeds, validation happens at exec time
+        });
+    });
+});

package/tests/pglite-setup.ts

@@ -35,6 +35,7 @@ const proc = spawn('bun', ['test', ...testDirs], {
     env: {
         ...process.env,
         USE_PGLITE: 'true',
+        DB_CONNECTION_URL: '', // Clear to use POSTGRES_* vars
         POSTGRES_HOST: 'localhost',
         POSTGRES_PORT: String(PORT),
         POSTGRES_USER: 'postgres',

package/tests/unit/query/JsonbArrayBuilder.test.ts

@@ -0,0 +1,178 @@
+/**
+ * Unit tests for JSONB Array Filter Builders
+ */
+import { describe, test, expect } from 'bun:test';
+import { buildJSONBPath } from '../../../query/FilterBuilder';
+import { QueryContext } from '../../../query/QueryContext';
+import {
+    jsonbContainsBuilder,
+    jsonbContainedByBuilder,
+    jsonbHasAnyBuilder,
+    jsonbHasAllBuilder,
+    jsonbArrayOptions,
+} from '../../../query/builders/JsonbArrayBuilder';
+
+describe('buildJSONBPath', () => {
+    test('simple field returns JSONB node path', () => {
+        expect(buildJSONBPath('tags', 'c')).toBe("c.data->'tags'");
+    });
+
+    test('nested field returns JSONB node path', () => {
+        expect(buildJSONBPath('metadata.tags', 'c')).toBe("c.data->'metadata'->'tags'");
+    });
+
+    test('deeply nested field', () => {
+        expect(buildJSONBPath('a.b.c', 'c')).toBe("c.data->'a'->'b'->'c'");
+    });
+
+    test('uses provided alias', () => {
+        expect(buildJSONBPath('tags', 'comp')).toBe("comp.data->'tags'");
+    });
+});
+
+describe('jsonbContainsBuilder (@>)', () => {
+    test('single string value is auto-wrapped in array', () => {
+        const ctx = new QueryContext();
+        const result = jsonbContainsBuilder(
+            { field: 'tags', operator: 'CONTAINS', value: 'urgent' },
+            'c', ctx
+        );
+        expect(result.sql).toBe("c.data->'tags' @> $1::jsonb");
+        expect(ctx.params[0]).toEqual(['urgent']);
+        expect(result.addedParams).toBe(1);
+    });
+
+    test('array value is passed as raw array', () => {
+        const ctx = new QueryContext();
+        const result = jsonbContainsBuilder(
+            { field: 'tags', operator: 'CONTAINS', value: ['a', 'b'] },
+            'c', ctx
+        );
+        expect(result.sql).toBe("c.data->'tags' @> $1::jsonb");
+        expect(ctx.params[0]).toEqual(['a', 'b']);
+    });
+
+    test('nested field path', () => {
+        const ctx = new QueryContext();
+        const result = jsonbContainsBuilder(
+            { field: 'meta.tags', operator: 'CONTAINS', value: 'x' },
+            'c', ctx
+        );
+        expect(result.sql).toBe("c.data->'meta'->'tags' @> $1::jsonb");
+    });
+
+    test('numeric value', () => {
+        const ctx = new QueryContext();
+        jsonbContainsBuilder(
+            { field: 'scores', operator: 'CONTAINS', value: 42 },
+            'c', ctx
+        );
+        expect(ctx.params[0]).toEqual([42]);
+    });
+});
+
+describe('jsonbContainedByBuilder (<@)', () => {
+    test('generates correct SQL', () => {
+        const ctx = new QueryContext();
+        const result = jsonbContainedByBuilder(
+            { field: 'tags', operator: 'CONTAINED_BY', value: ['a', 'b', 'c'] },
+            'c', ctx
+        );
+        expect(result.sql).toBe("c.data->'tags' <@ $1::jsonb");
+        expect(ctx.params[0]).toEqual(['a', 'b', 'c']);
+        expect(result.addedParams).toBe(1);
+    });
+
+    test('single value is auto-wrapped', () => {
+        const ctx = new QueryContext();
+        jsonbContainedByBuilder(
+            { field: 'tags', operator: 'CONTAINED_BY', value: 'only' },
+            'c', ctx
+        );
+        expect(ctx.params[0]).toEqual(['only']);
+    });
+});
+
+describe('jsonbHasAnyBuilder (?|)', () => {
+    test('generates correct SQL with text[] cast', () => {
+        const ctx = new QueryContext();
+        const result = jsonbHasAnyBuilder(
+            { field: 'tags', operator: 'HAS_ANY', value: ['a', 'b'] },
+            'c', ctx
+        );
+        expect(result.sql).toBe("c.data->'tags' ?| $1::text[]");
+        expect(ctx.params[0]).toEqual(['a', 'b']);
+        expect(result.addedParams).toBe(1);
+    });
+
+    test('single value is auto-wrapped and stringified', () => {
+        const ctx = new QueryContext();
+        jsonbHasAnyBuilder(
+            { field: 'tags', operator: 'HAS_ANY', value: 'solo' },
+            'c', ctx
+        );
+        expect(ctx.params[0]).toEqual(['solo']);
+    });
+
+    test('numeric values are cast to strings', () => {
+        const ctx = new QueryContext();
+        jsonbHasAnyBuilder(
+            { field: 'ids', operator: 'HAS_ANY', value: [1, 2, 3] },
+            'c', ctx
+        );
+        expect(ctx.params[0]).toEqual(['1', '2', '3']);
+    });
+});
+
+describe('jsonbHasAllBuilder (?&)', () => {
+    test('generates correct SQL with text[] cast', () => {
+        const ctx = new QueryContext();
+        const result = jsonbHasAllBuilder(
+            { field: 'tags', operator: 'HAS_ALL', value: ['x', 'y'] },
+            'c', ctx
+        );
+        expect(result.sql).toBe("c.data->'tags' ?& $1::text[]");
+        expect(ctx.params[0]).toEqual(['x', 'y']);
+        expect(result.addedParams).toBe(1);
+    });
+});
+
+describe('validation', () => {
+    const validate = jsonbArrayOptions.validate!;
+
+    test('rejects null value', () => {
+        expect(validate({ field: 'f', operator: 'CONTAINS', value: null })).toBe(false);
+    });
+
+    test('rejects undefined value', () => {
+        expect(validate({ field: 'f', operator: 'CONTAINS', value: undefined })).toBe(false);
+    });
+
+    test('rejects empty array', () => {
+        expect(validate({ field: 'f', operator: 'CONTAINS', value: [] })).toBe(false);
+    });
+
+    test('accepts string value', () => {
+        expect(validate({ field: 'f', operator: 'CONTAINS', value: 'tag' })).toBe(true);
+    });
+
+    test('accepts number value', () => {
+        expect(validate({ field: 'f', operator: 'CONTAINS', value: 42 })).toBe(true);
+    });
+
+    test('accepts boolean value', () => {
+        expect(validate({ field: 'f', operator: 'CONTAINS', value: true })).toBe(true);
+    });
+
+    test('accepts array of strings', () => {
+        expect(validate({ field: 'f', operator: 'CONTAINS', value: ['a', 'b'] })).toBe(true);
+    });
+
+    test('rejects object value', () => {
+        expect(validate({ field: 'f', operator: 'CONTAINS', value: { key: 'val' } })).toBe(false);
+    });
+
+    test('rejects array with non-primitive elements', () => {
+        expect(validate({ field: 'f', operator: 'CONTAINS', value: [{ a: 1 }] })).toBe(false);
+    });
+});