@kernl-sdk/pg 0.1.11 → 0.1.12

package/dist/migrations.d.ts

@@ -17,7 +17,7 @@ export interface Migration {
 /**
  * List of all migrations in order.
  */
-export declare const migrations: Migration[];
+export declare const MIGRATIONS: Migration[];
 /**
  * Minimum schema version required by this version of @kernl/pg.
  */

package/dist/migrations.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"migrations.d.ts","sourceRoot":"","sources":["../src/migrations.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,IAAI,CAAC;AACrC,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAGxD;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,UAAU,CAAC;IACnB,WAAW,EAAE,CAAC,KAAK,EAAE,KAAK,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9E;AAED,MAAM,WAAW,SAAS;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,CAAC,GAAG,EAAE,gBAAgB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9C;AAED;;GAEG;AACH,eAAO,MAAM,UAAU,EAAE,SAAS,EAQjC,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,uBAAuB,iBAAiB,CAAC"}
+{"version":3,"file":"migrations.d.ts","sourceRoot":"","sources":["../src/migrations.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,IAAI,CAAC;AACrC,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAOxD;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,UAAU,CAAC;IACnB,WAAW,EAAE,CAAC,KAAK,EAAE,KAAK,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9E;AAED,MAAM,WAAW,SAAS;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,CAAC,GAAG,EAAE,gBAAgB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9C;AAED;;GAEG;AACH,eAAO,MAAM,UAAU,EAAE,SAAS,EAcjC,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,uBAAuB,iBAAiB,CAAC"}

package/dist/migrations.js

@@ -1,18 +1,24 @@
 /**
  * Database migrations.
  */
-import { TABLE_THREADS, TABLE_THREAD_EVENTS } from "@kernl-sdk/storage";
+import { TABLE_THREADS, TABLE_THREAD_EVENTS, TABLE_MEMORIES, } from "@kernl-sdk/storage";
 /**
  * List of all migrations in order.
  */
-export const migrations = [
+export const MIGRATIONS = [
     {
-        id: "0001_initial",
+        id: "001_threads",
         async up(ctx) {
             await ctx.createTable(TABLE_THREADS);
             await ctx.createTable(TABLE_THREAD_EVENTS);
         },
     },
+    {
+        id: "002_memories",
+        async up(ctx) {
+            await ctx.createTable(TABLE_MEMORIES);
+        },
+    },
 ];
 /**
  * Minimum schema version required by this version of @kernl/pg.

package/dist/pgvector/__tests__/handle.test.d.ts

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

package/dist/pgvector/__tests__/handle.test.d.ts.map

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

package/dist/pgvector/__tests__/handle.test.js

@@ -0,0 +1,277 @@
+import { describe, it, expect, beforeAll, afterAll, beforeEach } from "vitest";
+import { Pool } from "pg";
+import { PGSearchIndex } from "../search.js";
+const TEST_DB_URL = process.env.KERNL_PG_TEST_URL;
+const SCHEMA = "kernl_search_test";
+describe.sequential("PGIndexHandle", () => {
+    if (!TEST_DB_URL) {
+        it.skip("requires KERNL_PG_TEST_URL environment variable", () => { });
+        return;
+    }
+    let pool;
+    let search;
+    let initialized = false;
+    const ensureInit = async () => {
+        if (initialized)
+            return;
+        await pool.query(`CREATE EXTENSION IF NOT EXISTS vector`);
+        await pool.query(`CREATE SCHEMA IF NOT EXISTS "${SCHEMA}"`);
+        await pool.query(`
+      CREATE TABLE IF NOT EXISTS "${SCHEMA}"."documents" (
+        id TEXT PRIMARY KEY,
+        title TEXT,
+        content TEXT,
+        status TEXT,
+        views INTEGER DEFAULT 0,
+        embedding vector(3)
+      )
+    `);
+        await pool.query(`
+      CREATE INDEX IF NOT EXISTS documents_embedding_idx
+      ON "${SCHEMA}"."documents"
+      USING hnsw (embedding vector_cosine_ops)
+    `);
+        initialized = true;
+    };
+    beforeAll(async () => {
+        pool = new Pool({ connectionString: TEST_DB_URL });
+        search = new PGSearchIndex({ pool, ensureInit });
+        // Clean slate
+        await pool.query(`DROP SCHEMA IF EXISTS "${SCHEMA}" CASCADE`);
+    });
+    afterAll(async () => {
+        await pool.query(`DROP SCHEMA IF EXISTS "${SCHEMA}" CASCADE`);
+        await pool.end();
+    });
+    beforeEach(async () => {
+        // Clear table between tests
+        if (initialized) {
+            await pool.query(`DELETE FROM "${SCHEMA}"."documents"`);
+        }
+    });
+    describe("bindIndex", () => {
+        it("registers binding for later use", async () => {
+            await search.bindIndex("docs", {
+                schema: SCHEMA,
+                table: "documents",
+                pkey: "id",
+                fields: {
+                    title: { column: "title", type: "string" },
+                    content: { column: "content", type: "string" },
+                    embedding: {
+                        column: "embedding",
+                        type: "vector",
+                        dimensions: 3,
+                        similarity: "cosine",
+                    },
+                },
+            });
+            // Can get handle without error
+            const handle = search.index("docs");
+            expect(handle.id).toBe("docs");
+        });
+    });
+    describe("index().query()", () => {
+        beforeAll(async () => {
+            await search.bindIndex("docs", {
+                schema: SCHEMA,
+                table: "documents",
+                pkey: "id",
+                fields: {
+                    title: { column: "title", type: "string" },
+                    content: { column: "content", type: "string" },
+                    status: { column: "status", type: "string" },
+                    views: { column: "views", type: "int" },
+                    embedding: {
+                        column: "embedding",
+                        type: "vector",
+                        dimensions: 3,
+                        similarity: "cosine",
+                    },
+                },
+            });
+        });
+        async function insertDocs() {
+            await ensureInit();
+            await pool.query(`
+        INSERT INTO "${SCHEMA}"."documents" (id, title, content, status, views, embedding)
+        VALUES
+          ('doc1', 'Hello World', 'First document', 'active', 100, '[0.1, 0.2, 0.3]'),
+          ('doc2', 'Goodbye World', 'Second document', 'active', 200, '[0.4, 0.5, 0.6]'),
+          ('doc3', 'Hello Again', 'Third document', 'draft', 50, '[0.15, 0.25, 0.35]'),
+          ('doc4', 'Final Doc', 'Fourth document', 'archived', 500, '[0.9, 0.8, 0.7]')
+      `);
+        }
+        it("queries with vector search", async () => {
+            await insertDocs();
+            const handle = search.index("docs");
+            const results = await handle.query({
+                query: [{ embedding: [0.1, 0.2, 0.3] }],
+                topK: 2,
+            });
+            expect(results).toHaveLength(2);
+            expect(results[0].id).toBe("doc1"); // closest match
+            expect(results[0].score).toBeGreaterThan(0.9); // high similarity
+            expect(results[0].index).toBe("docs");
+        });
+        it("queries with filter", async () => {
+            await insertDocs();
+            const handle = search.index("docs");
+            const results = await handle.query({
+                query: [{ embedding: [0.1, 0.2, 0.3] }],
+                filter: { status: "active" },
+                topK: 10,
+            });
+            expect(results).toHaveLength(2);
+            results.forEach((r) => {
+                expect(r.document?.status).toBe("active");
+            });
+        });
+        it("queries with comparison filter", async () => {
+            await insertDocs();
+            const handle = search.index("docs");
+            const results = await handle.query({
+                query: [{ embedding: [0.1, 0.2, 0.3] }],
+                filter: { views: { $gte: 100 } },
+                topK: 10,
+            });
+            expect(results.length).toBeGreaterThanOrEqual(2);
+            results.forEach((r) => {
+                expect(r.document?.views).toBeGreaterThanOrEqual(100);
+            });
+        });
+        it("queries with $or filter", async () => {
+            await insertDocs();
+            const handle = search.index("docs");
+            const results = await handle.query({
+                query: [{ embedding: [0.1, 0.2, 0.3] }],
+                filter: {
+                    $or: [{ status: "draft" }, { status: "archived" }],
+                },
+                topK: 10,
+            });
+            expect(results).toHaveLength(2);
+            results.forEach((r) => {
+                expect(["draft", "archived"]).toContain(r.document?.status);
+            });
+        });
+        it("queries with $in filter", async () => {
+            await insertDocs();
+            const handle = search.index("docs");
+            const results = await handle.query({
+                query: [{ embedding: [0.1, 0.2, 0.3] }],
+                filter: { status: { $in: ["active", "draft"] } },
+                topK: 10,
+            });
+            expect(results).toHaveLength(3);
+        });
+        it("respects topK limit", async () => {
+            await insertDocs();
+            const handle = search.index("docs");
+            const results = await handle.query({
+                query: [{ embedding: [0.5, 0.5, 0.5] }],
+                topK: 2,
+            });
+            expect(results).toHaveLength(2);
+        });
+        it("respects offset for pagination", async () => {
+            await insertDocs();
+            const handle = search.index("docs");
+            // Get first 2
+            const page1 = await handle.query({
+                query: [{ embedding: [0.5, 0.5, 0.5] }],
+                topK: 2,
+                offset: 0,
+            });
+            // Get next 2
+            const page2 = await handle.query({
+                query: [{ embedding: [0.5, 0.5, 0.5] }],
+                topK: 2,
+                offset: 2,
+            });
+            expect(page1).toHaveLength(2);
+            expect(page2).toHaveLength(2);
+            expect(page1[0].id).not.toBe(page2[0].id);
+        });
+        it("queries with orderBy (non-vector)", async () => {
+            await insertDocs();
+            const handle = search.index("docs");
+            const results = await handle.query({
+                filter: { status: "active" },
+                orderBy: { field: "views", direction: "desc" },
+                topK: 10,
+            });
+            expect(results).toHaveLength(2);
+            expect(results[0].document?.views).toBe(200);
+            expect(results[1].document?.views).toBe(100);
+        });
+        it("returns documents with mapped field names", async () => {
+            await insertDocs();
+            const handle = search.index("docs");
+            const results = await handle.query({
+                query: [{ embedding: [0.1, 0.2, 0.3] }],
+                topK: 1,
+            });
+            expect(results[0].document).toHaveProperty("title");
+            expect(results[0].document).toHaveProperty("content");
+            expect(results[0].document).toHaveProperty("status");
+            expect(results[0].document).toHaveProperty("views");
+            expect(results[0].document).toHaveProperty("embedding");
+        });
+        it("returns empty array when no matches", async () => {
+            await insertDocs();
+            const handle = search.index("docs");
+            const results = await handle.query({
+                query: [{ embedding: [0.1, 0.2, 0.3] }],
+                filter: { status: "nonexistent" },
+                topK: 10,
+            });
+            expect(results).toEqual([]);
+        });
+    });
+    describe("index() generic type", () => {
+        beforeAll(async () => {
+            await search.bindIndex("typed-docs", {
+                schema: SCHEMA,
+                table: "documents",
+                pkey: "id",
+                fields: {
+                    title: { column: "title", type: "string" },
+                    content: { column: "content", type: "string" },
+                    status: { column: "status", type: "string" },
+                    views: { column: "views", type: "int" },
+                    embedding: {
+                        column: "embedding",
+                        type: "vector",
+                        dimensions: 3,
+                        similarity: "cosine",
+                    },
+                },
+            });
+        });
+        it("provides typed document access", async () => {
+            await ensureInit();
+            await pool.query(`
+        INSERT INTO "${SCHEMA}"."documents" (id, title, content, status, views, embedding)
+        VALUES ('typed1', 'Typed Doc', 'Typed content', 'active', 42, '[0.1, 0.2, 0.3]')
+      `);
+            const handle = search.index("typed-docs");
+            const results = await handle.query({
+                query: [{ embedding: [0.1, 0.2, 0.3] }],
+                topK: 1,
+            });
+            // TypeScript should allow these without errors
+            const doc = results[0].document;
+            expect(doc?.title).toBe("Typed Doc");
+            expect(doc?.views).toBe(42);
+        });
+    });
+    describe("error handling", () => {
+        it("throws when table does not exist", async () => {
+            const handle = search.index("unbound-index");
+            // Convention-based indexing tries to use "public.unbound-index"
+            // which doesn't exist, so PostgreSQL throws an error
+            await expect(handle.query({ query: [{ embedding: [0.1, 0.2, 0.3] }] })).rejects.toThrow('relation "public.unbound-index" does not exist');
+        });
+    });
+});

package/dist/pgvector/__tests__/hit.test.d.ts

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

package/dist/pgvector/__tests__/hit.test.d.ts.map

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

package/dist/pgvector/__tests__/hit.test.js

@@ -0,0 +1,134 @@
+import { describe, it, expect } from "vitest";
+import { SEARCH_HIT } from "../hit.js";
+describe("SEARCH_HIT", () => {
+    describe("decode", () => {
+        it("converts basic row to SearchHit", () => {
+            const row = {
+                id: "doc-123",
+                score: 0.95,
+                title: "Hello World",
+                content: "Some content",
+            };
+            const result = SEARCH_HIT.decode(row, "docs");
+            expect(result).toEqual({
+                id: "doc-123",
+                index: "docs",
+                score: 0.95,
+                document: {
+                    id: "doc-123",
+                    title: "Hello World",
+                    content: "Some content",
+                },
+            });
+        });
+        it("converts id to string", () => {
+            const row = { id: 123, score: 0.5 };
+            const result = SEARCH_HIT.decode(row, "docs");
+            expect(result.id).toBe("123");
+        });
+        it("defaults score to 0 when not a number", () => {
+            const row = { id: "1", score: null };
+            const result = SEARCH_HIT.decode(row, "docs");
+            expect(result.score).toBe(0);
+        });
+        it("defaults score to 0 when undefined", () => {
+            const row = { id: "1" };
+            const result = SEARCH_HIT.decode(row, "docs");
+            expect(result.score).toBe(0);
+        });
+        it("returns document with only id when no other fields", () => {
+            const row = { id: "1", score: 0.5 };
+            const result = SEARCH_HIT.decode(row, "docs");
+            expect(result.document).toEqual({ id: "1" });
+        });
+        describe("with binding", () => {
+            const binding = {
+                schema: "public",
+                table: "documents",
+                pkey: "id",
+                fields: {
+                    title: { column: "doc_title", type: "string" },
+                    content: { column: "doc_content", type: "string" },
+                    embedding: {
+                        column: "vec",
+                        type: "vector",
+                        dimensions: 3,
+                    },
+                },
+            };
+            it("maps columns to logical field names", () => {
+                const row = {
+                    id: "1",
+                    score: 0.9,
+                    doc_title: "Hello",
+                    doc_content: "World",
+                    vec: [0.1, 0.2, 0.3],
+                };
+                const result = SEARCH_HIT.decode(row, "docs", binding);
+                expect(result.document).toEqual({
+                    id: "1",
+                    title: "Hello",
+                    content: "World",
+                    embedding: [0.1, 0.2, 0.3],
+                });
+            });
+            it("only includes fields defined in binding", () => {
+                const row = {
+                    id: "1",
+                    score: 0.9,
+                    doc_title: "Hello",
+                    extra_col: "should be ignored",
+                    internal_field: "also ignored",
+                };
+                const result = SEARCH_HIT.decode(row, "docs", binding);
+                expect(result.document).toEqual({
+                    id: "1",
+                    title: "Hello",
+                });
+                expect(result.document?.extra_col).toBeUndefined();
+                expect(result.document?.internal_field).toBeUndefined();
+            });
+            it("handles missing columns gracefully", () => {
+                const row = {
+                    id: "1",
+                    score: 0.9,
+                    doc_title: "Hello",
+                    // doc_content and vec are missing
+                };
+                const result = SEARCH_HIT.decode(row, "docs", binding);
+                expect(result.document).toEqual({
+                    id: "1",
+                    title: "Hello",
+                });
+            });
+            it("returns document with only id when no bound fields present", () => {
+                const row = {
+                    id: "1",
+                    score: 0.9,
+                    unrelated_column: "value",
+                };
+                const result = SEARCH_HIT.decode(row, "docs", binding);
+                expect(result.document).toEqual({ id: "1" });
+            });
+        });
+        describe("with TDocument generic", () => {
+            it("types document correctly", () => {
+                const row = {
+                    id: "1",
+                    score: 0.9,
+                    title: "Hello",
+                    views: 100,
+                };
+                const result = SEARCH_HIT.decode(row, "docs");
+                // TypeScript should allow accessing these fields
+                expect(result.document?.title).toBe("Hello");
+                expect(result.document?.views).toBe(100);
+            });
+        });
+    });
+    describe("encode", () => {
+        it("throws not implemented", () => {
+            expect(() => SEARCH_HIT.encode({})).toThrow("SEARCH_HIT.encode: not implemented");
+        });
+    });
+});

package/dist/pgvector/__tests__/integration/document.integration.test.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Document operations integration tests for pgvector.
+ *
+ * Tests upsert, patch, and delete operations against real PostgreSQL.
+ */
+export {};
+//# sourceMappingURL=document.integration.test.d.ts.map

package/dist/pgvector/__tests__/integration/document.integration.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"document.integration.test.d.ts","sourceRoot":"","sources":["../../../../src/pgvector/__tests__/integration/document.integration.test.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}