@arki/event-sourcing 0.1.0

package/dist/builders/stateful-process-manager.js

@@ -0,0 +1,280 @@
+import { debugBuilder } from '../debug.js';
+/**
+ * StatefulProcessManagerBuilder - Fluent API for building type-safe stateful process managers (sagas)
+ *
+ * Provides an immutable builder pattern for creating stateful process managers with:
+ * - Type safety through TypeScript generics
+ * - Runtime validation through Zod schemas
+ * - ORPC-style API with .handler() as terminal method
+ * - Persistent state management with load/save operations
+ *
+ * A Stateful Process Manager (Saga) maintains state across events to coordinate complex,
+ * long-running business processes by:
+ * - name: Unique identifier for the stateful process manager
+ * - eventTypes: Array of event types this process manager handles
+ * - stateSchema: Schema for validating process manager state
+ * - contextSchema: Schema for validating execution context
+ * - getStateId: Function to extract state identifier from events
+ * - loadState: Function to load existing state from storage
+ * - saveState: Function to persist state to storage
+ * - handler: Function that processes individual events and returns updated state
+ *
+ * @example
+ * ```typescript
+ * type OrderState = {
+ *   orderId: string;
+ *   status: 'pending' | 'paid' | 'shipped' | 'completed';
+ *   paymentId?: string;
+ *   trackingId?: string;
+ * };
+ *
+ * const orderProcessManager = defineStatefulProcessManager<OrderEvent, OrderState>()
+ *   .name('order-fulfillment')
+ *   .eventTypes(['OrderPlaced', 'PaymentProcessed', 'OrderShipped'])
+ *   .stateSchema(z.object({
+ *     orderId: z.string(),
+ *     status: z.enum(['pending', 'paid', 'shipped', 'completed']),
+ *     paymentId: z.string().optional(),
+ *     trackingId: z.string().optional(),
+ *   }))
+ *   .contextSchema(z.object({ messageBus: z.any(), repo: z.any() }))
+ *   .getStateId(event => `order-${event.data.orderId}`)
+ *   .loadState(async (stateId, context) => {
+ *     return await context.repo.orderSagas.findById(stateId);
+ *   })
+ *   .saveState(async (stateId, state, context) => {
+ *     await context.repo.orderSagas.upsert({ id: stateId, ...state });
+ *   })
+ *   .handler(async (event, state, context) => {
+ *     if (event.type === 'OrderPlaced') {
+ *       // Initialize state for new order
+ *       return {
+ *         orderId: event.data.orderId,
+ *         status: 'pending',
+ *       };
+ *     } else if (event.type === 'PaymentProcessed') {
+ *       // Update state after payment
+ *       return {
+ *         ...state!,
+ *         status: 'paid',
+ *         paymentId: event.data.paymentId,
+ *       };
+ *     } else if (event.type === 'OrderShipped') {
+ *       // Update state after shipping
+ *       return {
+ *         ...state!,
+ *         status: 'shipped',
+ *         trackingId: event.data.trackingId,
+ *       };
+ *     }
+ *     return state!;
+ *   });
+ * ```
+ */
+class StatefulProcessManagerBuilder {
+    _name;
+    _eventTypes;
+    _stateSchema;
+    _contextSchema;
+    _getStateIdFn;
+    _loadStateFn;
+    _saveStateFn;
+    _handlerFn;
+    /**
+     * Creates a deep copy of the builder to ensure immutability
+     * @private
+     */
+    clone() {
+        const builder = new StatefulProcessManagerBuilder();
+        builder._name = this._name;
+        builder._eventTypes = this._eventTypes;
+        builder._stateSchema = this._stateSchema;
+        builder._contextSchema = this._contextSchema;
+        builder._getStateIdFn = this._getStateIdFn;
+        builder._loadStateFn = this._loadStateFn;
+        builder._saveStateFn = this._saveStateFn;
+        builder._handlerFn = this._handlerFn;
+        return builder;
+    }
+    /**
+     * Sets the stateful process manager name
+     * @param name - Unique identifier for the stateful process manager
+     * @returns A new StatefulProcessManagerBuilder instance with the name set
+     */
+    name(name) {
+        const builder = this.clone();
+        builder._name = name;
+        debugBuilder('[stateful-process-manager] Set name: %s', name);
+        return builder;
+    }
+    /**
+     * Sets the event types this stateful process manager can handle
+     * @param types - Array of event type strings
+     * @returns A new StatefulProcessManagerBuilder instance with the event types set
+     */
+    eventTypes(types) {
+        const builder = this.clone();
+        builder._eventTypes = types;
+        debugBuilder('[stateful-process-manager:%s] Set event types: %o', this._name ?? 'unnamed', types);
+        return builder;
+    }
+    /**
+     * Sets the state schema for validation
+     * @param schema - Zod schema for validating the stateful process manager state
+     * @returns A new StatefulProcessManagerBuilder instance with the state schema set
+     */
+    stateSchema(schema) {
+        const builder = new StatefulProcessManagerBuilder();
+        builder._name = this._name;
+        builder._eventTypes = this._eventTypes;
+        builder._stateSchema = schema;
+        builder._contextSchema = this._contextSchema;
+        builder._getStateIdFn = this._getStateIdFn;
+        builder._loadStateFn = this._loadStateFn;
+        builder._saveStateFn = this._saveStateFn;
+        builder._handlerFn = this._handlerFn;
+        debugBuilder('[stateful-process-manager:%s] Set state schema', this._name ?? 'unnamed');
+        return builder;
+    }
+    /**
+     * Sets the context schema for validation
+     * @param schema - Zod schema for validating the execution context
+     * @returns A new StatefulProcessManagerBuilder instance with the context schema set
+     */
+    contextSchema(schema) {
+        const builder = new StatefulProcessManagerBuilder();
+        builder._name = this._name;
+        builder._eventTypes = this._eventTypes;
+        builder._stateSchema = this._stateSchema;
+        builder._contextSchema = schema;
+        builder._getStateIdFn = this._getStateIdFn;
+        builder._loadStateFn = this._loadStateFn;
+        builder._saveStateFn = this._saveStateFn;
+        builder._handlerFn = this._handlerFn;
+        debugBuilder('[stateful-process-manager:%s] Set context schema', this._name ?? 'unnamed');
+        return builder;
+    }
+    /**
+     * Sets the function to extract state identifier from events
+     * @param fn - Function that extracts a unique state identifier from an event
+     * @returns A new StatefulProcessManagerBuilder instance with the getStateId function set
+     */
+    getStateId(fn) {
+        const builder = this.clone();
+        builder._getStateIdFn = fn;
+        debugBuilder('[stateful-process-manager:%s] Set getStateId function', this._name ?? 'unnamed');
+        return builder;
+    }
+    /**
+     * Sets the function to load existing state from storage
+     * @param fn - Function that loads state by identifier, returns null if state doesn't exist
+     * @returns A new StatefulProcessManagerBuilder instance with the loadState function set
+     */
+    loadState(fn) {
+        const builder = this.clone();
+        builder._loadStateFn = fn;
+        debugBuilder('[stateful-process-manager:%s] Set loadState function', this._name ?? 'unnamed');
+        return builder;
+    }
+    /**
+     * Sets the function to persist state to storage
+     * @param fn - Function that saves state by identifier
+     * @returns A new StatefulProcessManagerBuilder instance with the saveState function set
+     */
+    saveState(fn) {
+        const builder = this.clone();
+        builder._saveStateFn = fn;
+        debugBuilder('[stateful-process-manager:%s] Set saveState function', this._name ?? 'unnamed');
+        return builder;
+    }
+    /**
+     * Terminal method that creates the stateful process manager
+     *
+     * Validates that all required configuration is set and returns an object
+     * with three properties:
+     * - processorId: The stateful process manager identifier
+     * - canHandle: Array of event types to filter events
+     * - eachBatch: Function that validates context, loads state for each event,
+     *              processes it through the handler, and saves the updated state
+     *
+     * @param fn - Function that processes individual events with their state and returns updated state
+     * @returns An object containing the stateful process manager configuration
+     * @throws Error if name, eventTypes, stateSchema, contextSchema, getStateId, loadState, or saveState are not defined
+     */
+    handler(fn) {
+        if (!this._name ||
+            !this._eventTypes ||
+            !this._stateSchema ||
+            !this._contextSchema ||
+            !this._getStateIdFn ||
+            !this._loadStateFn ||
+            !this._saveStateFn) {
+            debugBuilder('[stateful-process-manager] ERROR: Missing required properties');
+            throw new Error('Stateful process manager must have all configuration methods called');
+        }
+        const name = this._name;
+        const eventTypes = this._eventTypes;
+        const stateSchema = this._stateSchema;
+        const contextSchema = this._contextSchema;
+        const getStateIdFn = this._getStateIdFn;
+        const loadStateFn = this._loadStateFn;
+        const saveStateFn = this._saveStateFn;
+        debugBuilder('[stateful-process-manager:%s] Building handler for event types: %o', name, eventTypes);
+        return {
+            processorId: name,
+            canHandle: eventTypes,
+            eachBatch: async (events, context) => {
+                debugBuilder('[stateful-process-manager:%s] Validating context', name);
+                const validatedContext = contextSchema.parse(context);
+                debugBuilder('[stateful-process-manager:%s] Processing batch of %d events', name, events.length);
+                for (const event of events) {
+                    const stateId = getStateIdFn(event);
+                    debugBuilder('[stateful-process-manager:%s] Processing event with stateId: %s', name, stateId);
+                    // Load state
+                    debugBuilder('[stateful-process-manager:%s] Loading state for: %s', name, stateId);
+                    const state = await loadStateFn(stateId, validatedContext);
+                    const validatedState = state ? stateSchema.parse(state) : null;
+                    debugBuilder('[stateful-process-manager:%s] State loaded: %s', name, validatedState ? 'existing state' : 'no existing state');
+                    // Handle event
+                    debugBuilder('[stateful-process-manager:%s] Handling event', name);
+                    const newState = await fn(event, validatedState, validatedContext);
+                    const validatedNewState = stateSchema.parse(newState);
+                    debugBuilder('[stateful-process-manager:%s] Event handled, new state computed', name);
+                    // Save state
+                    debugBuilder('[stateful-process-manager:%s] Saving state for: %s', name, stateId);
+                    await saveStateFn(stateId, validatedNewState, validatedContext);
+                    debugBuilder('[stateful-process-manager:%s] State saved successfully', name);
+                }
+                debugBuilder('[stateful-process-manager:%s] Batch processed successfully', name);
+            },
+        };
+    }
+}
+/**
+ * Factory function to create a new StatefulProcessManagerBuilder
+ *
+ * @example
+ * ```typescript
+ * const builder = defineStatefulProcessManager<MyEvent, MyState>()
+ *   .name('my-stateful-process-manager')
+ *   .eventTypes(['EventTypeA', 'EventTypeB'])
+ *   .stateSchema(myStateSchema)
+ *   .contextSchema(myContextSchema)
+ *   .getStateId(event => `state-${event.data.id}`)
+ *   .loadState(async (stateId, context) => {
+ *     return await context.repo.findById(stateId);
+ *   })
+ *   .saveState(async (stateId, state, context) => {
+ *     await context.repo.upsert({ id: stateId, ...state });
+ *   })
+ *   .handler(async (event, state, context) => {
+ *     // Process event and return updated state
+ *     return { ...state, updated: true };
+ *   });
+ * ```
+ */
+export function defineStatefulProcessManager() {
+    debugBuilder('[stateful-process-manager] Creating new stateful process manager builder');
+    return new StatefulProcessManagerBuilder();
+}
+//# sourceMappingURL=stateful-process-manager.js.map

