@deterministic-code/datasources 0.0.0-stage → 0.1.0

package/package.json

@@ -1,6 +1,18 @@
 {
   "name": "@deterministic-code/datasources",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./mocks": "./src/mocks/index.ts"
+  },
+  "files": [
+    "src"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT"
+}

package/src/ArrayReader.ts

@@ -0,0 +1,32 @@
+import type { IReader } from "./IReader.ts";
+import { readerToAsyncIterable } from "./readerToAsyncIterable.ts";
+
+export class ArrayReader<T = unknown> implements IReader<T> {
+  private index = -1;
+  current: T | undefined = undefined;
+
+  constructor(private readonly rows: readonly T[]) {}
+
+  async next(): Promise<boolean> {
+    this.index += 1;
+    if (this.index < this.rows.length) {
+      this.current = this.rows[this.index];
+      return true;
+    }
+    this.current = undefined;
+    return false;
+  }
+
+  read(): AsyncIterable<T> {
+    return readerToAsyncIterable(this);
+  }
+
+  async nextResult(): Promise<boolean> {
+    this.current = undefined;
+    return false;
+  }
+
+  async dispose(): Promise<void> {}
+
+  [Symbol.asyncDispose] = (): Promise<void> => this.dispose();
+}

package/src/BatchCommandIBulkWriteStrategy.ts

