@fragno-dev/db 0.0.1 → 0.1.0

package/src/query/result-transform.ts

@@ -0,0 +1,247 @@
+import type { AnyColumn, AnyTable } from "../schema/create";
+import type { SQLProvider } from "../shared/providers";
+import { deserialize, serialize } from "../schema/serialize";
+import { FragnoId, FragnoReference } from "../schema/create";
+import { createId } from "../id";
+
+/**
+ * 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;
+  }
+}
+
+/**
+ * Generate a runtime default value for a column that has defaultTo$()
+ *
+ * Only generates values for runtime defaults (defaultTo$), NOT static defaults (defaultTo).
+ * Static defaults should be handled by the database via DEFAULT constraints.
+ *
+ * @param column - The column with a default value configuration
+ * @returns The generated default value, or undefined if the column has no runtime default
+ *
+ * @internal
+ */
+export function generateRuntimeDefault(column: AnyColumn): unknown {
+  // Check if column has a default value configuration
+  if (!column.default) {
+    return undefined;
+  }
+
+  // If it's a static default value (defaultTo), return undefined
+  // as the database should handle this via DEFAULT constraint
+  if ("value" in column.default) {
+    return undefined;
+  }
+
+  // Handle runtime defaults (defaultTo$)
+  const runtime = column.default.runtime;
+
+  if (runtime === "auto") {
+    return createId();
+  }
+
+  if (runtime === "now") {
+    return new Date();
+  }
+
+  if (typeof runtime === "function") {
+    return runtime();
+  }
+
+  return undefined;
+}
+
+/**
+ * Encodes a record of values from the application format to database format.
+ *
+ * This function transforms object keys to match SQL column names and serializes
+ * values according to the database provider's requirements (e.g., converting
+ * JavaScript Date objects to numbers for SQLite).
+ *
+ * @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
+ * @param provider - The SQL provider (sqlite, postgresql, mysql, etc.)
+ * @returns A record with database-compatible column names and serialized values
+ *
+ * @example
+ * ```ts
+ * const encoded = encodeValues(
+ *   { userId: 123, createdAt: new Date() },
+ *   userTable,
+ *   true,
+ *   'sqlite'
+ * );
+ * // Returns: { user_id: 123, created_at: 1234567890 }
+ * ```
+ */
+export function encodeValues(
+  values: Record<string, unknown>,
+  table: AnyTable,
+  generateDefault: boolean,
+  provider: SQLProvider,
+): 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 string references - convert external ID to internal ID via subquery
+      if (col.role === "reference" && typeof value === "string") {
+        // Find relation that uses this column
+        const relation = Object.values(table.relations).find((rel) =>
+          rel.on.some(([localCol]) => localCol === k),
+        );
+        if (relation) {
+          result[col.name] = new ReferenceSubquery(relation.table, value);
+          continue;
+        }
+
+        throw new Error(`Reference column ${k} not found in table ${table.name}`);
+      }
+
+      result[col.name] = serialize(value, col, provider);
+    }
+  }
+
+  return result;
+}
+
+/**
+ * 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 provider - The SQL provider (sqlite, postgresql, mysql, etc.)
+ * @returns A record in application format with deserialized values
+ *
+ * @example
+ * ```ts
+ * const decoded = decodeResult(
+ *   { user_id: 123, created_at: 1234567890, 'posts:title': 'Hello' },
+ *   userTable,
+ *   'sqlite'
+ * );
+ * // Returns: { userId: 123, createdAt: Date, posts: { title: 'Hello' } }
+ * ```
+ */
+export function decodeResult(
+  result: Record<string, unknown>,
+  table: AnyTable,
+  provider: SQLProvider,
+): Record<string, unknown> {
+  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] = deserialize(value, col, provider);
+      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, provider);
+  }
+
+  // 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/unit-of-work-types.test.ts

