@fragno-dev/db 0.1.15 → 0.2.0

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}`);
+  }
+}

package/src/query/serialize/dialect/sqlite-serializer.test.ts

@@ -0,0 +1,251 @@
+import { describe, it, expect } from "vitest";
+import { SQLiteSerializer } from "./sqlite-serializer";
+import type { AnyColumn } from "../../../schema/create";
+import { BetterSQLite3DriverConfig } from "../../../adapters/generic-sql/driver-config";
+
+describe("SQLiteSerializer", () => {
+  const mockDriverConfig = new BetterSQLite3DriverConfig();
+  const serializer = new SQLiteSerializer(mockDriverConfig);
+
+  describe("serializeBigInt", () => {
+    describe("for internal-id and reference columns", () => {
+      it("should convert safe bigint to number for reference column", () => {
+        const col: AnyColumn = {
+          name: "userId",
+          type: "bigint",
+          role: "reference",
+          isNullable: false,
+        } as AnyColumn;
+
+        const result = serializer["serializeBigInt"](BigInt(123), col);
+        expect(result).toBe(123);
+        expect(typeof result).toBe("number");
+      });
+
+      it("should convert safe bigint to number for internal-id column", () => {
+        const col: AnyColumn = {
+          name: "_internalId",
+          type: "bigint",
+          role: "internal-id",
+          isNullable: false,
+        } as AnyColumn;
+
+        const result = serializer["serializeBigInt"](BigInt(456), col);
+        expect(result).toBe(456);
+        expect(typeof result).toBe("number");
+      });
+
+      it("should convert MAX_SAFE_INTEGER successfully", () => {
+        const col: AnyColumn = {
+          name: "userId",
+          type: "bigint",
+          role: "reference",
+          isNullable: false,
+        } as AnyColumn;
+
+        const maxSafe = BigInt(Number.MAX_SAFE_INTEGER);
+        const result = serializer["serializeBigInt"](maxSafe, col);
+        expect(result).toBe(Number.MAX_SAFE_INTEGER);
+      });
+
+      it("should convert negative MAX_SAFE_INTEGER successfully", () => {
+        const col: AnyColumn = {
+          name: "userId",
+          type: "bigint",
+          role: "reference",
+          isNullable: false,
+        } as AnyColumn;
+
+        const minSafe = BigInt(-Number.MAX_SAFE_INTEGER);
+        const result = serializer["serializeBigInt"](minSafe, col);
+        expect(result).toBe(-Number.MAX_SAFE_INTEGER);
+      });
+
+      it("should throw RangeError when bigint exceeds MAX_SAFE_INTEGER for reference column", () => {
+        const col: AnyColumn = {
+          name: "userId",
+          type: "bigint",
+          role: "reference",
+          isNullable: false,
+        } as AnyColumn;
+
+        const tooBig = BigInt(Number.MAX_SAFE_INTEGER) + BigInt(1);
+
+        expect(() => serializer["serializeBigInt"](tooBig, col)).toThrow(RangeError);
+        expect(() => serializer["serializeBigInt"](tooBig, col)).toThrow(
+          /Cannot serialize bigint value.*exceeds Number\.MAX_SAFE_INTEGER/,
+        );
+        expect(() => serializer["serializeBigInt"](tooBig, col)).toThrow(/userId/);
+      });
+
+      it("should throw RangeError when bigint is less than -MAX_SAFE_INTEGER for internal-id column", () => {
+        const col: AnyColumn = {
+          name: "_internalId",
+          type: "bigint",
+          role: "internal-id",
+          isNullable: false,
+        } as AnyColumn;
+
+        const tooSmall = BigInt(-Number.MAX_SAFE_INTEGER) - BigInt(1);
+
+        expect(() => serializer["serializeBigInt"](tooSmall, col)).toThrow(RangeError);
+        expect(() => serializer["serializeBigInt"](tooSmall, col)).toThrow(
+          /Cannot serialize bigint value.*exceeds Number\.MAX_SAFE_INTEGER/,
+        );
+        expect(() => serializer["serializeBigInt"](tooSmall, col)).toThrow(/_internalId/);
+      });
+    });
+
+    describe("for regular bigint columns", () => {
+      it("should convert to Buffer for regular bigint column", () => {
+        const col: AnyColumn = {
+          name: "largeNumber",
+          type: "bigint",
+          role: "regular",
+          isNullable: false,
+        } as AnyColumn;
+
+        const result = serializer["serializeBigInt"](BigInt(789), col);
+        expect(result).toBeInstanceOf(Buffer);
+        expect((result as Buffer).length).toBe(8);
+      });
+
+      it("should handle large values outside safe integer range as Buffer", () => {
+        const col: AnyColumn = {
+          name: "largeNumber",
+          type: "bigint",
+          role: "regular",
+          isNullable: false,
+        } as AnyColumn;
+
+        const veryLarge = BigInt(Number.MAX_SAFE_INTEGER) + BigInt(1000);
+        const result = serializer["serializeBigInt"](veryLarge, col);
+
+        expect(result).toBeInstanceOf(Buffer);
+        // Verify round-trip
+        const deserialized = (result as Buffer).readBigInt64BE(0);
+        expect(deserialized).toBe(veryLarge);
+      });
+    });
+  });
+
+  describe("other serialization methods", () => {
+    it("should serialize Date to timestamp number", () => {
+      const date = new Date("2024-01-01T00:00:00Z");
+      const result = serializer["serializeDate"](date);
+      expect(result).toBe(date.getTime());
+      expect(typeof result).toBe("number");
+    });
+
+    it("should serialize boolean to 0/1", () => {
+      expect(serializer["serializeBoolean"](true)).toBe(1);
+      expect(serializer["serializeBoolean"](false)).toBe(0);
+    });
+
+    it("should serialize JSON to string", () => {
+      const obj = { foo: "bar", num: 42 };
+      const result = serializer["serializeJson"](obj);
+      expect(result).toBe(JSON.stringify(obj));
+      expect(typeof result).toBe("string");
+    });
+  });
+
+  describe("deserializeBinary", () => {
+    it("should deserialize Buffer to Uint8Array", () => {
+      const buffer = Buffer.from([1, 2, 3, 4]);
+      const result = serializer["deserializeBinary"](buffer);
+      expect(result).toBeInstanceOf(Uint8Array);
+      expect(Array.from(result)).toEqual([1, 2, 3, 4]);
+    });
+
+    it("should deserialize Uint8Array directly", () => {
+      const uint8 = new Uint8Array([5, 6, 7, 8]);
+      const result = serializer["deserializeBinary"](uint8);
+      expect(result).toBeInstanceOf(Uint8Array);
+      expect(result).toBe(uint8);
+    });
+
+    it("should deserialize ArrayBuffer to Uint8Array", () => {
+      const arrayBuffer = new ArrayBuffer(4);
+      const view = new Uint8Array(arrayBuffer);
+      view.set([9, 10, 11, 12]);
+      const result = serializer["deserializeBinary"](arrayBuffer);
+      expect(result).toBeInstanceOf(Uint8Array);
+      expect(Array.from(result)).toEqual([9, 10, 11, 12]);
+    });
+
+    it("should throw error for invalid binary value", () => {
+      expect(() => serializer["deserializeBinary"]("not binary")).toThrow(
+        /Cannot deserialize binary/,
+      );
+    });
+  });
+
+  describe("deserializeInteger", () => {
+    it("should deserialize number directly", () => {
+      expect(serializer["deserializeInteger"](42)).toBe(42);
+    });
+
+    it("should deserialize string to number", () => {
+      expect(serializer["deserializeInteger"]("123")).toBe(123);
+    });
+
+    it("should deserialize bigint to number when safe", () => {
+      expect(serializer["deserializeInteger"](BigInt(456))).toBe(456);
+    });
+
+    it("should throw error when bigint exceeds safe range", () => {
+      const tooBig = BigInt(Number.MAX_SAFE_INTEGER) + BigInt(1);
+      expect(() => serializer["deserializeInteger"](tooBig)).toThrow(RangeError);
+      expect(() => serializer["deserializeInteger"](tooBig)).toThrow(/exceeds safe integer range/);
+    });
+
+    it("should throw error for invalid string", () => {
+      expect(() => serializer["deserializeInteger"]("not a number")).toThrow(
+        /Cannot deserialize integer from invalid string/,
+      );
+    });
+
+    it("should throw error for invalid type", () => {
+      expect(() => serializer["deserializeInteger"](null)).toThrow(
+        /Cannot deserialize integer from value/,
+      );
+    });
+  });
+
+  describe("deserializeDecimal", () => {
+    it("should deserialize number directly", () => {
+      expect(serializer["deserializeDecimal"](3.14)).toBe(3.14);
+    });
+
+    it("should deserialize string to number", () => {
+      expect(serializer["deserializeDecimal"]("3.14")).toBe(3.14);
+      expect(serializer["deserializeDecimal"]("123.456")).toBe(123.456);
+      expect(serializer["deserializeDecimal"]("-99.99")).toBe(-99.99);
+    });
+
+    it("should throw error for invalid string", () => {
+      expect(() => serializer["deserializeDecimal"]("not a number")).toThrow(
+        /Cannot deserialize decimal from invalid string/,
+      );
+    });
+
+    it("should throw error for invalid type", () => {
+      expect(() => serializer["deserializeDecimal"](null)).toThrow(
+        /Cannot deserialize decimal from value/,
+      );
+    });
+  });
+
+  describe("deserializeString", () => {
+    it("should deserialize string directly", () => {
+      expect(serializer["deserializeString"]("hello")).toBe("hello");
+    });
+
+    it("should throw error for non-string", () => {
+      expect(() => serializer["deserializeString"](123)).toThrow(
+        /Cannot deserialize string from value/,
+      );
+    });
+  });
+});

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

@@ -0,0 +1,156 @@
+import type { AnyColumn } from "../../../schema/create";
+import { SQLSerializer } from "../sql-serializer";
+import type { DriverConfig } from "../../../adapters/generic-sql/driver-config";
+
+/**
+ * SQLite-specific serializer.
+ *
+ * SQLite has limited native type support and requires conversions:
+ * - JSON → strings (no native JSON support)
+ * - Dates → numbers (timestamps)
+ * - Booleans → 0/1
+ * - BigInts → Buffer (except for internal-id and reference columns → number)
+ * - Numbers/strings → Date for timestamps/dates
+ */
+export class SQLiteSerializer extends SQLSerializer {
+  constructor(driverConfig: DriverConfig) {
+    super(driverConfig);
+  }
+
+  protected serializeDate(value: Date): number {
+    return value.getTime();
+  }
+
+  protected serializeBoolean(value: boolean): number {
+    return value ? 1 : 0;
+  }
+
+  protected serializeBigInt(value: bigint, col: AnyColumn): number | Buffer {
+    // SQLite special case: internal-id and reference columns use integer, not blob
+    // These should be converted to numbers for SQLite
+    if (col.role === "reference" || col.role === "internal-id") {
+      // Check if the bigint is within the safe integer range to avoid precision loss
+      if (Math.abs(Number(value)) > Number.MAX_SAFE_INTEGER) {
+        throw new RangeError(
+          `Cannot serialize bigint value ${value} for column "${col.name}": ` +
+            `value exceeds Number.MAX_SAFE_INTEGER (${Number.MAX_SAFE_INTEGER}). ` +
+            `SQLite reference and internal-id columns use INTEGER type which requires values ` +
+            `to fit within JavaScript's safe integer range.`,
+        );
+      }
+      return Number(value);
+    }
+    const buf = Buffer.alloc(8);
+    buf.writeBigInt64BE(value);
+    return buf;
+  }
+
+  protected deserializeDate(value: unknown): Date {
+    if (value instanceof Date) {
+      return value;
+    }
+    if (typeof value === "number" || 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;
+    }
+    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;
+    }
+    if (value instanceof Buffer) {
+      return value.readBigInt64BE(0);
+    }
+    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): string {
+    // SQLite doesn't support native JSON, so we stringify
+    return JSON.stringify(value);
+  }
+
+  protected deserializeJson(value: unknown): unknown {
+    // SQLite stores JSON as strings, so we need to parse
+    if (typeof value !== "string") {
+      throw new Error(`Expected JSON string but got ${typeof value}`);
+    }
+    return JSON.parse(value);
+  }
+
+  protected deserializeBinary(value: unknown): Uint8Array {
+    // SQLite 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;
+    }
+    // SQLite may return integers as strings for large values
+    if (typeof value === "string") {
+      const num = Number(value);
+      if (isNaN(num)) {
+        throw new Error(`Cannot deserialize integer from invalid string: ${value}`);
+      }
+      return num;
+    }
+    // SQLite 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 {
+    // SQLite stores decimals as REAL (floating point) or TEXT
+    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/sql-serializer.ts

