@kernl-sdk/pg 0.1.11 → 0.1.12

package/dist/pgvector/search.d.ts

@@ -0,0 +1,60 @@
+import type { Pool } from "pg";
+import { CursorPage } from "@kernl-sdk/shared";
+import type { SearchIndex, IndexHandle, NewIndexParams, ListIndexesParams, IndexSummary, IndexStats, UnknownDocument, SearchCapabilities } from "@kernl-sdk/retrieval";
+import type { PGIndexConfig } from "./types.js";
+export interface PGSearchIndexConfig {
+    pool: Pool;
+    ensureInit?: () => Promise<void>;
+}
+/**
+ * pgvector-backed SearchIndex implementation.
+ */
+export declare class PGSearchIndex implements SearchIndex<PGIndexConfig> {
+    readonly id = "pgvector";
+    private pool;
+    private userInit;
+    private configs;
+    private ready;
+    constructor(config: PGSearchIndexConfig);
+    /**
+     * Create a new index table.
+     *
+     * @param params.id - Table name
+     * @param params.schema - Field definitions (one field must have pk: true)
+     * @param params.providerOptions.schema - Postgres schema (default: "public")
+     */
+    createIndex(params: NewIndexParams): Promise<void>;
+    /**
+     * List all indexes.
+     */
+    listIndexes(params?: ListIndexesParams): Promise<CursorPage<IndexSummary>>;
+    /**
+     * Get index statistics.
+     */
+    describeIndex(id: string): Promise<IndexStats>;
+    /**
+     * Delete an index and all its documents.
+     */
+    deleteIndex(id: string): Promise<void>;
+    /**
+     * No-op for pgvector.
+     */
+    warm(_id: string): Promise<void>;
+    /**
+     * pgvector capabilities.
+     */
+    capabilities(): SearchCapabilities;
+    /**
+     * Get a handle for operating on a specific index.
+     */
+    index<TDocument = UnknownDocument>(id: string): IndexHandle<TDocument>;
+    /**
+     * Bind an existing Postgres table as an index.
+     */
+    bindIndex(id: string, config: PGIndexConfig): Promise<void>;
+    /**
+     * Ensure metadata table exists and load configs.
+     */
+    private ensureInit;
+}
+//# sourceMappingURL=search.d.ts.map

package/dist/pgvector/search.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../../src/pgvector/search.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,IAAI,CAAC;AAC/B,OAAO,EAAE,UAAU,EAA2B,MAAM,mBAAmB,CAAC;AAExE,OAAO,KAAK,EACV,WAAW,EACX,WAAW,EACX,cAAc,EACd,iBAAiB,EACjB,YAAY,EACZ,UAAU,EACV,eAAe,EACf,kBAAkB,EACnB,MAAM,sBAAsB,CAAC;AAI9B,OAAO,KAAK,EAAE,aAAa,EAAkB,MAAM,SAAS,CAAC;AAI7D,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,IAAI,CAAC;IACX,UAAU,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAClC;AAED;;GAEG;AACH,qBAAa,aAAc,YAAW,WAAW,CAAC,aAAa,CAAC;IAC9D,QAAQ,CAAC,EAAE,cAAc;IAEzB,OAAO,CAAC,IAAI,CAAO;IACnB,OAAO,CAAC,QAAQ,CAAsB;IACtC,OAAO,CAAC,OAAO,CAAoC;IACnD,OAAO,CAAC,KAAK,CAAS;gBAEV,MAAM,EAAE,mBAAmB;IAKvC;;;;;;OAMG;IACG,WAAW,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IA8ExD;;OAEG;IACG,WAAW,CACf,MAAM,CAAC,EAAE,iBAAiB,GACzB,OAAO,CAAC,UAAU,CAAC,YAAY,CAAC,CAAC;IAwDpC;;OAEG;IACG,aAAa,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAmCpD;;OAEG;IACG,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAkB5C;;OAEG;IACG,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAEtC;;OAEG;IACH,YAAY,IAAI,kBAAkB;IAUlC;;OAEG;IACH,KAAK,CAAC,SAAS,GAAG,eAAe,EAAE,EAAE,EAAE,MAAM,GAAG,WAAW,CAAC,SAAS,CAAC;IAUtE;;OAEG;IACG,SAAS,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC;IAgBjE;;OAEG;YACW,UAAU;CA8BzB"}

