@fragno-dev/db 0.3.0 → 0.4.1

package/src/sync/conflict-checker.test.ts

@@ -0,0 +1,450 @@
+import { describe, test, expect, beforeEach, afterEach } from "vitest";
+
+import Database from "better-sqlite3";
+import { SqliteDialect } from "kysely";
+
+import { BetterSQLite3DriverConfig } from "../adapters/generic-sql/driver-config";
+import { buildFindOptions } from "../query/orm/orm";
+import { schema, column, idColumn, referenceColumn } from "../schema/create";
+import { sql } from "../sql-driver/sql";
+import { SqlDriverAdapter } from "../sql-driver/sql-driver-adapter";
+import { checkConflicts } from "./conflict-checker";
+
+const testSchema = schema("test", (s) => {
+  return s
+    .addTable("users", (t) => {
+      return t.addColumn("id", idColumn()).addColumn("name", column("string"));
+    })
+    .addTable("posts", (t) => {
+      return t
+        .addColumn("id", idColumn())
+        .addColumn("title", column("string"))
+        .addColumn("userId", referenceColumn());
+    })
+    .addReference("author", {
+      type: "one",
+      from: { table: "posts", column: "userId" },
+      to: { table: "users", column: "id" },
+    });
+});
+
+const baseVersionstamp = "000000000000000000000001";
+const nextVersionstamp = "000000000000000000000002";
+
+const createDriver = () => {
+  const database = new Database(":memory:");
+  const dialect = new SqliteDialect({ database });
+  const driver = new SqlDriverAdapter(dialect);
+
+  return { database, dialect, driver };
+};
+
+const setupTables = async (driver: SqlDriverAdapter, dialect: SqliteDialect) => {
+  await driver.executeQuery(
+    sql`CREATE TABLE users (
+      id text,
+      name text,
+      _internalId integer,
+      _version integer
+    );`.compile(dialect),
+  );
+
+  await driver.executeQuery(
+    sql`CREATE TABLE posts (
+      id text,
+      title text,
+      userId integer,
+      _internalId integer,
+      _version integer
+    );`.compile(dialect),
+  );
+
+  await driver.executeQuery(
+    sql`CREATE TABLE fragno_db_outbox_mutations (
+      id text,
+      entryVersionstamp text,
+      mutationVersionstamp text,
+      uowId text,
+      schema text,
+      "table" text,
+      externalId text,
+      op text
+    );`.compile(dialect),
+  );
+};
+
+describe("checkConflicts", () => {
+  let database: InstanceType<typeof Database>;
+  let dialect: SqliteDialect;
+  let driver: SqlDriverAdapter;
+  const insertMutation = async ({
+    id,
+    schema: schemaName,
+    table,
+    externalId,
+    entryVersionstamp = nextVersionstamp,
+  }: {
+    id: string;
+    schema: string;
+    table: string;
+    externalId: string;
+    entryVersionstamp?: string;
+  }) => {
+    await driver.executeQuery(
+      sql`INSERT INTO fragno_db_outbox_mutations (
+            id, entryVersionstamp, mutationVersionstamp, uowId, schema, "table", externalId, op
+          ) VALUES (
+            ${id}, ${entryVersionstamp}, ${entryVersionstamp}, ${`uow_${id}`}, ${schemaName}, ${table}, ${externalId}, ${"update"}
+          );`.compile(dialect),
+    );
+  };
+
+  beforeEach(async () => {
+    const setup = createDriver();
+    database = setup.database;
+    dialect = setup.dialect;
+    driver = setup.driver;
+    await setupTables(driver, dialect);
+  });
+
+  afterEach(async () => {
+    await driver.destroy();
+    database.close();
+  });
+
+  test("detects conflicts from read keys", async () => {
+    await driver.executeQuery(
+      sql`INSERT INTO users (id, name, _internalId, _version)
+          VALUES (${"u1"}, ${"Ava"}, 1, 0);`.compile(dialect),
+    );
+
+    await insertMutation({
+      id: "m1",
+      schema: "",
+      table: "users",
+      externalId: "u1",
+    });
+
+    const hasConflict = await checkConflicts(
+      {
+        baseVersionstamp,
+        readKeys: [{ schema: "", table: "users", externalId: "u1" }],
+        writeKeys: [],
+        readScopes: [],
+      },
+      { driver, driverConfig: new BetterSQLite3DriverConfig() },
+    );
+
+    expect(hasConflict).toBe(true);
+  });
+
+  test("detects conflicts from read scopes with joins", async () => {
+    await driver.executeQuery(
+      sql`INSERT INTO users (id, name, _internalId, _version)
+          VALUES (${"u1"}, ${"Ava"}, 1, 0);`.compile(dialect),
+    );
+
+    await driver.executeQuery(
+      sql`INSERT INTO posts (id, title, userId, _internalId, _version)
+          VALUES (${"p1"}, ${"Hello"}, 1, 10, 0);`.compile(dialect),
+    );
+
+    await insertMutation({
+      id: "m2",
+      schema: "",
+      table: "users",
+      externalId: "u1",
+    });
+
+    const options = buildFindOptions(testSchema.tables.posts, {
+      where: (eb) => eb("title", "=", "Hello"),
+      join: (jb) => {
+        jb["author"]();
+      },
+    });
+
+    if (!options) {
+      throw new Error("Expected join options to compile.");
+    }
+
+    const hasConflict = await checkConflicts(
+      {
+        baseVersionstamp,
+        readKeys: [],
+        writeKeys: [],
+        readScopes: [
+          {
+            schema: "",
+            table: testSchema.tables.posts,
+            indexName: "primary",
+            condition: options.where,
+            joins: options.join,
+          },
+        ],
+      },
+      { driver, driverConfig: new BetterSQLite3DriverConfig() },
+    );
+
+    expect(hasConflict).toBe(true);
+  });
+
+  test("honors unknownReadStrategy ignore", async () => {
+    await insertMutation({
+      id: "m3",
+      schema: "",
+      table: "users",
+      externalId: "u1",
+    });
+
+    const hasConflict = await checkConflicts(
+      {
+        baseVersionstamp,
+        readKeys: [],
+        writeKeys: [],
+        readScopes: [],
+        unknownReads: [{ schema: "", table: "users" }],
+        unknownReadStrategy: "ignore",
+      },
+      { driver, driverConfig: new BetterSQLite3DriverConfig() },
+    );
+
+    expect(hasConflict).toBe(false);
+  });
+
+  test("ignores empty externalIds in read/write keys", async () => {
+    await insertMutation({
+      id: "m4",
+      schema: "",
+      table: "users",
+      externalId: "u1",
+    });
+
+    const hasConflict = await checkConflicts(
+      {
+        baseVersionstamp,
+        readKeys: [{ schema: "", table: "users", externalId: "   " }],
+        writeKeys: [{ schema: "", table: "users", externalId: "" }],
+        readScopes: [],
+      },
+      { driver, driverConfig: new BetterSQLite3DriverConfig() },
+    );
+
+    expect(hasConflict).toBe(false);
+  });
+
+  test("detects conflicts from write keys", async () => {
+    await insertMutation({
+      id: "m5",
+      schema: "",
+      table: "users",
+      externalId: "u1",
+    });
+
+    const hasConflict = await checkConflicts(
+      {
+        baseVersionstamp,
+        readKeys: [],
+        writeKeys: [{ schema: "", table: "users", externalId: "u1" }],
+        readScopes: [],
+      },
+      { driver, driverConfig: new BetterSQLite3DriverConfig() },
+    );
+
+    expect(hasConflict).toBe(true);
+  });
+
+  test("skips mutations at the base versionstamp", async () => {
+    await insertMutation({
+      id: "m6",
+      schema: "",
+      table: "users",
+      externalId: "u1",
+      entryVersionstamp: baseVersionstamp,
+    });
+
+    const hasConflict = await checkConflicts(
+      {
+        baseVersionstamp,
+        readKeys: [{ schema: "", table: "users", externalId: "u1" }],
+        writeKeys: [],
+        readScopes: [],
+      },
+      { driver, driverConfig: new BetterSQLite3DriverConfig() },
+    );
+
+    expect(hasConflict).toBe(false);
+  });
+
+  test("defaults unknown read strategy to conflict", async () => {
+    await insertMutation({
+      id: "m7",
+      schema: "",
+      table: "users",
+      externalId: "u1",
+    });
+
+    const hasConflict = await checkConflicts(
+      {
+        baseVersionstamp,
+        readKeys: [],
+        writeKeys: [],
+        readScopes: [],
+        unknownReads: [{ schema: "", table: "posts" }],
+      },
+      { driver, driverConfig: new BetterSQLite3DriverConfig() },
+    );
+
+    expect(hasConflict).toBe(true);
+  });
+
+  test("unknownReadStrategy table only checks matching tables", async () => {
+    await insertMutation({
+      id: "m8",
+      schema: "",
+      table: "users",
+      externalId: "u1",
+    });
+
+    const shouldSkip = await checkConflicts(
+      {
+        baseVersionstamp,
+        readKeys: [],
+        writeKeys: [],
+        readScopes: [],
+        unknownReads: [{ schema: "", table: "posts" }],
+        unknownReadStrategy: "table",
+      },
+      { driver, driverConfig: new BetterSQLite3DriverConfig() },
+    );
+
+    const shouldConflict = await checkConflicts(
+      {
+        baseVersionstamp,
+        readKeys: [],
+        writeKeys: [],
+        readScopes: [],
+        unknownReads: [{ schema: "", table: "users" }],
+        unknownReadStrategy: "table",
+      },
+      { driver, driverConfig: new BetterSQLite3DriverConfig() },
+    );
+
+    expect(shouldSkip).toBe(false);
+    expect(shouldConflict).toBe(true);
+  });
+
+  test("read scopes without matching rows do not conflict", async () => {
+    await driver.executeQuery(
+      sql`INSERT INTO posts (id, title, userId, _internalId, _version)
+          VALUES (${"p1"}, ${"Hello"}, 1, 10, 0);`.compile(dialect),
+    );
+
+    await insertMutation({
+      id: "m9",
+      schema: "",
+      table: "posts",
+      externalId: "p1",
+    });
+
+    const options = buildFindOptions(testSchema.tables.posts, {
+      where: (eb) => eb("title", "=", "Missing"),
+    });
+
+    if (!options) {
+      throw new Error("Expected options to compile.");
+    }
+
+    const hasConflict = await checkConflicts(
+      {
+        baseVersionstamp,
+        readKeys: [],
+        writeKeys: [],
+        readScopes: [
+          {
+            schema: "",
+            table: testSchema.tables.posts,
+            indexName: "primary",
+            condition: options.where,
+            joins: options.join,
+          },
+        ],
+      },
+      { driver, driverConfig: new BetterSQLite3DriverConfig() },
+    );
+
+    expect(hasConflict).toBe(false);
+  });
+
+  test("returns conflict when any read scope matches", async () => {
+    await driver.executeQuery(
+      sql`INSERT INTO posts (id, title, userId, _internalId, _version)
+          VALUES (${"p1"}, ${"Hello"}, 1, 10, 0);`.compile(dialect),
+    );
+
+    await insertMutation({
+      id: "m10",
+      schema: "",
+      table: "posts",
+      externalId: "p1",
+    });
+
+    const noMatch = buildFindOptions(testSchema.tables.posts, {
+      where: (eb) => eb("title", "=", "Missing"),
+    });
+    const match = buildFindOptions(testSchema.tables.posts, {
+      where: (eb) => eb("title", "=", "Hello"),
+    });
+
+    if (!noMatch || !match) {
+      throw new Error("Expected options to compile.");
+    }
+
+    const hasConflict = await checkConflicts(
+      {
+        baseVersionstamp,
+        readKeys: [],
+        writeKeys: [],
+        readScopes: [
+          {
+            schema: "",
+            table: testSchema.tables.posts,
+            indexName: "primary",
+            condition: noMatch.where,
+            joins: noMatch.join,
+          },
+          {
+            schema: "",
+            table: testSchema.tables.posts,
+            indexName: "primary",
+            condition: match.where,
+            joins: match.join,
+          },
+        ],
+      },
+      { driver, driverConfig: new BetterSQLite3DriverConfig() },
+    );
+
+    expect(hasConflict).toBe(true);
+  });
+
+  test("does not conflict on schema mismatch", async () => {
+    await insertMutation({
+      id: "m11",
+      schema: "other",
+      table: "users",
+      externalId: "u1",
+    });
+
+    const hasConflict = await checkConflicts(
+      {
+        baseVersionstamp,
+        readKeys: [{ schema: "", table: "users", externalId: "u1" }],
+        writeKeys: [],
+        readScopes: [],
+      },
+      { driver, driverConfig: new BetterSQLite3DriverConfig() },
+    );
+
+    expect(hasConflict).toBe(false);
+  });
+});

