@deterministic-code/datasources 0.0.0-stage → 0.1.1

package/src/StreamingReader.ts

@@ -0,0 +1,64 @@
+import type { Cells } from "./converters/Cell.ts";
+import type { IReader } from "./IReader.ts";
+import { readerToAsyncIterable } from "./readerToAsyncIterable.ts";
+
+export class StreamingReader implements IReader<Cells> {
+  current: Cells | undefined = undefined;
+  private closed = false;
+
+  constructor(
+    private readonly pull: () => Promise<Cells | undefined>,
+    private readonly advance: () => Promise<boolean>,
+    private readonly close: () => Promise<void> = async () => {},
+  ) {}
+
+  async next(): Promise<boolean> {
+    this.current = await this.pull();
+    return this.current !== undefined;
+  }
+
+  read(): AsyncIterable<Cells> {
+    return readerToAsyncIterable(this);
+  }
+
+  async nextResult(): Promise<boolean> {
+    this.current = undefined;
+    return this.advance();
+  }
+
+  async dispose(): Promise<void> {
+    if (this.closed) return;
+    this.closed = true;
+    await this.close();
+  }
+
+  [Symbol.asyncDispose] = (): Promise<void> => this.dispose();
+}
+
+export const statementReader = (
+  statements: readonly string[],
+  load: (sql: string) => AsyncIterable<Cells>,
+): StreamingReader => {
+  let index = 0;
+  let rows: AsyncIterator<Cells> | undefined;
+  const closeRows = async () => {
+    await rows?.return?.();
+    rows = undefined;
+  };
+  return new StreamingReader(
+    async () => {
+      if (index >= statements.length) return undefined;
+      const sql = statements[index];
+      if (!sql) return undefined;
+      rows ??= load(sql)[Symbol.asyncIterator]();
+      const step = await rows.next();
+      return step.done ? undefined : step.value;
+    },
+    async () => {
+      await closeRows();
+      index += 1;
+      return index < statements.length;
+    },
+    closeRows,
+  );
+};

package/src/Transaction.test.ts

@@ -0,0 +1,37 @@
+import { afterAll, afterEach, beforeEach, describe, expect, it } from "vitest";
+import { Datasource, DatasourceFactory, MockDriver } from "./index.ts";
+
+const envKeys = [
+  "INSTALLED_PROVIDERS",
+  "DATASOURCE_URL",
+  "PROVIDER",
+] as const;
+const savedEnv = Object.fromEntries(envKeys.map((key) => [key, process.env[key]]));
+
+beforeEach(() => {
+  for (const key of envKeys) delete process.env[key];
+  DatasourceFactory.register("sqlite", new MockDriver());
+  process.env.PROVIDER = "sqlite";
+});
+
+afterEach(() => DatasourceFactory.reset());
+
+afterAll(() => {
+  for (const key of envKeys) {
+    if (savedEnv[key] === undefined) delete process.env[key];
+    else process.env[key] = savedEnv[key];
+  }
+});
+
+describe("Transaction", () => {
+  it("commit or abort", async () => {
+    const ds = Datasource.default;
+    const connection = await ds.createConnection();
+    await connection.open();
+    const txn = await connection.startTransaction();
+    const saved = true;
+    if (saved) await txn.commit();
+    else await txn.abort();
+    expect(txn.isolation).toBe("readCommitted");
+  });
+});

package/src/UnitOfWorkTransaction.test.ts

