@deterministic-code/datasources 0.0.0-stage → 0.1.1

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

@@ -0,0 +1,86 @@
+import type { IDatasource } from "./IDatasource.ts";
+import type { IDatasourceFactory } from "./IDatasourceFactory.ts";
+import type { IDriver } from "./IDriver.ts";
+import type { DatasourceOptions } from "./DatasourceOptions.ts";
+import { Datasource } from "./Datasource.ts";
+import { DatasourceError } from "./DatasourceError.ts";
+import { DatasourceUrlParser } from "./DatasourceUrlParser.ts";
+import { DriverLoader } from "./DriverLoader.ts";
+import { DotEnv } from "./dotEnv.ts";
+import { ProviderCatalog } from "./ProviderCatalog.ts";
+import { ProviderNotInstalledError } from "./ProviderNotInstalledError.ts";
+
+const factories = new Map<string, IDriver>();
+
+const get = (options: DatasourceOptions | undefined, key: string): string | undefined => {
+  const value = options?.[key];
+  return value && value.trim() ? value.trim() : undefined;
+};
+
+const nonEmpty = (value: string | undefined): string | undefined =>
+  value?.trim() ? value.trim() : undefined;
+
+const merge = (file: DatasourceOptions, env: Record<string, string | undefined>): DatasourceOptions => {
+  const options: DatasourceOptions = { ...file };
+  for (const key of ["INSTALLED_PROVIDERS", "DATASOURCE_URL", "PROVIDER"] as const) {
+    const value = nonEmpty(env[key]);
+    if (value) options[key] = value;
+  }
+  return options;
+};
+
+const split = (value: string | undefined): string[] =>
+  (value ?? "")
+    .split(",")
+    .map((name) => name.trim())
+    .filter((name) => name.length > 0);
+
+function* installed(options: DatasourceOptions): Generator<string> {
+  const names = new Set<string>();
+  for (const name of split(get(options, "INSTALLED_PROVIDERS"))) {
+    if (names.has(name)) continue;
+    names.add(name);
+    yield name;
+  }
+  const url = get(options, "DATASOURCE_URL");
+  if (!url) return;
+  const provider = DatasourceUrlParser.parse(url)?.provider;
+  if (!provider) throw new DatasourceError("DATASOURCE_URL has no provider");
+  if (!names.has(provider)) yield provider;
+}
+
+const registerInstalled = (options: DatasourceOptions): void => {
+  for (const name of installed(options)) {
+    const catalog = ProviderCatalog.default[name];
+    if (!catalog) throw new ProviderNotInstalledError(name);
+    DatasourceFactory.register(name, DriverLoader.load(catalog));
+  }
+};
+
+const resolve = (options?: DatasourceOptions): IDatasource => {
+  const listed = options ?? merge(DotEnv.load(), process.env);
+  if (options === undefined) registerInstalled(listed);
+  const name = get(listed, "PROVIDER")
+    ?? (() => { throw new DatasourceError("Datasource defaults are not specified"); })();
+  const driver = factories.get(name);
+  if (!driver) throw new ProviderNotInstalledError(name);
+  return new Datasource(name, driver, listed);
+};
+
+export class DatasourceFactory implements IDatasourceFactory {
+  static defaults = (options: DatasourceOptions): void => registerInstalled(options);
+
+  static register = (provider: string, driver: IDriver): void => {
+    factories.set(provider, driver);
+  };
+
+  static create = (options?: DatasourceOptions): IDatasource => resolve(options);
+
+  create = (options?: DatasourceOptions): IDatasource => resolve(options);
+
+  static reset = (): void => {
+    factories.clear();
+  };
+
+  static registered = (): string[] => [...factories.keys()].sort();
+}

package/src/DatasourceOptions.ts

@@ -0,0 +1 @@
+export type DatasourceOptions = Record<string, string>;

package/src/DatasourceUrl.ts

@@ -0,0 +1,37 @@
+export class DatasourceUrl {
+  readonly provider: string;
+  readonly username: string | undefined;
+  readonly password: string | undefined;
+  readonly host: string | undefined;
+  readonly port: number | undefined;
+  readonly path: string;
+  readonly schema: string | undefined;
+  readonly options: Readonly<Record<string, string>>;
+
+  constructor(
+    provider: string,
+    username: string | undefined,
+    password: string | undefined,
+    host: string | undefined,
+    port: number | undefined,
+    path: string,
+    schema: string | undefined,
+    options: Readonly<Record<string, string>>,
+  ) {
+    this.provider = provider;
+    this.username = username;
+    this.password = password;
+    this.host = host;
+    this.port = port;
+    this.path = path;
+    this.schema = schema;
+    this.options = options;
+  }
+
+  get datasource(): string | undefined {
+    if (this.path === "") return undefined;
+    if (!this.path.startsWith("/")) return this.path;
+    const rest = this.path.slice(1);
+    return rest === "" ? undefined : rest;
+  }
+}

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

