@deterministic-code/datasources 0.0.0-stage → 0.1.1

package/src/DefaultReadonlyEnrichmentStrategy.ts

@@ -0,0 +1,164 @@
+import type { Scalar } from "./builders/Scalar.ts";
+import { DatasourceError } from "./DatasourceError.ts";
+import type { Enrichment } from "./Enrichment.ts";
+import { EnrichmentPropertyType } from "./EnrichmentPropertyType.ts";
+import type { IReadonlyEnrichmentStrategy } from "./IReadonlyEnrichmentStrategy.ts";
+import type { IReadonlyRepository } from "./IReadonlyRepository.ts";
+import type { Row } from "./Row.ts";
+import { Operator, Where } from "./statements/index.ts";
+
+type Props = Record<string, Scalar | object>;
+
+export class DefaultReadonlyEnrichmentStrategy<T extends object>
+  implements IReadonlyEnrichmentStrategy<T>
+{
+  apply<TRelated extends object>(
+    via: IReadonlyRepository<TRelated>,
+    enrichment: Enrichment,
+    parents: T[],
+    sources?: (Row | undefined)[],
+  ): Promise<void> {
+    const type = enrichment.type ?? EnrichmentPropertyType.Object;
+    const run = {
+      [EnrichmentPropertyType.List]: () => this.applyList(via, enrichment, parents, sources),
+      [EnrichmentPropertyType.Object]: () => this.applyObject(via, enrichment, parents, sources),
+      [EnrichmentPropertyType.Dictionary]: () => this.applyDictionary(via, enrichment, parents, sources),
+    }[type];
+    return run ? run() : Promise.reject(new DatasourceError(`Unsupported enrichment type "${type}"`));
+  }
+
+  async applyLinked<TRelated extends object, TLink extends object>(
+    via: IReadonlyRepository<TRelated>,
+    link: IReadonlyRepository<TLink>,
+    enrichment: Enrichment,
+    parents: T[],
+    sources?: (Row | undefined)[],
+  ): Promise<void> {
+    const association = enrichment.association ?? (() => {
+      throw new DatasourceError("Missing association");
+    })();
+    for (const [index, parent] of parents.entries()) {
+      const key = this.sourceKey(parent, enrichment.sourceProperty, sources, index);
+      if (key === undefined || key === null) continue;
+      const related: TRelated[] = [];
+      for await (const row of link.read(
+        new Where(new Operator.Equals(association.parent, this.scalar(key))),
+      )) {
+        const id = this.props(row)[association.related];
+        if (id === undefined || id === null || typeof id === "object") continue;
+        const entity = await via.readSingle(new Where(new Operator.Equals(enrichment.relatedKey, id)));
+        if (entity) related.push(entity);
+      }
+      Object.assign(parent, { [enrichment.destinationProperty]: related });
+    }
+  }
+
+  protected async applyObject<TRelated extends object>(
+    via: IReadonlyRepository<TRelated>,
+    enrichment: Enrichment,
+    parents: T[],
+    sources?: (Row | undefined)[],
+  ): Promise<void> {
+    const cache = new Map<string, TRelated | undefined>();
+    for (const [index, parent] of parents.entries()) {
+      const key = this.sourceKey(parent, enrichment.sourceProperty, sources, index);
+      if (key === undefined || key === null) continue;
+      const cacheKey = this.keyOf(key);
+      if (!cache.has(cacheKey))
+        cache.set(
+          cacheKey,
+          await via.readSingle(new Where(new Operator.Equals(enrichment.relatedKey, this.scalar(key)))),
+        );
+      const related = cache.get(cacheKey);
+      if (!related) continue;
+      Object.assign(parent, {
+        [enrichment.destinationProperty]: enrichment.relatedProperty ? this.props(related)[enrichment.relatedProperty] : related,
+      });
+    }
+  }
+
+  protected async applyList<TRelated extends object>(
+    via: IReadonlyRepository<TRelated>,
+    enrichment: Enrichment,
+    parents: T[],
+    sources?: (Row | undefined)[],
+  ): Promise<void> {
+    for (const [index, parent] of parents.entries()) {
+      const key = this.sourceKey(parent, enrichment.sourceProperty, sources, index);
+      if (key === undefined || key === null) continue;
+      const related: TRelated[] = [];
+      for await (const item of via.read(
+        new Where(new Operator.Equals(enrichment.relatedKey, this.scalar(key))),
+      ))
+        related.push(item);
+      Object.assign(parent, { [enrichment.destinationProperty]: related });
+    }
+  }
+
+  protected async applyDictionary<TRelated extends object>(
+    via: IReadonlyRepository<TRelated>,
+    enrichment: Enrichment,
+    parents: T[],
+    sources?: (Row | undefined)[],
+  ): Promise<void> {
+    const mapKey = mapKeyName(enrichment.relatedKey);
+    for (const [index, parent] of parents.entries()) {
+      const key = this.sourceKey(parent, enrichment.sourceProperty, sources, index);
+      if (key === undefined || key === null) continue;
+      const map: Record<string, Scalar | object> = {};
+      for await (const item of via.read(
+        new Where(new Operator.Equals(enrichment.relatedKey, this.scalar(key))),
+      )) {
+        const row = this.props(item);
+        const entry = row[mapKey];
+        if (entry === undefined || entry === null || typeof entry === "object") continue;
+        map[String(entry)] = enrichment.relatedProperty
+          ? (row[enrichment.relatedProperty] ?? null)
+          : Object.fromEntries(
+              Object.entries(row).filter(
+                ([name]) => name !== mapKey && name !== enrichment.relatedKey && name !== "Id" && name !== "id",
+              ),
+            );
+      }
+      Object.assign(parent, { [enrichment.destinationProperty]: map });
+    }
+  }
+
+  protected sourceKey(
+    parent: T,
+    name: string,
+    sources: (Row | undefined)[] | undefined,
+    index: number,
+  ): Scalar | object | undefined {
+    const cell = sources?.[index]?.[name];
+    const raw = cell !== undefined && cell !== null ? cell : this.props(parent)[name];
+    return this.lookupKey(raw);
+  }
+
+  protected props = <TItem>(item: TItem): Props => item as never as Props;
+
+  protected keyOf = (key: Scalar | object): string => String(this.lookupKey(key));
+
+  protected lookupKey = (value: Scalar | object | undefined): Scalar | object | undefined => {
+    if (value === undefined || value === null || typeof value !== "object") return value;
+    const id = this.props(value).Id ?? this.props(value).id;
+    return id !== undefined && id !== null && typeof id !== "object" ? id : value;
+  };
+
+  protected scalar = (value: Scalar | object): Scalar => {
+    const key = this.lookupKey(value);
+    return key === null ||
+      typeof key === "string" ||
+      typeof key === "number" ||
+      typeof key === "boolean" ||
+      typeof key === "bigint"
+      ? key
+      : (() => {
+          throw new DatasourceError("Enrichment key must be a scalar");
+        })();
+  };
+}
+
+const mapKeyName = (relatedKey: string): string =>
+  relatedKey.includes("_") || relatedKey[0] !== relatedKey[0]?.toUpperCase() ? "key" : "Key";
+

