@deterministic-code/datasources 0.0.0-stage → 0.1.1

package/src/ConsoleCommandMiddleware.test.ts

@@ -0,0 +1,149 @@
+import { describe, expect, it, vi } from "vitest";
+import { CommandMiddlewareHost, ConsoleCommandMiddleware, formatElapsed } from "./index.ts";
+
+describe("ConsoleCommandMiddleware", () => {
+  it("formats elapsed time as ms or μs", () => {
+    expect(formatElapsed(2)).toBe("2ms");
+    expect(formatElapsed(1)).toBe("1ms");
+    expect(formatElapsed(0.85)).toBe("850μs");
+    expect(formatElapsed(0.4)).toBe("400μs");
+  });
+
+  it("logs Start and Finish with an injected clock", async () => {
+    const lines: string[] = [];
+    const stamps = [
+      new Date("2026-08-28T01:54:12.101Z"),
+      new Date("2026-08-28T01:54:12.103Z"),
+    ];
+    const middleware = new ConsoleCommandMiddleware(
+      (line) => lines.push(line),
+      () => stamps.shift() ?? new Date("2026-08-28T01:54:12.103Z"),
+    );
+    const host = new CommandMiddlewareHost();
+    host.addMiddleware(middleware);
+    await host.run('SELECT * FROM "widget" ORDER BY "id"', undefined, async () => {
+      await new Promise((resolve) => setTimeout(resolve, 2));
+      return { value: 1, rows: [] };
+    });
+    expect(lines[0]).toBe(
+      '[2026-08-28T01:54:12.101Z]-[datasource][Start]-[SELECT * FROM "widget" ORDER BY "id"]',
+    );
+    expect(lines[1]).toMatch(
+      /^\[2026-08-28T01:54:12.103Z\]-\[datasource\]\[Finish\]-\[SELECT \* FROM "widget" ORDER BY "id"\] \d+(ms|μs)$/,
+    );
+  });
+
+  it("uses console.log and Date by default", async () => {
+    const logged: string[] = [];
+    const spy = vi.spyOn(console, "log").mockImplementation((line) => {
+      logged.push(String(line));
+    });
+    const middleware = new ConsoleCommandMiddleware();
+    middleware.beforeCommand("SELECT 1");
+    middleware.afterCommand("SELECT 1", undefined, [], 2);
+    expect(logged[0]).toMatch(
+      /^\[\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z\]-\[datasource\]\[Start\]-\[SELECT 1\]$/,
+    );
+    expect(logged[1]).toMatch(/\[Finish\]-\[SELECT 1\] 2ms$/);
+    spy.mockRestore();
+  });
+
+  it("trims trailing newlines before logging", async () => {
+    const lines: string[] = [];
+    const host = new CommandMiddlewareHost();
+    host.addMiddleware(new ConsoleCommandMiddleware((line) => lines.push(line)));
+    await host.run("SELECT 1\n", undefined, async () => ({ value: 1, rows: [] }));
+    expect(lines[0].replace(/^\[[^\]]+\]-/, "")).toBe("[datasource][Start]-[SELECT 1]");
+  });
+
+  it("logs Request and AfterCommand when isVerbose", async () => {
+    const lines: string[] = [];
+    const stamps = [
+      new Date("2026-08-28T01:54:12.101Z"),
+      new Date("2026-08-28T01:54:12.102Z"),
+      new Date("2026-08-28T01:54:12.103Z"),
+      new Date("2026-08-28T01:54:12.104Z"),
+    ];
+    const host = new CommandMiddlewareHost();
+    host.addMiddleware(
+      new ConsoleCommandMiddleware(
+        (line) => lines.push(line),
+        () => stamps.shift() ?? new Date("2026-08-28T01:54:12.104Z"),
+        { isVerbose: "true" },
+      ),
+    );
+    await host.run("SELECT 1", [{ name: "id", value: 1 }], async () => ({
+      value: 1,
+      rows: [{ id: 1 }],
+    }));
+    expect(lines).toHaveLength(4);
+    expect(lines[0]).toBe("[2026-08-28T01:54:12.101Z]-[datasource][Start]-[SELECT 1]");
+    expect(lines[1]).toBe("[2026-08-28T01:54:12.102Z]-[datasource][Request]-[{id: 1}]");
+    expect(lines[2]).toMatch(
+      /^\[2026-08-28T01:54:12.103Z\]-\[datasource\]\[Finish\]-\[SELECT 1\] \d+(ms|μs)$/,
+    );
+    expect(lines[3]).toBe("[2026-08-28T01:54:12.104Z]-[datasource][AfterCommand]-[{id: 1}]");
+    lines.length = 0;
+    await host.run("DELETE FROM user", [{ name: "id", value: 2 }], async () => ({
+      value: { result: null, rowsAffected: 1 },
+      rows: [],
+    }));
+    expect(lines[3]).toBe(
+      "[2026-08-28T01:54:12.104Z]-[datasource][AfterCommand]-[{result: null, rowsAffected: 1}]",
+    );
+  });
+
+  it("serializes Date, binary, and bigint in verbose bodies", () => {
+    const lines: string[] = [];
+    const middleware = new ConsoleCommandMiddleware(
+      (line) => lines.push(line),
+      () => new Date("2026-08-28T01:54:12.101Z"),
+      { isVerbose: "1" },
+    );
+    middleware.beforeCommand("SELECT 1");
+    expect(lines[1]).toBe("[2026-08-28T01:54:12.101Z]-[datasource][Request]-[{}]");
+    lines.length = 0;
+    middleware.beforeCommand("SELECT 1", [
+      { name: "when", value: new Date("2026-08-28T01:54:12.000Z") },
+      { name: "blob", value: new Uint8Array([1, 2, 3]) },
+      { name: "n", value: 1n },
+    ]);
+    middleware.afterCommand(
+      "SELECT 1",
+      undefined,
+      [
+        {
+          when: new Date("2026-08-28T01:54:12.000Z"),
+          blob: new Uint8Array([1, 2, 3]),
+          n: 1n,
+        },
+      ],
+      2,
+    );
+    expect(lines[1]).toBe(
+      "[2026-08-28T01:54:12.101Z]-[datasource][Request]-[{when: 2026-08-28T01:54:12.000Z, blob: AQID, n: 1}]",
+    );
+    expect(lines[3]).toBe(
+      "[2026-08-28T01:54:12.101Z]-[datasource][AfterCommand]-[{blob: AQID, n: 1, when: 2026-08-28T01:54:12.000Z}]",
+    );
+    lines.length = 0;
+    middleware.beforeCommand("SELECT 1", [
+      { name: "name", value: "Ada" },
+      { name: "missing", value: null },
+      { name: "on", value: true },
+      { name: "off", value: false },
+    ]);
+    middleware.afterCommand(
+      "SELECT 1",
+      undefined,
+      [{ name: "Ada", missing: null, on: true, off: false }],
+      2,
+    );
+    expect(lines[1]).toBe(
+      "[2026-08-28T01:54:12.101Z]-[datasource][Request]-[{name: Ada, missing: null, on: True, off: False}]",
+    );
+    expect(lines[3]).toBe(
+      "[2026-08-28T01:54:12.101Z]-[datasource][AfterCommand]-[{missing: null, name: Ada, off: False, on: True}]",
+    );
+  });
+});

