@fragno-dev/db 0.2.2 → 0.4.1

package/src/query/condition-builder.ts

@@ -1,4 +1,5 @@
 import type { AnyColumn, FragnoId, IdColumn } from "../schema/create";
+import { dbInterval, dbNow, type DbInterval, type DbIntervalInput, type DbNow } from "./db-now";
 
 export type ConditionType = "compare" | "and" | "or" | "not";
 
@@ -54,6 +55,8 @@ export type ConditionBuilder<Columns extends Record<string, AnyColumn>> = {
 
   isNull: (a: keyof Columns) => Condition;
   isNotNull: (a: keyof Columns) => Condition;
+  now: () => DbNow;
+  interval: (input: DbIntervalInput) => DbInterval;
 };
 
 // replacement for `like` (Prisma doesn't support `like`)
@@ -117,6 +120,8 @@ export function createBuilder<Columns extends Record<string, AnyColumn>>(
 
   builder.isNull = (a) => builder(a, "is", null);
   builder.isNotNull = (a) => builder(a, "is not", null);
+  builder.now = () => dbNow();
+  builder.interval = (input) => dbInterval(input);
   builder.not = (condition) => {
     if (typeof condition === "boolean") {
       return !condition;
@@ -249,6 +254,8 @@ export function createIndexedBuilder<Columns extends Record<string, AnyColumn>>(
 
   builder.isNull = (a) => builder(a, "is", null);
   builder.isNotNull = (a) => builder(a, "is not", null);
+  builder.now = () => dbNow();
+  builder.interval = (input) => dbInterval(input);
   builder.not = (condition) => {
     if (typeof condition === "boolean") {
       return !condition;

package/src/query/cursor-client.test.ts

@@ -0,0 +1,70 @@
+import { beforeAll, describe, expect, it } from "vitest";
+
+import type { AnyColumn } from "../schema/create";
+import { Cursor, createCursorFromRecord, decodeCursor } from "./cursor-client";
+
+const ensureBase64Helpers = () => {
+  const g = globalThis as typeof globalThis & {
+    btoa?: (input: string) => string;
+    atob?: (input: string) => string;
+  };
+
+  if (!g.btoa) {
+    g.btoa = (input: string) => Buffer.from(input, "binary").toString("base64");
+  }
+
+  if (!g.atob) {
+    g.atob = (input: string) => Buffer.from(input, "base64").toString("binary");
+  }
+};
+
+beforeAll(() => {
+  ensureBase64Helpers();
+});
+
+describe("cursor-client", () => {
+  it("roundtrips cursor data with unicode values", () => {
+    const cursor = new Cursor({
+      indexName: "idx_created",
+      orderDirection: "asc",
+      pageSize: 25,
+      indexValues: {
+        createdAt: 1730000000000,
+        name: "München",
+      },
+    });
+
+    const encoded = cursor.encode();
+    const decoded = decodeCursor(encoded);
+
+    expect(decoded.indexName).toBe("idx_created");
+    expect(decoded.orderDirection).toBe("asc");
+    expect(decoded.pageSize).toBe(25);
+    expect(decoded.indexValues).toEqual({
+      createdAt: 1730000000000,
+      name: "München",
+    });
+  });
+
+  it("creates a cursor from a record", () => {
+    const column: AnyColumn = {
+      name: "createdAt",
+      type: "timestamp",
+      role: "regular",
+      isNullable: false,
+    } as AnyColumn;
+
+    const cursor = createCursorFromRecord({ createdAt: 123, other: "ignore" }, [column], {
+      indexName: "idx_created",
+      orderDirection: "desc",
+      pageSize: 10,
+    });
+
+    expect(cursor.indexValues).toEqual({ createdAt: 123 });
+    expect(cursor.orderDirection).toBe("desc");
+  });
+
+  it("rejects malformed cursor payloads", () => {
+    expect(() => decodeCursor("not-base64")).toThrowError(/Invalid cursor/);
+  });
+});

package/src/query/cursor-client.ts

@@ -0,0 +1,263 @@
+import type { AnyColumn } from "../schema/create";
+
+/**
+ * Cursor object containing all information needed for pagination
+ */
+export class Cursor {
+  readonly #indexName: string;
+  readonly #orderDirection: "asc" | "desc";
+  readonly #pageSize: number;
+  readonly #indexValues: Record<string, unknown>;
+
+  constructor(data: {
+    indexName: string;
+    orderDirection: "asc" | "desc";
+    pageSize: number;
+    indexValues: Record<string, unknown>;
+  }) {
+    this.#indexName = data.indexName;
+    this.#orderDirection = data.orderDirection;
+    this.#pageSize = data.pageSize;
+    this.#indexValues = data.indexValues;
+  }
+
+  /**
+   * Get the index name being used for pagination
+   */
+  get indexName(): string {
+    return this.#indexName;
+  }
+
+  /**
+   * Get the ordering direction
+   */
+  get orderDirection(): "asc" | "desc" {
+    return this.#orderDirection;
+  }
+
+  /**
+   * Get the page size
+   */
+  get pageSize(): number {
+    return this.#pageSize;
+  }
+
+  /**
+   * Get the cursor position values
+   */
+  get indexValues(): Record<string, unknown> {
+    return this.#indexValues;
+  }
+
+  /**
+   * Encode cursor to an opaque base64 string (safe to send to client)
+   */
+  encode(): string {
+    assertSerializableIndexValues(this.#indexValues);
+    const data: CursorData = {
+      v: 1,
+      indexName: this.#indexName,
+      orderDirection: this.#orderDirection,
+      pageSize: this.#pageSize,
+      indexValues: this.#indexValues,
+    };
+    return encodeCursorData(data);
+  }
+}
+
+/**
+ * Result of a cursor-based query containing items and pagination cursor
+ */
+export interface CursorResult<T> {
+  /**
+   * The query results
+   */
+  items: T[];
+  /**
+   * Cursor to fetch the next page (undefined if no more results)
+   */
+  cursor?: Cursor;
+  /**
+   * Whether there are more results available after this page
+   */
+  hasNextPage: boolean;
+}
+
+/**
+ * Cursor data structure for serialization
+ */
+export interface CursorData {
+  v: number; // version
+  indexName: string;
+  orderDirection: "asc" | "desc";
+  pageSize: number;
+  indexValues: Record<string, unknown>;
+}
+
+const getBase64Helpers = () => {
+  const { btoa, atob, TextEncoder, TextDecoder } = globalThis;
+
+  if (!btoa || !atob) {
+    throw new Error("Base64 helpers (btoa/atob) are not available in this environment.");
+  }
+
+  if (!TextEncoder || !TextDecoder) {
+    throw new Error("TextEncoder/TextDecoder are required for cursor encoding.");
+  }
+
+  const encodeBase64 = (input: string): string => {
+    const bytes = new TextEncoder().encode(input);
+    let binary = "";
+    for (const byte of bytes) {
+      binary += String.fromCharCode(byte);
+    }
+    return btoa(binary);
+  };
+
+  const decodeBase64 = (input: string): string => {
+    const binary = atob(input);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i += 1) {
+      bytes[i] = binary.charCodeAt(i);
+    }
+    return new TextDecoder().decode(bytes);
+  };
+
+  return { encodeBase64, decodeBase64 };
+};
+
+/**
+ * Encode cursor data to a base64 string (internal)
+ */
+function encodeCursorData(data: CursorData): string {
+  let json: string;
+  try {
+    json = JSON.stringify(data);
+  } catch (error) {
+    throw new Error(`Invalid cursor: ${error instanceof Error ? error.message : "malformed data"}`);
+  }
+
+  return getBase64Helpers().encodeBase64(json);
+}
+
+/**
+ * Decode a base64 cursor string back to a Cursor object
+ *
+ * @param cursor - The base64-encoded cursor string
+ * @returns Decoded Cursor object
+ * @throws Error if cursor is invalid or malformed
+ *
+ * @example
+ * ```ts
+ * const cursor = decodeCursor("eyJpbmRleFZhbHVlcyI6e30sImRpcmVjdGlvbiI6ImZvcndhcmQifQ==");
+ * ```
+ */
+export function decodeCursor(cursor: string): Cursor {
+  try {
+    const json = getBase64Helpers().decodeBase64(cursor);
+    const data = JSON.parse(json);
+    const record = data as Record<string, unknown>;
+
+    // Validate structure
+    if (
+      !isPlainObject(data) ||
+      !isPlainObject(record["indexValues"]) ||
+      typeof record["indexName"] !== "string" ||
+      record["indexName"].length === 0 ||
+      typeof record["orderDirection"] !== "string" ||
+      (record["orderDirection"] !== "asc" && record["orderDirection"] !== "desc") ||
+      typeof record["pageSize"] !== "number" ||
+      !Number.isFinite(record["pageSize"]) ||
+      !Number.isInteger(record["pageSize"]) ||
+      record["pageSize"] <= 0
+    ) {
+      throw new Error("Invalid cursor structure");
+    }
+
+    // Only support v1
+    if (typeof record["v"] !== "number") {
+      throw new Error("Unsupported cursor version: missing. Only v1 is supported.");
+    }
+    const version = record["v"];
+    if (version !== 1) {
+      throw new Error(`Unsupported cursor version: ${version}. Only v1 is supported.`);
+    }
+
+    return new Cursor({
+      indexName: record["indexName"],
+      orderDirection: record["orderDirection"],
+      pageSize: record["pageSize"],
+      indexValues: record["indexValues"],
+    });
+  } catch (error) {
+    throw new Error(`Invalid cursor: ${error instanceof Error ? error.message : "malformed data"}`);
+  }
+}
+
+/**
+ * Create a cursor from a record and pagination metadata
+ *
+ * @param record - The database record
+ * @param indexColumns - The columns that make up the index
+ * @param metadata - Pagination metadata (index name, order direction, page size)
+ * @returns Cursor object
+ *
+ * @example
+ * ```ts
+ * const cursor = createCursorFromRecord(
+ *   { id: "abc", name: "Alice", createdAt: 123 },
+ *   [table.columns.createdAt, table.columns.id],
+ *   {
+ *     indexName: "idx_created",
+ *     orderDirection: "asc",
+ *     pageSize: 10
+ *   }
+ * );
+ * ```
+ */
+export function createCursorFromRecord(
+  record: Record<string, unknown>,
+  indexColumns: AnyColumn[],
+  metadata: {
+    indexName: string;
+    orderDirection: "asc" | "desc";
+    pageSize: number;
+  },
+): Cursor {
+  const indexValues: Record<string, unknown> = {};
+
+  for (const col of indexColumns) {
+    const value = record[col.name];
+    if (value === undefined) {
+      throw new Error(`Record is missing value for index column "${col.name}".`);
+    }
+    indexValues[col.name] = value;
+  }
+
+  return new Cursor({
+    indexName: metadata.indexName,
+    orderDirection: metadata.orderDirection,
+    pageSize: metadata.pageSize,
+    indexValues,
+  });
+}
+
+const isPlainObject = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" && value !== null && !Array.isArray(value);
+
+const assertSerializableIndexValues = (values: Record<string, unknown>): void => {
+  for (const [key, value] of Object.entries(values)) {
+    if (value === undefined) {
+      throw new Error(`Cursor index value "${key}" is undefined.`);
+    }
+    if (typeof value === "number" && !Number.isFinite(value)) {
+      throw new Error(`Cursor index value "${key}" must be a finite number.`);
+    }
+    if (typeof value === "bigint") {
+      throw new Error(`Cursor index value "${key}" must not be a BigInt.`);
+    }
+    if (typeof value === "function" || typeof value === "symbol") {
+      throw new Error(`Cursor index value "${key}" is not JSON-serializable.`);
+    }
+  }
+};

package/src/query/cursor.test.ts

@@ -1,11 +1,12 @@
 import { describe, it, expect } from "vitest";
-import { decodeCursor, createCursorFromRecord, serializeCursorValues, Cursor } from "./cursor";
-import { column, idColumn, schema } from "../schema/create";
+
 import {
   BetterSQLite3DriverConfig,
   MySQL2DriverConfig,
   NodePostgresDriverConfig,
 } from "../adapters/generic-sql/driver-config";
+import { column, idColumn, schema } from "../schema/create";
+import { decodeCursor, createCursorFromRecord, serializeCursorValues, Cursor } from "./cursor";
 
 describe("Cursor utilities", () => {
   describe("Cursor class encode and decode", () => {
@@ -92,6 +93,39 @@ describe("Cursor utilities", () => {
       const decoded = decodeCursor(encoded);
       expect(decoded.indexValues).toEqual({});
     });
+
+    it("should throw when index values contain undefined", () => {
+      const cursor = new Cursor({
+        indexName: "_primary",
+        orderDirection: "asc",
+        pageSize: 10,
+        indexValues: { id: undefined },
+      });
+
+      expect(() => cursor.encode()).toThrow(/undefined/i);
+    });
+
+    it("should throw when index values contain BigInt", () => {
+      const cursor = new Cursor({
+        indexName: "_primary",
+        orderDirection: "asc",
+        pageSize: 10,
+        indexValues: { id: 1n },
+      });
+
+      expect(() => cursor.encode()).toThrow(/bigint/i);
+    });
+
+    it("should throw when index values contain non-finite numbers", () => {
+      const cursor = new Cursor({
+        indexName: "_primary",
+        orderDirection: "asc",
+        pageSize: 10,
+        indexValues: { id: Number.NaN },
+      });
+
+      expect(() => cursor.encode()).toThrow(/finite/i);
+    });
   });
 
   describe("decodeCursor error handling", () => {
@@ -145,11 +179,58 @@ describe("Cursor utilities", () => {
       const encoded = Buffer.from(JSON.stringify(invalidData), "utf-8").toString("base64");
       expect(() => decodeCursor(encoded)).toThrow(/invalid cursor/i);
     });
+
+    it("should throw error for array indexValues", () => {
+      const invalidData = {
+        v: 1,
+        indexValues: [],
+        indexName: "test",
+        orderDirection: "asc",
+        pageSize: 10,
+      };
+      const encoded = Buffer.from(JSON.stringify(invalidData), "utf-8").toString("base64");
+      expect(() => decodeCursor(encoded)).toThrow(/invalid cursor/i);
+    });
+
+    it("should throw error for non-string indexName", () => {
+      const invalidData = {
+        v: 1,
+        indexValues: { id: "test" },
+        indexName: 123,
+        orderDirection: "asc",
+        pageSize: 10,
+      };
+      const encoded = Buffer.from(JSON.stringify(invalidData), "utf-8").toString("base64");
+      expect(() => decodeCursor(encoded)).toThrow(/invalid cursor/i);
+    });
+
+    it("should throw error for invalid pageSize values", () => {
+      const invalidData = {
+        v: 1,
+        indexValues: { id: "test" },
+        indexName: "test",
+        orderDirection: "asc",
+        pageSize: 0,
+      };
+      const encoded = Buffer.from(JSON.stringify(invalidData), "utf-8").toString("base64");
+      expect(() => decodeCursor(encoded)).toThrow(/invalid cursor/i);
+    });
+
+    it("should throw error for missing cursor version", () => {
+      const invalidData = {
+        indexValues: { id: "test" },
+        indexName: "test",
+        orderDirection: "asc",
+        pageSize: 10,
+      };
+      const encoded = Buffer.from(JSON.stringify(invalidData), "utf-8").toString("base64");
+      expect(() => decodeCursor(encoded)).toThrow(/unsupported cursor version/i);
+    });
   });
 
   describe("createCursorFromRecord", () => {
     it("should create a cursor from a record with single column index", () => {
-      const testSchema = schema((s) =>
+      const testSchema = schema("test", (s) =>
         s.addTable("users", (t) =>
           t.addColumn("id", idColumn()).addColumn("name", column("string")),
         ),
@@ -172,7 +253,7 @@ describe("Cursor utilities", () => {
     });
 
     it("should create a cursor from a record with multi-column index", () => {
-      const testSchema = schema((s) =>
+      const testSchema = schema("test", (s) =>
         s.addTable("posts", (t) =>
           t
             .addColumn("id", idColumn())
@@ -207,8 +288,31 @@ describe("Cursor utilities", () => {
       });
     });
 
+    it("should throw when record is missing index columns", () => {
+      const testSchema = schema("test", (s) =>
+        s.addTable("posts", (t) =>
+          t
+            .addColumn("id", idColumn())
+            .addColumn("createdAt", column("integer"))
+            .createIndex("created", ["createdAt"]),
+        ),
+      );
+
+      const table = testSchema.tables.posts;
+      const record = { id: "post123" };
+      const indexColumns = table.indexes.created.columns;
+
+      expect(() =>
+        createCursorFromRecord(record, indexColumns, {
+          indexName: "created",
+          orderDirection: "asc",
+          pageSize: 10,
+        }),
+      ).toThrow(/missing value/i);
+    });
+
     it("should only include columns that are in the index", () => {
-      const testSchema = schema((s) =>
+      const testSchema = schema("test", (s) =>
         s.addTable("users", (t) =>
           t
             .addColumn("id", idColumn())
@@ -235,7 +339,7 @@ describe("Cursor utilities", () => {
 
   describe("serializeCursorValues", () => {
     it("should serialize cursor values for database queries", () => {
-      const testSchema = schema((s) =>
+      const testSchema = schema("test", (s) =>
         s.addTable("users", (t) =>
           t.addColumn("id", idColumn()).addColumn("age", column("integer")),
         ),
@@ -260,8 +364,8 @@ describe("Cursor utilities", () => {
       expect(serialized).toHaveProperty("age", 25);
     });
 
-    it("should handle missing values in cursor data", () => {
-      const testSchema = schema((s) =>
+    it("should throw when cursor data is missing index values", () => {
+      const testSchema = schema("test", (s) =>
         s.addTable("users", (t) =>
           t.addColumn("id", idColumn()).addColumn("name", column("string")),
         ),
@@ -276,20 +380,15 @@ describe("Cursor utilities", () => {
       });
 
       const indexColumns = [table.columns.id, table.columns.name];
-      const serialized = serializeCursorValues(
-        cursor,
-        indexColumns,
-        new NodePostgresDriverConfig(),
-      );
-
-      expect(serialized).toHaveProperty("id", "user123");
-      expect(serialized).not.toHaveProperty("name");
+      expect(() =>
+        serializeCursorValues(cursor, indexColumns, new NodePostgresDriverConfig()),
+      ).toThrow(/missing values/i);
     });
   });
 
   describe("round-trip integration", () => {
     it("should successfully round-trip cursor data through encode/decode", () => {
-      const testSchema = schema((s) =>
+      const testSchema = schema("test", (s) =>
         s.addTable("posts", (t) =>
           t
             .addColumn("id", idColumn())
@@ -332,7 +431,7 @@ describe("Cursor utilities", () => {
     });
 
     it("should handle Date objects in cursors for PostgreSQL", () => {
-      const testSchema = schema((s) =>
+      const testSchema = schema("test", (s) =>
         s.addTable("posts", (t) =>
           t
             .addColumn("id", idColumn())
@@ -379,7 +478,7 @@ describe("Cursor utilities", () => {
     });
 
     it("should handle Date objects in cursors for SQLite", () => {
-      const testSchema = schema((s) =>
+      const testSchema = schema("test", (s) =>
         s.addTable("posts", (t) =>
           t
             .addColumn("id", idColumn())
@@ -421,7 +520,7 @@ describe("Cursor utilities", () => {
     });
 
     it("should handle Date objects in cursors for MySQL", () => {
-      const testSchema = schema((s) =>
+      const testSchema = schema("test", (s) =>
         s.addTable("posts", (t) =>
           t
             .addColumn("id", idColumn())