package/dist/pgvector/search.js

@@ -0,0 +1,227 @@
+import { CursorPage } from "@kernl-sdk/shared";
+import { KERNL_SCHEMA_NAME } from "@kernl-sdk/storage";
+import { PGIndexHandle } from "./handle.js";
+import { FIELD_TYPE, SIMILARITY } from "./sql/index.js";
+const META_TABLE = "search_indexes";
+/**
+ * pgvector-backed SearchIndex implementation.
+ */
+export class PGSearchIndex {
+    id = "pgvector";
+    pool;
+    userInit;
+    configs = new Map();
+    ready = false;
+    constructor(config) {
+        this.pool = config.pool;
+        this.userInit = config.ensureInit ?? (() => Promise.resolve());
+    }
+    /**
+     * Create a new index table.
+     *
+     * @param params.id - Table name
+     * @param params.schema - Field definitions (one field must have pk: true)
+     * @param params.providerOptions.schema - Postgres schema (default: "public")
+     */
+    async createIndex(params) {
+        await this.ensureInit();
+        const schemaName = params.providerOptions?.schema ?? "public";
+        // find primary key field
+        const pkEntry = Object.entries(params.schema).find(([, f]) => f.pk);
+        if (!pkEntry) {
+            throw new Error("schema must have a field with pk: true");
+        }
+        const pkey = pkEntry[0];
+        const columns = [];
+        const vectorFields = [];
+        for (const [name, field] of Object.entries(params.schema)) {
+            const colDef = `"${name}" ${FIELD_TYPE.encode(field)}${field.pk ? " PRIMARY KEY" : ""}`;
+            columns.push(colDef);
+            if (field.type === "vector") {
+                vectorFields.push({
+                    name,
+                    dimensions: field.dimensions,
+                    similarity: field.similarity,
+                });
+            }
+        }
+        // create table
+        await this.pool.query(`
+      CREATE TABLE "${schemaName}"."${params.id}" (
+        ${columns.join(",\n        ")}
+      )
+    `);
+        // create HNSW indexes for vector fields
+        for (const vf of vectorFields) {
+            await this.pool.query(`
+        CREATE INDEX "${params.id}_${vf.name}_idx"
+        ON "${schemaName}"."${params.id}"
+        USING hnsw ("${vf.name}" ${SIMILARITY.encode(vf.similarity)})
+      `);
+        }
+        // auto-bind the created table
+        const fields = {};
+        for (const [name, field] of Object.entries(params.schema)) {
+            fields[name] = {
+                column: name,
+                type: field.type,
+                ...(field.type === "vector" && {
+                    dimensions: field.dimensions,
+                    similarity: field.similarity,
+                }),
+            };
+        }
+        const config = {
+            schema: schemaName,
+            table: params.id,
+            pkey,
+            fields,
+        };
+        // persist to metadata table
+        await this.pool.query(`INSERT INTO "${KERNL_SCHEMA_NAME}"."${META_TABLE}" (id, backend, config, created_at)
+       VALUES ($1, $2, $3, $4)`, [params.id, this.id, JSON.stringify(config), Date.now()]);
+        this.configs.set(params.id, config);
+    }
+    /**
+     * List all indexes.
+     */
+    async listIndexes(params) {
+        await this.ensureInit();
+        const loader = async (p) => {
+            const limit = p.limit ?? 100;
+            let sql = `
+        SELECT id FROM "${KERNL_SCHEMA_NAME}"."${META_TABLE}"
+        WHERE backend = $1
+      `;
+            const sqlParams = [this.id];
+            let idx = 2;
+            if (p.prefix) {
+                sql += ` AND id LIKE $${idx}`;
+                sqlParams.push(`${p.prefix}%`);
+                idx++;
+            }
+            if (p.cursor) {
+                sql += ` AND id > $${idx}`;
+                sqlParams.push(p.cursor);
+                idx++;
+            }
+            sql += ` ORDER BY id ASC LIMIT $${idx}`;
+            sqlParams.push(limit + 1);
+            const result = await this.pool.query(sql, sqlParams);
+            const hasMore = result.rows.length > limit;
+            const rows = hasMore ? result.rows.slice(0, -1) : result.rows;
+            const data = rows.map((row) => ({
+                id: row.id,
+                status: "ready",
+            }));
+            return {
+                data,
+                next: hasMore ? (rows[rows.length - 1]?.id ?? null) : null,
+                last: !hasMore,
+            };
+        };
+        const response = await loader(params ?? {});
+        return new CursorPage({
+            params: params ?? {},
+            response,
+            loader,
+        });
+    }
+    /**
+     * Get index statistics.
+     */
+    async describeIndex(id) {
+        await this.ensureInit();
+        const cfg = this.configs.get(id);
+        if (!cfg) {
+            throw new Error(`Index "${id}" not bound`);
+        }
+        // get row count
+        const countRes = await this.pool.query(`SELECT COUNT(*) as count FROM "${cfg.schema}"."${cfg.table}"`);
+        const count = parseInt(countRes.rows[0]?.count ?? "0", 10);
+        // get table size in bytes
+        const sizeRes = await this.pool.query(`SELECT pg_total_relation_size('"${cfg.schema}"."${cfg.table}"') as size`);
+        const sizeb = parseInt(sizeRes.rows[0]?.size ?? "0", 10);
+        // find vector field for dimensions/similarity
+        const vectorField = Object.values(cfg.fields).find((f) => f.type === "vector");
+        return {
+            id,
+            count,
+            sizeb,
+            dimensions: vectorField?.dimensions,
+            similarity: vectorField?.similarity,
+            status: "ready",
+        };
+    }
+    /**
+     * Delete an index and all its documents.
+     */
+    async deleteIndex(id) {
+        await this.ensureInit();
+        const cfg = this.configs.get(id);
+        if (!cfg) {
+            throw new Error(`Index "${id}" not bound`);
+        }
+        await this.pool.query(`DROP TABLE IF EXISTS "${cfg.schema}"."${cfg.table}"`);
+        await this.pool.query(`DELETE FROM "${KERNL_SCHEMA_NAME}"."${META_TABLE}" WHERE id = $1`, [id]);
+        this.configs.delete(id);
+    }
+    /**
+     * No-op for pgvector.
+     */
+    async warm(_id) { }
+    /**
+     * pgvector capabilities.
+     */
+    capabilities() {
+        return {
+            modes: new Set(["vector"]),
+            multiSignal: false,
+            multiVector: false,
+            filters: true,
+            orderBy: true,
+        };
+    }
+    /**
+     * Get a handle for operating on a specific index.
+     */
+    index(id) {
+        const cfg = this.configs.get(id);
+        return new PGIndexHandle(this.pool, () => this.ensureInit(), id, cfg);
+    }
+    /**
+     * Bind an existing Postgres table as an index.
+     */
+    async bindIndex(id, config) {
+        await this.ensureInit();
+        // upsert to metadata table
+        await this.pool.query(`INSERT INTO "${KERNL_SCHEMA_NAME}"."${META_TABLE}" (id, backend, config, created_at)
+       VALUES ($1, $2, $3, $4)
+       ON CONFLICT (id) DO UPDATE SET config = $3`, [id, this.id, JSON.stringify(config), Date.now()]);
+        this.configs.set(id, config);
+    }
+    /* --- internal utils --- */
+    /**
+     * Ensure metadata table exists and load configs.
+     */
+    async ensureInit() {
+        if (this.ready)
+            return;
+        await this.userInit();
+        // create metadata table
+        await this.pool.query(`
+      CREATE TABLE IF NOT EXISTS "${KERNL_SCHEMA_NAME}"."${META_TABLE}" (
+        id TEXT PRIMARY KEY,
+        backend TEXT NOT NULL,
+        config JSONB NOT NULL,
+        created_at BIGINT NOT NULL
+      )
+    `);
+        // load existing configs for this backend
+        const result = await this.pool.query(`SELECT id, config FROM "${KERNL_SCHEMA_NAME}"."${META_TABLE}" WHERE backend = $1`, [this.id]);
+        for (const row of result.rows) {
+            this.configs.set(row.id, row.config);
+        }
+        this.ready = true;
+    }
+}

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

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

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

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

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

