@fragno-dev/db 0.1.14 → 0.2.0

package/src/query/cursor.test.ts

@@ -1,6 +1,11 @@
 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";
 
 describe("Cursor utilities", () => {
   describe("Cursor class encode and decode", () => {
@@ -245,7 +250,11 @@ describe("Cursor utilities", () => {
       });
 
       const indexColumns = [table.columns.id, table.columns.age];
-      const serialized = serializeCursorValues(cursor, indexColumns, "postgresql");
+      const serialized = serializeCursorValues(
+        cursor,
+        indexColumns,
+        new NodePostgresDriverConfig(),
+      );
 
       expect(serialized).toHaveProperty("id", "user123");
       expect(serialized).toHaveProperty("age", 25);
@@ -267,7 +276,11 @@ describe("Cursor utilities", () => {
       });
 
       const indexColumns = [table.columns.id, table.columns.name];
-      const serialized = serializeCursorValues(cursor, indexColumns, "postgresql");
+      const serialized = serializeCursorValues(
+        cursor,
+        indexColumns,
+        new NodePostgresDriverConfig(),
+      );
 
       expect(serialized).toHaveProperty("id", "user123");
       expect(serialized).not.toHaveProperty("name");
@@ -307,13 +320,144 @@ describe("Cursor utilities", () => {
       const decoded = decodeCursor(cursor.encode());
 
       // Serialize the values
-      const serialized = serializeCursorValues(decoded, indexColumns, "postgresql");
+      const serialized = serializeCursorValues(
+        decoded,
+        indexColumns,
+        new NodePostgresDriverConfig(),
+      );
 
       // Should preserve the values
       expect(serialized["score"]).toBe(42);
       expect(serialized["createdAt"]).toBe(1234567890);
     });
 
+    it("should handle Date objects in cursors for PostgreSQL", () => {
+      const testSchema = schema((s) =>
+        s.addTable("posts", (t) =>
+          t
+            .addColumn("id", idColumn())
+            .addColumn("createdAt", column("timestamp"))
+            .createIndex("created", ["createdAt"]),
+        ),
+      );
+
+      const table = testSchema.tables.posts;
+      const createdAtDate = new Date("2025-11-07T09:36:57.959Z");
+      const record = {
+        id: "post123",
+        createdAt: createdAtDate,
+      };
+
+      const index = table.indexes.created;
+      const indexColumns = index.columns;
+
+      // Create cursor from record (has Date object)
+      const cursor = createCursorFromRecord(record, indexColumns, {
+        indexName: "created",
+        orderDirection: "asc",
+        pageSize: 10,
+      });
+
+      // Encode and decode (Date becomes string in JSON)
+      const encoded = cursor.encode();
+      const decoded = decodeCursor(encoded);
+
+      // After decode, the value is a string (from JSON.parse)
+      expect(typeof decoded.indexValues["createdAt"]).toBe("string");
+      expect(decoded.indexValues["createdAt"]).toBe("2025-11-07T09:36:57.959Z");
+
+      // Serialize should convert it back to Date for the database
+      const serialized = serializeCursorValues(
+        decoded,
+        indexColumns,
+        new NodePostgresDriverConfig(),
+      );
+
+      // For PostgreSQL, Date objects should be passed through as-is
+      expect(serialized["createdAt"]).toBeInstanceOf(Date);
+      expect((serialized["createdAt"] as Date).toISOString()).toBe("2025-11-07T09:36:57.959Z");
+    });
+
+    it("should handle Date objects in cursors for SQLite", () => {
+      const testSchema = schema((s) =>
+        s.addTable("posts", (t) =>
+          t
+            .addColumn("id", idColumn())
+            .addColumn("createdAt", column("timestamp"))
+            .createIndex("created", ["createdAt"]),
+        ),
+      );
+
+      const table = testSchema.tables.posts;
+      const createdAtDate = new Date("2025-11-07T09:36:57.959Z");
+      const record = {
+        id: "post123",
+        createdAt: createdAtDate,
+      };
+
+      const index = table.indexes.created;
+      const indexColumns = index.columns;
+
+      // Create cursor from record
+      const cursor = createCursorFromRecord(record, indexColumns, {
+        indexName: "created",
+        orderDirection: "asc",
+        pageSize: 10,
+      });
+
+      // Encode and decode
+      const decoded = decodeCursor(cursor.encode());
+
+      // Serialize should convert string back to Date, then to timestamp number for SQLite
+      const serialized = serializeCursorValues(
+        decoded,
+        indexColumns,
+        new BetterSQLite3DriverConfig(),
+      );
+
+      // For SQLite, Date should be converted to timestamp number
+      expect(typeof serialized["createdAt"]).toBe("number");
+      expect(serialized["createdAt"]).toBe(createdAtDate.getTime());
+    });
+
+    it("should handle Date objects in cursors for MySQL", () => {
+      const testSchema = schema((s) =>
+        s.addTable("posts", (t) =>
+          t
+            .addColumn("id", idColumn())
+            .addColumn("createdAt", column("timestamp"))
+            .createIndex("created", ["createdAt"]),
+        ),
+      );
+
+      const table = testSchema.tables.posts;
+      const createdAtDate = new Date("2025-11-07T09:36:57.959Z");
+      const record = {
+        id: "post123",
+        createdAt: createdAtDate,
+      };
+
+      const index = table.indexes.created;
+      const indexColumns = index.columns;
+
+      // Create cursor from record
+      const cursor = createCursorFromRecord(record, indexColumns, {
+        indexName: "created",
+        orderDirection: "asc",
+        pageSize: 10,
+      });
+
+      // Encode and decode
+      const decoded = decodeCursor(cursor.encode());
+
+      // Serialize for MySQL
+      const serialized = serializeCursorValues(decoded, indexColumns, new MySQL2DriverConfig());
+
+      // For MySQL, Date objects should be passed through as-is
+      expect(serialized["createdAt"]).toBeInstanceOf(Date);
+      expect((serialized["createdAt"] as Date).toISOString()).toBe("2025-11-07T09:36:57.959Z");
+    });
+
     it("should handle different order directions correctly", () => {
       const cursorAsc = new Cursor({
         indexName: "_primary",

package/src/query/cursor.ts

@@ -1,6 +1,7 @@
 import type { AnyColumn } from "../schema/create";
-import { serialize } from "../schema/serialize";
-import type { SQLProvider } from "../shared/providers";
+import { createSQLSerializer } from "./serialize/create-sql-serializer";
+import { resolveFragnoIdValue } from "./value-encoding";
+import type { DriverConfig } from "../adapters/generic-sql/driver-config";
 
 /**
  * Cursor object containing all information needed for pagination
@@ -78,6 +79,10 @@ export interface CursorResult<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;
 }
 
 /**
@@ -203,12 +208,16 @@ export function createCursorFromRecord(
 /**
  * Serialize cursor values for database queries
  *
- * Converts cursor values (which are in application format) to database format
- * using the column serialization rules.
+ * Converts cursor values (which are in JSON-compatible format after decode)
+ * to database format using the column serialization rules.
+ *
+ * This function performs a two-step process:
+ * 1. Deserialize from JSON format to application format (e.g., ISO string → Date)
+ * 2. Serialize from application format to database format (e.g., Date → driver format)
  *
  * @param cursor - The cursor object
  * @param indexColumns - The columns that make up the index
- * @param provider - The SQL provider
+ * @param driverConfig - The driver configuration
  * @returns Serialized values ready for database queries
  *
  * @example
@@ -216,21 +225,29 @@ export function createCursorFromRecord(
  * const serialized = serializeCursorValues(
  *   cursor,
  *   [table.columns.createdAt],
- *   "postgresql"
+ *   driverConfig
  * );
  * ```
  */
 export function serializeCursorValues(
   cursor: Cursor,
   indexColumns: AnyColumn[],
-  provider: SQLProvider,
+  driverConfig: DriverConfig,
 ): Record<string, unknown> {
+  const serializer = createSQLSerializer(driverConfig);
   const serialized: Record<string, unknown> = {};
 
   for (const col of indexColumns) {
     const value = cursor.indexValues[col.ormName];
     if (value !== undefined) {
-      serialized[col.ormName] = serialize(value, col, provider);
+      // First deserialize from JSON format to application format
+      // (e.g., "2025-11-07T09:36:57.959Z" string → Date object)
+      const deserialized = serializer.deserialize(value, col);
+      // Resolve FragnoId/FragnoReference to primitive values (if present)
+      const resolved = resolveFragnoIdValue(deserialized, col);
+      // Then serialize to database format
+      // (e.g., Date → database driver format)
+      serialized[col.ormName] = serializer.serialize(resolved, col);
     }
   }
 

package/src/query/orm/orm.ts

@@ -4,7 +4,7 @@ import type {
   FindManyOptions,
   JoinBuilder,
   OrderBy,
-} from "../query";
+} from "../simple-query-interface";
 import { buildCondition, type Condition } from "../condition-builder";
 import type { AnyColumn, AnyRelation, AnyTable } from "../../schema/create";
 

package/src/query/query-type.test.ts

@@ -1,14 +1,14 @@
 import { describe, expectTypeOf, it } from "vitest";
 import { column, FragnoId, idColumn, referenceColumn, schema } from "../schema/create";
 import type {
-  AbstractQuery,
+  SimpleQueryInterface,
   FindFirstOptions,
   FindManyOptions,
   JoinBuilder,
   OrderBy,
   SelectClause,
   TableToInsertValues,
-} from "./query";
+} from "./simple-query-interface";
 import type { ConditionBuilder } from "./condition-builder";
 
 describe("query type tests", () => {
@@ -91,8 +91,8 @@ describe("query type tests", () => {
     });
   });
 
-  describe("AbstractQuery methods", () => {
-    type Query = AbstractQuery<TestSchema>;
+  describe("SimpleQueryInterface methods", () => {
+    type Query = SimpleQueryInterface<TestSchema>;
 
     describe("findFirst", () => {
       it("should return all columns when select is true or undefined", () => {
@@ -257,7 +257,7 @@ describe("query type tests", () => {
 
   describe("table name type checking", () => {
     it("should only allow valid table names", () => {
-      const _query = {} as AbstractQuery<TestSchema>;
+      const _query = {} as SimpleQueryInterface<TestSchema>;
 
       // Valid table names
       type UsersParam = Parameters<typeof _query.find<"users">>;
@@ -272,7 +272,7 @@ describe("query type tests", () => {
 
   describe("column type inference", () => {
     it("should correctly infer column types for users table", () => {
-      const _query = {} as AbstractQuery<TestSchema>;
+      const _query = {} as SimpleQueryInterface<TestSchema>;
       type Result = Awaited<ReturnType<typeof _query.findFirst<"users">>>;
       type User = Exclude<Result, null>;
 
@@ -284,7 +284,7 @@ describe("query type tests", () => {
     });
 
     it("should correctly infer column types for posts table", () => {
-      const _query = {} as AbstractQuery<TestSchema>;
+      const _query = {} as SimpleQueryInterface<TestSchema>;
       type Result = Awaited<ReturnType<typeof _query.findFirst<"posts">>>;
       type Post = Exclude<Result, null>;
 
@@ -297,7 +297,7 @@ describe("query type tests", () => {
     });
 
     it("should correctly infer column types for comments table", () => {
-      const _query = {} as AbstractQuery<TestSchema>;
+      const _query = {} as SimpleQueryInterface<TestSchema>;
       type Result = Awaited<ReturnType<typeof _query.findFirst<"comments">>>;
       type Comment = Exclude<Result, null>;
 
@@ -311,7 +311,7 @@ describe("query type tests", () => {
 
   describe("complex scenarios", () => {
     it("should handle multiple table operations with correct types", () => {
-      const _query = {} as AbstractQuery<TestSchema>;
+      const _query = {} as SimpleQueryInterface<TestSchema>;
 
       // Create user return type
       type UserResult = Awaited<ReturnType<typeof _query.create<"users">>>;

package/src/query/serialize/create-sql-serializer.ts

@@ -0,0 +1,34 @@
+import type { DriverConfig } from "../../adapters/generic-sql/driver-config";
+import { SQLSerializer } from "./sql-serializer";
+import { SQLiteSerializer } from "./dialect/sqlite-serializer";
+import { PostgreSQLSerializer } from "./dialect/postgres-serializer";
+import { MySQLSerializer } from "./dialect/mysql-serializer";
+
+// Re-export SQLSerializer for convenience
+export { SQLSerializer } from "./sql-serializer";
+
+/**
+ * Factory function to create a dialect-specific SQL serializer from a DriverConfig.
+ *
+ * Based on the database type, returns the appropriate serializer implementation
+ * (PostgreSQL, MySQL, or SQLite).
+ *
+ * @param driverConfig - The driver configuration
+ * @returns Dialect-specific SQLSerializer instance
+ */
+export function createSQLSerializer(driverConfig: DriverConfig): SQLSerializer {
+  // TODO: The serializers are pretty lenient in what they accept (lost of typeof checks), it may
+  //       be beneficial to implement serializers per DriverConfig, and be less lenient.
+  switch (driverConfig.databaseType) {
+    case "postgresql":
+      return new PostgreSQLSerializer(driverConfig);
+    case "mysql":
+      return new MySQLSerializer(driverConfig);
+    case "sqlite":
+      return new SQLiteSerializer(driverConfig);
+    default: {
+      const exhaustiveCheck: never = driverConfig.databaseType;
+      throw new Error(`Unsupported database type: ${exhaustiveCheck}`);
+    }
+  }
+}

package/src/query/serialize/dialect/mysql-serializer.ts

@@ -0,0 +1,142 @@
+import type { AnyColumn } from "../../../schema/create";
+import { SQLSerializer } from "../sql-serializer";
+import type { DriverConfig } from "../../../adapters/generic-sql/driver-config";
+
+/**
+ * MySQL-specific serializer.
+ *
+ * MySQL has good native type support:
+ * - Native JSON support (MySQL 5.7+)
+ * - Native boolean type (TINYINT(1))
+ * - Native timestamp/datetime/date types
+ * - Native bigint support
+ *
+ * Similar to PostgreSQL, most values pass through without conversion.
+ * Timestamps/dates are returned as strings and need to be parsed.
+ */
+export class MySQLSerializer extends SQLSerializer {
+  constructor(driverConfig: DriverConfig) {
+    super(driverConfig);
+  }
+
+  protected serializeDate(value: Date): Date {
+    // MySQL handles Date objects natively
+    return value;
+  }
+
+  protected serializeBoolean(value: boolean): boolean {
+    // MySQL handles boolean natively (as TINYINT(1))
+    return value;
+  }
+
+  protected serializeBigInt(value: bigint, _col: AnyColumn): bigint {
+    // MySQL handles bigint natively
+    return value;
+  }
+
+  protected deserializeDate(value: unknown): Date {
+    if (value instanceof Date) {
+      return value;
+    }
+    // MySQL returns timestamps/dates as strings
+    if (typeof value === "string") {
+      return new Date(value);
+    }
+    throw new Error(`Cannot deserialize date from value: ${value}`);
+  }
+
+  protected deserializeBoolean(value: unknown): boolean {
+    if (typeof value === "boolean") {
+      return value;
+    }
+    // MySQL may return booleans as numbers (0/1)
+    if (typeof value === "number") {
+      return value === 1;
+    }
+    throw new Error(`Cannot deserialize boolean from value: ${value}`);
+  }
+
+  protected deserializeBigInt(value: unknown): bigint {
+    if (typeof value === "bigint") {
+      return value;
+    }
+    // MySQL may return bigints as strings
+    if (typeof value === "string") {
+      return BigInt(value);
+    }
+    if (typeof value === "number") {
+      return BigInt(value);
+    }
+    throw new Error(`Cannot deserialize bigint from value: ${value}`);
+  }
+
+  protected serializeJson(value: unknown): unknown {
+    // MySQL supports native JSON, pass through as-is
+    return value;
+  }
+
+  protected deserializeJson(value: unknown): unknown {
+    // MySQL returns parsed JSON objects, pass through as-is
+    return value;
+  }
+
+  protected deserializeBinary(value: unknown): Uint8Array {
+    // MySQL can return Buffer or Uint8Array for BLOB columns
+    if (value instanceof Buffer) {
+      return new Uint8Array(value.buffer, value.byteOffset, value.byteLength);
+    }
+    if (value instanceof Uint8Array) {
+      return value;
+    }
+    if (value instanceof ArrayBuffer) {
+      return new Uint8Array(value);
+    }
+    throw new Error(`Cannot deserialize binary from value: ${typeof value}`);
+  }
+
+  protected deserializeInteger(value: unknown): number {
+    if (typeof value === "number") {
+      return value;
+    }
+    // MySQL may return integers as strings
+    if (typeof value === "string") {
+      const num = Number(value);
+      if (isNaN(num)) {
+        throw new Error(`Cannot deserialize integer from invalid string: ${value}`);
+      }
+      return num;
+    }
+    // MySQL may return bigint for large integers
+    if (typeof value === "bigint") {
+      if (value > Number.MAX_SAFE_INTEGER || value < Number.MIN_SAFE_INTEGER) {
+        throw new RangeError(
+          `Cannot deserialize integer value ${value}: exceeds safe integer range`,
+        );
+      }
+      return Number(value);
+    }
+    throw new Error(`Cannot deserialize integer from value: ${typeof value}`);
+  }
+
+  protected deserializeDecimal(value: unknown): number {
+    // MySQL can return decimals as numbers or strings
+    if (typeof value === "number") {
+      return value;
+    }
+    if (typeof value === "string") {
+      const num = parseFloat(value);
+      if (isNaN(num)) {
+        throw new Error(`Cannot deserialize decimal from invalid string: ${value}`);
+      }
+      return num;
+    }
+    throw new Error(`Cannot deserialize decimal from value: ${typeof value}`);
+  }
+
+  protected deserializeString(value: unknown): string {
+    if (typeof value === "string") {
+      return value;
+    }
+    throw new Error(`Cannot deserialize string from value: ${typeof value}`);
+  }
+}

package/src/query/serialize/dialect/postgres-serializer.ts

@@ -0,0 +1,129 @@
+import type { AnyColumn } from "../../../schema/create";
+import { SQLSerializer } from "../sql-serializer";
+import type { DriverConfig } from "../../../adapters/generic-sql/driver-config";
+
+/**
+ * PostgreSQL-specific serializer.
+ *
+ * PostgreSQL has excellent native type support:
+ * - Native JSON support
+ * - Native boolean type
+ * - Native timestamp/date types
+ * - Native bigint support
+ *
+ * Most values pass through without conversion, only strings need to be parsed to Date.
+ */
+export class PostgreSQLSerializer extends SQLSerializer {
+  constructor(driverConfig: DriverConfig) {
+    super(driverConfig);
+  }
+
+  protected serializeDate(value: Date): Date {
+    // PostgreSQL handles Date objects natively
+    return value;
+  }
+
+  protected serializeBoolean(value: boolean): boolean {
+    // PostgreSQL handles boolean natively
+    return value;
+  }
+
+  protected serializeBigInt(value: bigint, _col: AnyColumn): bigint {
+    // PostgreSQL handles bigint natively
+    return value;
+  }
+
+  protected deserializeDate(value: unknown): Date {
+    if (value instanceof Date) {
+      return value;
+    }
+    // PostgreSQL returns timestamps/dates as strings
+    if (typeof value === "string") {
+      return new Date(value);
+    }
+    throw new Error(`Cannot deserialize date from value: ${value}`);
+  }
+
+  protected deserializeBoolean(value: unknown): boolean {
+    if (typeof value === "boolean") {
+      return value;
+    }
+    throw new Error(`Cannot deserialize boolean from value: ${value}`);
+  }
+
+  protected deserializeBigInt(value: unknown): bigint {
+    if (typeof value === "bigint") {
+      return value;
+    }
+    // PostgreSQL may return bigints as strings
+    if (typeof value === "string") {
+      return BigInt(value);
+    }
+    if (typeof value === "number") {
+      return BigInt(value);
+    }
+    throw new Error(`Cannot deserialize bigint from value: ${value}`);
+  }
+
+  protected serializeJson(value: unknown): unknown {
+    // PostgreSQL supports native JSON, pass through as-is
+    return value;
+  }
+
+  protected deserializeJson(value: unknown): unknown {
+    // PostgreSQL returns parsed JSON objects, pass through as-is
+    return value;
+  }
+
+  protected deserializeBinary(value: unknown): Uint8Array {
+    // PostgreSQL can return Buffer or Uint8Array for BYTEA columns
+    if (value instanceof Buffer) {
+      return new Uint8Array(value.buffer, value.byteOffset, value.byteLength);
+    }
+    if (value instanceof Uint8Array) {
+      return value;
+    }
+    if (value instanceof ArrayBuffer) {
+      return new Uint8Array(value);
+    }
+    throw new Error(`Cannot deserialize binary from value: ${typeof value}`);
+  }
+
+  protected deserializeInteger(value: unknown): number {
+    if (typeof value === "number") {
+      return value;
+    }
+    // PostgreSQL may return bigint for large integers
+    if (typeof value === "bigint") {
+      if (value > Number.MAX_SAFE_INTEGER || value < Number.MIN_SAFE_INTEGER) {
+        throw new RangeError(
+          `Cannot deserialize integer value ${value}: exceeds safe integer range`,
+        );
+      }
+      return Number(value);
+    }
+    throw new Error(`Cannot deserialize integer from value: ${typeof value}`);
+  }
+
+  protected deserializeDecimal(value: unknown): number {
+    // PostgreSQL can return decimals as numbers or strings depending on precision
+    if (typeof value === "number") {
+      return value;
+    }
+    if (typeof value === "string") {
+      const num = parseFloat(value);
+      if (isNaN(num)) {
+        throw new Error(`Cannot deserialize decimal from invalid string: ${value}`);
+      }
+      return num;
+    }
+    throw new Error(`Cannot deserialize decimal from value: ${typeof value}`);
+  }
+
+  protected deserializeString(value: unknown): string {
+    if (typeof value === "string") {
+      return value;
+    }
+    throw new Error(`Cannot deserialize string from value: ${typeof value}`);
+  }
+}