@@ -0,0 +1,228 @@
+import type { CRUDRepository } from "./CRUDRepository.ts";
+import type { CRUDRepositoryOptions } from "./CRUDRepositoryOptions.ts";
+import type { Response } from "./Response.ts";
+import type { IWhere } from "./statements/IWhere.ts";
+import type { BulkCommand } from "./BulkCommand.ts";
+import { Native } from "./statements/Native.ts";
+import type { IBulkWriteStrategy } from "./IBulkWriteStrategy.ts";
+import { execute, type ICommand } from "./ICommand.ts";
+import type { Cell, Cells } from "./converters/Cell.ts";
+import type { Field } from "./builders/Field.ts";
+import type { Scalar } from "./builders/Scalar.ts";
+import type { IExpression } from "./statements/IExpression.ts";
+import {
+  BulkDeleteStatement,
+  BulkInsertStatement,
+  BulkUpdateStatement,
+  DefaultStatementTextRenderer,
+  Literal,
+  Operator,
+  Where,
+} from "./statements/index.ts";
+import { DatasourceError } from "./DatasourceError.ts";
+import { repositoryParts } from "./CRUDRepositoryBuilder.ts";
+import { MetaDataRowTypeConverter } from "./converters/MetaDataRowTypeConverter.ts";
+import type { Parameter } from "./Parameter.ts";
+import { afterBulkWrite } from "./BulkWriteEnrichment.ts";
+
+const empty = (): Response => ({ result: null, rowsAffected: 0 });
+const budget = 8000;
+const maxRows = 250;
+
+const assigned = (value: Cell): boolean =>
+  value !== null && value !== "" && value !== 0 && value !== 0n;
+
+const columnsOf = (rows: readonly { name: string }[][]): string[] => {
+  const seen = new Set<string>();
+  const columns: string[] = [];
+  for (const row of rows)
+    for (const field of row)
+      if (!seen.has(field.name)) {
+        seen.add(field.name);
+        columns.push(field.name);
+      }
+  return columns;
+};
+
+type Inserted = { table: string; fields: Parameter[] };
+type Updated = { table: string; fields: Parameter[]; ids: Parameter[] };
+type Deleted = { table: string; ids: Parameter[] };
+
+export class BatchCommandIBulkWriteStrategy<T extends object> implements IBulkWriteStrategy<T> {
+  repo!: CRUDRepository<T>;
+  command!: ICommand;
+  options!: CRUDRepositoryOptions<T>;
+  private cached?: ReturnType<typeof repositoryParts>["statements"];
+
+  attach = (command: ICommand, options: CRUDRepositoryOptions<T>): void => {
+    this.command = command;
+    this.options = options;
+  };
+
+  create = (items: T[]): Promise<Response> => this.then(this.writeCreates(items), items, "create");
+
+  update = (items: T[], byWhere: IWhere | undefined): Promise<Response> =>
+    this.then(
+      byWhere ? this.sendEach(items.map((item) => this.updateCommand(item, byWhere))) : this.writeUpdates(items),
+      items,
+      "update",
+    );
+
+  delete = (items: T[], byWhere: IWhere | undefined): Promise<Response> =>
+    this.then(
+      byWhere ? this.sendEach(items.map((item) => this.deleteCommand(item, byWhere))) : this.writeDeletes(items),
+      items,
+      "delete",
+    );
+
+  private then = async (write: Promise<Response>, items: T[], mode: "create" | "update" | "delete"): Promise<Response> => {
+    const response = await write;
+    await afterBulkWrite(this.repo, this.options, items, mode);
+    return response;
+  };
+
+  private writeCreates = async (items: T[]): Promise<Response> => {
+    if (items.length === 0) return empty();
+    const rows = items.map(this.mappedInsert);
+    const columns = columnsOf(rows.map((row) => row.fields));
+    return this.chunked(rows, columns.length, (chunk) => {
+      const statement = new BulkInsertStatement(
+        rows[0]!.table,
+        columns,
+        chunk.map((row) => row.fields),
+      );
+      return execute(this.command, statement, statement.parameters);
+    });
+  };
+
+  private writeUpdates = async (items: T[]): Promise<Response> => {
+    if (items.length === 0) return empty();
+    const rows = items.map(this.mappedUpdate);
+    const set = columnsOf(rows.map((row) => row.fields));
+    const ids = columnsOf(rows.map((row) => row.ids));
+    return this.chunked(rows, set.length + ids.length, (chunk) => {
+      const statement = new BulkUpdateStatement(rows[0]!.table, set, ids, chunk);
+      return execute(this.command, statement, statement.parameters);
+    });
+  };
+
+  private writeDeletes = async (items: T[]): Promise<Response> => {
+    if (items.length === 0) return empty();
+    const rows = items.map(this.mappedDelete);
+    const ids = columnsOf(rows.map((row) => row.ids));
+    return this.chunked(rows, ids.length, (chunk) => {
+      const statement = new BulkDeleteStatement(
+        rows[0]!.table,
+        ids,
+        chunk.map((row) => row.ids),
+      );
+      return execute(this.command, statement, statement.parameters);
+    });
+  };
+
+  private chunked = async <TRow>(
+    rows: TRow[],
+    width: number,
+    write: (chunk: TRow[]) => Promise<Response>,
+  ): Promise<Response> => {
+    const size = Math.min(maxRows, Math.max(1, Math.floor(budget / Math.max(1, width))));
+    let rowsAffected = 0;
+    for (let at = 0; at < rows.length; at += size) rowsAffected += (await write(rows.slice(at, at + size))).rowsAffected;
+    return { result: null, rowsAffected };
+  };
+
+  private sendEach = async (commands: BulkCommand[]): Promise<Response> => {
+    let rowsAffected = 0;
+    for (const command of commands)
+      rowsAffected += (await this.command.executeNative(new Native(command.text), command.parameters)).rowsAffected;
+    return { result: null, rowsAffected };
+  };
+
+  private mappedInsert = (item: T): Inserted => {
+    const record = this.reverse(item);
+    const statement = this.statements().insert(
+      this.fields(record, (col) => !this.ids.includes(col) || assigned(record[col] ?? null)),
+    );
+    return { table: statement.table, fields: statement.fields };
+  };
+
+  private mappedUpdate = (item: T): Updated => {
+    const record = this.reverse(item);
+    const fields = this.fields(record, (col) => !this.ids.includes(col));
+    if (fields.length === 0) throw new DatasourceError("Update requires at least one non-Id field");
+    const statement = this.statements().update(fields, this.idsWhere(record), (name, value) =>
+      this.cell(name, value, true),
+    );
+    return { table: statement.table, fields: statement.fields, ids: statement.where?.parameters ?? [] };
+  };
+
+  private mappedDelete = (item: T): Deleted => {
+    const record = this.reverse(item);
+    const statement = this.statements().delete(this.idsWhere(record), (name, value) => this.cell(name, value, true));
+    return { table: statement.table, ids: statement.where?.parameters ?? [] };
+  };
+
+  private updateCommand = (item: T, byWhere?: IWhere): BulkCommand => {
+    const record = this.reverse(item);
+    const fields = this.fields(record, (col) => !this.ids.includes(col));
+    if (fields.length === 0) throw new DatasourceError("Update requires at least one non-Id field");
+    const statement = this.statements().update(fields, byWhere ?? this.idsWhere(record), (name, value) =>
+      this.cell(name, value, byWhere === undefined),
+    );
+    return { text: DefaultStatementTextRenderer.instance.render(statement), parameters: statement.parameters };
+  };
+
+  private deleteCommand = (item: T, byWhere?: IWhere): BulkCommand => {
+    const record = this.reverse(item);
+    const statement = this.statements().delete(byWhere ?? this.idsWhere(record), (name, value) =>
+      this.cell(name, value, byWhere === undefined),
+    );
+    const listed = statement.where?.parameters ?? [];
+    const parameters: Parameter[] = listed.length
+      ? listed
+      : DefaultStatementTextRenderer.instance.render(statement).includes("$")
+        ? this.fields(record, () => true)
+        : [];
+    return { text: DefaultStatementTextRenderer.instance.render(statement), parameters };
+  };
+
+  private statements = () =>
+    (this.cached ??= repositoryParts(this.command.connection, this.options).statements);
+
+  private get ids(): readonly string[] {
+    return this.options.ids ?? this.repo.ids;
+  }
+
+  private reverse = (item: T): Cells => {
+    const objects = this.options.objectConverter ?? new MetaDataRowTypeConverter<T>();
+    const row = objects.reverseConvert(item);
+    return this.options.rowConverter ? this.options.rowConverter.reverseConvert(row) : row;
+  };
+
+  private fields = (record: Cells, include: (col: string) => boolean): Field[] =>
+    Object.entries(record)
+      .filter(([key, value]) => include(key) && value !== null && value !== undefined)
+      .sort(([left], [right]) => left.localeCompare(right))
+      .map(([name, value]) => ({ name, value: this.cell(name, value, true) as Scalar }));
+
+  private cell = (property: string, value: Cell, fieldsApplied: boolean): Cell =>
+    fieldsApplied
+      ? value
+      : this.options.objectConverter instanceof MetaDataRowTypeConverter &&
+          this.options.objectConverter.fields[property]
+        ? this.options.objectConverter.fields[property]!.reverseConvert(value)
+        : value;
+
+  private idsWhere = (record: Cells): IWhere => {
+    const parts: IExpression[] = this.ids.map((col) => {
+      if (!Object.prototype.hasOwnProperty.call(record, col))
+        throw new DatasourceError(`Missing Id value "${col}"`);
+      return new Operator.Equals(col, record[col] as Scalar);
+    });
+    return new Where(
+      parts.length === 0
+        ? new Operator.Equals(new Literal(1), new Literal(1))
+        : parts.reduce((left, right) => new Operator.And(left, right)),
+    );
+  };
+}

