@deterministic-code/datasources 0.0.0-stage → 0.1.1

package/src/ProviderCatalog.test.ts

@@ -0,0 +1,110 @@
+import { afterAll, afterEach, beforeEach, describe, expect, it } from "vitest";
+import { DriverLoader } from "./DriverLoader.ts";
+import { Datasource, DatasourceError, DatasourceFactory, ProviderCatalog, ProviderNotInstalledError } 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.reset();
+});
+
+afterEach(() => DatasourceFactory.reset());
+
+afterAll(() => {
+  for (const key of envKeys) {
+    if (savedEnv[key] === undefined) delete process.env[key];
+    else process.env[key] = savedEnv[key];
+  }
+});
+
+describe("ProviderCatalog", () => {
+  it("default stores location and module", () => {
+    const sqlite = ProviderCatalog.default.sqlite;
+    expect(sqlite?.location).toBe("@datasources/sqlite");
+    expect(sqlite?.module).toBe("SqliteDriver");
+    expect(ProviderCatalog.default.sqlserver?.module).toBe("SqlServerDriver");
+    expect(ProviderCatalog.default.mongodb?.module).toBe("MongoDbDriver");
+    expect(ProviderCatalog.default.dynamodb?.module).toBe("DynamoDbDriver");
+  });
+
+  it("full constructor stores location and module", () => {
+    const catalog = new ProviderCatalog("acme", "@acme/data", "AcmeDriver");
+    expect(catalog.name).toBe("acme");
+    expect(catalog.location).toBe("@acme/data");
+    expect(catalog.module).toBe("AcmeDriver");
+  });
+
+  it("default lists monorepo providers", () => {
+    expect(Object.keys(ProviderCatalog.default)).toEqual([
+      "json",
+      "memory",
+      "sqlite",
+      "xml",
+      "yaml",
+      "mysql",
+      "sqlserver",
+      "postgres",
+      "oracle",
+      "mongodb",
+      "dynamodb",
+    ]);
+  });
+
+  it("defaults registers installed providers", () => {
+    DatasourceFactory.defaults({
+      INSTALLED_PROVIDERS: "json,memory",
+      DATASOURCE_URL: "memory://",
+    });
+    expect(DatasourceFactory.registered()).toEqual(["json", "memory"]);
+    expect(
+      Datasource.create({ PROVIDER: "memory", DATASOURCE_URL: "memory://" }).provider,
+    ).toBe("memory");
+  });
+
+  it("create does not take installed providers", () => {
+    DatasourceFactory.defaults({ INSTALLED_PROVIDERS: "json,memory" });
+    expect(Datasource.create({ PROVIDER: "json", DATASOURCE_URL: "json://" }).provider).toBe(
+      "json",
+    );
+    expect(DatasourceFactory.registered()).toEqual(["json", "memory"]);
+  });
+
+  it("create reads connection from the environment", () => {
+    process.env.INSTALLED_PROVIDERS = "json,memory";
+    process.env.DATASOURCE_URL = "memory://";
+    process.env.PROVIDER = "memory";
+    expect(Datasource.create().provider).toBe("memory");
+    expect(Datasource.default.provider).toBe("memory");
+    expect(DatasourceFactory.registered()).toEqual(["json", "memory"]);
+  });
+
+  it("missing export throws", () => {
+    expect(() =>
+      DriverLoader.load(new ProviderCatalog("json", "@datasources/json", "MissingDriver")),
+    ).toThrow(ProviderNotInstalledError);
+  });
+
+  it("missing package or unknown name", () => {
+    expect(() => DatasourceFactory.defaults({ INSTALLED_PROVIDERS: "sqlite" })).toThrow(
+      ProviderNotInstalledError,
+    );
+    expect(() => DatasourceFactory.defaults({ INSTALLED_PROVIDERS: "nope" })).toThrow(
+      ProviderNotInstalledError,
+    );
+  });
+
+  it("default overrides env", () => {
+    process.env.INSTALLED_PROVIDERS = "json,memory";
+    process.env.PROVIDER = "json";
+    process.env.DATASOURCE_URL = "json://";
+    expect(Datasource.default.provider).toBe("json");
+  });
+
+  it("url without provider throws", () => {
+    expect(() => DatasourceFactory.defaults({ DATASOURCE_URL: "not-a-url" })).toThrow(
+      new DatasourceError("DATASOURCE_URL has no provider"),
+    );
+  });
+});