package/src/DefaultUpdateEnrichmentStrategy.ts

@@ -0,0 +1,40 @@
+import { DatasourceError } from "./DatasourceError.ts";
+import { DeleteEnrichmentStrategy } from "./DeleteEnrichmentStrategy.ts";
+import type { Enrichment } from "./Enrichment.ts";
+import type { ICRUDRepository } from "./ICRUDRepository.ts";
+import { UpdateEnrichmentStrategy } from "./UpdateEnrichmentStrategy.ts";
+
+export class DefaultUpdateEnrichmentStrategy<T> extends UpdateEnrichmentStrategy<T> {
+  async updateChildren<TChild extends object>(writer: ICRUDRepository<TChild>, enrichment: Enrichment, parent: T): Promise<void> {
+    const existing = await DeleteEnrichmentStrategy.load(writer, enrichment, parent);
+    const rows = this.payloadOf<TChild, T>(parent, enrichment.destinationProperty, enrichment);
+    for (const related of rows) this.stampCell(related, enrichment.relatedKey, this.getCell(parent, enrichment.sourceProperty));
+    const keys = this.namesOf(writer, rows[0] ?? existing[0] ?? {} as TChild);
+    const keep = new Set(rows.filter((row) => this.hasKey(row, keys)).map((row) => this.keyOf(row, keys)));
+    for (const row of existing.filter((row) => !keep.has(this.keyOf(row, keys))))
+      await writer.delete(row, DeleteEnrichmentStrategy.childrenWhere(writer, enrichment, parent));
+    for (const related of rows)
+      this.hasKey(related, keys) && existing.some((row) => this.keyOf(row, keys) === this.keyOf(related, keys))
+        ? await writer.update(related)
+        : await writer.create(related);
+  }
+
+  async updateLinked<TChild extends object>(writer: ICRUDRepository<TChild>, enrichment: Enrichment, parent: T): Promise<void> {
+    const association = enrichment.association;
+    if (!association) throw new DatasourceError("Missing association");
+    const parentKey = this.requiredKey(parent, enrichment);
+    const existing = await DeleteEnrichmentStrategy.loadLinks(writer, association.parent, parentKey);
+    const wanted = this.relatedIds(parent, enrichment);
+    const keep = new Set(wanted.map((id) => String(id)));
+    for (const row of existing) {
+      const id = this.getCell(row, association.related);
+      if (this.presentCell(id) && keep.has(String(id))) continue;
+      if (!this.presentCell(id)) continue;
+      await writer.delete(row, this.linkWhere(association, parentKey, id));
+    }
+    for (const id of wanted) {
+      if (existing.some((row) => String(this.getCell(row, association.related) ?? "") === String(id))) continue;
+      await writer.create({ [association.parent]: parentKey, [association.related]: id } as TChild);
+    }
+  }
+}

