@fragno-dev/db 0.1.14 → 0.2.0

package/src/query/{result-transform.test.ts → value-decoding.test.ts}

@@ -1,268 +1,11 @@
 import { assert, describe, expect, it } from "vitest";
 import { column, idColumn, referenceColumn, schema, FragnoId } from "../schema/create";
-import { decodeResult, encodeValues, ReferenceSubquery } from "./result-transform";
-
-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 encode string values", () => {
-      const result = encodeValues(
-        { id: "user1", name: "John", email: "john@example.com" },
-        usersTable,
-        false,
-        "sqlite",
-      );
-
-      expect(result).toEqual({
-        id: "user1",
-        name: "John",
-        email: "john@example.com",
-      });
-    });
-
-    it("should encode integer values", () => {
-      const result = encodeValues({ age: 25 }, usersTable, false, "sqlite");
-
-      expect(result).toEqual({ age: 25 });
-    });
-
-    it("should encode boolean values for sqlite", () => {
-      const result = encodeValues({ isActive: true }, usersTable, false, "sqlite");
-
-      expect(result).toEqual({ isActive: 1 });
-    });
-
-    it("should encode boolean values for postgresql", () => {
-      const result = encodeValues({ isActive: true }, usersTable, false, "postgresql");
-
-      expect(result).toEqual({ isActive: true });
-    });
-  });
-
-  describe("date encoding", () => {
-    it("should encode Date to number for sqlite", () => {
-      const date = new Date("2024-01-15T10:30:00Z");
-      const result = encodeValues({ createdAt: date }, usersTable, false, "sqlite");
-
-      expect(result).toEqual({ createdAt: date.getTime() });
-    });
-
-    it("should keep Date as Date for postgresql", () => {
-      const date = new Date("2024-01-15T10:30:00Z");
-      const result = encodeValues({ createdAt: date }, usersTable, false, "postgresql");
-
-      expect(result).toEqual({ createdAt: date });
-    });
-
-    it("should keep Date as Date for mysql", () => {
-      const date = new Date("2024-01-15T10:30:00Z");
-      const result = encodeValues({ createdAt: date }, usersTable, false, "mysql");
-
-      expect(result).toEqual({ createdAt: date });
-    });
-  });
-
-  describe("nullable columns", () => {
-    it("should handle null values", () => {
-      const result = encodeValues({ age: null }, usersTable, false, "sqlite");
-
-      expect(result).toEqual({ age: null });
-    });
-
-    it("should omit undefined values", () => {
-      const result = encodeValues({ age: undefined }, usersTable, false, "sqlite");
-
-      expect(result).toEqual({});
-    });
-
-    it("should handle nullable timestamp", () => {
-      const result = encodeValues({ publishedAt: null }, postsTable, false, "sqlite");
-
-      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,
-        "sqlite",
-      );
-
-      expect(result["title"]).toBe("Test Post");
-      expect(result["userId"]).instanceOf(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,
-        "sqlite",
-      );
-
-      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,
-        "sqlite",
-      );
-
-      expect(result["viewCount"]).toBe(100);
-    });
-  });
-
-  describe("complete record encoding", () => {
-    it("should encode all fields correctly", () => {
-      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,
-        "sqlite",
-      );
-
-      expect(result).toEqual({
-        id: "user1",
-        name: "Alice",
-        email: "alice@example.com",
-        age: 30,
-        isActive: 0,
-        createdAt: date.getTime(),
-      });
-    });
-  });
-
-  describe("FragnoId encoding", () => {
-    it("should encode FragnoId with external ID only", () => {
-      const fragnoId = FragnoId.fromExternal("user123", 1);
-      const result = encodeValues({ id: fragnoId, name: "John" }, usersTable, false, "postgresql");
-
-      expect(result).toEqual({
-        id: "user123",
-        name: "John",
-      });
-    });
-
-    it("should encode FragnoId with both IDs", () => {
-      const fragnoId = new FragnoId({
-        externalId: "user123",
-        internalId: BigInt(456),
-        version: 1,
-      });
-      const result = encodeValues({ id: fragnoId, name: "John" }, usersTable, false, "postgresql");
-
-      expect(result).toEqual({
-        id: "user123",
-        name: "John",
-      });
-    });
-
-    it("should encode 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,
-        "postgresql",
-      );
-
-      // Reference columns should use the internal ID (bigint)
-      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,
-        "postgresql",
-      );
-
-      // 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 across providers
-      const sqliteResult = encodeValues(testData, usersTable, false, "sqlite");
-      const postgresqlResult = encodeValues(testData, usersTable, false, "postgresql");
-      const mysqlResult = encodeValues(testData, usersTable, false, "mysql");
-
-      expect(sqliteResult).toEqual({ id: "user123", name: "John" });
-      expect(postgresqlResult).toEqual({ id: "user123", name: "John" });
-      expect(mysqlResult).toEqual({ id: "user123", name: "John" });
-    });
-  });
-});
+import { decodeResult } from "./value-decoding";
+import {
+  SQLocalDriverConfig,
+  NodePostgresDriverConfig,
+  MySQL2DriverConfig,
+} from "../adapters/generic-sql/driver-config";
 
 describe("decodeResult", () => {
   const testSchema = schema((s) => {
@@ -295,12 +38,16 @@ describe("decodeResult", () => {
   const usersTable = testSchema.tables.users;
   const postsTable = testSchema.tables.posts;
 
+  const sqliteConfig = new SQLocalDriverConfig();
+  const postgresqlConfig = new NodePostgresDriverConfig();
+  const mysqlConfig = new MySQL2DriverConfig();
+
   describe("basic decoding", () => {
     it("should decode string values", () => {
       const result = decodeResult(
         { id: "user1", name: "John", email: "john@example.com" },
         usersTable,
-        "sqlite",
+        sqliteConfig,
       );
 
       expect(result).toEqual({
@@ -311,25 +58,25 @@ describe("decodeResult", () => {
     });
 
     it("should decode integer values", () => {
-      const result = decodeResult({ age: 25 }, usersTable, "sqlite");
+      const result = decodeResult({ age: 25 }, usersTable, sqliteConfig);
 
       expect(result).toEqual({ age: 25 });
     });
 
     it("should decode boolean values from sqlite", () => {
-      const result = decodeResult({ isActive: 1 }, usersTable, "sqlite");
+      const result = decodeResult({ isActive: 1 }, usersTable, sqliteConfig);
 
       expect(result).toEqual({ isActive: true });
     });
 
     it("should decode boolean false from sqlite", () => {
-      const result = decodeResult({ isActive: 0 }, usersTable, "sqlite");
+      const result = decodeResult({ isActive: 0 }, usersTable, sqliteConfig);
 
       expect(result).toEqual({ isActive: false });
     });
 
     it("should decode boolean values from postgresql", () => {
-      const result = decodeResult({ isActive: true }, usersTable, "postgresql");
+      const result = decodeResult({ isActive: true }, usersTable, postgresqlConfig);
 
       expect(result).toEqual({ isActive: true });
     });
@@ -338,7 +85,7 @@ describe("decodeResult", () => {
   describe("date decoding", () => {
     it("should decode number to Date for sqlite timestamp", () => {
       const timestamp = 1705317000000;
-      const result = decodeResult({ createdAt: timestamp }, usersTable, "sqlite");
+      const result = decodeResult({ createdAt: timestamp }, usersTable, sqliteConfig);
 
       expect(result["createdAt"]).toBeInstanceOf(Date);
       expect((result["createdAt"] as Date).getTime()).toBe(timestamp);
@@ -346,7 +93,7 @@ describe("decodeResult", () => {
 
     it("should decode ISO string to Date for sqlite timestamp", () => {
       const isoString = "2024-01-15T10:30:00.000Z";
-      const result = decodeResult({ createdAt: isoString }, usersTable, "sqlite");
+      const result = decodeResult({ createdAt: isoString }, usersTable, sqliteConfig);
 
       expect(result["createdAt"]).toBeInstanceOf(Date);
       expect((result["createdAt"] as Date).toISOString()).toBe(isoString);
@@ -354,7 +101,7 @@ describe("decodeResult", () => {
 
     it("should keep Date as Date for postgresql", () => {
       const date = new Date("2024-01-15T10:30:00Z");
-      const result = decodeResult({ createdAt: date }, usersTable, "postgresql");
+      const result = decodeResult({ createdAt: date }, usersTable, postgresqlConfig);
 
       expect(result["createdAt"]).toBe(date);
     });
@@ -362,13 +109,13 @@ describe("decodeResult", () => {
 
   describe("nullable columns", () => {
     it("should handle null values", () => {
-      const result = decodeResult({ age: null }, usersTable, "sqlite");
+      const result = decodeResult({ age: null }, usersTable, sqliteConfig);
 
       expect(result).toEqual({ age: null });
     });
 
     it("should handle nullable timestamp", () => {
-      const result = decodeResult({ publishedAt: null }, postsTable, "sqlite");
+      const result = decodeResult({ publishedAt: null }, postsTable, sqliteConfig);
 
       expect(result).toEqual({ publishedAt: null });
     });
@@ -385,7 +132,7 @@ describe("decodeResult", () => {
           "author:email": "alice@example.com",
         },
         postsTable,
-        "sqlite",
+        sqliteConfig,
       );
 
       expect(result).toEqual({
@@ -410,7 +157,7 @@ describe("decodeResult", () => {
           "author:createdAt": timestamp,
         },
         postsTable,
-        "sqlite",
+        sqliteConfig,
       );
 
       expect(result["author"]).toEqual({
@@ -428,7 +175,7 @@ describe("decodeResult", () => {
           "unknownRelation:field": "value",
         },
         postsTable,
-        "sqlite",
+        sqliteConfig,
       );
 
       expect(result).toEqual({
@@ -446,7 +193,7 @@ describe("decodeResult", () => {
           "author:unknownField": "value",
         },
         postsTable,
-        "sqlite",
+        sqliteConfig,
       );
 
       expect(result).toEqual({
@@ -496,7 +243,7 @@ describe("decodeResult", () => {
           "category:name": "Technology",
         },
         schemaWithMultipleRelations.tables.posts,
-        "sqlite",
+        sqliteConfig,
       );
 
       expect(result).toEqual({
@@ -526,7 +273,7 @@ describe("decodeResult", () => {
           "author:name": "Alice",
         },
         postsTable,
-        "sqlite",
+        sqliteConfig,
       );
 
       // Main table id should be FragnoId
@@ -557,7 +304,7 @@ describe("decodeResult", () => {
           createdAt: timestamp,
         },
         usersTable,
-        "sqlite",
+        sqliteConfig,
       );
 
       expect(result).toEqual({
@@ -573,7 +320,7 @@ describe("decodeResult", () => {
 
   describe("edge cases", () => {
     it("should handle empty result", () => {
-      const result = decodeResult({}, usersTable, "sqlite");
+      const result = decodeResult({}, usersTable, sqliteConfig);
 
       expect(result).toEqual({});
     });
@@ -585,7 +332,7 @@ describe("decodeResult", () => {
           "author:name": "Alice",
         },
         postsTable,
-        "sqlite",
+        sqliteConfig,
       );
 
       expect(result).toEqual({
@@ -608,7 +355,7 @@ describe("decodeResult", () => {
           "author:name": "Alice",
         },
         postsTable,
-        "sqlite",
+        sqliteConfig,
       );
 
       expect(result).toEqual({
@@ -633,14 +380,14 @@ describe("decodeResult", () => {
           name: "John",
         },
         usersTable,
-        "postgresql",
+        postgresqlConfig,
       );
 
       const fragnoId = result["id"];
       assert(fragnoId instanceof FragnoId);
 
       expect(fragnoId.externalId).toBe("user123");
-      expect(fragnoId.internalId).toBe(456);
+      expect(fragnoId.internalId).toBe(456n);
       expect(result["name"]).toBe("John");
     });
 
@@ -652,7 +399,7 @@ describe("decodeResult", () => {
           name: "John",
         },
         usersTable,
-        "postgresql",
+        postgresqlConfig,
       );
 
       const fragnoId = result["id"];
@@ -670,7 +417,7 @@ describe("decodeResult", () => {
           name: "John",
         },
         usersTable,
-        "postgresql",
+        postgresqlConfig,
       );
 
       expect(result).toEqual({
@@ -688,9 +435,9 @@ describe("decodeResult", () => {
       };
 
       // Test across providers
-      const sqliteResult = decodeResult(testData, usersTable, "sqlite");
-      const postgresqlResult = decodeResult(testData, usersTable, "postgresql");
-      const mysqlResult = decodeResult(testData, usersTable, "mysql");
+      const sqliteResult = decodeResult(testData, usersTable, sqliteConfig);
+      const postgresqlResult = decodeResult(testData, usersTable, postgresqlConfig);
+      const mysqlResult = decodeResult(testData, usersTable, mysqlConfig);
 
       // All should create FragnoId objects
       expect(sqliteResult["id"]).toBeInstanceOf(FragnoId);
@@ -698,7 +445,7 @@ describe("decodeResult", () => {
       expect(mysqlResult["id"]).toBeInstanceOf(FragnoId);
 
       expect((sqliteResult["id"] as FragnoId).externalId).toBe("user123");
-      expect((sqliteResult["id"] as FragnoId).internalId).toBe(456);
+      expect((sqliteResult["id"] as FragnoId).internalId).toBe(456n);
     });
 
     it("should create FragnoId in relation data when both IDs present", () => {
@@ -712,7 +459,7 @@ describe("decodeResult", () => {
           "author:name": "Alice",
         },
         postsTable,
-        "postgresql",
+        postgresqlConfig,
       );
 
       expect(result["id"]).toBe("post1");
@@ -721,7 +468,7 @@ describe("decodeResult", () => {
       const author: Record<string, unknown> = result["author"] as Record<string, unknown>;
       assert(author["id"] instanceof FragnoId);
       expect(author["id"].externalId).toBe("user123");
-      expect(author["id"].internalId).toBe(456);
+      expect(author["id"].internalId).toBe(456n);
       expect(author["name"]).toBe("Alice");
     });
 
@@ -734,7 +481,7 @@ describe("decodeResult", () => {
           "author:name": "Alice",
         },
         postsTable,
-        "postgresql",
+        postgresqlConfig,
       );
 
       expect(result).toEqual({
@@ -762,12 +509,12 @@ describe("decodeResult", () => {
           createdAt: timestamp,
         },
         usersTable,
-        "sqlite",
+        sqliteConfig,
       );
 
       expect(result["id"]).toBeInstanceOf(FragnoId);
       expect((result["id"] as FragnoId).externalId).toBe("user123");
-      expect((result["id"] as FragnoId).internalId).toBe(456);
+      expect((result["id"] as FragnoId).internalId).toBe(456n);
       expect(result["name"]).toBe("Alice");
       expect(result["email"]).toBe("alice@example.com");
       expect(result["age"]).toBe(30);
@@ -783,12 +530,12 @@ describe("decodeResult", () => {
           name: "John",
         },
         usersTable,
-        "postgresql",
+        postgresqlConfig,
       );
 
       expect(result["id"]).toBeInstanceOf(FragnoId);
       expect((result["id"] as FragnoId).externalId).toBe("user123");
-      expect((result["id"] as FragnoId).internalId).toBe(789);
+      expect((result["id"] as FragnoId).internalId).toBe(789n);
       expect(result["name"]).toBe("John");
     });
   });

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