@deterministic-code/datasources 0.1.0 → 0.1.1

package/src/CommandMiddlewareHost.test.ts

@@ -0,0 +1,98 @@
+import { describe, expect, it } from "vitest";
+import { CommandMiddlewareHost } from "./index.ts";
+
+describe("CommandMiddlewareHost", () => {
+  it("base execute methods require a driver", () => {
+    const host = new CommandMiddlewareHost();
+    expect(() => host.execute("SELECT id FROM users")).toThrow("executeNative");
+    expect(() => host.execute("  ")).toThrow("empty command");
+    expect(() => host.executeReader("SELECT id FROM users")).toThrow("executeReaderNative");
+    expect(() => host.executeReader("")).toThrow("empty command");
+  });
+
+  it("rewrites the text and runs afterCommand", async () => {
+    const host = new CommandMiddlewareHost();
+    const seen: string[] = [];
+    let used = "";
+    host.addMiddleware({
+      beforeCommand: (text) => {
+        seen.push(`before:${text}`);
+        return { text: "SELECT 2" };
+      },
+      afterCommand: (text, _params, results, elapsedMs) => {
+        seen.push(`after:${text}:${results.length}:${elapsedMs >= 0}`);
+      },
+    });
+    const result = await host.run("SELECT 1", undefined, async (text) => {
+      used = text;
+      seen.push("op");
+      return { value: 7, rows: [{ id: 1 }] };
+    });
+    expect(result).toBe(7);
+    expect(used).toBe("SELECT 2");
+    expect(seen[0]).toBe("before:SELECT 1");
+    expect(seen[1]).toBe("op");
+    expect(seen[2]?.startsWith("after:SELECT 2:1:true")).toBe(true);
+  });
+
+  it("runs with no middleware", async () => {
+    const host = new CommandMiddlewareHost();
+    expect(await host.run("", undefined, async () => ({ value: "ok", rows: [] }))).toBe(
+      "ok",
+    );
+  });
+
+  it("skips the command when beforeCommand throws", async () => {
+    const host = new CommandMiddlewareHost();
+    let ran = false;
+    host.addMiddleware({
+      beforeCommand: () => {
+        throw new Error("blocked");
+      },
+      afterCommand: () => {
+        ran = true;
+      },
+    });
+    await expect(
+      host.run("select", undefined, async () => {
+        ran = true;
+        return { value: 1, rows: [] };
+      }),
+    ).rejects.toThrow("blocked");
+    expect(ran).toBe(false);
+  });
+
+  it("runs afterCommand with error when the command fails", async () => {
+    const host = new CommandMiddlewareHost();
+    let captured: Error | undefined;
+    host.addMiddleware({
+      beforeCommand: () => undefined,
+      afterCommand: (_q, _p, _r, _e, error) => {
+        captured = error;
+      },
+    });
+    await expect(
+      host.run("select", undefined, async () => {
+        throw new Error("fail-op");
+      }),
+    ).rejects.toThrow("fail-op");
+    expect(captured?.message).toBe("fail-op");
+  });
+
+  it("wraps a non-Error throw for afterCommand", async () => {
+    const host = new CommandMiddlewareHost();
+    let captured: Error | undefined;
+    host.addMiddleware({
+      beforeCommand: () => undefined,
+      afterCommand: (_q, _p, _r, _e, error) => {
+        captured = error;
+      },
+    });
+    await expect(
+      host.run("select", undefined, async () => {
+        throw "string-fail";
+      }),
+    ).rejects.toBe("string-fail");
+    expect(captured?.message).toBe("string-fail");
+  });
+});

package/src/Connection.test.ts

@@ -0,0 +1,34 @@
+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("Connection", () => {
+  it("create from default", async () => {
+    const ds = Datasource.default;
+    const connection = await ds.createConnection();
+    await connection.open();
+    await connection.close();
+    expect(connection.isOpen).toBe(false);
+  });
+});

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/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/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/DatasourceFactory.test.ts

