@deterministic-code/datasources 0.1.0 → 0.1.1

package/src/RepositoryFactory.test.ts

@@ -0,0 +1,94 @@
+import { describe, expect, it } from "vitest";
+import type { IReadonlyRepository } from "./IReadonlyRepository.ts";
+import { MockConnection } from "./mocks/mock-connection.ts";
+import { MockRepository } from "./mocks/mock-repository.ts";
+import { RepositoryFactory } from "./RepositoryFactory.ts";
+import { RepositoryNotRegisteredError } from "./RepositoryNotRegisteredError.ts";
+
+class Item {}
+
+const emptyReadonly = (): IReadonlyRepository<Item> => ({
+  type: Item,
+  readSingle: async () => undefined,
+  async *read() {},
+});
+
+describe("RepositoryFactory", () => {
+  it("registers and creates", () => {
+    const factory = new RepositoryFactory();
+    const repo = new MockRepository<Item>(new MockConnection(), Item);
+    factory.register(repo);
+    const created = factory.create(Item);
+
+    expect(created).toBe(repo);
+    expect(factory.asReadonly.create(Item)).toBe(repo);
+  });
+
+  it("readonly registration is not crud", () => {
+    const factory = new RepositoryFactory();
+    const repo = emptyReadonly();
+    factory.asReadonly.register(repo);
+
+    expect(factory.asReadonly.create(Item)).toBe(repo);
+    expect(() => factory.create(Item)).toThrow(RepositoryNotRegisteredError);
+    try {
+      factory.create(Item);
+    } catch (error) {
+      expect(error).toBeInstanceOf(RepositoryNotRegisteredError);
+      expect((error as RepositoryNotRegisteredError).entityTypeName).toBe("Item");
+      expect((error as Error).message).toContain("Item");
+    }
+  });
+
+  it("registers and creates by name", () => {
+    const factory = new RepositoryFactory();
+    const connection = new MockConnection();
+    const crud = new MockRepository<Item>(connection, Item);
+    const read = emptyReadonly();
+    factory.register("Contact", "contacts", () => crud, () => read);
+
+    expect(factory.create("Contact", connection)).toBe(crud);
+    expect(factory.createReadonly("contacts", connection)).toBe(read);
+    expect(factory.access("contacts", connection).create()).toBe(crud);
+    expect(factory.access("Contact", connection).createReadonly()).toBe(read);
+  });
+
+  it("binds register on construct", () => {
+    RepositoryFactory.resetBinders();
+    const connection = new MockConnection();
+    const crud = new MockRepository<Item>(connection, Item);
+    const read = emptyReadonly();
+    RepositoryFactory.bind((factory) =>
+      factory.register("Contact", "contacts", () => crud, () => read),
+    );
+    try {
+      const factory = new RepositoryFactory();
+      expect(factory.create("contacts", connection)).toBe(crud);
+    } finally {
+      RepositoryFactory.resetBinders();
+    }
+  });
+
+  it("binds register on access", () => {
+    RepositoryFactory.resetBinders();
+    const connection = new MockConnection();
+    const crud = new MockRepository<Item>(connection, Item);
+    const read = emptyReadonly();
+    RepositoryFactory.bind((factory) =>
+      factory.register("Contact", "contacts", () => crud, () => read),
+    );
+    try {
+      const factory = new RepositoryFactory();
+      expect(factory.access("contacts", connection).create()).toBe(crud);
+    } finally {
+      RepositoryFactory.resetBinders();
+    }
+  });
+
+  it("throws when missing", () => {
+    const factory = new RepositoryFactory();
+    expect(() => factory.create(Item)).toThrow(RepositoryNotRegisteredError);
+    expect(() => factory.create("Contacts", new MockConnection())).toThrow(RepositoryNotRegisteredError);
+    expect(() => factory.createReadonly("Contacts", new MockConnection())).toThrow(RepositoryNotRegisteredError);
+  });
+});