package/src/ProviderCatalog.ts

@@ -0,0 +1,21 @@
+export class ProviderCatalog {
+  constructor(
+    readonly name: string,
+    readonly location: string,
+    readonly module: string,
+  ) {}
+
+  static readonly default: Readonly<Record<string, ProviderCatalog>> = {
+    json: new ProviderCatalog("json", "@datasources/json", "JsonDriver"),
+    memory: new ProviderCatalog("memory", "@datasources/memory", "MemoryDriver"),
+    sqlite: new ProviderCatalog("sqlite", "@datasources/sqlite", "SqliteDriver"),
+    xml: new ProviderCatalog("xml", "@datasources/xml", "XmlDriver"),
+    yaml: new ProviderCatalog("yaml", "@datasources/yaml", "YamlDriver"),
+    mysql: new ProviderCatalog("mysql", "@datasources/mysql", "MysqlDriver"),
+    sqlserver: new ProviderCatalog("sqlserver", "@datasources/sqlserver", "SqlServerDriver"),
+    postgres: new ProviderCatalog("postgres", "@datasources/postgres", "PostgresDriver"),
+    oracle: new ProviderCatalog("oracle", "@datasources/oracle", "OracleDriver"),
+    mongodb: new ProviderCatalog("mongodb", "@datasources/mongodb", "MongoDbDriver"),
+    dynamodb: new ProviderCatalog("dynamodb", "@datasources/dynamodb", "DynamoDbDriver"),
+  };
+}

package/src/ProviderNotImplementedError.test.ts

@@ -0,0 +1,11 @@
+import { describe, expect, it } from "vitest";
+import { ProviderNotImplementedError } from "./index.ts";
+
+describe("ProviderNotImplementedError", () => {
+  it("reports an unimplemented provider", () => {
+    const error = new ProviderNotImplementedError("oracle");
+    expect(error.name).toBe("ProviderNotImplementedError");
+    expect(error.provider).toBe("oracle");
+    expect(error.message).toContain("oracle");
+  });
+});

package/src/ProviderNotImplementedError.ts

@@ -0,0 +1,9 @@
+export class ProviderNotImplementedError extends Error {
+  readonly provider: string;
+
+  constructor(provider: string) {
+    super(`Provider "${provider}" is not implemented`);
+    this.name = "ProviderNotImplementedError";
+    this.provider = provider;
+  }
+}

package/src/ProviderNotInstalledError.test.ts

@@ -0,0 +1,11 @@
+import { describe, expect, it } from "vitest";
+import { ProviderNotInstalledError } from "./index.ts";
+
+describe("ProviderNotInstalledError", () => {
+  it("reports a missing provider", () => {
+    const error = new ProviderNotInstalledError("mysql");
+    expect(error.name).toBe("ProviderNotInstalledError");
+    expect(error.provider).toBe("mysql");
+    expect(error.message).toContain("mysql");
+  });
+});

package/src/ProviderNotInstalledError.ts

@@ -0,0 +1,9 @@
+export class ProviderNotInstalledError extends Error {
+  readonly provider: string;
+
+  constructor(provider: string) {
+    super(`Provider "${provider}" is not installed`);
+    this.name = "ProviderNotInstalledError";
+    this.provider = provider;
+  }
+}

package/src/ReadonlyRepository.test.ts

