@shirudo/ddd-kit 3.0.0-rc.13 → 3.0.0-rc.15

package/dist/chunks/snapshot-store.d.ts

@@ -193,15 +193,16 @@ type ClockFactory = () => Date;
 /**
  * Factory function producing a fresh, unique event identifier for each call.
  *
- * The library ships a default that uses Web Crypto `crypto.randomUUID()`
- * (works on Node 19+, modern browsers in secure contexts, Deno, Bun,
- * Cloudflare Workers, Vercel Edge, and any runtime that implements Web
- * Crypto). Note that `crypto.randomUUID()` returns **UUID v4** (purely
- * random); for production event stores prefer a **time-ordered** id
- * format (UUID v7 / ULID / KSUID) so B-tree indexes on the eventId
- * column stay clustered and `ORDER BY eventId` matches creation order.
- * Supply one to {@link createDomainEventFactory} to use UUID v7, ULID,
- * KSUID, or another collision-safe format without mutating module state.
+ * The library ships a default that creates a time-ordered **UUID v7** from
+ * Web Crypto random bits (works on Node 19+, modern browsers in secure
+ * contexts, Deno, Bun, Cloudflare Workers, Vercel Edge, and any runtime that
+ * implements Web Crypto). A B-tree index on the eventId column stays
+ * clustered. The id is no ordering authority: ids from several processes
+ * interleave within one millisecond, and clock skew can invert them. Order
+ * events by aggregate version or stream position. Supply another generator
+ * to {@link createDomainEventFactory} to
+ * use ULID, KSUID, or another collision-safe format without mutating module
+ * state.
  */
 type EventIdFactory = () => string;
 /**
@@ -266,8 +267,8 @@ interface DomainEvent<T extends string, P = void> {
   /**
    * Unique identifier for this specific event instance. Used by idempotent
    * consumers, outbox dispatch tracking, and as the target of
-   * `metadata.causationId`. Convenience constructors default to
-   * `crypto.randomUUID()`; strict construction requires the caller to supply it.
+   * `metadata.causationId`. Convenience constructors default to a UUID v7;
+   * strict construction requires the caller to supply it.
    */
   readonly eventId: string;
   /**
@@ -291,7 +292,7 @@ interface DomainEvent<T extends string, P = void> {
    */
   readonly payload: P;
   /**
-   * Timestamp when the accepted fact was recorded by the application shell.
+   * Timestamp when the application shell stamped the accepted fact.
    * Put business-relevant time in the payload under a domain name.
    */
   readonly occurredAt: Date;
@@ -342,10 +343,11 @@ type AnyUnstampedDomainEvent = UnstampedDomainEvent<string, unknown>;
 type UnstampedDomainEventOf<TEvent extends AnyDomainEvent> = TEvent extends DomainEvent<infer TType, infer TPayload> ? UnstampedDomainEvent<TType, TPayload> : never;
 /** An aggregate may hold unstamped decisions and already stamped events together. */
 type PendingDomainEvent<TEvent extends AnyDomainEvent> = TEvent | UnstampedDomainEventOf<TEvent>;
