@fragno-dev/db 0.1.15 → 0.2.0

package/src/adapters/generic-sql/uow-encoder.test.ts

@@ -0,0 +1,183 @@
+import { describe, it, expect } from "vitest";
+import { UnitOfWorkEncoder } from "./uow-encoder";
+import { schema, column, idColumn, referenceColumn } from "../../schema/create";
+import {
+  BetterSQLite3DriverConfig,
+  MySQL2DriverConfig,
+  NodePostgresDriverConfig,
+} from "./driver-config";
+
+describe("UnitOfWorkEncoder", () => {
+  const testSchema = schema((s) => {
+    return s
+      .addTable("users", (t) => {
+        return t
+          .addColumn("id", idColumn())
+          .addColumn("name", column("string"))
+          .addColumn("age", column("integer").nullable())
+          .addColumn("isActive", column("bool"))
+          .addColumn("createdAt", column("timestamp"));
+      })
+      .addTable("posts", (t) => {
+        return t
+          .addColumn("id", idColumn())
+          .addColumn("userId", referenceColumn())
+          .addColumn("title", column("string"));
+      });
+  });
+
+  const usersTable = testSchema.tables.users;
+  const postsTable = testSchema.tables.posts;
+
+  describe("SQLite encoding", () => {
+    const sqliteConfig = new BetterSQLite3DriverConfig();
+
+    // Mock Kysely instance (only needed for reference subquery processing)
+    const db = {} as any; // eslint-disable-line @typescript-eslint/no-explicit-any
+    const encoder = new UnitOfWorkEncoder(sqliteConfig, db);
+
+    it("should serialize Date to number for sqlite", () => {
+      const date = new Date("2024-01-15T10:30:00Z");
+      const result = encoder.encodeForDatabase({
+        values: { createdAt: date },
+        table: usersTable,
+        generateDefaults: false,
+      });
+
+      expect(result).toEqual({ createdAt: date.getTime() });
+    });
+
+    it("should serialize boolean to number for sqlite", () => {
+      const result = encoder.encodeForDatabase({
+        values: { isActive: true },
+        table: usersTable,
+        generateDefaults: false,
+      });
+
+      expect(result).toEqual({ isActive: 1 });
+    });
+
+    it("should serialize bigint to Number for reference columns in sqlite", () => {
+      const result = encoder.encodeForDatabase({
+        values: { userId: BigInt(456) },
+        table: postsTable,
+        generateDefaults: false,
+      });
+
+      // Reference columns should be converted to Number for SQLite
+      expect(result).toEqual({ userId: 456 });
+    });
+
+    it("should handle multiple fields", () => {
+      const date = new Date("2024-01-15T10:30:00Z");
+      const result = encoder.encodeForDatabase({
+        values: {
+          name: "Alice",
+          age: 30,
+          isActive: false,
+          createdAt: date,
+        },
+        table: usersTable,
+        generateDefaults: false,
+      });
+
+      expect(result).toEqual({
+        name: "Alice",
+        age: 30,
+        isActive: 0,
+        createdAt: date.getTime(),
+      });
+    });
+
+    it("should handle null values", () => {
+      const result = encoder.encodeForDatabase({
+        values: { age: null },
+        table: usersTable,
+        generateDefaults: false,
+      });
+
+      expect(result).toEqual({ age: null });
+    });
+
+    it("should generate defaults when requested", () => {
+      const result = encoder.encodeForDatabase({
+        values: { title: "Test" },
+        table: postsTable,
+        generateDefaults: true,
+      });
+
+      // Should have generated an ID
+      expect(result["id"]).toBeDefined();
+      expect(typeof result["id"]).toBe("string");
+      expect(result["title"]).toBe("Test");
+    });
+  });
+
+  describe("PostgreSQL encoding", () => {
+    const postgresConfig = new NodePostgresDriverConfig();
+
+    // Mock Kysely instance
+    const db = {} as any; // eslint-disable-line @typescript-eslint/no-explicit-any
+    const encoder = new UnitOfWorkEncoder(postgresConfig, db);
+
+    it("should keep Date as Date for postgresql", () => {
+      const date = new Date("2024-01-15T10:30:00Z");
+      const result = encoder.encodeForDatabase({
+        values: { createdAt: date },
+        table: usersTable,
+        generateDefaults: false,
+      });
+
+      expect(result).toEqual({ createdAt: date });
+    });
+
+    it("should keep boolean as boolean for postgresql", () => {
+      const result = encoder.encodeForDatabase({
+        values: { isActive: true },
+        table: usersTable,
+        generateDefaults: false,
+      });
+
+      expect(result).toEqual({ isActive: true });
+    });
+
+    it("should keep bigint as bigint for reference columns in postgresql", () => {
+      const result = encoder.encodeForDatabase({
+        values: { userId: BigInt(456) },
+        table: postsTable,
+        generateDefaults: false,
+      });
+
+      expect(result).toEqual({ userId: BigInt(456) });
+    });
+  });
+
+  describe("MySQL encoding", () => {
+    const mysqlConfig = new MySQL2DriverConfig();
+
+    // Mock Kysely instance
+    const db = {} as any; // eslint-disable-line @typescript-eslint/no-explicit-any
+    const encoder = new UnitOfWorkEncoder(mysqlConfig, db);
+
+    it("should keep Date as Date for mysql", () => {
+      const date = new Date("2024-01-15T10:30:00Z");
+      const result = encoder.encodeForDatabase({
+        values: { createdAt: date },
+        table: usersTable,
+        generateDefaults: false,
+      });
+
+      expect(result).toEqual({ createdAt: date });
+    });
+
+    it("should keep boolean as boolean for mysql", () => {
+      const result = encoder.encodeForDatabase({
+        values: { isActive: true },
+        table: usersTable,
+        generateDefaults: false,
+      });
+
+      expect(result).toEqual({ isActive: true });
+    });
+  });
+});