package/src/DefaultWriteEnrichmentStrategy.ts

@@ -0,0 +1,151 @@
+import { CascadeDeleteEnrichmentStrategy } from "./CascadeDeleteEnrichmentStrategy.ts";
+import type { CreateEnrichmentStrategy } from "./CreateEnrichmentStrategy.ts";
+import { DatasourceError } from "./DatasourceError.ts";
+import { DefaultCreateEnrichmentStrategy } from "./DefaultCreateEnrichmentStrategy.ts";
+import { EnrichmentPropertyType } from "./EnrichmentPropertyType.ts";
+import { DefaultUpdateEnrichmentStrategy } from "./DefaultUpdateEnrichmentStrategy.ts";
+import type { ICRUDRepository } from "./ICRUDRepository.ts";
+import { enrichmentsOf } from "./ReadonlyRepository.ts";
+import type { IRepositoryTree } from "./IRepositoryTree.ts";
+import type { IWriteEnrichmentStrategy } from "./IWriteEnrichmentStrategy.ts";
+import type { StoredEnrichment } from "./StoredEnrichment.ts";
+import type { Scalar } from "./builders/Scalar.ts";
+import type { DeleteEnrichmentStrategy } from "./DeleteEnrichmentStrategy.ts";
+import type { UpdateEnrichmentStrategy } from "./UpdateEnrichmentStrategy.ts";
+import type { WriteMode } from "./WriteMode.ts";
+
+const unloaded = <TParent>(parent: TParent, into: string): boolean => {
+  const value = (parent as never as Record<string, Scalar | object>)[into];
+  return value === undefined || value === null;
+};
+
+const childWriter = (entry: StoredEnrichment, into: string): ICRUDRepository<object> => {
+  if (entry.persist) return entry.persist;
+  throw new DatasourceError(`Deep write requires a CRUD repository for "${into}"`);
+};
+
+const linkWriter = (entry: StoredEnrichment, into: string): ICRUDRepository<object> => {
+  if (entry.link) return entry.link;
+  throw new DatasourceError(`Deep write requires a CRUD repository for "${into}"`);
+};
+
+const dispatch = (mode: string, runs: Record<WriteMode, () => Promise<void>>): Promise<void> =>
+  (runs[mode as WriteMode] ??
+    (() => {
+      throw new DatasourceError("Unknown persist mode");
+    }))();
+
+export class DefaultWriteEnrichmentStrategy<T> implements IWriteEnrichmentStrategy<T> {
+  protected skipUnloaded = false;
+  readonly useTransaction: boolean;
+  private readonly createStrategy: CreateEnrichmentStrategy<T>;
+  private readonly deleteStrategy: DeleteEnrichmentStrategy<T>;
+  private readonly updateStrategy: UpdateEnrichmentStrategy<T>;
+
+  constructor(
+    deleteStrategy: DeleteEnrichmentStrategy<T> = new CascadeDeleteEnrichmentStrategy<T>(),
+    updateStrategy: UpdateEnrichmentStrategy<T> = new DefaultUpdateEnrichmentStrategy<T>(),
+    createStrategy: CreateEnrichmentStrategy<T> = new DefaultCreateEnrichmentStrategy<T>(),
+    useTransaction = false,
+  ) {
+    this.deleteStrategy = deleteStrategy;
+    this.updateStrategy = updateStrategy;
+    this.createStrategy = createStrategy;
+    this.useTransaction = useTransaction;
+  }
+
+  persist = async (tree: IRepositoryTree, items: T[], mode: WriteMode): Promise<void> => {
+    await this.walk(tree.parent.value, items, mode);
+  };
+
+  persistBulk = async (tree: IRepositoryTree, items: T[], mode: WriteMode): Promise<void> => {
+    if (mode === "delete") return this.persist(tree, items, mode);
+    await this.walkBulk(tree.parent.value, items, mode);
+  };
+
+  private walk = async (host: object, parents: T[], mode: WriteMode): Promise<void> => {
+    const entries = enrichmentsOf(host);
+    if (!entries) return;
+    for (const entry of entries) await this.persistEntry(entry, parents, mode);
+  };
+
+  private walkBulk = async (host: object, parents: T[], mode: WriteMode): Promise<void> => {
+    const entries = enrichmentsOf(host);
+    if (!entries) return;
+    for (const entry of entries) await this.persistEntryBulk(entry, parents, mode);
+  };
+
+  private persistEntryBulk = async (
+    entry: StoredEnrichment,
+    parents: T[],
+    mode: WriteMode,
+  ): Promise<void> => {
+    const enrichment = entry.enrichment;
+    const type = enrichment.type ?? EnrichmentPropertyType.Object;
+    if (type === EnrichmentPropertyType.Custom)
+      throw new DatasourceError(`Unsupported enrichment type "${type}"`);
+    if (enrichment.association) {
+      const writer = linkWriter(entry, enrichment.destinationProperty);
+      for (const parent of parents) {
+        if (this.skip(parent, enrichment.destinationProperty, mode)) continue;
+        await dispatch(mode, {
+          create: () => this.createStrategy.createLinked(writer, enrichment, parent),
+          update: () => this.updateStrategy.updateLinked(writer, enrichment, parent),
+          delete: () => this.deleteStrategy.deleteLinked(writer, enrichment, parent),
+        });
+      }
+      return;
+    }
+    if (type === EnrichmentPropertyType.List && enrichment.relatedProperty) return;
+    if (type !== EnrichmentPropertyType.List && type !== EnrichmentPropertyType.Dictionary) return;
+    const writer = childWriter(entry, enrichment.destinationProperty);
+    const ready = parents.filter((parent) => !this.skip(parent, enrichment.destinationProperty, mode));
+    const children = ready.flatMap((parent) => this.createStrategy.collectChildren(writer, enrichment, parent));
+    if (children.length === 0) return;
+    const bulk = writer as ICRUDRepository<object> & { createBulk?: (items: object[]) => Promise<object[]>; updateBulk?: (items: object[]) => Promise<unknown> };
+    if (mode === "create") {
+      if (bulk.createBulk) await bulk.createBulk(children);
+      else for (const child of children) await writer.create(child);
+      return;
+    }
+    if (bulk.updateBulk) await bulk.updateBulk(children);
+    else for (const child of children) await writer.update(child);
+  };
+
+  private persistEntry = async (
+    entry: StoredEnrichment,
+    parents: T[],
+    mode: WriteMode,
+  ): Promise<void> => {
+    const enrichment = entry.enrichment;
+    const type = enrichment.type ?? EnrichmentPropertyType.Object;
+    if (type === EnrichmentPropertyType.Custom)
+      throw new DatasourceError(`Unsupported enrichment type "${type}"`);
+    if (enrichment.association) {
+      const writer = linkWriter(entry, enrichment.destinationProperty);
+      for (const parent of parents) {
+        if (this.skip(parent, enrichment.destinationProperty, mode)) continue;
+        await dispatch(mode, {
+          create: () => this.createStrategy.createLinked(writer, enrichment, parent),
+          update: () => this.updateStrategy.updateLinked(writer, enrichment, parent),
+          delete: () => this.deleteStrategy.deleteLinked(writer, enrichment, parent),
+        });
+      }
+      return;
+    }
+    if (type === EnrichmentPropertyType.List && enrichment.relatedProperty) return;
+    if (type !== EnrichmentPropertyType.List && type !== EnrichmentPropertyType.Dictionary) return;
+    const writer = childWriter(entry, enrichment.destinationProperty);
+    for (const parent of parents) {
+      if (this.skip(parent, enrichment.destinationProperty, mode)) continue;
+      await dispatch(mode, {
+        create: () => this.createStrategy.createChildren(writer, enrichment, parent),
+        update: () => this.updateStrategy.updateChildren(writer, enrichment, parent),
+        delete: () => this.deleteStrategy.deleteChildren(writer, enrichment, parent, async () => {}),
+      });
+    }
+  };
+
+  private skip = (parent: T, into: string, mode: string): boolean =>
+    this.skipUnloaded && mode !== "delete" && unloaded(parent, into);
+}