@@ -0,0 +1,192 @@
+import { describe, expectTypeOf, it } from "vitest";
+import { column, idColumn, referenceColumn, schema } from "../schema/create";
+import { createUnitOfWork, JoinFindBuilder } from "./unit-of-work";
+import type { FragnoId, FragnoReference } from "../schema/create";
+
+type Prettify<T> = {
+  [K in keyof T]: T[K];
+} & {};
+
+type RecursivePrettify<T> = {
+  [K in keyof T]: T[K] extends FragnoId
+    ? FragnoId
+    : T[K] extends FragnoReference
+      ? FragnoReference
+      : T[K] extends object
+        ? RecursivePrettify<T[K]>
+        : T[K];
+} & {};
+
+type InferJoinOut<T> =
+  T extends JoinFindBuilder<infer _Table, infer _Select, infer JoinOut> ? JoinOut : never;
+
+type InferJoinOutPrettify<T> = RecursivePrettify<InferJoinOut<T>>;
+
+describe("UnitOfWork type tests", () => {
+  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("invitedBy", referenceColumn().nullable())
+          .createIndex("idx_email", ["email"], { unique: true })
+          .createIndex("idx_name", ["name"]);
+      })
+      .addTable("posts", (t) => {
+        return t
+          .addColumn("id", idColumn())
+          .addColumn("title", column("string"))
+          .addColumn("content", column("string"))
+          .addColumn("userId", referenceColumn())
+          .createIndex("idx_user", ["userId"])
+          .createIndex("idx_title", ["title"]);
+      })
+      .addTable("comments", (t) => {
+        return t
+          .addColumn("id", idColumn())
+          .addColumn("content", column("string"))
+          .addColumn("postId", referenceColumn())
+          .addColumn("authorId", referenceColumn())
+          .createIndex("idx_post", ["postId"])
+          .createIndex("idx_author", ["authorId"]);
+      })
+      .addReference("author", {
+        type: "one",
+        from: { table: "posts", column: "userId" },
+        to: { table: "users", column: "id" },
+      })
+      .addReference("inviter", {
+        type: "one",
+        from: { table: "users", column: "invitedBy" },
+        to: { table: "users", column: "id" },
+      })
+      .addReference("post", {
+        type: "one",
+        from: { table: "comments", column: "postId" },
+        to: { table: "posts", column: "id" },
+      })
+      .addReference("author", {
+        type: "one",
+        from: { table: "comments", column: "authorId" },
+        to: { table: "users", column: "id" },
+      })
+      .addReference("posts", {
+        type: "many",
+        from: { table: "users", column: "id" },
+        to: { table: "posts", column: "userId" },
+      })
+      .addReference("comments", {
+        type: "many",
+        from: { table: "posts", column: "id" },
+        to: { table: "comments", column: "postId" },
+      });
+  });
+
+  function createTestUOW() {
+    const mockCompiler = {
+      compileRetrievalOperation: () => null,
+      compileMutationOperation: () => null,
+    };
+    const mockExecutor = {
+      executeRetrievalPhase: async () => [],
+      executeMutationPhase: async () => ({ success: true, createdInternalIds: [] }),
+    };
+    const mockDecoder = () => [];
+    return createUnitOfWork(testSchema, mockCompiler, mockExecutor, mockDecoder);
+  }
+
+  it("should type find without joins correctly", async () => {
+    const uow = createTestUOW();
+
+    const uow1 = uow.find("users", (b) => b.whereIndex("primary"));
+    const [_userResult] = await uow1.executeRetrieve();
+    type UserResult = RecursivePrettify<(typeof _userResult)[number]>;
+
+    expectTypeOf<UserResult>().toEqualTypeOf<{
+      id: FragnoId;
+      name: string;
+      email: string;
+      age: number | null;
+      invitedBy: FragnoReference | null;
+    }>();
+  });
+
+  it("should type find with joins correctly", async () => {
+    const uow = createTestUOW();
+
+    const uow1 = uow.find("users", (b) =>
+      b.whereIndex("primary").join((jb) => jb.inviter((ib) => ib.select(["name"]))),
+    );
+    const [_userResult] = await uow1.executeRetrieve();
+    type UserResult = RecursivePrettify<(typeof _userResult)[number]>;
+
+    // @ts-expect-error assert type
+    expectTypeOf<UserResult>().toEqualTypeOf<{
+      id: FragnoId;
+      name: string;
+      email: string;
+      age: number | null;
+      invitedBy: FragnoReference | null;
+      inviter: {
+        name: string;
+      } | null;
+    }>();
+  });
+
+  it("join builder without join given", () => {
+    const _builder = new JoinFindBuilder("users", testSchema.tables.users);
+    type JoinOut = InferJoinOutPrettify<typeof _builder>;
+    expectTypeOf<JoinOut>().toEqualTypeOf<{}>();
+  });
+
+  it("join builder with join given", () => {
+    const builder = new JoinFindBuilder("users", testSchema.tables.users);
+
+    /*
+    join: (jb) =>           // jb is IndexedJoinBuilder, the thing with relations as key (fns)
+      jb.posts((b) =>       // b is JoinFindBuilder
+        b.whereIndex("primary").select(["id"])
+      )
+    */
+
+    const _builderOut = builder.join((jb) => jb.inviter((ib) => ib.select(["name"])));
+    type _JoinOut = InferJoinOutPrettify<typeof _builderOut>;
+    //    ^?
+
+    type _JoinOutInviter = Prettify<_JoinOut["inviter"]>;
+    //     ^?
+
+    // FIXME: There should not be a `{}` in the type
+    expectTypeOf<_JoinOutInviter>().toEqualTypeOf<{
+      id: FragnoId;
+      name: string;
+      email: string;
+      age: number | null;
+      invitedBy: FragnoReference | null;
+    } | null>();
+  });
+
+  it("join builder with 'many' relationship returns array", () => {
+    const builder = new JoinFindBuilder("users", testSchema.tables.users);
+
+    const _builderOut = builder.join((jb) => jb.posts((ib) => ib.select(["title"])));
+    type _JoinOut = InferJoinOut<typeof _builderOut>;
+    //    ^?
+
+    type _JoinOutPosts = Prettify<_JoinOut["posts"]>;
+    //     ^?
+
+    // FIXME: There should not be a `{}` in the array
+    expectTypeOf<_JoinOutPosts>().toEqualTypeOf<
+      {
+        id: FragnoId;
+        title: string;
+        content: string;
+        userId: FragnoReference;
+      }[]
+    >();
+  });
+});