@deterministic-code/datasources 0.0.0-stage → 0.1.1

package/src/FirstResultReader.test.ts

@@ -0,0 +1,43 @@
+import { describe, expect, it } from "vitest";
+import { FirstResultReader, StreamingReader } from "./index.ts";
+
+describe("FirstResultReader", () => {
+  it("replays the first set then advances", async () => {
+    const sets = [[{ id: 1 }, { id: 2 }], [{ id: 3 }]];
+    let set = 0;
+    let row = 0;
+    let closed = false;
+    const live = new StreamingReader(
+      async () => (row >= (sets[set]?.length ?? 0) ? undefined : sets[set]![row++]!),
+      async () => {
+        set += 1;
+        row = 0;
+        return set < sets.length;
+      },
+      async () => {
+        closed = true;
+      },
+    );
+    const { value: reader, rows } = await FirstResultReader.capture(live);
+    expect(rows).toEqual([{ id: 1 }, { id: 2 }]);
+    expect(await reader.next()).toBe(true);
+    expect(reader.current).toEqual({ id: 1 });
+    expect(await reader.next()).toBe(true);
+    expect(reader.current).toEqual({ id: 2 });
+    expect(await reader.next()).toBe(false);
+    expect(await reader.nextResult()).toBe(true);
+    expect(await reader.next()).toBe(true);
+    expect(reader.current).toEqual({ id: 3 });
+    await reader.dispose();
+    expect(closed).toBe(true);
+    const empty = await FirstResultReader.capture(
+      new StreamingReader(
+        async () => undefined,
+        async () => false,
+        async () => {},
+      ),
+    );
+    expect(await Array.fromAsync(empty.value.read())).toEqual([]);
+    await empty.value[Symbol.asyncDispose]();
+  });
+});

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

package/src/IDriver.ts

@@ -0,0 +1,24 @@
+import type { ICommand } from "./ICommand.ts";
+import type { IConnection } from "./IConnection.ts";
+import type { ITransaction } from "./ITransaction.ts";
+import type { IsolationLevel } from "./IsolationLevel.ts";
+import type { DatasourceOptions } from "./DatasourceOptions.ts";
+import type { Cell } from "./converters/Cell.ts";
+import type { TypeConverter } from "./converters/TypeConverter.ts";
+import type { Information } from "./Information.ts";
+import type { StatementTextRenderer } from "./statements/StatementTextRenderer.ts";
+
+export const columnType = (name: string): string => name;
+
+export interface IDriver {
+  connection(options?: DatasourceOptions): IConnection;
+  command(connection: IConnection): ICommand;
+  transaction(
+    connection: IConnection,
+    isolation?: IsolationLevel,
+  ): ITransaction;
+  rowTypeConverters: Record<string, TypeConverter<Cell, Cell>>;
+  columnType(name: string): string;
+  statementRenderer?: StatementTextRenderer | null;
+  information?: Information | null;
+}

package/src/IEnriched.ts

@@ -0,0 +1,11 @@
+import type { Enrichment } from "./Enrichment.ts";
+import type { IReadonlyEnrichmentStrategy } from "./IReadonlyEnrichmentStrategy.ts";
+import type { IReadonlyRepository } from "./IReadonlyRepository.ts";
+
+export interface IEnriched<T> {
+  addEnriched<TRelated extends object>(
+    enrichment: Enrichment,
+    via: IReadonlyRepository<TRelated>,
+    strategy?: IReadonlyEnrichmentStrategy<T & object>,
+  ): this;
+}

package/src/IReader.ts

@@ -0,0 +1,8 @@
+export interface IReader<T = unknown> {
+  readonly current: T | undefined;
+  next(): Promise<boolean>;
+  nextResult(): Promise<boolean>;
+  read(): AsyncIterable<T>;
+  dispose(): Promise<void>;
+  [Symbol.asyncDispose](): Promise<void>;
+}

