@deterministic-code/datasources 0.0.0-stage → 0.1.1

package/src/mappers/FlatToNestedMapper.ts

@@ -0,0 +1,127 @@
+import type { Cell, Cells } from "../converters/Cell.ts";
+import type { IFlatToNestedMapper } from "./IFlatToNestedMapper.ts";
+import type { TypeMap, TypeMapFields } from "./TypeMap.ts";
+import type { TypeMapGroup } from "./TypeMapGroup.ts";
+
+type GroupPlan = { key: string; fields: Record<string, string>; destKey: string };
+
+const stringFields = (fields: TypeMapFields<object>): Record<string, string> =>
+  Object.fromEntries(
+    Object.entries(fields).filter((entry): entry is [string, string] => typeof entry[1] === "string"),
+  );
+
+const destOf = (fields: Record<string, string>, column: string) =>
+  Object.entries(fields).find(([, source]) => source === column)?.[0] ?? column;
+
+const cellKey = (value: Cell | undefined) => (value == null ? null : String(value));
+
+export class FlatToNestedMapper<T> implements IFlatToNestedMapper<T> {
+  readonly spec: TypeMap<T>;
+  private readonly scalars: Record<string, string>;
+  private readonly groups: Record<string, GroupPlan>;
+  private readonly parentDest: string;
+
+  constructor(spec: TypeMap<T>) {
+    this.spec = spec;
+    this.scalars = {};
+    this.groups = {};
+    for (const [name, value] of Object.entries(spec.fields) as [string, string | TypeMapGroup<object>][]) {
+      if (typeof value === "string") this.scalars[name] = value;
+      else {
+        const fields = stringFields(value.fields);
+        this.groups[name] = { key: value.key, fields, destKey: destOf(fields, value.key) };
+      }
+    }
+    this.parentDest = destOf(this.scalars, spec.key);
+  }
+
+  map = (rows: Iterable<T | Cells>): T[] => this._collapse(rows);
+
+  reverseMap = (values: T[]): Cells[] => [...values].flatMap((value) => this.explode(value));
+
+  private _map = (row: Cells): T => {
+    const dest = {} as Record<string, Cell | Cells[]>;
+    for (const [name, column] of Object.entries(this.scalars)) dest[name] = row[column] ?? null;
+    for (const [name, group] of Object.entries(this.groups)) {
+      const key = row[group.key];
+      dest[name] =
+        key == null
+          ? []
+          : [
+              Object.fromEntries(
+                Object.entries(group.fields).map(([field, column]) => [field, row[column] ?? null]),
+              ),
+            ];
+    }
+    return dest as T;
+  };
+
+  private _collapse = (rows: Iterable<T | Cells>): T[] => {
+    const byParent = new Map<string, T>();
+    const seen = new Set<string>();
+    for (const raw of rows) {
+      const item = this.mapped(raw) ? raw : this._map(raw);
+      const parent = cellKey((item as Record<string, Cell>)[this.parentDest]);
+      if (parent == null) continue;
+      const existing = byParent.get(parent);
+      if (!existing) {
+        byParent.set(parent, item);
+        this.mark(seen, parent, item);
+        continue;
+      }
+      this.merge(existing, item, parent, seen);
+    }
+    return [...byParent.values()];
+  };
+
+  private explode = (value: T): Cells[] => {
+    const record = value as Record<string, Cell | Cells[]>;
+    let rows: Cells[] = [this.scalarsOf(record)];
+    for (const [name, group] of Object.entries(this.groups)) {
+      const children = (record[name] as Cells[] | undefined)?.length
+        ? (record[name] as Cells[])
+        : [undefined];
+      rows = rows.flatMap((row) => children.map((child) => this.withChild(row, group, child)));
+    }
+    return rows;
+  };
+
+  private scalarsOf = (record: Record<string, Cell | Cells[]>): Cells => {
+    const row: Cells = {};
+    for (const [name, column] of Object.entries(this.scalars))
+      row[column] = (record[name] as Cell | undefined) ?? null;
+    return row;
+  };
+
+  private withChild = (row: Cells, group: GroupPlan, child: Cells | undefined): Cells => {
+    const next = { ...row };
+    for (const [field, column] of Object.entries(group.fields)) next[column] = child?.[field] ?? null;
+    return next;
+  };
+
+  private mapped = (row: T | Cells): row is T =>
+    Object.keys(this.groups).every((name) => Array.isArray((row as Record<string, unknown>)[name]));
+
+  private mark = (seen: Set<string>, parent: string, item: T) => {
+    const record = item as Record<string, Cells[]>;
+    for (const [name, group] of Object.entries(this.groups))
+      for (const child of record[name]) {
+        const key = cellKey(child[group.destKey]);
+        if (key != null) seen.add(`${parent}:${name}:${key}`);
+      }
+  };
+
+  private merge = (into: T, from: T, parent: string, seen: Set<string>) => {
+    const dest = into as Record<string, Cells[]>;
+    const source = from as Record<string, Cells[]>;
+    for (const [name, group] of Object.entries(this.groups)) {
+      const children = dest[name];
+      for (const child of source[name]) {
+        const key = cellKey(child[group.destKey]);
+        if (key == null || seen.has(`${parent}:${name}:${key}`)) continue;
+        seen.add(`${parent}:${name}:${key}`);
+        children.push(child);
+      }
+    }
+  };
+}

