@fragno-dev/db 0.2.2 → 0.3.0

package/src/outbox/outbox.ts

@@ -0,0 +1,137 @@
+import type { AnyTable, FragnoId } from "../schema/create";
+
+export type OutboxConfig = {
+  enabled: boolean;
+};
+
+export type OutboxVersionstampStrategy =
+  | "update-returning"
+  | "insert-on-conflict-returning"
+  | "insert-on-duplicate-last-insert-id";
+
+export type OutboxPayload = {
+  version: 1;
+  mutations: OutboxMutation[];
+};
+
+export type OutboxMutation =
+  | {
+      op: "create";
+      schema: string;
+      namespace?: string;
+      table: string;
+      externalId: string;
+      versionstamp: string;
+      values: Record<string, unknown>;
+    }
+  | {
+      op: "update";
+      schema: string;
+      namespace?: string;
+      table: string;
+      externalId: string;
+      versionstamp: string;
+      set: Record<string, unknown>;
+      checkVersion?: number;
+    }
+  | {
+      op: "delete";
+      schema: string;
+      namespace?: string;
+      table: string;
+      externalId: string;
+      versionstamp: string;
+      checkVersion?: number;
+    };
+
+export type OutboxRefMap = Record<string, string>;
+
+export type OutboxPayloadSerialized = {
+  json: unknown;
+  meta?: Record<string, unknown>;
+};
+
+export type OutboxEntry = {
+  id: FragnoId;
+  versionstamp: string;
+  uowId: string;
+  payload: OutboxPayloadSerialized;
+  refMap?: OutboxRefMap;
+  createdAt: Date;
+};
+
+export type OutboxRefLookup = {
+  key: string;
+  internalId: bigint | number;
+  table: AnyTable;
+  namespace?: string;
+};
+
+export function encodeVersionstamp(transactionVersion: bigint, userVersion: number): Uint8Array {
+  if (userVersion < 0 || userVersion > 0xffff) {
+    throw new Error(`Invalid outbox user version: ${userVersion}`);
+  }
+
+  const txBytes = bigintToBytes(transactionVersion, 10);
+  const userBytes = new Uint8Array(2);
+  userBytes[0] = (userVersion >> 8) & 0xff;
+  userBytes[1] = userVersion & 0xff;
+
+  const combined = new Uint8Array(12);
+  combined.set(txBytes, 0);
+  combined.set(userBytes, 10);
+
+  return combined;
+}
+
+export function versionstampToHex(bytes: Uint8Array): string {
+  let hex = "";
+  for (const byte of bytes) {
+    hex += byte.toString(16).padStart(2, "0");
+  }
+  return hex;
+}
+
+export function hexToVersionstamp(hex: string): Uint8Array {
+  if (hex.length % 2 !== 0) {
+    throw new Error(`Invalid versionstamp hex length: ${hex.length}`);
+  }
+
+  const bytes = new Uint8Array(hex.length / 2);
+  for (let i = 0; i < hex.length; i += 2) {
+    bytes[i / 2] = Number.parseInt(hex.slice(i, i + 2), 16);
+  }
+  return bytes;
+}
+
+export function parseOutboxVersionValue(value: unknown): bigint {
+  if (typeof value === "bigint") {
+    return value;
+  }
+
+  if (typeof value === "number") {
+    return BigInt(value);
+  }
+
+  if (typeof value === "string") {
+    return BigInt(value);
+  }
+
+  throw new Error(`Invalid outbox version value: ${String(value)}`);
+}
+
+function bigintToBytes(value: bigint, length: number): Uint8Array {
+  const bytes = new Uint8Array(length);
+  let remaining = value;
+
+  for (let i = length - 1; i >= 0; i -= 1) {
+    bytes[i] = Number(remaining & 0xffn);
+    remaining >>= 8n;
+  }
+
+  if (remaining !== 0n) {
+    throw new Error(`Outbox version ${value} exceeds ${length * 8} bits`);
+  }
+
+  return bytes;
+}

package/src/query/column-defaults.ts

@@ -1,6 +1,11 @@
 import type { AnyColumn } from "../schema/create";
 import { createId } from "../id";
 
+export type RuntimeDefaultContext = {
+  now?: () => Date;
+  createId?: () => string;
+};
+
 /**
  * Generate a runtime default value for a column that has defaultTo$()
  *
@@ -12,7 +17,10 @@ import { createId } from "../id";
  *
  * @internal
  */