package/src/BuiltRepository.ts

@@ -0,0 +1,17 @@
+import type { IConnection } from "./IConnection.ts";
+import type { Cells } from "./converters/Cell.ts";
+import type { Constructable } from "./converters/Constructable.ts";
+import type { TypeConverter } from "./converters/TypeConverter.ts";
+import type { IMapper } from "./mappers/IMapper.ts";
+import type { ReadonlyRepositoryStatements } from "./ReadonlyRepositoryStatements.ts";
+
+export type BuiltRepository<T = Cells> = {
+  connection: IConnection;
+  rowConverter?: TypeConverter<Cells, Cells>;
+  objectConverter: TypeConverter<T, Cells>;
+  propertyMappings: IMapper<string, string>;
+  entityMapper: IMapper<string, string>;
+  statements: ReadonlyRepositoryStatements;
+  ids: string[];
+  type: Constructable<T>;
+};

package/src/BulkCRUDRepository.ts

@@ -0,0 +1,84 @@
+import type { IConnection } from "./IConnection.ts";
+import type { Constructable } from "./converters/Constructable.ts";
+import type { Cells } from "./converters/Cell.ts";
+import { CRUDRepository } from "./CRUDRepository.ts";
+import type { CRUDRepositoryOptions } from "./CRUDRepositoryOptions.ts";
+import { createCRUDRepositoryOptions } from "./createCRUDRepositoryOptions.ts";
+import type { Response } from "./Response.ts";
+import type { IWhere } from "./statements/IWhere.ts";
+import type { IBulkWriteStrategy } from "./IBulkWriteStrategy.ts";
+import { SingleCommandIBulkWriteStrategy } from "./SingleCommandIBulkWriteStrategy.ts";
+import { UnitOfWorkTransaction } from "./UnitOfWorkTransaction.ts";
+
+const isBulkStrategy = <T extends object>(value: object): value is IBulkWriteStrategy<T> =>
+  "create" in value &&
+  "update" in value &&
+  "delete" in value &&
+  !("persist" in value) &&
+  !("createCommand" in value) &&
+  !("statements" in value);
+
+const transactionOf = <T extends object>(
+  options: IConnection | CRUDRepositoryOptions<T> | IBulkWriteStrategy<T> | undefined,
+): boolean =>
+  options !== undefined && "write" in options ? options.write?.useTransaction ?? false : false;
+
+const inTransaction = async <TResult>(
+  transactional: boolean,
+  connection: IConnection,
+  write: () => Promise<TResult>,
+): Promise<TResult> => {
+  if (!transactional) return write();
+  const work = new UnitOfWorkTransaction(connection);
+  await work.begin();
+  try {
+    const result = await write();
+    await work.commit();
+    return result;
+  } catch (error) {
+    await work.abort();
+    throw error;
+  }
+};
+
+export class BulkCRUDRepository<T extends object = Cells> extends CRUDRepository<T> {
+  private readonly strategy: IBulkWriteStrategy<T>;
+  private readonly transactional: boolean;
+
+  constructor(type: Constructable<T>, connection: IConnection, bulk?: IBulkWriteStrategy<T>);
+  constructor(connection: IConnection, options: CRUDRepositoryOptions<T>, bulk?: IBulkWriteStrategy<T>);
+  constructor(
+    typeOrConnection: Constructable<T> | IConnection,
+    connectionOrOptions?: IConnection | CRUDRepositoryOptions<T> | IBulkWriteStrategy<T>,
+    bulk?: IBulkWriteStrategy<T>,
+  ) {
+    const strategy = bulk ?? (isBulkStrategy<T>(connectionOrOptions ?? {}) ? connectionOrOptions : undefined);
+    const transactional = transactionOf(connectionOrOptions);
+    const parent = (
+      isBulkStrategy(connectionOrOptions ?? {}) ? undefined : connectionOrOptions
+    ) as IConnection & CRUDRepositoryOptions<T>;
+    super(typeOrConnection as Constructable<T> & IConnection, parent);
+    this.strategy = strategy ?? new SingleCommandIBulkWriteStrategy<T>();
+    this.transactional = transactional;
+    this.strategy.repo = this;
+    this.strategy.attach(
+      this.command(),
+      typeof typeOrConnection === "function"
+        ? createCRUDRepositoryOptions(typeOrConnection)
+        : parent,
+    );
+  }
+
+  createBulk = async (items: T[]): Promise<T[]> => {
+    await inTransaction(this.transactional || items.length > 0, this.command().connection, () =>
+      this.strategy.create(items),
+    );
+    return items;
+  };
+
+  updateBulk = (items: T[], byWhere?: IWhere): Promise<Response> =>
+    inTransaction(this.transactional, this.command().connection, () => this.strategy.update(items, byWhere));
+
+  deleteBulk = (items: T[], byWhere?: IWhere): Promise<Response> =>
+    inTransaction(this.transactional, this.command().connection, () => this.strategy.delete(items, byWhere));
+}