package/src/sync/conflict-checker.ts

@@ -0,0 +1,248 @@
+import { sql } from "kysely";
+
+import type { DriverConfig } from "../adapters/generic-sql/driver-config";
+import { createColdKysely } from "../adapters/generic-sql/migration/cold-kysely";
+import { createSQLQueryCompiler } from "../adapters/generic-sql/query/create-sql-query-compiler";
+import type { SQLiteStorageMode } from "../adapters/generic-sql/sqlite-storage";
+import type { NamingResolver } from "../naming/sql-naming";
+import type { Condition } from "../query/condition-builder";
+import type { CompiledJoin } from "../query/orm/orm";
+import type { AnyTable } from "../schema/create";
+import type { SqlDriverAdapter } from "../sql-driver/sql-driver-adapter";
+
+export type ConflictKey = {
+  schema: string;
+  table: string;
+  externalId: string;
+};
+
+export type ConflictReadScope = {
+  schema: string;
+  table: AnyTable;
+  indexName: string;
+  condition?: Condition;
+  joins?: CompiledJoin[];
+};
+
+export type UnknownRead = {
+  schema: string;
+  table: string;
+};
+
+export type UnknownReadStrategy = "conflict" | "table" | "ignore";
+
+export type ConflictCheckInput = {
+  baseVersionstamp?: string;
+  readKeys: ConflictKey[];
+  writeKeys: ConflictKey[];
+  readScopes: ConflictReadScope[];
+  unknownReads?: UnknownRead[];
+  unknownReadStrategy?: UnknownReadStrategy;
+};
+
+export type ConflictCheckRuntime = {
+  driver: SqlDriverAdapter;
+  driverConfig: DriverConfig;
+  sqliteStorageMode?: SQLiteStorageMode;
+  resolver?: NamingResolver;
+};
+
+const OUTBOX_MUTATIONS_TABLE = "fragno_db_outbox_mutations" as const;
+
+const normalizeKeys = (keys: ConflictKey[]): ConflictKey[] =>
+  keys.filter((key) => key.externalId.trim().length > 0);
+
+const groupKeys = (keys: ConflictKey[]) => {
+  const map = new Map<string, { schema: string; table: string; externalIds: string[] }>();
+  for (const key of keys) {
+    const groupKey = `${key.schema}::${key.table}`;
+    const existing = map.get(groupKey);
+    if (existing) {
+      existing.externalIds.push(key.externalId);
+      continue;
+    }
+    map.set(groupKey, {
+      schema: key.schema,
+      table: key.table,
+      externalIds: [key.externalId],
+    });
+  }
+  return Array.from(map.values());
+};
+
+const groupTables = (tables: UnknownRead[]) => {
+  const map = new Map<string, UnknownRead>();
+  for (const entry of tables) {
+    const key = `${entry.schema}::${entry.table}`;
+    if (!map.has(key)) {
+      map.set(key, entry);
+    }
+  }
+  return Array.from(map.values());
+};
+
+const hasKeyConflicts = async (
+  runtime: ConflictCheckRuntime,
+  baseVersionstamp: string | undefined,
+  readKeys: ConflictKey[],
+  writeKeys: ConflictKey[],
+): Promise<boolean> => {
+  const combinedKeys = normalizeKeys([...readKeys, ...writeKeys]);
+  if (combinedKeys.length === 0) {
+    return false;
+  }
+
+  const grouped = groupKeys(combinedKeys);
+  const db = createColdKysely(runtime.driverConfig.databaseType);
+  let query = db.selectFrom(OUTBOX_MUTATIONS_TABLE).select(sql<number>`1`.as("exists"));
+
+  if (baseVersionstamp) {
+    query = query.where("entryVersionstamp", ">", baseVersionstamp);
+  }
+
+  query = query.where((eb) =>
+    eb.or(
+      grouped.map((group) =>
+        eb.and([
+          eb("schema", "=", group.schema),
+          eb("table", "=", group.table),
+          eb("externalId", "in", group.externalIds),
+        ]),
+      ),
+    ),
+  );
+
+  query = query.limit(1);
+
+  const result = await runtime.driver.executeQuery(query.compile());
+  return result.rows.length > 0;
+};
+
+const hasUnknownReadConflicts = async (
+  runtime: ConflictCheckRuntime,
+  baseVersionstamp: string | undefined,
+  unknownReads: UnknownRead[],
+  strategy: UnknownReadStrategy,
+): Promise<boolean> => {
+  if (unknownReads.length === 0 || strategy === "ignore") {
+    return false;
+  }
+
+  const db = createColdKysely(runtime.driverConfig.databaseType);
+
+  if (strategy === "conflict") {
+    let query = db.selectFrom(OUTBOX_MUTATIONS_TABLE).select(sql<number>`1`.as("exists"));
+    if (baseVersionstamp) {
+      query = query.where("entryVersionstamp", ">", baseVersionstamp);
+    }
+    query = query.limit(1);
+    const result = await runtime.driver.executeQuery(query.compile());
+    return result.rows.length > 0;
+  }
+
+  const grouped = groupTables(unknownReads);
+  let query = db.selectFrom(OUTBOX_MUTATIONS_TABLE).select(sql<number>`1`.as("exists"));
+
+  if (baseVersionstamp) {
+    query = query.where("entryVersionstamp", ">", baseVersionstamp);
+  }
+
+  query = query.where((eb) =>
+    eb.or(
+      grouped.map((group) =>
+        eb.and([eb("schema", "=", group.schema), eb("table", "=", group.table)]),
+      ),
+    ),
+  );
+
+  query = query.limit(1);
+
+  const result = await runtime.driver.executeQuery(query.compile());
+  return result.rows.length > 0;
+};
+
+const hasScopeConflicts = async (
+  runtime: ConflictCheckRuntime,
+  baseVersionstamp: string | undefined,
+  scope: ConflictReadScope,
+): Promise<boolean> => {
+  const db = createColdKysely(runtime.driverConfig.databaseType);
+  const compiler = createSQLQueryCompiler(
+    db,
+    runtime.driverConfig,
+    runtime.sqliteStorageMode,
+    runtime.resolver,
+  );
+
+  const { query: baseQuery, aliases } = compiler.buildJoinQuery(scope.table, {
+    where: scope.condition,
+    join: scope.joins,
+  });
+
+  let query = baseQuery.select(sql<number>`1`.as("exists"));
+  const mutationAliases: string[] = [];
+
+  for (const [index, alias] of aliases.entries()) {
+    const mutationAlias = `m_${index}`;
+    mutationAliases.push(mutationAlias);
+
+    const idColumn = alias.table.getIdColumn();
+    const columnName = runtime.resolver
+      ? runtime.resolver.getColumnName(alias.table.name, idColumn.name)
+      : idColumn.name;
+
+    query = query.leftJoin(`${OUTBOX_MUTATIONS_TABLE} as ${mutationAlias}`, (join) => {
+      let on = join
+        .on(`${mutationAlias}.schema`, "=", scope.schema)
+        .on(`${mutationAlias}.table`, "=", alias.table.name)
+        .onRef(`${mutationAlias}.externalId`, "=", `${alias.alias}.${columnName}`);
+
+      if (baseVersionstamp) {
+        on = on.on(`${mutationAlias}.entryVersionstamp`, ">", baseVersionstamp);
+      }
+
+      return on;
+    });
+  }
+
+  if (mutationAliases.length > 0) {
+    query = query.where((eb) =>
+      eb.or(mutationAliases.map((alias) => eb(`${alias}.entryVersionstamp`, "is not", null))),
+    );
+  }
+
+  query = query.limit(1);
+
+  const result = await runtime.driver.executeQuery(query.compile());
+  return result.rows.length > 0;
+};
+
+export const checkConflicts = async (
+  input: ConflictCheckInput,
+  runtime: ConflictCheckRuntime,
+): Promise<boolean> => {
+  const unknownReadStrategy = input.unknownReadStrategy ?? "conflict";
+
+  if (await hasKeyConflicts(runtime, input.baseVersionstamp, input.readKeys, input.writeKeys)) {
+    return true;
+  }
+
+  for (const scope of input.readScopes) {
+    if (await hasScopeConflicts(runtime, input.baseVersionstamp, scope)) {
+      return true;
+    }
+  }
+
+  if (
+    await hasUnknownReadConflicts(
+      runtime,
+      input.baseVersionstamp,
+      input.unknownReads ?? [],
+      unknownReadStrategy,
+    )
+  ) {
+    return true;
+  }
+
+  return false;
+};

package/src/sync/index.ts

@@ -0,0 +1,14 @@
+export { defineSyncCommands } from "./commands";
+export {
+  collectReadKeys,
+  collectReadScopes,
+  collectWriteKeys,
+  stripReadTrackingResults,
+} from "./read-tracking";
+export type { ReadKey, ReadScope } from "./read-tracking";
+export type {
+  SyncCommandDefinition,
+  SyncCommandHandler,
+  SyncCommandRegistry,
+  SyncCommandTxFactory,
+} from "./types";