-export function generateRuntimeDefault(column: AnyColumn): unknown {
+export function generateRuntimeDefault(
+  column: AnyColumn,
+  context: RuntimeDefaultContext = {},
+): unknown {
   // Check if column has a default value configuration
   if (!column.default) {
     return undefined;
@@ -34,11 +42,11 @@ export function generateRuntimeDefault(column: AnyColumn): unknown {
   const runtime = column.default.runtime;
 
   if (runtime === "cuid") {
-    return createId();
+    return (context.createId ?? createId)();
   }
 
   if (runtime === "now") {
-    return new Date();
+    return (context.now ?? (() => new Date()))();
   }
 
   if (typeof runtime === "function") {
@@ -47,3 +55,33 @@ export function generateRuntimeDefault(column: AnyColumn): unknown {
 
   return undefined;
 }
+
+/**
+ * Generate a fallback value for database-level defaults.
+ *
+ * This is used by adapters that cannot rely on database DEFAULT constraints,
+ * such as the in-memory adapter.
+ *
+ * @internal
+ */
+export function generateDatabaseDefault(
+  column: AnyColumn,
+  context: RuntimeDefaultContext = {},
+): unknown {
+  if (!column.default) {
+    return undefined;
+  }
+
+  if ("value" in column.default) {
+    return column.default.value;
+  }
+
+  if ("dbSpecial" in column.default) {
+    if (column.default.dbSpecial === "now") {
+      return (context.now ?? (() => new Date()))();
+    }
+    return undefined;
+  }
+
+  return undefined;
+}

package/src/query/condition-builder.test.ts

@@ -3,7 +3,7 @@ import { column, idColumn, schema } from "../schema/create";
 import { createBuilder, createIndexedBuilder } from "./condition-builder";
 
 describe("ConditionBuilder", () => {
-  const testSchema = schema((s) =>
+  const testSchema = schema("test", (s) =>
     s
       .addTable("users", (t) =>
         t
@@ -11,7 +11,7 @@ describe("ConditionBuilder", () => {
           .addColumn("email", column("string"))
           .addColumn("name", column("string"))
           .addColumn("age", column("integer").nullable())
-          .createIndex("_primary", ["id"], { unique: true })
+          .createIndex("idx_users_primary", ["id"], { unique: true })
           .createIndex("idx_email", ["email"], { unique: true })
           .createIndex("idx_name_age", ["name", "age"]),
       )
@@ -21,7 +21,7 @@ describe("ConditionBuilder", () => {
           .addColumn("title", column("string"))
           .addColumn("content", column("string"))
           .addColumn("published", column("bool"))
-          .createIndex("_primary", ["id"], { unique: true })
+          .createIndex("idx_posts_primary", ["id"], { unique: true })
           .createIndex("idx_published", ["published"]),
       ),
   );

package/src/query/cursor.test.ts

@@ -92,6 +92,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 +178,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 +252,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 +287,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 +338,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 +363,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 +379,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 +430,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 +477,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 +519,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())

package/src/query/cursor.ts

@@ -2,6 +2,7 @@ import type { AnyColumn } from "../schema/create";
 import { createSQLSerializer } from "./serialize/create-sql-serializer";
 import { resolveFragnoIdValue } from "./value-encoding";
 import type { DriverConfig } from "../adapters/generic-sql/driver-config";
+import type { SQLiteStorageMode } from "../adapters/generic-sql/sqlite-storage";
 
 /**
  * Cursor object containing all information needed for pagination
@@ -56,6 +57,7 @@ export class Cursor {
    * 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,
@@ -100,7 +102,12 @@ export interface CursorData {
  * Encode cursor data to a base64 string (internal)
  */
 function encodeCursorData(data: CursorData): string {
-  const json = JSON.stringify(data);
+  let json: string;
+  try {
+    json = JSON.stringify(data);
+  } catch (error) {
+    throw new Error(`Invalid cursor: ${error instanceof Error ? error.message : "malformed data"}`);
+  }
   // Use Buffer in Node.js or btoa in browsers
   if (typeof Buffer !== "undefined") {
     return Buffer.from(json, "utf-8").toString("base64");
@@ -129,32 +136,38 @@ export function decodeCursor(cursor: string): Cursor {
       json = atob(cursor);
     }
     const data = JSON.parse(json);
+    const record = data as Record<string, unknown>;
 
     // Validate structure
     if (
-      !data ||
-      typeof data !== "object" ||
-      !data.indexValues ||
-      typeof data.indexValues !== "object" ||
-      typeof data.pageSize !== "number" ||
-      !data.indexName ||
-      !data.orderDirection ||
-      (data.orderDirection !== "asc" && data.orderDirection !== "desc")
+      !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
-    const version = typeof data.v === "number" ? data.v : 0;
+    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: data.indexName,
-      orderDirection: data.orderDirection,
-      pageSize: data.pageSize,
-      indexValues: data.indexValues,
+      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"}`);
@@ -194,7 +207,11 @@ export function createCursorFromRecord(
   const indexValues: Record<string, unknown> = {};
 
   for (const col of indexColumns) {
-    indexValues[col.ormName] = record[col.ormName];
+    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({
@@ -218,6 +235,7 @@ export function createCursorFromRecord(
  * @param cursor - The cursor object
  * @param indexColumns - The columns that make up the index
  * @param driverConfig - The driver configuration
+ * @param sqliteStorageMode - Optional SQLite storage mode override
  * @returns Serialized values ready for database queries
  *
  * @example
@@ -233,23 +251,54 @@ export function serializeCursorValues(
   cursor: Cursor,
   indexColumns: AnyColumn[],
   driverConfig: DriverConfig,
+  sqliteStorageMode?: SQLiteStorageMode,
 ): Record<string, unknown> {
-  const serializer = createSQLSerializer(driverConfig);
+  const serializer = createSQLSerializer(driverConfig, sqliteStorageMode);
   const serialized: Record<string, unknown> = {};
+  const missingColumns: string[] = [];
 
   for (const col of indexColumns) {
-    const value = cursor.indexValues[col.ormName];
-    if (value !== undefined) {
-      // 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);
+    const value = cursor.indexValues[col.name];
+    if (value === undefined) {
+      missingColumns.push(col.name);
+      continue;
     }
+    // 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.name] = serializer.serialize(resolved, col);
+  }
+
+  if (missingColumns.length > 0) {
+    const suffix = cursor.indexName ? ` for index "${cursor.indexName}"` : "";
+    const columns = missingColumns.map((name) => `"${name}"`).join(", ");
+    const plural = missingColumns.length === 1 ? "" : "s";
+    throw new Error(`Cursor is missing values for index column${plural} ${columns}${suffix}.`);
   }
 
   return serialized;
 }
+
+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/db-now.ts

@@ -0,0 +1,6 @@
+export type DbNow = { tag: "db-now" };
+
+export const dbNow = (): DbNow => ({ tag: "db-now" });
+
+export const isDbNow = (value: unknown): value is DbNow =>
+  typeof value === "object" && value !== null && (value as { tag?: string }).tag === "db-now";

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

@@ -13,7 +13,7 @@ import type { ConditionBuilder } from "./condition-builder";
 
 describe("query type tests", () => {
   // Create test schema
-  const _testSchema = schema((s) => {
+  const _testSchema = schema("_test", (s) => {
     return s
       .addTable("users", (t) => {
         return t
@@ -337,7 +337,7 @@ describe("query type tests", () => {
   });
 
   describe("join", () => {
-    const userSchema = schema((s) => {
+    const userSchema = schema("user", (s) => {
       return s
         .addTable("users", (t) => {
           return t.addColumn("id", idColumn()).addColumn("name", column("string"));

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

@@ -1,4 +1,5 @@
 import type { DriverConfig } from "../../adapters/generic-sql/driver-config";
+import type { SQLiteStorageMode } from "../../adapters/generic-sql/sqlite-storage";
 import { SQLSerializer } from "./sql-serializer";
 import { SQLiteSerializer } from "./dialect/sqlite-serializer";
 import { PostgreSQLSerializer } from "./dialect/postgres-serializer";
@@ -14,9 +15,13 @@ export { SQLSerializer } from "./sql-serializer";
  * (PostgreSQL, MySQL, or SQLite).
  *
  * @param driverConfig - The driver configuration
+ * @param sqliteStorageMode - Optional SQLite storage mode override
  * @returns Dialect-specific SQLSerializer instance
  */
-export function createSQLSerializer(driverConfig: DriverConfig): SQLSerializer {
+export function createSQLSerializer(
+  driverConfig: DriverConfig,
+  sqliteStorageMode?: SQLiteStorageMode,
+): 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) {
@@ -25,7 +30,7 @@ export function createSQLSerializer(driverConfig: DriverConfig): SQLSerializer {
     case "mysql":
       return new MySQLSerializer(driverConfig);
     case "sqlite":
-      return new SQLiteSerializer(driverConfig);
+      return new SQLiteSerializer(driverConfig, sqliteStorageMode);
     default: {
       const exhaustiveCheck: never = driverConfig.databaseType;
       throw new Error(`Unsupported database type: ${exhaustiveCheck}`);