package/src/mappers/IFlatToNestedMapper.ts

@@ -0,0 +1,7 @@
+import type { Cells } from "../converters/Cell.ts";
+import type { IMapper } from "./IMapper.ts";
+import type { TypeMap } from "./TypeMap.ts";
+
+export interface IFlatToNestedMapper<T> extends IMapper<Iterable<T | Cells>, T[]> {
+  readonly spec: TypeMap<T>;
+}

package/src/mappers/IMapper.ts

@@ -0,0 +1,4 @@
+export interface IMapper<TFrom, TTo> {
+  map(value: TFrom): TTo;
+  reverseMap(value: TTo): TFrom;
+}

package/src/mappers/IdentityMapper.test.ts

@@ -0,0 +1,12 @@
+import { describe, expect, it } from "vitest";
+import { IdentityMapper } from "./IdentityMapper.ts";
+
+describe("IdentityMapper", () => {
+  it("maps and reverses the same value", () => {
+    const mapper = new IdentityMapper<string>();
+    const mapped = mapper.map("contact");
+    const reversed = mapper.reverseMap("contact");
+    expect(mapped).toBe("contact");
+    expect(reversed).toBe("contact");
+  });
+});

package/src/mappers/IdentityMapper.ts

@@ -0,0 +1,6 @@
+import type { IMapper } from "./IMapper.ts";
+
+export class IdentityMapper<T> implements IMapper<T, T> {
+  map = (value: T): T => value;
+  reverseMap = (value: T): T => value;
+}

package/src/mappers/PluralizerMapper.test.ts

@@ -0,0 +1,40 @@
+import { describe, expect, it } from "vitest";
+import { ChangeCasingMapper } from "./ChangeCasingMapper.ts";
+import { PluralizerMapper } from "./PluralizerMapper.ts";
+
+describe("PluralizerMapper", () => {
+  it("pluralizes and lowercases the table name", () => {
+    const mapper = new PluralizerMapper();
+    expect(mapper.map("User")).toBe("Users");
+    expect(mapper.reverseMap("Users")).toBe("User");
+  });
+
+  it("maps contacts", () => {
+    const mapper = new PluralizerMapper();
+    const contact = mapper.map("Contact");
+    const address = mapper.map("Address");
+    expect(contact).toBe("Contacts");
+    expect(address).toBe("Addresses");
+  });
+
+  it("reverse maps contacts", () => {
+    const mapper = new PluralizerMapper();
+    const contact = mapper.reverseMap("Contacts");
+    const address = mapper.reverseMap("Addresses");
+    expect(contact).toBe("Contact");
+    expect(address).toBe("Address");
+  });
+
+  it("lowercases then pluralizes", () => {
+    const casing = new ChangeCasingMapper("pascalCase", "snakeCase");
+    const pluralizer = new PluralizerMapper();
+    const contact = pluralizer.map(casing.map("Contact"));
+    const address = pluralizer.map(casing.map("Address"));
+    const contactName = casing.reverseMap(pluralizer.reverseMap(contact));
+    const addressName = casing.reverseMap(pluralizer.reverseMap(address));
+    expect(contact).toBe("contacts");
+    expect(address).toBe("addresses");
+    expect(contactName).toBe("Contact");
+    expect(addressName).toBe("Address");
+  });
+});