@@ -0,0 +1,143 @@
+import type { DriverConfig } from "../../adapters/generic-sql/driver-config";
+import type { AnyColumn } from "../../schema/create";
+
+/**
+ * Abstract base class for SQL value serialization/deserialization.
+ *
+ * Similar to SQLTypeMapper, this class provides a framework for converting values
+ * between application format and database format. Each database dialect extends
+ * this class and implements abstract methods for dialect-specific conversions.
+ *
+ * Handles:
+ * - Type conversions (Date, boolean, BigInt, etc.)
+ * - JSON handling (delegated to dialect-specific implementations)
+ * - Binary data conversion (Uint8Array ↔ Buffer)
+ */
+export abstract class SQLSerializer {
+  protected readonly driverConfig: DriverConfig;
+
+  constructor(driverConfig: DriverConfig) {
+    this.driverConfig = driverConfig;
+  }
+
+  /**
+   * Deserialize a value from database format to application format.
+   *
+   * @param value - The raw database value
+   * @param col - The column schema definition
+   * @returns The deserialized value in application format
+   * @throws Error if value cannot be deserialized to the expected type
+   */
+  deserialize(value: unknown, col: AnyColumn): unknown {
+    if (value === null) {
+      return null;
+    }
+
+    // Handle JSON deserialization (delegated to subclass)
+    if (col.type === "json") {
+      return this.deserializeJson(value);
+    }
+
+    // Handle date/timestamp deserialization
+    if (col.type === "timestamp" || col.type === "date") {
+      return this.deserializeDate(value);
+    }
+
+    // Handle boolean deserialization
+    if (col.type === "bool") {
+      return this.deserializeBoolean(value);
+    }
+
+    // Handle bigint deserialization
+    if (col.type === "bigint") {
+      return this.deserializeBigInt(value);
+    }
+
+    // Handle binary deserialization (delegated to subclass for driver flexibility)
+    if (col.type === "binary") {
+      return this.deserializeBinary(value);
+    }
+
+    // Handle integer deserialization (delegated to subclass - drivers may return string/bigint)
+    if (col.type === "integer") {
+      return this.deserializeInteger(value);
+    }
+
+    // Handle decimal deserialization (delegated to subclass for driver flexibility)
+    if (col.type === "decimal") {
+      return this.deserializeDecimal(value);
+    }
+
+    // Handle string/varchar deserialization (delegated to subclass for consistency)
+    if (col.type === "string" || (typeof col.type === "string" && col.type.startsWith("varchar"))) {
+      return this.deserializeString(value);
+    }
+
+    throw new Error(`Unsupported column type for deserialization: ${col.type}`);
+  }
+
+  /**
+   * Serialize a value from application format to database format.
+   *
+   * Note: This method expects FragnoId/FragnoReference objects to be resolved
+   * to primitive values before calling. Use resolveFragnoIdValue() from
+   * value-encoding.ts for this purpose.
+   *
+   * @param value - The application value to serialize (should not be FragnoId/FragnoReference)
+   * @param col - The column schema definition
+   * @param skipDriverConversions - Skip driver-level type conversions (Date->number, boolean->0/1, bigint->Buffer).
+   *                                 Set to true when using ORMs like Drizzle that handle these conversions internally.
+   * @returns The serialized value in database format
+   */
+  serialize(value: unknown, col: AnyColumn, skipDriverConversions = false): unknown {
+    if (value === null) {
+      return null;
+    }
+
+    // Handle JSON serialization (delegated to subclass)
+    if (col.type === "json") {
+      return this.serializeJson(value);
+    }
+
+    // Skip driver-specific type conversions when using ORMs that handle them internally
+    if (!skipDriverConversions) {
+      // Handle date/timestamp serialization
+      if (value instanceof Date) {
+        return this.serializeDate(value);
+      }
+
+      // Handle boolean serialization
+      if (typeof value === "boolean") {
+        return this.serializeBoolean(value);
+      }
+
+      // Handle bigint serialization
+      if (typeof value === "bigint") {
+        return this.serializeBigInt(value, col);
+      }
+    }
+
+    // Handle binary serialization (most drivers accept Buffer)
+    if (col.type === "binary" && value instanceof Uint8Array) {
+      return Buffer.from(value);
+    }
+
+    return value;
+  }
+
+  // Abstract methods for dialect-specific serialization
+  protected abstract serializeDate(value: Date): Date | number;
+  protected abstract serializeBoolean(value: boolean): boolean | number;
+  protected abstract serializeBigInt(value: bigint, col: AnyColumn): bigint | number | Buffer;
+  protected abstract serializeJson(value: unknown): unknown;
+
+  // Abstract methods for dialect-specific deserialization
+  protected abstract deserializeDate(value: unknown): Date;
+  protected abstract deserializeBoolean(value: unknown): boolean;
+  protected abstract deserializeBigInt(value: unknown): bigint;
+  protected abstract deserializeJson(value: unknown): unknown;
+  protected abstract deserializeBinary(value: unknown): Uint8Array;
+  protected abstract deserializeInteger(value: unknown): number;
+  protected abstract deserializeDecimal(value: unknown): number;
+  protected abstract deserializeString(value: unknown): string;
+}

package/src/query/{query.ts → simple-query-interface.ts}

@@ -6,7 +6,7 @@ import type {
   UpdateBuilder,
   DeleteBuilder,
   UpdateManyBuilder,
-} from "./unit-of-work";
+} from "./unit-of-work/unit-of-work";
 import type { Prettify } from "../util/types";
 import type { CursorResult } from "./cursor";
 
@@ -132,7 +132,7 @@ export type FindManyOptions<
     }
   : {});
 
-export interface AbstractQuery<TSchema extends AnySchema, TUOWConfig = void> {
+export interface SimpleQueryInterface<TSchema extends AnySchema, TUOWConfig = void> {
   /**
    * Find multiple records using a builder pattern
    */