@fragno-dev/db 0.1.12 → 0.1.13

package/src/adapters/drizzle/drizzle-adapter-pglite.test.ts

@@ -1,10 +1,10 @@
 import { drizzle } from "drizzle-orm/pglite";
 import { DrizzleAdapter } from "./drizzle-adapter";
-import { beforeAll, describe, expect, expectTypeOf, it } from "vitest";
+import { assert, beforeAll, describe, expect, expectTypeOf, it } from "vitest";
 import { column, idColumn, referenceColumn, schema } from "../../schema/create";
 import type { DBType } from "./shared";
 import { createRequire } from "node:module";
-import { encodeCursor } from "../../query/cursor";
+import { Cursor } from "../../query/cursor";
 import type { DrizzleCompiledQuery } from "./drizzle-uow-compiler";
 import { writeAndLoadSchema } from "./test-utils";
 
@@ -245,10 +245,12 @@ describe("DrizzleAdapter PGLite", () => {
 
     // Create cursor from last item of first page
     const lastItem = firstPage[firstPage.length - 1]!;
-    const cursor = encodeCursor({
+    const cursor = new Cursor({
+      indexName: "name_idx",
+      orderDirection: "asc",
+      pageSize: 2,
       indexValues: { name: lastItem.name },
-      direction: "forward",
-    });
+    }).encode();
 
     // Fetch next page using cursor
     const [secondPage] = await queryEngine
@@ -729,4 +731,69 @@ describe("DrizzleAdapter PGLite", () => {
       "This post was created in the same transaction as the user",
     ]);
   });
+
+  it("should support cursor-based pagination with findWithCursor()", async () => {
+    const queryEngine = adapter.createQueryEngine(testSchema, "namespace");
+
+    // Create multiple users for pagination testing
+    for (let i = 1; i <= 25; i++) {
+      await queryEngine.create("users", {
+        name: `Cursor User ${i.toString().padStart(2, "0")}`,
+        age: 20 + i,
+      });
+    }
+
+    // Fetch first page with cursor
+    const firstPage = await queryEngine.findWithCursor("users", (b) =>
+      b.whereIndex("name_idx").orderByIndex("name_idx", "asc").pageSize(10),
+    );
+
+    // Check structure
+    expect(firstPage).toHaveProperty("items");
+    expect(firstPage).toHaveProperty("cursor");
+    expect(Array.isArray(firstPage.items)).toBe(true);
+    expect(firstPage.items.length).toBeGreaterThan(0);
+    expect(firstPage.items.length).toBeLessThanOrEqual(10);
+
+    assert(firstPage.cursor instanceof Cursor);
+    expect(firstPage.items).toHaveLength(10);
+    expect(firstPage.cursor).toBeInstanceOf(Cursor);
+
+    // Fetch second page using cursor
+    const secondPage = await queryEngine.findWithCursor("users", (b) =>
+      b
+        .whereIndex("name_idx")
+        .after(firstPage.cursor!)
+        .orderByIndex("name_idx", "asc")
+        .pageSize(10),
+    );
+
+    expect(secondPage.items.length).toBeGreaterThan(0);
+    expect(secondPage.items.length).toBeLessThanOrEqual(10);
+
+    // Verify no overlap - first item of second page should come after last item of first page
+    const firstPageLastName = firstPage.items[firstPage.items.length - 1].name;
+    const secondPageFirstName = secondPage.items[0].name;
+    expect(secondPageFirstName > firstPageLastName).toBe(true);
+  });
+
+  it("should support findWithCursor() in Unit of Work", async () => {
+    const queryEngine = adapter.createQueryEngine(testSchema, "namespace");
+
+    // Use findWithCursor in UOW
+    const uow = queryEngine
+      .createUnitOfWork("cursor-test")
+      .findWithCursor("users", (b) =>
+        b.whereIndex("name_idx").orderByIndex("name_idx", "asc").pageSize(5),
+      );
+
+    const [result] = await uow.executeRetrieve();
+
+    // Verify result structure
+    expect(result).toHaveProperty("items");
+    expect(result).toHaveProperty("cursor");
+    expect(Array.isArray(result.items)).toBe(true);
+    expect(result.items).toHaveLength(5);
+    expect(result.cursor).toBeInstanceOf(Cursor);
+  });
 });

