@deterministic-code/datasources 0.0.0-stage → 0.1.0

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.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++;
+  };
+}

package/src/FirstResultReader.ts

@@ -0,0 +1,49 @@
+import type { Cells } from "./converters/Cell.ts";
+import type { IReader } from "./IReader.ts";
+import { readerToAsyncIterable } from "./readerToAsyncIterable.ts";
+
+export class FirstResultReader implements IReader<Cells> {
+  current: Cells | undefined = undefined;
+  private index = -1;
+  private firstSet = true;
+
+  private constructor(
+    private readonly first: readonly Cells[],
+    private readonly live: IReader<Cells>,
+  ) {}
+
+  static async capture(live: IReader<Cells>): Promise<{ value: IReader<Cells>; rows: Cells[] }> {
+    const rows: Cells[] = [];
+    while (await live.next()) if (live.current != null) rows.push(live.current);
+    return { value: new FirstResultReader(rows, live), rows };
+  }
+
+  async next(): Promise<boolean> {
+    if (!this.firstSet) {
+      const moved = await this.live.next();
+      this.current = this.live.current;
+      return moved;
+    }
+    this.index += 1;
+    if (this.index < this.first.length) {
+      this.current = this.first[this.index];
+      return true;
+    }
+    this.current = undefined;
+    return false;
+  }
+
+  async nextResult(): Promise<boolean> {
+    this.firstSet = false;
+    this.current = undefined;
+    return this.live.nextResult();
+  }
+
+  read(): AsyncIterable<Cells> {
+    return readerToAsyncIterable(this);
+  }
+
+  dispose = (): Promise<void> => this.live.dispose();
+
+  [Symbol.asyncDispose] = (): Promise<void> => this.dispose();
+}

package/src/HashsetOptimizedReadonlyEnrichmentStrategy.ts

@@ -0,0 +1,80 @@
+import type { Scalar } from "./builders/Scalar.ts";
+import { Operator, Where } from "./statements/index.ts";
+import type { Enrichment } from "./Enrichment.ts";
+import type { IReadonlyRepository } from "./IReadonlyRepository.ts";
+import type { Row } from "./Row.ts";
+import { DefaultReadonlyEnrichmentStrategy } from "./DefaultReadonlyEnrichmentStrategy.ts";
+
+const hasKey = (value: Scalar | object | undefined): value is Scalar =>
+  value !== undefined && value !== null;
+
+export class HashsetOptimizedReadonlyEnrichmentStrategy<T extends object>
+  extends DefaultReadonlyEnrichmentStrategy<T>
+{
+  protected override async applyObject<TRelated extends object>(
+    via: IReadonlyRepository<TRelated>,
+    enrichment: Enrichment,
+    parents: T[],
+    sources?: (Row | undefined)[],
+  ): Promise<void> {
+    const keys = this.keysOf(parents, sources, enrichment.sourceProperty);
+    if (keys.size === 0) return;
+    const index = new Map<string, TRelated>();
+    for await (const item of via.read(
+      new Where(new Operator.In(enrichment.relatedKey, [...keys.values()])),
+    )) {
+      const by = this.props(item)[enrichment.relatedKey];
+      if (hasKey(by)) index.set(this.keyOf(by), item);
+    }
+    for (const [indexOfParent, parent] of parents.entries()) {
+      const key = this.sourceKey(parent, enrichment.sourceProperty, sources, indexOfParent);
+      if (key === undefined || key === null) continue;
+      const related = index.get(this.keyOf(key));
+      if (!related) continue;
+      Object.assign(parent, {
+        [enrichment.destinationProperty]: enrichment.relatedProperty ? this.props(related)[enrichment.relatedProperty] : related,
+      });
+    }
+  }
+
+  protected override async applyList<TRelated extends object>(
+    via: IReadonlyRepository<TRelated>,
+    enrichment: Enrichment,
+    parents: T[],
+    sources?: (Row | undefined)[],
+  ): Promise<void> {
+    const keys = this.keysOf(parents, sources, enrichment.sourceProperty);
+    if (keys.size === 0) return;
+    const index = new Map<string, TRelated[]>();
+    for await (const item of via.read(
+      new Where(new Operator.In(enrichment.relatedKey, [...keys.values()])),
+    )) {
+      const by = this.props(item)[enrichment.relatedKey];
+      if (hasKey(by)) {
+        const cacheKey = this.keyOf(by);
+        const list = index.get(cacheKey) ?? [];
+        list.push(item);
+        index.set(cacheKey, list);
+      }
+    }
+    for (const [indexOfParent, parent] of parents.entries()) {
+      const key = this.sourceKey(parent, enrichment.sourceProperty, sources, indexOfParent);
+      if (key === undefined || key === null) continue;
+      Object.assign(parent, { [enrichment.destinationProperty]: index.get(this.keyOf(key)) ?? [] });
+    }
+  }
+
+  private keysOf(
+    parents: T[],
+    sources: (Row | undefined)[] | undefined,
+    from: string,
+  ): Map<string, Scalar> {
+    const keys = new Map<string, Scalar>();
+    for (const [index, parent] of parents.entries()) {
+      const key = this.sourceKey(parent, from, sources, index);
+      if (key === undefined || key === null) continue;
+      keys.set(this.keyOf(key), this.scalar(key));
+    }
+    return keys;
+  }
+}

