@schemeless/event-store-types 2.4.3 → 2.6.0

package/dist/EventStore.types.d.ts

@@ -3,6 +3,11 @@ export interface BaseEventInput<Payload, META = undefined> {
     meta?: META;
     identifier?: string;
     correlationId?: string;
+    /**
+     * @deprecated Will be removed in v3.0.
+     * causationId is now managed exclusively by the framework.
+     * Do not set this field manually.
+     */
     causationId?: string;
     created?: Date;
 }
@@ -42,6 +47,18 @@ export interface EventFlow<PartialPayload = any, Payload extends PartialPayload
     readonly sideEffect?: (event: CreatedEvent<Payload>) => Promise<void | BaseEvent<any>[]> | void | BaseEvent<any>[];
     readonly cancelApply?: (event: CreatedEvent<Payload>) => Promise<void> | void;
     readonly createConsequentEvents?: (causalEvent: CreatedEvent<Payload>) => Promise<BaseEvent<any>[]> | BaseEvent<any>[];
+    /**
+     * Generates compensating event(s) to reverse this event's effects.
+     * Called by the framework during revert operations.
+     *
+     * If this hook is not defined, the event cannot be reverted.
+     * If any event in a causal chain lacks this hook, the entire chain
+     * cannot be reverted.
+     *
+     * @param originalEvent - The event being reverted
+     * @returns Compensating event(s) to persist
+     */
+    readonly compensate?: (originalEvent: CreatedEvent<Payload>) => BaseEvent<any> | BaseEvent<any>[];
 }
 export type EventTaskAndError = {
     task: CreatedEvent<any>;
@@ -68,7 +85,9 @@ export declare enum SideEffectsState {
 export declare enum EventOutputState {
     success = "Event:success",
     invalid = "Event:invalid",
-    canceled = "Event:canceled"
+    canceled = "Event:canceled",
+    reverted = "Event:reverted",
+    revertFailed = "Event:revertFailed"
 }
 export declare enum EventObserverState {
     success = "Observer:success"

package/dist/EventStore.types.js

@@ -12,6 +12,8 @@ var EventOutputState;
     EventOutputState["success"] = "Event:success";
     EventOutputState["invalid"] = "Event:invalid";
     EventOutputState["canceled"] = "Event:canceled";
+    EventOutputState["reverted"] = "Event:reverted";
+    EventOutputState["revertFailed"] = "Event:revertFailed";
 })(EventOutputState = exports.EventOutputState || (exports.EventOutputState = {}));
 var EventObserverState;
 (function (EventObserverState) {

package/dist/Repo.types.d.ts

@@ -16,4 +16,18 @@ export interface IEventStoreRepo<PAYLOAD = any, META = any> {
     createEventEntity: (event: CreatedEvent<any>) => IEventStoreEntity<PAYLOAD, META>;
     storeEvents: (events: CreatedEvent<any>[]) => Promise<void>;
     resetStore: () => Promise<void>;
+    /**
+     * Retrieves a single event by its ID.
+     * Required for revert operations.
+     */
+    getEventById?: (id: string) => Promise<IEventStoreEntity<PAYLOAD, META> | null>;
+    /**
+     * Finds all events directly caused by the specified event.
+     * Returns events where causationId equals the given eventId.
+     * Required for revert operations to traverse the event tree.
+     *
+     * Note for DynamoDB: Consider adding a GSI on causationId for better
+     * performance. Without a GSI, this will result in a table scan.
+     */
+    findByCausationId?: (causationId: string) => Promise<IEventStoreEntity<PAYLOAD, META>[]>;
 }

package/dist/Revert.types.d.ts

@@ -0,0 +1,38 @@
+import type { CreatedEvent } from './EventStore.types';
+/**
+ * Result of canRevert() check
+ */
+export interface CanRevertResult {
+    /** Whether the event can be reverted */
+    canRevert: boolean;
+    /** Reason why revert is not possible (if canRevert is false) */
+    reason?: string;
+    /** Events missing the 'compensate' hook */
+    missingCompensateEvents?: Array<{
+        id: string;
+        domain: string;
+        type: string;
+    }>;
+}
+/**
+ * Result of previewRevert() - shows what would be affected
+ */
+export interface PreviewRevertResult {
+    /** The root event that would be reverted */
+    rootEvent: CreatedEvent<any>;
+    /** All descendant events that would be reverted */
+    descendantEvents: CreatedEvent<any>[];
+    /** Total count of events affected */
+    totalEventCount: number;
+}
+/**
+ * Result of a successful revert() operation
+ */
+export interface RevertResult {
+    /** ID of the event that was reverted */
+    revertedEventId: string;
+    /** Compensating events generated for this event */
+    compensatingEvents: CreatedEvent<any>[];
+    /** Revert results for child events */
+    childResults: RevertResult[];
+}

package/dist/Revert.types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/index.d.ts

@@ -1,2 +1,3 @@
 export * from './EventStore.types';
 export * from './Repo.types';
+export * from './Revert.types';

package/dist/index.js

@@ -16,3 +16,4 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./EventStore.types"), exports);
 __exportStar(require("./Repo.types"), exports);
+__exportStar(require("./Revert.types"), exports);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@schemeless/event-store-types",
-  "version": "2.4.3",
+  "version": "2.6.0",
   "typescript:main": "src/index.ts",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -34,5 +34,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "c94ac386be41b1a90c8d9bd4c047fac3c7b5031f"
+  "gitHead": "fa654aea833fcac2ee269d23e7f7683bd20bd16f"
 }

package/readme.md

@@ -28,6 +28,17 @@ const eventFlow: EventFlow = {
 
 `CreatedEvent` extends the base shape with generated identifiers and timestamps, while `SideEffectsState`, `EventOutputState`, and `EventObserverState` describe the possible outcomes emitted by the runtime.
 
+### Traceability IDs
+
+The event store uses several ID fields to track causation and correlation across event chains:
+
+- **`correlationId`** – Groups all events originating from the same root command. The framework inherits this from parent events or creates it for root events. Developers can optionally pass this from external systems (e.g., HTTP request headers).
+- **`causationId`** – Links each event to its immediate parent. This field is **managed exclusively by the framework** via `createConsequentEvents` or `sideEffect` handlers.
+- **`identifier`** – Developer-provided field to record who or what triggered the event (e.g., user ID, service name).
+- **`trackingId`** – Developer-provided external reference for cross-system tracing.
+
+> **Important:** Do not manually set `causationId` in your event inputs. The framework automatically populates this field based on the event creation context to ensure chain integrity.
+
 ## Repository contracts
 
 `Repo.types` exposes the `IEventStoreRepo` and `IEventStoreEntity` interfaces. Adapters implement these to integrate with the core runtime.
@@ -49,3 +60,36 @@ class CustomRepo implements IEventStoreRepo {
 ```
 
 The iterator returned by `getAllEvents` yields arrays of `IEventStoreEntity` records. Each record includes identifiers, correlation/causation metadata, and the `created` timestamp so replays can process history in order.
+
+### Revert support
+
+To enable revert operations, adapters should also implement two additional optional methods:
+
+```ts
+class CustomRepo implements IEventStoreRepo {
+  // ... existing methods ...
+
+  async getEventById(id: string) {
+    // Return a single event by ID, or null if not found
+  }
+
+  async findByCausationId(causationId: string) {
+    // Return all events where causationId equals the given value
+    // Used to traverse the event tree during reverts
+  }
+}
+```
+
+> **Note:** For DynamoDB adapters, consider adding a Global Secondary Index on `causationId` for better performance.
+
+## Revert types
+
+The package exports types for the revert API:
+
+```ts
+import { CanRevertResult, PreviewRevertResult, RevertResult } from '@schemeless/event-store-types';
+```
+
+- `CanRevertResult` – Indicates whether an event can be reverted, with reasons if not
+- `PreviewRevertResult` – Shows which events would be affected by a revert
+- `RevertResult` – Contains the outcome of a revert operation, including generated compensating events