package/src/DatasourceUrlParser.ts

@@ -0,0 +1,188 @@
+import { DatasourceUrl } from "./DatasourceUrl.ts";
+
+const empty: Readonly<Record<string, string>> = {};
+
+const schemeStart = (c: string): boolean =>
+  (c >= "A" && c <= "Z") || (c >= "a" && c <= "z");
+
+const schemeChar = (c: string): boolean =>
+  schemeStart(c) || (c >= "0" && c <= "9") || c === "+" || c === "." || c === "-";
+
+const schemeColon = (url: string): number | undefined => {
+  if (!schemeStart(url.charAt(0))) return undefined;
+  let i = 1;
+  while (i < url.length && schemeChar(url[i])) i++;
+  return i < url.length && url[i] === ":" ? i : undefined;
+};
+
+const hex = (text: string): number | undefined =>
+  /^[0-9a-fA-F]{2}$/.test(text) ? Number.parseInt(text, 16) : undefined;
+
+const decode = (text: string): string | undefined => {
+  const bytes: number[] = [];
+  let decoded = "";
+  const flush = (): void => {
+    if (bytes.length === 0) return;
+    decoded += new TextDecoder().decode(new Uint8Array(bytes));
+    bytes.length = 0;
+  };
+  for (let i = 0; i < text.length; i++) {
+    const c = text[i];
+    if (c !== "%") {
+      const code = text.charCodeAt(i);
+      if (code <= 127) bytes.push(code);
+      else {
+        flush();
+        decoded += c;
+      }
+      continue;
+    }
+    const byte = i + 2 < text.length ? hex(text.slice(i + 1, i + 3)) : undefined;
+    if (byte === undefined) return undefined;
+    bytes.push(byte);
+    i += 2;
+  }
+  flush();
+  return decoded;
+};
+
+const portOf = (text: string): number | undefined =>
+  /^[0-9]+$/.test(text) ? Number.parseInt(text, 10) : undefined;
+
+type Authority = {
+  username: string | undefined;
+  password: string | undefined;
+  host: string | undefined;
+  port: number | undefined;
+  file: string | undefined;
+};
+
+const userOf = (user: string): { username: string | undefined; password: string | undefined } | undefined => {
+  const colon = user.indexOf(":");
+  const username = decode(colon < 0 ? user : user.slice(0, colon));
+  if (username === undefined) return undefined;
+  if (colon < 0) return { username: username === "" ? undefined : username, password: undefined };
+  const password = decode(user.slice(colon + 1));
+  if (password === undefined) return undefined;
+  return { username: username === "" ? undefined : username, password };
+};
+
+const hostLiteral = (hostport: string): { host: string | undefined; port: number | undefined } | undefined => {
+  const end = hostport.indexOf("]");
+  if (end < 1) return undefined;
+  const host = decode(hostport.slice(1, end));
+  if (host === undefined) return undefined;
+  if (end + 1 === hostport.length) return { host, port: undefined };
+  if (hostport[end + 1] !== ":") return undefined;
+  const port = portOf(hostport.slice(end + 2));
+  return port === undefined ? undefined : { host, port };
+};
+
+const authorityOf = (authority: string, hasPath: boolean): Authority | undefined => {
+  if (authority.length === 0)
+    return { username: undefined, password: undefined, host: undefined, port: undefined, file: undefined };
+  const at = authority.lastIndexOf("@");
+  let hostport = authority;
+  let username: string | undefined;
+  let password: string | undefined;
+  if (at >= 0) {
+    const user = userOf(authority.slice(0, at));
+    if (!user) return undefined;
+    username = user.username;
+    password = user.password;
+    hostport = authority.slice(at + 1);
+  }
+  const base = { username, password, file: undefined };
+  if (hostport.length === 0) return { ...base, host: undefined, port: undefined };
+  if (hostport[0] === "[") {
+    const literal = hostLiteral(hostport);
+    return literal ? { ...base, host: literal.host, port: literal.port } : undefined;
+  }
+  const colon = hostport.lastIndexOf(":");
+  if (colon >= 0) {
+    const port = portOf(hostport.slice(colon + 1));
+    if (port !== undefined) {
+      const name = hostport.slice(0, colon);
+      if (name.length === 0) return { ...base, host: undefined, port };
+      const host = decode(name);
+      return host === undefined ? undefined : { ...base, host, port };
+    }
+  }
+  if (!hasPath && at < 0 && hostport[0] !== ":") {
+    const file = decode(hostport);
+    return file === undefined ? undefined : { ...base, host: undefined, port: undefined, file };
+  }
+  const host = decode(hostport);
+  return host === undefined ? undefined : { ...base, host, port: undefined };
+};
+
+const queryOf = (
+  query: string,
+): { schema: string | undefined; options: Readonly<Record<string, string>> } | undefined => {
+  if (query.length === 0) return { schema: undefined, options: empty };
+  const options: Record<string, string> = {};
+  let schema: string | undefined;
+  for (const part of query.split("&")) {
+    if (part.length === 0) continue;
+    const eq = part.indexOf("=");
+    const key = decode(eq < 0 ? part : part.slice(0, eq));
+    const value = decode(eq < 0 ? "" : part.slice(eq + 1));
+    if (key === undefined || value === undefined) return undefined;
+    if (key === "schema") schema = value;
+    else options[key] = value;
+  }
+  return { schema, options };
+};
+
+const partsOf = (
+  rest: string,
+):
+  | {
+      username: string | undefined;
+      password: string | undefined;
+      host: string | undefined;
+      port: number | undefined;
+      path: string;
+    }
+  | undefined => {
+  if (!rest.startsWith("//"))
+    return { username: undefined, password: undefined, host: undefined, port: undefined, path: rest };
+  const body = rest.slice(2);
+  const slash = body.indexOf("/");
+  const authority = authorityOf(slash >= 0 ? body.slice(0, slash) : body, slash >= 0);
+  if (!authority) return undefined;
+  return {
+    username: authority.username,
+    password: authority.password,
+    host: authority.host,
+    port: authority.port,
+    path: authority.file ?? (slash >= 0 ? body.slice(slash) : ""),
+  };
+};
+
+export class DatasourceUrlParser {
+  static parse(url: string | undefined): DatasourceUrl | undefined {
+    if (url === undefined || url.trim() === "") return undefined;
+    const colon = schemeColon(url);
+    if (colon === undefined) return undefined;
+    let rest = url.slice(colon + 1);
+    const hash = rest.indexOf("#");
+    if (hash >= 0) rest = rest.slice(0, hash);
+    const queryAt = rest.indexOf("?");
+    const query = queryAt >= 0 ? rest.slice(queryAt + 1) : "";
+    if (queryAt >= 0) rest = rest.slice(0, queryAt);
+    const parts = partsOf(rest);
+    const parsed = queryOf(query);
+    if (!parts || !parsed) return undefined;
+    return new DatasourceUrl(
+      url.slice(0, colon).toLowerCase(),
+      parts.username,
+      parts.password,
+      parts.host,
+      parts.port,
+      parts.path,
+      parsed.schema,
+      parsed.options,
+    );
+  }
+}