package/src/BulkCommand.ts

@@ -0,0 +1,6 @@
+import type { Parameter } from "./Parameter.ts";
+
+export interface BulkCommand {
+  text: string;
+  parameters: Parameter[];
+}

package/src/BulkWriteEnrichment.ts

@@ -0,0 +1,19 @@
+import type { CRUDRepository } from "./CRUDRepository.ts";
+import type { CRUDRepositoryOptions } from "./CRUDRepositoryOptions.ts";
+import { DefaultWriteEnrichmentStrategy } from "./DefaultWriteEnrichmentStrategy.ts";
+import { enrichmentsOf } from "./ReadonlyRepository.ts";
+import { RepositoryTree } from "./RepositoryTree.ts";
+import { RepositoryTreeNode } from "./RepositoryTreeNode.ts";
+import type { WriteMode } from "./WriteMode.ts";
+
+export const afterBulkWrite = async <T extends object>(
+  repo: CRUDRepository<T>,
+  options: CRUDRepositoryOptions<T>,
+  items: T[],
+  mode: WriteMode,
+): Promise<void> => {
+  if (items.length === 0 || !enrichmentsOf(repo)?.length) return;
+  const write = options.write ?? new DefaultWriteEnrichmentStrategy<T>();
+  const tree = new RepositoryTree(new RepositoryTreeNode(repo, ""));
+  await (write.persistBulk ?? write.persist)(tree, items, mode);
+};