package/dist/builders/stateful-process-manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stateful-process-manager.js","sourceRoot":"","sources":["../../src/builders/stateful-process-manager.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAQ3C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuEG;AACH,MAAM,6BAA6B;IACzB,KAAK,CAAU;IACf,WAAW,CAAuB;IAClC,YAAY,CAAoB;IAChC,cAAc,CAAsB;IACpC,aAAa,CAAgC;IAC7C,YAAY,CAAgE;IAC5E,YAAY,CAAsE;IAClF,UAAU,CAA+E;IAEjG;;;OAGG;IACK,KAAK;QACX,MAAM,OAAO,GAAG,IAAI,6BAA6B,EAA6B,CAAC;QAC/E,OAAO,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC;QAC3B,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,WAAW,CAAC;QACvC,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,YAAY,CAAC;QACzC,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,cAAc,CAAC;QAC7C,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,aAAa,CAAC;QAC3C,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,YAAY,CAAC;QACzC,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,YAAY,CAAC;QACzC,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,UAAU,CAAC;QACrC,OAAO,OAAO,CAAC;IACjB,CAAC;IAED;;;;OAIG;IACH,IAAI,CAAC,IAAY;QACf,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,EAAE,CAAC;QAC7B,OAAO,CAAC,KAAK,GAAG,IAAI,CAAC;QACrB,YAAY,CAAC,yCAAyC,EAAE,IAAI,CAAC,CAAC;QAC9D,OAAO,OAAO,CAAC;IACjB,CAAC;IAED;;;;OAIG;IACH,UAAU,CAAC,KAA0B;QACnC,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,EAAE,CAAC;QAC7B,OAAO,CAAC,WAAW,GAAG,KAAK,CAAC;QAC5B,YAAY,CAAC,mDAAmD,EAAE,IAAI,CAAC,KAAK,IAAI,SAAS,EAAE,KAAK,CAAC,CAAC;QAClG,OAAO,OAAO,CAAC;IACjB,CAAC;IAED;;;;OAIG;IACH,WAAW,CAAY,MAA4B;QACjD,MAAM,OAAO,GAAG,IAAI,6BAA6B,EAAiC,CAAC;QACnF,OAAO,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC;QAC3B,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,WAAW,CAAC;QACvC,OAAO,CAAC,YAAY,GAAG,MAAM,CAAC;QAC9B,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,cAAc,CAAC;QAC7C,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,aAA2D,CAAC;QACzF,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,YAEf,CAAC;QACd,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,YAEf,CAAC;QACd,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,UAEb,CAAC;QACd,YAAY,CAAC,gDAAgD,EAAE,IAAI,CAAC,KAAK,IAAI,SAAS,CAAC,CAAC;QACxF,OAAO,OAAO,CAAC;IACjB,CAAC;IAED;;;;OAIG;IACH,aAAa,CACX,MAA8B;QAE9B,MAAM,OAAO,GAAG,IAAI,6BAA6B,EAAiC,CAAC;QACnF,OAAO,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC;QAC3B,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,WAAW,CAAC;QACvC,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,YAAY,CAAC;QACzC,OAAO,CAAC,cAAc,GAAG,MAAM,CAAC;QAChC,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,aAAa,CAAC;QAC3C,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,YAEf,CAAC;QACd,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,YAEf,CAAC;QACd,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,UAEb,CAAC;QACd,YAAY,CAAC,kDAAkD,EAAE,IAAI,CAAC,KAAK,IAAI,SAAS,CAAC,CAAC;QAC1F,OAAO,OAAO,CAAC;IACjB,CAAC;IAED;;;;OAIG;IACH,UAAU,CAAC,EAAgC;QACzC,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,EAAE,CAAC;QAC7B,OAAO,CAAC,aAAa,GAAG,EAAE,CAAC;QAC3B,YAAY,CAAC,uDAAuD,EAAE,IAAI,CAAC,KAAK,IAAI,SAAS,CAAC,CAAC;QAC/F,OAAO,OAAO,CAAC;IACjB,CAAC;IAED;;;;OAIG;IACH,SAAS,CACP,EAAgE;QAEhE,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,EAAE,CAAC;QAC7B,OAAO,CAAC,YAAY,GAAG,EAAE,CAAC;QAC1B,YAAY,CAAC,sDAAsD,EAAE,IAAI,CAAC,KAAK,IAAI,SAAS,CAAC,CAAC;QAC9F,OAAO,OAAO,CAAC;IACjB,CAAC;IAED;;;;OAIG;IACH,SAAS,CACP,EAAsE;QAEtE,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,EAAE,CAAC;QAC7B,OAAO,CAAC,YAAY,GAAG,EAAE,CAAC;QAC1B,YAAY,CAAC,sDAAsD,EAAE,IAAI,CAAC,KAAK,IAAI,SAAS,CAAC,CAAC;QAC9F,OAAO,OAAO,CAAC;IACjB,CAAC;IAED;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,EAA+E;QAKrF,IACE,CAAC,IAAI,CAAC,KAAK;YACX,CAAC,IAAI,CAAC,WAAW;YACjB,CAAC,IAAI,CAAC,YAAY;YAClB,CAAC,IAAI,CAAC,cAAc;YACpB,CAAC,IAAI,CAAC,aAAa;YACnB,CAAC,IAAI,CAAC,YAAY;YAClB,CAAC,IAAI,CAAC,YAAY,EAClB,CAAC;YACD,YAAY,CAAC,+DAA+D,CAAC,CAAC;YAC9E,MAAM,IAAI,KAAK,CAAC,qEAAqE,CAAC,CAAC;QACzF,CAAC;QAED,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC;QACxB,MAAM,UAAU,GAAG,IAAI,CAAC,WAAW,CAAC;QACpC,MAAM,WAAW,GAAG,IAAI,CAAC,YAAY,CAAC;QACtC,MAAM,aAAa,GAAG,IAAI,CAAC,cAAc,CAAC;QAC1C,MAAM,YAAY,GAAG,IAAI,CAAC,aAAa,CAAC;QACxC,MAAM,WAAW,GAAG,IAAI,CAAC,YAAY,CAAC;QACtC,MAAM,WAAW,GAAG,IAAI,CAAC,YAAY,CAAC;QAEtC,YAAY,CAAC,oEAAoE,EAAE,IAAI,EAAE,UAAU,CAAC,CAAC;QAErG,OAAO;YACL,WAAW,EAAE,IAAI;YACjB,SAAS,EAAE,UAAU;YACrB,SAAS,EAAE,KAAK,EAAE,MAAmB,EAAE,OAAgB,EAAE,EAAE;gBACzD,YAAY,CAAC,kDAAkD,EAAE,IAAI,CAAC,CAAC;gBACvE,MAAM,gBAAgB,GAAG,aAAa,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;gBACtD,YAAY,CAAC,6DAA6D,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC;gBAEjG,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;oBAC3B,MAAM,OAAO,GAAG,YAAY,CAAC,KAAK,CAAC,CAAC;oBACpC,YAAY,CAAC,iEAAiE,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC;oBAE/F,aAAa;oBACb,YAAY,CAAC,qDAAqD,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC;oBACnF,MAAM,KAAK,GAAG,MAAM,WAAW,CAAC,OAAO,EAAE,gBAAgB,CAAC,CAAC;oBAC3D,MAAM,cAAc,GAAG,KAAK,CAAC,CAAC,CAAC,WAAW,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;oBAC/D,YAAY,CACV,gDAAgD,EAChD,IAAI,EACJ,cAAc,CAAC,CAAC,CAAC,gBAAgB,CAAC,CAAC,CAAC,mBAAmB,CACxD,CAAC;oBAEF,eAAe;oBACf,YAAY,CAAC,8CAA8C,EAAE,IAAI,CAAC,CAAC;oBACnE,MAAM,QAAQ,GAAG,MAAM,EAAE,CAAC,KAAK,EAAE,cAAc,EAAE,gBAAgB,CAAC,CAAC;oBACnE,MAAM,iBAAiB,GAAG,WAAW,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;oBACtD,YAAY,CAAC,iEAAiE,EAAE,IAAI,CAAC,CAAC;oBAEtF,aAAa;oBACb,YAAY,CAAC,oDAAoD,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC;oBAClF,MAAM,WAAW,CAAC,OAAO,EAAE,iBAAiB,EAAE,gBAAgB,CAAC,CAAC;oBAChE,YAAY,CAAC,wDAAwD,EAAE,IAAI,CAAC,CAAC;gBAC/E,CAAC;gBAED,YAAY,CAAC,4DAA4D,EAAE,IAAI,CAAC,CAAC;YACnF,CAAC;SACF,CAAC;IACJ,CAAC;CACF;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,UAAU,4BAA4B;IAI1C,YAAY,CAAC,0EAA0E,CAAC,CAAC;IACzF,OAAO,IAAI,6BAA6B,EAA2B,CAAC;AACtE,CAAC"}

