@deterministic-code/datasources 0.0.0-stage → 0.1.1

package/src/index.ts

@@ -0,0 +1,222 @@
+export type { ICommand } from "./ICommand.ts";
+export { execute, executeReader } from "./ICommand.ts";
+export type { ICommandMiddleware } from "./ICommandMiddleware.ts";
+export type { IConnection } from "./IConnection.ts";
+export type { IDatasource } from "./IDatasource.ts";
+export type { IDriver } from "./IDriver.ts";
+export { columnType } from "./IDriver.ts";
+export type { Information } from "./Information.ts";
+export type { DatasourceOptions } from "./DatasourceOptions.ts";
+export { DatasourceFactory } from "./DatasourceFactory.ts";
+export { ProviderCatalog } from "./ProviderCatalog.ts";
+export type {
+  ICreateTableStatement,
+  ICreateIndexStatement,
+  IDeleteStatement,
+  IExpression,
+  IBulkDeleteStatement,
+  IBulkInsertStatement,
+  IBulkUpdateStatement,
+  IInsertStatement,
+  ISelectStatement,
+  IStatement,
+  IStatementVisitor,
+  ICondition,
+  IConditionVisitor,
+  IExecuteStoredProcedureStatement,
+  IReturnStatement,
+  ITableConstraint,
+  TableConstraintKind,
+  IUpdateStatement,
+  IWhere,
+} from "./statements/index.ts";
+export type { IReader } from "./IReader.ts";
+export type { IRepository } from "./IRepository.ts";
+export type { IReadonlyRepository } from "./IReadonlyRepository.ts";
+export type { ICRUDRepository } from "./ICRUDRepository.ts";
+export { ReadonlyRepository, untyped } from "./ReadonlyRepository.ts";
+export type { IRepositoryFactory } from "./IRepositoryFactory.ts";
+export type { ICRUDRepositoryFactory } from "./ICRUDRepositoryFactory.ts";
+export { RepositoryFactory } from "./RepositoryFactory.ts";
+export { RepositoryAccess } from "./RepositoryAccess.ts";
+export { RepositoryNotRegisteredError } from "./RepositoryNotRegisteredError.ts";
+export type { IEnriched } from "./IEnriched.ts";
+export type { IRepositoryTree } from "./IRepositoryTree.ts";
+export type { IRepositoryTreeNode } from "./IRepositoryTreeNode.ts";
+export type { Association, Enrichment } from "./Enrichment.ts";
+export { EnrichmentPropertyType } from "./EnrichmentPropertyType.ts";
+export type { IReadonlyEnrichmentStrategy } from "./IReadonlyEnrichmentStrategy.ts";
+export type { IWriteEnrichmentStrategy } from "./IWriteEnrichmentStrategy.ts";
+export type { WriteMode } from "./WriteMode.ts";
+export { DefaultReadonlyEnrichmentStrategy } from "./DefaultReadonlyEnrichmentStrategy.ts";
+export { DefaultWriteEnrichmentStrategy } from "./DefaultWriteEnrichmentStrategy.ts";
+export { DeleteEnrichmentStrategy } from "./DeleteEnrichmentStrategy.ts";
+export { CascadeDeleteEnrichmentStrategy } from "./CascadeDeleteEnrichmentStrategy.ts";
+export { UpdateEnrichmentStrategy } from "./UpdateEnrichmentStrategy.ts";
+export { DefaultUpdateEnrichmentStrategy } from "./DefaultUpdateEnrichmentStrategy.ts";
+export { CreateEnrichmentStrategy } from "./CreateEnrichmentStrategy.ts";
+export { DefaultCreateEnrichmentStrategy } from "./DefaultCreateEnrichmentStrategy.ts";
+export { CascadeDeleteUpdateEnrichmentStrategy } from "./CascadeDeleteUpdateEnrichmentStrategy.ts";
+export { LazyWriteEnrichmentStrategy } from "./LazyWriteEnrichmentStrategy.ts";
+export { HashsetOptimizedReadonlyEnrichmentStrategy } from "./HashsetOptimizedReadonlyEnrichmentStrategy.ts";
+export { NestedToObjectEnrichmentStrategy } from "./NestedToObjectEnrichmentStrategy.ts";
+export { BulkCRUDRepository } from "./BulkCRUDRepository.ts";
+export type { IBulkWriteStrategy } from "./IBulkWriteStrategy.ts";
+export type { BulkCommand } from "./BulkCommand.ts";
+export { SingleCommandIBulkWriteStrategy } from "./SingleCommandIBulkWriteStrategy.ts";
+export { BatchCommandIBulkWriteStrategy } from "./BatchCommandIBulkWriteStrategy.ts";
+export { StoredProcedureBulkWriteStrategy } from "./StoredProcedureBulkWriteStrategy.ts";
+export { RepositoryTree } from "./RepositoryTree.ts";
+export { RepositoryTreeNode } from "./RepositoryTreeNode.ts";
+export { CRUDRepository } from "./CRUDRepository.ts";
+export { ReadonlyRepositoryBuilder } from "./ReadonlyRepositoryBuilder.ts";
+export { CRUDRepositoryBuilder } from "./CRUDRepositoryBuilder.ts";
+export { StatementMappers } from "./StatementMappers.ts";
+export { ReadonlyRepositoryStatements } from "./ReadonlyRepositoryStatements.ts";
+export { CRUDRepositoryStatements } from "./CRUDRepositoryStatements.ts";
+export type { BuiltRepository } from "./BuiltRepository.ts";
+export { createCRUDRepositoryOptions } from "./createCRUDRepositoryOptions.ts";
+export { createReadonlyRepositoryMappingOptions } from "./createReadonlyRepositoryMappingOptions.ts";
+export type { ReadonlyRepositoryMappingOptions } from "./ReadonlyRepositoryMappingOptions.ts";
+export type { CRUDRepositoryOptions } from "./CRUDRepositoryOptions.ts";
+export { Response } from "./Response.ts";
+export type { ITransaction } from "./ITransaction.ts";
+export type { IUnitOfWork } from "./IUnitOfWork.ts";
+export { UnitOfWorkTransaction } from "./UnitOfWorkTransaction.ts";
+export { IsolationLevel } from "./IsolationLevel.ts";
+export type { IsolationLevel as IsolationLevelName } from "./IsolationLevel.ts";
+export type { Comparison } from "./statements/index.ts";
+export {
+  ArrayExpression,
+  CheckConstraint,
+  ColumnDefault,
+  Condition,
+  ConditionRenderer,
+  ExpressionRenderer,
+  CreateIndexStatement,
+  CreateTableStatement,
+  CreateTableStatementTextRenderer,
+  CreateIndexStatementTextRenderer,
+  SelectStatementTextRenderer,
+  InsertStatementTextRenderer,
+  UpdateStatementTextRenderer,
+  DeleteStatementTextRenderer,
+  BulkInsertStatementTextRenderer,
+  BulkUpdateStatementTextRenderer,
+  BulkDeleteStatementTextRenderer,
+  ExecuteStoredProcedureStatementTextRenderer,
+  ReturnStatementTextRenderer,
+  SelectInsertedIdStatementTextRenderer,
+  DefaultStatementTextRenderer,
+  DeleteStatement,
+  ForeignKey,
+  Identifier,
+  InsertStatement,
+  BulkInsertStatement,
+  BulkUpdateStatement,
+  BulkDeleteStatement,
+  Literal,
+  NotNull,
+  Operator,
+  eq,
+  ne,
+  gt,
+  lt,
+  ge,
+  le,
+  PrimaryKey,
+  Aggregate,
+  OrderBy,
+  SelectStatement,
+  StatementParser,
+  StatementRenderer,
+  StatementTextRenderer,
+  Native,
+  n,
+  Subquery,
+  ReferentialAction,
+  ExpressionEvaluator,
+  StatementEvaluator,
+  ExecuteStoredProcedureStatement,
+  SelectInsertedIdStatement,
+  ReturnStatement,
+  UniqueConstraint,
+  UpdateStatement,
+  WhereText,
+  Where,
+  Join,
+} from "./statements/index.ts";
+export type { IDatasourceFactory } from "./IDatasourceFactory.ts";
+export type { Parameter } from "./Parameter.ts";
+export { ParameterDirection } from "./ParameterDirection.ts";
+export type { ParameterDirection as ParameterDirectionName } from "./ParameterDirection.ts";
+export type { Row } from "./Row.ts";
+export { ArrayReader } from "./ArrayReader.ts";
+export { FirstResultReader } from "./FirstResultReader.ts";
+export { StreamingReader, statementReader } from "./StreamingReader.ts";
+export { splitStatements } from "./splitStatements.ts";
+export { statementParameters } from "./statementParameters.ts";
+export { statementUsesParameter } from "./statementUsesParameter.ts";
+export { collectAsync } from "./collectAsync.ts";
+export { CommandMiddlewareHost } from "./CommandMiddlewareHost.ts";
+export {
+  ConsoleCommandMiddleware,
+  formatElapsed,
+} from "./ConsoleCommandMiddleware.ts";
+export { ExpectConsoleMiddleware } from "./ExpectConsoleMiddleware.ts";
+export { Datasource } from "./Datasource.ts";
+export { DatasourceUrl } from "./DatasourceUrl.ts";
+export { DatasourceUrlParser } from "./DatasourceUrlParser.ts";
+import { Datasource } from "./Datasource.ts";
+import { DatasourceFactory } from "./DatasourceFactory.ts";
+Datasource.create = (options) => DatasourceFactory.create(options) as Datasource;
+export { DatasourceError } from "./DatasourceError.ts";
+export type { Cell, Cells } from "./converters/Cell.ts";
+export type { Constructable } from "./converters/Constructable.ts";
+export { TypeConverter } from "./converters/TypeConverter.ts";
+export { MetaDataRowTypeConverter } from "./converters/MetaDataRowTypeConverter.ts";
+export { RowTypeConverter } from "./converters/RowTypeConverter.ts";
+export { ToLowerCaseConverter } from "./converters/ToLowerCaseConverter.ts";
+export { ToUpperCaseConverter } from "./converters/ToUpperCaseConverter.ts";
+export { ChangeCasingConverter, type Casing } from "./converters/ChangeCasingConverter.ts";
+export { PluralizerConverter } from "./converters/PluralizerConverter.ts";
+export { RegexConverter } from "./converters/RegexConverter.ts";
+export { ReplaceConverter } from "./converters/ReplaceConverter.ts";
+export type { IMapper } from "./mappers/IMapper.ts";
+export type { IFlatToNestedMapper } from "./mappers/IFlatToNestedMapper.ts";
+export type { TypeMap, TypeMapFields } from "./mappers/TypeMap.ts";
+export type { TypeMapGroup } from "./mappers/TypeMapGroup.ts";
+export { FlatToNestedMapper } from "./mappers/FlatToNestedMapper.ts";
+export { ChangeCasingMapper } from "./mappers/ChangeCasingMapper.ts";
+export { DictionaryMapper } from "./mappers/DictionaryMapper.ts";
+export { IdentityMapper } from "./mappers/IdentityMapper.ts";
+export { PluralizerMapper } from "./mappers/PluralizerMapper.ts";
+export { TransformMapper } from "./mappers/TransformMapper.ts";
+export { TransformConverterMapper } from "./mappers/TransformConverterMapper.ts";
+export { RowTypeMapper } from "./mappers/RowTypeMapper.ts";
+export { parametersToRecord } from "./parametersToRecord.ts";
+export { ProviderNotImplementedError } from "./ProviderNotImplementedError.ts";
+export { ProviderNotInstalledError } from "./ProviderNotInstalledError.ts";
+export type { Column, JoinKind, SelectStatementOptions, ReferentialAction as ReferentialActionName, SortDirection } from "./statements/index.ts";
+export type { Field, Scalar } from "./builders/index.ts";
+export { readerToAsyncIterable } from "./readerToAsyncIterable.ts";
+export {
+  StubCommand,
+  StubConnection,
+  StubDatasource,
+  StubReader,
+  StubRepository,
+  StubTransaction,
+  createStubDatasource,
+} from "./stubs/index.ts";
+export {
+  MockCommand,
+  MockConnection,
+  MockDatasource,
+  MockDriver,
+  MockSelectStatement,
+  MockReader,
+  MockRepository,
+  MockTransaction,
+  MockWhere,
+} from "./mocks/index.ts";

