@kernl-sdk/pg 0.1.10 → 0.1.12

package/dist/pgvector/sql/__tests__/query.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query.test.d.ts","sourceRoot":"","sources":["../../../../src/pgvector/sql/__tests__/query.test.ts"],"names":[],"mappings":""}

package/dist/pgvector/sql/__tests__/query.test.js

@@ -0,0 +1,392 @@
+import { describe, it, expect } from "vitest";
+import { sqlize } from "../query.js";
+import { SQL_SELECT } from "../select.js";
+import { SQL_WHERE } from "../where.js";
+import { SQL_ORDER } from "../order.js";
+import { SQL_LIMIT } from "../limit.js";
+describe("sqlize", () => {
+    it("converts query with vector signal", () => {
+        const vector = [0.1, 0.2, 0.3];
+        const result = sqlize({ query: [{ embedding: vector }] }, { pkey: "id", schema: "public", table: "docs" });
+        expect(result.select).toEqual({
+            pkey: "id",
+            signals: [{ embedding: vector }],
+            binding: undefined,
+            include: undefined,
+        });
+        expect(result.where).toEqual({ filter: undefined });
+        expect(result.order).toEqual({
+            signals: [{ embedding: vector }],
+            orderBy: undefined,
+            binding: undefined,
+            schema: "public",
+            table: "docs",
+        });
+        expect(result.limit).toEqual({ topK: 10, offset: 0 });
+    });
+    it("throws on multi-signal fusion (not supported by pgvector)", () => {
+        expect(() => sqlize({
+            max: [
+                { content: "search", weight: 0.3 },
+                { embedding: [0.1, 0.2], weight: 0.7 },
+            ],
+        }, { pkey: "doc_id", schema: "public", table: "docs" })).toThrow("pgvector does not support multi-signal fusion");
+    });
+    it("converts query with filter", () => {
+        const result = sqlize({
+            query: [{ embedding: [0.1, 0.2] }],
+            filter: { status: "active", views: { $gt: 100 } },
+        }, { pkey: "id", schema: "public", table: "docs" });
+        expect(result.where.filter).toEqual({
+            status: "active",
+            views: { $gt: 100 },
+        });
+    });
+    it("converts query with orderBy", () => {
+        const result = sqlize({
+            filter: { status: "active" },
+            orderBy: { field: "created_at", direction: "desc" },
+        }, { pkey: "id", schema: "public", table: "docs" });
+        expect(result.order.orderBy).toEqual({
+            field: "created_at",
+            direction: "desc",
+        });
+    });
+    it("converts query with pagination", () => {
+        const result = sqlize({
+            query: [{ embedding: [0.1, 0.2] }],
+            topK: 25,
+            offset: 50,
+        }, { pkey: "id", schema: "public", table: "docs" });
+        expect(result.limit).toEqual({ topK: 25, offset: 50 });
+    });
+    it("uses default pagination values", () => {
+        const result = sqlize({ query: [{ embedding: [0.1, 0.2] }] }, { pkey: "id", schema: "public", table: "docs" });
+        expect(result.limit).toEqual({ topK: 10, offset: 0 });
+    });
+    it("passes binding through to all inputs", () => {
+        const binding = {
+            schema: "public",
+            table: "docs",
+            pkey: "id",
+            fields: {
+                embedding: {
+                    column: "vec_col",
+                    type: "vector",
+                    dimensions: 3,
+                    similarity: "cosine",
+                },
+            },
+        };
+        const result = sqlize({ query: [{ embedding: [0.1, 0.2, 0.3] }] }, { pkey: "id", schema: "public", table: "docs", binding });
+        expect(result.select.binding).toBe(binding);
+        expect(result.order.binding).toBe(binding);
+    });
+    it("uses custom pkey", () => {
+        const result = sqlize({ query: [{ embedding: [0.1, 0.2] }] }, { pkey: "document_id", schema: "public", table: "docs" });
+        expect(result.select.pkey).toBe("document_id");
+    });
+    it("handles empty query (filter-only)", () => {
+        const result = sqlize({
+            filter: { status: "active" },
+            orderBy: { field: "created_at", direction: "desc" },
+            topK: 100,
+        }, { pkey: "id", schema: "public", table: "docs" });
+        expect(result.select.signals).toEqual([]);
+        expect(result.order.signals).toEqual([]);
+        expect(result.where.filter).toEqual({ status: "active" });
+    });
+    describe("signal priority", () => {
+        it("prefers query over max when both present", () => {
+            const querySignals = [{ embedding: [0.1, 0.2, 0.3] }];
+            const maxSignals = [{ embedding: [0.4, 0.5, 0.6] }];
+            const result = sqlize({ query: querySignals, max: maxSignals }, { pkey: "id", schema: "public", table: "docs" });
+            // query takes precedence over max
+            expect(result.select.signals).toEqual(querySignals);
+            expect(result.order.signals).toEqual(querySignals);
+        });
+        it("uses max when query is undefined", () => {
+            const maxSignals = [{ embedding: [0.4, 0.5, 0.6] }];
+            const result = sqlize({ max: maxSignals }, { pkey: "id", schema: "public", table: "docs" });
+            expect(result.select.signals).toEqual(maxSignals);
+            expect(result.order.signals).toEqual(maxSignals);
+        });
+        it("uses empty array when both query and max are undefined", () => {
+            const result = sqlize({ filter: { status: "active" } }, { pkey: "id", schema: "public", table: "docs" });
+            expect(result.select.signals).toEqual([]);
+            expect(result.order.signals).toEqual([]);
+        });
+    });
+    describe("filter-only with binding", () => {
+        it("passes binding through for filter-only queries", () => {
+            const binding = {
+                schema: "public",
+                table: "docs",
+                pkey: "id",
+                fields: {
+                    embedding: {
+                        column: "vec_col",
+                        type: "vector",
+                        dimensions: 3,
+                        similarity: "cosine",
+                    },
+                },
+            };
+            const result = sqlize({ filter: { status: "active" }, topK: 50 }, { pkey: "id", schema: "public", table: "docs", binding });
+            expect(result.select.binding).toBe(binding);
+            expect(result.order.binding).toBe(binding);
+            expect(result.select.signals).toEqual([]);
+        });
+    });
+    describe("orderBy-only queries", () => {
+        it("handles orderBy without query signals", () => {
+            const result = sqlize({
+                orderBy: { field: "created_at", direction: "asc" },
+                topK: 20,
+            }, { pkey: "id", schema: "public", table: "docs" });
+            expect(result.select.signals).toEqual([]);
+            expect(result.order.signals).toEqual([]);
+            expect(result.order.orderBy).toEqual({
+                field: "created_at",
+                direction: "asc",
+            });
+            expect(result.limit).toEqual({ topK: 20, offset: 0 });
+        });
+    });
+    describe("edge cases", () => {
+        it("handles query with empty signals array", () => {
+            const result = sqlize({ query: [] }, { pkey: "id", schema: "public", table: "docs" });
+            expect(result.select.signals).toEqual([]);
+            expect(result.order.signals).toEqual([]);
+        });
+        it("handles all options together", () => {
+            const binding = {
+                schema: "public",
+                table: "docs",
+                pkey: "id",
+                fields: {
+                    embedding: {
+                        column: "vec_col",
+                        type: "vector",
+                        dimensions: 3,
+                        similarity: "euclidean",
+                    },
+                },
+            };
+            const result = sqlize({
+                query: [{ embedding: [0.1, 0.2, 0.3] }],
+                filter: { status: "active", views: { $gt: 100 } },
+                orderBy: { field: "created_at", direction: "desc" },
+                topK: 50,
+                offset: 25,
+            }, { pkey: "doc_id", schema: "public", table: "documents", binding });
+            expect(result.select.pkey).toBe("doc_id");
+            expect(result.select.signals).toHaveLength(1);
+            expect(result.select.binding).toBe(binding);
+            expect(result.where.filter).toEqual({
+                status: "active",
+                views: { $gt: 100 },
+            });
+            expect(result.order.orderBy).toEqual({
+                field: "created_at",
+                direction: "desc",
+            });
+            expect(result.order.binding).toBe(binding);
+            expect(result.limit).toEqual({ topK: 50, offset: 25 });
+        });
+        it("handles undefined filter", () => {
+            const result = sqlize({ query: [{ embedding: [0.1, 0.2] }] }, { pkey: "id", schema: "public", table: "docs" });
+            expect(result.where.filter).toBeUndefined();
+        });
+        it("handles undefined orderBy", () => {
+            const result = sqlize({ query: [{ embedding: [0.1, 0.2] }] }, { pkey: "id", schema: "public", table: "docs" });
+            expect(result.order.orderBy).toBeUndefined();
+        });
+    });
+});
+/**
+ * Full pipeline integration tests.
+ * These tests verify that sqlize → all codecs → assembled SQL works correctly.
+ */
+describe("full pipeline integration", () => {
+    it("assembles complete SQL with vector search, filter, and pagination", () => {
+        const vector = [0.1, 0.2, 0.3];
+        const binding = {
+            schema: "public",
+            table: "documents",
+            pkey: "id",
+            fields: {
+                embedding: {
+                    column: "vec_col",
+                    type: "vector",
+                    dimensions: 3,
+                    similarity: "cosine",
+                },
+            },
+        };
+        // Step 1: sqlize the query
+        const query = sqlize({
+            query: [{ embedding: vector }],
+            filter: { status: "active", views: { $gt: 100 } },
+            topK: 25,
+            offset: 50,
+        }, { pkey: "doc_id", schema: "public", table: "documents", binding });
+        // Step 2: encode each clause (include: false to exclude extra columns)
+        const select = SQL_SELECT.encode({ ...query.select, include: false });
+        const whereStartIdx = 1 + select.params.length;
+        const where = SQL_WHERE.encode({ ...query.where, startIdx: whereStartIdx });
+        const order = SQL_ORDER.encode(query.order);
+        const limitStartIdx = whereStartIdx + where.params.length;
+        const limit = SQL_LIMIT.encode({ ...query.limit, startIdx: limitStartIdx });
+        // Step 3: verify individual clauses
+        expect(select.sql).toBe('"doc_id" as id, 1 - ("vec_col" <=> $1::vector) as score');
+        expect(select.params).toEqual([JSON.stringify(vector)]);
+        expect(where.sql).toBe('"status" = $2 AND "views" > $3');
+        expect(where.params).toEqual(["active", 100]);
+        expect(order.sql).toBe('"vec_col" <=> $1::vector');
+        expect(limit.sql).toBe("LIMIT $4 OFFSET $5");
+        expect(limit.params).toEqual([25, 50]);
+        // Step 4: verify assembled params array
+        const allParams = [...select.params, ...where.params, ...limit.params];
+        expect(allParams).toEqual([
+            JSON.stringify(vector), // $1
+            "active", // $2
+            100, // $3
+            25, // $4
+            50, // $5
+        ]);
+        // Step 5: verify param indices are correct
+        expect(whereStartIdx).toBe(2);
+        expect(limitStartIdx).toBe(4);
+    });
+    it("assembles SQL with filter-only query (no vector)", () => {
+        const query = sqlize({
+            filter: {
+                status: "published",
+                $or: [{ featured: true }, { views: { $gte: 1000 } }],
+            },
+            orderBy: { field: "created_at", direction: "desc" },
+            topK: 10,
+        }, { pkey: "id", schema: "public", table: "docs" });
+        const select = SQL_SELECT.encode(query.select);
+        const whereStartIdx = 1 + select.params.length;
+        const where = SQL_WHERE.encode({ ...query.where, startIdx: whereStartIdx });
+        const order = SQL_ORDER.encode(query.order);
+        const limitStartIdx = whereStartIdx + where.params.length;
+        const limit = SQL_LIMIT.encode({ ...query.limit, startIdx: limitStartIdx });
+        // No vector signal, so no params from SELECT
+        expect(select.sql).toBe('"id" as id, 1 as score');
+        expect(select.params).toEqual([]);
+        // WHERE starts at $1 since SELECT has no params
+        expect(where.sql).toBe('"status" = $1 AND (("featured" = $2) OR ("views" >= $3))');
+        expect(where.params).toEqual(["published", true, 1000]);
+        // ORDER BY uses explicit field (table-qualified to avoid ambiguity)
+        expect(order.sql).toBe('"public"."docs"."created_at" DESC');
+        // LIMIT starts at $4
+        expect(limit.sql).toBe("LIMIT $4");
+        expect(limit.params).toEqual([10]);
+    });
+    it("assembles SQL with complex nested filter", () => {
+        const vector = [0.5, 0.5];
+        const query = sqlize({
+            query: [{ embedding: vector }],
+            filter: {
+                $and: [
+                    { type: "article" },
+                    {
+                        $or: [
+                            { status: "published" },
+                            { $and: [{ status: "draft" }, { author_id: 123 }] },
+                        ],
+                    },
+                ],
+                deleted_at: null,
+            },
+            topK: 5,
+        }, { pkey: "id", schema: "public", table: "docs" });
+        const select = SQL_SELECT.encode(query.select);
+        const whereStartIdx = 1 + select.params.length;
+        const where = SQL_WHERE.encode({ ...query.where, startIdx: whereStartIdx });
+        const limitStartIdx = whereStartIdx + where.params.length;
+        const limit = SQL_LIMIT.encode({ ...query.limit, startIdx: limitStartIdx });
+        // SELECT uses $1
+        expect(select.params).toHaveLength(1);
+        // WHERE uses $2-$6
+        expect(where.sql).toBe('(("type" = $2) AND ((("status" = $3) OR ((("status" = $4) AND ("author_id" = $5)))))) AND "deleted_at" IS NULL');
+        expect(where.params).toEqual(["article", "published", "draft", 123]);
+        // LIMIT uses $6
+        expect(limit.sql).toBe("LIMIT $6");
+        expect(limit.params).toEqual([5]);
+    });
+    it("handles euclidean distance correctly through pipeline", () => {
+        const vector = [1.0, 2.0, 3.0];
+        const binding = {
+            schema: "public",
+            table: "docs",
+            pkey: "id",
+            fields: {
+                embedding: {
+                    column: "embedding",
+                    type: "vector",
+                    dimensions: 3,
+                    similarity: "euclidean",
+                },
+            },
+        };
+        const query = sqlize({ query: [{ embedding: vector }], topK: 10 }, { pkey: "id", schema: "public", table: "docs", binding });
+        const select = SQL_SELECT.encode({ ...query.select, include: false });
+        const order = SQL_ORDER.encode(query.order);
+        // Euclidean uses <-> operator
+        expect(select.sql).toBe('"id" as id, 1 / (1 + ("embedding" <-> $1::vector)) as score');
+        expect(order.sql).toBe('"embedding" <-> $1::vector');
+    });
+    it("handles dot product correctly through pipeline", () => {
+        const vector = [1.0, 2.0, 3.0];
+        const binding = {
+            schema: "public",
+            table: "docs",
+            pkey: "id",
+            fields: {
+                embedding: {
+                    column: "embedding",
+                    type: "vector",
+                    dimensions: 3,
+                    similarity: "dot_product",
+                },
+            },
+        };
+        const query = sqlize({ query: [{ embedding: vector }], topK: 10 }, { pkey: "id", schema: "public", table: "docs", binding });
+        const select = SQL_SELECT.encode({ ...query.select, include: false });
+        const order = SQL_ORDER.encode(query.order);
+        // Dot product uses <#> operator
+        expect(select.sql).toBe('"id" as id, -("embedding" <#> $1::vector) as score');
+        expect(order.sql).toBe('"embedding" <#> $1::vector');
+    });
+    it("guards against parameter index drift", () => {
+        // This test ensures that when we chain all codecs together,
+        // the parameter indices don't drift or overlap
+        const query = sqlize({
+            query: [{ embedding: [0.1, 0.2] }],
+            filter: { a: 1, b: 2, c: 3 },
+            topK: 10,
+            offset: 20,
+        }, { pkey: "id", schema: "public", table: "docs" });
+        const select = SQL_SELECT.encode(query.select);
+        const whereStartIdx = 1 + select.params.length;
+        const where = SQL_WHERE.encode({ ...query.where, startIdx: whereStartIdx });
+        const limitStartIdx = whereStartIdx + where.params.length;
+        const limit = SQL_LIMIT.encode({ ...query.limit, startIdx: limitStartIdx });
+        // Verify no gaps in indices
+        // SELECT: $1 (vector)
+        // WHERE: $2, $3, $4 (a, b, c)
+        // LIMIT: $5, $6 (topK, offset)
+        expect(select.params).toHaveLength(1); // $1
+        expect(whereStartIdx).toBe(2);
+        expect(where.params).toHaveLength(3); // $2, $3, $4
+        expect(limitStartIdx).toBe(5);
+        expect(limit.params).toHaveLength(2); // $5, $6
+        // Total params should be 6
+        const allParams = [...select.params, ...where.params, ...limit.params];
+        expect(allParams).toHaveLength(6);
+    });
+});

package/dist/pgvector/sql/__tests__/select.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=select.test.d.ts.map

package/dist/pgvector/sql/__tests__/select.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"select.test.d.ts","sourceRoot":"","sources":["../../../../src/pgvector/sql/__tests__/select.test.ts"],"names":[],"mappings":""}