package/dist/bus.d.ts

@@ -0,0 +1,3 @@
+export { getInMemoryMessageBus } from '@event-driven-io/emmett';
+export type { CommandBus, EventBus, MessageBus } from '@event-driven-io/emmett';
+//# sourceMappingURL=bus.d.ts.map

package/dist/bus.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bus.d.ts","sourceRoot":"","sources":["../src/bus.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AAEhE,YAAY,EAAE,UAAU,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC"}

package/dist/bus.js

@@ -0,0 +1,2 @@
+export { getInMemoryMessageBus } from '@event-driven-io/emmett';
+//# sourceMappingURL=bus.js.map

package/dist/bus.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bus.js","sourceRoot":"","sources":["../src/bus.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC"}

package/dist/command-flow.d.ts

@@ -0,0 +1,87 @@
+import type { Command, CommandHandlerResult, CommandHandlerRetryOptions, Decider, DefaultCommandMetadata, DefaultRecord, Event, EventStore, HandleOptions } from '@event-driven-io/emmett';
+import type { z, ZodType, ZodTypeAny } from '@arki/contracts';
+type BuildCommand<CommandType extends string, Data extends DefaultRecord, Metadata extends DefaultCommandMetadata | undefined> = Command<CommandType, Data, Metadata extends undefined ? undefined : Metadata>;
+type HandlerMetadata<Metadata> = Metadata extends undefined ? undefined : Metadata;
+type MetadataInput<Metadata> = Metadata extends undefined ? {
+    metadata?: undefined;
+} : {
+    metadata: Metadata;
+};
+type StreamResolver<Context, CommandType> = (params: {
+    command: CommandType;
+    context: Context;
+}) => string;
+export type CommandFlowExecuteOptions<Context, Store extends EventStore, Input extends DefaultRecord, Metadata extends DefaultCommandMetadata | undefined> = {
+    context: Context;
+    eventStore: Store;
+    input: Input;
+    streamId?: string;
+    handleOptions?: HandleOptions<Store>;
+} & MetadataInput<Metadata>;
+export type CommandFlowHandlerArgs<Context, Store extends EventStore, CommandType, Input extends DefaultRecord, Metadata extends DefaultCommandMetadata | undefined, State, StreamEvent extends Event> = {
+    command: CommandType;
+    context: Context;
+    eventStore: Store;
+    input: Input;
+    metadata: HandlerMetadata<Metadata>;
+    streamId?: string;
+    handleOptions?: HandleOptions<Store>;
+    run: (streamId: string, options?: {
+        handleOptions?: HandleOptions<Store>;
+    }) => Promise<CommandHandlerResult<State, StreamEvent, Store>>;
+};
+export type CommandFlowHandler<Context, Store extends EventStore, CommandType, Input extends DefaultRecord, Metadata extends DefaultCommandMetadata | undefined, State, StreamEvent extends Event, ReturnType> = (args: CommandFlowHandlerArgs<Context, Store, CommandType, Input, Metadata, State, StreamEvent>) => Promise<ReturnType> | ReturnType;
+type CommandFlowExecutor<Context, Store extends EventStore, Input extends DefaultRecord, Metadata extends DefaultCommandMetadata | undefined, ReturnType> = (options: CommandFlowExecuteOptions<Context, Store, Input, Metadata>) => Promise<ReturnType>;
+export type CommandFlow<Context, Store extends EventStore, CommandType extends string, Input extends DefaultRecord, Metadata extends DefaultCommandMetadata | undefined, State, StreamEvent extends Event, ReturnType> = CommandFlowExecutor<Context, Store, Input, Metadata, ReturnType> & {
+    readonly commandType: CommandType;
+    readonly schemas: {
+        input: ZodTypeAny;
+        metadata?: ZodTypeAny;
+        event: ZodTypeAny;
+        state?: ZodTypeAny;
+    };
+    readonly decider: Decider<State, BuildCommand<CommandType, Input, Metadata>, StreamEvent>;
+    readonly createCommand: (input: Input, metadata?: HandlerMetadata<Metadata>) => BuildCommand<CommandType, Input, Metadata>;
+    readonly runCommand: (options: {
+        eventStore: Store;
+        command: BuildCommand<CommandType, Input, Metadata>;
+        streamId: string;
+        handleOptions?: HandleOptions<Store>;
+    }) => Promise<CommandHandlerResult<State, StreamEvent, Store>>;
+    readonly resolveStreamId?: StreamResolver<Context, BuildCommand<CommandType, Input, Metadata>>;
+};
+export declare class CommandFlowBuilder<Context, Store extends EventStore, CommandType extends string, Input extends DefaultRecord = DefaultRecord, Metadata extends DefaultCommandMetadata | undefined = undefined, State = unknown, StreamEvent extends Event = Event> {
+    private readonly commandType;
+    private inputSchema?;
+    private metadataSchema?;
+    private eventSchema?;
+    private stateSchema?;
+    private currentDecider?;
+    private streamResolver?;
+    private mapToStreamId?;
+    private retryOptions?;
+    constructor(commandType: CommandType);
+    input<Schema extends ZodType<DefaultRecord>>(schema: Schema): CommandFlowBuilder<Context, Store, CommandType, z.infer<Schema>, Metadata, State, StreamEvent>;
+    metadata<Schema extends ZodType<DefaultCommandMetadata>>(schema: Schema): CommandFlowBuilder<Context, Store, CommandType, Input, z.infer<Schema>, State, StreamEvent>;
+    events<Schema extends ZodType<Event>>(schema: Schema): CommandFlowBuilder<Context, Store, CommandType, Input, Metadata, State, z.infer<Schema>>;
+    state<Schema extends ZodType>(schema: Schema): CommandFlowBuilder<Context, Store, CommandType, Input, Metadata, z.infer<Schema>, StreamEvent>;
+    decider<NextState>(decider: Decider<NextState, BuildCommand<CommandType, Input, Metadata>, StreamEvent>): CommandFlowBuilder<Context, Store, CommandType, Input, Metadata, NextState, StreamEvent>;
+    stream(resolver: StreamResolver<Context, BuildCommand<CommandType, Input, Metadata>>): this;
+    mapStreamId(mapper: (id: string) => string): this;
+    retry(options: CommandHandlerRetryOptions): this;
+    handler<ReturnType = CommandHandlerResult<State, StreamEvent, Store>>(handler?: CommandFlowHandler<Context, Store, BuildCommand<CommandType, Input, Metadata>, Input, Metadata, State, StreamEvent, ReturnType>): CommandFlow<Context, Store, CommandType, Input, Metadata, State, StreamEvent, ReturnType>;
+    private ensureInputSchema;
+    private ensureEventSchema;
+    private ensureDecider;
+}
+type Toolkit<Context, Store extends EventStore> = {
+    command<CommandType extends string>(commandType: CommandType): CommandFlowBuilder<Context, Store, CommandType, DefaultRecord, undefined, unknown, Event>;
+};
+export declare const es: {
+    $context<Context, Store extends EventStore = EventStore<import("@event-driven-io/emmett").AnyRecordedMessageMetadata>>(): Toolkit<Context, Store>;
+};
+export declare const eventSourcing: {
+    $context<Context, Store extends EventStore = EventStore<import("@event-driven-io/emmett").AnyRecordedMessageMetadata>>(): Toolkit<Context, Store>;
+};
+export {};
+//# sourceMappingURL=command-flow.d.ts.map