@@ -0,0 +1,43 @@
+import { describe, expect, it } from "vitest";
+import { DatasourceError, MockConnection, MockTransaction, UnitOfWorkTransaction } from "./index.ts";
+
+describe("UnitOfWorkTransaction", () => {
+  it("joins a transaction already open on the connection", async () => {
+    const connection = new MockConnection();
+    const txn = connection.transaction as MockTransaction;
+    const outer = new UnitOfWorkTransaction(connection);
+    await outer.begin();
+    const inner = new UnitOfWorkTransaction(connection);
+    await inner.begin();
+    await inner.commit();
+    await outer.commit();
+    expect(connection.startTransactionCalls).toBe(1);
+    expect(txn.commitCalls).toBe(1);
+    expect(txn.abortCalls).toBe(0);
+  });
+
+  it("aborts the outer transaction once when a joined unit aborts", async () => {
+    const connection = new MockConnection();
+    const txn = connection.transaction as MockTransaction;
+    const outer = new UnitOfWorkTransaction(connection);
+    await outer.begin();
+    const inner = new UnitOfWorkTransaction(connection);
+    await inner.begin();
+    await inner.abort();
+    await outer.abort();
+    expect(connection.startTransactionCalls).toBe(1);
+    expect(txn.commitCalls).toBe(0);
+    expect(txn.abortCalls).toBe(1);
+  });
+
+  it("rejects a second begin and a unit that never began", async () => {
+    const failed = new MockConnection();
+    failed.startTransactionError = new Error("nope");
+    const broken = new UnitOfWorkTransaction(failed);
+    await expect(broken.begin()).rejects.toThrow("nope");
+    await expect(broken.begin()).rejects.toThrow(DatasourceError);
+    const idle = new UnitOfWorkTransaction(new MockConnection());
+    await expect(idle.commit()).rejects.toThrow("has not begun");
+    await expect(idle.abort()).rejects.toThrow("has not begun");
+  });
+});

package/src/UnitOfWorkTransaction.ts

@@ -0,0 +1,50 @@
+import { DatasourceError } from "./DatasourceError.ts";
+import type { IConnection } from "./IConnection.ts";
+import type { ITransaction } from "./ITransaction.ts";
+import type { IUnitOfWork } from "./IUnitOfWork.ts";
+
+const open = new WeakSet<IConnection>();
+
+export class UnitOfWorkTransaction implements IUnitOfWork {
+  private begun = false;
+  private transaction: ITransaction | undefined;
+
+  constructor(private readonly connection: IConnection) {}
+
+  begin = async (): Promise<void> => {
+    if (this.begun) throw new DatasourceError("Unit of work already begun");
+    this.begun = true;
+    if (open.has(this.connection)) return;
+    open.add(this.connection);
+    try {
+      this.transaction = await this.connection.startTransaction();
+    } catch (error) {
+      open.delete(this.connection);
+      throw error;
+    }
+  };
+
+  commit = async (): Promise<void> => {
+    if (!this.begun) throw new DatasourceError("Unit of work has not begun");
+    const txn = this.transaction;
+    if (!txn) return;
+    await txn.commit();
+    this.release();
+  };
+
+  abort = async (): Promise<void> => {
+    if (!this.begun) throw new DatasourceError("Unit of work has not begun");
+    const txn = this.transaction;
+    if (!txn) return;
+    try {
+      await txn.abort();
+    } finally {
+      this.release();
+    }
+  };
+
+  private release(): void {
+    open.delete(this.connection);
+    this.transaction = undefined;
+  }
+}

package/src/UpdateEnrichmentStrategy.ts