@@ -0,0 +1,161 @@
+import { describe, it, expect } from "vitest";
+import { SQL_LIMIT } from "../limit.js";
+describe("SQL_LIMIT", () => {
+    describe("encode", () => {
+        it("builds LIMIT clause", () => {
+            const result = SQL_LIMIT.encode({
+                topK: 10,
+                offset: 0,
+                startIdx: 1,
+            });
+            expect(result.sql).toBe("LIMIT $1");
+            expect(result.params).toEqual([10]);
+        });
+        it("respects startIdx for parameter numbering", () => {
+            const result = SQL_LIMIT.encode({
+                topK: 10,
+                offset: 0,
+                startIdx: 5,
+            });
+            expect(result.sql).toBe("LIMIT $5");
+            expect(result.params).toEqual([10]);
+        });
+        it("includes OFFSET when offset > 0", () => {
+            const result = SQL_LIMIT.encode({
+                topK: 10,
+                offset: 20,
+                startIdx: 1,
+            });
+            expect(result.sql).toBe("LIMIT $1 OFFSET $2");
+            expect(result.params).toEqual([10, 20]);
+        });
+        it("skips OFFSET when offset is 0", () => {
+            const result = SQL_LIMIT.encode({
+                topK: 25,
+                offset: 0,
+                startIdx: 3,
+            });
+            expect(result.sql).toBe("LIMIT $3");
+            expect(result.params).toEqual([25]);
+        });
+        it("handles pagination correctly", () => {
+            // Page 1: offset 0
+            const page1 = SQL_LIMIT.encode({
+                topK: 20,
+                offset: 0,
+                startIdx: 1,
+            });
+            expect(page1.sql).toBe("LIMIT $1");
+            expect(page1.params).toEqual([20]);
+            // Page 2: offset 20
+            const page2 = SQL_LIMIT.encode({
+                topK: 20,
+                offset: 20,
+                startIdx: 1,
+            });
+            expect(page2.sql).toBe("LIMIT $1 OFFSET $2");
+            expect(page2.params).toEqual([20, 20]);
+            // Page 3: offset 40
+            const page3 = SQL_LIMIT.encode({
+                topK: 20,
+                offset: 40,
+                startIdx: 1,
+            });
+            expect(page3.sql).toBe("LIMIT $1 OFFSET $2");
+            expect(page3.params).toEqual([20, 40]);
+        });
+        it("correctly increments param index after SELECT and WHERE", () => {
+            // Simulating: SELECT uses $1, WHERE uses $2-$4
+            // LIMIT should start at $5
+            const result = SQL_LIMIT.encode({
+                topK: 10,
+                offset: 50,
+                startIdx: 5,
+            });
+            expect(result.sql).toBe("LIMIT $5 OFFSET $6");
+            expect(result.params).toEqual([10, 50]);
+        });
+        describe("edge values", () => {
+            it("handles topK: 0", () => {
+                const result = SQL_LIMIT.encode({
+                    topK: 0,
+                    offset: 0,
+                    startIdx: 1,
+                });
+                // LIMIT 0 is valid SQL - returns no rows
+                expect(result.sql).toBe("LIMIT $1");
+                expect(result.params).toEqual([0]);
+            });
+            it("handles topK: 1", () => {
+                const result = SQL_LIMIT.encode({
+                    topK: 1,
+                    offset: 0,
+                    startIdx: 1,
+                });
+                expect(result.sql).toBe("LIMIT $1");
+                expect(result.params).toEqual([1]);
+            });
+            it("handles very large topK", () => {
+                const result = SQL_LIMIT.encode({
+                    topK: 1000000,
+                    offset: 0,
+                    startIdx: 1,
+                });
+                expect(result.sql).toBe("LIMIT $1");
+                expect(result.params).toEqual([1000000]);
+            });
+            it("handles very large offset", () => {
+                const result = SQL_LIMIT.encode({
+                    topK: 10,
+                    offset: 999999,
+                    startIdx: 1,
+                });
+                expect(result.sql).toBe("LIMIT $1 OFFSET $2");
+                expect(result.params).toEqual([10, 999999]);
+            });
+            it("handles very large startIdx", () => {
+                const result = SQL_LIMIT.encode({
+                    topK: 10,
+                    offset: 20,
+                    startIdx: 50,
+                });
+                expect(result.sql).toBe("LIMIT $50 OFFSET $51");
+                expect(result.params).toEqual([10, 20]);
+            });
+            it("handles startIdx: 1 with both topK and offset", () => {
+                const result = SQL_LIMIT.encode({
+                    topK: 25,
+                    offset: 100,
+                    startIdx: 1,
+                });
+                expect(result.sql).toBe("LIMIT $1 OFFSET $2");
+                expect(result.params).toEqual([25, 100]);
+            });
+        });
+        describe("offset boundary", () => {
+            it("includes OFFSET when offset is exactly 1", () => {
+                const result = SQL_LIMIT.encode({
+                    topK: 10,
+                    offset: 1,
+                    startIdx: 1,
+                });
+                expect(result.sql).toBe("LIMIT $1 OFFSET $2");
+                expect(result.params).toEqual([10, 1]);
+            });
+            it("does not include OFFSET when offset is exactly 0", () => {
+                const result = SQL_LIMIT.encode({
+                    topK: 10,
+                    offset: 0,
+                    startIdx: 1,
+                });
+                expect(result.sql).toBe("LIMIT $1");
+                expect(result.params).toEqual([10]);
+            });
+        });
+    });
+    describe("decode", () => {
+        it("throws not implemented", () => {
+            expect(() => SQL_LIMIT.decode({})).toThrow("SQL_LIMIT.decode not implemented");
+        });
+    });
+});

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

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

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

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

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