package/src/DeleteEnrichmentStrategy.ts

@@ -0,0 +1,56 @@
+import type { Enrichment } from "./Enrichment.ts";
+import type { ICRUDRepository } from "./ICRUDRepository.ts";
+import type { Scalar } from "./builders/Scalar.ts";
+import { Operator, Where } from "./statements/index.ts";
+
+type Props = Record<string, Scalar | object>;
+
+const get = <TItem>(item: TItem, name: string): Scalar | object | undefined =>
+  (item as never as Props)[name];
+
+export abstract class DeleteEnrichmentStrategy<T> {
+  abstract deleteChildren<TChild extends object>(
+    writer: ICRUDRepository<TChild>,
+    enrichment: Enrichment,
+    parent: T,
+    deleteNested: (rows: TChild[]) => Promise<void>,
+  ): Promise<void>;
+
+  abstract deleteLinked<TChild extends object>(writer: ICRUDRepository<TChild>, enrichment: Enrichment, parent: T): Promise<void>;
+
+  static load = async <TParent, TChild extends object>(
+    writer: ICRUDRepository<TChild>,
+    enrichment: Enrichment,
+    parent: TParent,
+  ): Promise<TChild[]> => {
+    const key = get(parent, enrichment.sourceProperty);
+    if (key === undefined || key === null || typeof key === "object") return [];
+    const items: TChild[] = [];
+    for await (const item of writer.read(new Where(new Operator.Equals(enrichment.relatedKey, key))))
+      items.push(item);
+    return items;
+  };
+
+  static childrenWhere = <TParent, TChild extends object>(
+    writer: ICRUDRepository<TChild>,
+    enrichment: Enrichment,
+    parent: TParent,
+  ): Where | undefined => {
+    if (writer.ids.length > 0) return undefined;
+    const key = get(parent, enrichment.sourceProperty);
+    return key === undefined || key === null || typeof key === "object"
+      ? undefined
+      : new Where(new Operator.Equals(enrichment.relatedKey, key));
+  };
+
+  static loadLinks = async <TChild extends object>(
+    writer: ICRUDRepository<TChild>,
+    column: string,
+    key: Scalar,
+  ): Promise<TChild[]> => {
+    const items: TChild[] = [];
+    for await (const item of writer.read(new Where(new Operator.Equals(column, key))))
+      items.push(item);
+    return items;
+  };
+};