@@ -0,0 +1,406 @@
+import { describe, expect, it } from "vitest";
+import { MemoryDriver } from "@datasources/memory";
+import { collectAsync } from "./collectAsync.ts";
+import type { Cells } from "./converters/Cell.ts";
+import { TypeConverter } from "./converters/TypeConverter.ts";
+import { DefaultReadonlyEnrichmentStrategy } from "./DefaultReadonlyEnrichmentStrategy.ts";
+import { NestedToObjectEnrichmentStrategy } from "./NestedToObjectEnrichmentStrategy.ts";
+import { HashsetOptimizedReadonlyEnrichmentStrategy } from "./HashsetOptimizedReadonlyEnrichmentStrategy.ts";
+import { ReadonlyRepository } from "./ReadonlyRepository.ts";
+import { RepositoryTreeNode } from "./RepositoryTreeNode.ts";
+import { ChangeCasingMapper } from "./mappers/ChangeCasingMapper.ts";
+import { DictionaryMapper } from "./mappers/DictionaryMapper.ts";
+import type { IMapper } from "./mappers/IMapper.ts";
+import { TransformMapper } from "./mappers/TransformMapper.ts";
+import type { IConnection } from "./IConnection.ts";
+import type { Scalar } from "./builders/Scalar.ts";
+import { MockCommand } from "./mocks/mock-command.ts";
+import { MockConnection } from "./mocks/mock-connection.ts";
+import { MockReader } from "./mocks/mock-reader.ts";
+import { Join, Operator, SelectStatement, Where } from "./statements/index.ts";
+import { WhereText } from "./statements/WhereText.ts";
+
+class UserType {
+  Id = 0;
+  Name = "";
+}
+
+class Child {
+  Id = 0;
+  ParentId = 0;
+  Type = new UserType();
+  TypeName = "";
+  Label = "";
+}
+
+class Parent {
+  Id = 0;
+  Type = new UserType();
+  TypeName = "";
+  Children: Child[] = [];
+  Child?: Child | string;
+}
+
+class View {
+  UserType = "";
+}
+
+type Seed = Record<string, Scalar>;
+
+const snake = new ChangeCasingMapper("pascalCase", "snakeCase");
+const references = new DictionaryMapper<string>([["Type", "type_id"]]);
+const columns: IMapper<string, string> = new TransformMapper(
+  (name) => {
+    const mapped = references.map(name);
+    return mapped !== name ? mapped : snake.map(name);
+  },
+  (name) => {
+    const from = references.reverseMap(name);
+    return from !== name ? from : snake.reverseMap(name);
+  },
+);
+
+const repo = <T>(type: new () => T, connection: IConnection) =>
+  new ReadonlyRepository(connection, { type, propertyMappings: columns });
+
+const setup = async (rows: Seed[] = []): Promise<IConnection> => {
+  const connection = new MemoryDriver().connection();
+  await connection.open();
+  for (const row of rows) {
+    const response = await connection.createCommand().execute(
+      "insert",
+      Object.entries(row).map(([name, value]) => ({ name, value })),
+    );
+    if (typeof response.result === "number") row.id = response.result;
+  }
+  return connection;
+};
+
+const remove = (connection: IConnection, row: Seed) =>
+  connection.createCommand().execute("delete", [{ name: "id", value: row.id }]);
+
+describe("ReadonlyRepository", () => {
+  it("reads one row through a where clause", async () => {
+    const first: Seed = {};
+    const second: Seed = {};
+    const connection = await setup([first, second]);
+    const parentsRepo = repo(Parent, connection);
+    const byClause = await collectAsync(parentsRepo.read(new Where(new Operator.Equals("Id", first.id))));
+    const byWhere = await collectAsync(parentsRepo.read(new WhereText(JSON.stringify({ id: first.id }))));
+    expect(byClause.map((item) => item.Id)).toEqual([first.id]);
+    expect(byWhere.map((item) => item.Id)).toEqual([first.id]);
+  });
+
+  it("fills lookup select and leaves missing default", async () => {
+    const person: Seed = { name: "person" };
+    const gone: Seed = { name: "gone" };
+    const typesConnection = await setup([person, gone]);
+    await remove(typesConnection, gone);
+    const connection = await setup([{ type_id: person.id }, { type_id: gone.id }]);
+    const parentsRepo = repo(Parent, connection);
+    const typesRepo = repo(UserType, typesConnection);
+    parentsRepo.addEnriched({ destinationProperty: "TypeName", sourceProperty: "Type", relatedKey: "Id", relatedProperty: "Name" }, typesRepo);
+    const items = await collectAsync(parentsRepo.read());
+    expect(items[0]?.TypeName).toBe("person");
+    expect(items[1]?.TypeName).toBe("");
+  });
+
+  it("hashset fills lookup select and leaves missing default", async () => {
+    const person: Seed = { name: "person" };
+    const gone: Seed = { name: "gone" };
+    const typesConnection = await setup([person, gone]);
+    await remove(typesConnection, gone);
+    const connection = await setup([{ type_id: person.id }, { type_id: gone.id }]);
+    const parentsRepo = repo(Parent, connection);
+    const typesRepo = repo(UserType, typesConnection);
+    parentsRepo.addEnriched(
+      { destinationProperty: "TypeName", sourceProperty: "Type", relatedKey: "Id", relatedProperty: "Name" },
+      typesRepo,
+      new HashsetOptimizedReadonlyEnrichmentStrategy(),
+    );
+    const items = await collectAsync(parentsRepo.read());
+    expect(items[0]?.TypeName).toBe("person");
+    expect(items[1]?.TypeName).toBe("");
+  });
+
+  it("fills lists and readSingle is enriched", async () => {
+    const org: Seed = { name: "org" };
+    const typesConnection = await setup([org]);
+    const parent: Seed = { type_id: org.id };
+    const other: Seed = { type_id: org.id };
+    const connection = await setup([parent, other]);
+    await remove(connection, other);
+    const parentsRepo = repo(Parent, connection);
+    const typesRepo = repo(UserType, typesConnection);
+    const childrenConnection = await setup([
+      { parent_id: parent.id, label: "a" },
+      { parent_id: parent.id, label: "b" },
+      { parent_id: other.id, label: "x" },
+    ]);
+    const childrenRepo = repo(Child, childrenConnection);
+    parentsRepo.addEnriched({ destinationProperty: "TypeName", sourceProperty: "Type", relatedKey: "Id", relatedProperty: "Name" }, typesRepo);
+    parentsRepo.addEnriched({ destinationProperty: "Children", sourceProperty: "Id", relatedKey: "ParentId", type: "list" }, childrenRepo);
+    const item = await parentsRepo.readSingle();
+    expect(item?.TypeName).toBe("org");
+    expect(item?.Children.map((child) => child.Label)).toEqual(["a", "b"]);
+  });
+
+  it("hashset fills lists and readSingle is enriched", async () => {
+    const org: Seed = { name: "org" };
+    const typesConnection = await setup([org]);
+    const parent: Seed = { type_id: org.id };
+    const other: Seed = { type_id: org.id };
+    const connection = await setup([parent, other]);
+    await remove(connection, other);
+    const parentsRepo = repo(Parent, connection);
+    const typesRepo = repo(UserType, typesConnection);
+    const childrenConnection = await setup([
+      { parent_id: parent.id, label: "a" },
+      { parent_id: parent.id, label: "b" },
+      { parent_id: other.id, label: "x" },
+    ]);
+    const childrenRepo = repo(Child, childrenConnection);
+    const strategy = new HashsetOptimizedReadonlyEnrichmentStrategy<Parent>();
+    parentsRepo.addEnriched({ destinationProperty: "TypeName", sourceProperty: "Type", relatedKey: "Id", relatedProperty: "Name" }, typesRepo, strategy);
+    parentsRepo.addEnriched({ destinationProperty: "Children", sourceProperty: "Id", relatedKey: "ParentId", type: "list" }, childrenRepo, strategy);
+    const item = await parentsRepo.readSingle();
+    expect(item?.TypeName).toBe("org");
+    expect(item?.Children.map((child) => child.Label)).toEqual(["a", "b"]);
+  });
+
+  it("nests list lookup and keeps root sibling", async () => {
+    const org: Seed = { name: "org" };
+    const typesConnection = await setup([org]);
+    const home: Seed = { name: "home" };
+    const gone: Seed = { name: "gone" };
+    const childTypesConnection = await setup([home, gone]);
+    await remove(childTypesConnection, gone);
+    const parent: Seed = { type_id: org.id };
+    const connection = await setup([parent]);
+    const parentsRepo = repo(Parent, connection);
+    const typesRepo = repo(UserType, typesConnection);
+    const childTypesRepo = repo(UserType, childTypesConnection);
+    const childrenConnection = await setup([
+      { parent_id: parent.id, type_id: home.id, label: "a" },
+      { parent_id: parent.id, type_id: gone.id, label: "b" },
+    ]);
+    const childrenRepo = repo(Child, childrenConnection);
+    childrenRepo.addEnriched({ destinationProperty: "TypeName", sourceProperty: "Type", relatedKey: "Id", relatedProperty: "Name" }, childTypesRepo);
+    parentsRepo.addEnriched({ destinationProperty: "TypeName", sourceProperty: "Type", relatedKey: "Id", relatedProperty: "Name" }, typesRepo);
+    parentsRepo.addEnriched({ destinationProperty: "Children", sourceProperty: "Id", relatedKey: "ParentId", type: "list" }, childrenRepo);
+    const item = await parentsRepo.readSingle();
+    expect(item?.TypeName).toBe("org");
+    expect(item?.Children[0]?.TypeName).toBe("home");
+    expect(item?.Children[1]?.TypeName).toBe("");
+  });
+
+  it("hashset nests list lookup and keeps root sibling", async () => {
+    const org: Seed = { name: "org" };
+    const typesConnection = await setup([org]);
+    const home: Seed = { name: "home" };
+    const gone: Seed = { name: "gone" };
+    const childTypesConnection = await setup([home, gone]);
+    await remove(childTypesConnection, gone);
+    const parent: Seed = { type_id: org.id };
+    const connection = await setup([parent]);
+    const parentsRepo = repo(Parent, connection);
+    const typesRepo = repo(UserType, typesConnection);
+    const childTypesRepo = repo(UserType, childTypesConnection);
+    const childrenConnection = await setup([
+      { parent_id: parent.id, type_id: home.id, label: "a" },
+      { parent_id: parent.id, type_id: gone.id, label: "b" },
+    ]);
+    const childrenRepo = repo(Child, childrenConnection);
+    const strategy = new HashsetOptimizedReadonlyEnrichmentStrategy<Parent>();
+    childrenRepo.addEnriched({ destinationProperty: "TypeName", sourceProperty: "Type", relatedKey: "Id", relatedProperty: "Name" }, childTypesRepo);
+    parentsRepo.addEnriched({ destinationProperty: "TypeName", sourceProperty: "Type", relatedKey: "Id", relatedProperty: "Name" }, typesRepo, strategy);
+    parentsRepo.addEnriched({ destinationProperty: "Children", sourceProperty: "Id", relatedKey: "ParentId", type: "list" }, childrenRepo, strategy);
+    const item = await parentsRepo.readSingle();
+    expect(item?.TypeName).toBe("org");
+    expect(item?.Children[0]?.TypeName).toBe("home");
+    expect(item?.Children[1]?.TypeName).toBe("");
+  });
+
+  it("skips missing enrichment keys", async () => {
+    const connection = await setup([{ type_id: -1 }, { type_id: -1 }]);
+    const parentsRepo = repo(Parent, connection);
+    const typesRepo = repo(UserType, await setup([{ name: "person" }]));
+    const childrenRepo = repo(Child, await setup([{ label: "a" }]));
+    parentsRepo.addEnriched({ destinationProperty: "TypeName", sourceProperty: "Type", relatedKey: "Id", relatedProperty: "Name" }, typesRepo);
+    parentsRepo.addEnriched({ destinationProperty: "Children", sourceProperty: "Id", relatedKey: "ParentId", type: "list" }, childrenRepo);
+    const items = await collectAsync(parentsRepo.read());
+    expect(items[0]?.TypeName).toBe("");
+    expect(items[1]?.TypeName).toBe("");
+    expect(items[1]?.Children).toEqual([]);
+  });
+
+  it("readSingle is undefined when empty", async () => {
+    const parentsRepo = repo(Parent, await setup());
+    expect(await parentsRepo.readSingle()).toBeUndefined();
+  });
+
+  it("nests on a singular related object and skips strings", async () => {
+    const kept: Seed = { child: "skip" };
+    const nested: Seed = {};
+    const connection = await setup([kept, nested]);
+    const parentsRepo = repo(Parent, connection);
+    const home: Seed = { name: "home" };
+    const childTypesRepo = repo(UserType, await setup([home]));
+    const childrenRepo = repo(Child, await setup([
+      { parent_id: nested.id, type_id: home.id, label: "only" },
+    ]));
+    childrenRepo.addEnriched({ destinationProperty: "TypeName", sourceProperty: "Type", relatedKey: "Id", relatedProperty: "Name" }, childTypesRepo);
+    parentsRepo.addEnriched({ destinationProperty: "Child", sourceProperty: "Id", relatedKey: "ParentId" }, childrenRepo);
+    const items = await collectAsync(parentsRepo.read());
+    expect(items[0]?.Child).toBe("skip");
+    expect(items[1]?.Child && typeof items[1].Child === "object" ? items[1].Child.TypeName : undefined).toBe("home");
+  });
+
+  it("throws when an enrichment key is an object", async () => {
+    const typesRepo = repo(UserType, await setup());
+    await expect(
+      new DefaultReadonlyEnrichmentStrategy<Parent>().apply(
+        typesRepo,
+        { destinationProperty: "TypeName", sourceProperty: "Type", relatedKey: "Id", relatedProperty: "Name" },
+        [Object.assign(new Parent(), { Id: 1, Type: { Name: "x" } })],
+      ),
+    ).rejects.toThrow(/scalar/);
+  });
+
+  it("hashset assigns the related row when select is omitted", async () => {
+    const person: Seed = { name: "person" };
+    const typesConnection = await setup([person]);
+    const connection = await setup([{ type_id: person.id }]);
+    const parentsRepo = repo(Parent, connection);
+    const typesRepo = repo(UserType, typesConnection);
+    parentsRepo.addEnriched(
+      { destinationProperty: "Type", sourceProperty: "Type", relatedKey: "Id" },
+      typesRepo,
+      new HashsetOptimizedReadonlyEnrichmentStrategy(),
+    );
+    const items = await collectAsync(parentsRepo.read());
+    expect(items[0]?.Type).toMatchObject({ Name: "person" });
+  });
+
+  it("hashset skips missing keys and unmatched rows", async () => {
+    const person: Seed = { name: "person" };
+    const typesConnection = await setup([person]);
+    const matched: Seed = { type_id: person.id };
+    const missing: Seed = { type_id: Number(person.id) + 1 };
+    const blank: Seed = { type_id: -1 };
+    const connection = await setup([matched, missing, blank]);
+    const parentsRepo = repo(Parent, connection);
+    const typesRepo = repo(UserType, typesConnection);
+    const childrenConnection = await setup([
+      { label: "orphan" },
+      { parent_id: matched.id, label: "a" },
+      { parent_id: matched.id, label: "b" },
+    ]);
+    const childrenRepo = repo(Child, childrenConnection);
+    const strategy = new HashsetOptimizedReadonlyEnrichmentStrategy<Parent>();
+    parentsRepo.addEnriched({ destinationProperty: "TypeName", sourceProperty: "Type", relatedKey: "Id", relatedProperty: "Name" }, typesRepo, strategy);
+    parentsRepo.addEnriched({ destinationProperty: "Children", sourceProperty: "Id", relatedKey: "ParentId", type: "list" }, childrenRepo, strategy);
+    const items = await collectAsync(parentsRepo.read());
+    expect(items[0]?.TypeName).toBe("person");
+    expect(items[0]?.Children.map((child) => child.Label)).toEqual(["a", "b"]);
+    expect(items[1]?.TypeName).toBe("");
+    expect(items[1]?.Children).toEqual([]);
+    expect(items[2]?.Children).toEqual([]);
+    expect(new RepositoryTreeNode({}, "").value).toEqual({});
+  });
+
+  it("collapses join rows", async () => {
+    const person: Seed = { TypeName: "person" };
+    const org: Seed = { TypeName: "org" };
+    const connection = await setup([person, org]);
+    person.Id = person.id;
+    org.Id = org.id;
+    const parents: Parent[] = [];
+    const parentsRepo = repo(Parent, connection);
+    await new NestedToObjectEnrichmentStrategy<Parent>({
+      key: "Id",
+      fields: { Id: "Id", TypeName: "TypeName" },
+    }).apply(parentsRepo, { destinationProperty: "TypeName", sourceProperty: "Id", relatedKey: "Id" }, parents, [person, org]);
+    const items = parents;
+    expect(items.map((item) => item.Id)).toEqual([person.id, org.id]);
+    expect(items.map((item) => item.TypeName)).toEqual(["person", "org"]);
+  });
+
+    it("lookup key comes from renamed row", async () => {
+    const admin: Seed = { name: "admin" };
+    const typesConnection = await setup([admin]);
+    const typesRepo = repo(UserType, typesConnection);
+    const usersConnection = await setup([{ user_type_id: admin.id }]);
+    const usersRepo = new ReadonlyRepository(usersConnection, {
+      type: View,
+      propertyMappings: new DictionaryMapper([["UserType", "user_type_id"]]),
+    });
+    usersRepo.addEnriched({ destinationProperty: "UserType", sourceProperty: "UserType", relatedKey: "Id", relatedProperty: "Name" }, typesRepo);
+    const item = await usersRepo.readSingle();
+    expect(item?.UserType).toBe("admin");
+  });
+
+  it("uses per-call object and row converters when provided", async () => {
+    class Item {
+      Label = "";
+    }
+    class FixedLabel extends TypeConverter<Item, Cells> {
+      constructor(private readonly label: string) {
+        super();
+      }
+      convert = (_from: Cells): Item => Object.assign(new Item(), { Label: this.label });
+      reverseConvert = (to: Item): Cells => ({ Label: to.Label });
+    }
+    class TagLabel extends TypeConverter<Item, Cells> {
+      convert = (from: Cells): Item =>
+        Object.assign(new Item(), { Label: `tag:${String(from.Label)}` });
+      reverseConvert = (to: Item): Cells => ({ Label: to.Label });
+    }
+    class UpperLabel extends TypeConverter<Cells, Cells> {
+      convert = (from: Cells): Cells => ({
+        ...from,
+        Label: String(from.Label).toUpperCase(),
+      });
+      reverseConvert = (to: Cells): Cells => to;
+    }
+
+    const connection = new MockConnection();
+    const command = new MockCommand(connection);
+    connection.command = command;
+    command.reader = new MockReader([{ Label: "ada" }]);
+    const itemsRepo = new ReadonlyRepository(connection, {
+      type: Item,
+      entity: "items",
+      readProperties: ["Label"],
+      objectConverter: new FixedLabel("default"),
+    });
+    expect((await itemsRepo.readSingle())?.Label).toBe("default");
+
+    command.reader = new MockReader([{ Label: "ada" }]);
+    expect(
+      (
+        await itemsRepo.readSingle(undefined, undefined, {
+          objectConverter: new TagLabel(),
+          rowConverter: new UpperLabel(),
+        })
+      )?.Label,
+    ).toBe("tag:ADA");
+  });
+
+  it("public include uses the node binder", async () => {
+    const person: Seed = { name: "person" };
+    const typesConnection = await setup([person]);
+    const connection = await setup([{ type_id: person.id }]);
+    const parentsRepo = repo(Parent, connection);
+    const typesRepo = repo(UserType, typesConnection);
+    parentsRepo.addEnriched({ destinationProperty: "TypeName", sourceProperty: "Type", relatedKey: "Id", relatedProperty: "Name" }, typesRepo);
+    const items = await collectAsync(parentsRepo.read());
+    expect(items[0]?.TypeName).toBe("person");
+    await new DefaultReadonlyEnrichmentStrategy<Parent>().apply(
+      typesRepo,
+      { destinationProperty: "TypeName", sourceProperty: "Type", relatedKey: "Id", relatedProperty: "Name" },
+      items,
+      [{ Type: person.id }],
+    );
+  });
+});