package/src/IBulkWriteStrategy.ts

@@ -0,0 +1,13 @@
+import type { CRUDRepository } from "./CRUDRepository.ts";
+import type { CRUDRepositoryOptions } from "./CRUDRepositoryOptions.ts";
+import type { ICommand } from "./ICommand.ts";
+import type { Response } from "./Response.ts";
+import type { IWhere } from "./statements/IWhere.ts";
+
+export interface IBulkWriteStrategy<T extends object> {
+  repo: CRUDRepository<T>;
+  attach(command: ICommand, options: CRUDRepositoryOptions<T>): void;
+  create(items: T[]): Promise<Response>;
+  update(items: T[], byWhere: IWhere | undefined): Promise<Response>;
+  delete(items: T[], byWhere: IWhere | undefined): Promise<Response>;
+}

package/src/ICRUDRepository.ts

@@ -0,0 +1,13 @@
+import type { Scalar } from "./builders/Scalar.ts";
+import type { Cells } from "./converters/Cell.ts";
+import type { IReadonlyRepository } from "./IReadonlyRepository.ts";
+import type { IWhere } from "./statements/IWhere.ts";
+import type { Response } from "./Response.ts";
+
+export interface ICRUDRepository<T = unknown> extends IReadonlyRepository<T> {
+  readonly ids: readonly string[];
+  create(item: T): Promise<T>;
+  update(item: T, byWhere?: IWhere): Promise<Response>;
+  delete(item: T, byWhere?: IWhere): Promise<Response>;
+  readSingleById(id: Scalar | Cells): Promise<T | undefined>;
+}

package/src/ICRUDRepositoryFactory.ts

@@ -0,0 +1,8 @@
+import type { Constructable } from "./converters/Constructable.ts";
+import type { ICRUDRepository } from "./ICRUDRepository.ts";
+import type { IRepository } from "./IRepository.ts";
+
+export interface ICRUDRepositoryFactory {
+  register(repository: IRepository): void;
+  create<T>(type: Constructable<T>): ICRUDRepository<T>;
+}

package/src/ICommand.ts