package/src/CRUDRepository.ts

@@ -0,0 +1,264 @@
+import type { IConnection } from "./IConnection.ts";
+import type { ICRUDRepository } from "./ICRUDRepository.ts";
+import type { Response } from "./Response.ts";
+import type { IWhere } from "./IWhere.ts";
+import type { Field } from "./builders/Field.ts";
+import type { Scalar } from "./builders/Scalar.ts";
+import type { IExpression } from "./statements/IExpression.ts";
+import { Literal } from "./statements/Literal.ts";
+import { DefaultStatementTextRenderer, Operator, Where } from "./statements/index.ts";
+import type { Cell, Cells } from "./converters/Cell.ts";
+import type { Constructable } from "./converters/Constructable.ts";
+import type { CRUDRepositoryOptions } from "./CRUDRepositoryOptions.ts";
+import { repositoryParts } from "./CRUDRepositoryBuilder.ts";
+import type { CRUDRepositoryStatements } from "./CRUDRepositoryStatements.ts";
+import { MetaDataRowTypeConverter } from "./converters/MetaDataRowTypeConverter.ts";
+import { enrichmentsOf, ReadonlyRepository } from "./ReadonlyRepository.ts";
+import type { Enrichment } from "./Enrichment.ts";
+import type { IReadonlyEnrichmentStrategy } from "./IReadonlyEnrichmentStrategy.ts";
+import type { IReadonlyRepository } from "./IReadonlyRepository.ts";
+import { DefaultReadonlyEnrichmentStrategy } from "./DefaultReadonlyEnrichmentStrategy.ts";
+import { StoredEnrichment } from "./StoredEnrichment.ts";
+import { execute, executeReader } from "./ICommand.ts";
+import { DatasourceError } from "./DatasourceError.ts";
+import { DefaultWriteEnrichmentStrategy } from "./DefaultWriteEnrichmentStrategy.ts";
+import type { IWriteEnrichmentStrategy } from "./IWriteEnrichmentStrategy.ts";
+import { UnitOfWorkTransaction } from "./UnitOfWorkTransaction.ts";
+import type { IRepositoryTree } from "./IRepositoryTree.ts";
+import { RepositoryTree } from "./RepositoryTree.ts";
+import { RepositoryTreeNode } from "./RepositoryTreeNode.ts";
+
+type Props = Record<string, Scalar | object>;
+
+const assigned = (value: Cell): boolean =>
+  value !== null && value !== "" && value !== 0 && value !== 0n;
+
+const fieldsOf = (
+  record: Cells,
+  include: (col: string) => boolean,
+  cell: (property: string, value: Cell, fieldsApplied: boolean) => Cell,
+  enrichmentInto: (name: string) => boolean,
+): Field[] =>
+  Object.entries(record)
+    .filter(([key, value]) => include(key) && !enrichmentInto(key) && value !== null && value !== undefined)
+    .sort(([left], [right]) => left.localeCompare(right))
+    .map(([name, value]) => ({ name, value: cell(name, value, true) as Scalar }));
+
+const isCells = (id: Scalar | Cells): id is Cells => typeof id === "object" && id !== null;
+
+const named = (row: Cells, property: string, sqlColumn: string): Cells => {
+  if (property === sqlColumn || !(sqlColumn in row)) return row;
+  const { [sqlColumn]: cell, ...rest } = row;
+  return { ...rest, [property]: cell };
+};
+
+const identified = (row: Cells, column: string): Cells => {
+  const values = Object.values(row);
+  return column in row || values.length !== 1 ? row : { [column]: values[0] };
+};
+
+const scalarOf = (value: Scalar | object | undefined): Scalar | undefined =>
+  value === undefined || value === null || typeof value === "object" ? undefined : value;
+
+
+export class CRUDRepository<T = Cells>
+  extends ReadonlyRepository<T>
+  implements ICRUDRepository<T>
+{
+  readonly ids: readonly string[];
+  private readonly crudStatements: CRUDRepositoryStatements;
+  private readonly tree: IRepositoryTree;
+  private readonly write: IWriteEnrichmentStrategy<T>;
+  private get useTransaction(): boolean {
+    return this.write.useTransaction;
+  }
+
+  constructor(type: Constructable<T>, connection: IConnection);
+  constructor(connection: IConnection, options: CRUDRepositoryOptions<T>);
+  constructor(
+    typeOrConnection: Constructable<T> | IConnection,
+    connectionOrOptions?: IConnection | CRUDRepositoryOptions<T>,
+  ) {
+    const options = connectionOrOptions as IConnection | CRUDRepositoryOptions<T>;
+    const opened = repositoryParts(typeOrConnection, options);
+    super(opened.built);
+    this.ids = opened.built.ids;
+    this.crudStatements = opened.statements;
+    this.tree = new RepositoryTree(new RepositoryTreeNode(this, ""));
+    this.write = (options as CRUDRepositoryOptions<T>).write ?? new DefaultWriteEnrichmentStrategy<T>();
+  }
+
+  override addEnriched<TRelated extends object>(
+    enrichment: Enrichment,
+    via: IReadonlyRepository<TRelated>,
+    strategy?: IReadonlyEnrichmentStrategy<T & object>,
+  ): this {
+    super.addEnriched(enrichment, via, strategy);
+    const writer = writerOf(via);
+    if (writer) lastEnrichment(this).persist = writer;
+    return this;
+  }
+
+  addLinked<TRelated extends object, TLink extends object>(
+    enrichment: Enrichment,
+    via: IReadonlyRepository<TRelated>,
+    link: ICRUDRepository<TLink>,
+    strategy?: IReadonlyEnrichmentStrategy<T & object>,
+  ): this {
+    const chosen = strategy ?? new DefaultReadonlyEnrichmentStrategy<T & object>();
+    super.addEnriched(enrichment, via, strategy);
+    const stored = lastEnrichment(this) as StoredEnrichment<T & object>;
+    stored.apply = (parents, sources) =>
+      chosen.applyLinked(via, link, enrichment, parents, sources);
+    stored.link = link as ICRUDRepository<object>;
+    return this;
+  }
+
+  create = (item: T): Promise<T> => this.inTransaction(() => this.createCore(item));
+
+  update = (item: T, byWhere?: IWhere): Promise<Response> =>
+    this.inTransaction(() => this.updateCore(item, byWhere));
+
+  delete = (item: T, byWhere?: IWhere): Promise<Response> =>
+    this.inTransaction(() => this.deleteCore(item, byWhere));
+
+  private inTransaction = async <TResult>(write: () => Promise<TResult>): Promise<TResult> => {
+    if (!this.useTransaction) return write();
+    const work = new UnitOfWorkTransaction(this.command().connection);
+    await work.begin();
+    try {
+      const result = await write();
+      await work.commit();
+      return result;
+    } catch (error) {
+      await work.abort();
+      throw error;
+    }
+  };
+
+  private createCore = async (item: T): Promise<T> => {
+    await this.insert(item);
+    if (!this.enriched) return item;
+    await this.write.persist(this.tree, [item], "create");
+    if (this.ids.length !== 1) return item;
+    const id = this.idValue(item);
+    return id === undefined ? item : (await this.readSingleById(id)) ?? item;
+  };
+
+  private updateCore = async (item: T, byWhere?: IWhere): Promise<Response> => {
+    const response = await this.save(item, byWhere);
+    if (this.enriched) await this.write.persist(this.tree, [item], "update");
+    return response;
+  };
+
+  private deleteCore = async (item: T, byWhere?: IWhere): Promise<Response> => {
+    if (this.enriched) await this.write.persist(this.tree, [item], "delete");
+    return this.remove(item, byWhere);
+  };
+
+  readSingleById = async (id: Scalar | Cells): Promise<T | undefined> =>
+    this.readSingle(this.byId(id));
+
+  private insert = async (item: T): Promise<Response> => {
+    const record = this.reverseConvert(item);
+    const fields = fieldsOf(
+      record,
+      (col) => !this.ids.includes(col) || assigned(record[col] ?? null),
+      this.cell,
+      this.enrichmentInto,
+    );
+    const statement = this.crudStatements.insert(fields);
+    const response = await execute(this.command(), statement, statement.fields);
+    if (this.ids.length === 1 && !fields.some((field) => field.name === this.ids[0]))
+      await this.copyInsertedId(item, fields);
+    return response;
+  };
+
+  private copyInsertedId = async (target: T, fields: Field[]): Promise<void> => {
+    void fields;
+    const column = this.ids[0]!;
+    const statement = this.crudStatements.selectInsertedId(column);
+    const sqlColumn = statement.column;
+    const reader = await executeReader(this.command(), statement);
+    try {
+      if (!(await reader.next())) return;
+      const current = reader.current;
+      if (!current) throw new DatasourceError("Reader current must be a row");
+      const row = identified(named(current, column, sqlColumn), column);
+      const cells = this.rowConverter ? this.rowConverter.convert(row) : row;
+      const converted =
+        this.objectConverter instanceof MetaDataRowTypeConverter
+          ? this.objectConverter.convert(cells, this.type)
+          : this.objectConverter!.convert(cells);
+      const value = scalarOf((converted as Props)[column]);
+      if (value !== undefined) (target as Props)[column] = value;
+    } finally {
+      await reader.dispose();
+    }
+  };
+
+  private idValue = (item: T): Scalar | undefined => scalarOf((item as Props)[this.ids[0]!]);
+
+  private save = async (item: T, byWhere?: IWhere): Promise<Response> => {
+    const record = this.reverseConvert(item);
+    const fields = fieldsOf(record, (col) => !this.ids.includes(col), this.cell, this.enrichmentInto);
+    if (fields.length === 0) throw new DatasourceError("Update requires at least one non-Id field");
+    const statement = this.crudStatements.update(
+      fields,
+      byWhere ?? this.idWhere(record),
+      (name, value) => this.cell(name, value, byWhere === undefined),
+    );
+    return execute(this.command(), statement, statement.parameters);
+  };
+
+  private remove = async (item: T, byWhere?: IWhere): Promise<Response> => {
+    const record = this.reverseConvert(item);
+    const statement = this.crudStatements.delete(
+      byWhere ?? this.idWhere(record),
+      (name, value) => this.cell(name, value, byWhere === undefined),
+    );
+    const listed = statement.where?.parameters ?? [];
+    const parameters = listed.length
+      ? listed
+      : DefaultStatementTextRenderer.instance.render(statement).includes("$")
+        ? fieldsOf(record, () => true, this.cell, this.enrichmentInto)
+        : [];
+    return execute(this.command(), statement, parameters);
+  };
+
+  private byId = (id: Scalar | Cells): IWhere => {
+    if (this.ids.length === 0) throw new DatasourceError("ReadSingleById requires an Id column");
+    if (isCells(id)) return this.idWhere(id);
+    if (this.ids.length !== 1)
+      throw new DatasourceError("Composite id requires a row keyed by each Id column");
+    return this.idWhere({ [this.ids[0]!]: id });
+  };
+
+  private reverseConvert = (item: T): Cells => {
+    const row = this.objectConverter!.reverseConvert(item);
+    return this.rowConverter ? this.rowConverter.reverseConvert(row) : row;
+  };
+
+  private idWhere = (record: Cells): IWhere => {
+    const parts: IExpression[] = this.ids.map((col) => {
+      if (!Object.prototype.hasOwnProperty.call(record, col))
+        throw new DatasourceError(`Missing Id value "${col}"`);
+      return new Operator.Equals(col, record[col] as Scalar);
+    });
+    return new Where(
+      parts.length === 0
+        ? new Operator.Equals(new Literal(1), new Literal(1))
+        : parts.reduce((left, right) => new Operator.And(left, right)),
+    );
+  };
+
+  protected enrichmentInto = (name: string): boolean =>
+    enrichmentsOf(this)!.some((entry) => entry.enrichment.destinationProperty === name);
+}
+
+const writerOf = <TRelated extends object>(
+  via: IReadonlyRepository<TRelated>,
+): ICRUDRepository<object> | undefined =>
+  "create" in via && typeof via.create === "function" ? (via as ICRUDRepository<object>) : undefined;
+
+const lastEnrichment = (host: object): StoredEnrichment => enrichmentsOf(host)!.at(-1)!;