@shirudo/ddd-kit 2.0.0 → 2.2.0

package/README.md

@@ -1,8 +1,8 @@
 # @shirudo/ddd-kit
 
-Composable TypeScript toolkit for tactical Domain-Driven Design. Ships the canonical building blocks (Value Objects, Entities, Aggregate Roots, Domain Events, Repositories, and CQRS handlers) without a framework or runtime lock-in. ESM-only; runs on Node 18+, Cloudflare Workers, Vercel Edge, Deno, and Bun.
+Composable TypeScript toolkit for tactical Domain-Driven Design. Ships the canonical building blocks (Value Objects, Entities, Aggregate Roots, Domain Events, Repositories, and CQRS handlers) without a framework or runtime lock-in. ESM-only; runs on Node 20+, Cloudflare Workers, Vercel Edge, Deno, and Bun.
 
-> **Stable: 1.0**
+> **Stable: 2.1**
 >
 > The public API is stable and follows [Semantic Versioning](https://semver.org/). Breaking changes bump the major and ship with a migration path in the [CHANGELOG](https://github.com/shi-rudo/ddd-kit-ts/blob/main/CHANGELOG.md).
 
@@ -15,11 +15,13 @@ Composable TypeScript toolkit for tactical Domain-Driven Design. Ships the canon
 - **Entities:** identity + lifecycle, with collection helpers branded by `Id<Tag>`.
 - **Aggregate Roots:** state-stored (`AggregateRoot`) and event-sourced (`EventSourcedAggregate`), with optimistic-concurrency versioning.
 - **Domain Events:** typed, deeply frozen, carry metadata for traceability and schema evolution.
+- **Domain State Machine:** finite, named domain states with typed context, guards, reducers, terminal states, and value outputs for aggregate lifecycles and process managers.
 - **Repositories:** technology-agnostic persistence ports with an Identity-Map contract and OCC.
 - **CQRS:** zero-config in-memory `CommandBus` / `QueryBus`, plus `CommandHandler` / `QueryHandler` types for external brokers.
 - **Unit of Work:** opt-in `UnitOfWork` facade with tx-bound repositories, repository-side enrollment, a per-operation Identity Map, and aggregate-level dirty tracking (`changedKeys` / `hasChanges`) for partial writes. Honestly speaking: a transaction coordinator with registration and Identity Map; writes stay explicit by design (no auto-flush).
 - **Outbox:** `withCommit` harvests pending events inside the transaction, stamps them with the aggregate's commit version, and publishes them atomically.
-- **Repository contract tests:** `@shirudo/ddd-kit/testing` ships the suite every adapter must pass: OCC is a testable contract, not a documented pattern.
+- **Event Store:** `EventStore` port with expectedVersion-guarded appends and snapshot catch-up reads, plus `InMemoryEventStore` as the reference implementation.
+- **Repository contract tests:** `@shirudo/ddd-kit/testing` ships the suites (state-stored and event-sourced) every adapter must pass: OCC is a testable contract, not a documented pattern.
 - **Result-first boundary:** a typed error hierarchy on [`@shirudo/base-error`](https://www.npmjs.com/package/@shirudo/base-error) and `Result` from [`@shirudo/result`](https://www.npmjs.com/package/@shirudo/result); `voValidated` collects field violations and renders RFC 9457 via the opt-in `@shirudo/ddd-kit/http` entry.
 
 ## Installation
@@ -58,6 +60,7 @@ Each building block has a dedicated guide. Start with [Design Decisions](https:/
 | Aggregate Roots, factories, reconstitution | [Aggregate Roots](https://github.com/shi-rudo/ddd-kit-ts/blob/main/docs/guide/aggregates.md) |
 | Event sourcing (`apply`, replay, snapshots) | [Event Sourcing](https://github.com/shi-rudo/ddd-kit-ts/blob/main/docs/guide/event-sourcing.md) |
 | Domain Events (`createDomainEvent`, metadata) | [Domain Events](https://github.com/shi-rudo/ddd-kit-ts/blob/main/docs/guide/domain-events.md) |
+| Domain State Machine (`DomainStateMachine`, `transitionDomainState`) | [Domain State Machine](https://github.com/shi-rudo/ddd-kit-ts/blob/main/docs/guide/domain-state-machine.md) |
 | Errors: throw vs Result, `ValidationError`, RFC 9457 | [Result vs Throw](https://github.com/shi-rudo/ddd-kit-ts/blob/main/docs/guide/result-vs-throw.md) |
 | Commands, queries, buses | [CQRS & Buses](https://github.com/shi-rudo/ddd-kit-ts/blob/main/docs/guide/cqrs-and-buses.md) |
 | Repositories, Identity Map, OCC | [Repository](https://github.com/shi-rudo/ddd-kit-ts/blob/main/docs/guide/repository.md) |

package/dist/{aggregate-CePTINEt.d.ts → aggregate-DFi6HlEh.d.ts}

@@ -106,6 +106,29 @@ declare class MissingHandlerError extends BaseError<"MissingHandlerError"> {
     readonly eventType: string;
     constructor(eventType: string, cause?: unknown);
 }
+/**
+ * Thrown by `EventSourcedAggregate.loadFromHistory` and
+ * `restoreFromSnapshotWithEvents` when the replay target is not fresh:
+ * the aggregate carries unflushed `pendingEvents`, or (for
+ * `loadFromHistory`) an in-memory version that was never persisted.
+ * Replaying onto such an instance would `markRestored` a
+ * `persistedVersion` that counts unpersisted history: repository routing
+ * flips from INSERT to UPDATE (or appends with a wrong expected version)
+ * and harvested events would claim a version baseline the stream does
+ * not carry.
+ *
+ * Deliberately **not** a `DomainError` or `InfrastructureError` (same
+ * posture as {@link MissingHandlerError}): a deterministic programming
+ * bug in how the aggregate was constructed before replay. It propagates
+ * as a throw instead of riding the replay methods' `Result` channel, so
+ * a generic corrupted-stream handler cannot absorb it. Reconstitution
+ * belongs on a bare instance: construct the aggregate without
+ * factory-recorded events or prior mutations, then replay.
+ */
+declare class UnreplayableAggregateError extends BaseError<"UnreplayableAggregateError"> {
+    readonly aggregateId: string;
+    constructor(aggregateId: string, reason: string);
+}
 /**
  * Thrown by `withCommit` when an event harvested from an aggregate cannot
  * be safely committed: it is missing `aggregateId` / `aggregateType`
@@ -131,6 +154,34 @@ declare class EventHarvestError extends BaseError<"EventHarvestError"> {
     /** The `type` of the offending event, for programmatic routing. */
     eventType?: string | undefined);
 }
+/** Constructor options for {@link UnregisteredHandlerError}. */
+interface UnregisteredHandlerErrorOptions {
+    /** Which bus rejected the dispatch. */
+    readonly busKind: "command" | "query";
+    /** The message type no handler was registered for. */
+    readonly messageType: string;
+}
+/**
+ * Produced by the in-memory `CommandBus` / `QueryBus` when a message is
+ * dispatched for a type no handler was registered under: a wiring bug
+ * (typo in the type string, missing `register` call at bootstrap), not
+ * a domain or infrastructure failure.
+ *
+ * Extends `BaseError` directly (same crash-loud family as
+ * {@link MissingHandlerError}): a generic `catch (e instanceof
+ * DomainError)` handler must not absorb it. For 2.x compatibility the
+ * buses still deliver it through their error CHANNEL (`err(...)` via the
+ * `errorMapper`, so the default string channel keeps its exact message)
+ * rather than throwing; the named type exists so a typed error channel
+ * can route it explicitly instead of pattern-matching message strings.
+ * `QueryBus.executeUnsafe` throws it directly. v3 makes `execute` throw
+ * it too.
+ */
+declare class UnregisteredHandlerError extends BaseError<"UnregisteredHandlerError"> {
+    readonly busKind: "command" | "query";
+    readonly messageType: string;
+    constructor(options: UnregisteredHandlerErrorOptions);
+}
 /**
  * Thrown at the end of a `UnitOfWork.run` when an aggregate that was
  * loaded into the identity map during the operation carries unflushed
@@ -231,6 +282,36 @@ declare class DuplicateAggregateError extends InfrastructureError<"DuplicateAggr
     readonly aggregateId: string;
     constructor(options: DuplicateAggregateErrorOptions);
 }
+/**
+ * Thrown on snapshot restore (`restoreFromSnapshot`,
+ * `restoreFromSnapshotWithEvents`) when the stored snapshot carries a
+ * different schema version than the aggregate's declared
+ * `snapshotSchemaVersion` and no `migrateSnapshotState` override handles
+ * the upgrade. Without the check, a snapshot written against an older
+ * `TSnapshotState` shape would surface as an undefined-field crash on
+ * the first method call after a much later restore.
+ *
+ * `InfrastructureError` because the storage boundary served outdated
+ * data; the schema evolving past stored snapshots is an expected
+ * lifecycle event, not a programming bug. NOT retryable: the recovery
+ * is a code path, not a repeat. Either override `migrateSnapshotState`
+ * on the aggregate (upgrade old shapes in place), or catch this error
+ * in the repository, discard the snapshot, and refold from the full
+ * event stream / reload from the source of truth.
+ */
+interface SnapshotSchemaMismatchErrorOptions {
+    readonly aggregateType: string;
+    readonly aggregateId: string;
+    readonly expectedSchemaVersion: number;
+    readonly actualSchemaVersion: number;
+}
+declare class SnapshotSchemaMismatchError extends InfrastructureError<"SnapshotSchemaMismatchError"> {
+    readonly aggregateType: string;
+    readonly aggregateId: string;
+    readonly expectedSchemaVersion: number;
+    readonly actualSchemaVersion: number;
+    constructor(options: SnapshotSchemaMismatchErrorOptions);
+}
 /**
  * Thrown by `IRepository.save()` when the aggregate's expected version
  * does not match the version currently persisted: i.e. another writer
@@ -354,61 +435,6 @@ declare function withEventIdFactory<T>(factory: EventIdFactory, fn: () => T): T;
  * Intended for use in test `afterEach` hooks.
  */
 declare function resetEventIdFactory(): void;
-/**
- * Clock function producing a fresh `Date` for each call. The library
- * defaults to `() => new Date()`; override globally via `setClockFactory`
- * for deterministic event-sourcing tests, time-travel debugging, or any
- * scenario where `occurredAt` must be reproducible.
- */
-type ClockFactory = () => Date;
-/**
- * Replaces the global clock factory used by `createDomainEvent`. Call once
- * during application bootstrap (or per-test in deterministic test suites):
- *
- * ```ts
- * import { setClockFactory } from "@shirudo/ddd-kit";
- *
- * setClockFactory(() => new Date("2026-01-01T00:00:00Z"));
- * ```
- *
- * The per-call `options.occurredAt` override always wins over this
- * factory. Symmetric to `setEventIdFactory`.
- *
- * Module-scoped: see {@link setEventIdFactory} for the global-state
- * caveats. For test isolation prefer {@link withClockFactory}; for
- * multi-tenant request isolation prefer the per-call
- * `options.occurredAt`.
- */
-declare function setClockFactory(factory: ClockFactory): void;
-/**
- * Scoped variant of {@link setClockFactory}: installs `factory`, runs
- * `fn`, then restores the previous factory in a `finally` block.
- * Synchronous-only, with the same constraints (and same runtime thenable
- * guard) as {@link withEventIdFactory}.
- *
- * **When to prefer the per-call `options.occurredAt` instead.** Same
- * trade-off as {@link withEventIdFactory}: passing `{ occurredAt }`
- * to `createDomainEvent` is the strongest isolation for single-event
- * cases. The scoped helper is for events constructed deep inside
- * domain methods where threading an explicit timestamp is awkward.
- *
- * @example
- * ```ts
- * it("stamps events with a fixed clock", () => {
- *   const fixed = new Date("2026-01-01T00:00:00Z");
- *   withClockFactory(() => fixed, () => {
- *     const e = createDomainEvent("X", { v: 1 });
- *     expect(e.occurredAt).toEqual(fixed);
- *   });
- * });
- * ```
- */
-declare function withClockFactory<T>(factory: ClockFactory, fn: () => T): T;
-/**
- * Restores the default clock factory (`() => new Date()`).
- * Intended for use in test `afterEach` hooks.
- */
-declare function resetClockFactory(): void;
 /**
  * Metadata associated with a domain event for traceability and correlation.
  * Used in event-driven architectures to track event flow across services.
@@ -512,11 +538,16 @@ interface DomainEvent<T extends string, P = void> {
      * `CreateDomainEventOptions.aggregateVersion`; a pre-set value is
      * never overwritten.
      *
-     * Consumers use it for ordering ("apply projections up to aggregate
-     * version N"), idempotency watermarks, debugging, and integration
-     * logs. Optional at the type level: events created outside an
-     * aggregate (system/integration events) and events from older kit
-     * versions don't carry it.
+     * Consumers use it for cross-commit ordering and debugging. It is NOT
+     * a per-event idempotency key: all events of one commit share the
+     * stamp, so a position cursor keyed on it alone would silently skip
+     * every event after the first within a commit (e.g. after a crash
+     * between two same-version events). Dedup keys belong on `eventId`;
+     * as a watermark this value is per-commit only (advance it after
+     * processing ALL events of that version; see the outbox guide).
+     * Optional at the type level: events created outside an aggregate
+     * (system/integration events) and events from older kit versions
+     * don't carry it.
      */
     aggregateVersion?: number;
     /**
@@ -575,6 +606,14 @@ interface CreateDomainEventOptions {
  * Creates a domain event with default values.
  * Sets occurredAt to current date and version to 1 if not provided.
  *
+ * **Input ownership.** The event is deeply frozen, and `payload` and
+ * `metadata` are deep-cloned first, so the caller's own objects are never
+ * frozen in place and later mutation of them does not bleed into the
+ * event (same contract as `vo()`). The clone follows the plain-data event
+ * contract via `structuredClone`: functions, Promise, and WeakMap/WeakSet
+ * values throw a `TypeError`; symbol-keyed properties are not carried
+ * over.
+ *
  * **For aggregate-internal events, prefer `this.recordEvent(...)` on
  * `AggregateRoot` / `EventSourcedAggregate`.** That helper auto-injects
  * `aggregateId` (from `this.id`) and `aggregateType` (from the
@@ -646,15 +685,25 @@ interface AggregateSnapshot<TState> {
     /**
      * The state of the aggregate at the time of the snapshot.
      */
-    state: TState;
+    readonly state: TState;
     /**
      * The version of the aggregate when the snapshot was taken.
      */
-    version: Version;
+    readonly version: Version;
     /**
      * Timestamp when the snapshot was created.
      */
-    snapshotAt: Date;
+    readonly snapshotAt: Date;
+    /**
+     * Schema version of the SHAPE of `state` (the aggregate's declared
+     * `snapshotSchemaVersion`), stamped by `createSnapshot`. Distinct from
+     * {@link version}, which counts mutations: this field says "which
+     * shape does the stored state have", so a restore can detect a
+     * snapshot written against an older `TSnapshotState` and migrate or
+     * discard it instead of crashing later. Optional: absent on snapshots
+     * written by older kit versions, which restore treats as schema `1`.
+     */
+    readonly schemaVersion?: number;
 }
 /**
  * Public contract every Aggregate Root satisfies. Implemented by
@@ -719,4 +768,4 @@ declare function sameVersion<TId extends Id<string>>(a: {
     version: Version;
 }): boolean;
 
-export { type AnyDomainEvent as A, type CreateDomainEventOptions as C, DomainError as D, type EventIdFactory as E, type IAggregateRoot as I, MissingHandlerError as M, UnenrolledChangesError as U, type Version as V, type Id as a, type AggregateSnapshot as b, type IEventSourcedAggregate as c, InfrastructureError as d, setEventIdFactory as e, type ClockFactory as f, setClockFactory as g, withClockFactory as h, resetClockFactory as i, type EventMetadata as j, type DomainEvent as k, createDomainEvent as l, copyMetadata as m, mergeMetadata as n, EventHarvestError as o, AggregateDeletedError as p, type AggregateNotFoundErrorOptions as q, resetEventIdFactory as r, sameVersion as s, AggregateNotFoundError as t, type DuplicateAggregateErrorOptions as u, DuplicateAggregateError as v, withEventIdFactory as w, type ConcurrencyConflictErrorOptions as x, ConcurrencyConflictError as y, type IdGenerator as z };
+export { type AnyDomainEvent as A, type CreateDomainEventOptions as C, DomainError as D, type EventIdFactory as E, type IAggregateRoot as I, MissingHandlerError as M, SnapshotSchemaMismatchError as S, UnenrolledChangesError as U, type Version as V, type Id as a, type AggregateSnapshot as b, type IEventSourcedAggregate as c, InfrastructureError as d, copyMetadata as e, createDomainEvent as f, type DomainEvent as g, type EventMetadata as h, setEventIdFactory as i, AggregateDeletedError as j, AggregateNotFoundError as k, type AggregateNotFoundErrorOptions as l, mergeMetadata as m, ConcurrencyConflictError as n, type ConcurrencyConflictErrorOptions as o, DuplicateAggregateError as p, type DuplicateAggregateErrorOptions as q, resetEventIdFactory as r, sameVersion as s, EventHarvestError as t, type SnapshotSchemaMismatchErrorOptions as u, UnregisteredHandlerError as v, withEventIdFactory as w, type UnregisteredHandlerErrorOptions as x, UnreplayableAggregateError as y, type IdGenerator as z };