package/src/ConsoleCommandMiddleware.ts

@@ -0,0 +1,64 @@
+import type { ICommandMiddleware } from "./ICommandMiddleware.ts";
+import type { Parameter } from "./Parameter.ts";
+import type { Row } from "./Row.ts";
+import type { Cell } from "./converters/Cell.ts";
+
+export const formatElapsed = (elapsedMs: number): string =>
+  elapsedMs < 1
+    ? `${Math.round(elapsedMs * 1000)}μs`
+    : `${Math.round(elapsedMs)}ms`;
+
+const cellOf = (value: Cell): string =>
+  value === null
+    ? "null"
+    : value instanceof Date
+      ? value.toISOString()
+      : value instanceof Uint8Array
+        ? Buffer.from(value).toString("base64")
+        : typeof value === "bigint"
+          ? String(value)
+          : typeof value === "boolean"
+            ? value ? "True" : "False"
+            : typeof value === "string"
+              ? value
+              : String(value);
+
+const paramsOf = (params?: ReadonlyArray<Parameter>) =>
+  `{${(params ?? []).map((param) => `${param.name}: ${cellOf(param.value as Cell)}`).join(", ")}}`;
+
+const rowsOf = (rows: ReadonlyArray<Row>) =>
+  rows
+    .map((row) => `{${Object.entries(row).sort(([left], [right]) => left < right ? -1 : 1).map(([key, value]) => `${key}: ${cellOf(value)}`).join(", ")}}`)
+    .join(", ");
+
+export class ConsoleCommandMiddleware implements ICommandMiddleware {
+  constructor(
+    private readonly write: (line: string) => void = (line) => {
+      console.log(line);
+    },
+    private readonly now: () => Date = () => new Date(),
+    private readonly options: Record<string, string> = {},
+  ) {}
+
+  beforeCommand = (text: string, params?: ReadonlyArray<Parameter>): void => {
+    this.write(this.line("Start", text));
+    if (this.verbose()) this.write(this.line("Request", paramsOf(params)));
+  };
+
+  afterCommand = (
+    text: string,
+    _params: ReadonlyArray<Parameter> | undefined,
+    results: ReadonlyArray<Row>,
+    elapsedMs: number,
+  ): void => {
+    const options = { ...this.options, elapsedMs: formatElapsed(elapsedMs) };
+    this.write(`${this.line("Finish", text)} ${options.elapsedMs}`);
+    if (this.verbose()) this.write(this.line("AfterCommand", rowsOf(results)));
+  };
+
+  private verbose = (): boolean =>
+    this.options.isVerbose === "true" || this.options.isVerbose === "1";
+
+  private line = (phase: string, text: string): string =>
+    `[${this.now().toISOString()}]-[datasource][${phase}]-[${text}]`;
+}

