@fragno-dev/db 0.2.2 → 0.4.1

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";

package/src/sync/plan.ts

@@ -0,0 +1,9 @@
+export type SyncCommandPlan = {
+  readKeys: Array<{ schema: string; table: string; externalId: string }>;
+  writeKeys: Array<{ schema: string; table: string; externalId: string }>;
+  readScopes: Array<{
+    schema: string;
+    table: string;
+    indexName: string;
+  }>;
+};

package/src/sync/read-tracking.test.ts

@@ -0,0 +1,177 @@
+import { describe, it, expect } from "vitest";
+
+import {
+  createUnitOfWork,
+  type UOWCompiler,
+  type UOWDecoder,
+  type UOWExecutor,
+} from "../query/unit-of-work/unit-of-work";
+import {
+  schema,
+  idColumn,
+  column,
+  referenceColumn,
+  FragnoId,
+  type AnySchema,
+} from "../schema/create";
+import {
+  collectReadKeys,
+  collectReadScopes,
+  collectWriteKeys,
+  stripReadTrackingResults,
+} from "./read-tracking";
+
+type AnyExecutor = UOWExecutor<unknown, unknown>;
+
+const testSchema = schema("test", (s) =>
+  s
+    .addTable("users", (t) =>
+      t
+        .addColumn("id", idColumn())
+        .addColumn("name", column("string"))
+        .createIndex("name_idx", ["name"]),
+    )
+    .addTable("posts", (t) =>
+      t
+        .addColumn("id", idColumn())
+        .addColumn("author_id", referenceColumn())
+        .addColumn("title", column("string")),
+    )
+    .addTable("comments", (t) =>
+      t
+        .addColumn("id", idColumn())
+        .addColumn("post_id", referenceColumn())
+        .addColumn("commenter_id", referenceColumn())
+        .addColumn("text", column("string")),
+    )
+    .addReference("post", {
+      type: "one",
+      from: { table: "comments", column: "post_id" },
+      to: { table: "posts", column: "id" },
+    })
+    .addReference("author", {
+      type: "one",
+      from: { table: "posts", column: "author_id" },
+      to: { table: "users", column: "id" },
+    })
+    .addReference("commenter", {
+      type: "one",
+      from: { table: "comments", column: "commenter_id" },
+      to: { table: "users", column: "id" },
+    }),
+);
+
+const createMockCompiler = (): UOWCompiler<unknown> => ({
+  compileRetrievalOperation: () => null,
+  compileMutationOperation: () => null,
+});
+
+const createMockDecoder = (): UOWDecoder => ({
+  decode(rawResults) {
+    return rawResults;
+  },
+});
+
+const createMockExecutor = (): AnyExecutor => ({
+  executeRetrievalPhase: async () => [],
+  executeMutationPhase: async () => ({ success: true, createdInternalIds: [] }),
+});
+
+describe("read tracking", () => {
+  it("collects read scopes, keys, and strips extended ids", () => {
+    const compiler = createMockCompiler();
+    const executor = createMockExecutor();
+    const decoder = createMockDecoder();
+    const schemaNamespaceMap: WeakMap<AnySchema, string | null> = new WeakMap();
+    schemaNamespaceMap.set(testSchema, "tenant");
+
+    const baseUow = createUnitOfWork(compiler, executor, decoder, schemaNamespaceMap);
+    baseUow.enableReadTracking();
+
+    baseUow.forSchema(testSchema).find("comments", (b) =>
+      b
+        .whereIndex("primary")
+        .select(["text"])
+        .join((jb) =>
+          jb["post"]((pb) =>
+            pb.select(["title"]).join((jb2) => jb2["author"]((ab) => ab.select(["name"]))),
+          )["commenter"]((cb) => cb.select(["name"])),
+        ),
+    );
+
+    const operations = baseUow.getRetrievalOperations();
+    const commentId = FragnoId.fromExternal("c1", 1);
+    const postId = FragnoId.fromExternal("p1", 1);
+    const authorId = FragnoId.fromExternal("a1", 1);
+    const commenterId = FragnoId.fromExternal("u2", 1);
+
+    const results = [
+      [
+        {
+          id: commentId,
+          text: "hello",
+          post: {
+            id: postId,
+            title: "post",
+            author: {
+              id: authorId,
+              name: "author",
+            },
+          },
+          commenter: {
+            id: commenterId,
+            name: "commenter",
+          },
+        },
+      ],
+    ];
+
+    const scopes = collectReadScopes(operations);
+    expect(scopes).toHaveLength(1);
+    expect(scopes[0]).toMatchObject({
+      schema: "tenant",
+      table: testSchema.tables.comments,
+      indexName: "_primary",
+    });
+
+    const keys = collectReadKeys(operations, results);
+    expect(keys).toEqual(
+      expect.arrayContaining([
+        { schema: "tenant", table: "comments", externalId: "c1" },
+        { schema: "tenant", table: "posts", externalId: "p1" },
+        { schema: "tenant", table: "users", externalId: "a1" },
+        { schema: "tenant", table: "users", externalId: "u2" },
+      ]),
+    );
+
+    stripReadTrackingResults(operations, results);
+
+    const [comment] = results[0] as Array<Record<string, unknown>>;
+    expect(comment["id"]).toBeUndefined();
+    expect((comment["post"] as Record<string, unknown>)["id"]).toBeUndefined();
+    expect((comment["commenter"] as Record<string, unknown>)["id"]).toBeUndefined();
+    expect(
+      ((comment["post"] as Record<string, unknown>)["author"] as Record<string, unknown>)["id"],
+    ).toBeUndefined();
+  });
+
+  it("collects write keys from mutation operations", () => {
+    const compiler = createMockCompiler();
+    const executor = createMockExecutor();
+    const decoder = createMockDecoder();
+    const schemaNamespaceMap: WeakMap<AnySchema, string | null> = new WeakMap();
+    schemaNamespaceMap.set(testSchema, "tenant");
+
+    const baseUow = createUnitOfWork(compiler, executor, decoder, schemaNamespaceMap);
+    const uow = baseUow.forSchema(testSchema);
+
+    const createdId = uow.create("users", { name: "test" });
+    uow.update("users", createdId, (b) => b.set({ name: "next" }));
+    uow.delete("users", createdId);
+
+    const keys = collectWriteKeys(baseUow.getMutationOperations());
+    expect(keys).toEqual(
+      expect.arrayContaining([expect.objectContaining({ table: "users", schema: "tenant" })]),
+    );
+  });
+});