package/src/DriverLoader.ts

@@ -0,0 +1,97 @@
+import { readFileSync } from "node:fs";
+import { createRequire, registerHooks } from "node:module";
+import { tmpdir } from "node:os";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import type { IDriver } from "./IDriver.ts";
+import type { ProviderCatalog } from "./ProviderCatalog.ts";
+import { ProviderNotInstalledError } from "./ProviderNotInstalledError.ts";
+
+type DriverCtor = new () => IDriver;
+type DriverModule = Record<string, DriverCtor>;
+type TypeScript = {
+  transpileModule: (
+    source: string,
+    options: {
+      compilerOptions: { module: number; target: number };
+      fileName: string;
+    },
+  ) => { outputText: string };
+  ModuleKind: { ESNext: number };
+  ScriptTarget: { ES2022: number };
+};
+
+const require = createRequire(import.meta.url);
+const virtual = new Map<string, string>();
+const virtualBySource = new Map<string, string>();
+let typeScriptHook = false;
+let compiling = false;
+let nextVirtual = 0;
+
+const installTypeScriptHook = (): void => {
+  if (typeScriptHook) return;
+  const typescript = require("typescript") as TypeScript;
+  /* v8 ignore start */
+  registerHooks({
+    resolve: (specifier, context, nextResolve) => {
+      const parentURL = context.parentURL ? virtual.get(context.parentURL) ?? context.parentURL : undefined;
+      const resolved = nextResolve(specifier, parentURL ? { ...context, parentURL } : context);
+      /* v8 ignore next */
+      if (!compiling || !resolved.url.endsWith(".ts")) return resolved;
+      const existing = virtualBySource.get(resolved.url);
+      /* v8 ignore next */
+      if (existing) return { url: existing, shortCircuit: true };
+      const url = pathToFileURL(`${tmpdir()}/datasources-plugin-${nextVirtual++}.mjs`).href;
+      virtual.set(url, resolved.url);
+      virtualBySource.set(resolved.url, url);
+      return { url, shortCircuit: true };
+    },
+    load: (url, context, nextLoad) => {
+      const original = virtual.get(url) ?? (compiling && url.endsWith(".ts") ? url : undefined);
+      /* v8 ignore next */
+      if (!original) return nextLoad(url, context);
+      const filename = fileURLToPath(original);
+      const source = typescript.transpileModule(readFileSync(filename, "utf8"), {
+        compilerOptions: {
+          module: typescript.ModuleKind.ESNext,
+          target: typescript.ScriptTarget.ES2022,
+        },
+        fileName: filename,
+      }).outputText;
+      return { format: "module", source, shortCircuit: true };
+    },
+  });
+  /* v8 ignore stop */
+  typeScriptHook = true;
+};
+
+const instantiate = (catalog: ProviderCatalog): IDriver => {
+  compiling = true;
+  try {
+    return instantiateLoaded(catalog);
+  } finally {
+    compiling = false;
+  }
+};
+
+const instantiateLoaded = (catalog: ProviderCatalog): IDriver => {
+  const loaded = require(catalog.location) as DriverModule;
+  const Type = loaded[catalog.module];
+  if (typeof Type !== "function") throw new ProviderNotInstalledError(catalog.name);
+  return new Type();
+};
+
+export class DriverLoader {
+  static load = (catalog: ProviderCatalog): IDriver => {
+    try {
+      return instantiate(catalog);
+    } catch (error) {
+      if (error instanceof ProviderNotInstalledError) throw error;
+      try {
+        installTypeScriptHook();
+        return instantiate(catalog);
+      } catch {
+        throw new ProviderNotInstalledError(catalog.name);
+      }
+    }
+  };
+}