package/src/DefaultCreateEnrichmentStrategy.ts

@@ -0,0 +1,21 @@
+import { CreateEnrichmentStrategy } from "./CreateEnrichmentStrategy.ts";
+import { DatasourceError } from "./DatasourceError.ts";
+import type { Enrichment } from "./Enrichment.ts";
+import type { ICRUDRepository } from "./ICRUDRepository.ts";
+
+export class DefaultCreateEnrichmentStrategy<T> extends CreateEnrichmentStrategy<T> {
+  async createChildren<TChild extends object>(writer: ICRUDRepository<TChild>, enrichment: Enrichment, parent: T): Promise<void> {
+    for (const related of this.payloadOf<TChild, T>(parent, enrichment.destinationProperty, enrichment)) {
+      this.stampCell(related, enrichment.relatedKey, this.getCell(parent, enrichment.sourceProperty));
+      await writer.create(related);
+    }
+  }
+
+  async createLinked<TChild extends object>(writer: ICRUDRepository<TChild>, enrichment: Enrichment, parent: T): Promise<void> {
+    const association = enrichment.association;
+    if (!association) throw new DatasourceError("Missing association");
+    const parentKey = this.requiredKey(parent, enrichment);
+    for (const id of this.relatedIds(parent, enrichment))
+      await writer.create({ [association.parent]: parentKey, [association.related]: id } as TChild);
+  }
+}