@deterministic-code/datasources 0.1.0 → 0.1.1

package/src/mappers/FlatToNestedMapper.test.ts

@@ -0,0 +1,269 @@
+import { describe, expect, it } from "vitest";
+import type { Cells } from "../converters/Cell.ts";
+import type { TypeMap } from "./TypeMap.ts";
+import { FlatToNestedMapper } from "./FlatToNestedMapper.ts";
+
+type Address = { id: number; line1: string; city: string; address_type_name: string };
+type Phone = { id: number; number: string; phone_type_name: string };
+type Contact = {
+  id: number;
+  first_name: string;
+  last_name: string;
+  email: string | null;
+  contact_source_name: string;
+  contact_type_name: string;
+  addresses: Address[];
+  phones: Phone[];
+};
+
+const contactsView: TypeMap<Contact> = {
+  key: "id",
+  fields: {
+    id: "id",
+    first_name: "first_name",
+    last_name: "last_name",
+    email: "email",
+    contact_source_name: "contact_source_name",
+    contact_type_name: "contact_type_name",
+    addresses: {
+      key: "address_id",
+      fields: {
+        id: "address_id",
+        line1: "address_line1",
+        city: "address_city",
+        address_type_name: "address_type_name",
+      },
+    },
+    phones: {
+      key: "phone_id",
+      fields: {
+        id: "phone_id",
+        number: "phone_number",
+        phone_type_name: "phone_type_name",
+      },
+    },
+  },
+};
+
+const adaHome: Cells = {
+  id: 7,
+  first_name: "Ada",
+  last_name: "Lovelace",
+  email: "ada@ex.com",
+  contact_source_name: "Web",
+  contact_type_name: "Person",
+  address_id: 101,
+  address_line1: "10 Downing St",
+  address_city: "London",
+  address_type_name: "Home",
+  phone_id: 201,
+  phone_number: "+44",
+  phone_type_name: "Mobile",
+};
+
+const adaWork: Cells = {
+  ...adaHome,
+  address_id: 102,
+  address_line1: "1 Parliament Sq",
+  address_city: "London",
+};
+
+const noAddress: Cells = {
+  id: 8,
+  first_name: "Charles",
+  last_name: "Babbage",
+  email: null,
+  contact_source_name: "Import",
+  contact_type_name: "Person",
+  address_id: null,
+  address_line1: null,
+  address_city: null,
+  address_type_name: null,
+  phone_id: 202,
+  phone_number: "555",
+  phone_type_name: "Work",
+};
+
+describe("FlatToNestedMapper", () => {
+  const mapper = new FlatToNestedMapper<Contact>(contactsView);
+
+  it("maps join rows to a nested contact", () => {
+    const mapper = new FlatToNestedMapper<Contact>({
+      key: "id",
+      fields: {
+        id: "id",
+        first_name: "first_name",
+        last_name: "last_name",
+        email: "email",
+        contact_source_name: "contact_source_name",
+        contact_type_name: "contact_type_name",
+        addresses: {
+          key: "address_id",
+          fields: {
+            id: "address_id",
+            line1: "address_line1",
+            city: "address_city",
+            address_type_name: "address_type_name",
+          },
+        },
+        phones: {
+          key: "phone_id",
+          fields: {
+            id: "phone_id",
+            number: "phone_number",
+            phone_type_name: "phone_type_name",
+          },
+        },
+      },
+    });
+    const adaHome: Cells = {
+      id: 7,
+      first_name: "Ada",
+      last_name: "Lovelace",
+      email: "ada@ex.com",
+      contact_source_name: "Web",
+      contact_type_name: "Person",
+      address_id: 101,
+      address_line1: "10 Downing St",
+      address_city: "London",
+      address_type_name: "Home",
+      phone_id: 201,
+      phone_number: "+44",
+      phone_type_name: "Mobile",
+    };
+    const adaWork = {
+      ...adaHome,
+      address_id: 102,
+      address_line1: "1 Parliament Sq",
+    };
+    const nested = mapper.map([adaHome, adaWork]);
+    const flat = mapper.reverseMap(nested);
+    expect(nested[0]).toEqual({
+      id: 7,
+      first_name: "Ada",
+      last_name: "Lovelace",
+      email: "ada@ex.com",
+      contact_source_name: "Web",
+      contact_type_name: "Person",
+      addresses: [
+        { id: 101, line1: "10 Downing St", city: "London", address_type_name: "Home" },
+        { id: 102, line1: "1 Parliament Sq", city: "London", address_type_name: "Home" },
+      ],
+      phones: [{ id: 201, number: "+44", phone_type_name: "Mobile" }],
+    });
+    expect(flat).toEqual([adaHome, adaWork]);
+  });
+
+  it("maps one denormalized row into a contact with 0-1 children", () => {
+    expect(mapper.map([adaHome])[0]).toEqual({
+      id: 7,
+      first_name: "Ada",
+      last_name: "Lovelace",
+      email: "ada@ex.com",
+      contact_source_name: "Web",
+      contact_type_name: "Person",
+      addresses: [{ id: 101, line1: "10 Downing St", city: "London", address_type_name: "Home" }],
+      phones: [{ id: 201, number: "+44", phone_type_name: "Mobile" }],
+    });
+    expect(mapper.map([noAddress])[0]?.addresses).toEqual([]);
+    expect(mapper.map([noAddress])[0]?.phones).toEqual([{ id: 202, number: "555", phone_type_name: "Work" }]);
+  });
+
+  it("reverseMaps the first child of each group", () => {
+    expect(mapper.reverseMap(mapper.map([adaHome]))).toEqual([adaHome]);
+    expect(mapper.reverseMap(mapper.map([noAddress]))).toEqual([noAddress]);
+  });
+
+  it("collapses duplicate join rows into one contact with unique children", () => {
+    const [ada, charles] = mapper.map([adaHome, adaWork, adaHome, noAddress]);
+    expect(ada).toEqual({
+      id: 7,
+      first_name: "Ada",
+      last_name: "Lovelace",
+      email: "ada@ex.com",
+      contact_source_name: "Web",
+      contact_type_name: "Person",
+      addresses: [
+        { id: 101, line1: "10 Downing St", city: "London", address_type_name: "Home" },
+        { id: 102, line1: "1 Parliament Sq", city: "London", address_type_name: "Home" },
+      ],
+      phones: [{ id: 201, number: "+44", phone_type_name: "Mobile" }],
+    });
+    expect(charles?.id).toBe(8);
+    expect(charles?.addresses).toEqual([]);
+    expect(charles?.phones).toHaveLength(1);
+  });
+
+  it("collapses already-mapped rows", () => {
+    const [ada] = mapper.map([mapper.map([adaHome])[0]!, mapper.map([adaWork])[0]!]);
+    expect(ada?.addresses).toHaveLength(2);
+    expect(ada?.phones).toHaveLength(1);
+  });
+
+  it("skips rows without a parent key and children without a group key", () => {
+    const orphan = { ...adaHome, id: null };
+    const mapped = mapper.map([adaHome])[0]!;
+    mapped.addresses = [
+      { id: 0, line1: "x", city: "y", address_type_name: "" },
+      { id: 101, line1: "dup", city: "London", address_type_name: "Home" },
+    ];
+    mapped.addresses[0] = {
+      id: undefined as unknown as number,
+      line1: "x",
+      city: "y",
+      address_type_name: "",
+    };
+    const extra = mapper.map([adaWork])[0]!;
+    extra.addresses = [
+      {
+        id: undefined as unknown as number,
+        line1: "ghost",
+        city: "None",
+        address_type_name: "",
+      },
+    ];
+    expect(mapper.map([orphan])).toEqual([]);
+    const [ada] = mapper.map([mapped, extra]);
+    expect(ada?.addresses.map((address) => address.line1)).toEqual(["x", "dup"]);
+  });
+
+  it("falls back to the spec key when it is not a mapped dest field", () => {
+    const names = new FlatToNestedMapper<{ id: number; name: string }>({
+      key: "id",
+      fields: { name: "name" },
+    });
+    expect(names.map([{ id: 1, name: "ada" }])).toEqual([{ id: 1, name: "ada" }]);
+  });
+
+  it("omits nested group fields when compiling a collection", () => {
+    type Row = { id: number; items: { id: number; title: string; kids: { n: number }[] }[] };
+    const nested = new FlatToNestedMapper<Row>({
+      key: "id",
+      fields: {
+        id: "id",
+        items: {
+          key: "item_id",
+          fields: {
+            id: "item_id",
+            title: "item_title",
+            kids: { key: "kid_id", fields: { n: "kid_n" } },
+          },
+        },
+      },
+    });
+    expect(nested.map([{ id: 1, item_id: 2 }])).toEqual([
+      {
+        id: 1,
+        items: [{ id: 2, title: null }],
+      },
+    ]);
+    expect(nested.map([{}])).toEqual([]);
+    expect(nested.reverseMap([{} as Row])).toEqual([
+      {
+        id: null,
+        item_id: null,
+        item_title: null,
+      },
+    ]);
+  });
+});

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