package/src/Enrichment.ts

@@ -0,0 +1,15 @@
+import type { EnrichmentPropertyType } from "./EnrichmentPropertyType.ts";
+
+export type Association = {
+  parent: string;
+  related: string;
+};
+
+export type Enrichment = {
+  destinationProperty: string;
+  sourceProperty: string;
+  relatedKey: string;
+  relatedProperty?: string;
+  type?: EnrichmentPropertyType;
+  association?: Association;
+};

package/src/EnrichmentPropertyType.ts

@@ -0,0 +1,9 @@
+export const EnrichmentPropertyType = {
+  Object: "object",
+  List: "list",
+  Dictionary: "dictionary",
+  Custom: "custom",
+} as const;
+
+export type EnrichmentPropertyType =
+  (typeof EnrichmentPropertyType)[keyof typeof EnrichmentPropertyType];

package/src/ExpectConsoleMiddleware.test.ts

@@ -0,0 +1,79 @@
+import { describe, expect, it } from "vitest";
+import { CommandMiddlewareHost } from "./CommandMiddlewareHost.ts";
+import { ExpectConsoleMiddleware, consoleSignature } from "./ExpectConsoleMiddleware.ts";
+
+const now = () => new Date("2026-08-28T01:54:12.101Z");
+
+describe("ExpectConsoleMiddleware", () => {
+  it("matches the transcript and drops the finish duration", async () => {
+    const middleware = new ExpectConsoleMiddleware(
+      [
+        "[2026-08-28T01:54:12.101Z]-[datasource][Start]-[SELECT 1]",
+        "[2026-08-28T01:54:12.101Z]-[datasource][Request]-[{id: 1}]",
+        "[2026-08-28T01:54:12.101Z]-[datasource][Finish]-[SELECT 1]",
+        "[2026-08-28T01:54:12.101Z]-[datasource][AfterCommand]-[{id: 1}]",
+      ],
+      now,
+    );
+    const host = new CommandMiddlewareHost();
+    host.addMiddleware(middleware);
+    await host.run("SELECT 1", [{ name: "id", value: 1 }], async () => ({
+      value: 1,
+      rows: [{ id: 1 }],
+    }));
+    middleware.complete();
+    expect(consoleSignature("[2026-08-28T01:54:12.101Z]-[datasource][Finish]-[SELECT 1] 2ms")).toBe(
+      "[2026-08-28T01:54:12.101Z]-[datasource][Finish]-[SELECT 1]",
+    );
+    expect(consoleSignature("[2026-08-28T01:54:12.101Z]-[datasource][Start]-[SELECT 1]")).toBe(
+      "[2026-08-28T01:54:12.101Z]-[datasource][Start]-[SELECT 1]",
+    );
+    expect(consoleSignature("[2026-08-28T01:54:12.101Z]-[datasource][Finish]-[SELECT 1] 3μs")).toBe(
+      "[2026-08-28T01:54:12.101Z]-[datasource][Finish]-[SELECT 1]",
+    );
+  });
+
+  it("applies a custom line check", async () => {
+    const normalize = (line: string) => consoleSignature(line).replaceAll("2026-08-28T01:54:12.101Z", "<date>");
+    const middleware = new ExpectConsoleMiddleware(
+      [
+        "[<date>]-[datasource][Start]-[SELECT 1]",
+        "[<date>]-[datasource][Request]-[{id: 1}]",
+        "[<date>]-[datasource][Finish]-[SELECT 1]",
+        "[<date>]-[datasource][AfterCommand]-[{id: 1}]",
+      ],
+      now,
+      normalize,
+    );
+    const host = new CommandMiddlewareHost();
+    host.addMiddleware(middleware);
+    await host.run("SELECT 1", [{ name: "id", value: 1 }], async () => ({
+      value: 1,
+      rows: [{ id: 1 }],
+    }));
+    middleware.complete();
+  });
+
+  it("rejects a different line and a short transcript", async () => {
+    const host = new CommandMiddlewareHost();
+    const mismatch = new ExpectConsoleMiddleware(["[nope]"], now);
+    host.addMiddleware(mismatch);
+    await expect(
+      host.run("SELECT 1", [{ name: "id", value: 1 }], async () => ({
+        value: 1,
+        rows: [{ id: 1 }],
+      })),
+    ).rejects.toThrow(/console mismatch at 0/);
+    expect(() => new ExpectConsoleMiddleware(["[missing]"], now).complete()).toThrow(
+      /actual:   <missing>/,
+    );
+    const extraHost = new CommandMiddlewareHost();
+    extraHost.addMiddleware(new ExpectConsoleMiddleware(
+      ["[2026-08-28T01:54:12.101Z]-[datasource][Start]-[SELECT 1]"],
+      now,
+    ));
+    await expect(
+      extraHost.run("SELECT 1", undefined, async () => ({ value: null, rows: [] })),
+    ).rejects.toThrow(/<missing>/);
+  });
+});

