@kernl-sdk/pg 0.1.25 → 0.1.26

package/src/pgvector/__tests__/integration/query.integration.test.ts

@@ -1,7 +1,7 @@
 /**
  * Query behavior integration tests for pgvector.
  *
- * Tests vector search, topK behavior, offset pagination, orderBy,
+ * Tests vector search, limit behavior, offset pagination, orderBy,
  * and result structure against real PostgreSQL.
  */
 
@@ -135,7 +135,7 @@ describe.sequential("pgvector query integration tests", () => {
       // Query with basis vector 1 - should match vec-1 best
       const hits = await handle.query({
         query: [{ embedding: [1.0, 0.0, 0.0, 0.0] }],
-        topK: 10,
+        limit: 10,
       });
 
       expect(hits.length).toBeGreaterThan(0);
@@ -146,7 +146,7 @@ describe.sequential("pgvector query integration tests", () => {
       // Query with basis vector 2
       const hits = await handle.query({
         query: [{ embedding: [0.0, 1.0, 0.0, 0.0] }],
-        topK: 10,
+        limit: 10,
       });
 
       expect(hits.length).toBeGreaterThan(0);
@@ -162,7 +162,7 @@ describe.sequential("pgvector query integration tests", () => {
       // Query with mix of basis 1 and 2 - should prefer vec-5 which has [0.5, 0.5, 0, 0]
       const hits = await handle.query({
         query: [{ embedding: [0.5, 0.5, 0.0, 0.0] }],
-        topK: 10,
+        limit: 10,
       });
 
       expect(hits.length).toBeGreaterThan(0);
@@ -172,7 +172,7 @@ describe.sequential("pgvector query integration tests", () => {
     it("returns high similarity score for exact match", async () => {
       const hits = await handle.query({
         query: [{ embedding: [1.0, 0.0, 0.0, 0.0] }],
-        topK: 1,
+        limit: 1,
       });
 
       // Cosine similarity of identical vectors should be very close to 1
@@ -182,7 +182,7 @@ describe.sequential("pgvector query integration tests", () => {
     it("returns lower similarity for orthogonal vectors", async () => {
       const hits = await handle.query({
         query: [{ embedding: [1.0, 0.0, 0.0, 0.0] }],
-        topK: 10,
+        limit: 10,
       });
 
       // Find vec-4 which is orthogonal to query
@@ -196,7 +196,7 @@ describe.sequential("pgvector query integration tests", () => {
       // Already normalized
       const hits = await handle.query({
         query: [{ embedding: [0.707, 0.707, 0.0, 0.0] }],
-        topK: 3,
+        limit: 3,
       });
 
       // Should still find vec-5 as best match
@@ -207,7 +207,7 @@ describe.sequential("pgvector query integration tests", () => {
       // Not normalized (should still work with cosine similarity)
       const hits = await handle.query({
         query: [{ embedding: [2.0, 2.0, 0.0, 0.0] }],
-        topK: 3,
+        limit: 3,
       });
 
       // Should still find vec-5 as best match
@@ -216,42 +216,42 @@ describe.sequential("pgvector query integration tests", () => {
   });
 
   // ============================================================
-  // TOPK BEHAVIOR
+  // LIMIT BEHAVIOR
   // ============================================================
 
-  describe("topK behavior", () => {
-    it("topK smaller than doc count returns exactly topK", async () => {
+  describe("limit behavior", () => {
+    it("limit smaller than doc count returns exactly limit", async () => {
       const hits = await handle.query({
         query: [{ embedding: [0.5, 0.5, 0.5, 0.5] }],
-        topK: 3,
+        limit: 3,
       });
 
       expect(hits.length).toBe(3);
     });
 
-    it("topK larger than doc count returns all docs", async () => {
+    it("limit larger than doc count returns all docs", async () => {
       const hits = await handle.query({
         query: [{ embedding: [0.5, 0.5, 0.5, 0.5] }],
-        topK: 100,
+        limit: 100,
       });
 
       expect(hits.length).toBe(6);
     });
 
-    it("topK of 1 returns single best match", async () => {
+    it("limit of 1 returns single best match", async () => {
       const hits = await handle.query({
         query: [{ embedding: [1.0, 0.0, 0.0, 0.0] }],
-        topK: 1,
+        limit: 1,
       });
 
       expect(hits.length).toBe(1);
       expect(hits[0].id).toBe("vec-1");
     });
 
-    it("topK with filter returns limited filtered results", async () => {
+    it("limit with filter returns limited filtered results", async () => {
       const hits = await handle.query({
         query: [{ embedding: [0.5, 0.5, 0.5, 0.5] }],
-        topK: 1,
+        limit: 1,
         filter: { category: "db" },
       });
 
@@ -259,10 +259,10 @@ describe.sequential("pgvector query integration tests", () => {
       expect(hits[0].document?.category).toBe("db");
     });
 
-    it("topK of 0 returns empty array", async () => {
+    it("limit of 0 returns empty array", async () => {
       const hits = await handle.query({
         query: [{ embedding: [0.5, 0.5, 0.5, 0.5] }],
-        topK: 0,
+        limit: 0,
       });
 
       expect(hits.length).toBe(0);
@@ -278,13 +278,13 @@ describe.sequential("pgvector query integration tests", () => {
       // Get all results
       const allHits = await handle.query({
         query: [{ embedding: [0.5, 0.5, 0.5, 0.5] }],
-        topK: 10,
+        limit: 10,
       });
 
       // Get results with offset
       const offsetHits = await handle.query({
         query: [{ embedding: [0.5, 0.5, 0.5, 0.5] }],
-        topK: 10,
+        limit: 10,
         offset: 2,
       });
 
@@ -292,10 +292,10 @@ describe.sequential("pgvector query integration tests", () => {
       expect(offsetHits[0].id).toBe(allHits[2].id);
     });
 
-    it("offset with topK limits correctly", async () => {
+    it("offset with limit limits correctly", async () => {
       const hits = await handle.query({
         query: [{ embedding: [0.5, 0.5, 0.5, 0.5] }],
-        topK: 2,
+        limit: 2,
         offset: 2,
       });
 
@@ -305,7 +305,7 @@ describe.sequential("pgvector query integration tests", () => {
     it("offset beyond result count returns empty", async () => {
       const hits = await handle.query({
         query: [{ embedding: [0.5, 0.5, 0.5, 0.5] }],
-        topK: 10,
+        limit: 10,
         offset: 100,
       });
 
@@ -316,21 +316,21 @@ describe.sequential("pgvector query integration tests", () => {
       // Page 1
       const page1 = await handle.query({
         query: [{ embedding: [0.5, 0.5, 0.5, 0.5] }],
-        topK: 2,
+        limit: 2,
         offset: 0,
       });
 
       // Page 2
       const page2 = await handle.query({
         query: [{ embedding: [0.5, 0.5, 0.5, 0.5] }],
-        topK: 2,
+        limit: 2,
         offset: 2,
       });
 
       // Page 3
       const page3 = await handle.query({
         query: [{ embedding: [0.5, 0.5, 0.5, 0.5] }],
-        topK: 2,
+        limit: 2,
         offset: 4,
       });
 
@@ -348,13 +348,13 @@ describe.sequential("pgvector query integration tests", () => {
       // 2 docs in "ml" category
       const allMl = await handle.query({
         query: [{ embedding: [0.5, 0.5, 0.5, 0.5] }],
-        topK: 10,
+        limit: 10,
         filter: { category: "ml" },
       });
 
       const offsetMl = await handle.query({
         query: [{ embedding: [0.5, 0.5, 0.5, 0.5] }],
-        topK: 10,
+        limit: 10,
         offset: 1,
         filter: { category: "ml" },
       });
@@ -373,7 +373,7 @@ describe.sequential("pgvector query integration tests", () => {
     it("orders by integer field ascending", async () => {
       const hits = await handle.query({
         orderBy: { field: "priority", direction: "asc" },
-        topK: 10,
+        limit: 10,
       });
 
       expect(hits.length).toBe(6);
@@ -391,7 +391,7 @@ describe.sequential("pgvector query integration tests", () => {
     it("orders by integer field descending", async () => {
       const hits = await handle.query({
         orderBy: { field: "priority", direction: "desc" },
-        topK: 10,
+        limit: 10,
       });
 
       expect(hits[0].document?.priority).toBe(6);
@@ -402,7 +402,7 @@ describe.sequential("pgvector query integration tests", () => {
       // Note: We can still order by the "score" field even though it's excluded from the result
       const hits = await handle.query({
         orderBy: { field: "priority", direction: "desc" },
-        topK: 10,
+        limit: 10,
       });
 
       // Verify descending order by priority
@@ -416,7 +416,7 @@ describe.sequential("pgvector query integration tests", () => {
     it("orders by string field", async () => {
       const hits = await handle.query({
         orderBy: { field: "title", direction: "asc" },
-        topK: 10,
+        limit: 10,
       });
 
       // Verify alphabetical order
@@ -431,7 +431,7 @@ describe.sequential("pgvector query integration tests", () => {
       const hits = await handle.query({
         filter: { category: "ml" },
         orderBy: { field: "priority", direction: "desc" },
-        topK: 10,
+        limit: 10,
       });
 
       expect(hits.length).toBe(2);
@@ -439,10 +439,10 @@ describe.sequential("pgvector query integration tests", () => {
       expect(hits[1].document?.priority).toBe(1);
     });
 
-    it("orderBy with topK limits after ordering", async () => {
+    it("orderBy with limit limits after ordering", async () => {
       const hits = await handle.query({
         orderBy: { field: "priority", direction: "asc" },
-        topK: 3,
+        limit: 3,
       });
 
       expect(hits.length).toBe(3);
@@ -454,7 +454,7 @@ describe.sequential("pgvector query integration tests", () => {
     it("orderBy with offset", async () => {
       const hits = await handle.query({
         orderBy: { field: "priority", direction: "asc" },
-        topK: 2,
+        limit: 2,
         offset: 2,
       });
 
@@ -472,7 +472,7 @@ describe.sequential("pgvector query integration tests", () => {
     it("filter-only query returns all matching docs", async () => {
       const hits = await handle.query({
         filter: { category: "db" },
-        topK: 10,
+        limit: 10,
       });
 
       expect(hits.length).toBe(2);
@@ -484,7 +484,7 @@ describe.sequential("pgvector query integration tests", () => {
     it("empty query with orderBy returns ordered docs", async () => {
       const hits = await handle.query({
         orderBy: { field: "priority", direction: "asc" },
-        topK: 10,
+        limit: 10,
       });
 
       expect(hits.length).toBe(6);
@@ -495,7 +495,7 @@ describe.sequential("pgvector query integration tests", () => {
       const hits = await handle.query({
         filter: { category: "search" },
         orderBy: { field: "priority", direction: "desc" },
-        topK: 10,
+        limit: 10,
       });
 
       expect(hits.length).toBe(2);
@@ -513,7 +513,7 @@ describe.sequential("pgvector query integration tests", () => {
     it("results have required fields", async () => {
       const hits = await handle.query({
         query: [{ embedding: [1.0, 0.0, 0.0, 0.0] }],
-        topK: 1,
+        limit: 1,
       });
 
       expect(hits.length).toBe(1);
@@ -527,7 +527,7 @@ describe.sequential("pgvector query integration tests", () => {
     it("score is a valid number", async () => {
       const hits = await handle.query({
         query: [{ embedding: [1.0, 0.0, 0.0, 0.0] }],
-        topK: 5,
+        limit: 5,
       });
 
       for (const hit of hits) {
@@ -539,7 +539,7 @@ describe.sequential("pgvector query integration tests", () => {
     it("document fields are included by default", async () => {
       const hits = await handle.query({
         query: [{ embedding: [1.0, 0.0, 0.0, 0.0] }],
-        topK: 1,
+        limit: 1,
       });
 
       expect(hits[0].document).toBeDefined();
@@ -556,7 +556,7 @@ describe.sequential("pgvector query integration tests", () => {
     it("index field matches query index", async () => {
       const hits = await handle.query({
         query: [{ embedding: [1.0, 0.0, 0.0, 0.0] }],
-        topK: 5,
+        limit: 5,
       });
 
       for (const hit of hits) {
@@ -574,7 +574,7 @@ describe.sequential("pgvector query integration tests", () => {
       const hits = await handle.query({
         query: [{ embedding: [0.5, 0.5, 0.5, 0.5] }],
         filter: { category: "nonexistent" },
-        topK: 10,
+        limit: 10,
       });
 
       expect(hits).toEqual([]);
@@ -583,17 +583,17 @@ describe.sequential("pgvector query integration tests", () => {
     it("offset beyond result count returns empty array", async () => {
       const hits = await handle.query({
         query: [{ embedding: [0.5, 0.5, 0.5, 0.5] }],
-        topK: 10,
+        limit: 10,
         offset: 1000,
       });
 
       expect(hits).toEqual([]);
     });
 
-    it("topK 0 returns empty array", async () => {
+    it("limit 0 returns empty array", async () => {
       const hits = await handle.query({
         query: [{ embedding: [0.5, 0.5, 0.5, 0.5] }],
-        topK: 0,
+        limit: 0,
       });
 
       expect(hits).toEqual([]);
@@ -625,7 +625,7 @@ describe.sequential("pgvector query integration tests", () => {
 
       const hits = await eucHandle.query({
         query: [{ embedding: [1, 0, 0, 0] }],
-        topK: 3,
+        limit: 3,
       });
 
       expect(hits[0].id).toBe("e1"); // Exact match
@@ -656,7 +656,7 @@ describe.sequential("pgvector query integration tests", () => {
 
       const hits = await dotHandle.query({
         query: [{ embedding: [1, 1, 0, 0] }],
-        topK: 3,
+        limit: 3,
       });
 
       // Dot product: d1=1, d2=1, d3=1

package/src/pgvector/__tests__/search.test.ts

@@ -210,7 +210,7 @@ describe.sequential("PGSearchIndex", () => {
 
       const results = await handle.query({
         query: [{ embedding: [0.1, 0.2, 0.3] }],
-        topK: 1,
+        limit: 1,
       });
 
       expect(results).toHaveLength(1);

package/src/pgvector/sql/__tests__/limit.test.ts

@@ -5,7 +5,7 @@ describe("SQL_LIMIT", () => {
   describe("encode", () => {
     it("builds LIMIT clause", () => {
       const result = SQL_LIMIT.encode({
-        topK: 10,
+        limit: 10,
         offset: 0,
         startIdx: 1,
       });
@@ -15,7 +15,7 @@ describe("SQL_LIMIT", () => {
 
     it("respects startIdx for parameter numbering", () => {
       const result = SQL_LIMIT.encode({
-        topK: 10,
+        limit: 10,
         offset: 0,
         startIdx: 5,
       });
@@ -25,7 +25,7 @@ describe("SQL_LIMIT", () => {
 
     it("includes OFFSET when offset > 0", () => {
       const result = SQL_LIMIT.encode({
-        topK: 10,
+        limit: 10,
         offset: 20,
         startIdx: 1,
       });
@@ -35,7 +35,7 @@ describe("SQL_LIMIT", () => {
 
     it("skips OFFSET when offset is 0", () => {
       const result = SQL_LIMIT.encode({
-        topK: 25,
+        limit: 25,
         offset: 0,
         startIdx: 3,
       });
@@ -46,7 +46,7 @@ describe("SQL_LIMIT", () => {
     it("handles pagination correctly", () => {
       // Page 1: offset 0
       const page1 = SQL_LIMIT.encode({
-        topK: 20,
+        limit: 20,
         offset: 0,
         startIdx: 1,
       });
@@ -55,7 +55,7 @@ describe("SQL_LIMIT", () => {
 
       // Page 2: offset 20
       const page2 = SQL_LIMIT.encode({
-        topK: 20,
+        limit: 20,
         offset: 20,
         startIdx: 1,
       });
@@ -64,7 +64,7 @@ describe("SQL_LIMIT", () => {
 
       // Page 3: offset 40
       const page3 = SQL_LIMIT.encode({
-        topK: 20,
+        limit: 20,
         offset: 40,
         startIdx: 1,
       });
@@ -76,7 +76,7 @@ describe("SQL_LIMIT", () => {
       // Simulating: SELECT uses $1, WHERE uses $2-$4
       // LIMIT should start at $5
       const result = SQL_LIMIT.encode({
-        topK: 10,
+        limit: 10,
         offset: 50,
         startIdx: 5,
       });
@@ -85,9 +85,9 @@ describe("SQL_LIMIT", () => {
     });
 
     describe("edge values", () => {
-      it("handles topK: 0", () => {
+      it("handles limit: 0", () => {
         const result = SQL_LIMIT.encode({
-          topK: 0,
+          limit: 0,
           offset: 0,
           startIdx: 1,
         });
@@ -96,9 +96,9 @@ describe("SQL_LIMIT", () => {
         expect(result.params).toEqual([0]);
       });
 
-      it("handles topK: 1", () => {
+      it("handles limit: 1", () => {
         const result = SQL_LIMIT.encode({
-          topK: 1,
+          limit: 1,
           offset: 0,
           startIdx: 1,
         });
@@ -106,9 +106,9 @@ describe("SQL_LIMIT", () => {
         expect(result.params).toEqual([1]);
       });
 
-      it("handles very large topK", () => {
+      it("handles very large limit", () => {
         const result = SQL_LIMIT.encode({
-          topK: 1000000,
+          limit: 1000000,
           offset: 0,
           startIdx: 1,
         });
@@ -118,7 +118,7 @@ describe("SQL_LIMIT", () => {
 
       it("handles very large offset", () => {
         const result = SQL_LIMIT.encode({
-          topK: 10,
+          limit: 10,
           offset: 999999,
           startIdx: 1,
         });
@@ -128,7 +128,7 @@ describe("SQL_LIMIT", () => {
 
       it("handles very large startIdx", () => {
         const result = SQL_LIMIT.encode({
-          topK: 10,
+          limit: 10,
           offset: 20,
           startIdx: 50,
         });
@@ -136,9 +136,9 @@ describe("SQL_LIMIT", () => {
         expect(result.params).toEqual([10, 20]);
       });
 
-      it("handles startIdx: 1 with both topK and offset", () => {
+      it("handles startIdx: 1 with both limit and offset", () => {
         const result = SQL_LIMIT.encode({
-          topK: 25,
+          limit: 25,
           offset: 100,
           startIdx: 1,
         });
@@ -150,7 +150,7 @@ describe("SQL_LIMIT", () => {
     describe("offset boundary", () => {
       it("includes OFFSET when offset is exactly 1", () => {
         const result = SQL_LIMIT.encode({
-          topK: 10,
+          limit: 10,
           offset: 1,
           startIdx: 1,
         });
@@ -160,7 +160,7 @@ describe("SQL_LIMIT", () => {
 
       it("does not include OFFSET when offset is exactly 0", () => {
         const result = SQL_LIMIT.encode({
-          topK: 10,
+          limit: 10,
           offset: 0,
           startIdx: 1,
         });

package/src/pgvector/sql/__tests__/query.test.ts

@@ -27,7 +27,7 @@ describe("sqlize", () => {
       schema: "public",
       table: "docs",
     });
-    expect(result.limit).toEqual({ topK: 10, offset: 0 });
+    expect(result.limit).toEqual({ limit: 10, offset: 0 });
   });
 
   it("throws on multi-signal fusion (not supported by pgvector)", () => {
@@ -78,19 +78,19 @@ describe("sqlize", () => {
     const result = sqlize(
       {
         query: [{ embedding: [0.1, 0.2] }],
-        topK: 25,
+        limit: 25,
         offset: 50,
       },
       { pkey: "id", schema: "public", table: "docs" },
     );
 
-    expect(result.limit).toEqual({ topK: 25, offset: 50 });
+    expect(result.limit).toEqual({ limit: 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 });
+    expect(result.limit).toEqual({ limit: 10, offset: 0 });
   });
 
   it("passes binding through to all inputs", () => {
@@ -131,7 +131,7 @@ describe("sqlize", () => {
       {
         filter: { status: "active" },
         orderBy: { field: "created_at", direction: "desc" },
-        topK: 100,
+        limit: 100,
       },
       { pkey: "id", schema: "public", table: "docs" },
     );
@@ -196,7 +196,7 @@ describe("sqlize", () => {
       };
 
       const result = sqlize(
-        { filter: { status: "active" }, topK: 50 },
+        { filter: { status: "active" }, limit: 50 },
         { pkey: "id", schema: "public", table: "docs", binding },
       );
 
@@ -211,7 +211,7 @@ describe("sqlize", () => {
       const result = sqlize(
         {
           orderBy: { field: "created_at", direction: "asc" },
-          topK: 20,
+          limit: 20,
         },
         { pkey: "id", schema: "public", table: "docs" },
       );
@@ -222,7 +222,7 @@ describe("sqlize", () => {
         field: "created_at",
         direction: "asc",
       });
-      expect(result.limit).toEqual({ topK: 20, offset: 0 });
+      expect(result.limit).toEqual({ limit: 20, offset: 0 });
     });
   });
 
@@ -257,7 +257,7 @@ describe("sqlize", () => {
           query: [{ embedding: [0.1, 0.2, 0.3] }],
           filter: { status: "active", views: { $gt: 100 } },
           orderBy: { field: "created_at", direction: "desc" },
-          topK: 50,
+          limit: 50,
           offset: 25,
         },
         { pkey: "doc_id", schema: "public", table: "documents", binding },
@@ -275,7 +275,7 @@ describe("sqlize", () => {
         direction: "desc",
       });
       expect(result.order.binding).toBe(binding);
-      expect(result.limit).toEqual({ topK: 50, offset: 25 });
+      expect(result.limit).toEqual({ limit: 50, offset: 25 });
     });
 
     it("handles undefined filter", () => {
@@ -324,7 +324,7 @@ describe("full pipeline integration", () => {
       {
         query: [{ embedding: vector }],
         filter: { status: "active", views: { $gt: 100 } },
-        topK: 25,
+        limit: 25,
         offset: 50,
       },
       { pkey: "doc_id", schema: "public", table: "documents", binding },
@@ -375,7 +375,7 @@ describe("full pipeline integration", () => {
           $or: [{ featured: true }, { views: { $gte: 1000 } }],
         },
         orderBy: { field: "created_at", direction: "desc" },
-        topK: 10,
+        limit: 10,
       },
       { pkey: "id", schema: "public", table: "docs" },
     );
@@ -423,7 +423,7 @@ describe("full pipeline integration", () => {
           ],
           deleted_at: null,
         },
-        topK: 5,
+        limit: 5,
       },
       { pkey: "id", schema: "public", table: "docs" },
     );
@@ -465,7 +465,7 @@ describe("full pipeline integration", () => {
     };
 
     const query = sqlize(
-      { query: [{ embedding: vector }], topK: 10 },
+      { query: [{ embedding: vector }], limit: 10 },
       { pkey: "id", schema: "public", table: "docs", binding },
     );
 
@@ -496,7 +496,7 @@ describe("full pipeline integration", () => {
     };
 
     const query = sqlize(
-      { query: [{ embedding: vector }], topK: 10 },
+      { query: [{ embedding: vector }], limit: 10 },
       { pkey: "id", schema: "public", table: "docs", binding },
     );
 
@@ -518,7 +518,7 @@ describe("full pipeline integration", () => {
       {
         query: [{ embedding: [0.1, 0.2] }],
         filter: { a: 1, b: 2, c: 3 },
-        topK: 10,
+        limit: 10,
         offset: 20,
       },
       { pkey: "id", schema: "public", table: "docs" },
@@ -533,7 +533,7 @@ describe("full pipeline integration", () => {
     // Verify no gaps in indices
     // SELECT: $1 (vector)
     // WHERE: $2, $3, $4 (a, b, c)
-    // LIMIT: $5, $6 (topK, offset)
+    // LIMIT: $5, $6 (limit, offset)
 
     expect(select.params).toHaveLength(1); // $1
     expect(whereStartIdx).toBe(2);