@@ -0,0 +1,218 @@
+import { describe, it, expect } from "vitest";
+import { SQL_ORDER } from "../order.js";
+describe("SQL_ORDER", () => {
+    describe("encode", () => {
+        it("returns score DESC when no signals or orderBy", () => {
+            const result = SQL_ORDER.encode({
+                signals: [],
+            });
+            expect(result.sql).toBe("score DESC");
+        });
+        describe("explicit orderBy", () => {
+            it("handles orderBy with default direction (desc)", () => {
+                const result = SQL_ORDER.encode({
+                    signals: [],
+                    orderBy: { field: "created_at" },
+                });
+                expect(result.sql).toBe('"created_at" DESC');
+            });
+            it("handles orderBy with asc direction", () => {
+                const result = SQL_ORDER.encode({
+                    signals: [],
+                    orderBy: { field: "name", direction: "asc" },
+                });
+                expect(result.sql).toBe('"name" ASC');
+            });
+            it("handles orderBy with desc direction", () => {
+                const result = SQL_ORDER.encode({
+                    signals: [],
+                    orderBy: { field: "views", direction: "desc" },
+                });
+                expect(result.sql).toBe('"views" DESC');
+            });
+            it("orderBy takes precedence over vector signals", () => {
+                const result = SQL_ORDER.encode({
+                    signals: [{ embedding: [0.1, 0.2, 0.3] }],
+                    orderBy: { field: "created_at", direction: "desc" },
+                });
+                expect(result.sql).toBe('"created_at" DESC');
+            });
+        });
+        describe("vector ordering", () => {
+            it("orders by cosine distance (default)", () => {
+                const result = SQL_ORDER.encode({
+                    signals: [{ embedding: [0.1, 0.2, 0.3] }],
+                });
+                expect(result.sql).toBe('"embedding" <=> $1::vector');
+            });
+            it("uses binding to map field to column", () => {
+                const result = SQL_ORDER.encode({
+                    signals: [{ embedding: [0.1, 0.2, 0.3] }],
+                    binding: {
+                        schema: "public",
+                        table: "docs",
+                        pkey: "id",
+                        fields: {
+                            embedding: {
+                                column: "vec_col",
+                                type: "vector",
+                                dimensions: 3,
+                                similarity: "cosine",
+                            },
+                        },
+                    },
+                });
+                expect(result.sql).toBe('"vec_col" <=> $1::vector');
+            });
+            it("orders by euclidean distance", () => {
+                const result = SQL_ORDER.encode({
+                    signals: [{ embedding: [0.1, 0.2, 0.3] }],
+                    binding: {
+                        schema: "public",
+                        table: "docs",
+                        pkey: "id",
+                        fields: {
+                            embedding: {
+                                column: "embedding",
+                                type: "vector",
+                                dimensions: 3,
+                                similarity: "euclidean",
+                            },
+                        },
+                    },
+                });
+                expect(result.sql).toBe('"embedding" <-> $1::vector');
+            });
+            it("orders by dot product distance", () => {
+                const result = SQL_ORDER.encode({
+                    signals: [{ embedding: [0.1, 0.2, 0.3] }],
+                    binding: {
+                        schema: "public",
+                        table: "docs",
+                        pkey: "id",
+                        fields: {
+                            embedding: {
+                                column: "embedding",
+                                type: "vector",
+                                dimensions: 3,
+                                similarity: "dot_product",
+                            },
+                        },
+                    },
+                });
+                expect(result.sql).toBe('"embedding" <#> $1::vector');
+            });
+            it("ignores non-vector signals", () => {
+                const result = SQL_ORDER.encode({
+                    signals: [{ content: "search text" }],
+                });
+                expect(result.sql).toBe("score DESC");
+            });
+            it("finds vector signal among mixed signals", () => {
+                const result = SQL_ORDER.encode({
+                    signals: [
+                        { content: "search text", weight: 0.3 },
+                        { embedding: [0.1, 0.2, 0.3], weight: 0.7 },
+                    ],
+                });
+                expect(result.sql).toBe('"embedding" <=> $1::vector');
+            });
+        });
+        describe("binding edge cases", () => {
+            it("falls back to field name when binding exists but field not in fields", () => {
+                const result = SQL_ORDER.encode({
+                    signals: [{ embedding: [0.1, 0.2, 0.3] }],
+                    binding: {
+                        schema: "public",
+                        table: "docs",
+                        pkey: "id",
+                        fields: {
+                            other_field: {
+                                column: "other_col",
+                                type: "vector",
+                                dimensions: 3,
+                                similarity: "euclidean",
+                            },
+                        },
+                    },
+                });
+                // embedding not in binding.fields, uses field name and defaults to cosine
+                expect(result.sql).toBe('"embedding" <=> $1::vector');
+            });
+            it("defaults to cosine when binding field has no similarity", () => {
+                const result = SQL_ORDER.encode({
+                    signals: [{ embedding: [0.1, 0.2, 0.3] }],
+                    binding: {
+                        schema: "public",
+                        table: "docs",
+                        fields: {
+                            embedding: {
+                                column: "vec_col",
+                                type: "vector",
+                                dimensions: 3,
+                                // similarity intentionally omitted
+                            },
+                        },
+                    }, // cast to bypass type check for test
+                });
+                expect(result.sql).toBe('"vec_col" <=> $1::vector');
+            });
+        });
+        describe("multiple vector signals", () => {
+            it("uses only the first vector signal for ordering", () => {
+                const result = SQL_ORDER.encode({
+                    signals: [
+                        { embedding1: [0.1, 0.2, 0.3] },
+                        { embedding2: [0.4, 0.5, 0.6] },
+                    ],
+                });
+                // Should use embedding1, not embedding2
+                expect(result.sql).toBe('"embedding1" <=> $1::vector');
+            });
+            it("uses first vector field within a single signal object", () => {
+                const result = SQL_ORDER.encode({
+                    signals: [{ embedding1: [0.1, 0.2], embedding2: [0.3, 0.4] }],
+                });
+                // Object iteration order - first encountered wins
+                expect(result.sql).toMatch(/\$1::vector/);
+            });
+        });
+        describe("consistency with SELECT", () => {
+            it("uses same $1 placeholder as SELECT for vector param", () => {
+                // ORDER BY always references $1::vector when there's a vector signal
+                // This must stay in sync with SELECT which puts vector at $1
+                const result = SQL_ORDER.encode({
+                    signals: [{ embedding: [0.1, 0.2, 0.3] }],
+                });
+                expect(result.sql).toBe('"embedding" <=> $1::vector');
+                // No params returned - ORDER BY reuses SELECT's $1
+            });
+        });
+        describe("malformed signals", () => {
+            it("treats empty signal object as no vector signal", () => {
+                const result = SQL_ORDER.encode({
+                    signals: [{}],
+                });
+                expect(result.sql).toBe("score DESC");
+            });
+            it("treats signal with only weight as no vector signal", () => {
+                const result = SQL_ORDER.encode({
+                    signals: [{ weight: 0.5 }],
+                });
+                expect(result.sql).toBe("score DESC");
+            });
+            it("handles empty vector array", () => {
+                const result = SQL_ORDER.encode({
+                    signals: [{ embedding: [] }],
+                });
+                // Empty array is still detected as vector
+                expect(result.sql).toBe('"embedding" <=> $1::vector');
+            });
+        });
+    });
+    describe("decode", () => {
+        it("throws not implemented", () => {
+            expect(() => SQL_ORDER.decode({})).toThrow("SQL_ORDER.decode not implemented");
+        });
+    });
+});

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

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