@fragno-dev/db 0.1.15 → 0.2.0

package/src/query/value-decoding.ts

@@ -0,0 +1,113 @@
+import type { AnyTable } from "../schema/create";
+import { createSQLSerializer } from "./serialize/create-sql-serializer";
+import { FragnoId, FragnoReference } from "../schema/create";
+import type { DriverConfig } from "../adapters/generic-sql/driver-config";
+
+/**
+ * Decodes a database result record to application format.
+ *
+ * This function transforms database column names back to application property names
+ * and deserializes values according to the database provider's format (e.g., converting
+ * SQLite integers back to JavaScript Date objects).
+ *
+ * Supports relation data encoded with the pattern `relationName:columnName`.
+ *
+ * @param result - The raw database result record
+ * @param table - The table schema definition containing column and relation information
+ * @param driverConfig - The driver configuration containing database type information
+ * @returns A record in application format with deserialized values
+ *
+ * @example
+ * ```ts
+ * const decoded = decodeResult(
+ *   { user_id: 123, created_at: 1234567890, 'posts:title': 'Hello' },
+ *   userTable,
+ *   driverConfig
+ * );
+ * // Returns: { userId: 123, createdAt: Date, posts: { title: 'Hello' } }
+ * ```
+ */
+export function decodeResult(
+  result: Record<string, unknown>,
+  table: AnyTable,
+  driverConfig: DriverConfig,
+): Record<string, unknown> {
+  const serializer = createSQLSerializer(driverConfig);
+  const output: Record<string, unknown> = {};
+  // First pass: collect all column values
+  const columnValues: Record<string, unknown> = {};
+
+  // Collect all relation data (including nested) keyed by relation name
+  const relationData: Record<string, Record<string, unknown>> = {};
+
+  for (const k in result) {
+    const colonIndex = k.indexOf(":");
+    const value = result[k];
+
+    // Direct column (no colon)
+    if (colonIndex === -1) {
+      const col = table.columns[k];
+      if (!col) {
+        continue;
+      }
+
+      // Store all column values (including hidden ones for FragnoId creation)
+      columnValues[k] = serializer.deserialize(value, col);
+      continue;
+    }
+
+    // Relation column (has colon)
+    const relationName = k.slice(0, colonIndex);
+    const remainder = k.slice(colonIndex + 1);
+
+    const relation = table.relations[relationName];
+    if (relation === undefined) {
+      continue;
+    }
+
+    // Collect relation data with the remaining key path
+    relationData[relationName] ??= {};
+    relationData[relationName][remainder] = value;
+  }
+
+  // Process each relation's data recursively
+  for (const relationName in relationData) {
+    const relation = table.relations[relationName];
+    if (!relation) {
+      continue;
+    }
+
+    // Recursively decode the relation data
+    output[relationName] = decodeResult(relationData[relationName], relation.table, driverConfig);
+  }
+
+  // Second pass: create output with FragnoId objects where appropriate
+  for (const k in columnValues) {
+    const col = table.columns[k];
+    if (!col) {
+      continue;
+    }
+
+    // Filter out hidden columns (like _internalId, _version) from results
+    if (col.isHidden) {
+      continue;
+    }
+
+    // For external ID columns, create FragnoId if we have both external and internal IDs
+    if (col.role === "external-id" && columnValues["_internalId"] !== undefined) {
+      output[k] = new FragnoId({
+        externalId: columnValues[k] as string,
+        internalId: columnValues["_internalId"] as bigint,
+        // _version is always selected as a hidden column, so it should always be present
+        version: columnValues["_version"] as number,
+      });
+    } else if (col.role === "reference") {
+      // For reference columns, create FragnoReference with internal ID
+      output[k] = FragnoReference.fromInternal(columnValues[k] as bigint);
+    } else {
+      output[k] = columnValues[k];
+    }
+  }
+
+  return output;
+}

package/src/query/value-encoding.test.ts