package/src/StatementMappers.test.ts

@@ -0,0 +1,221 @@
+import { describe, expect, it } from "vitest";
+import { DictionaryMapper } from "./mappers/DictionaryMapper.ts";
+import { StatementMappers } from "./StatementMappers.ts";
+import { DefaultStatementTextRenderer } from "./statements/DefaultStatementTextRenderer.ts";
+import { DeleteStatement } from "./statements/DeleteStatement.ts";
+import { ExecuteStoredProcedureStatement } from "./statements/ExecuteStoredProcedureStatement.ts";
+import { Identifier } from "./statements/Identifier.ts";
+import { InsertStatement } from "./statements/InsertStatement.ts";
+import { Join } from "./statements/Join.ts";
+import { Operator } from "./statements/Operator.ts";
+import { OrderBy } from "./statements/OrderBy.ts";
+import { SelectInsertedIdStatement } from "./statements/SelectInsertedIdStatement.ts";
+import { SelectStatement } from "./statements/SelectStatement.ts";
+import { UpdateStatement } from "./statements/UpdateStatement.ts";
+import { Where } from "./statements/Where.ts";
+import { WhereText } from "./statements/WhereText.ts";
+import type { Cell } from "./converters/Cell.ts";
+
+const mapper = (name: string, value: Cell): Cell =>
+  typeof value === "string" ? `${name}:${value.toUpperCase()}` : value;
+
+describe("StatementMappers", () => {
+  it("maps a select", () => {
+    const mappings = new StatementMappers(
+      new DictionaryMapper([
+        ["User", "people"],
+        ["Role", "roles"],
+      ]),
+      new DictionaryMapper([
+        ["Name", "full_name"],
+        ["title", "book.title"],
+        ["id", "user_id"],
+      ]),
+    );
+    const select = new SelectStatement({
+      distinct: true,
+      table: "User",
+      fields: ["Name", "title", "scope.title", "alias.other", '"schema.name".id'],
+      where: new Where(new Operator.Equals("Name", "Bea")),
+      joins: [Join.inner("Role", "User.id", "Role.user_id"), Join.cross("logs")],
+      groupBy: ["Name"],
+      having: new Where(new Operator.Equals("Name", "Bea")),
+      orderBy: [OrderBy.desc("Name")],
+      limit: 5,
+      offset: 1,
+    });
+    const mapped = mappings.apply(select, mapper) as SelectStatement;
+    expect(mapped.table).toBe("people");
+    expect(mapped.fields).toEqual([
+      "full_name",
+      "book.title",
+      "book.title",
+      "alias.other",
+      '"schema.name".user_id',
+    ]);
+    expect(mapped.distinct).toBe(true);
+    expect(mapped.limit).toBe(5);
+    expect(mapped.offset).toBe(1);
+    expect(mapped.groupBy).toEqual(["full_name"]);
+    expect(mapped.orderBy).toEqual([{ column: "full_name", direction: "desc" }]);
+    expect((mapped.joins[0]?.on as Operator.Equals).left).toBeInstanceOf(Identifier);
+    expect(((mapped.joins[0]?.on as Operator.Equals).left as Identifier).name).toBe("people.user_id");
+    expect(mapped.joins[1]).toEqual({ kind: "cross", table: "logs" });
+    expect(DefaultStatementTextRenderer.instance.render(mapped)).toContain("full_name = $full_name");
+    expect(mapped.where?.parameters?.[0]?.value).toBe("Name:BEA");
+    expect(mappings.property("full_name")).toBe("Name");
+    expect(mappings.property("people.full_name")).toBe("Name");
+    expect(mappings.property("other")).toBe("other");
+    expect(mappings.property("people.missing")).toBe("people.missing");
+  });
+
+  it("maps writes", () => {
+    const mappings = new StatementMappers(
+      new DictionaryMapper([
+        ["User", "people"],
+        ["Role", "roles"],
+      ]),
+      new DictionaryMapper([
+        ["Name", "full_name"],
+        ["title", "book.title"],
+        ["id", "user_id"],
+      ]),
+    );
+    const insert = mappings.apply(new InsertStatement("User", [{ name: "Name", value: "Ada" }]), mapper) as InsertStatement;
+    expect(DefaultStatementTextRenderer.instance.render(insert)).toBe("INSERT INTO people (full_name) VALUES ($full_name)");
+    expect(insert.fields[0]?.value).toBe("Ada");
+
+    const update = mappings.apply(
+      new UpdateStatement("User", [{ name: "Name", value: "Ada" }], new Where(new Operator.Equals("Name", "Bea"))),
+      mapper,
+    ) as UpdateStatement;
+    expect(DefaultStatementTextRenderer.instance.render(update)).toBe(
+      "UPDATE people SET full_name = $full_name WHERE full_name = $full_name__where",
+    );
+    expect(update.parameters[0]?.value).toBe("Ada");
+    expect(update.parameters[1]).toEqual({ name: "full_name__where", value: "Name:BEA" });
+
+    const deleted = mappings.apply(
+      new DeleteStatement("User", new Where(new Operator.Equals("Name", "Bea"))),
+      mapper,
+    ) as DeleteStatement;
+    expect(DefaultStatementTextRenderer.instance.render(deleted)).toBe("DELETE FROM people WHERE full_name = $full_name");
+
+    const inserted = mappings.apply(new SelectInsertedIdStatement("User", "id"), mapper) as SelectInsertedIdStatement;
+    expect(inserted.table).toBe("people");
+    expect(inserted.column).toBe("user_id");
+  });
+
+  it("leaves raw and other statements", () => {
+    const mappings = new StatementMappers(
+      new DictionaryMapper([
+        ["User", "people"],
+        ["Role", "roles"],
+      ]),
+      new DictionaryMapper([
+        ["Name", "full_name"],
+        ["title", "book.title"],
+        ["id", "user_id"],
+      ]),
+    );
+    const call = new ExecuteStoredProcedureStatement("save_user", []);
+    expect(mappings.apply(call, mapper)).toBe(call);
+    expect(mappings.apply(undefined, mapper)).toBeUndefined();
+    const text = new WhereText("name = $name");
+    expect(mappings.applyWhere(text, mapper)).toBe(text);
+    const kept = mappings.apply(new DeleteStatement("User", text), mapper) as DeleteStatement;
+    expect(kept.where).toBe(text);
+    expect(DefaultStatementTextRenderer.instance.render(kept)).toBe("DELETE FROM people WHERE name = $name");
+  });
+
+  it("maps a select field alias", () => {
+    const mappings = new StatementMappers(
+      new DictionaryMapper([
+        ["Contact", "contacts_base"],
+        ["Address", "address"],
+      ]),
+      new DictionaryMapper([
+        ["Id", "id"],
+        ["FirstName", "first_name"],
+        ["ContactId", "contact_id"],
+      ]),
+    );
+    const select = new SelectStatement({
+      table: "Contact",
+      fields: ["Contact.Id AS Id", "Contact.FirstName AS FirstName", "Address.Id AS AddressId"],
+      joins: [Join.left("Address", "Contact.Id", "Address.ContactId")],
+    });
+    const mapped = mappings.apply(select, mapper) as SelectStatement;
+    expect(DefaultStatementTextRenderer.instance.render(mapped)).toBe(
+      "SELECT contacts_base.id AS Id, contacts_base.first_name AS FirstName, address.id AS AddressId FROM contacts_base LEFT JOIN address ON contacts_base.id = address.contact_id",
+    );
+  });
+
+  it("maps a contacts select", () => {
+    const mappings = new StatementMappers(
+      new DictionaryMapper([
+        ["Contact", "contacts_base"],
+        ["ContactSource", "contact_source"],
+        ["ContactType", "contact_type"],
+        ["Address", "address"],
+        ["AddressType", "address_type"],
+        ["Phone", "phone"],
+        ["PhoneType", "phone_type"],
+      ]),
+      new DictionaryMapper([
+        ["Id", "id"],
+        ["FirstName", "first_name"],
+        ["LastName", "last_name"],
+        ["Email", "email"],
+        ["Name", "name"],
+        ["Line1", "line1"],
+        ["City", "city"],
+        ["Number", "number"],
+        ["ContactId", "contact_id"],
+        ["ContactSourceId", "contact_source_id"],
+        ["ContactTypeId", "contact_type_id"],
+        ["AddressTypeId", "address_type_id"],
+        ["PhoneTypeId", "phone_type_id"],
+      ]),
+    );
+    const select = new SelectStatement({
+      distinct: true,
+      table: "Contact",
+      fields: [
+        "Contact.FirstName",
+        "Contact.LastName",
+        "Contact.Email",
+        "ContactSource.Name",
+        "Address.Line1",
+        "Address.City",
+        "Phone.Number",
+      ],
+      where: new Where(
+        new Operator.And(
+          new Operator.Equals("Contact.Email", "ada@ex.com"),
+          new Operator.GreaterThan("Address.City", "A"),
+        ),
+      ),
+      joins: [
+        Join.inner("ContactSource", "Contact.ContactSourceId", "ContactSource.Id"),
+        Join.inner("ContactType", "Contact.ContactTypeId", "ContactType.Id"),
+        Join.left("Address", "Contact.Id", "Address.ContactId"),
+        Join.left("AddressType", "Address.AddressTypeId", "AddressType.Id"),
+        Join.left("Phone", "Contact.Id", "Phone.ContactId"),
+        Join.left("PhoneType", "Phone.PhoneTypeId", "PhoneType.Id"),
+      ],
+      groupBy: ["Contact.LastName"],
+      having: new Where(new Operator.Equals("ContactType.Name", "person")),
+      orderBy: [OrderBy.asc("Contact.LastName"), OrderBy.desc("Contact.FirstName")],
+      limit: 20,
+      offset: 1,
+    });
+    const mapped = mappings.apply(select, mapper) as SelectStatement;
+    expect(DefaultStatementTextRenderer.instance.render(mapped)).toBe(
+      "SELECT DISTINCT contacts_base.first_name, contacts_base.last_name, contacts_base.email, contact_source.name, address.line1, address.city, phone.number FROM contacts_base INNER JOIN contact_source ON contacts_base.contact_source_id = contact_source.id INNER JOIN contact_type ON contacts_base.contact_type_id = contact_type.id LEFT JOIN address ON contacts_base.id = address.contact_id LEFT JOIN address_type ON address.address_type_id = address_type.id LEFT JOIN phone ON contacts_base.id = phone.contact_id LEFT JOIN phone_type ON phone.phone_type_id = phone_type.id WHERE contacts_base.email = $contacts_base.email AND address.city > $address.city GROUP BY contacts_base.last_name HAVING contact_type.name = $contact_type.name ORDER BY contacts_base.last_name ASC, contacts_base.first_name DESC LIMIT 20 OFFSET 1",
+    );
+    expect(mapped.where?.parameters[0]?.value).toBe("Contact.Email:ADA@EX.COM");
+    expect(mapped.where?.parameters[1]?.value).toBe("Address.City:A");
+    expect((mapped.having as Where).parameters[0]?.value).toBe("ContactType.Name:PERSON");
+  });
+});