package/src/IReadonlyEnrichmentStrategy.ts

@@ -0,0 +1,19 @@
+import type { Enrichment } from "./Enrichment.ts";
+import type { IReadonlyRepository } from "./IReadonlyRepository.ts";
+import type { Row } from "./Row.ts";
+
+export interface IReadonlyEnrichmentStrategy<T extends object> {
+  apply<TRelated extends object>(
+    via: IReadonlyRepository<TRelated>,
+    enrichment: Enrichment,
+    parents: T[],
+    sources?: (Row | undefined)[],
+  ): Promise<void>;
+  applyLinked<TRelated extends object, TLink extends object>(
+    via: IReadonlyRepository<TRelated>,
+    link: IReadonlyRepository<TLink>,
+    enrichment: Enrichment,
+    parents: T[],
+    sources?: (Row | undefined)[],
+  ): Promise<void>;
+}

package/src/IReadonlyRepository.ts

@@ -0,0 +1,21 @@
+import type { Parameter } from "./Parameter.ts";
+import type { IExecuteStoredProcedureStatement } from "./statements/IExecuteStoredProcedureStatement.ts";
+import type { ISelectStatement } from "./statements/ISelectStatement.ts";
+import type { IRepository } from "./IRepository.ts";
+import type { IWhere } from "./statements/IWhere.ts";
+import type { ReadonlyRepositoryMappingOptions } from "./ReadonlyRepositoryMappingOptions.ts";
+
+export type ReadQuery = ISelectStatement | IWhere | IExecuteStoredProcedureStatement;
+
+export interface IReadonlyRepository<T = unknown> extends IRepository<T> {
+  readSingle(
+    query?: ReadQuery,
+    parameters?: Parameter[],
+    options?: ReadonlyRepositoryMappingOptions<T>,
+  ): Promise<T | undefined>;
+  read(
+    query?: ReadQuery,
+    parameters?: Parameter[],
+    options?: ReadonlyRepositoryMappingOptions<T>,
+  ): AsyncIterable<T>;
+}

package/src/IRepository.ts

@@ -0,0 +1,5 @@
+import type { Constructable } from "./converters/Constructable.ts";
+
+export interface IRepository<T = unknown> {
+  readonly type: Constructable<T>;
+}

package/src/IRepositoryFactory.ts

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

package/src/IRepositoryTree.ts

@@ -0,0 +1,5 @@
+import type { IRepositoryTreeNode } from "./IRepositoryTreeNode.ts";
+
+export interface IRepositoryTree {
+  readonly parent: IRepositoryTreeNode;
+}

package/src/IRepositoryTreeNode.ts

@@ -0,0 +1,8 @@
+import type { Enrichment } from "./Enrichment.ts";
+
+export interface IRepositoryTreeNode {
+  readonly value: object;
+  readonly propertyName: string;
+  readonly parent?: IRepositoryTreeNode;
+  readonly enrichment?: Enrichment;
+}

package/src/ITransaction.ts

@@ -0,0 +1,9 @@
+import type { IConnection } from "./IConnection.ts";
+import type { IsolationLevel } from "./IsolationLevel.ts";
+
+export interface ITransaction {
+  readonly connection: IConnection;
+  readonly isolation: IsolationLevel;
+  commit(): Promise<void>;
+  abort(): Promise<void>;
+}

package/src/IUnitOfWork.ts

@@ -0,0 +1,5 @@
+export interface IUnitOfWork {
+  begin(): Promise<void>;
+  commit(): Promise<void>;
+  abort(): Promise<void>;
+}

package/src/IWriteEnrichmentStrategy.ts

@@ -0,0 +1,8 @@
+import type { IRepositoryTree } from "./IRepositoryTree.ts";
+import type { WriteMode } from "./WriteMode.ts";
+
+export interface IWriteEnrichmentStrategy<T> {
+  readonly useTransaction: boolean;
+  persist(tree: IRepositoryTree, items: T[], mode: WriteMode): Promise<void>;
+  persistBulk?(tree: IRepositoryTree, items: T[], mode: WriteMode): Promise<void>;
+}