@@ -0,0 +1,390 @@
+import { describe, expect, it } from "vitest";
+import {
+  column,
+  FragnoId,
+  FragnoReference,
+  idColumn,
+  schema,
+  referenceColumn,
+} from "../schema/create";
+import { resolveFragnoIdValue, encodeValues, ReferenceSubquery } from "./value-encoding";
+
+describe("encodeValues", () => {
+  const testSchema = schema((s) => {
+    return s
+      .addTable("users", (t) => {
+        return t
+          .addColumn("id", idColumn())
+          .addColumn("name", column("string"))
+          .addColumn("email", column("string"))
+          .addColumn("age", column("integer").nullable())
+          .addColumn("isActive", column("bool"))
+          .addColumn("createdAt", column("timestamp"));
+      })
+      .addTable("posts", (t) => {
+        return t
+          .addColumn("id", idColumn())
+          .addColumn("title", column("string"))
+          .addColumn("userId", referenceColumn())
+          .addColumn("viewCount", column("integer").defaultTo(0))
+          .addColumn("publishedAt", column("timestamp").nullable());
+      })
+      .addReference("author", {
+        type: "one",
+        from: { table: "posts", column: "userId" },
+        to: { table: "users", column: "id" },
+      });
+  });
+
+  const usersTable = testSchema.tables.users;
+  const postsTable = testSchema.tables.posts;
+
+  describe("basic encoding", () => {
+    it("should resolve string values", () => {
+      const result = encodeValues(
+        { id: "user1", name: "John", email: "john@example.com" },
+        usersTable,
+        false,
+      );
+
+      expect(result).toEqual({
+        id: "user1",
+        name: "John",
+        email: "john@example.com",
+      });
+    });
+
+    it("should resolve integer values", () => {
+      const result = encodeValues({ age: 25 }, usersTable, false);
+
+      expect(result).toEqual({ age: 25 });
+    });
+
+    it("should resolve boolean values (not serialized)", () => {
+      const result = encodeValues({ isActive: true }, usersTable, false);
+
+      // Boolean stays as boolean (not converted to 0/1)
+      expect(result).toEqual({ isActive: true });
+    });
+  });
+
+  describe("date encoding", () => {
+    it("should keep Date as Date (not serialized)", () => {
+      const date = new Date("2024-01-15T10:30:00Z");
+      const result = encodeValues({ createdAt: date }, usersTable, false);
+
+      // Date stays as Date (serialization happens later in encoder)
+      expect(result).toEqual({ createdAt: date });
+    });
+  });
+
+  describe("nullable columns", () => {
+    it("should handle null values", () => {
+      const result = encodeValues({ age: null }, usersTable, false);
+
+      expect(result).toEqual({ age: null });
+    });
+
+    it("should omit undefined values", () => {
+      const result = encodeValues({ age: undefined }, usersTable, false);
+
+      expect(result).toEqual({});
+    });
+
+    it("should handle nullable timestamp", () => {
+      const result = encodeValues({ publishedAt: null }, postsTable, false);
+
+      expect(result).toEqual({ publishedAt: null });
+    });
+  });
+
+  describe("default value generation", () => {
+    it("should generate runtime defaults when generateDefault is true", () => {
+      const result = encodeValues({ title: "Test Post", userId: "user1" }, postsTable, true);
+
+      expect(result["title"]).toBe("Test Post");
+      expect(result["userId"]).toBeInstanceOf(ReferenceSubquery);
+      // viewCount has static default (defaultTo), so it's omitted to let DB handle it
+      expect(result["viewCount"]).toBeUndefined();
+      expect(result["id"]).toBeDefined();
+      expect(typeof result["id"]).toBe("string");
+    });
+
+    it("should not generate default values when generateDefault is false", () => {
+      const result = encodeValues({ title: "Test Post", userId: "user1" }, postsTable, false);
+
+      expect(result).toEqual({
+        title: "Test Post",
+        userId: expect.any(ReferenceSubquery),
+      });
+    });
+
+    it("should not override explicitly provided values", () => {
+      const result = encodeValues(
+        { title: "Test Post", userId: "user1", viewCount: 100 },
+        postsTable,
+        true,
+      );
+
+      expect(result["viewCount"]).toBe(100);
+    });
+  });
+
+  describe("complete record encoding", () => {
+    it("should resolve all fields correctly (without serialization)", () => {
+      const date = new Date("2024-01-15T10:30:00Z");
+      const result = encodeValues(
+        {
+          id: "user1",
+          name: "Alice",
+          email: "alice@example.com",
+          age: 30,
+          isActive: false,
+          createdAt: date,
+        },
+        usersTable,
+        false,
+      );
+
+      // Values are resolved but NOT serialized (Date stays as Date, boolean stays as boolean)
+      expect(result).toEqual({
+        id: "user1",
+        name: "Alice",
+        email: "alice@example.com",
+        age: 30,
+        isActive: false, // Not serialized to 0
+        createdAt: date, // Not serialized to timestamp
+      });
+    });
+  });
+
+  describe("FragnoId encoding", () => {
+    it("should resolve FragnoId with external ID only", () => {
+      const fragnoId = FragnoId.fromExternal("user123", 1);
+      const result = encodeValues({ id: fragnoId, name: "John" }, usersTable, false);
+
+      expect(result).toEqual({
+        id: "user123",
+        name: "John",
+      });
+    });
+
+    it("should resolve FragnoId with both IDs", () => {
+      const fragnoId = new FragnoId({
+        externalId: "user123",
+        internalId: BigInt(456),
+        version: 1,
+      });
+      const result = encodeValues({ id: fragnoId, name: "John" }, usersTable, false);
+
+      expect(result).toEqual({
+        id: "user123",
+        name: "John",
+      });
+    });
+
+    it("should resolve FragnoId in reference columns", () => {
+      const fragnoId = new FragnoId({
+        externalId: "user123",
+        internalId: BigInt(456),
+        version: 1,
+      });
+      const result = encodeValues({ title: "Test Post", userId: fragnoId }, postsTable, false);
+
+      // Reference columns should use the internal ID (bigint, not serialized)
+      expect(result).toEqual({
+        title: "Test Post",
+        userId: BigInt(456),
+      });
+    });
+
+    it("should convert FragnoId without internalId to ReferenceSubquery for reference columns", () => {
+      const fragnoId = new FragnoId({
+        externalId: "user123",
+        version: 1,
+      });
+      const result = encodeValues({ title: "Test Post", userId: fragnoId }, postsTable, false);
+
+      // FragnoId without internalId should be converted to ReferenceSubquery for database lookup
+      expect(result["title"]).toBe("Test Post");
+      expect(result["userId"]).toBeInstanceOf(ReferenceSubquery);
+      expect((result["userId"] as ReferenceSubquery).externalIdValue).toBe("user123");
+    });
+
+    it("should handle FragnoId across different providers", () => {
+      const fragnoId = new FragnoId({
+        externalId: "user123",
+        internalId: BigInt(456),
+        version: 1,
+      });
+      const testData = { id: fragnoId, name: "John" };
+
+      // Test that provider-agnostic resolution works
+      const result = encodeValues(testData, usersTable, false);
+
+      expect(result).toEqual({ id: "user123", name: "John" });
+    });
+
+    it("should handle ReferenceSubquery correctly", () => {
+      const fragnoId = FragnoId.fromExternal("user123", 1);
+      const result = encodeValues({ id: fragnoId, name: "John" }, usersTable, false);
+
+      // FragnoId handling should still work
+      expect(result).toEqual({
+        id: "user123",
+        name: "John",
+      });
+
+      // Test ReferenceSubquery
+      const refResult = encodeValues(
+        { title: "Test Post", userId: "user_external_id" },
+        postsTable,
+        false,
+      );
+
+      expect(refResult["title"]).toBe("Test Post");
+      expect(refResult["userId"]).toBeInstanceOf(ReferenceSubquery);
+    });
+  });
+});
+
+describe("resolveFragnoIdValue", () => {
+  describe("FragnoReference handling", () => {
+    it("should extract internal ID from FragnoReference", () => {
+      const ref = FragnoReference.fromInternal(BigInt(123));
+      const col = column("bigint");
+      col.role = "reference";
+
+      const result = resolveFragnoIdValue(ref, col);
+
+      expect(result).toBe(BigInt(123));
+    });
+  });
+
+  describe("FragnoId handling for external-id columns", () => {
+    it("should extract external ID from FragnoId", () => {
+      const externalIdCol = column("string");
+      externalIdCol.role = "external-id";
+      const fragnoId = new FragnoId({
+        externalId: "user123",
+        internalId: BigInt(456),
+        version: 1,
+      });
+
+      const result = resolveFragnoIdValue(fragnoId, externalIdCol);
+
+      expect(result).toBe("user123");
+    });
+
+    it("should work with FragnoId created from fromExternal", () => {
+      const externalIdCol = column("string");
+      externalIdCol.role = "external-id";
+      const fragnoId = FragnoId.fromExternal("user789", 2);
+
+      const result = resolveFragnoIdValue(fragnoId, externalIdCol);
+
+      expect(result).toBe("user789");
+    });
+  });
+
+  describe("FragnoId handling for internal-id columns", () => {
+    it("should extract internal ID from FragnoId", () => {
+      const internalIdCol = column("bigint");
+      internalIdCol.role = "internal-id";
+      const fragnoId = new FragnoId({
+        externalId: "user123",
+        internalId: BigInt(456),
+        version: 1,
+      });
+
+      const result = resolveFragnoIdValue(fragnoId, internalIdCol);
+
+      expect(result).toBe(BigInt(456));
+    });
+
+    it("should throw error when FragnoId lacks internal ID", () => {
+      const internalIdCol = column("bigint");
+      internalIdCol.role = "internal-id";
+      const fragnoId = FragnoId.fromExternal("user123", 1);
+
+      expect(() => resolveFragnoIdValue(fragnoId, internalIdCol)).toThrow(
+        "FragnoId must have internalId for internal-id column",
+      );
+    });
+  });
+
+  describe("FragnoId handling for reference columns", () => {
+    it("should prefer internal ID when available", () => {
+      const referenceCol = column("bigint");
+      referenceCol.role = "reference";
+      const fragnoId = new FragnoId({
+        externalId: "user123",
+        internalId: BigInt(456),
+        version: 1,
+      });
+
+      const result = resolveFragnoIdValue(fragnoId, referenceCol);
+
+      expect(result).toBe(BigInt(456));
+    });
+
+    it("should fallback to external ID when internal ID unavailable", () => {
+      const referenceCol = column("bigint");
+      referenceCol.role = "reference";
+      const fragnoId = FragnoId.fromExternal("user123", 1);
+
+      const result = resolveFragnoIdValue(fragnoId, referenceCol);
+
+      expect(result).toBe("user123");
+    });
+  });
+
+  describe("FragnoId handling for regular columns", () => {
+    it("should use external ID for regular columns", () => {
+      const regularCol = column("string");
+      regularCol.role = "regular";
+      const fragnoId = new FragnoId({
+        externalId: "user123",
+        internalId: BigInt(456),
+        version: 1,
+      });
+
+      const result = resolveFragnoIdValue(fragnoId, regularCol);
+
+      expect(result).toBe("user123");
+    });
+  });
+
+  describe("non-FragnoId values", () => {
+    it("should pass through strings", () => {
+      const col = column("string");
+      const result = resolveFragnoIdValue("hello", col);
+      expect(result).toBe("hello");
+    });
+
+    it("should pass through numbers", () => {
+      const col = column("integer");
+      const result = resolveFragnoIdValue(42, col);
+      expect(result).toBe(42);
+    });
+
+    it("should pass through dates", () => {
+      const col = column("timestamp");
+      const date = new Date();
+      const result = resolveFragnoIdValue(date, col);
+      expect(result).toBe(date);
+    });
+
+    it("should pass through null", () => {
+      const col = column("string").nullable();
+      const result = resolveFragnoIdValue(null, col);
+      expect(result).toBe(null);
+    });
+
+    it("should pass through bigint", () => {
+      const col = column("bigint");
+      const result = resolveFragnoIdValue(BigInt(999), col);
+      expect(result).toBe(BigInt(999));
+    });
+  });
+});