package/src/ExpectConsoleMiddleware.ts

@@ -0,0 +1,47 @@
+import { ConsoleCommandMiddleware } from "./ConsoleCommandMiddleware.ts";
+import type { ICommandMiddleware } from "./ICommandMiddleware.ts";
+import type { Parameter } from "./Parameter.ts";
+import type { Row } from "./Row.ts";
+
+export const consoleSignature = (line: string): string => {
+  const duration = line.lastIndexOf("] ");
+  return duration >= 0 && (line.endsWith("ms") || line.endsWith("μs"))
+    ? line.slice(0, duration + 1)
+    : line;
+};
+
+export class ExpectConsoleMiddleware implements ICommandMiddleware {
+  private readonly inner: ConsoleCommandMiddleware;
+  private index = 0;
+
+  constructor(
+    private readonly expected: readonly string[],
+    now: () => Date,
+    private readonly normalize: (line: string) => string = consoleSignature,
+  ) {
+    this.inner = new ConsoleCommandMiddleware((line) => this.check(line), now, { isVerbose: "true" });
+  }
+
+  beforeCommand = (text: string, params?: ReadonlyArray<Parameter>) =>
+    this.inner.beforeCommand(text, params);
+
+  afterCommand = (
+    text: string,
+    params: ReadonlyArray<Parameter> | undefined,
+    results: ReadonlyArray<Row>,
+    elapsedMs: number,
+    error?: Error,
+  ) => this.inner.afterCommand(text, params, results, elapsedMs, error);
+
+  complete = (): void => {
+    if (this.index !== this.expected.length)
+      throw new Error(`console mismatch at ${this.index}\nexpected: ${this.expected[this.index]}\nactual:   <missing>`);
+  };
+
+  private check = (line: string): void => {
+    const actual = this.normalize(line);
+    if (this.index >= this.expected.length || actual !== this.expected[this.index])
+      throw new Error(`console mismatch at ${this.index}\nexpected: ${this.index < this.expected.length ? this.expected[this.index] : "<missing>"}\nactual:   ${actual}`);
+    this.index++;
+  };
+}