package/src/Information.ts

@@ -0,0 +1,5 @@
+export type Information = {
+  descriptions: readonly string[];
+  overrides: readonly string[];
+  changeLogs: readonly string[];
+};

package/src/IsolationLevel.test.ts

@@ -0,0 +1,13 @@
+import { describe, expect, it } from "vitest";
+import { IsolationLevel } from "./index.ts";
+
+describe("IsolationLevel", () => {
+  it("names the ANSI levels", () => {
+    expect(IsolationLevel).toEqual({
+      ReadUncommitted: "readUncommitted",
+      ReadCommitted: "readCommitted",
+      RepeatableRead: "repeatableRead",
+      Serializable: "serializable",
+    });
+  });
+});

package/src/IsolationLevel.ts

@@ -0,0 +1,8 @@
+export const IsolationLevel = {
+  ReadUncommitted: "readUncommitted",
+  ReadCommitted: "readCommitted",
+  RepeatableRead: "repeatableRead",
+  Serializable: "serializable",
+} as const;
+
+export type IsolationLevel = (typeof IsolationLevel)[keyof typeof IsolationLevel];

package/src/LazyWriteEnrichmentStrategy.ts

@@ -0,0 +1,5 @@
+import { DefaultWriteEnrichmentStrategy } from "./DefaultWriteEnrichmentStrategy.ts";
+
+export class LazyWriteEnrichmentStrategy<T> extends DefaultWriteEnrichmentStrategy<T> {
+  protected override skipUnloaded = true;
+}

package/src/NestedToObjectEnrichmentStrategy.ts

@@ -0,0 +1,33 @@
+import type { Cells } from "./converters/Cell.ts";
+import type { Enrichment } from "./Enrichment.ts";
+import type { IReadonlyRepository } from "./IReadonlyRepository.ts";
+import { FlatToNestedMapper } from "./mappers/FlatToNestedMapper.ts";
+import type { TypeMap } from "./mappers/TypeMap.ts";
+import type { Row } from "./Row.ts";
+import { DefaultReadonlyEnrichmentStrategy } from "./DefaultReadonlyEnrichmentStrategy.ts";
+
+export class NestedToObjectEnrichmentStrategy<T extends object>
+  extends DefaultReadonlyEnrichmentStrategy<T>
+{
+  private readonly nested: FlatToNestedMapper<T>;
+
+  constructor(typeMap: TypeMap<T>) {
+    super();
+    this.nested = new FlatToNestedMapper(typeMap);
+  }
+
+  override apply<TRelated extends object>(
+    _via: IReadonlyRepository<TRelated>,
+    _enrichment: Enrichment,
+    parents: T[],
+    sources?: (Row | undefined)[],
+  ): Promise<void> {
+    parents.length = 0;
+    for (const item of this.nested.map(rows(sources))) parents.push(item);
+    return Promise.resolve();
+  }
+}
+
+function* rows(sources?: (Row | undefined)[]): Iterable<Cells> {
+  for (const source of sources ?? []) if (source) yield source;
+}

package/src/Parameter.ts

@@ -0,0 +1,8 @@
+import type { Scalar } from "./builders/Scalar.ts";
+import type { ParameterDirection } from "./ParameterDirection.ts";
+
+export interface Parameter<T = Scalar> {
+  name: string;
+  value?: T;
+  direction?: ParameterDirection;
+}

package/src/ParameterDirection.ts

@@ -0,0 +1,9 @@
+export const ParameterDirection = {
+  Input: "input",
+  Output: "output",
+  InputOutput: "inputOutput",
+  ReturnValue: "returnValue",
+} as const;
+
+export type ParameterDirection =
+  (typeof ParameterDirection)[keyof typeof ParameterDirection];