package/src/StreamingReader.test.ts

@@ -0,0 +1,126 @@
+import { describe, expect, it } from "vitest";
+import { splitStatements, statementParameters, statementUsesParameter, statementReader, StreamingReader } from "./index.ts";
+
+describe("splitStatements", () => {
+  it("splits on semicolons outside quotes and comments", () => {
+    expect(splitStatements("")).toEqual([]);
+    expect(splitStatements("SELECT 1")).toEqual(["SELECT 1"]);
+    expect(splitStatements("SELECT 1;")).toEqual(["SELECT 1"]);
+    expect(splitStatements("SELECT 1 AS id; SELECT 2 AS id")).toEqual([
+      "SELECT 1 AS id",
+      "SELECT 2 AS id",
+    ]);
+    expect(splitStatements("SELECT ';' AS id; SELECT 2 AS id")).toEqual([
+      "SELECT ';' AS id",
+      "SELECT 2 AS id",
+    ]);
+    expect(splitStatements('SELECT "a""b" AS id; SELECT `c`')).toEqual([
+      'SELECT "a""b" AS id',
+      "SELECT `c`",
+    ]);
+    expect(splitStatements("SELECT 1; -- tail\nSELECT 2")).toEqual([
+      "SELECT 1",
+      "-- tail\nSELECT 2",
+    ]);
+    expect(splitStatements("SELECT 1; /* ; */ SELECT 2")).toEqual([
+      "SELECT 1",
+      "/* ; */ SELECT 2",
+    ]);
+    const mysql = "CREATE PROCEDURE add_user()\nBEGIN\n  INSERT INTO t VALUES (1);\nEND";
+    expect(splitStatements(mysql)).toEqual([mysql]);
+    const postgres =
+      "CREATE PROCEDURE bulk_create_user(payload jsonb)\nLANGUAGE plpgsql\nAS $$\nBEGIN\n  INSERT INTO t VALUES (1);\nEND;\n$$";
+    expect(splitStatements(postgres)).toEqual([postgres]);
+  });
+
+  it("matches a parameter token at a word boundary", () => {
+    expect(statementUsesParameter("INSERT INTO t (is_enabled) VALUES ($is_enabled__10)", "is_enabled__10")).toBe(true);
+    expect(statementUsesParameter("INSERT INTO t (is_enabled) VALUES ($is_enabled__10)", "is_enabled__1")).toBe(false);
+    expect(statementUsesParameter("$is_enabled__1", "is_enabled__1")).toBe(true);
+    expect(statementParameters("INSERT INTO t (a, b) VALUES ($a__0, $b__0), ($a__1, $b__1)")).toEqual([
+      "a__0",
+      "b__0",
+      "a__1",
+      "b__1",
+    ]);
+  });
+});
+
+describe("StreamingReader", () => {
+  it("reads the current set and advances on nextResult", async () => {
+    const sets = [[{ id: 1 }], [{ id: 2 }]];
+    let set = 0;
+    let row = 0;
+    let reads = 0;
+    let closed = false;
+    const reader = new StreamingReader(
+      async () => {
+        reads += 1;
+        const rows = sets[set] ?? [];
+        if (row >= rows.length) return undefined;
+        const current = rows[row];
+        row += 1;
+        return current;
+      },
+      async () => {
+        set += 1;
+        row = 0;
+        return set < sets.length;
+      },
+      async () => {
+        closed = true;
+      },
+    );
+    expect(reads).toBe(0);
+    expect(await reader.next()).toBe(true);
+    expect(reader.current).toEqual({ id: 1 });
+    expect(await reader.next()).toBe(false);
+    expect(reader.current).toBeUndefined();
+    expect(await reader.nextResult()).toBe(true);
+    expect(reader.current).toBeUndefined();
+    expect(await reader.next()).toBe(true);
+    expect(reader.current).toEqual({ id: 2 });
+    expect(await reader.nextResult()).toBe(false);
+    await reader.dispose();
+    await reader.dispose();
+    expect(closed).toBe(true);
+    const plain = new StreamingReader(
+      async () => undefined,
+      async () => false,
+    );
+    expect(await Array.fromAsync(plain.read())).toEqual([]);
+    await plain.dispose();
+    await plain[Symbol.asyncDispose]();
+    await plain.dispose();
+  });
+
+  it("loads one statement at a time", async () => {
+    const loaded: string[] = [];
+    const reader = statementReader(["SELECT 1 AS id", "SELECT 2 AS id"], async function* (sql) {
+      loaded.push(sql);
+      yield sql.endsWith("1 AS id") ? { id: 1 } : { id: 2 };
+    });
+    expect(loaded).toEqual([]);
+    expect(await reader.next()).toBe(true);
+    expect(reader.current).toEqual({ id: 1 });
+    expect(await reader.next()).toBe(false);
+    expect(loaded).toEqual(["SELECT 1 AS id"]);
+    expect(await reader.nextResult()).toBe(true);
+    expect(await reader.next()).toBe(true);
+    expect(reader.current).toEqual({ id: 2 });
+    expect(await reader.nextResult()).toBe(false);
+    expect(await reader.next()).toBe(false);
+    expect(loaded).toEqual(["SELECT 1 AS id", "SELECT 2 AS id"]);
+    await reader.dispose();
+  });
+
+  it("returns false when a statement reader has no statements", async () => {
+    const reader = statementReader([], async function* () {});
+    expect(await reader.next()).toBe(false);
+    expect(await reader.nextResult()).toBe(false);
+    const blank = statementReader([""], async function* () {
+      yield { id: 1 };
+    });
+    expect(await blank.next()).toBe(false);
+  });
+});