package/src/mappers/PluralizerMapper.ts

@@ -0,0 +1,9 @@
+import { PluralizerConverter } from "../converters/PluralizerConverter.ts";
+import type { IMapper } from "./IMapper.ts";
+
+export class PluralizerMapper implements IMapper<string, string> {
+  private readonly pluralizer = new PluralizerConverter();
+
+  map = (value: string): string => this.pluralizer.convert(value);
+  reverseMap = (value: string): string => this.pluralizer.reverseConvert(value);
+}

package/src/mappers/RowTypeMapper.test.ts

@@ -0,0 +1,12 @@
+import { describe, expect, it } from "vitest";
+import { MetaDataRowTypeConverter } from "../converters/MetaDataRowTypeConverter.ts";
+import { RowTypeMapper } from "./RowTypeMapper.ts";
+
+describe("RowTypeMapper", () => {
+  it("maps a flat row to T and back", () => {
+    const mapper = new RowTypeMapper<{ id: number; name: string }>(new MetaDataRowTypeConverter());
+    const row = { id: 1, name: "ada" };
+    expect(mapper.map(row)).toEqual(row);
+    expect(mapper.reverseMap(row)).toEqual(row);
+  });
+});

package/src/mappers/RowTypeMapper.ts

@@ -0,0 +1,13 @@
+import type { Cells } from "../converters/Cell.ts";
+import { MetaDataRowTypeConverter as RowTypeConverter } from "../converters/MetaDataRowTypeConverter.ts";
+import type { TypeConverter } from "../converters/TypeConverter.ts";
+import { TransformMapper } from "./TransformMapper.ts";
+
+export class RowTypeMapper<T> extends TransformMapper<Cells, T> {
+  constructor(converter: TypeConverter<T, Cells> = new RowTypeConverter()) {
+    super(
+      (row) => converter.convert(row),
+      (item) => converter.reverseConvert(item),
+    );
+  }
+}

package/src/mappers/TransformConverterMapper.test.ts

