@shirudo/ddd-kit 1.1.0 → 1.3.0

package/dist/testing.d.ts

@@ -0,0 +1,252 @@
+import { I as IAggregateRoot, a as Id, A as AnyDomainEvent } from './aggregate-BGdgvqKh.js';
+import '@shirudo/result';
+import '@shirudo/base-error';
+
+/**
+ * The repository surface the contract suite exercises: the minimal
+ * structural subset of the canonical `IUnitOfWorkRepository` (exported
+ * from the main entry) that the tests need. `getById` is typed over
+ * the aggregate's own branded id (`TAgg["id"]`), so concrete adapters,
+ * including arrow-function-property style repositories, which are
+ * checked contravariantly, match without casts.
+ */
+interface ContractRepository<TAgg extends IAggregateRoot<Id<string>, AnyDomainEvent>> {
+    getById(id: TAgg["id"]): Promise<TAgg | null>;
+    save(aggregate: TAgg): Promise<void>;
+    delete(aggregate: TAgg): Promise<void>;
+}
+/**
+ * One isolated test environment: fresh storage, fresh outbox. The
+ * suite creates one per test via {@link RepositoryContractHarness} and
+ * tears it down afterwards (a teardown failure never masks an
+ * in-flight contract violation).
+ */
+interface RepositoryContractEnvironment<TAgg extends IAggregateRoot<Id<string>, Evt>, Evt extends AnyDomainEvent = AnyDomainEvent> {
+    /**
+     * Execute one unit of work against the adapter under test: open the
+     * transaction, hand the suite a tx-bound repository, commit on
+     * resolve, roll back on throw, and run the post-commit lifecycle
+     * (event harvest into the outbox, `markPersisted`). Wire this
+     * through your real `UnitOfWork` / `withCommit` setup: the commit
+     * boundary IS part of what the suite proves.
+     */
+    run<R>(work: (ctx: {
+        repository: ContractRepository<TAgg>;
+    }) => Promise<R>): Promise<R>;
+    /**
+     * All events currently persisted in the outbox (committed writes
+     * only; a rolled-back transaction's events must not appear here).
+     */
+    committedOutboxEvents(): Promise<ReadonlyArray<Evt>>;
+    /** Release connections, drop schemas, etc. Called in a finally. */
+    teardown?(): Promise<void>;
+}
+/**
+ * What an adapter supplies to run the contract suite.
+ *
+ * The harness MUST provide isolation per environment (fresh
+ * tables/keyspace or a truncate); tests assume they see only their
+ * own writes. **For SQL/ORM adapters this must run against a real
+ * database** (testcontainers or equivalent), not an in-memory fake:
+ * the mandatory two-writer test proves YOUR `WHERE version = ?`
+ * predicate, and an in-memory stand-in proves only itself.
+ *
+ * Optional capabilities widen the suite: tests for an absent
+ * capability come back **marked `skipped`** with a `run()` that
+ * rejects loudly: bind them with `it.skip` so the gap stays visible
+ * in every report (see {@link RepositoryContractTest}); a naive
+ * binding fails instead of green-no-op'ing. Capabilities are captured
+ * once at suite creation. Provide every capability your adapter can
+ * support; each one closes a real OCC hole.
+ */
+interface RepositoryContractHarness<TAgg extends IAggregateRoot<Id<string>, Evt>, Evt extends AnyDomainEvent = AnyDomainEvent> {
+    createEnvironment(): Promise<RepositoryContractEnvironment<TAgg, Evt>>;
+    /**
+     * A brand-new aggregate (never persisted, unique id,
+     * `persistedVersion === undefined`).
+     */
+    createAggregate(): TAgg;
+    /**
+     * Apply exactly ONE version-bumping domain mutation that records at
+     * least one domain event (a `commit()`-style state change). The
+     * suite relies on the +1-per-call arithmetic and on the event for
+     * its outbox assertions.
+     */
+    mutate(aggregate: TAgg): void;
+    /**
+     * Optional: a version-bumping mutation whose state is deep-equal to
+     * the previous state (`setState({...state}, true)`). Enables the
+     * version-only-change-still-persists test: the skip-save/OCC-desync
+     * trap.
+     */
+    mutateVersionOnly?(aggregate: TAgg): void;
+    /**
+     * Optional: a mutation that changes ONLY a child collection (a
+     * non-root-row `changedKeys` entry). Enables the
+     * child-change-bumps-root-version test for partial-write
+     * repositories.
+     */
+    mutateChildCollection?(aggregate: TAgg): void;
+    /**
+     * Optional: construct a NEW (never-persisted) aggregate instance
+     * carrying a SPECIFIC id. Enables TWO tests: deletion-is-final-
+     * across-instances (resurrection via a factory after delete) and
+     * the duplicate-insert test (see
+     * {@link insertsAreDuplicateChecked} to opt out of the latter
+     * independently).
+     */
+    createAggregateWithId?(id: TAgg["id"]): TAgg;
+    /**
+     * Semantic opt-OUT (default `true`): whether `save()`'s INSERT path
+     * rejects an existing id with `DuplicateAggregateError` (mapping the
+     * driver's unique-violation: Postgres `23505`, MySQL `1062`, SQLite
+     * `SQLITE_CONSTRAINT_UNIQUE`). This is the near-mandatory contract:
+     * `save()` is insert-or-update, never upsert. Create-idempotency
+     * belongs in the USE CASE (load, then decide), not in the save path.
+     * Set `false` ONLY for a deliberately upserting adapter
+     * (idempotent-create design); the duplicate-insert test is then
+     * reported as skipped under this capability name, without costing
+     * the deletion-finality coverage that `createAggregateWithId` also
+     * gates.
+     */
+    insertsAreDuplicateChecked?: boolean;
+    /**
+     * Optional: a plain-data projection of the aggregate's persisted
+     * state, compared with deep equality. Enables the mandatory test's
+     * state assertion (without it, only the version and the outbox are
+     * compared, and an adapter whose predicate guards the version write
+     * but not the state write would slip through).
+     *
+     * **The projection must be roundtrip-stable**: it compares a
+     * DB-reloaded aggregate against an in-memory one, so normalize
+     * anything your store changes in transit: dates to ISO strings at
+     * your store's precision (MySQL DATETIME truncates millis), no
+     * `undefined`-valued keys (JSON columns drop them), decimals/bigints
+     * to one consistent representation. A mismatch here fails the
+     * mandatory test; the message names the projection as a suspect.
+     */
+    snapshotState?(aggregate: TAgg): unknown;
+    /**
+     * Optional flag: declare it when your `delete(aggregate)` runs an
+     * OCC predicate (`DELETE … WHERE id = ? AND version = ?`). Enables
+     * the stale-delete conflict test. Unpredicated deletes are
+     * last-write-wins by construction: acceptable for GC-style
+     * cleanup, rarely for user-initiated deletion of contended
+     * aggregates (see the repository guide).
+     */
+    deletesAreVersionChecked?: boolean;
+}
+/**
+ * One named contract test; `run` rejects with a descriptive Error on
+ * violation. When the harness lacks the capability a test needs, the
+ * entry is still returned with {@link skipped} set and a `run` that
+ * REJECTS with an explanatory error: bind it with your runner's skip
+ * (`(test.skipped ? it.skip : it)(test.name, test.run)`) so the gap is
+ * visible in every test report: a missing capability must never look
+ * like green coverage, and a naive binding that ignores `skipped`
+ * fails loud instead of passing silently.
+ */
+interface RepositoryContractTest {
+    name: string;
+    run: () => Promise<void>;
+    /** Present when the harness lacks the capability this test needs. */
+    skipped?: {
+        capability: string;
+    };
+}
+/**
+ * The repository contract test suite: the proof that an adapter
+ * actually delivers the guarantees the kit's Unit of Work documents.
+ *
+ * The kit is ORM-agnostic: the OCC version predicate lives in YOUR
+ * repository's SQL. That makes optimistic concurrency a **repository
+ * contract, not a kit guarantee**: the kit ships the boundary, the
+ * `persistedVersion` baseline, `ConcurrencyConflictError`, and this
+ * suite; your adapter must pass it. An adapter that has not passed the
+ * suite (against a real database, for SQL adapters) has not
+ * demonstrated OCC.
+ *
+ * Framework-agnostic: assertions throw plain `Error`s, so the suite
+ * binds to vitest, jest, or `node:test` the same way:
+ *
+ * ```ts
+ * import { describe, it } from "vitest";
+ * import { createRepositoryContractTests } from "@shirudo/ddd-kit/testing";
+ *
+ * const harness: RepositoryContractHarness<Order, OrderEvent> = {
+ *   createEnvironment: async () => {
+ *     const schema = await provisionTestSchema(); // testcontainers etc.
+ *     const uowDeps = {
+ *       scope: schema.scope,
+ *       outbox: schema.outbox,
+ *       repositories: {
+ *         orders: (tx, session) => new DrizzleOrderRepository(tx, session),
+ *       },
+ *     };
+ *     return {
+ *       run: (work) =>
+ *         new UnitOfWork(uowDeps).run(({ repositories }) =>
+ *           work({ repository: repositories.orders })),
+ *       committedOutboxEvents: () => schema.readOutboxEvents(),
+ *       teardown: () => schema.drop(),
+ *     };
+ *   },
+ *   createAggregate: () => Order.draft(orderIds.next()),
+ *   mutate: (order) => order.changeNote(`note-${counter++}`), // ONE bump + event
+ *   // provide every optional capability your adapter supports:
+ *   createAggregateWithId: (id) => Order.draft(id),
+ *   snapshotState: (order) => normalizeForRoundtrip(order.state),
+ *   deletesAreVersionChecked: true,
+ * };
+ *
+ * describe("DrizzleOrderRepository: repository contract", () => {
+ *   for (const test of createRepositoryContractTests(harness)) {
+ *     (test.skipped ? it.skip : it)(test.name, test.run);
+ *   }
+ * });
+ * ```
+ *
+ * **`env.run` must provide unit-of-work semantics.** Three core tests
+ * (identity-map sameness, getById-null-after-delete, deletion
+ * finality) exercise the session machinery: `session.identityMap`,
+ * the `isDeleted` probe, the deleted-gate. Wiring `run` through the
+ * kit's `UnitOfWork` gives you all of it; a hand-rolled `withCommit`
+ * wiring must provide equivalents or those tests will fail. A
+ * `withCommit`-only setup that deliberately makes no identity-map /
+ * deletion-finality claims is outside this suite's scope; the suite
+ * is the compliance bar for unit-of-work repositories.
+ *
+ * **Error matching is by NAME along the `cause` chain, not by
+ * `instanceof`.** The suite ships in its own bundle entry; comparing
+ * class identity would spuriously fail whenever the adapter's errors
+ * come from a different copy of the kit (the main entry's bundle, or a
+ * second installed version). `error.name === "ConcurrencyConflictError"`
+ * anywhere in the chain is the contract.
+ *
+ * **What each test proves.** The OCC, routing, rollback, and outbox
+ * tests prove YOUR adapter's SQL and transaction wiring. The
+ * identity-map, deletion-finality, and event-lifecycle tests prove
+ * your READ-PATH and unit-of-work WIRING (they exercise kit-provided
+ * machinery, namely `session.identityMap`, the deleted-gate, and
+ * `withCommit`'s harvest, and fail when your repository bypasses or
+ * mis-wires it).
+ * A deletion-finality failure usually means a missing
+ * `identityMap.isDeleted` check or an `enrollSaved` placed after the
+ * row write, not a broken DELETE statement.
+ *
+ * **Known limitation: no truly concurrent runs.** The mandatory
+ * two-writer test is deliberately sequential-deterministic: writer B
+ * loads, writer A loads/mutates/commits, then B commits its stale
+ * instance. The stale `persistedVersion` baseline travels with B's
+ * instance, so the version predicate is exercised exactly as in a true
+ * race, without depending on lock timing, pool sizes, or
+ * engine-specific blocking. The flip side: lock interaction is NOT
+ * covered. A `SELECT … FOR UPDATE`-style repository that blocks
+ * instead of conflicting, or a SERIALIZABLE engine surfacing raw
+ * serialization failures (Postgres 40001) your adapter must map to
+ * `ConcurrencyConflictError`, needs adapter-specific tests on top of
+ * this suite.
+ */
+declare function createRepositoryContractTests<TAgg extends IAggregateRoot<Id<string>, Evt>, Evt extends AnyDomainEvent = AnyDomainEvent>(harness: RepositoryContractHarness<TAgg, Evt>): RepositoryContractTest[];
+
+export { type ContractRepository, type RepositoryContractEnvironment, type RepositoryContractHarness, type RepositoryContractTest, createRepositoryContractTests };