package/src/mappers/ChangeCasingMapper.test.ts

@@ -0,0 +1,32 @@
+import { describe, expect, it } from "vitest";
+import { ChangeCasingMapper } from "./ChangeCasingMapper.ts";
+
+describe("ChangeCasingMapper", () => {
+  it("maps pascal to snake and back", () => {
+    const mapper = new ChangeCasingMapper("pascalCase", "snakeCase");
+    expect(mapper.map("UserType")).toBe("user_type");
+    expect(mapper.map("Id")).toBe("id");
+    expect(mapper.reverseMap("user_type")).toBe("UserType");
+    expect(mapper.reverseMap("id")).toBe("Id");
+  });
+
+  it("maps contact names", () => {
+    const mapper = new ChangeCasingMapper("pascalCase", "snakeCase");
+    const contact = mapper.map("Contact");
+    const firstName = mapper.map("FirstName");
+    const emailAddress = mapper.map("EmailAddress");
+    expect(contact).toBe("contact");
+    expect(firstName).toBe("first_name");
+    expect(emailAddress).toBe("email_address");
+  });
+
+  it("reverse maps contact names", () => {
+    const mapper = new ChangeCasingMapper("pascalCase", "snakeCase");
+    const contact = mapper.reverseMap("contact");
+    const firstName = mapper.reverseMap("first_name");
+    const emailAddress = mapper.reverseMap("email_address");
+    expect(contact).toBe("Contact");
+    expect(firstName).toBe("FirstName");
+    expect(emailAddress).toBe("EmailAddress");
+  });
+});