@@ -0,0 +1,97 @@
+import type { Enrichment } from "./Enrichment.ts";
+import type { ICRUDRepository } from "./ICRUDRepository.ts";
+import type { Scalar } from "./builders/Scalar.ts";
+import { defaultId } from "./createCRUDRepositoryOptions.ts";
+import { DatasourceError } from "./DatasourceError.ts";
+import { Operator, Where } from "./statements/index.ts";
+
+type Props = Record<string, Scalar | object>;
+
+export abstract class UpdateEnrichmentStrategy<T> {
+  abstract updateChildren<TChild extends object>(writer: ICRUDRepository<TChild>, enrichment: Enrichment, parent: T): Promise<void>;
+
+  abstract updateLinked<TChild extends object>(writer: ICRUDRepository<TChild>, enrichment: Enrichment, parent: T): Promise<void>;
+
+  protected getCell = <TItem>(item: TItem, name: string): Scalar | object | undefined =>
+    (item as never as Props)[name];
+
+  protected presentCell = (value: Scalar | object | undefined): value is Scalar =>
+    value !== undefined && value !== null && typeof value !== "object" && value !== 0 && value !== 0n && value !== "";
+
+  protected payloadOf = <TChild extends object, TParent>(
+    parent: TParent,
+    into: string,
+    enrichment?: Enrichment,
+  ): TChild[] => mapPayload(this.getCell(parent, into), enrichment) as TChild[];
+
+  protected stampCell = <TItem extends object>(related: TItem, by: string, key: Scalar | object | undefined): void => {
+    if (key === undefined || key === null || typeof key === "object") return;
+    const current = this.getCell(related, by);
+    if (current !== null && typeof current === "object" && !Array.isArray(current)) {
+      const target = current as Props;
+      const id = "Id" in target ? "Id" : "id";
+      target[id] = key;
+      return;
+    }
+    Object.assign(related, { [by]: key });
+  };
+
+  protected hasKey = <TItem extends object>(item: TItem, keys: readonly string[]): boolean =>
+    keys.length > 0 && keys.every((name) => this.presentCell(this.getCell(item, name)));
+
+  protected keyOf = <TItem extends object>(item: TItem, keys: readonly string[]): string =>
+    keys.map((name) => String(this.getCell(item, name) ?? "")).join("\u001f");
+
+  protected namesOf = <TChild extends object>(writer: ICRUDRepository<TChild>, item: TChild): readonly string[] =>
+    writer.ids.length > 0 ? writer.ids : defaultId(Object.keys(item));
+
+  protected linkWhere = (
+    association: NonNullable<Enrichment["association"]>,
+    parentKey: Scalar,
+    relatedKey: Scalar,
+  ): Where =>
+    new Where(
+      new Operator.And(
+        new Operator.Equals(association.parent, parentKey),
+        new Operator.Equals(association.related, relatedKey),
+      ),
+    );
+
+  protected relatedIds = <TParent>(parent: TParent, enrichment: Enrichment): Scalar[] => {
+    const ids: Scalar[] = [];
+    const seen = new Set<string>();
+    for (const related of this.payloadOf<object, TParent>(parent, enrichment.destinationProperty)) {
+      const id = this.getCell(related, enrichment.relatedKey);
+      if (!this.presentCell(id)) throw new DatasourceError(`${enrichment.destinationProperty} requires "${enrichment.relatedKey}"`);
+      const key = String(id);
+      if (seen.has(key)) continue;
+      seen.add(key);
+      ids.push(id);
+    }
+    return ids;
+  };
+
+  protected requiredKey = <TParent>(parent: TParent, enrichment: Enrichment): Scalar => {
+    const key = this.getCell(parent, enrichment.sourceProperty);
+    if (!this.presentCell(key)) throw new DatasourceError(`${enrichment.destinationProperty} requires "${enrichment.sourceProperty}"`);
+    return key;
+  };
+}
+
+const mapPayload = (value: Scalar | object | undefined, enrichment?: Enrichment): object[] => {
+  if (value === undefined || value === null || typeof value === "string") return [];
+  if (Array.isArray(value)) return value.filter((item) => item !== null && typeof item === "object");
+  if (enrichment?.type !== "dictionary" || typeof value !== "object") return [];
+  const keyName = mapKeyName(enrichment.relatedKey);
+  const valueName = enrichment.relatedProperty ?? (keyName === "Key" ? "Value" : "value");
+  return Object.entries(value as Record<string, Scalar | object>)
+    .sort(([left], [right]) => left.localeCompare(right))
+    .map(([key, cell]) =>
+      cell !== null && typeof cell === "object" && !Array.isArray(cell)
+        ? { [keyName]: key, ...(cell as object) }
+        : { [keyName]: key, [valueName]: cell },
+    );
+};
+
+const mapKeyName = (relatedKey: string): string =>
+  relatedKey.includes("_") || relatedKey[0] !== relatedKey[0]?.toUpperCase() ? "key" : "Key";

package/src/UserViewCRUDRepository.test.ts

