@classytic/arc 2.8.5 → 2.9.1

package/dist/{eventPlugin-CDjVTM82.mjs → eventPlugin-Dl7MoVWH.mjs}

@@ -1,5 +1,5 @@
 import { t as __exportAll } from "./chunk-BpYLSNr0.mjs";
-import { t as requestContext } from "./requestContext-DYvHl113.mjs";
+import { t as requestContext } from "./requestContext-DYtmNpm5.mjs";
 import fp from "fastify-plugin";
 //#region src/events/EventTransport.ts
 /**
@@ -67,7 +67,10 @@ var MemoryEventTransport = class {
 	}
 };
 /**
-* Create a domain event with auto-generated metadata
+* Create a domain event with auto-generated metadata.
+*
+* `id` and `timestamp` are filled in; everything else is caller-controlled.
+* Set `schemaVersion` explicitly for any event type you plan to evolve.
 */
 function createEvent(type, payload, meta) {
 	return {
@@ -80,6 +83,55 @@ function createEvent(type, payload, meta) {
 		}
 	};
 }
+/**
+* Create a child event that chains causation from a parent event.
+*
+* Rules:
+*  - `causationId` is set to the parent's `id` (direct cause)
+*  - `correlationId` is inherited from the parent if set, else falls back
+*    to the parent's `id` (root correlation)
+*  - `userId` / `organizationId` are inherited when not overridden so the
+*    whole chain stays scoped to the originating principal/tenant
+*
+* Caller-supplied `meta` wins over inherited fields — pass `{ userId: newActor }`
+* to override when a subsystem acts on behalf of a different principal.
+*
+* @example
+* ```typescript
+* const orderPlaced = createEvent('order.placed', { orderId: 'o1' }, {
+*   correlationId: req.id, userId: user.id,
+* });
+* await events.publish(orderPlaced);
+*
+* // Downstream handler emits a child event:
+* const reserved = createChildEvent(orderPlaced, 'inventory.reserved', {
+*   orderId: 'o1', skus: ['sku-1', 'sku-2'],
+* });
+* // reserved.meta.causationId   === orderPlaced.meta.id
+* // reserved.meta.correlationId === orderPlaced.meta.correlationId
+* // reserved.meta.userId        === user.id   (inherited)
+* ```
+*/
+function createChildEvent(parent, type, payload, meta) {
+	const inherited = {
+		correlationId: parent.meta.correlationId ?? parent.meta.id,
+		causationId: parent.meta.id
+	};
+	if (parent.meta.userId !== void 0) inherited.userId = parent.meta.userId;
+	if (parent.meta.organizationId !== void 0) inherited.organizationId = parent.meta.organizationId;
+	if (parent.meta.source !== void 0) inherited.source = parent.meta.source;
+	if (parent.meta.idempotencyKey !== void 0) inherited.idempotencyKey = parent.meta.idempotencyKey;
+	return {
+		type,
+		payload,
+		meta: {
+			id: crypto.randomUUID(),
+			timestamp: /* @__PURE__ */ new Date(),
+			...inherited,
+			...meta
+		}
+	};
+}
 //#endregion
 //#region src/events/retry.ts
 /**
@@ -89,16 +141,21 @@ function createEvent(type, payload, meta) {
 * After all retries exhausted, calls `onDead` callback if provided.
 */
 function withRetry(handler, options = {}) {
-	const { maxRetries = 3, backoffMs = 1e3, maxBackoffMs = 3e4, jitter = .1, onDead, name, logger = console } = options;
+	const { maxRetries = 3, backoffMs = 1e3, maxBackoffMs = 3e4, jitter = .1, transport, onDead, name, logger = console } = options;
 	const label = name ?? handler.name ?? "anonymous";
 	return async (event) => {
 		const errors = [];
+		let firstFailedAt;
+		let lastFailedAt;
 		for (let attempt = 0; attempt <= maxRetries; attempt++) try {
 			await handler(event);
 			return;
 		} catch (err) {
 			const error = err instanceof Error ? err : new Error(String(err));
+			const now = /* @__PURE__ */ new Date();
 			errors.push(error);
+			if (firstFailedAt === void 0) firstFailedAt = now;
+			lastFailedAt = now;
 			if (attempt < maxRetries) {
 				const baseDelay = Math.min(backoffMs * 2 ** attempt, maxBackoffMs);
 				const delay = baseDelay + jitter * baseDelay * Math.random();
@@ -106,7 +163,28 @@ function withRetry(handler, options = {}) {
 				await sleep(delay);
 			}
 		}
-		logger.error(`[Arc Events] Handler '${label}' permanently failed for ${event.type} after ${maxRetries + 1} attempts. ${errors.length} errors.`);
+		const attempts = maxRetries + 1;
+		logger.error(`[Arc Events] Handler '${label}' permanently failed for ${event.type} after ${attempts} attempts. ${errors.length} errors.`);
+		if (transport?.deadLetter) {
+			const lastError = errors[errors.length - 1];
+			const dlq = {
+				event,
+				error: {
+					message: lastError?.message ?? "unknown",
+					...lastError && "code" in lastError && typeof lastError.code === "string" ? { code: lastError.code } : {},
+					...lastError?.stack ? { stack: lastError.stack } : {}
+				},
+				attempts,
+				firstFailedAt: firstFailedAt ?? /* @__PURE__ */ new Date(),
+				lastFailedAt: lastFailedAt ?? /* @__PURE__ */ new Date(),
+				handlerName: label
+			};
+			try {
+				await transport.deadLetter(dlq);
+			} catch (dlqErr) {
+				logger.error("[Arc Events] transport.deadLetter() failed:", dlqErr);
+			}
+		}
 		if (onDead) try {
 			await onDead(event, errors);
 		} catch (dlqErr) {
@@ -243,4 +321,4 @@ var eventPlugin_default = fp(eventPlugin, {
 	fastify: "5.x"
 });
 //#endregion
-export { MemoryEventTransport as a, withRetry as i, eventPlugin_exports as n, createEvent as o, createDeadLetterPublisher as r, eventPlugin as t };
+export { MemoryEventTransport as a, withRetry as i, eventPlugin_exports as n, createChildEvent as o, createDeadLetterPublisher as r, createEvent as s, eventPlugin as t };

package/dist/events/index.d.mts

@@ -1,7 +1,8 @@
-import { a as MemoryEventTransport, c as createEvent, i as EventTransport, n as EventHandler, o as MemoryEventTransportOptions, r as EventLogger, s as PublishManyResult, t as DomainEvent } from "../EventTransport-BXja8NOc.mjs";
-import { a as withRetry, c as EventDefinitionOutput, d as EventSchema, f as ValidationResult, i as createDeadLetterPublisher, l as EventRegistry, m as defineEvent, n as eventPlugin, o as CustomValidator, p as createEventRegistry, r as RetryOptions, s as EventDefinitionInput, t as EventPluginOptions, u as EventRegistryOptions } from "../eventPlugin-D9DKB2zM.mjs";
+import { o as RepositoryLike } from "../interface-YrWsmKqE.mjs";
+import { a as EventMeta, c as MemoryEventTransportOptions, d as createEvent, i as EventLogger, l as PublishManyResult, n as DomainEvent, o as EventTransport, r as EventHandler, s as MemoryEventTransport, t as DeadLetteredEvent, u as createChildEvent } from "../EventTransport-CqZ8FyM_.mjs";
+import { a as withRetry, c as EventDefinitionOutput, d as EventSchema, f as ValidationResult, i as createDeadLetterPublisher, l as EventRegistry, m as defineEvent, n as eventPlugin, o as CustomValidator, p as createEventRegistry, r as RetryOptions, s as EventDefinitionInput, t as EventPluginOptions, u as EventRegistryOptions } from "../eventPlugin-BxvaCIZF.mjs";
 import { RedisEventTransportOptions, RedisLike } from "./transports/redis.mjs";
-import { r as RedisStreamTransportOptions, t as RedisStreamLike } from "../redis-stream-CrsfUmPt.mjs";
+import { r as RedisStreamTransportOptions, t as RedisStreamLike } from "../redis-stream-Bz-4q96t.mjs";
 
 //#region src/events/eventTypes.d.ts
 /**
@@ -50,6 +51,34 @@ declare const CACHE_EVENTS: Readonly<{
 /** Type for cache event names */
 type CacheEvent = (typeof CACHE_EVENTS)[keyof typeof CACHE_EVENTS];
 //#endregion
+//#region src/events/memory-outbox.d.ts
+interface MemoryEntry {
+  event: DomainEvent;
+  status: "pending" | "delivered" | "dead_letter";
+  attempts: number;
+  visibleAt: number;
+  leaseOwner: string | null;
+  leaseExpiresAt: number;
+  deliveredAt: number | null;
+  firstFailedAt: number | null;
+  lastFailedAt: number | null;
+  lastError: OutboxErrorInfo | null;
+  dedupeKey?: string;
+}
+declare class MemoryOutboxStore implements OutboxStore {
+  private readonly entries;
+  private readonly seenDedupeKeys;
+  save(event: DomainEvent, options?: OutboxWriteOptions): Promise<void>;
+  getPending(limit: number): Promise<DomainEvent[]>;
+  claimPending(options?: OutboxClaimOptions): Promise<DomainEvent[]>;
+  acknowledge(eventId: string, options?: OutboxAcknowledgeOptions): Promise<void>;
+  fail(eventId: string, error: OutboxErrorInfo, options?: OutboxFailOptions): Promise<void>;
+  getDeadLettered(limit: number): Promise<DeadLetteredEvent[]>;
+  purge(olderThanMs: number): Promise<number>;
+  /** Test helper: inspect entry by id */
+  _getEntry(eventId: string): Readonly<MemoryEntry> | undefined;
+}
+//#endregion
 //#region src/events/outbox.d.ts
 /**
  * **Terminology (v2.8.1+):**
@@ -119,6 +148,52 @@ interface OutboxErrorInfo {
   readonly message: string;
   readonly code?: string;
 }
+/**
+ * Context passed to {@link OutboxFailurePolicy}.
+ */
+interface OutboxFailureContext {
+  /** The event whose delivery just failed */
+  readonly event: DomainEvent;
+  /** The error returned by the transport / handler */
+  readonly error: Error;
+  /**
+   * Attempt count including this failure (1 on the first fail).
+   *
+   * Tracked by {@link EventOutbox} in-process — accurate within a single
+   * relay process, resets on restart. For durable attempt counts, query
+   * your store directly inside the policy.
+   */
+  readonly attempts: number;
+}
+/**
+ * Decision returned by {@link OutboxFailurePolicy} — controls how the
+ * relay calls `store.fail()` for a failed event.
+ */
+interface OutboxFailureDecision {
+  /** Schedule retry for this time. Omit for immediate (next-poll) retry. */
+  readonly retryAt?: Date;
+  /**
+   * Move the event to dead-letter state (no further retries). When `true`,
+   * {@link RelayResult.deadLettered} is incremented.
+   */
+  readonly deadLetter?: boolean;
+}
+/**
+ * Centralised retry/DLQ policy evaluated by {@link EventOutbox.relayBatch}
+ * on every failure. Returns the options passed to `store.fail()`.
+ *
+ * Typical shape:
+ * ```typescript
+ * failurePolicy: ({ attempts, error }) => {
+ *   if (attempts >= 5) return { deadLetter: true };
+ *   return { retryAt: exponentialBackoff({ attempt: attempts }) };
+ * }
+ * ```
+ *
+ * Without a policy, the relay uses the legacy "immediate re-visibility" fail
+ * behaviour (each fail() is equivalent to `{}`).
+ */
+type OutboxFailurePolicy = (ctx: OutboxFailureContext) => OutboxFailureDecision | Promise<OutboxFailureDecision>;
 /**
  * Thrown by a store when `acknowledge` / `fail` is called by a consumer that
  * does not own the event's current lease.
@@ -240,6 +315,22 @@ interface OutboxStore {
    * @throws {@link OutboxOwnershipError} on ownership mismatch
    */
   fail?(eventId: string, error: OutboxErrorInfo, options?: OutboxFailOptions): Promise<void>;
+  /**
+   * Return events currently in dead-letter state as typed
+   * {@link DeadLetteredEvent} envelopes.
+   *
+   * Closes the loop between {@link OutboxStore.fail} (with `deadLetter: true`)
+   * and {@link import('./EventTransport.js').DeadLetteredEvent} — apps get the
+   * same shape out of the outbox that {@link import('./retry.js').withRetry}
+   * delivers to transports. No hand-building DLQ envelopes.
+   *
+   * Implementations MUST populate `error`, `attempts`, and both
+   * `firstFailedAt` / `lastFailedAt` from whatever they tracked during `fail()`
+   * calls. `handlerName` is optional — stores that don't track it can omit.
+   *
+   * @param limit - Max envelopes to return
+   */
+  getDeadLettered?(limit: number): Promise<DeadLetteredEvent[]>;
   /**
    * Purge old **delivered** events (optional, DB-agnostic contract).
    *
@@ -285,6 +376,12 @@ interface RelayResult {
   readonly malformed: number;
   /** Number of fail() calls that themselves threw (store bugs / contention) */
   readonly failHookErrors: number;
+  /**
+   * Number of events moved to dead-letter state this batch via the configured
+   * {@link OutboxFailurePolicy}. Zero when no policy is set or no failure
+   * tripped the `deadLetter` branch.
+   */
+  readonly deadLettered: number;
   /** Whether `publishMany` was used (true) or per-event `publish` (false) */
   readonly usedPublishMany: boolean;
 }
@@ -298,8 +395,23 @@ type OutboxRelayErrorHandler = (info: {
   readonly error: Error;
 }) => void;
 interface EventOutboxOptions {
-  /** Outbox store for persistence */
-  readonly store: OutboxStore;
+  /**
+   * Repository managing the outbox collection. Arc consumes it directly —
+   * no wrapper classes. Requires `create`, `getOne`, `findAll`,
+   * `deleteMany`, and `findOneAndUpdate` from `RepositoryLike` (mongokit
+   * ≥3.8 satisfies all of these). Takes precedence over `store` when both
+   * are passed.
+   *
+   * Use this for the common path where the outbox lives in your primary
+   * database. Use `store` for non-repository backends (memory / custom).
+   */
+  readonly repository?: RepositoryLike;
+  /**
+   * Non-repository outbox store. Use when your backend isn't a repository
+   * (memory for tests, Kafka, DynamoDB, custom). Ignored if `repository`
+   * is also passed.
+   */
+  readonly store?: OutboxStore;
   /** Transport to relay events to (optional — can relay later) */
   readonly transport?: EventTransport;
   /** Max events per relay batch (default: 100) */
@@ -327,6 +439,17 @@ interface EventOutboxOptions {
    * throughput, or to debug batch-specific issues.
    */
   readonly usePublishMany?: boolean;
+  /**
+   * Retry/DLQ decision policy. When set, {@link EventOutbox.relayBatch}
+   * invokes this on every failure and uses the returned options for
+   * `store.fail()`. Centralises the "after N fails, dead-letter" rule so
+   * apps don't recompute `exponentialBackoff` + escalation thresholds on
+   * every failure site.
+   *
+   * Without a policy, `fail()` is called with `{}` (immediate re-visibility
+   * on next poll) — legacy behaviour, unchanged.
+   */
+  readonly failurePolicy?: OutboxFailurePolicy;
 }
 declare class EventOutbox {
   private readonly _store;
@@ -336,6 +459,14 @@ declare class EventOutbox {
   private readonly _leaseMs;
   private readonly _onError?;
   private readonly _usePublishMany;
+  private readonly _failurePolicy?;
+  /**
+   * In-process attempt counter per event id. Accurate within this relay
+   * process; resets on restart. Populated as failures occur and cleared on
+   * successful ack or dead-letter transition. For durable authoritative
+   * counts, apps can query the store directly inside {@link OutboxFailurePolicy}.
+   */
+  private readonly _attempts;
   constructor(opts: EventOutboxOptions);
   /** Unique consumer ID used for lease ownership when the store supports claims */
   get consumerId(): string;
@@ -395,6 +526,16 @@ declare class EventOutbox {
    * @returns Per-kind outcome counts for the batch
    */
   relayBatch(): Promise<RelayResult>;
+  /**
+   * Fetch current dead-lettered events as typed {@link DeadLetteredEvent}
+   * envelopes. Delegates to {@link OutboxStore.getDeadLettered} — returns
+   * `[]` when the store doesn't implement it.
+   *
+   * Pairs with {@link OutboxFailurePolicy}: apps set a policy that routes to
+   * `deadLetter: true` after N attempts, then read back with this to alert,
+   * replay, or archive.
+   */
+  getDeadLettered(limit?: number): Promise<DeadLetteredEvent[]>;
   /**
    * Purge old **delivered** events from the outbox store.
    * Delegates to `store.purge()` if implemented; no-op otherwise.
@@ -403,36 +544,6 @@ declare class EventOutbox {
    */
   purge(olderThanMs?: number): Promise<number>;
 }
-interface MemoryEntry {
-  event: DomainEvent;
-  status: "pending" | "delivered" | "dead_letter";
-  attempts: number;
-  visibleAt: number;
-  leaseOwner: string | null;
-  leaseExpiresAt: number;
-  deliveredAt: number | null;
-  lastError: OutboxErrorInfo | null;
-  dedupeKey?: string;
-}
-/**
- * In-memory outbox store — reference implementation supporting the full
- * capability set (claim/lease, fail/retry, dedupe, visibleAt).
- *
- * For dev/testing only. Production deployments should use a durable store
- * backed by the app's database.
- */
-declare class MemoryOutboxStore implements OutboxStore {
-  private readonly entries;
-  private readonly seenDedupeKeys;
-  save(event: DomainEvent, options?: OutboxWriteOptions): Promise<void>;
-  getPending(limit: number): Promise<DomainEvent[]>;
-  claimPending(options?: OutboxClaimOptions): Promise<DomainEvent[]>;
-  acknowledge(eventId: string, options?: OutboxAcknowledgeOptions): Promise<void>;
-  fail(eventId: string, error: OutboxErrorInfo, options?: OutboxFailOptions): Promise<void>;
-  purge(olderThanMs: number): Promise<number>;
-  /** Test helper: inspect entry by id */
-  _getEntry(eventId: string): Readonly<MemoryEntry> | undefined;
-}
 /**
  * Options for {@link exponentialBackoff}.
  */
@@ -486,4 +597,4 @@ interface ExponentialBackoffOptions {
  */
 declare function exponentialBackoff(options: ExponentialBackoffOptions): Date;
 //#endregion
-export { ARC_LIFECYCLE_EVENTS, type ArcLifecycleEvent, CACHE_EVENTS, CRUD_EVENT_SUFFIXES, type CacheEvent, type CrudEventSuffix, type CustomValidator, type DomainEvent, type EventDefinitionInput, type EventDefinitionOutput, type EventHandler, type EventLogger, EventOutbox, type EventOutboxOptions, type EventPluginOptions, type EventRegistry, type EventRegistryOptions, type EventSchema, type EventTransport, type ExponentialBackoffOptions, InvalidOutboxEventError, MemoryEventTransport, type MemoryEventTransportOptions, MemoryOutboxStore, type OutboxAcknowledgeOptions, type OutboxClaimOptions, type OutboxErrorInfo, type OutboxFailOptions, OutboxOwnershipError, type OutboxRelayErrorHandler, type OutboxRelayErrorKind, type OutboxStore, type OutboxWriteOptions, type PublishManyResult, type RedisEventTransportOptions, type RedisLike, type RedisStreamLike, type RedisStreamTransportOptions, type RelayResult, type RetryOptions, type ValidationResult, createDeadLetterPublisher, createEvent, createEventRegistry, crudEventType, defineEvent, eventPlugin, exponentialBackoff, withRetry };
+export { ARC_LIFECYCLE_EVENTS, type ArcLifecycleEvent, CACHE_EVENTS, CRUD_EVENT_SUFFIXES, type CacheEvent, type CrudEventSuffix, type CustomValidator, type DeadLetteredEvent, type DomainEvent, type EventDefinitionInput, type EventDefinitionOutput, type EventHandler, type EventLogger, type EventMeta, EventOutbox, type EventOutboxOptions, type EventPluginOptions, type EventRegistry, type EventRegistryOptions, type EventSchema, type EventTransport, type ExponentialBackoffOptions, InvalidOutboxEventError, MemoryEventTransport, type MemoryEventTransportOptions, MemoryOutboxStore, type OutboxAcknowledgeOptions, type OutboxClaimOptions, type OutboxErrorInfo, type OutboxFailOptions, type OutboxFailureContext, type OutboxFailureDecision, type OutboxFailurePolicy, OutboxOwnershipError, type OutboxRelayErrorHandler, type OutboxRelayErrorKind, type OutboxStore, type OutboxWriteOptions, type PublishManyResult, type RedisEventTransportOptions, type RedisLike, type RedisStreamLike, type RedisStreamTransportOptions, type RelayResult, type RetryOptions, type ValidationResult, createChildEvent, createDeadLetterPublisher, createEvent, createEventRegistry, crudEventType, defineEvent, eventPlugin, exponentialBackoff, withRetry };