package/src/CreateEnrichmentStrategy.ts

@@ -0,0 +1,82 @@
+import type { Enrichment } from "./Enrichment.ts";
+import type { ICRUDRepository } from "./ICRUDRepository.ts";
+import type { Scalar } from "./builders/Scalar.ts";
+import { DatasourceError } from "./DatasourceError.ts";
+
+type Props = Record<string, Scalar | object>;
+
+export abstract class CreateEnrichmentStrategy<T> {
+  abstract createChildren<TChild extends object>(writer: ICRUDRepository<TChild>, enrichment: Enrichment, parent: T): Promise<void>;
+
+  abstract createLinked<TChild extends object>(writer: ICRUDRepository<TChild>, enrichment: Enrichment, parent: T): Promise<void>;
+
+  collectChildren<TChild extends object>(writer: ICRUDRepository<TChild>, enrichment: Enrichment, parent: T): TChild[] {
+    const children = this.payloadOf<TChild, T>(parent, enrichment.destinationProperty, enrichment);
+    if (children.length === 0) return children;
+    const key = this.requiredKey(parent, enrichment);
+    for (const child of children) this.stampCell(child, enrichment.relatedKey, key);
+    return children;
+  }
+
+  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 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/Datasource.test.ts

@@ -0,0 +1,63 @@
+import { afterAll, afterEach, beforeEach, describe, expect, it } from "vitest";
+import { Datasource, DatasourceFactory, MockConnection, 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("Datasource", () => {
+  it("create default from env settings", async () => {
+    const ds = Datasource.default;
+    const command = await ds.createCommand();
+    expect(ds.provider).toBe("sqlite");
+    expect(command.connection).toBe(await ds.createConnection());
+    expect(command.connection.isOpen).toBe(true);
+    class Wide {
+      id = 0;
+      on = false;
+      when = new Date(0);
+      blob = new Uint8Array();
+      tags: string[] = [];
+      name = "";
+    }
+    expect(ds.createRepository(Wide)).toBeTruthy();
+  });
+
+  it("leaves a passed connection closed", async () => {
+    const ds = Datasource.default;
+    const given = new MockConnection();
+    expect((await ds.createCommand(given)).connection).toBe(given);
+    expect(given.isOpen).toBe(false);
+    await ds.createCommand();
+    await expect(ds.createCommand()).rejects.toThrow("Connection is already open");
+  });
+
+  it("applies repository options for crud and readonly", () => {
+    const ds = Datasource.default;
+    class Item {
+      id = 0;
+      name = "";
+    }
+    expect(ds.createRepository(Item, undefined, { entity: "items", ids: ["id"] })).toBeTruthy();
+    expect(ds.createReadonlyRepository(Item, undefined, { entity: "items" })).toBeTruthy();
+    expect(ds.createReadonlyRepository(Item)).toBeTruthy();
+  });
+});

package/src/Datasource.ts

@@ -0,0 +1,152 @@
+import type { Cell } from "./converters/Cell.ts";
+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 { IDatasource } from "./IDatasource.ts";
+import type { IDriver } from "./IDriver.ts";
+import type { IReadonlyRepository } from "./IReadonlyRepository.ts";
+import type { ICRUDRepository } from "./ICRUDRepository.ts";
+import type { DatasourceOptions } from "./DatasourceOptions.ts";
+import type { ReadonlyRepositoryMappingOptions } from "./ReadonlyRepositoryMappingOptions.ts";
+import { DatasourceError } from "./DatasourceError.ts";
+import { CRUDRepository } from "./CRUDRepository.ts";
+import { ReadonlyRepository } from "./ReadonlyRepository.ts";
+import { RepositoryFactory } from "./RepositoryFactory.ts";
+import { RepositoryNotRegisteredError } from "./RepositoryNotRegisteredError.ts";
+import { RowTypeConverter } from "./converters/RowTypeConverter.ts";
+import { createCRUDRepositoryOptions } from "./createCRUDRepositoryOptions.ts";
+import { createReadonlyRepositoryMappingOptions } from "./createReadonlyRepositoryMappingOptions.ts";
+
+export class Datasource implements IDatasource {
+  private connection?: IConnection;
+  readonly repositories = new RepositoryFactory();
+
+  constructor(
+    readonly provider: string,
+    private readonly driver: IDriver,
+    private readonly options?: DatasourceOptions,
+  ) {
+    const self = this;
+    return new Proxy(this, {
+      get(target, prop, receiver) {
+        if (typeof prop !== "string" || Reflect.has(target, prop))
+          return Reflect.get(target, prop, receiver);
+        if (self.repositories.has(prop))
+          return self.repositories.create(prop, self.defaultConnection());
+        throw new RepositoryNotRegisteredError(prop);
+      },
+    });
+  }
+
+  private defaultConnection = (): IConnection =>
+    (this.connection ??= this.driver.connection(this.options));
+
+  createConnection = (): Promise<IConnection> =>
+    Promise.resolve(this.defaultConnection());
+
+  createCommand = async (connection?: IConnection): Promise<ICommand> => {
+    if (!connection) {
+      connection = this.defaultConnection();
+      if (connection.isOpen) throw new DatasourceError("Connection is already open");
+      await connection.open();
+    }
+    return this.driver.command(connection);
+  };
+
+  private applyCrud = <T>(
+    type: Constructable<T>,
+    options?: CRUDRepositoryOptions<T>,
+  ): CRUDRepositoryOptions<T> => {
+    const built = createCRUDRepositoryOptions(type, this.driver.rowTypeConverters);
+    const types = this.driver.rowTypeConverters;
+    const rows = options?.rowConverter ?? RowTypeConverter.from(this.driver.rowTypeConverters, columnsOf(type));
+    return {
+      ...(options ?? built),
+      entity: options?.entity ?? built.entity,
+      rowConverter: rows,
+      rowTypeConverters: types,
+      type,
+    };
+  };
+
+  private applyReadonly = <T>(
+    type: Constructable<T>,
+    options?: ReadonlyRepositoryMappingOptions<T>,
+  ): ReadonlyRepositoryMappingOptions<T> => {
+    const built = createReadonlyRepositoryMappingOptions(type, this.driver.rowTypeConverters);
+    const types = this.driver.rowTypeConverters;
+    const rows = options?.rowConverter ?? RowTypeConverter.from(this.driver.rowTypeConverters, columnsOf(type));
+    return {
+      ...(options ?? built),
+      entity: options?.entity ?? built.entity,
+      rowConverter: rows,
+      rowTypeConverters: types,
+      type,
+    };
+  };
+
+  createRepository<T>(
+    type: Constructable<T>,
+    connection?: IConnection,
+    options?: CRUDRepositoryOptions<T>,
+  ): ICRUDRepository<T>;
+  createRepository(typeName: string, connection?: IConnection): ICRUDRepository;
+  createRepository<T>(
+    typeOrName: Constructable<T> | string,
+    connection?: IConnection,
+    options?: CRUDRepositoryOptions<T>,
+  ): ICRUDRepository<T> {
+    if (typeof typeOrName === "string")
+      return this.repositories.create(typeOrName, connection ?? this.defaultConnection()) as ICRUDRepository<T>;
+    return new CRUDRepository(
+      connection ?? this.defaultConnection(),
+      this.applyCrud(typeOrName, options),
+    );
+  }
+
+  createReadonlyRepository<T>(
+    type: Constructable<T>,
+    connection?: IConnection,
+    options?: ReadonlyRepositoryMappingOptions<T>,
+  ): IReadonlyRepository<T>;
+  createReadonlyRepository(typeName: string, connection?: IConnection): IReadonlyRepository;
+  createReadonlyRepository<T>(
+    typeOrName: Constructable<T> | string,
+    connection?: IConnection,
+    options?: ReadonlyRepositoryMappingOptions<T>,
+  ): IReadonlyRepository<T> {
+    if (typeof typeOrName === "string")
+      return this.repositories.createReadonly(typeOrName, connection ?? this.defaultConnection()) as IReadonlyRepository<T>;
+    return new ReadonlyRepository(
+      connection ?? this.defaultConnection(),
+      this.applyReadonly(typeOrName, options),
+    );
+  }
+
+  static create: (options?: DatasourceOptions) => Datasource;
+
+  static get default(): Datasource {
+    return Datasource.create();
+  }
+}
+
+const columnsOf = <T>(type: Constructable<T>): Record<string, string> => {
+  const instance = new type() as Record<string, Cell | object>;
+  const columns: Record<string, string> = {};
+  for (const [name, value] of Object.entries(instance)) {
+    if (Array.isArray(value)) continue;
+    const canonical = canonicalOf(value);
+    if (canonical) columns[name] = canonical;
+  }
+  return columns;
+};
+
+const canonicalOf = (value: Cell | object): string | undefined =>
+  typeof value === "boolean"
+    ? "bool"
+    : value instanceof Date
+      ? "datetime"
+      : value instanceof Uint8Array
+        ? "binary"
+        : undefined;

package/src/DatasourceError.test.ts

@@ -0,0 +1,10 @@
+import { describe, expect, it } from "vitest";
+import { DatasourceError } from "./index.ts";
+
+describe("DatasourceError", () => {
+  it("wraps a generic datasource error", () => {
+    const error = new DatasourceError("broken");
+    expect(error.name).toBe("DatasourceError");
+    expect(error.message).toBe("broken");
+  });
+});

package/src/DatasourceError.ts

@@ -0,0 +1,6 @@
+export class DatasourceError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "DatasourceError";
+  }
+}