@@ -0,0 +1,323 @@
+import { describe, expect, it } from "vitest";
+import { MemoryDriver } from "@datasources/memory";
+import { collectAsync } from "./collectAsync.ts";
+import { CRUDRepository } from "./CRUDRepository.ts";
+import { LazyWriteEnrichmentStrategy } from "./LazyWriteEnrichmentStrategy.ts";
+import type { IConnection } from "./IConnection.ts";
+
+class UserView {
+  id = 0;
+  username = "";
+  is_enabled = false;
+  user_type_id = 0;
+  user_type?: UserType;
+  roles: Role[] | null = null;
+  groups: Group[] | null = null;
+}
+
+class UserType {
+  id = 0;
+  name = "";
+}
+
+class Role {
+  id = 0;
+  name = "";
+}
+
+class Group {
+  id = 0;
+  name = "";
+}
+
+class UserRole {
+  user_id = 0;
+  role_id = 0;
+}
+
+class UserGroup {
+  user_id = 0;
+  group_id = 0;
+}
+
+type Graph = {
+  usersRepo: CRUDRepository<UserView>;
+  userTypesRepo: CRUDRepository<UserType>;
+  rolesRepo: CRUDRepository<Role>;
+  groupsRepo: CRUDRepository<Group>;
+  userRolesRepo: CRUDRepository<UserRole>;
+  userGroupsRepo: CRUDRepository<UserGroup>;
+  adminType: UserType;
+  adminRole: Role;
+  editorRole: Role;
+  engineering: Group;
+  ops: Group;
+};
+
+const setup = async (): Promise<IConnection> => {
+  const connection = new MemoryDriver().connection();
+  await connection.open();
+  return connection;
+};
+
+const ids = (values: number[]) => [...values].sort((left, right) => left - right);
+
+const graph = async (write?: LazyWriteEnrichmentStrategy<UserView>): Promise<Graph> => {
+  const connection = await setup();
+  const usersRepo = new CRUDRepository(connection, { type: UserView, write });
+  const userTypesRepo = new CRUDRepository(UserType, connection);
+  const rolesRepo = new CRUDRepository(Role, connection);
+  const groupsRepo = new CRUDRepository(Group, connection);
+  const userRolesRepo = new CRUDRepository(UserRole, connection);
+  const userGroupsRepo = new CRUDRepository(UserGroup, connection);
+  const adminType = await userTypesRepo.create(Object.assign(new UserType(), { name: "admin" }));
+  const adminRole = await rolesRepo.create(Object.assign(new Role(), { name: "admin" }));
+  const editorRole = await rolesRepo.create(Object.assign(new Role(), { name: "editor" }));
+  const engineering = await groupsRepo.create(Object.assign(new Group(), { name: "engineering" }));
+  const ops = await groupsRepo.create(Object.assign(new Group(), { name: "ops" }));
+  return { usersRepo, userTypesRepo, rolesRepo, groupsRepo, userRolesRepo, userGroupsRepo, adminType, adminRole, editorRole, engineering, ops };
+};
+
+const link = (usersRepo: CRUDRepository<UserView>, seeded: Graph): void => {
+  usersRepo.addEnriched({ destinationProperty: "user_type", sourceProperty: "user_type_id", relatedKey: "id" }, seeded.userTypesRepo);
+  usersRepo.addLinked(
+    { destinationProperty: "roles", sourceProperty: "id", relatedKey: "id", association: { parent: "user_id", related: "role_id" } },
+    seeded.rolesRepo,
+    seeded.userRolesRepo,
+  );
+  usersRepo.addLinked(
+    { destinationProperty: "groups", sourceProperty: "id", relatedKey: "id", association: { parent: "user_id", related: "group_id" } },
+    seeded.groupsRepo,
+    seeded.userGroupsRepo,
+  );
+};
+
+const createAda = async (seeded: Graph, roles: Role[] | null, groups: Group[] | null): Promise<UserView> => {
+  link(seeded.usersRepo, seeded);
+  return seeded.usersRepo.create(Object.assign(new UserView(), {
+    username: "ada",
+    is_enabled: true,
+    user_type_id: seeded.adminType.id,
+    roles,
+    groups,
+  }));
+};
+
+describe("CRUDRepository user view", () => {
+  it("creates, updates, and deletes through link rows", async () => {
+    const seeded = await graph();
+    const usersRepo = seeded.usersRepo;
+    usersRepo.addEnriched({ destinationProperty: "user_type", sourceProperty: "user_type_id", relatedKey: "id" }, seeded.userTypesRepo);
+    usersRepo.addLinked(
+      { destinationProperty: "roles", sourceProperty: "id", relatedKey: "id", association: { parent: "user_id", related: "role_id" } },
+      seeded.rolesRepo,
+      seeded.userRolesRepo,
+    );
+    usersRepo.addLinked(
+      { destinationProperty: "groups", sourceProperty: "id", relatedKey: "id", association: { parent: "user_id", related: "group_id" } },
+      seeded.groupsRepo,
+      seeded.userGroupsRepo,
+    );
+    const created = await usersRepo.create(Object.assign(new UserView(), {
+      username: "ada",
+      is_enabled: true,
+      user_type_id: seeded.adminType.id,
+      roles: [seeded.adminRole, seeded.editorRole],
+      groups: [seeded.engineering],
+    }));
+    const createdRoleLinks = await collectAsync(seeded.userRolesRepo.read());
+    const createdGroupLinks = await collectAsync(seeded.userGroupsRepo.read());
+    const saved = await usersRepo.update(Object.assign(new UserView(), {
+      id: created.id,
+      username: "ada",
+      is_enabled: true,
+      user_type_id: seeded.adminType.id,
+      roles: [seeded.editorRole],
+      groups: [seeded.engineering, seeded.ops],
+    }));
+    const updated = await usersRepo.readSingleById(created.id);
+    const updatedRoleLinks = await collectAsync(seeded.userRolesRepo.read());
+    const updatedGroupLinks = await collectAsync(seeded.userGroupsRepo.read());
+    const removed = await usersRepo.delete(Object.assign(new UserView(), { id: created.id }));
+
+    expect(created.id > 0).toEqual(true);
+    expect(created.username).toEqual("ada");
+    expect(created.is_enabled).toEqual(true);
+    expect(created.user_type_id).toEqual(seeded.adminType.id);
+    expect(created.user_type?.name).toEqual("admin");
+    expect(ids(created.roles?.map((role) => role.id) ?? [])).toEqual(ids([seeded.adminRole.id, seeded.editorRole.id]));
+    expect(created.groups?.map((group) => group.name)).toEqual(["engineering"]);
+    expect(createdRoleLinks.map((linkRow) => linkRow.user_id)).toEqual([created.id, created.id]);
+    expect(ids(createdRoleLinks.map((linkRow) => linkRow.role_id))).toEqual(ids([seeded.adminRole.id, seeded.editorRole.id]));
+    expect(createdGroupLinks.map((linkRow) => linkRow.user_id)).toEqual([created.id]);
+    expect(createdGroupLinks.map((linkRow) => linkRow.group_id)).toEqual([seeded.engineering.id]);
+    expect(saved.rowsAffected).toEqual(1);
+    expect(updated?.id).toEqual(created.id);
+    expect(updated?.username).toEqual("ada");
+    expect(updated?.is_enabled).toEqual(true);
+    expect(updated?.user_type_id).toEqual(seeded.adminType.id);
+    expect(updated?.roles?.map((role) => role.id)).toEqual([seeded.editorRole.id]);
+    expect(ids(updated?.groups?.map((group) => group.id) ?? [])).toEqual(ids([seeded.engineering.id, seeded.ops.id]));
+    expect(updatedRoleLinks.map((linkRow) => linkRow.user_id)).toEqual([created.id]);
+    expect(updatedRoleLinks.map((linkRow) => linkRow.role_id)).toEqual([seeded.editorRole.id]);
+    expect(updatedGroupLinks.map((linkRow) => linkRow.user_id)).toEqual([created.id, created.id]);
+    expect(ids(updatedGroupLinks.map((linkRow) => linkRow.group_id))).toEqual(ids([seeded.engineering.id, seeded.ops.id]));
+    expect(removed.rowsAffected).toEqual(1);
+    expect(await collectAsync(usersRepo.read())).toEqual([]);
+    expect(await collectAsync(seeded.userRolesRepo.read())).toEqual([]);
+    expect(await collectAsync(seeded.userGroupsRepo.read())).toEqual([]);
+    expect((await collectAsync(seeded.rolesRepo.read())).map((role) => role.name).sort()).toEqual(["admin", "editor"]);
+    expect((await collectAsync(seeded.groupsRepo.read())).map((group) => group.name).sort()).toEqual(["engineering", "ops"]);
+    expect((await collectAsync(seeded.userTypesRepo.read())).map((type) => type.name)).toEqual(["admin"]);
+  });
+
+  it("clears one association when the list is null", async () => {
+    const seeded = await graph();
+    const created = await createAda(seeded, [seeded.adminRole, seeded.editorRole], [seeded.engineering]);
+    const saved = await seeded.usersRepo.update(Object.assign(new UserView(), {
+      id: created.id,
+      username: "ada",
+      is_enabled: true,
+      user_type_id: seeded.adminType.id,
+      roles: null,
+      groups: [seeded.engineering],
+    }));
+    const loaded = await seeded.usersRepo.readSingleById(created.id);
+    const userRoles = await collectAsync(seeded.userRolesRepo.read());
+    const userGroups = await collectAsync(seeded.userGroupsRepo.read());
+
+    expect(created.id > 0).toEqual(true);
+    expect(saved.rowsAffected).toEqual(1);
+    expect(loaded?.id).toEqual(created.id);
+    expect(loaded?.username).toEqual("ada");
+    expect(loaded?.user_type_id).toEqual(seeded.adminType.id);
+    expect(loaded?.user_type?.name).toEqual("admin");
+    expect(loaded?.roles ?? []).toEqual([]);
+    expect(loaded?.groups?.map((group) => group.id)).toEqual([seeded.engineering.id]);
+    expect(userRoles).toEqual([]);
+    expect(userGroups.map((linkRow) => linkRow.user_id)).toEqual([created.id]);
+    expect(userGroups.map((linkRow) => linkRow.group_id)).toEqual([seeded.engineering.id]);
+    expect((await collectAsync(seeded.rolesRepo.read())).map((role) => role.name).sort()).toEqual(["admin", "editor"]);
+    expect((await collectAsync(seeded.groupsRepo.read())).map((group) => group.name).sort()).toEqual(["engineering", "ops"]);
+  });
+
+  it("clears one association when the list is empty", async () => {
+    const seeded = await graph();
+    const created = await createAda(seeded, [seeded.adminRole, seeded.editorRole], [seeded.engineering]);
+    const saved = await seeded.usersRepo.update(Object.assign(new UserView(), {
+      id: created.id,
+      username: "ada",
+      is_enabled: true,
+      user_type_id: seeded.adminType.id,
+      roles: [],
+      groups: [seeded.engineering],
+    }));
+    const loaded = await seeded.usersRepo.readSingleById(created.id);
+    const userRoles = await collectAsync(seeded.userRolesRepo.read());
+    const userGroups = await collectAsync(seeded.userGroupsRepo.read());
+
+    expect(created.id > 0).toEqual(true);
+    expect(saved.rowsAffected).toEqual(1);
+    expect(loaded?.id).toEqual(created.id);
+    expect(loaded?.username).toEqual("ada");
+    expect(loaded?.user_type_id).toEqual(seeded.adminType.id);
+    expect(loaded?.user_type?.name).toEqual("admin");
+    expect(loaded?.roles ?? []).toEqual([]);
+    expect(loaded?.groups?.map((group) => group.id)).toEqual([seeded.engineering.id]);
+    expect(userRoles).toEqual([]);
+    expect(userGroups.map((linkRow) => linkRow.user_id)).toEqual([created.id]);
+    expect(userGroups.map((linkRow) => linkRow.group_id)).toEqual([seeded.engineering.id]);
+    expect((await collectAsync(seeded.rolesRepo.read())).map((role) => role.name).sort()).toEqual(["admin", "editor"]);
+    expect((await collectAsync(seeded.groupsRepo.read())).map((group) => group.name).sort()).toEqual(["engineering", "ops"]);
+  });
+
+  it("inserts one junction row for a duplicate related id", async () => {
+    const seeded = await graph();
+    const created = await createAda(seeded, [seeded.adminRole, seeded.adminRole], [seeded.engineering]);
+    const roleLinks = await collectAsync(seeded.userRolesRepo.read());
+    const groupLinks = await collectAsync(seeded.userGroupsRepo.read());
+
+    expect(created.id > 0).toEqual(true);
+    expect(roleLinks.map((linkRow) => linkRow.user_id)).toEqual([created.id]);
+    expect(roleLinks.map((linkRow) => linkRow.role_id)).toEqual([seeded.adminRole.id]);
+    expect(groupLinks.map((linkRow) => linkRow.user_id)).toEqual([created.id]);
+    expect(groupLinks.map((linkRow) => linkRow.group_id)).toEqual([seeded.engineering.id]);
+    expect((await collectAsync(seeded.rolesRepo.read())).map((role) => role.name).sort()).toEqual(["admin", "editor"]);
+  });
+
+  it("lazy write skips unloaded links", async () => {
+    const seeded = await graph(new LazyWriteEnrichmentStrategy());
+    link(seeded.usersRepo, seeded);
+    const created = await seeded.usersRepo.create(Object.assign(new UserView(), {
+      username: "ada",
+      is_enabled: true,
+      user_type_id: seeded.adminType.id,
+      roles: null,
+      groups: [seeded.engineering],
+    }));
+    const createdRoleLinks = await collectAsync(seeded.userRolesRepo.read());
+    const createdGroupLinks = await collectAsync(seeded.userGroupsRepo.read());
+    const skipped = await seeded.usersRepo.update(Object.assign(new UserView(), {
+      id: created.id,
+      username: "ada",
+      is_enabled: false,
+      user_type_id: seeded.adminType.id,
+    }));
+    const afterSkip = await seeded.usersRepo.readSingleById(created.id);
+    const skippedRoleLinks = await collectAsync(seeded.userRolesRepo.read());
+    const skippedGroupLinks = await collectAsync(seeded.userGroupsRepo.read());
+    const linked = await seeded.usersRepo.update(Object.assign(new UserView(), {
+      id: created.id,
+      username: "ada",
+      is_enabled: false,
+      user_type_id: seeded.adminType.id,
+      roles: [seeded.editorRole],
+    }));
+    const linkedRoleLinks = await collectAsync(seeded.userRolesRepo.read());
+    const linkedGroupLinks = await collectAsync(seeded.userGroupsRepo.read());
+    const removed = await seeded.usersRepo.delete(Object.assign(new UserView(), { id: created.id, roles: null, groups: null }));
+
+    expect(created.id > 0).toEqual(true);
+    expect(createdRoleLinks).toEqual([]);
+    expect(createdGroupLinks.map((linkRow) => linkRow.user_id)).toEqual([created.id]);
+    expect(createdGroupLinks.map((linkRow) => linkRow.group_id)).toEqual([seeded.engineering.id]);
+    expect(skipped.rowsAffected).toEqual(1);
+    expect(afterSkip?.id).toEqual(created.id);
+    expect(afterSkip?.username).toEqual("ada");
+    expect(afterSkip?.is_enabled).toEqual(false);
+    expect(skippedRoleLinks).toEqual([]);
+    expect(skippedGroupLinks.map((linkRow) => linkRow.user_id)).toEqual([created.id]);
+    expect(skippedGroupLinks.map((linkRow) => linkRow.group_id)).toEqual([seeded.engineering.id]);
+    expect(linked.rowsAffected).toEqual(1);
+    expect(linkedRoleLinks.map((linkRow) => linkRow.user_id)).toEqual([created.id]);
+    expect(linkedRoleLinks.map((linkRow) => linkRow.role_id)).toEqual([seeded.editorRole.id]);
+    expect(linkedGroupLinks.map((linkRow) => linkRow.user_id)).toEqual([created.id]);
+    expect(linkedGroupLinks.map((linkRow) => linkRow.group_id)).toEqual([seeded.engineering.id]);
+    expect((await collectAsync(seeded.rolesRepo.read())).map((role) => role.name).sort()).toEqual(["admin", "editor"]);
+    expect((await collectAsync(seeded.groupsRepo.read())).map((group) => group.name).sort()).toEqual(["engineering", "ops"]);
+    expect(removed.rowsAffected).toEqual(1);
+    expect(await collectAsync(seeded.usersRepo.read())).toEqual([]);
+    expect(await collectAsync(seeded.userRolesRepo.read())).toEqual([]);
+    expect(await collectAsync(seeded.userGroupsRepo.read())).toEqual([]);
+  });
+
+  it("rejects a link without an id", async () => {
+    const seeded = await graph();
+    seeded.usersRepo.addLinked(
+      { destinationProperty: "roles", sourceProperty: "id", relatedKey: "id", association: { parent: "user_id", related: "role_id" } },
+      seeded.rolesRepo,
+      seeded.userRolesRepo,
+    );
+    await expect(seeded.usersRepo.create(Object.assign(new UserView(), {
+      username: "ada",
+      user_type_id: seeded.adminType.id,
+      is_enabled: true,
+      roles: [new Role()],
+    }))).rejects.toThrow(/requires "id"/);
+    const users = await collectAsync(seeded.usersRepo.read());
+    expect(users.length).toEqual(1);
+    expect(users[0]!.id > 0).toEqual(true);
+    expect(users[0]!.username).toEqual("ada");
+    expect(await collectAsync(seeded.userRolesRepo.read())).toEqual([]);
+  });
+});

package/src/WriteMode.ts

@@ -0,0 +1 @@
+export type WriteMode = "create" | "update" | "delete";

package/src/builders/Field.ts

@@ -0,0 +1,6 @@
+import type { Scalar } from "./Scalar.ts";
+
+export interface Field {
+  name: string;
+  value: Scalar;
+}

package/src/builders/Scalar.ts

@@ -0,0 +1 @@
+export type Scalar = string | number | boolean | bigint | null;