package/src/Transaction.test.ts

@@ -0,0 +1,37 @@
+import { afterAll, afterEach, beforeEach, describe, expect, it } from "vitest";
+import { Datasource, DatasourceFactory, 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("Transaction", () => {
+  it("commit or abort", async () => {
+    const ds = Datasource.default;
+    const connection = await ds.createConnection();
+    await connection.open();
+    const txn = await connection.startTransaction();
+    const saved = true;
+    if (saved) await txn.commit();
+    else await txn.abort();
+    expect(txn.isolation).toBe("readCommitted");
+  });
+});

package/src/UnitOfWorkTransaction.test.ts

@@ -0,0 +1,43 @@
+import { describe, expect, it } from "vitest";
+import { DatasourceError, MockConnection, MockTransaction, UnitOfWorkTransaction } from "./index.ts";
+
+describe("UnitOfWorkTransaction", () => {
+  it("joins a transaction already open on the connection", async () => {
+    const connection = new MockConnection();
+    const txn = connection.transaction as MockTransaction;
+    const outer = new UnitOfWorkTransaction(connection);
+    await outer.begin();
+    const inner = new UnitOfWorkTransaction(connection);
+    await inner.begin();
+    await inner.commit();
+    await outer.commit();
+    expect(connection.startTransactionCalls).toBe(1);
+    expect(txn.commitCalls).toBe(1);
+    expect(txn.abortCalls).toBe(0);
+  });
+
+  it("aborts the outer transaction once when a joined unit aborts", async () => {
+    const connection = new MockConnection();
+    const txn = connection.transaction as MockTransaction;
+    const outer = new UnitOfWorkTransaction(connection);
+    await outer.begin();
+    const inner = new UnitOfWorkTransaction(connection);
+    await inner.begin();
+    await inner.abort();
+    await outer.abort();
+    expect(connection.startTransactionCalls).toBe(1);
+    expect(txn.commitCalls).toBe(0);
+    expect(txn.abortCalls).toBe(1);
+  });
+
+  it("rejects a second begin and a unit that never began", async () => {
+    const failed = new MockConnection();
+    failed.startTransactionError = new Error("nope");
+    const broken = new UnitOfWorkTransaction(failed);
+    await expect(broken.begin()).rejects.toThrow("nope");
+    await expect(broken.begin()).rejects.toThrow(DatasourceError);
+    const idle = new UnitOfWorkTransaction(new MockConnection());
+    await expect(idle.commit()).rejects.toThrow("has not begun");
+    await expect(idle.abort()).rejects.toThrow("has not begun");
+  });
+});