@@ -0,0 +1,181 @@
+import { describe, expect, it } from "vitest";
+import { TypeConverter } from "../converters/TypeConverter.ts";
+import { TransformConverterMapper } from "./TransformConverterMapper.ts";
+
+class Wrap extends TypeConverter<string, string> {
+  convert = (from: string) => `[${from}]`;
+  reverseConvert = (to: string) => to.replace(/^\[|\]$/g, "");
+}
+
+describe("TransformConverterMapper", () => {
+  it("converts both ways without a filter", () => {
+    const mapper = new TransformConverterMapper(new Wrap());
+    expect(mapper.map("ab")).toBe("[ab]");
+    expect(mapper.reverseMap("[ab]")).toBe("ab");
+  });
+
+  it("converts when the filter is true", () => {
+    const mapper = new TransformConverterMapper(new Wrap(), (s) => s.includes("ab"));
+    expect(mapper.map("ab")).toBe("[ab]");
+    expect(mapper.reverseMap("[ab]")).toBe("ab");
+  });
+
+  it("is identity when the filter is false", () => {
+    const mapper = new TransformConverterMapper(new Wrap(), (s) => s.includes("ab"));
+    expect(mapper.map("a")).toBe("a");
+    expect(mapper.reverseMap("[a]")).toBe("[a]");
+  });
+
+  type Address = { street: string; city: string; country: string };
+  type Contact = { email: string; phone: string; address: Address };
+  type User = { username: string; displayName: string; contact: Contact };
+  type Payload = string[] | User;
+
+  class UserFromCells extends TypeConverter<Payload, Payload> {
+    convert = (from: Payload): Payload => {
+      if (!Array.isArray(from)) return from;
+      const [username, displayName, email, phone, street, city, country] = from;
+      if (from.length !== 7) throw new Error("expected 7 cells");
+      return {
+        username,
+        displayName,
+        contact: { email, phone, address: { street, city, country } },
+      };
+    };
+    reverseConvert = (to: Payload): Payload =>
+      Array.isArray(to)
+        ? to
+        : [
+            to.username,
+            to.displayName,
+            to.contact.email,
+            to.contact.phone,
+            to.contact.address.street,
+            to.contact.address.city,
+            to.contact.address.country,
+          ];
+  }
+
+  it("expands flat cells into a nested user", () => {
+    const cells = [
+      "ada",
+      "Ada Lovelace",
+      "ada@example.com",
+      "+44 20 7946 0958",
+      "10 Downing St",
+      "London",
+      "UK",
+    ];
+    const expected: User = {
+      username: "ada",
+      displayName: "Ada Lovelace",
+      contact: {
+        email: "ada@example.com",
+        phone: "+44 20 7946 0958",
+        address: { street: "10 Downing St", city: "London", country: "UK" },
+      },
+    };
+    const mapper = new TransformConverterMapper(new UserFromCells());
+    expect(mapper.map(cells)).toEqual(expected);
+    expect(mapper.reverseMap(expected)).toEqual(cells);
+  });
+
+  type Account = {
+    id: number;
+    username: string;
+    displayName: string;
+    isEnabled: boolean;
+    created: Date;
+    contact: Contact;
+  };
+  type AccountPayload = string[] | Account;
+
+  class AccountFromCells extends TypeConverter<AccountPayload, AccountPayload> {
+    convert = (from: AccountPayload): AccountPayload => {
+      if (!Array.isArray(from)) return from;
+      const [id, username, displayName, enabled, created, email, phone, street, city] = from;
+      if (from.length !== 10) throw new Error("expected 10 cells");
+      return {
+        id: Number(id),
+        username,
+        displayName,
+        isEnabled: enabled === "1",
+        created: new Date(created),
+        contact: { email, phone, address: { street, city, country: "" } },
+      };
+    };
+    reverseConvert = (to: AccountPayload): AccountPayload =>
+      Array.isArray(to)
+        ? to
+        : [
+            String(to.id),
+            to.username,
+            to.displayName,
+            to.isEnabled ? "1" : "0",
+            to.created.toISOString(),
+            to.contact.email,
+            to.contact.phone,
+            to.contact.address.street,
+            to.contact.address.city,
+            "",
+          ];
+  }
+
+  const isEnabled = (payload: AccountPayload) =>
+    Array.isArray(payload) ? payload[3] === "1" : payload.isEnabled;
+
+  it("converts types and filters rows", () => {
+    const ada = [
+      "7",
+      "ada",
+      "Ada Lovelace",
+      "1",
+      "2020-01-02T03:04:05.000Z",
+      "ada@example.com",
+      "+44",
+      "10 Downing St",
+      "London",
+      "secret-note",
+    ];
+    const guest = [
+      "0",
+      "guest",
+      "Guest",
+      "0",
+      "2020-01-01T00:00:00.000Z",
+      "guest@example.com",
+      "",
+      "1 Road",
+      "Paris",
+      "ignore-me",
+    ];
+    const expected: Account = {
+      id: 7,
+      username: "ada",
+      displayName: "Ada Lovelace",
+      isEnabled: true,
+      created: new Date("2020-01-02T03:04:05.000Z"),
+      contact: {
+        email: "ada@example.com",
+        phone: "+44",
+        address: { street: "10 Downing St", city: "London", country: "" },
+      },
+    };
+    const mapper = new TransformConverterMapper(new AccountFromCells(), isEnabled);
+    expect(mapper.map(ada)).toEqual(expected);
+    expect(mapper.reverseMap(expected)).toEqual([
+      "7",
+      "ada",
+      "Ada Lovelace",
+      "1",
+      "2020-01-02T03:04:05.000Z",
+      "ada@example.com",
+      "+44",
+      "10 Downing St",
+      "London",
+      "",
+    ]);
+    expect(mapper.map(guest)).toBe(guest);
+    expect(mapper.reverseMap(guest)).toBe(guest);
+  });
+});

package/src/mappers/TransformConverterMapper.ts

