@shirudo/ddd-kit 3.0.0-rc.11 → 3.0.0-rc.12

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

@@ -464,6 +464,11 @@ declare function createDomainEventFactory(options?: DomainEventFactoryOptions):
  * with {@link createDomainEventFactory} for custom policy.
  */
 declare const defaultDomainEventFactory: DomainEventFactory;
+/**
+ * Creates an uncommitted domain event: the event that an aggregate method
+ * returns before the application shell records it. The payload and the
+ * metadata follow the input ownership rule of {@link createDomainEvent}.
+ */
 declare function createUncommittedDomainEvent<T extends string>(type: T, payload?: undefined, options?: CreateUncommittedDomainEventOptions): UncommittedDomainEvent<T, void>;
 declare function createUncommittedDomainEvent<T extends string, P>(type: T, payload: P, options?: CreateUncommittedDomainEventOptions): UncommittedDomainEvent<T, P>;
 /**
@@ -474,6 +479,56 @@ declare function createUncommittedDomainEvent<T extends string, P>(type: T, payl
  * identity, recording time, and trace metadata.
  */
 declare function recordDomainEvent<T extends string, P>(event: UncommittedDomainEvent<T, P>, stamp: DomainEventStamp): DomainEvent<T, P>;
+/**
+ * Creates a domain event with default values.
+ * Sets occurredAt to current date and schemaVersion 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 event data rule checks the data before the
+ * copy and the copy after it. So the copy loses no data without an error,
+ * and no getter of the data runs. The in-memory event store applies the
+ * same rule on append. The checks catch accidents, not a hostile `Proxy`: a
+ * trap that changes the data during the check can hide a loss. An error
+ * that a `Proxy` trap throws passes unchanged, so a coded error of the
+ * caller keeps its code. These values throw a `TypeError`: a function, a
+ * Promise, a WeakMap or a WeakSet, an `Error`, a host object such as a
+ * `File`, a binary buffer, a `RegExp`, and shared memory. The same holds
+ * for what the copy would lose or change: a class instance, an accessor, an
+ * enumerable symbol-keyed property, a non-enumerable data property, and an
+ * expando on a built-in. A non-enumerable symbol key is metadata by
+ * convention, and the event does not get it. Map a value object to plain
+ * data before it goes into an event. `toJSON()` of a `ValueObject` is
+ * shallow, so map a nested value object too.
+ *
+ * **For aggregate-internal events, prefer `this.createEvent(...)` on
+ * `StateStoredAggregate` / `EventSourcedAggregate`.** That helper auto-injects
+ * `aggregateId` (from `this.id`) and `aggregateType` (from the
+ * aggregate's declared `aggregateType` property), which downstream
+ * consumers (outbox dispatchers, projection handlers, audit logs)
+ * route by. The commit boundary validates that both fields are present
+ * and throws if they are missing, so a direct `createDomainEvent(...)`
+ * call inside an aggregate that forgets the options is caught at
+ * runtime. Record pending decisions in the application
+ * shell before repository persistence or outbox harvest.
+ *
+ * Use `createDomainEvent(...)` directly for events that don't belong to
+ * an aggregate: system events, integration events, configuration events,
+ * test fixtures. For those, set `aggregateId` / `aggregateType` in
+ * `options` if downstream consumers expect routing metadata.
+ *
+ * @param type - The event type
+ * @param payload - The event payload
+ * @param options - Optional event configuration (including `aggregateId`
+ *   and `aggregateType` for routing)
+ * @returns A domain event
+ *
+ * @example
+ * ```typescript
+ * const event = createDomainEvent("OrderCreated", { orderId: "123" });
+ * ```
+ */
 declare function createDomainEvent<T extends string>(type: T, payload?: undefined, options?: CreateDomainEventOptions): DomainEvent<T, void>;
 declare function createDomainEvent<T extends string, P>(type: T, payload: P, options?: CreateDomainEventOptions): DomainEvent<T, P>;
 /**

package/dist/index.d.ts

@@ -3589,7 +3589,9 @@ declare function deepEqual(a: unknown, b: unknown): boolean;
  * `DataCloneError`. An Error, a Promise, a WeakMap, or a WeakSet cannot be
  * detached at all. A SharedArrayBuffer and a view over one keep sharing
  * their memory. A Proxy fails in the walk or in the clone; a failure in
- * the clone is rethrown as a `TypeError` with the cause.
+ * the clone is rethrown as a `TypeError` with the cause. An error that a
+ * Proxy trap throws in the walk passes unchanged, so a coded error of the
+ * caller keeps its code.
  *
  * The walk reads the graph through property descriptors and walks a Map
  * or a Set with the built-in iteration, so no accessor and no own iterator
@@ -3597,17 +3599,22 @@ declare function deepEqual(a: unknown, b: unknown): boolean;
  * change the graph, and an accessor that a trap adds runs during the
  * clone. A second walk checks the clone, so a value that a trap swapped in
  * and the content of a built-in whose prototype was replaced are rejected
- * too. The walks also count the data properties of records and arrays. A
- * copy with another count throws, because a built-in whose prototype was
- * replaced loses its own properties in the copy. `subject` names the state
- * in the messages.
+ * too. A trap that changes the graph after the first walk can still hide a
+ * value that the copy drops: the walks catch accidents, not a hostile
+ * Proxy. The second walk also follows the steps of the first walk: the kind
+ * of each object and the key of each data property, in walk order. A copy
+ * that differs throws, because a built-in whose prototype was replaced is
+ * a built-in again in the copy and loses its own properties. `subject`
+ * names the state in the messages.
  *
  * Plain objects (from any realm), arrays, Dates, Maps, Sets, bigints, and
  * typed arrays pass. A RegExp passes: pattern and flags survive the clone,
  * and `lastIndex` restores as 0. The scan state of a global or sticky
- * pattern is not domain data. A non-enumerable property on a built-in
- * passes: it is the built-in's own machinery (`lastIndex`), not data. A
- * non-enumerable symbol key passes anywhere: it is metadata by convention.
+ * pattern is not domain data. On a built-in, the mutator shadows of a deep
+ * freeze, the `lastIndex` of a RegExp, and the `length` of a boxed String
+ * pass: they are machinery, not data. Every other non-enumerable property
+ * throws. A non-enumerable symbol key passes anywhere: it is metadata by
+ * convention.
  *
  * The concrete entity uses it for a detached read DTO of a plain-data
  * state. The snapshot model uses it for the captured DTO and the restored

package/dist/index.js

@@ -1,5 +1,5 @@
 import { $ as isDomainErrorLike, A as MissingHandlerError, B as SnapshotCorruptedError, C as InvalidEventStreamPageError, D as MisattributedEventError, E as KitWiringError, F as ProjectionOrderViolationError, G as UnmintedEventError, H as SnapshotVersionNotRestoredError, I as ProjectionReceiptViolationError, J as UnreplayableAggregateError, K as UnprojectableEventError, L as ReentrantEventRecordingError, M as PendingEventLimitExceededError, N as ProjectionGapError, O as MissingEntityIdError, P as ProjectionIdentityViolationError, Q as detachAggregateIdentity, R as ReplayRejectedError, S as InvalidCommandMessageError, T as InvalidVersionError, U as UnenrolledChangesError, V as SnapshotSchemaMismatchError, W as UnmanagedInstanceError, X as attributeConflictIntent, Y as assertNoHostileOwnProtoKey, Z as describeAggregateIdentity, _ as IdempotencyInFlightError, a as DirectStateMutationError, b as InMemoryCapacityExceededError, c as DuplicateEventIdError, d as EventHarvestError, et as isInfrastructureErrorLike, f as FoldReturnedNoStateError, g as IdempotencyCompletionWithoutClaimError, h as IdempotencyClaimLostError, i as ConcurrencyConflictError, j as PendingEventBatchMismatchError, k as MissingFoldError, l as DuplicateHandlerRegistrationError, m as HostileStateKeyError, n as AggregateNotFoundError, nt as rewriteErrorMessage, o as DomainError, p as ForeignEventError, q as UnregisteredHandlerError, r as CapabilityRegistryConflictError, s as DuplicateAggregateError, t as AggregateDeletedError, tt as isWiringErrorLike, u as ErrorMapperFailedError, v as IdempotencyKeyReuseError, w as InvalidIntegrationMessageError, x as InfrastructureError, y as IdempotencyReconciliationRequiredError, z as ReplayTargetMismatchError } from "./chunks/kit-errors.js";
-import { A as SnapshotTimeValidationError, B as voWithValidation, C as defaultDomainEventFactory, D as mintUncommittedDomainEvent, E as mergeMetadata, F as ValueObject, G as isBuiltInObject, H as deepOmit, I as deepFreeze, K as isIntrinsicConstructorPrototype, L as vo, M as detachState, N as hasCooperativeBrand, O as recordDomainEvent, P as stampCooperativeBrand, R as voEquals, S as createUncommittedDomainEvent, T as isUncommittedDomainEvent, U as deepEqual, V as deepEqualExcept, W as findPropertyDescriptor, _ as adoptUncommittedDomainEvent, a as isDispatchTrackingOutbox, b as createDomainEventFactory, c as runBoundedExecution, d as assertPositiveInteger, f as assertPositiveSafeInteger, g as adoptRecordedDomainEvent, h as waitRejectingOnAbort, i as assertPageWithinWindow, j as detachFreezableState, k as DomainEventValidationError, l as MAX_TIMER_DELAY_MS, m as abortReason, n as readStreamPages, o as DEFAULT_EXECUTION_TIMEOUT_MS, p as assertTimerDelay, q as isWeakMap, r as assertPageNotEmpty, s as ownerSignalOf, t as pinTargetVersion, u as assertNonNegativeSafeInteger, v as copyMetadata, w as isRecordedDomainEvent, x as createDomainEventFromFacts, y as createDomainEvent, z as voEqualsExcept } from "./chunks/read-stream-pages.js";
+import { A as SnapshotTimeValidationError, B as stampCooperativeBrand, C as defaultDomainEventFactory, D as mintUncommittedDomainEvent, E as mergeMetadata, F as vo, G as isBuiltInObject, H as deepOmit, I as voEquals, K as isIntrinsicConstructorPrototype, L as voEqualsExcept, M as detachState, N as ValueObject, O as recordDomainEvent, P as deepFreeze, R as voWithValidation, S as createUncommittedDomainEvent, T as isUncommittedDomainEvent, U as deepEqual, V as deepEqualExcept, W as findPropertyDescriptor, _ as adoptUncommittedDomainEvent, a as isDispatchTrackingOutbox, b as createDomainEventFactory, c as runBoundedExecution, d as assertPositiveInteger, f as assertPositiveSafeInteger, g as adoptRecordedDomainEvent, h as waitRejectingOnAbort, i as assertPageWithinWindow, j as detachFreezableState, k as DomainEventValidationError, l as MAX_TIMER_DELAY_MS, m as abortReason, n as readStreamPages, o as DEFAULT_EXECUTION_TIMEOUT_MS, p as assertTimerDelay, q as isWeakMap, r as assertPageNotEmpty, s as ownerSignalOf, t as pinTargetVersion, u as assertNonNegativeSafeInteger, v as copyMetadata, w as isRecordedDomainEvent, x as createDomainEventFromFacts, y as createDomainEvent, z as hasCooperativeBrand } from "./chunks/read-stream-pages.js";
 import { err, ok } from "@shirudo/result";
 import { ValidationError, someChainRetryable } from "@shirudo/base-error";
 

package/dist/testing.js

@@ -1,4 +1,4 @@
-import { I as deepFreeze, U as deepEqual, a as isDispatchTrackingOutbox, c as runBoundedExecution, f as assertPositiveSafeInteger, n as readStreamPages, w as isRecordedDomainEvent } from "./chunks/read-stream-pages.js";
+import { P as deepFreeze, U as deepEqual, a as isDispatchTrackingOutbox, c as runBoundedExecution, f as assertPositiveSafeInteger, n as readStreamPages, w as isRecordedDomainEvent } from "./chunks/read-stream-pages.js";
 
 //#region src/testing/contract-assertions.ts
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@shirudo/ddd-kit",
-	"version": "3.0.0-rc.11",
+	"version": "3.0.0-rc.12",
 	"packageManager": "pnpm@11.13.1",
 	"description": "Composable TypeScript toolkit for tactical DDD",
 	"type": "module",