@@ -0,0 +1,45 @@
+import type { IStatement } from "./statements/IStatement.ts";
+import { DefaultStatementTextRenderer } from "./statements/DefaultStatementTextRenderer.ts";
+import { Native } from "./statements/Native.ts";
+import type { ICommandMiddleware } from "./ICommandMiddleware.ts";
+import type { IConnection } from "./IConnection.ts";
+import type { Cells } from "./converters/Cell.ts";
+import type { IReader } from "./IReader.ts";
+import type { Response } from "./Response.ts";
+import type { Parameter } from "./Parameter.ts";
+
+export interface ICommand {
+  readonly connection: IConnection;
+  addMiddleware(middleware: ICommandMiddleware): this;
+  executeReader(text: string, parameters?: Parameter[]): Promise<IReader<Cells>>;
+  execute(text: string, parameters?: Parameter[]): Promise<Response>;
+  executeNative(text: Native, parameters?: Parameter[]): Promise<Response>;
+  executeReaderNative(text: Native, parameters?: Parameter[]): Promise<IReader<Cells>>;
+  executeStatement?(statement: IStatement, parameters?: Parameter[]): Promise<Response>;
+  executeReaderStatement?(
+    statement: IStatement,
+    parameters?: Parameter[],
+  ): Promise<IReader<Cells>>;
+}
+
+export const execute = (
+  command: ICommand,
+  statement: IStatement,
+  parameters?: Parameter[],
+): Promise<Response> =>
+  command.executeStatement?.(statement, parameters) ??
+  command.executeNative(
+    new Native(DefaultStatementTextRenderer.instance.render(statement)),
+    parameters,
+  );
+
+export const executeReader = (
+  command: ICommand,
+  statement: IStatement,
+  parameters?: Parameter[],
+): Promise<IReader<Cells>> =>
+  command.executeReaderStatement?.(statement, parameters) ??
+  command.executeReaderNative(
+    new Native(DefaultStatementTextRenderer.instance.render(statement)),
+    parameters,
+  );

package/src/ICommandMiddleware.ts

@@ -0,0 +1,20 @@
+import type { Parameter } from "./Parameter.ts";
+import type { Row } from "./Row.ts";
+
+export interface ICommandMiddleware {
+  beforeCommand(
+    text: string,
+    params?: ReadonlyArray<Parameter>,
+  ):
+    | void
+    | { text: string; params?: ReadonlyArray<Parameter> }
+    | Promise<void | { text: string; params?: ReadonlyArray<Parameter> }>;
+
+  afterCommand(
+    text: string,
+    params: ReadonlyArray<Parameter> | undefined,
+    results: ReadonlyArray<Row>,
+    elapsedMs: number,
+    error?: Error,
+  ): void | Promise<void>;
+}

package/src/IConnection.ts

@@ -0,0 +1,13 @@
+import type { ICommand } from "./ICommand.ts";
+import type { ITransaction } from "./ITransaction.ts";
+import type { IsolationLevel } from "./IsolationLevel.ts";
+
+export interface IConnection {
+  readonly provider: string;
+  readonly isOpen: boolean;
+  createCommand(): ICommand;
+  open(): Promise<void>;
+  close(): Promise<void>;
+  startTransaction(isolation?: IsolationLevel): Promise<ITransaction>;
+  [Symbol.asyncDispose](): Promise<void>;
+}

package/src/IDatasource.ts

@@ -0,0 +1,27 @@
+import type { Constructable } from "./converters/Constructable.ts";
+import type { CRUDRepositoryOptions } from "./CRUDRepositoryOptions.ts";
+import type { ICommand } from "./ICommand.ts";
+import type { IConnection } from "./IConnection.ts";
+import type { IReadonlyRepository } from "./IReadonlyRepository.ts";
+import type { ICRUDRepository } from "./ICRUDRepository.ts";
+import type { ReadonlyRepositoryMappingOptions } from "./ReadonlyRepositoryMappingOptions.ts";
+import type { RepositoryFactory } from "./RepositoryFactory.ts";
+
+export interface IDatasource {
+  readonly provider: string;
+  readonly repositories: RepositoryFactory;
+  createConnection(): Promise<IConnection>;
+  createCommand(connection?: IConnection): Promise<ICommand>;
+  createRepository<T>(
+    type: Constructable<T>,
+    connection?: IConnection,
+    options?: CRUDRepositoryOptions<T>,
+  ): ICRUDRepository<T>;
+  createRepository(typeName: string, connection?: IConnection): ICRUDRepository;
+  createReadonlyRepository<T>(
+    type: Constructable<T>,
+    connection?: IConnection,
+    options?: ReadonlyRepositoryMappingOptions<T>,
+  ): IReadonlyRepository<T>;
+  createReadonlyRepository(typeName: string, connection?: IConnection): IReadonlyRepository;
+}

package/src/IDatasourceFactory.ts

@@ -0,0 +1,6 @@
+import type { DatasourceOptions } from "./DatasourceOptions.ts";
+import type { IDatasource } from "./IDatasource.ts";
+
+export interface IDatasourceFactory {
+  create(options?: DatasourceOptions): IDatasource;
+}