package/dist/command-flow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-flow.d.ts","sourceRoot":"","sources":["../src/command-flow.ts"],"names":[],"mappings":"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"}

package/dist/command-flow.js

@@ -0,0 +1,233 @@
+import { DeciderCommandHandler } from '@event-driven-io/emmett';
+import { debugCommand } from './debug.js';
+export class CommandFlowBuilder {
+    commandType;
+    inputSchema;
+    metadataSchema;
+    eventSchema;
+    stateSchema;
+    currentDecider;
+    streamResolver;
+    mapToStreamId;
+    retryOptions;
+    constructor(commandType) {
+        this.commandType = commandType;
+        debugCommand('Creating command flow builder for command: %s', commandType);
+    }
+    input(schema) {
+        this.inputSchema = schema;
+        debugCommand('[%s] Registered input schema', this.commandType);
+        return this;
+    }
+    metadata(schema) {
+        this.metadataSchema = schema;
+        debugCommand('[%s] Registered metadata schema', this.commandType);
+        return this;
+    }
+    events(schema) {
+        this.eventSchema = schema;
+        debugCommand('[%s] Registered event schema', this.commandType);
+        return this;
+    }
+    state(schema) {
+        this.stateSchema = schema;
+        debugCommand('[%s] Registered state schema', this.commandType);
+        return this;
+    }
+    decider(decider) {
+        this.currentDecider = decider;
+        debugCommand('[%s] Registered decider', this.commandType);
+        return this;
+    }
+    stream(resolver) {
+        this.streamResolver = resolver;
+        debugCommand('[%s] Registered stream resolver', this.commandType);
+        return this;
+    }
+    mapStreamId(mapper) {
+        this.mapToStreamId = mapper;
+        debugCommand('[%s] Registered stream ID mapper', this.commandType);
+        return this;
+    }
+    retry(options) {
+        this.retryOptions = options;
+        debugCommand('[%s] Configured retry options', this.commandType);
+        return this;
+    }
+    handler(handler) {
+        const inputSchema = this.ensureInputSchema();
+        const eventSchema = this.ensureEventSchema();
+        const metadataSchema = this.metadataSchema;
+        const stateSchema = this.stateSchema;
+        const decider = this.ensureDecider();
+        const streamResolver = this.streamResolver;
+        const mapToStreamId = this.mapToStreamId;
+        const retryOptions = this.retryOptions;
+        const validatedDecider = {
+            decide: (command, state) => {
+                const safeState = stateSchema ? stateSchema.parse(state) : state;
+                const result = decider.decide(command, safeState);
+                const events = Array.isArray(result) ? result : [result];
+                const parsed = events.map(evt => eventSchema.parse(evt));
+                return Array.isArray(result) ? parsed : parsed[0];
+            },
+            evolve: (state, event) => {
+                const parsedEvent = eventSchema.parse(event);
+                const nextState = decider.evolve(state, parsedEvent);
+                return stateSchema ? stateSchema.parse(nextState) : nextState;
+            },
+            initialState: () => {
+                const initial = decider.initialState();
+                return stateSchema ? stateSchema.parse(initial) : initial;
+            },
+        };
+        const runner = DeciderCommandHandler({
+            decide: validatedDecider.decide,
+            evolve: validatedDecider.evolve,
+            initialState: validatedDecider.initialState,
+            mapToStreamId,
+            retry: retryOptions,
+        });
+        const defaultHandler = async ({ command, context, run, streamId, handleOptions }) => {
+            if (!streamResolver && !streamId) {
+                debugCommand('[%s] ERROR: No stream resolver or streamId provided', this.commandType);
+                throw new Error(`No stream resolver provided for command "${this.commandType}". Call .stream(...) or provide streamId.`);
+            }
+            debugCommand('[%s] Resolving stream ID', this.commandType);
+            const resolvedStream = streamId ?? streamResolver?.({ command, context });
+            if (!resolvedStream) {
+                debugCommand('[%s] ERROR: Failed to resolve stream ID', this.commandType);
+                throw new Error(`Unable to resolve stream id for command "${this.commandType}". Provide a streamId when executing.`);
+            }
+            debugCommand('[%s] Stream resolved to: %s', this.commandType, resolvedStream);
+            return run(resolvedStream, { handleOptions });
+        };
+        const finalHandler = (handler ?? defaultHandler);
+        const flowExecutor = async (options) => {
+            const { context, eventStore, input, streamId, handleOptions } = options;
+            const metadataOption = options;
+            debugCommand('[%s] Executing command flow with input: %O', this.commandType, input);
+            const parsedInput = inputSchema.parse(input);
+            debugCommand('[%s] Input validation passed', this.commandType);
+            let parsedMetadata;
+            if (metadataSchema) {
+                if (!('metadata' in metadataOption)) {
+                    debugCommand('[%s] ERROR: Metadata expected but not provided', this.commandType);
+                    throw new Error(`Metadata expected for command "${this.commandType}" but none was provided.`);
+                }
+                const metadataValue = metadataOption.metadata;
+                parsedMetadata = metadataSchema.parse(metadataValue);
+                debugCommand('[%s] Metadata validation passed', this.commandType);
+            }
+            else {
+                parsedMetadata = undefined;
+            }
+            const command = (metadataSchema
+                ? {
+                    type: this.commandType,
+                    data: parsedInput,
+                    metadata: parsedMetadata,
+                    kind: 'Command',
+                }
+                : {
+                    type: this.commandType,
+                    data: parsedInput,
+                    kind: 'Command',
+                });
+            debugCommand('[%s] Command created successfully', this.commandType);
+            const run = (resolvedStreamId, runOptions) => {
+                debugCommand('[%s] Running command on stream: %s', this.commandType, resolvedStreamId);
+                return runner(eventStore, resolvedStreamId, command, runOptions?.handleOptions ?? handleOptions);
+            };
+            const result = await finalHandler({
+                command,
+                context,
+                eventStore,
+                input: parsedInput,
+                metadata: parsedMetadata,
+                streamId,
+                handleOptions,
+                run,
+            });
+            debugCommand('[%s] Command execution completed successfully', this.commandType);
+            return result;
+        };
+        const createCommand = (input, metadataValue) => {
+            const parsedInput = inputSchema.parse(input);
+            if (metadataSchema) {
+                if (metadataValue === undefined) {
+                    throw new Error(`Metadata expected for command "${this.commandType}" but none was provided.`);
+                }
+                const parsedMetadata = metadataSchema.parse(metadataValue);
+                return {
+                    type: this.commandType,
+                    data: parsedInput,
+                    metadata: parsedMetadata,
+                    kind: 'Command',
+                };
+            }
+            if (metadataValue !== undefined) {
+                throw new Error(`Metadata value provided for command "${this.commandType}" without metadata schema. Add .metadata(...) to the builder.`);
+            }
+            return {
+                type: this.commandType,
+                data: parsedInput,
+                kind: 'Command',
+            };
+        };
+        const schemas = {
+            input: inputSchema,
+            ...(metadataSchema ? { metadata: metadataSchema } : {}),
+            event: eventSchema,
+            ...(stateSchema ? { state: stateSchema } : {}),
+        };
+        const runCommand = ({ eventStore, command, streamId, handleOptions, }) => {
+            if (!streamId) {
+                throw new Error(`Missing streamId when running command "${this.commandType}".`);
+            }
+            return runner(eventStore, streamId, command, handleOptions);
+        };
+        const flow = Object.assign(flowExecutor, {
+            commandType: this.commandType,
+            schemas,
+            decider: validatedDecider,
+            createCommand,
+            runCommand,
+        });
+        if (streamResolver) {
+            Object.assign(flow, {
+                resolveStreamId: (resolverParams) => streamResolver(resolverParams),
+            });
+        }
+        debugCommand('[%s] Command flow built successfully', this.commandType);
+        return flow;
+    }
+    ensureInputSchema() {
+        if (!this.inputSchema) {
+            throw new Error(`Command "${this.commandType}" is missing an input schema. Call .input(...) before defining the handler.`);
+        }
+        return this.inputSchema;
+    }
+    ensureEventSchema() {
+        if (!this.eventSchema) {
+            throw new Error(`Command "${this.commandType}" is missing an event schema. Call .events(...) before defining the handler.`);
+        }
+        return this.eventSchema;
+    }
+    ensureDecider() {
+        if (!this.currentDecider) {
+            throw new Error(`Command "${this.commandType}" is missing a decider definition. Call .decider(...) before defining the handler.`);
+        }
+        return this.currentDecider;
+    }
+}
+const createToolkit = () => ({
+    command: commandType => new CommandFlowBuilder(commandType),
+});
+export const es = {
+    $context() {
+        return createToolkit();
+    },
+};
+export const eventSourcing = es;
+//# sourceMappingURL=command-flow.js.map

package/dist/command-flow.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-flow.js","sourceRoot":"","sources":["../src/command-flow.ts"],"names":[],"mappings":"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"}