@@ -0,0 +1,159 @@
+import { afterAll, afterEach, beforeEach, describe, expect, it } from "vitest";
+import {
+  CRUDRepository,
+  Datasource,
+  DatasourceError,
+  DatasourceFactory,
+  MockDriver,
+  ProviderNotInstalledError,
+  ReadonlyRepository,
+  untyped,
+} from "./index.ts";
+import type { IConnection } from "./IConnection.ts";
+import { MockCommand } from "./mocks/mock-command.ts";
+import { MockConnection } from "./mocks/mock-connection.ts";
+
+const selectText = async (
+  repo: { read(): AsyncIterable<unknown> },
+  connection: IConnection,
+): Promise<string | undefined> => {
+  if (!(connection instanceof MockConnection)) throw new Error("expected mock connection");
+  const command = new MockCommand(connection);
+  connection.command = command;
+  for await (const item of repo.read()) void item;
+  return command.executeReaderCalls[0]?.text;
+};
+
+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];
+});
+
+afterEach(() => {
+  DatasourceFactory.reset();
+});
+
+afterAll(() => {
+  for (const key of envKeys) {
+    if (savedEnv[key] === undefined) delete process.env[key];
+    else process.env[key] = savedEnv[key];
+  }
+});
+
+describe("DatasourceFactory", () => {
+  it("default from environment", () => {
+    DatasourceFactory.register("sqlite", new MockDriver());
+    process.env.PROVIDER = "sqlite";
+    const ds = Datasource.default;
+    expect(ds.provider).toBe("sqlite");
+  });
+
+  it("skips a repeated installed provider", () => {
+    DatasourceFactory.defaults({ INSTALLED_PROVIDERS: "memory,memory" });
+    expect(DatasourceFactory.registered()).toEqual(["memory"]);
+  });
+
+  it("missing provider throws", () => {
+    expect(() => DatasourceFactory.create({ PROVIDER: "missing" })).toThrow(
+      ProviderNotInstalledError,
+    );
+  });
+
+  it("mock driver builds command and transaction", () => {
+    const driver = new MockDriver();
+    expect(driver.rowTypeConverters).toEqual({});
+    const connection = driver.connection();
+    expect(driver.command(connection)).toBeInstanceOf(MockCommand);
+    expect(driver.transaction(connection).isolation).toBe("readCommitted");
+    expect(driver.transaction(connection, "readCommitted").isolation).toBe(
+      "readCommitted",
+    );
+  });
+});
+
+describe("Datasource registry", () => {
+  it("registers, lists, creates, and resets", () => {
+    expect(DatasourceFactory.registered()).toEqual([]);
+    DatasourceFactory.register("json", new MockDriver());
+    DatasourceFactory.register("memory", new MockDriver());
+    expect(DatasourceFactory.registered()).toEqual(["json", "memory"]);
+    const created = Datasource.create({ PROVIDER: "json", DATASOURCE_URL: "json://x" });
+    expect(created.provider).toBe("json");
+    DatasourceFactory.reset();
+    expect(DatasourceFactory.registered()).toEqual([]);
+    expect(() => Datasource.create({ PROVIDER: "json" })).toThrow(ProviderNotInstalledError);
+  });
+
+  it("requires consumer defaults when provider is omitted", async () => {
+    expect(() => Datasource.create()).toThrow(DatasourceError);
+    DatasourceFactory.register("sqlite", new MockDriver());
+    const ds = Datasource.create({
+      PROVIDER: "sqlite",
+      DATASOURCE_URL: "sqlite:///:memory:",
+    });
+    expect(ds.provider).toBe("sqlite");
+    const connection = await ds.createConnection();
+    expect(connection.isOpen).toBe(false);
+    expect((await ds.createCommand()).connection).toBe(connection);
+    expect(ds.createRepository(untyped())).toBeInstanceOf(CRUDRepository);
+    expect(ds.createReadonlyRepository(untyped()).constructor).toBe(ReadonlyRepository);
+    class Item {
+      id = 0;
+      name = "";
+    }
+    const typed = ds.createRepository(Item, connection);
+    const typedRead = ds.createReadonlyRepository(Item);
+    expect(typed).toBeInstanceOf(CRUDRepository);
+    expect(typed.type).toBe(Item);
+    expect(await selectText(typed, connection)).toBe("SELECT id, name FROM Item");
+    expect(typedRead.constructor).toBe(ReadonlyRepository);
+    expect(typedRead.type).toBe(Item);
+    expect(await selectText(typedRead, connection)).toBe("SELECT id, name FROM Item");
+    const enriched = ds.createReadonlyRepository(Item) as ReadonlyRepository<Item>;
+    expect(enriched).toBeInstanceOf(ReadonlyRepository);
+    typed.addLinked({ destinationProperty: "name", sourceProperty: "id", relatedKey: "id", association: { parent: "id", related: "name" } }, typedRead, typed);
+    const withWrite = ds.createRepository(Item, connection, {
+      write: { useTransaction: false, persist: async () => {} },
+      ids: ["id"],
+    });
+    expect(withWrite).toBeInstanceOf(CRUDRepository);
+    const withCrudIds = ds.createRepository(Item, connection, {
+      ids: undefined as never,
+      entity: "Item",
+    });
+    expect(withCrudIds).toBeInstanceOf(CRUDRepository);
+    const withReadOpts = ds.createRepository(Item, connection, {
+      entity: "items",
+    });
+    expect(withReadOpts).toBeInstanceOf(CRUDRepository);
+    expect(new DatasourceFactory().create({
+      PROVIDER: "sqlite",
+    }).provider).toBe("sqlite");
+    process.env.DATASOURCE_URL = "  ";
+    expect(() => Datasource.create()).toThrow(DatasourceError);
+    process.env.DATASOURCE_URL = "sqlite:///:memory:";
+    expect(() => Datasource.create()).toThrow(ProviderNotInstalledError);
+    DatasourceFactory.defaults({ INSTALLED_PROVIDERS: "json" });
+    expect(DatasourceFactory.registered()).toEqual(["json", "sqlite"]);
+    DatasourceFactory.reset();
+    for (const key of envKeys) delete process.env[key];
+    expect(() => Datasource.create()).toThrow("Datasource defaults are not specified");
+    expect(() => Datasource.default).toThrow("Datasource defaults are not specified");
+    DatasourceFactory.register("sqlite", new MockDriver());
+    DatasourceFactory.register("memory", new MockDriver());
+    process.env.DATASOURCE_URL = "sqlite:///:memory:";
+    expect(() => Datasource.default).toThrow(ProviderNotInstalledError);
+    delete process.env.DATASOURCE_URL;
+    process.env.PROVIDER = "sqlite";
+    expect(Datasource.default.provider).toBe("sqlite");
+    process.env.PROVIDER = "memory";
+    process.env.DATASOURCE_URL = "memory://";
+    expect(Datasource.default.provider).toBe("memory");
+  });
+});