package/src/query/value-encoding.ts

@@ -0,0 +1,168 @@
+import type { AnyTable, AnyColumn } from "../schema/create";
+import { FragnoId, FragnoReference } from "../schema/create";
+import { generateRuntimeDefault } from "./column-defaults";
+
+/**
+ * Marker class for reference column values that need subquery resolution.
+ * When a reference column receives a string (external ID), this marker tells
+ * the query builder to generate a subquery to look up the internal ID.
+ * @internal
+ */
+export class ReferenceSubquery {
+  #referencedTable: AnyTable;
+  #externalIdValue: string;
+
+  constructor(referencedTable: AnyTable, externalIdValue: string) {
+    this.#referencedTable = referencedTable;
+    this.#externalIdValue = externalIdValue;
+  }
+
+  get referencedTable() {
+    return this.#referencedTable;
+  }
+
+  get externalIdValue() {
+    return this.#externalIdValue;
+  }
+}
+
+/**
+ * Resolves FragnoId or FragnoReference objects to their appropriate primitive values.
+ *
+ * This function handles the Fragno ID system's conversion to database values:
+ * - FragnoReference objects are resolved to their internal IDs
+ * - FragnoId objects are resolved based on the column role:
+ *   - external-id: uses the external ID
+ *   - internal-id: uses the internal ID (must be present)
+ *   - reference: uses databaseId (internal ID if available, else external ID)
+ *   - other: uses the external ID by default
+ *
+ * @param value - The value to resolve (may be FragnoId, FragnoReference, or any other value)
+ * @param col - The column schema definition
+ * @returns The resolved primitive value, or the original value if not a FragnoId/FragnoReference
+ * @throws Error if internal ID is required but not available
+ * @internal
+ */
+export function resolveFragnoIdValue(value: unknown, col: AnyColumn): unknown {
+  // Handle FragnoReference objects (for reference columns)
+  if (value instanceof FragnoReference) {
+    return value.internalId;
+  }
+
+  // Handle FragnoId objects
+  if (value instanceof FragnoId) {
+    // For external ID columns, use the external ID
+    if (col.role === "external-id") {
+      return value.externalId;
+    }
+    // For internal ID columns, use the internal ID (must be present)
+    if (col.role === "internal-id") {
+      if (value.internalId === undefined) {
+        throw new Error(`FragnoId must have internalId for internal-id column ${col.name}`);
+      }
+      return value.internalId;
+    }
+    // For reference columns, prefer internal ID if available, else external ID
+    if (col.role === "reference") {
+      return value.databaseId;
+    }
+    // Default to external ID for other columns
+    return value.externalId;
+  }
+
+  return value;
+}
+
+/**
+ * Encodes a record of values from the application format to resolved format.
+ *
+ * This function:
+ * - Transforms object keys from ORM names to database column names
+ * - Resolves FragnoId/FragnoReference objects to primitive values
+ * - Generates default values for undefined columns
+ * - Creates ReferenceSubquery markers for external ID lookups
+ *
+ * Note: This function does NOT serialize values (Date → number, bigint → Buffer, etc.).
+ * Use UnitOfWorkEncoder.encode() to apply driver-specific serialization after this step.
+ *
+ * @param values - The record of values to encode in application format
+ * @param table - The table schema definition containing column information
+ * @param generateDefault - Whether to generate default values for undefined columns
+ * @returns A record with database column names and resolved (but not serialized) values
+ *
+ * @example
+ * ```ts
+ * const encoded = encodeValues(
+ *   { userId: 123, createdAt: new Date() },
+ *   userTable,
+ *   true
+ * );
+ * // Returns: { user_id: 123, created_at: Date } (not yet serialized)
+ * ```
+ */
+export function encodeValues(
+  values: Record<string, unknown>,
+  table: AnyTable,
+  generateDefault: boolean,
+): Record<string, unknown> {
+  const result: Record<string, unknown> = {};
+
+  for (const k in table.columns) {
+    const col = table.columns[k];
+
+    // Skip internal ID - never provided by user, auto-generated by database
+    if (col.role === "internal-id") {
+      continue;
+    }
+    let value = values[k];
+
+    if (generateDefault && value === undefined) {
+      // Only generate runtime defaults (defaultTo$), not static defaults (defaultTo).
+      // Static defaults should be handled by the database via DEFAULT constraints.
+      value = generateRuntimeDefault(col);
+    }
+
+    if (value !== undefined) {
+      // Handle reference columns: strings or FragnoIds without internal IDs need subqueries
+      if (col.role === "reference") {
+        let needsSubquery = false;
+        let externalIdForSubquery: string | undefined;
+
+        if (typeof value === "string") {
+          // String external ID - needs subquery
+          needsSubquery = true;
+          externalIdForSubquery = value;
+        } else if (value instanceof FragnoId && value.internalId === undefined) {
+          // FragnoId without internal ID - needs subquery
+          needsSubquery = true;
+          externalIdForSubquery = value.externalId;
+        } else if (value instanceof FragnoId && value.internalId !== undefined) {
+          // FragnoId with internal ID - use it directly (will be serialized later)
+          result[col.name] = value.internalId;
+          continue;
+        } else if (value instanceof FragnoReference) {
+          // FragnoReference - use internal ID directly (will be serialized later)
+          result[col.name] = value.internalId;
+          continue;
+        }
+
+        if (needsSubquery) {
+          const relation = Object.values(table.relations).find((rel) =>
+            rel.on.some(([localCol]) => localCol === k),
+          );
+          if (relation) {
+            result[col.name] = new ReferenceSubquery(relation.table, externalIdForSubquery!);
+            continue;
+          }
+          throw new Error(`Reference column ${k} not found in table ${table.name}`);
+        }
+      }
+
+      // Resolve FragnoId/FragnoReference to primitive values (serialization happens later)
+      const resolvedValue = resolveFragnoIdValue(value, col);
+      result[col.name] = resolvedValue;
+    }
+  }
+
+  return result;
+}

package/src/schema/create.test.ts

@@ -8,7 +8,11 @@ import {
   schema,
   SchemaBuilder,
 } from "./create";
-import type { RawColumnValues, TableToColumnValues, TableToInsertValues } from "../query/query";
+import type {
+  RawColumnValues,
+  TableToColumnValues,
+  TableToInsertValues,
+} from "../query/simple-query-interface";
 
 describe("create", () => {
   it("should create a table with columns using callback pattern", () => {

package/src/schema/create.ts

@@ -1,4 +1,5 @@
 import { createId } from "../id";
+import { inspect } from "node:util";
 
 export type AnySchema = Schema<Record<string, AnyTable>>;
 
@@ -547,6 +548,10 @@ export class FragnoId {
   valueOf(): string {
     return this.#externalId;
   }
+
+  [inspect.custom](): string {
+    return `FragnoId { externalId: ${this.#externalId}, internalId: ${this.#internalId?.toString()} }`;
+  }
 }
 
 /**