@@ -0,0 +1,11 @@
+import type { TypeConverter } from "../converters/TypeConverter.ts";
+import { TransformMapper } from "./TransformMapper.ts";
+
+export class TransformConverterMapper<T> extends TransformMapper<T, T> {
+  constructor(converter: TypeConverter<T, T>, filter?: (value: T) => boolean) {
+    super(
+      (value) => (filter?.(value) !== false ? converter.convert(value) : value),
+      (value) => (filter?.(value) !== false ? converter.reverseConvert(value) : value),
+    );
+  }
+}

package/src/mappers/TransformMapper.ts

@@ -0,0 +1,8 @@
+import type { IMapper } from "./IMapper.ts";
+
+export class TransformMapper<TFrom, TTo> implements IMapper<TFrom, TTo> {
+  constructor(
+    readonly map: (value: TFrom) => TTo,
+    readonly reverseMap: (value: TTo) => TFrom,
+  ) {}
+}

package/src/mappers/TypeMap.ts

@@ -0,0 +1,10 @@
+import type { TypeMapGroup } from "./TypeMapGroup.ts";
+
+export type TypeMapFields<T> = {
+  [K in keyof T]?: T[K] extends readonly (infer E)[] ? TypeMapGroup<E> : string;
+};
+
+export type TypeMap<T> = {
+  key: string;
+  fields: TypeMapFields<T>;
+};

package/src/mappers/TypeMapGroup.ts

@@ -0,0 +1,6 @@
+import type { TypeMapFields } from "./TypeMap.ts";
+
+export type TypeMapGroup<E> = {
+  key: string;
+  fields: TypeMapFields<E>;
+};

package/src/mappers/transformMapper.test.ts

@@ -0,0 +1,66 @@
+import { describe, expect, it } from "vitest";
+import { TransformMapper } from "./TransformMapper.ts";
+
+type User = { id: number; name: string };
+type Contacts = { email: string; phone: string };
+type Nested = { user: User; contacts: Contacts };
+type Flat = {
+  userId: number;
+  userName: string;
+  contactEmail: string;
+  contactPhone: string;
+};
+type Contact = { name: string; email: string };
+type ContactRow = { contactName: string; contactEmail: string };
+
+describe("TransformMapper", () => {
+  it("flattens and unflattens user and contacts", () => {
+    const nested: Nested = {
+      user: { id: 1, name: "Ada" },
+      contacts: { email: "ada@x.dev", phone: "555" },
+    };
+    const mapper = new TransformMapper<Nested, Flat>(
+      (n) => ({
+        userId: n.user.id,
+        userName: n.user.name,
+        contactEmail: n.contacts.email,
+        contactPhone: n.contacts.phone,
+      }),
+      (f) => ({
+        user: { id: f.userId, name: f.userName },
+        contacts: { email: f.contactEmail, phone: f.contactPhone },
+      }),
+    );
+    const flat = mapper.map(nested);
+    expect(flat).toEqual({
+      userId: 1,
+      userName: "Ada",
+      contactEmail: "ada@x.dev",
+      contactPhone: "555",
+    });
+    expect(mapper.reverseMap(flat)).toEqual(nested);
+  });
+
+  it("prefixes a contact field", () => {
+    const mapper = new TransformMapper<string, string>(
+      (name) => `contact_${name}`,
+      (name) => name.slice("contact_".length),
+    );
+    const mapped = mapper.map("email");
+    const reversed = mapper.reverseMap(mapped);
+    expect(mapped).toBe("contact_email");
+    expect(reversed).toBe("email");
+  });
+
+  it("maps a contact name and email", () => {
+    const contact: Contact = { name: "Ada", email: "ada@x.dev" };
+    const mapper = new TransformMapper<Contact, ContactRow>(
+      (item) => ({ contactName: item.name, contactEmail: item.email }),
+      (row) => ({ name: row.contactName, email: row.contactEmail }),
+    );
+    const mapped = mapper.map(contact);
+    const reversed = mapper.reverseMap(mapped);
+    expect(mapped).toEqual({ contactName: "Ada", contactEmail: "ada@x.dev" });
+    expect(reversed).toEqual(contact);
+  });
+});

package/src/mocks/MockCommand.test.ts