package/src/mappers/ChangeCasingMapper.ts

@@ -0,0 +1,15 @@
+import { ChangeCasingConverter, type Casing } from "../converters/ChangeCasingConverter.ts";
+import type { IMapper } from "./IMapper.ts";
+
+export class ChangeCasingMapper implements IMapper<string, string> {
+  private readonly forward: ChangeCasingConverter;
+  private readonly reverse: ChangeCasingConverter;
+
+  constructor(from: Casing, to: Casing) {
+    this.forward = new ChangeCasingConverter(to);
+    this.reverse = new ChangeCasingConverter(from);
+  }
+
+  map = (value: string): string => this.forward.convert(value);
+  reverseMap = (value: string): string => this.reverse.convert(value);
+}

package/src/mappers/DictionaryMapper.test.ts

@@ -0,0 +1,69 @@
+import { describe, expect, it } from "vitest";
+import { DictionaryMapper } from "./DictionaryMapper.ts";
+import { MockCommand } from "../mocks/mock-command.ts";
+import { MockConnection } from "../mocks/mock-connection.ts";
+import { MockReader } from "../mocks/mock-reader.ts";
+import { ReadonlyRepository } from "../ReadonlyRepository.ts";
+
+class Account {
+  Key = 0;
+  Login = "";
+}
+
+describe("DictionaryMapper", () => {
+  it("maps known names and passes through the rest", () => {
+    const mapper = new DictionaryMapper([
+      ["FirstName", "given_name"],
+      ["LastName", "family_name"],
+      ["Email", "email_address"],
+    ]);
+    const firstName = mapper.map("FirstName");
+    const lastName = mapper.map("LastName");
+    const email = mapper.map("Email");
+    const phone = mapper.map("Phone");
+    const fromFirst = mapper.reverseMap("given_name");
+    const fromLast = mapper.reverseMap("family_name");
+    const fromEmail = mapper.reverseMap("email_address");
+    const fromPhone = mapper.reverseMap("Phone");
+    expect(firstName).toBe("given_name");
+    expect(lastName).toBe("family_name");
+    expect(email).toBe("email_address");
+    expect(phone).toBe("Phone");
+    expect(fromFirst).toBe("FirstName");
+    expect(fromLast).toBe("LastName");
+    expect(fromEmail).toBe("Email");
+    expect(fromPhone).toBe("Phone");
+  });
+
+  it("first key wins on reverse", () => {
+    const mapper = new DictionaryMapper([
+      ["Home", "address"],
+      ["Work", "address"],
+    ]);
+    const home = mapper.map("Home");
+    const work = mapper.map("Work");
+    const address = mapper.reverseMap("address");
+    expect(home).toBe("address");
+    expect(work).toBe("address");
+    expect(address).toBe("Home");
+  });
+
+  it("read reverse-maps column names", async () => {
+    const connection = new MockConnection(undefined, "memory");
+    const command = new MockCommand(connection);
+    connection.command = command;
+    const repo = new ReadonlyRepository(connection, {
+      type: Account,
+      entity: "user",
+      propertyMappings: new DictionaryMapper([
+        ["Key", "id"],
+        ["Login", "username"],
+      ]),
+    });
+    command.reader = new MockReader([{ id: 7, username: "ada" }]);
+    const row = await repo.readSingle();
+    expect(row?.Key).toBe(7);
+    expect(row?.Login).toBe("ada");
+    expect(command.executeReaderCalls[0]?.text).toBe("SELECT id, username FROM user");
+  });
+});

package/src/mappers/DictionaryMapper.ts

@@ -0,0 +1,16 @@
+import type { IMapper } from "./IMapper.ts";
+
+export class DictionaryMapper<T extends string | number> implements IMapper<T, T> {
+  private readonly forward = new Map<T, T>();
+  private readonly reverse = new Map<T, T>();
+
+  constructor(map: readonly (readonly [T, T])[]) {
+    for (const [from, to] of map) {
+      this.forward.set(from, to);
+      if (!this.reverse.has(to)) this.reverse.set(to, from);
+    }
+  }
+
+  map = (value: T): T => this.forward.get(value) ?? value;
+  reverseMap = (value: T): T => this.reverse.get(value) ?? value;
+}

package/src/mappers/FlatToNestedMapper.test.ts

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