-/** Producer-owned options for an unstamped event. */
-interface CreateUnstampedDomainEventOptions {
-  readonly aggregateId?: string;
-  readonly aggregateType?: string;
+/**
+ * Options of `createEvent` in an aggregate. The aggregate fills its own
+ * identity, so only the schema version of the payload is left.
+ */
+interface CreateEventOptions {
   readonly schemaVersion?: number;
 }
 /**
@@ -355,7 +357,7 @@ interface CreateDomainEventOptions {
   /**
    * Override for the auto-generated `eventId`. Pass an existing id (for
    * replay, tests, or deterministic event sourcing) instead of letting the
-   * factory call `crypto.randomUUID()`.
+   * factory generate a UUID v7.
    */
   eventId?: string;
   /**
@@ -402,7 +404,7 @@ interface CreateDomainEventStampOptions {
 }
 /** Dependencies captured by one immutable domain-event factory instance. */
 interface DomainEventFactoryOptions {
-  /** Event-id generator. Defaults to Web Crypto `crypto.randomUUID()`. */
+  /** Event-id generator. Defaults to a UUID v7 from Web Crypto random bits. */
   readonly eventIdFactory?: EventIdFactory;
   /** Event-recording clock. Defaults to `() => new Date()`. */
   readonly clock?: ClockFactory;
@@ -442,7 +444,7 @@ interface DomainEventFactory {
  * The supplied functions are read once and captured by value. The returned
  * object is frozen, so another request, test, or library cannot replace its
  * policy. Its {@link DomainEventFactory.createStamp} method is the
- * application-shell bridge that records an accepted aggregate decision.
+ * application-shell bridge that stamps an accepted aggregate decision.
  * Passing the factory through `AggregateConfig`
  * enables the explicitly named convenience methods, whose defaults read time
  * and randomness.
@@ -453,8 +455,7 @@ interface DomainEventFactory {
  *   eventIdFactory: () => uuidv7(),
  *   clock: () => new Date(),
  * });
- * order.confirm();
- * stampPendingEvents(order, domainEvents);
+ * const uow = new UnitOfWork({ ...deps, eventStampFactory: domainEvents });
  * ```
  */
 declare function createDomainEventFactory(options?: DomainEventFactoryOptions): DomainEventFactory;
@@ -937,7 +938,7 @@ type Id<Tag extends string> = string & {
  * The kit makes no attempt to dedupe or detect collisions: a collision
  * silently overwrites earlier rows (under unique-key constraints) or
  * silently aliases two different entities (without them). Safe choices:
- * `crypto.randomUUID()` (UUIDv4, the default for events), ULID, UUIDv7,
+ * UUIDv7 (the default for events), `crypto.randomUUID()` (UUIDv4), ULID,
  * KSUID: all collision-resistant by design. Unsafe choices: `Date.now()`
  * alone (duplicates within the same millisecond), a process-local
  * counter without persistence (resets to 1 on restart, collides with
@@ -1396,6 +1397,43 @@ interface TransactionScope<TCtx> {
   transactional<T>(fn: (ctx: TCtx) => Promise<T>, options?: TransactionalOptions): Promise<T>;
 }
 //#endregion
+//#region src/application/unit-of-work/stamp-pending-events.d.ts
+/** Minimal shell role accepted by {@link stampPendingEvents}. */
+type DomainEventStampFactory = Pick<DomainEventFactory, "createStamp">;
+/** Per-decision stamp provider for metadata that depends on the event. */
+type DomainEventStampProvider<TEvent extends AnyDomainEvent> = (event: UnstampedDomainEventOf<TEvent>, index: number) => DomainEventStamp;
+/**
+ * Stamp options that every decision of one stamping shares: a stamp time
+ * and metadata such as the correlation id of the request. An `eventId` is per
+ * fact, so the factory creates it for each decision.
+ */
+type SharedDomainEventStampOptions = Omit<CreateDomainEventStampOptions, "eventId">;
+/**
+ * Stamps every still-unstamped event accepted by an aggregate.
+ *
+ * The commit stamps every still-unstamped event when it registers the
+ * aggregate, so a use case does not need this function. Call it first when
+ * the metadata depends on the concrete decision, for an import, or for a test
+ * that needs fixed ids. The commit keeps the stamps that this function set.
+ *
+ * The function is a command that also returns the stamped batch, a
+ * deliberate exception to command-query separation: the caller hands the
+ * batch on to persistence and needs no second read of `pendingEvents`.
+ *
+ * Stamping is atomic with respect to the aggregate's pending list: if stamp
+ * creation or validation fails, every decision remains unstamped. A
+ * successful second call returns the same event objects and does not read the
+ * factory again, so an instance that a retried attempt registers again keeps
+ * its event identities.
+ *
+ * Pass a `DomainEventFactory` (only its `createStamp` role is required) for one
+ * uniform stamping policy. Add `stampOptions` for metadata that every
+ * decision of the batch shares, such as the correlation id of the request.
+ * Pass a callback instead when metadata depends on the concrete decision.
+ */
+declare function stampPendingEvents<TId extends Id<string>, TEvent extends AnyDomainEvent>(aggregate: Aggregate<TId, TEvent>, factory: DomainEventStampFactory, stampOptions?: SharedDomainEventStampOptions): ReadonlyArray<TEvent>;
+declare function stampPendingEvents<TId extends Id<string>, TEvent extends AnyDomainEvent>(aggregate: Aggregate<TId, TEvent>, createStamp: DomainEventStampProvider<TEvent>): ReadonlyArray<TEvent>;
+//#endregion
 //#region src/application/cqrs/handler.d.ts
 /** Dependencies for {@link withCommit}. */
 interface WithCommitDeps<Evt extends AnyDomainEvent, TCtx> {
@@ -1459,6 +1497,19 @@ interface WithCommitDeps<Evt extends AnyDomainEvent, TCtx> {
    * unless the scope honors the signal.
    */
   signal?: AbortSignal;
+  /**
+   * Stamps every pending event that is still unstamped when its aggregate is
+   * registered: the event id, the stamp time, and the metadata. Defaults to
+   * `createDomainEventFactory()`, a UUID v7 from Web Crypto random bits and
+   * the system clock. An event that is already stamped, for example by an
+   * explicit `stampPendingEvents` call, keeps its stamp.
+   */
+  eventStampFactory?: DomainEventStampFactory;
+  /**
+   * Stamp options that every event stamped in this commit shares, for
+   * example the correlation id of the request.
+   */
+  stampOptions?: SharedDomainEventStampOptions;
 }
 declare const aggregateCommitTokenBrand: unique symbol;
 /**
@@ -2667,6 +2718,10 @@ interface EventStore<Evt extends AnyDomainEvent> extends EventStreamReader<Evt>
    *     proves the duplicate/gap rejection. The repository then calls
    *     `replayHistory`, whose replay guard rejects any event carrying an
    *     aggregate type or id that contradicts this stream key.
+   *  7. **Stamped events only:** reject an event without an `eventId` with
+   *     a `TypeError`, before any write. A direct `withCommit` callback can
+   *     append before its registration stamps the events; this check makes
+   *     that mistake fail instead of storing ids that the outbox never sees.
    *
    * An empty `events` array is a no-op; implementations resolve without
    * touching the store (an ES repository skips `append` for aggregates
@@ -2825,5 +2880,5 @@ interface SnapshotStore<TState = unknown> {
   delete(identity: AggregateIdentity): Promise<void>;
 }
 //#endregion
-export { Version as $, IdempotentCommitRequest as A, DomainEventFactoryOptions as At, CommitRegistrationOptions as B, createStampedDomainEvent as Bt, IdempotencyClaim as C, AnyUnstampedDomainEvent as Ct, IdempotencyReconciliation as D, CreateUnstampedDomainEventOptions as Dt, IdempotencyOperationErrorContext as E, CreateStampedDomainEventOptions as Et, DeadLetterDeadline as F, UnstampedDomainEvent as Ft, TransactionalOptions as G, Command as Gt, WithCommitWorkResult as H, mergeMetadata as Ht, DeadlineStore as I, UnstampedDomainEventOf as It, OnceOptions as J, JsonObject as Jt, EventBus as K, CommandHandler as Kt, DueDeadline as L, copyMetadata as Lt, IdempotentExecution as M, EventIdFactory as Mt, WithIdempotentCommitDeps as N, EventMetadata as Nt, IdempotencyReconciliationDecision as O, DomainEvent as Ot, withIdempotentCommit as P, PendingDomainEvent as Pt, ReplayableAggregate as Q, AggregateCommitToken as R, createDomainEvent as Rt, isPositionAfter as S, AnyDomainEvent as St, IdempotencyLease as T, CreateDomainEventStampOptions as Tt, withCommit as U, ClockFactory as Ut, WithCommitDeps as V, defaultDomainEventFactory as Vt, TransactionScope as W, AggregateIdentity as Wt, Aggregate as X, JsonValue as Xt, PublishOptions as Y, JsonPrimitive as Yt, AggregateSnapshot as Z, IdentityMap as _, ExecutionContext as _t, EventStoreAppendOptions as a, CommandMessageContent as at, ProjectionCheckpointStore as b, EventCommitCandidate as bt, StreamReadResult as c, CommandOutboxMapper as ct, RepositoryTracking as d, routeEventsToCommandOutbox as dt, sameVersion as et, UnitOfWorkIdentityMap as f, DeadLetterRecord as ft, AggregateClass as g, OutboxWriter as gt, PersistenceModel as h, OutboxRecord as ht, EventStore as i, CommandCommitOriginCandidate as it, IdempotentCommitResult as j, DomainEventStamp as jt, IdempotencyStore as k, DomainEventFactory as kt, AggregatePersistenceWrite as l, CommandOutboxWriter as lt, PersistenceLifecycle as m, Outbox as mt, ReplayableStreamPages as n, Id as nt, EventStreamReader as o, CommandMessageRelationships as ot, PersistenceChanges as p, DispatchTrackingOutbox as pt, EventHandler as q, PublishedCommand as qt, reconstituteAggregateFromStreamPages as r, IdGenerator as rt, ReadStreamOptions as s, CommandOutboxCommitCandidate as st, SnapshotStore as t, toVersion as tt, AggregateWriteIntent as u, DurableCommandMessage as ut, Projection as v, CommitPosition as vt, IdempotencyClaimHandle as w, CreateDomainEventOptions as wt, ProjectionPosition as x, EventCommitCandidatePosition as xt, ProjectionCheckpoint as y, CommittedDomainEvent as yt, CommitRegistration as z, createDomainEventFactory as zt };
+export { PublishOptions as $, JsonPrimitive as $t, IdempotentCommitRequest as A, CreateEventOptions as At, CommitRegistrationOptions as B, UnstampedDomainEventOf as Bt, IdempotencyClaim as C, CommittedDomainEvent as Ct, IdempotencyReconciliation as D, AnyUnstampedDomainEvent as Dt, IdempotencyOperationErrorContext as E, AnyDomainEvent as Et, DeadLetterDeadline as F, DomainEventStamp as Ft, DomainEventStampProvider as G, defaultDomainEventFactory as Gt, WithCommitWorkResult as H, createDomainEvent as Ht, DeadlineStore as I, EventIdFactory as It, TransactionScope as J, AggregateIdentity as Jt, SharedDomainEventStampOptions as K, mergeMetadata as Kt, DueDeadline as L, EventMetadata as Lt, IdempotentExecution as M, DomainEvent as Mt, WithIdempotentCommitDeps as N, DomainEventFactory as Nt, IdempotencyReconciliationDecision as O, CreateDomainEventOptions as Ot, withIdempotentCommit as P, DomainEventFactoryOptions as Pt, OnceOptions as Q, JsonObject as Qt, AggregateCommitToken as R, PendingDomainEvent as Rt, isPositionAfter as S, CommitPosition as St, IdempotencyLease as T, EventCommitCandidatePosition as Tt, withCommit as U, createDomainEventFactory as Ut, WithCommitDeps as V, copyMetadata as Vt, DomainEventStampFactory as W, createStampedDomainEvent as Wt, EventBus as X, CommandHandler as Xt, TransactionalOptions as Y, Command as Yt, EventHandler as Z, PublishedCommand as Zt, IdentityMap as _, DispatchTrackingOutbox as _t, EventStoreAppendOptions as a, toVersion as at, ProjectionCheckpointStore as b, OutboxWriter as bt, StreamReadResult as c, CommandCommitOriginCandidate as ct, RepositoryTracking as d, CommandOutboxCommitCandidate as dt, JsonValue as en, Aggregate as et, UnitOfWorkIdentityMap as f, CommandOutboxMapper as ft, AggregateClass as g, DeadLetterRecord as gt, PersistenceModel as h, routeEventsToCommandOutbox as ht, EventStore as i, sameVersion as it, IdempotentCommitResult as j, CreateStampedDomainEventOptions as jt, IdempotencyStore as k, CreateDomainEventStampOptions as kt, AggregatePersistenceWrite as l, CommandMessageContent as lt, PersistenceLifecycle as m, DurableCommandMessage as mt, ReplayableStreamPages as n, ReplayableAggregate as nt, EventStreamReader as o, Id as ot, PersistenceChanges as p, CommandOutboxWriter as pt, stampPendingEvents as q, ClockFactory as qt, reconstituteAggregateFromStreamPages as r, Version as rt, ReadStreamOptions as s, IdGenerator as st, SnapshotStore as t, AggregateSnapshot as tt, AggregateWriteIntent as u, CommandMessageRelationships as ut, Projection as v, Outbox as vt, IdempotencyClaimHandle as w, EventCommitCandidate as wt, ProjectionPosition as x, ExecutionContext as xt, ProjectionCheckpoint as y, OutboxRecord as yt, CommitRegistration as z, UnstampedDomainEvent as zt };
 //# sourceMappingURL=snapshot-store.d.ts.map

package/dist/chunks/value-object.js

@@ -492,7 +492,7 @@ function comparePlainObjects(objA, objB, visited) {
 * path, so memoising the first path's result would be wrong. This is
 * inherently exponential for diamond-shaped sharing (a node reachable
 * via 2^n paths is cloned 2^n times); the walk aborts with a descriptive
-* error after {@link PATH_SENSITIVE_VISIT_BUDGET} node visits instead of
+* error after a fixed budget of node visits instead of
 * hanging the process.
 *
 * **Prototype-pollution safety.** `__proto__` and `constructor` keys