package/src/adapters/generic-sql/uow-encoder.ts

@@ -0,0 +1,131 @@
+import type { AnyTable, AnyColumn } from "../../schema/create";
+import type { DriverConfig } from "./driver-config";
+import {
+  createSQLSerializer,
+  type SQLSerializer,
+} from "../../query/serialize/create-sql-serializer";
+import { encodeValues } from "../../query/value-encoding";
+import { processReferenceSubqueries } from "./query/where-builder";
+import type { TableNameMapper } from "../shared/table-name-mapper";
+import type { Kysely } from "kysely";
+
+/**
+ * Encoder class for Unit of Work mutation operations.
+ *
+ * Handles the complete transformation from application values to database-ready values
+ * in three clear steps:
+ * 1. Resolution - Resolve FragnoId/FragnoReference objects and generate defaults
+ * 2. Reference Processing - Create subqueries for external ID lookups
+ * 3. Serialization - Apply database-specific type conversions
+ *
+ * This class mirrors the UnitOfWorkDecoder pattern for symmetry.
+ */
+export class UnitOfWorkEncoder {
+  readonly #serializer: SQLSerializer;
+  readonly #db: Kysely<any>; // eslint-disable-line @typescript-eslint/no-explicit-any
+  readonly #mapper?: TableNameMapper;
+
+  constructor(
+    driverConfig: DriverConfig,
+    db: Kysely<any>, // eslint-disable-line @typescript-eslint/no-explicit-any
+    mapper?: TableNameMapper,
+  ) {
+    this.#serializer = createSQLSerializer(driverConfig);
+    this.#db = db;
+    this.#mapper = mapper;
+  }
+
+  /**
+   * Encode application values to database-ready format.
+   *
+   * This is the main entry point that handles all encoding steps:
+   * 1. **Resolution**: Transform ORM names to DB columns, resolve FragnoId/FragnoReference,
+   *    generate defaults (CUIDs for IDs, etc.)
+   * 2. **Reference Processing**: Convert external ID strings to subqueries for internal ID lookup
+   * 3. **Serialization**: Apply database-specific conversions (Date → number for SQLite, etc.)
+   *
+   * @param options - Encoding options
+   * @param options.values - Application values to encode
+   * @param options.table - Table schema definition
+   * @param options.generateDefaults - Whether to generate default values for undefined columns
+   * @returns Database-ready values
+   *
+   * @example
+   * ```ts
+   * const encoded = encoder.encodeForDatabase({
+   *   values: { userId: FragnoId(...), createdAt: new Date(), isActive: true },
+   *   table: usersTable,
+   *   generateDefaults: true
+   * });
+   * // For SQLite: { user_id: 456, created_at: 1705316400000, is_active: 1 }
+   * ```
+   */
+  encodeForDatabase(options: {
+    values: Record<string, unknown>;
+    table: AnyTable;
+    generateDefaults: boolean;
+  }): Record<string, unknown> {
+    // Step 1: Resolution - Resolve FragnoId/FragnoReference and generate defaults
+    const resolved = encodeValues(options.values, options.table, options.generateDefaults);
+
+    // Step 2: Reference Processing - Convert external IDs to subqueries
+    const processed = processReferenceSubqueries(resolved, this.#db, this.#mapper);
+
+    // Step 3: Serialization - Apply database-specific type conversions
+    const serialized = this.serializeValues(processed, options.table);
+
+    return serialized;
+  }
+
+  /**
+   * Serialize resolved values to database format.
+   *
+   * Applies database-specific type conversions:
+   * - SQLite: Date → number, boolean → 0/1, bigint → Buffer (or Number for reference columns)
+   * - PostgreSQL: Mostly pass-through (database handles types natively)
+   * - MySQL: Mostly pass-through
+   *
+   * @param values - Resolved values (after resolution and reference processing)
+   * @param table - The table schema definition
+   * @returns Serialized values ready for database driver
+   */
+  private serializeValues(
+    values: Record<string, unknown>,
+    table: AnyTable,
+  ): Record<string, unknown> {
+    const result: Record<string, unknown> = {};
+
+    for (const [dbColumnName, value] of Object.entries(values)) {
+      // Find the column definition by database column name
+      const col = this.findColumnByDbName(table, dbColumnName);
+
+      if (!col) {
+        // Not a regular column (might be a special value like sql.raw())
+        // Pass through as-is
+        result[dbColumnName] = value;
+        continue;
+      }
+
+      // Serialize the value using the column definition and database type
+      result[dbColumnName] = this.#serializer.serialize(value, col);
+    }
+
+    return result;
+  }
+
+  /**
+   * Find a column definition by its database column name.
+   *
+   * @param table - The table to search
+   * @param dbColumnName - The database column name (e.g., "user_id")
+   * @returns The column definition or undefined if not found
+   */
+  private findColumnByDbName(table: AnyTable, dbColumnName: string): AnyColumn | undefined {
+    for (const col of Object.values(table.columns)) {
+      if (col.name === dbColumnName) {
+        return col;
+      }
+    }
+    return undefined;
+  }
+}

package/src/adapters/kysely/kysely-adapter-pglite.test.ts

@@ -1,6 +1,5 @@
-import { Kysely } from "kysely";
 import { KyselyPGlite } from "kysely-pglite";
-import { assert, beforeAll, describe, expect, expectTypeOf, it } from "vitest";
+import { beforeAll, describe, expect, expectTypeOf, it } from "vitest";
 import { KyselyAdapter } from "./kysely-adapter";
 import {
   column,
@@ -11,6 +10,8 @@ import {
   type FragnoReference,
 } from "../../schema/create";
 import { Cursor } from "../../query/cursor";
+import { PGLiteDriverConfig } from "../generic-sql/driver-config";
+import { internalSchema } from "../../fragments/internal-fragment";
 
 describe("KyselyAdapter PGLite", () => {
   const testSchema = schema((s) => {
@@ -95,19 +96,14 @@ describe("KyselyAdapter PGLite", () => {
       });
   });
 
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  let kysely: Kysely<any>;
   let adapter: KyselyAdapter;
 
   beforeAll(async () => {
     const { dialect } = await KyselyPGlite.create();
-    kysely = new Kysely({
-      dialect,
-    });
 
     adapter = new KyselyAdapter({
-      db: kysely,
-      provider: "postgresql",
+      dialect,
+      driverConfig: new PGLiteDriverConfig(),
     });
   }, 12000);
 
@@ -115,72 +111,26 @@ describe("KyselyAdapter PGLite", () => {
     const schemaVersion = await adapter.getSchemaVersion("test");
     expect(schemaVersion).toBeUndefined();
 
-    const migrator = adapter.createMigrationEngine(testSchema, "test");
-    const preparedMigration = await migrator.prepareMigration({
-      updateSettings: false,
-    });
-    assert(preparedMigration.getSQL);
-
-    expect(preparedMigration.getSQL()).toMatchInlineSnapshot(`
-      "create table "users_test" ("id" varchar(30) not null unique, "name" text not null, "age" integer, "_internalId" bigserial not null primary key, "_version" integer default 0 not null);
-
-      create index "name_idx" on "users_test" ("name");
-
-      create index "age_idx" on "users_test" ("age");
-
-      create table "emails_test" ("id" varchar(30) not null unique, "user_id" bigint not null, "email" text not null, "is_primary" boolean default false not null, "_internalId" bigserial not null primary key, "_version" integer default 0 not null);
-
-      create unique index "unique_email" on "emails_test" ("email");
-
-      create index "user_emails" on "emails_test" ("user_id");
-
-      create table "posts_test" ("id" varchar(30) not null unique, "user_id" bigint not null, "title" text not null, "content" text not null, "_internalId" bigserial not null primary key, "_version" integer default 0 not null);
-
-      create index "posts_user_idx" on "posts_test" ("user_id");
-
-      create table "tags_test" ("id" varchar(30) not null unique, "name" text not null, "_internalId" bigserial not null primary key, "_version" integer default 0 not null);
-
-      create index "tag_name" on "tags_test" ("name");
-
-      create table "post_tags_test" ("id" varchar(30) not null unique, "post_id" bigint not null, "tag_id" bigint not null, "_internalId" bigserial not null primary key, "_version" integer default 0 not null);
-
-      create index "pt_post" on "post_tags_test" ("post_id");
-
-      create index "pt_tag" on "post_tags_test" ("tag_id");
-
-      create table "comments_test" ("id" varchar(30) not null unique, "post_id" bigint not null, "user_id" bigint not null, "text" text not null, "_internalId" bigserial not null primary key, "_version" integer default 0 not null);
-
-      create index "comments_post_idx" on "comments_test" ("post_id");
-
-      create index "comments_user_idx" on "comments_test" ("user_id");
-
-      alter table "emails_test" add constraint "emails_users_user_fk" foreign key ("user_id") references "users_test" ("_internalId") on delete restrict on update restrict;
-
-      alter table "posts_test" add constraint "posts_users_author_fk" foreign key ("user_id") references "users_test" ("_internalId") on delete restrict on update restrict;
-
-      alter table "post_tags_test" add constraint "post_tags_posts_post_fk" foreign key ("post_id") references "posts_test" ("_internalId") on delete restrict on update restrict;
-
-      alter table "post_tags_test" add constraint "post_tags_tags_tag_fk" foreign key ("tag_id") references "tags_test" ("_internalId") on delete restrict on update restrict;
-
-      alter table "comments_test" add constraint "comments_posts_post_fk" foreign key ("post_id") references "posts_test" ("_internalId") on delete restrict on update restrict;
-
-      alter table "comments_test" add constraint "comments_users_commenter_fk" foreign key ("user_id") references "users_test" ("_internalId") on delete restrict on update restrict;"
-    `);
+    {
+      const migrations = adapter.prepareMigrations(internalSchema, "");
+      await migrations.executeWithDriver(adapter.driver, 0);
+    }
 
-    await preparedMigration.execute();
+    {
+      const migrations = adapter.prepareMigrations(testSchema, "test");
+      await migrations.executeWithDriver(adapter.driver, 0);
+    }
 
     const queryEngine = adapter.createQueryEngine(testSchema, "test");
 
-    // Create a user
     const userId = await queryEngine.create("users", {
       name: "John Doe",
       age: 30,
     });
 
-    // create() now returns just the ID
     expect(userId).toMatchObject({
       externalId: expect.stringMatching(/^[a-z0-9]{20,}$/),
-      internalId: expect.any(Number),
+      internalId: expect.any(BigInt),
     });
 
     expect(userId.version).toBe(0);
@@ -191,7 +141,7 @@ describe("KyselyAdapter PGLite", () => {
     expect(getUser).toMatchObject({
       id: expect.objectContaining({
         externalId: expect.stringMatching(/^[a-z0-9]{20,}$/),
-        internalId: expect.any(Number),
+        internalId: expect.any(BigInt),
       }),
       name: "John Doe",
     });
@@ -212,12 +162,12 @@ describe("KyselyAdapter PGLite", () => {
 
     expect(email1Id).toMatchObject({
       externalId: expect.stringMatching(/^[a-z0-9]{20,}$/),
-      internalId: expect.any(Number),
+      internalId: expect.any(BigInt),
     });
 
     expect(email2Id).toMatchObject({
       externalId: expect.stringMatching(/^[a-z0-9]{20,}$/),
-      internalId: expect.any(Number),
+      internalId: expect.any(BigInt),
     });
 
     // Update user name
@@ -244,17 +194,17 @@ describe("KyselyAdapter PGLite", () => {
     expect(emailsWithUsers[0]).toEqual({
       id: expect.objectContaining({
         externalId: expect.stringMatching(/^[a-z0-9]{20,}$/),
-        internalId: expect.any(Number),
+        internalId: expect.any(BigInt),
       }),
       user_id: expect.objectContaining({
-        internalId: expect.any(Number),
+        internalId: expect.any(BigInt),
       }),
       email: expect.stringMatching(/\.com$/),
       is_primary: expect.any(Boolean),
       user: {
         id: expect.objectContaining({
           externalId: expect.stringMatching(/^[a-z0-9]{20,}$/),
-          internalId: expect.any(Number),
+          internalId: expect.any(BigInt),
         }),
         name: "Jane Doe",
         age: 30,
@@ -498,10 +448,10 @@ describe("KyselyAdapter PGLite", () => {
         externalId: expect.any(String),
       }),
       post_id: expect.objectContaining({
-        internalId: expect.any(Number),
+        internalId: expect.any(BigInt),
       }),
       tag_id: expect.objectContaining({
-        internalId: expect.any(Number),
+        internalId: expect.any(BigInt),
       }),
       post: {
         title: expect.any(String),
@@ -640,7 +590,7 @@ describe("KyselyAdapter PGLite", () => {
     expect(comment).toMatchObject({
       id: expect.objectContaining({
         externalId: expect.stringMatching(/^[a-z0-9]{20,}$/),
-        internalId: expect.any(Number),
+        internalId: expect.any(BigInt),
       }),
       text: "Great post!",
       // Post join (first level)
@@ -687,15 +637,15 @@ describe("KyselyAdapter PGLite", () => {
     expect(createdIds1).toMatchObject([
       expect.objectContaining({
         externalId: expect.stringMatching(/^[a-z0-9]{20,}$/),
-        internalId: expect.any(Number),
+        internalId: expect.any(BigInt),
       }),
       expect.objectContaining({
         externalId: expect.stringMatching(/^[a-z0-9]{20,}$/),
-        internalId: expect.any(Number),
+        internalId: expect.any(BigInt),
       }),
       expect.objectContaining({
         externalId: expect.stringMatching(/^[a-z0-9]{20,}$/),
-        internalId: expect.any(Number),
+        internalId: expect.any(BigInt),
       }),
     ]);
 

package/src/adapters/kysely/{kysely-adapter-sqlite.test.ts → kysely-adapter-sqlocal.test.ts}

@@ -1,8 +1,8 @@
-import { Kysely } from "kysely";
 import { SQLocalKysely } from "sqlocal/kysely";
 import { beforeAll, describe, expect, it } from "vitest";
 import { KyselyAdapter } from "./kysely-adapter";
 import { column, idColumn, referenceColumn, schema } from "../../schema/create";
+import { SQLocalDriverConfig } from "../generic-sql/driver-config";
 
 describe("KyselyAdapter SQLite", () => {
   const testSchema = schema((s) => {
@@ -33,32 +33,21 @@ describe("KyselyAdapter SQLite", () => {
       });
   });
 
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  let kysely: Kysely<any>;
   let adapter: KyselyAdapter;
 
   beforeAll(async () => {
     const { dialect } = new SQLocalKysely(":memory:");
-    kysely = new Kysely({
-      dialect,
-    });
-
     adapter = new KyselyAdapter({
-      db: kysely,
-      provider: "sqlite",
+      dialect,
+      driverConfig: new SQLocalDriverConfig(),
     });
 
     // Run migrations
-    const migrator = adapter.createMigrationEngine(testSchema, "test");
-    const preparedMigration = await migrator.prepareMigration({
-      updateSettings: false,
-    });
-    await preparedMigration.execute();
+    const preparedMigrations = adapter.prepareMigrations(testSchema, "test");
+    await preparedMigrations.execute(0, testSchema.version, { updateVersionInMigration: false });
   });
 
-  // TODO(Wilco): The SQLocal adapter does not return the number of affected rows for updates/deletes.
-  //              (this only seems to happens when the query is compiled and then executed with executeQuery())
-  it.todo("should perform a balance transfer between accounts", async () => {
+  it("should perform a balance transfer between accounts", async () => {
     const queryEngine = adapter.createQueryEngine(testSchema, "test");
 
     // Create two accounts with initial balances
@@ -153,4 +142,74 @@ describe("KyselyAdapter SQLite", () => {
       amount: transferAmount,
     });
   });
+
+  it("should execute Unit of Work with version checking", async () => {
+    // Use the same namespace as the first test (migrations already ran)
+    const queryEngine = adapter.createQueryEngine(testSchema, "test");
+
+    // Create initial account
+    const initialAccountId = await queryEngine.create("accounts", {
+      userId: "user3",
+      balance: 1000,
+    });
+
+    expect(initialAccountId.version).toBe(0);
+
+    // Build a UOW to update the account with optimistic locking
+    const uow = queryEngine
+      .createUnitOfWork("update-account-balance")
+      // Retrieval phase: find the account
+      .find("accounts", (b) => b.whereIndex("primary", (eb) => eb("id", "=", initialAccountId)));
+
+    // Execute retrieval and transition to mutation phase
+    const [accounts] = await uow.executeRetrieve();
+
+    // Mutation phase: update with version check
+    uow.update("accounts", initialAccountId, (b) => b.set({ balance: 1500 }).check());
+
+    // Execute mutations
+    const { success } = await uow.executeMutations();
+
+    // Should succeed
+    expect(success).toBe(true);
+    expect(accounts).toHaveLength(1);
+
+    // Verify the account was updated
+    const updatedAccount = await queryEngine.findFirst("accounts", (b) =>
+      b.whereIndex("primary", (eb) => eb("id", "=", initialAccountId)),
+    );
+
+    expect(updatedAccount).toMatchObject({
+      id: expect.objectContaining({
+        externalId: initialAccountId.externalId,
+        version: 1, // Version incremented
+      }),
+      userId: "user3",
+      balance: 1500,
+    });
+
+    // Try to update again with stale version (simulating concurrent update - should fail)
+    const uow2 = queryEngine.createUnitOfWork("update-account-stale");
+
+    // Use the old version (0) which is now stale
+    uow2.update("accounts", initialAccountId, (b) => b.set({ balance: 2000 }).check());
+
+    const { success: success2 } = await uow2.executeMutations();
+
+    // Should fail due to version conflict
+    expect(success2).toBe(false);
+
+    // Verify the account was NOT updated
+    const [[unchangedAccount]] = await queryEngine
+      .createUnitOfWork("verify-unchanged")
+      .find("accounts", (b) => b.whereIndex("primary", (eb) => eb("id", "=", initialAccountId)))
+      .executeRetrieve();
+
+    expect(unchangedAccount).toMatchObject({
+      id: expect.objectContaining({
+        version: 1, // Still version 1
+      }),
+      balance: 1500, // Still 1500, not 2000
+    });
+  });
 });