package/src/DatasourceUrlParser.test.ts

@@ -0,0 +1,173 @@
+import { describe, expect, it } from "vitest";
+import { DatasourceUrlParser } from "./index.ts";
+
+describe("DatasourceUrlParser", () => {
+  it("postgres url", () => {
+    const url = DatasourceUrlParser.parse(
+      "postgres://ds:ds@127.0.0.1:5432/datasources?schema=public&sslmode=require",
+    );
+    expect(url?.provider).toBe("postgres");
+    expect(url?.username).toBe("ds");
+    expect(url?.password).toBe("ds");
+    expect(url?.host).toBe("127.0.0.1");
+    expect(url?.port).toBe(5432);
+    expect(url?.path).toBe("/datasources");
+    expect(url?.datasource).toBe("datasources");
+    expect(url?.schema).toBe("public");
+    expect(url?.options.sslmode).toBe("require");
+  });
+
+  it("postgres user without password", () => {
+    const url = DatasourceUrlParser.parse("postgres://ds@127.0.0.1/datasources");
+    expect(url?.username).toBe("ds");
+    expect(url?.password).toBeUndefined();
+    expect(url?.port).toBeUndefined();
+    expect(url?.schema).toBeUndefined();
+    expect(url?.options).toEqual({});
+  });
+
+  it("schema only", () => {
+    const url = DatasourceUrlParser.parse("postgres://127.0.0.1/datasources?schema=public");
+    expect(url?.schema).toBe("public");
+    expect(url?.options).toEqual({});
+  });
+
+  it("options only", () => {
+    const url = DatasourceUrlParser.parse("postgres://127.0.0.1/datasources?sslmode=require");
+    expect(url?.schema).toBeUndefined();
+    expect(url?.options.sslmode).toBe("require");
+  });
+
+  it("repeated option keeps the last value", () => {
+    const url = DatasourceUrlParser.parse(
+      "postgres://127.0.0.1/datasources?sslmode=require&sslmode=disable",
+    );
+    expect(url?.options.sslmode).toBe("disable");
+  });
+
+  it("flag option is empty", () => {
+    const url = DatasourceUrlParser.parse("postgres://127.0.0.1/datasources?readonly");
+    expect(url?.options.readonly).toBe("");
+  });
+
+  it("mysql url", () => {
+    const url = DatasourceUrlParser.parse("mysql://ds:secret@127.0.0.1:3306/app");
+    expect(url?.provider).toBe("mysql");
+    expect(url?.username).toBe("ds");
+    expect(url?.password).toBe("secret");
+    expect(url?.host).toBe("127.0.0.1");
+    expect(url?.port).toBe(3306);
+    expect(url?.datasource).toBe("app");
+  });
+
+  it("mysql host and datasource", () => {
+    const url = DatasourceUrlParser.parse("mysql://db/app");
+    expect(url?.host).toBe("db");
+    expect(url?.datasource).toBe("app");
+    expect(url?.username).toBeUndefined();
+    expect(url?.port).toBeUndefined();
+  });
+
+  it("sqlite relative file", () => {
+    const url = DatasourceUrlParser.parse("sqlite:///app.db");
+    expect(url?.provider).toBe("sqlite");
+    expect(url?.path).toBe("/app.db");
+    expect(url?.datasource).toBe("app.db");
+    expect(url?.host).toBeUndefined();
+  });
+
+  it("sqlite absolute file", () => {
+    const url = DatasourceUrlParser.parse("sqlite:////tmp/app.db");
+    expect(url?.path).toBe("//tmp/app.db");
+    expect(url?.datasource).toBe("/tmp/app.db");
+  });
+
+  it("sqlite memory", () => {
+    const url = DatasourceUrlParser.parse("sqlite:///:memory:");
+    expect(url?.provider).toBe("sqlite");
+    expect(url?.path).toBe("/:memory:");
+    expect(url?.datasource).toBe(":memory:");
+  });
+
+  it("sqlite memory without path", () => {
+    const url = DatasourceUrlParser.parse("sqlite://:memory:");
+    expect(url?.host).toBe(":memory:");
+    expect(url?.datasource).toBeUndefined();
+  });
+
+  it("json file", () => {
+    const url = DatasourceUrlParser.parse("json://contacts.json");
+    expect(url?.provider).toBe("json");
+    expect(url?.datasource).toBe("contacts.json");
+    expect(url?.host).toBeUndefined();
+  });
+
+  it("percent encoded password", () => {
+    const url = DatasourceUrlParser.parse("postgres://ds:p%3Ax@127.0.0.1/datasources");
+    expect(url?.password).toBe("p:x");
+  });
+
+  it("password contains colon", () => {
+    const url = DatasourceUrlParser.parse("postgres://ds:a:b@127.0.0.1/datasources");
+    expect(url?.username).toBe("ds");
+    expect(url?.password).toBe("a:b");
+  });
+
+  it("edges", () => {
+    const upper = DatasourceUrlParser.parse("Postgres://127.0.0.1/db");
+    expect(upper?.provider).toBe("postgres");
+    const opaque = DatasourceUrlParser.parse("a.b+c1:file");
+    expect(opaque?.provider).toBe("a.b+c1");
+    expect(opaque?.datasource).toBe("file");
+    const slash = DatasourceUrlParser.parse("postgres://127.0.0.1/");
+    expect(slash?.path).toBe("/");
+    expect(slash?.datasource).toBeUndefined();
+    const ipv6 = DatasourceUrlParser.parse("postgres://[::1]:5432/db");
+    expect(ipv6?.host).toBe("::1");
+    expect(ipv6?.port).toBe(5432);
+    const hostOnly = DatasourceUrlParser.parse("postgres://[::1]/db");
+    expect(hostOnly?.host).toBe("::1");
+    expect(hostOnly?.port).toBeUndefined();
+    const noHost = DatasourceUrlParser.parse("postgres://ds@/db");
+    expect(noHost?.host).toBeUndefined();
+    const portOnly = DatasourceUrlParser.parse("postgres://:5432/db");
+    expect(portOnly?.host).toBeUndefined();
+    expect(portOnly?.port).toBe(5432);
+    const passwordOnly = DatasourceUrlParser.parse("postgres://:secret@h/db");
+    expect(passwordOnly?.username).toBeUndefined();
+    expect(passwordOnly?.password).toBe("secret");
+    const fragment = DatasourceUrlParser.parse("postgres://h/db#frag");
+    expect(fragment?.datasource).toBe("db");
+    const accented = DatasourceUrlParser.parse("postgres://dé@h/db");
+    expect(accented?.username).toBe("dé");
+    const encoded = DatasourceUrlParser.parse("postgres://d%C3%A9@h/db");
+    expect(encoded?.username).toBe("dé");
+    expect(DatasourceUrlParser.parse(undefined)).toBeUndefined();
+    expect(DatasourceUrlParser.parse("   ")).toBeUndefined();
+    expect(DatasourceUrlParser.parse("9abc:file")).toBeUndefined();
+    expect(DatasourceUrlParser.parse("postgres://ds:a%zz@h/db")).toBeUndefined();
+    expect(DatasourceUrlParser.parse("postgres://[/db")).toBeUndefined();
+    expect(DatasourceUrlParser.parse("postgres://[::1]x/db")).toBeUndefined();
+    expect(DatasourceUrlParser.parse("postgres://[::1]:no/db")).toBeUndefined();
+    expect(DatasourceUrlParser.parse("postgres://[%zz]/db")).toBeUndefined();
+    const emptyUser = DatasourceUrlParser.parse("postgres://@h/db");
+    expect(emptyUser?.username).toBeUndefined();
+    expect(emptyUser?.host).toBe("h");
+    expect(DatasourceUrlParser.parse("postgres://ds:a%@h/db")).toBeUndefined();
+    expect(DatasourceUrlParser.parse("postgres://%zz@h/db")).toBeUndefined();
+    expect(DatasourceUrlParser.parse("postgres://%zz:5432/db")).toBeUndefined();
+    expect(DatasourceUrlParser.parse("json://%zz")).toBeUndefined();
+    expect(DatasourceUrlParser.parse("postgres://%zz/db")).toBeUndefined();
+    expect(DatasourceUrlParser.parse("postgres://h/db?sslmode=%zz")).toBeUndefined();
+    expect(DatasourceUrlParser.parse("postgres://h/db?&sslmode=on")?.options.sslmode).toBe("on");
+  });
+
+  it("not a url", () => {
+    const blank = DatasourceUrlParser.parse("");
+    const text = DatasourceUrlParser.parse("not-a-url");
+    const connectionString = DatasourceUrlParser.parse("Host=db;Port=1");
+    expect(blank).toBeUndefined();
+    expect(text).toBeUndefined();
+    expect(connectionString).toBeUndefined();
+  });
+});