@@ -0,0 +1,75 @@
+import { describe, expect, it } from "vitest";
+import {
+  execute,
+  executeReader,
+  ExecuteStoredProcedureStatement,
+  Native,
+  MockCommand,
+  MockConnection,
+  MockReader,
+} from "../index.ts";
+
+describe("MockCommand", () => {
+  it("records command execute paths", async () => {
+    const connection = new MockConnection();
+    const command = new MockCommand(connection);
+    command.response = { result: 1, rowsAffected: 2 };
+    command.reader = new MockReader([{ id: 1 }]);
+    expect(await command.executeNative(new Native("insert"), [{ name: "id", value: 1 }])).toEqual({
+      result: 1,
+      rowsAffected: 2,
+    });
+    expect(command.executeCalls).toHaveLength(1);
+    const reader = await command.executeReaderNative(new Native(""));
+    expect(reader).toBe(command.reader);
+
+    command.reader = {
+      current: undefined,
+      next: async () => false,
+      nextResult: async () => false,
+      async *read() {
+        while (await this.next()) {
+          if (this.current !== undefined) yield this.current;
+        }
+      },
+      dispose: async () => {},
+    };
+    expect(await command.executeReaderNative(new Native("plain"))).toBe(command.reader);
+
+    command.executeError = new Error("exec");
+    await expect(command.executeNative(new Native(""))).rejects.toThrow("exec");
+    command.executeReaderError = new Error("read");
+    await expect(command.executeReaderNative(new Native("x"))).rejects.toThrow("read");
+
+    command.executeError = undefined;
+    command.executeReaderError = undefined;
+    const fields = [{ name: "id", value: 1 }];
+    const statement = new ExecuteStoredProcedureStatement("save", fields);
+    await execute(command, statement, fields);
+    expect(command.executeCalls.at(-1)).toEqual({
+      text: "CALL save($id)",
+      parameters: fields,
+    });
+    await executeReader(command, statement, fields);
+    expect(command.executeReaderCalls.at(-1)).toEqual({
+      text: "CALL save($id)",
+      parameters: fields,
+    });
+  });
+
+  it("runs command middleware on mock commands", async () => {
+    const connection = new MockConnection();
+    const command = new MockCommand(connection);
+    const seen: string[] = [];
+    command.addMiddleware({
+      beforeCommand: (text) => {
+        seen.push(`before:${text}`);
+      },
+      afterCommand: (text) => {
+        seen.push(`after:${text}`);
+      },
+    });
+    await command.executeNative(new Native("insert"));
+    expect(seen).toEqual(["before:insert", "after:insert"]);
+  });
+});

package/src/mocks/MockConnection.test.ts

@@ -0,0 +1,34 @@
+import { describe, expect, it } from "vitest";
+import { IsolationLevel, MockCommand, MockConnection, MockTransaction } from "../index.ts";
+
+describe("MockConnection", () => {
+  it("records connection operations and errors", async () => {
+    const connection = new MockConnection();
+    await connection.open();
+    expect(connection.openCalls).toBe(1);
+    expect(connection.isOpen).toBe(true);
+    const txn = await connection.startTransaction(IsolationLevel.ReadUncommitted);
+    expect(txn).toBe(connection.transaction);
+    expect(txn.isolation).toBe(IsolationLevel.ReadUncommitted);
+    await connection.close();
+    expect(connection.isOpen).toBe(false);
+
+    connection.openError = new Error("open-fail");
+    await expect(connection.open()).rejects.toThrow("open-fail");
+    connection.closeError = new Error("close-fail");
+    await expect(connection.close()).rejects.toThrow("close-fail");
+    connection.startTransactionError = new Error("tx-fail");
+    await expect(connection.startTransaction()).rejects.toThrow("tx-fail");
+
+    const customTxn = new MockTransaction(connection);
+    const withTxn = new MockConnection(customTxn);
+    expect(withTxn.transaction).toBe(customTxn);
+    const opened = new MockConnection();
+    await opened.open();
+    await expect(opened.open()).rejects.toThrow("already open");
+  });
+
+  it("creates a command when none is assigned", () => {
+    expect(new MockConnection().createCommand()).toBeInstanceOf(MockCommand);
+  });
+});