package/src/adapters/drizzle/drizzle-adapter-sqlite.test.ts

@@ -6,7 +6,7 @@ import { column, idColumn, referenceColumn, schema } from "../../schema/create";
 import type { DBType } from "./shared";
 import { createRequire } from "node:module";
 import { writeAndLoadSchema } from "./test-utils";
-import { encodeCursor } from "../../query/cursor";
+import { Cursor } from "../../query/cursor";
 
 // Import drizzle-kit for migrations
 const require = createRequire(import.meta.url);
@@ -272,10 +272,12 @@ describe("DrizzleAdapter SQLite", () => {
 
     // Create cursor from last item of first page
     const lastItem = firstPage[firstPage.length - 1]!;
-    const cursor = encodeCursor({
+    const cursor = new Cursor({
+      indexName: "name_idx",
+      orderDirection: "asc",
+      pageSize: 2,
       indexValues: { name: lastItem.name },
-      direction: "forward",
-    });
+    }).encode();
 
     // Fetch next page using cursor
     const [secondPage] = await queryEngine

package/src/adapters/drizzle/drizzle-query.ts

@@ -8,6 +8,7 @@ import { parseDrizzle, type DrizzleResult, type TableNameMapper, type DBType } f
 import { createDrizzleUOWDecoder } from "./drizzle-uow-decoder";
 import type { ConnectionPool } from "../../shared/connection-pool";
 import type { TableToUpdateValues } from "../../query/query";
+import type { CursorResult } from "../../query/cursor";
 
 /**
  * Configuration options for creating a Drizzle Unit of Work
@@ -153,6 +154,14 @@ export function fromDrizzle<T extends AnySchema>(
       return result;
     },
 
+    async findWithCursor(tableName, builderFn) {
+      // Safe: builderFn returns a FindBuilder, which matches UnitOfWork signature
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const uow = createUOW({ config: uowConfig }).findWithCursor(tableName, builderFn as any);
+      const [result] = await uow.executeRetrieve();
+      return result as CursorResult<unknown>;
+    },
+
     async findFirst(tableName, builderFn) {
       const uow = createUOW({ config: uowConfig });
       if (builderFn) {

package/src/adapters/drizzle/drizzle-uow-compiler.test.ts

@@ -14,6 +14,7 @@ import { UnitOfWork, type UOWDecoder } from "../../query/unit-of-work";
 import { writeAndLoadSchema } from "./test-utils";
 import type { ConnectionPool } from "../../shared/connection-pool";
 import { createDrizzleConnectionPool } from "./drizzle-connection-pool";
+import { Cursor } from "../../query/cursor";
 
 /**
  * Integration tests for Drizzle UOW compiler and executor.
@@ -233,7 +234,12 @@ describe("drizzle-uow-compiler", () => {
 
     it("should compile find operation with cursor pagination using after", () => {
       const uow = createTestUOW();
-      const cursor = "eyJpbmRleFZhbHVlcyI6eyJuYW1lIjoiQWxpY2UifSwiZGlyZWN0aW9uIjoiZm9yd2FyZCJ9"; // {"indexValues":{"name":"Alice"},"direction":"forward"}
+      const cursor = new Cursor({
+        indexName: "idx_name",
+        orderDirection: "asc",
+        pageSize: 10,
+        indexValues: { name: "Alice" },
+      });
       uow.find("users", (b) =>
         b.whereIndex("idx_name").orderByIndex("idx_name", "asc").after(cursor).pageSize(10),
       );
@@ -250,7 +256,12 @@ describe("drizzle-uow-compiler", () => {
 
     it("should compile find operation with cursor pagination using before", () => {
       const uow = createTestUOW();
-      const cursor = "eyJpbmRleFZhbHVlcyI6eyJuYW1lIjoiQm9iIn0sImRpcmVjdGlvbiI6ImJhY2t3YXJkIn0="; // {"indexValues":{"name":"Bob"},"direction":"backward"}
+      const cursor = new Cursor({
+        indexName: "idx_name",
+        orderDirection: "desc",
+        pageSize: 10,
+        indexValues: { name: "Bob" },
+      });
       uow.find("users", (b) =>
         b.whereIndex("idx_name").orderByIndex("idx_name", "desc").before(cursor).pageSize(10),
       );
@@ -267,7 +278,12 @@ describe("drizzle-uow-compiler", () => {
 
     it("should compile find operation with cursor pagination and additional where conditions", () => {
       const uow = createTestUOW();
-      const cursor = "eyJpbmRleFZhbHVlcyI6eyJuYW1lIjoiQWxpY2UifSwiZGlyZWN0aW9uIjoiZm9yd2FyZCJ9";
+      const cursor = new Cursor({
+        indexName: "idx_name",
+        orderDirection: "asc",
+        pageSize: 5,
+        indexValues: { name: "Alice" },
+      });
       uow.find("users", (b) =>
         b
           .whereIndex("idx_name", (eb) => eb("name", "starts with", "John"))

package/src/adapters/drizzle/drizzle-uow-compiler.ts

@@ -423,8 +423,9 @@ export function createDrizzleUOWCompiler<TSchema extends AnySchema>(
           // Add cursor-based pagination conditions
           if ((after || before) && indexColumns.length > 0) {
             const cursor = after || before;
-            const cursorData = decodeCursor(cursor!);
-            const serializedValues = serializeCursorValues(cursorData, indexColumns, provider);
+            // Decode cursor if it's a string, otherwise use it as-is
+            const cursorObj = typeof cursor === "string" ? decodeCursor(cursor!) : cursor!;
+            const serializedValues = serializeCursorValues(cursorObj, indexColumns, provider);
 
             // Build tuple comparison for cursor pagination
             // For "after" with "asc": (col1, col2, ...) > (val1, val2, ...)

package/src/adapters/drizzle/drizzle-uow-decoder.ts

@@ -4,6 +4,7 @@ import type { RetrievalOperation, UOWDecoder } from "../../query/unit-of-work";
 import { decodeResult } from "../../query/result-transform";
 import { getOrderedJoinColumns } from "./join-column-utils";
 import type { DrizzleResult } from "./shared";
+import { createCursorFromRecord, Cursor, type CursorResult } from "../../query/cursor";
 
 /**
  * Join information with nested join support
@@ -173,10 +174,48 @@ export function createDrizzleUOWDecoder<TSchema extends AnySchema>(
       }
 
       // Handle find operations - decode each row
-      return result.rows.map((row) => {
+      const decodedRows = result.rows.map((row) => {
         const transformedRow = transformJoinArraysToObjects(row, op, provider);
         return decodeResult(transformedRow, op.table, provider);
       });
+
+      // If cursor generation is requested, wrap in CursorResult
+      if (op.withCursor) {
+        let cursor: Cursor | undefined;
+
+        // Generate cursor from last item if results exist
+        if (decodedRows.length > 0 && op.options.orderByIndex && op.options.pageSize) {
+          const lastItem = decodedRows[decodedRows.length - 1];
+          const indexName = op.options.orderByIndex.indexName;
+
+          // Get index columns
+          let indexColumns;
+          if (indexName === "_primary") {
+            indexColumns = [op.table.getIdColumn()];
+          } else {
+            const index = op.table.indexes[indexName];
+            if (index) {
+              indexColumns = index.columns;
+            }
+          }
+
+          if (indexColumns && lastItem) {
+            cursor = createCursorFromRecord(lastItem as Record<string, unknown>, indexColumns, {
+              indexName: op.options.orderByIndex.indexName,
+              orderDirection: op.options.orderByIndex.direction,
+              pageSize: op.options.pageSize,
+            });
+          }
+        }
+
+        const cursorResult: CursorResult<unknown> = {
+          items: decodedRows,
+          cursor,
+        };
+        return cursorResult;
+      }
+
+      return decodedRows;
     });
   };
 }

package/src/adapters/kysely/kysely-adapter-pglite.test.ts

@@ -10,7 +10,7 @@ import {
   type FragnoId,
   type FragnoReference,
 } from "../../schema/create";
-import { encodeCursor } from "../../query/cursor";
+import { Cursor } from "../../query/cursor";
 
 describe("KyselyAdapter PGLite", () => {
   const testSchema = schema((s) => {
@@ -396,10 +396,12 @@ describe("KyselyAdapter PGLite", () => {
 
     // Get cursor for pagination (using the last item from page 1)
     const lastItem = page1Results[page1Results.length - 1]!;
-    const cursor = encodeCursor({
+    const cursor = new Cursor({
+      indexName: "name_idx",
+      orderDirection: "asc",
+      pageSize: 2,
       indexValues: { name: lastItem.name },
-      direction: "forward",
-    });
+    }).encode();
 
     // Get page 2 using the cursor
     const page2 = queryEngine
@@ -872,4 +874,100 @@ describe("KyselyAdapter PGLite", () => {
     // Verify the foreign key relationship is correct
     expect(post?.user_id.internalId).toBe(user?.id.internalId);
   });
+
+  it("should support cursor-based pagination with findWithCursor()", async () => {
+    const queryEngine = adapter.createQueryEngine(testSchema, "test");
+
+    // Create multiple users for pagination testing with unique prefix
+    const prefix = "CursorPagTest";
+    const userIds: FragnoId[] = [];
+    for (let i = 1; i <= 25; i++) {
+      const userId = await queryEngine.create("users", {
+        name: `${prefix} ${i.toString().padStart(2, "0")}`,
+        age: 20 + i,
+      });
+      userIds.push(userId);
+    }
+
+    // Fetch first page with cursor (filter by prefix to avoid other test data)
+    const firstPage = await queryEngine.findWithCursor("users", (b) =>
+      b.whereIndex("name_idx").orderByIndex("name_idx", "asc").pageSize(10),
+    );
+
+    // Check structure
+    expect(firstPage).toHaveProperty("items");
+    expect(firstPage).toHaveProperty("cursor");
+    expect(Array.isArray(firstPage.items)).toBe(true);
+    expect(firstPage.items.length).toBeGreaterThan(0);
+
+    assert(firstPage.cursor instanceof Cursor);
+
+    // Fetch second page using cursor
+    const secondPage = await queryEngine.findWithCursor("users", (b) =>
+      b
+        .whereIndex("name_idx")
+        .after(firstPage.cursor!)
+        .orderByIndex("name_idx", "asc")
+        .pageSize(10),
+    );
+
+    expect(secondPage.items.length).toBeGreaterThan(0);
+
+    // Verify no overlap - all names in second page should be different from first page
+    const firstPageNames = new Set(firstPage.items.map((u) => u.name));
+    const secondPageNames = secondPage.items.map((u) => u.name);
+
+    for (const name of secondPageNames) {
+      expect(firstPageNames.has(name)).toBe(false);
+    }
+
+    // Verify ordering - last item of first page should come before first item of second page
+    const firstPageLast = firstPage.items[firstPage.items.length - 1].name;
+    const secondPageFirst = secondPage.items[0].name;
+    expect(firstPageLast < secondPageFirst).toBe(true);
+
+    // Verify our test data is present
+    const testUsers = await queryEngine.find("users", (b) =>
+      b.whereIndex("name_idx").pageSize(100),
+    );
+    const testUserNames = testUsers.filter((u) => u.name.startsWith(prefix)).map((u) => u.name);
+    expect(testUserNames).toHaveLength(25);
+  });
+
+  it("should support findWithCursor() in Unit of Work", async () => {
+    const queryEngine = adapter.createQueryEngine(testSchema, "test");
+
+    // Create test users if not already present
+    const existingUsers = await queryEngine.find("users", (b) =>
+      b.whereIndex("name_idx").pageSize(1),
+    );
+
+    if (existingUsers.length === 0) {
+      for (let i = 1; i <= 5; i++) {
+        await queryEngine.create("users", {
+          name: `UOW Cursor User ${i}`,
+          age: 30 + i,
+        });
+      }
+    }
+
+    // Use findWithCursor in UOW
+    const uow = queryEngine
+      .createUnitOfWork("cursor-test")
+      .findWithCursor("users", (b) =>
+        b.whereIndex("name_idx").orderByIndex("name_idx", "asc").pageSize(3),
+      );
+
+    const [result] = await uow.executeRetrieve();
+
+    // Verify result structure
+    expect(result).toHaveProperty("items");
+    expect(result).toHaveProperty("cursor");
+    expect(Array.isArray(result.items)).toBe(true);
+    expect(result.items.length).toBeGreaterThan(0);
+
+    if (result.items.length === 3) {
+      expect(result.cursor).toBeInstanceOf(Cursor);
+    }
+  });
 });

package/src/adapters/kysely/kysely-query.ts

@@ -14,6 +14,7 @@ import type { CompiledQuery, Kysely } from "kysely";
 import type { TableNameMapper } from "./kysely-shared";
 import type { ConnectionPool } from "../../shared/connection-pool";
 import type { SQLProvider } from "../../shared/providers";
+import { createCursorFromRecord, Cursor, type CursorResult } from "../../query/cursor";
 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 type KyselyAny = Kysely<any>;
@@ -159,7 +160,45 @@ export function fromKysely<T extends AnySchema>(
 
         // Each result is an array of rows - decode each row
         const rowArray = rows as Record<string, unknown>[];
-        return rowArray.map((row) => decodeResult(row, op.table, provider));
+        const decodedRows = rowArray.map((row) => decodeResult(row, op.table, provider));
+
+        // If cursor generation is requested, wrap in CursorResult
+        if (op.withCursor) {
+          let cursor: Cursor | undefined;
+
+          // Generate cursor from last item if results exist
+          if (decodedRows.length > 0 && op.options.orderByIndex && op.options.pageSize) {
+            const lastItem = decodedRows[decodedRows.length - 1];
+            const indexName = op.options.orderByIndex.indexName;
+
+            // Get index columns
+            let indexColumns;
+            if (indexName === "_primary") {
+              indexColumns = [op.table.getIdColumn()];
+            } else {
+              const index = op.table.indexes[indexName];
+              if (index) {
+                indexColumns = index.columns;
+              }
+            }
+
+            if (indexColumns && lastItem) {
+              cursor = createCursorFromRecord(lastItem as Record<string, unknown>, indexColumns, {
+                indexName: op.options.orderByIndex.indexName,
+                orderDirection: op.options.orderByIndex.direction,
+                pageSize: op.options.pageSize,
+              });
+            }
+          }
+
+          const result: CursorResult<unknown> = {
+            items: decodedRows,
+            cursor,
+          };
+          return result;
+        }
+
+        return decodedRows;
       });
     };
 
@@ -193,6 +232,16 @@ export function fromKysely<T extends AnySchema>(
       return result ?? [];
     },
 
+    async findWithCursor(tableName, builderFn) {
+      // Safe: builderFn returns a FindBuilder, which matches UnitOfWork signature
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const uow = createUOW({ config: uowConfig }).findWithCursor(tableName, builderFn as any);
+      // executeRetrieve returns an array of results (one per find operation)
+      // Since we only have one findWithCursor, unwrap the first result
+      const [result] = await uow.executeRetrieve();
+      return result as CursorResult<unknown>;
+    },
+
     async findFirst(tableName, builderFn) {
       const uow = createUOW({ config: uowConfig });
       if (builderFn) {

package/src/adapters/kysely/kysely-uow-compiler.test.ts

@@ -5,6 +5,7 @@ import { UnitOfWork, type UOWDecoder } from "../../query/unit-of-work";
 import { createKyselyUOWCompiler } from "./kysely-uow-compiler";
 import type { ConnectionPool } from "../../shared/connection-pool";
 import { createKyselyConnectionPool } from "./kysely-connection-pool";
+import { Cursor } from "../../query/cursor";
 
 describe("kysely-uow-compiler", () => {
   const testSchema = schema((s) => {
@@ -252,7 +253,12 @@ describe("kysely-uow-compiler", () => {
 
     it("should compile find operation with cursor pagination using after", () => {
       const uow = createTestUOW();
-      const cursor = "eyJpbmRleFZhbHVlcyI6eyJuYW1lIjoiQWxpY2UifSwiZGlyZWN0aW9uIjoiZm9yd2FyZCJ9"; // {"indexValues":{"name":"Alice"},"direction":"forward"}
+      const cursor = new Cursor({
+        indexName: "idx_name",
+        orderDirection: "asc",
+        pageSize: 10,
+        indexValues: { name: "Alice" },
+      });
       uow.find("users", (b) =>
         b.whereIndex("idx_name").orderByIndex("idx_name", "asc").after(cursor).pageSize(10),
       );
@@ -269,7 +275,12 @@ describe("kysely-uow-compiler", () => {
 
     it("should compile find operation with cursor pagination using before", () => {
       const uow = createTestUOW();
-      const cursor = "eyJpbmRleFZhbHVlcyI6eyJuYW1lIjoiQm9iIn0sImRpcmVjdGlvbiI6ImJhY2t3YXJkIn0="; // {"indexValues":{"name":"Bob"},"direction":"backward"}
+      const cursor = new Cursor({
+        indexName: "idx_name",
+        orderDirection: "desc",
+        pageSize: 10,
+        indexValues: { name: "Bob" },
+      });
       uow.find("users", (b) =>
         b.whereIndex("idx_name").orderByIndex("idx_name", "desc").before(cursor).pageSize(10),
       );
@@ -286,7 +297,12 @@ describe("kysely-uow-compiler", () => {
 
     it("should compile find operation with cursor pagination and additional where conditions", () => {
       const uow = createTestUOW();
-      const cursor = "eyJpbmRleFZhbHVlcyI6eyJuYW1lIjoiQWxpY2UifSwiZGlyZWN0aW9uIjoiZm9yd2FyZCJ9";
+      const cursor = new Cursor({
+        indexName: "idx_name",
+        orderDirection: "asc",
+        pageSize: 5,
+        indexValues: { name: "Alice" },
+      });
       uow.find("users", (b) =>
         b
           .whereIndex("idx_name", (eb) => eb("name", "starts with", "John"))

package/src/adapters/kysely/kysely-uow-compiler.ts

@@ -105,8 +105,9 @@ export function createKyselyUOWCompiler<TSchema extends AnySchema>(
 
           if ((after || before) && indexColumns.length > 0) {
             const cursor = after || before;
-            const cursorData = decodeCursor(cursor!);
-            const serializedValues = serializeCursorValues(cursorData, indexColumns, provider);
+            // Decode cursor if it's a string, otherwise use it as-is
+            const cursorObj = typeof cursor === "string" ? decodeCursor(cursor!) : cursor!;
+            const serializedValues = serializeCursorValues(cursorObj, indexColumns, provider);
 
             // Build tuple comparison for cursor pagination
             // For "after" with "asc": (col1, col2, ...) > (val1, val2, ...)

package/src/mod.ts

@@ -1,8 +1,11 @@
 import type { DatabaseAdapter } from "./adapters/adapters";
 import type { AnySchema } from "./schema/create";
 import type { AbstractQuery } from "./query/query";
+import type { CursorResult } from "./query/cursor";
+import { Cursor } from "./query/cursor";
 
-export type { DatabaseAdapter };
+export type { DatabaseAdapter, CursorResult };
+export { Cursor };
 
 export const fragnoDatabaseFakeSymbol = "$fragno-database" as const;
 export const fragnoDatabaseLibraryVersion = "0.1" as const;
@@ -129,3 +132,5 @@ export {
   type FragnoPublicConfigWithDatabase,
   type DatabaseFragmentContext,
 } from "./fragment";
+
+export { decodeCursor, type CursorData } from "./query/cursor";