@shirudo/ddd-kit 1.2.0 → 1.3.0

package/dist/index.js

@@ -1,5 +1,5 @@
 import { ok, err } from '@shirudo/result';
-import { BaseError, ValidationError } from '@shirudo/base-error';
+import { BaseError, someChainRetryable, ValidationError } from '@shirudo/base-error';
 
 var __defProp = Object.defineProperty;
 var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
@@ -944,7 +944,7 @@ var BaseAggregate = class extends Entity {
    * `changedKeys`/`hasChanges`. An override that skips `super` leaves
    * that baseline uncaptured: `changedKeys` permanently reports ALL
    * keys and `hasChanges` never returns `false`, so a partial-write
-   * repository silently degrades to full writes on every save — on top
+   * repository silently degrades to full writes on every save, on top
    * of the broken version sync.
    *
    * @param version - The version the row currently holds in the DB
@@ -1237,7 +1237,7 @@ var AggregateRoot = class extends BaseAggregate {
    * If you override this, call `super.markRestored(version)` FIRST:
    * skipping it leaves the baseline uncaptured, so `changedKeys`
    * permanently reports ALL keys and `hasChanges` never returns `false`
-   * — partial-write repositories silently degrade to full writes — on
+   * (partial-write repositories silently degrade to full writes), on
    * top of breaking version sync.
    */
   markRestored(version) {
@@ -1260,7 +1260,7 @@ var AggregateRoot = class extends BaseAggregate {
    * **How it works.** `setState()` replaces state immutably and the
    * state object is shallow-frozen, so unchanged top-level sub-objects
    * keep reference identity across mutations. The diff is therefore a
-   * shallow per-key `!==` against the baseline reference — O(top-level
+   * shallow per-key `!==` against the baseline reference: O(top-level
    * keys), no proxies, no deep diff. A key also counts as dirty when its
    * *presence* differs (added or removed, even with an `undefined`
    * value). Computed fresh on every access (a new `Set` each time), so
@@ -1273,12 +1273,12 @@ var AggregateRoot = class extends BaseAggregate {
    * class-instance `TState` mutated through its own methods defeats
    * tracking entirely (the reference never changes). A keyless `TState`
    * (primitive, bare `Date`) has no keys to report, so `changedKeys`
-   * stays empty for it — use {@link hasChanges}, whose reference
+   * stays empty for it; use {@link hasChanges}, whose reference
    * fallback covers keyless states. A deep-equal but newly-referenced
    * value reports a false POSITIVE (harmless extra write); under the
    * contract above there are no false negatives.
    *
-   * Granularity is per top-level key — table-granular, not row-granular:
+   * Granularity is per top-level key, table-granular, not row-granular:
    * a dirty collection key means "this child table changed", not which
    * rows. `EventSourcedAggregate` deliberately has no `changedKeys`;
    * its `pendingEvents` are the change record.
@@ -1293,16 +1293,16 @@ var AggregateRoot = class extends BaseAggregate {
    * Safe skip signal: `false` only when there is genuinely nothing to
    * persist or flush. `true` when the aggregate has never been
    * persisted, the version moved past `persistedVersion`, there are
-   * unflushed {@link pendingEvents}, any state key is dirty, or — for
+   * unflushed {@link pendingEvents}, any state key is dirty, or, for
    * keyless states the per-key diff cannot see (primitive `TState`,
-   * zero-own-key objects like a bare `Date`) — the state reference
+   * zero-own-key objects like a bare `Date`), the state reference
    * changed since the baseline.
    *
    * The version clause is deliberate: `setState({...state}, true)` with
    * identical per-key values yields empty {@link changedKeys} but a
    * bumped version. If a repository skipped `save()` on a state-only
    * check, `withCommit` would still call `markPersisted(version)` after
-   * commit, desyncing `persistedVersion` from the DB row — and the next
+   * commit, desyncing `persistedVersion` from the DB row; and the next
    * uncontended save would throw a false `ConcurrencyConflictError`.
    *
    * The pending-events clause covers the sanctioned decoupled
@@ -1447,6 +1447,28 @@ var MissingHandlerError = class extends BaseError {
     __name(this, "MissingHandlerError");
   }
 };
+var EventHarvestError = class extends BaseError {
+  constructor(message, eventType) {
+    super(message, void 0, { name: "EventHarvestError" });
+    this.eventType = eventType;
+  }
+  static {
+    __name(this, "EventHarvestError");
+  }
+};
+var UnenrolledChangesError = class extends BaseError {
+  constructor(aggregateId) {
+    super(
+      `Aggregate ${aggregateId} was loaded in this unit of work and has pending events, but was never enrolled (no save), so its events would be silently dropped. Call repository.save(aggregate), and ensure save() calls session.enrollSaved before the row write.`,
+      void 0,
+      { name: "UnenrolledChangesError" }
+    );
+    this.aggregateId = aggregateId;
+  }
+  static {
+    __name(this, "UnenrolledChangesError");
+  }
+};
 var AggregateDeletedError = class extends BaseError {
   constructor(aggregateId) {
     super(
@@ -1675,8 +1697,17 @@ var CommandBus = class {
   }
 };
 
+// src/utils/abort.ts
+function abortReason(signal, fallbackMessage) {
+  return signal.reason ?? new Error(fallbackMessage);
+}
+__name(abortReason, "abortReason");
+
 // src/app/handler.ts
 async function withCommit(deps, fn) {
+  if (deps.signal?.aborted) {
+    throw abortReason(deps.signal, "withCommit aborted before opening a transaction");
+  }
   const { result, aggregates, deleted, events } = await deps.scope.transactional(
     async (ctx) => {
       const fnResult = await fn(ctx);
@@ -1690,8 +1721,9 @@ async function withCommit(deps, fn) {
             });
           }
           if (event.aggregateVersion > agg.version) {
-            throw new Error(
-              `withCommit: event "${event.type}" carries a pre-set aggregateVersion (${event.aggregateVersion}) AHEAD of its aggregate's commit version (${agg.version}). A stale-or-copied pre-set would advance consumer idempotency watermarks past real history; remove the manual aggregateVersion or correct it.`
+            throw new EventHarvestError(
+              `withCommit: event "${event.type}" carries a pre-set aggregateVersion (${event.aggregateVersion}) AHEAD of its aggregate's commit version (${agg.version}). A stale-or-copied pre-set would advance consumer idempotency watermarks past real history; remove the manual aggregateVersion or correct it.`,
+              event.type
             );
           }
           return event;
@@ -1702,10 +1734,11 @@ async function withCommit(deps, fn) {
         if (!event.aggregateId) missing.push("aggregateId");
         if (!event.aggregateType) missing.push("aggregateType");
         if (missing.length > 0) {
-          throw new Error(
+          throw new EventHarvestError(
             `withCommit: event "${event.type}" is missing ${missing.join(
               " and "
-            )}. Use this.recordEvent(type, payload) inside aggregate methods instead of createDomainEvent(...); recordEvent auto-injects aggregateId and aggregateType. Outbox dispatchers and projection handlers rely on these fields for routing.`
+            )}. Use this.recordEvent(type, payload) inside aggregate methods instead of createDomainEvent(...); recordEvent auto-injects aggregateId and aggregateType. Outbox dispatchers and projection handlers rely on these fields for routing.`,
+            event.type
           );
         }
       }
@@ -1718,7 +1751,8 @@ async function withCommit(deps, fn) {
         deleted: new Set(fnResult.deleted ?? []),
         events: harvested
       };
-    }
+    },
+    { signal: deps.signal }
   );
   for (const agg of aggregates) {
     try {
@@ -1751,6 +1785,10 @@ var IdentityMap = class {
   }
   _stores = /* @__PURE__ */ new Map();
   _deleted = /* @__PURE__ */ new Map();
+  // pendingEvents length captured when an instance was first registered
+  // (load time), so the unit of work can tell events RECORDED AFTER load
+  // apart from a "dirty" reconstitution that already carried events.
+  _pendingAtRegistration = /* @__PURE__ */ new WeakMap();
   /** The cached instance for type+id, or `undefined` (also after {@link delete}). */
   get(type, id) {
     return this._stores.get(type)?.get(id);
@@ -1762,7 +1800,7 @@ var IdentityMap = class {
   /**
    * Whether type+id was {@link delete}d in this unit of work. The
    * read path checks this BEFORE hydrating and returns `null`, so
-   * "deleted in this operation" reads uniformly as not-found —
+   * "deleted in this operation" reads uniformly as not-found,
    * regardless of whether the repository's physical delete already
    * removed the row or is deferred within the transaction. Without
    * the check, a read-only probe of a deleted aggregate would crash
@@ -1801,6 +1839,34 @@ var IdentityMap = class {
       );
     }
     store.set(id, aggregate);
+    if (aggregate !== null && typeof aggregate === "object" && !this._pendingAtRegistration.has(aggregate)) {
+      const pending = pendingEventsOf(aggregate);
+      if (pending) {
+        this._pendingAtRegistration.set(aggregate, pending.length);
+      }
+    }
+  }
+  /**
+   * Registered instances that have recorded MORE pending events than they
+   * carried when first registered (loaded). Used by the unit of work's
+   * end-of-run guard: an aggregate that gained events after load but was
+   * never enrolled would silently drop them. A read-only load, or a
+   * reconstitution that already carried events, shows no increase and is
+   * not reported.
+   */
+  instancesWithNewPendingEvents() {
+    const result = [];
+    for (const store of this._stores.values()) {
+      for (const instance of store.values()) {
+        const pending = pendingEventsOf(instance);
+        if (!pending) continue;
+        const atRegistration = this._pendingAtRegistration.get(instance) ?? 0;
+        if (pending.length > atRegistration) {
+          result.push(instance);
+        }
+      }
+    }
+    return result;
   }
   /**
    * Removes the entry for type+id and records a tombstone: subsequent
@@ -1824,6 +1890,12 @@ var IdentityMap = class {
     this._deleted.clear();
   }
 };
+function pendingEventsOf(value) {
+  if (value === null || typeof value !== "object") return void 0;
+  const pending = value.pendingEvents;
+  return Array.isArray(pending) ? pending : void 0;
+}
+__name(pendingEventsOf, "pendingEventsOf");
 
 // src/app/unit-of-work.ts
 var NestedUnitOfWorkError = class extends BaseError {
@@ -1857,7 +1929,7 @@ var CommitError = class extends InfrastructureError {
   }
   constructor(cause) {
     super(
-      "Unit of work failed after the work callback completed: the event harvest, outbox write, or transaction commit rejected. The transaction did not commit; see cause.",
+      "Unit of work failed after the work callback completed: the outbox write or the transaction commit rejected. The transaction did not commit; this failure may be transient, inspect the cause (e.g. someChainRetryable) before retrying.",
       cause,
       { name: "CommitError" }
     );
@@ -1890,7 +1962,10 @@ var UnitOfWork = class {
    * run the post-commit lifecycle (markPersisted, publish) for every
    * enrolled aggregate. Returns the callback's result.
    */
-  async run(work) {
+  async run(work, options) {
+    if (options?.signal?.aborted) {
+      throw abortReason(options.signal, "UnitOfWork.run aborted before opening a transaction");
+    }
     if (this._active) {
       throw new NestedUnitOfWorkError();
     }
@@ -1905,7 +1980,8 @@ var UnitOfWork = class {
           outbox: this.deps.outbox,
           bus: this.deps.bus,
           scope: this.deps.scope,
-          onPublishError: this.deps.onPublishError
+          onPublishError: this.deps.onPublishError,
+          signal: options?.signal
         },
         async (tx) => {
           session?.close();
@@ -1915,9 +1991,10 @@ var UnitOfWork = class {
           workThrew = false;
           workError = void 0;
           const repositories = this.buildRepositories(tx, s);
-          const context = makeContext(repositories, tx, s);
+          const context = makeContext(repositories, tx, s, options?.signal);
           try {
             const result = await work(context);
+            s.assertAllChangesEnrolled();
             workCompleted = true;
             const aggregates = s.enrolledAggregates;
             const deleted = s.deletedAggregates;
@@ -1938,6 +2015,10 @@ var UnitOfWork = class {
         throw new RollbackError(workError, error);
       }
       if (workCompleted) {
+        const harvestError = findHarvestErrorInChain(error);
+        if (harvestError) {
+          throw harvestError;
+        }
         throw new CommitError(error);
       }
       throw error;
@@ -1987,6 +2068,24 @@ var Session = class {
     );
     this._enrolled.add(aggregate);
   }
+  /**
+   * End-of-run safety net: a loaded aggregate (registered in the identity
+   * map via `getById`) that carries pending events but was never enrolled
+   * is almost certainly a forgotten `save()` / `enrollSaved`, whose events
+   * would otherwise be silently dropped. Convert that silent loss into a
+   * loud, rolling-back {@link UnenrolledChangesError}. Only sees loaded
+   * aggregates; a freshly created one that was never enrolled is invisible
+   * to the kit (the contract test suite remains the full mitigation).
+   */
+  assertAllChangesEnrolled() {
+    for (const instance of this._identityMap.instancesWithNewPendingEvents()) {
+      if (this._enrolled.has(instance) || this._deleted.has(instance)) {
+        continue;
+      }
+      const id = instance.id;
+      throw new UnenrolledChangesError(String(id));
+    }
+  }
   get enrolledAggregates() {
     return [...this._enrolled];
   }
@@ -2003,7 +2102,7 @@ var Session = class {
     }
   }
 };
-function makeContext(repositories, transaction, session) {
+function makeContext(repositories, transaction, session, signal) {
   return {
     get repositories() {
       session.assertOpen("context.repositories");
@@ -2013,10 +2112,32 @@ function makeContext(repositories, transaction, session) {
       session.assertOpen("context.rawTransaction");
       return transaction;
     },
-    session
+    session,
+    // The caller's own signal: exposed directly, not gated by
+    // assertOpen, so polling `aborted` after close stays harmless.
+    signal
   };
 }
 __name(makeContext, "makeContext");
+function findHarvestErrorInChain(error) {
+  const seen = /* @__PURE__ */ new Set();
+  let current = error;
+  while (current !== null && typeof current === "object" && !seen.has(current)) {
+    seen.add(current);
+    if (current instanceof EventHarvestError) {
+      return current;
+    }
+    let next;
+    try {
+      next = current.cause;
+    } catch {
+      return void 0;
+    }
+    current = next;
+  }
+  return void 0;
+}
+__name(findHarvestErrorInChain, "findHarvestErrorInChain");
 function causeChainContains(error, target) {
   if (target === void 0 || target === null) {
     return false;
@@ -2103,7 +2224,7 @@ var EventBusImpl = class {
   once(eventType, options) {
     return new Promise((resolve, reject) => {
       if (options?.signal?.aborted) {
-        reject(options.signal.reason ?? new Error("EventBus.once aborted"));
+        reject(abortReason(options.signal, "EventBus.once aborted"));
         return;
       }
       let timer;
@@ -2125,9 +2246,7 @@ var EventBusImpl = class {
       if (options?.signal) {
         abortListener = /* @__PURE__ */ __name(() => {
           cleanup();
-          reject(
-            options.signal.reason ?? new Error("EventBus.once aborted")
-          );
+          reject(abortReason(options.signal, "EventBus.once aborted"));
         }, "abortListener");
         options.signal.addEventListener("abort", abortListener);
       }
@@ -2207,6 +2326,101 @@ var InMemoryOutbox = class {
     for (const id of dispatchIds) this.pending.delete(id);
   }
 };
+var DEFAULT_MAX_ATTEMPTS = 3;
+var DEFAULT_BASE_DELAY_MS = 50;
+var DEFAULT_MAX_DELAY_MS = 1e3;
+function computeBackoffDelay(attempt, opts) {
+  const exponential = opts.baseDelayMs * 2 ** (attempt - 1);
+  const capped = Math.min(opts.maxDelayMs, exponential);
+  const jitter = 0.8 + opts.random() * 0.4;
+  return Math.max(0, Math.min(opts.maxDelayMs, Math.round(capped * jitter)));
+}
+__name(computeBackoffDelay, "computeBackoffDelay");
+function assertNonNegativeFinite(field, value) {
+  if (!Number.isFinite(value) || value < 0) {
+    throw new Error(
+      `RetryingTransactionScope: ${field} must be a non-negative finite number, got ${value}`
+    );
+  }
+}
+__name(assertNonNegativeFinite, "assertNonNegativeFinite");
+var ABORT_MESSAGE = "RetryingTransactionScope aborted";
+function defaultSleep(ms, signal) {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(abortReason(signal, ABORT_MESSAGE));
+      return;
+    }
+    let onAbort;
+    const timer = setTimeout(() => {
+      if (onAbort && signal) signal.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    if (signal) {
+      onAbort = /* @__PURE__ */ __name(() => {
+        clearTimeout(timer);
+        reject(abortReason(signal, ABORT_MESSAGE));
+      }, "onAbort");
+      signal.addEventListener("abort", onAbort, { once: true });
+    }
+  });
+}
+__name(defaultSleep, "defaultSleep");
+var RetryingTransactionScope = class {
+  constructor(inner, policy = {}) {
+    this.inner = inner;
+    this.maxAttempts = policy.maxAttempts ?? DEFAULT_MAX_ATTEMPTS;
+    this.baseDelayMs = policy.baseDelayMs ?? DEFAULT_BASE_DELAY_MS;
+    this.maxDelayMs = policy.maxDelayMs ?? DEFAULT_MAX_DELAY_MS;
+    if (!Number.isInteger(this.maxAttempts) || this.maxAttempts < 1) {
+      throw new Error(
+        `RetryingTransactionScope: maxAttempts must be an integer >= 1, got ${this.maxAttempts}`
+      );
+    }
+    assertNonNegativeFinite("baseDelayMs", this.baseDelayMs);
+    assertNonNegativeFinite("maxDelayMs", this.maxDelayMs);
+    this.isRetryable = policy.isRetryable ?? someChainRetryable;
+    this.sleep = policy.sleep ?? defaultSleep;
+    this.random = policy.random ?? Math.random;
+    this.onRetry = policy.onRetry;
+  }
+  static {
+    __name(this, "RetryingTransactionScope");
+  }
+  // Policy resolved and validated once at construction (a misconfigured
+  // policy is a wiring bug and fails fast, never at run time).
+  maxAttempts;
+  baseDelayMs;
+  maxDelayMs;
+  isRetryable;
+  sleep;
+  random;
+  onRetry;
+  async transactional(fn, options) {
+    const { maxAttempts, isRetryable, sleep } = this;
+    const signal = options?.signal;
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+      if (signal?.aborted) {
+        throw abortReason(signal, ABORT_MESSAGE);
+      }
+      try {
+        return await this.inner.transactional(fn, options);
+      } catch (error) {
+        if (attempt === maxAttempts || !isRetryable(error)) {
+          throw error;
+        }
+        const delayMs = computeBackoffDelay(attempt, {
+          baseDelayMs: this.baseDelayMs,
+          maxDelayMs: this.maxDelayMs,
+          random: this.random
+        });
+        this.onRetry?.({ attempt, error, delayMs });
+        await sleep(delayMs, signal);
+      }
+    }
+    throw new Error("RetryingTransactionScope: exhausted without result");
+  }
+};
 function voValidated(t, validate, message = "Validation failed") {
   const issues = new ValidationError(message);
   validate(issues, t);
@@ -2214,6 +2428,6 @@ function voValidated(t, validate, message = "Validation failed") {
 }
 __name(voValidated, "voValidated");
 
-export { AggregateDeletedError, AggregateNotFoundError, AggregateRoot, CommandBus, CommitError, ConcurrencyConflictError, DomainError, DuplicateAggregateError, Entity, EventBusImpl, EventSourcedAggregate, IdentityMap, InMemoryOutbox, InfrastructureError, MissingHandlerError, NestedUnitOfWorkError, QueryBus, RollbackError, TransactionClosedError, UnitOfWork, ValueObject, copyMetadata, createDomainEvent, createDomainEventWithMetadata, deepEqual, deepEqualExcept, deepFreeze, deepOmit, entityIds, findEntityById, freezeShallow, hasEntityId, mergeMetadata, removeEntityById, replaceEntityById, resetClockFactory, resetEventIdFactory, sameEntity, sameVersion, setClockFactory, setEventIdFactory, updateEntityById, vo, voEquals, voEqualsExcept, voValidated, voWithValidation, withClockFactory, withCommit, withEventIdFactory };
+export { AggregateDeletedError, AggregateNotFoundError, AggregateRoot, CommandBus, CommitError, ConcurrencyConflictError, DomainError, DuplicateAggregateError, Entity, EventBusImpl, EventHarvestError, EventSourcedAggregate, IdentityMap, InMemoryOutbox, InfrastructureError, MissingHandlerError, NestedUnitOfWorkError, QueryBus, RetryingTransactionScope, RollbackError, TransactionClosedError, UnenrolledChangesError, UnitOfWork, ValueObject, computeBackoffDelay, copyMetadata, createDomainEvent, createDomainEventWithMetadata, deepEqual, deepEqualExcept, deepFreeze, deepOmit, entityIds, findEntityById, freezeShallow, hasEntityId, mergeMetadata, removeEntityById, replaceEntityById, resetClockFactory, resetEventIdFactory, sameEntity, sameVersion, setClockFactory, setEventIdFactory, updateEntityById, vo, voEquals, voEqualsExcept, voValidated, voWithValidation, withClockFactory, withCommit, withEventIdFactory };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map