arvo-event-handler 3.0.13 → 3.0.15

package/dist/ArvoOrchestrator/types.d.ts

@@ -6,6 +6,9 @@ import type { IMachineExectionEngine } from '../MachineExecutionEngine/interface
 import type { IMachineMemory } from '../MachineMemory/interface';
 import type { IMachineRegistry } from '../MachineRegistry/interface';
 import type { ArvoEventHandlerOtelSpanOptions } from '../types';
+/**
+ * Discriminated union representing the result of a try operation.
+ */
 export type TryFunctionOutput<TData, TError extends Error> = {
     type: 'success';
     data: TData;
@@ -14,101 +17,123 @@ export type TryFunctionOutput<TData, TError extends Error> = {
     error: TError;
 };
 /**
- * Represents the state record stored in machine memory.
+ * State record persisted in machine memory for orchestration execution.
+ *
+ * Extends the base orchestration execution record with machine-specific state
+ * including XState snapshots, event history, and hierarchical orchestration context.
  */
 export type MachineMemoryRecord = OrchestrationExecutionMemoryRecord<{
-    /** Unique identifier for the machine instance */
+    /** Unique identifier for this orchestration instance */
     subject: string;
     /**
-     * Reference to the parent orchestration's subject when orchestrations are nested or chained.
-     * This enables hierarchical orchestration patterns where one orchestration can spawn
-     * sub-orchestrations. When the current orchestration completes, its completion event
-     * is routed back to this parent subject rather than staying within the current context.
+     * Parent orchestration subject for nested workflows.
      *
-     * - For root orchestrations: null
-     * - For nested orchestrations: contains the subject of the parent orchestration
-     * - Extracted from the `parentSubject$$` field in initialization events
+     * Enables hierarchical orchestration patterns where one orchestration spawns
+     * sub-orchestrations. When the current orchestration completes, its completion
+     * event routes back to this parent subject.
+     *
+     * - Root orchestrations: `null`
+     * - Nested orchestrations: parent's subject identifier
+     * - Source: `parentSubject$$` field in initialization events
      */
     parentSubject: string | null;
     /**
-     * The unique identifier of the event that originally initiated this entire orchestration workflow.
-     * This serves as the root identifier for tracking the complete execution chain from start to finish.
+     * ID of the event that initiated this orchestration workflow.
      *
-     * - For new orchestrations: set to the current event's ID
-     * - For resumed orchestrations: retrieved from the stored state
-     * - Used as the `parentid` for completion events to create a direct lineage back to the workflow's origin
+     * Serves as the root identifier for tracing the complete execution chain.
+     * Used as `parentid` for completion events to maintain lineage back to
+     * the workflow's origin.
      *
-     * This enables tracing the entire execution path and ensures completion events reference
-     * the original triggering event rather than just the immediate previous step.
+     * - New orchestrations: set to current event's ID
+     * - Resumed orchestrations: retrieved from stored state
      */
     initEventId: string;
     /**
-     * Current execution status of the machine. The status field represents the current
-     * state of the machine's lifecycle. While commonly used values are:
-     * - 'active': Machine is currently executing
-     * - 'done': Machine has completed its execution successfully
-     * - 'error': Machine encountered an error during execution
-     * - 'stopped': Machine execution was explicitly stopped
+     * Current machine execution status.
+     *
+     * Common values include:
+     * - `'active'`: Machine is executing
+     * - `'done'`: Machine completed successfully
+     * - `'error'`: Machine encountered an error
+     * - `'stopped'`: Machine was explicitly stopped
      *
-     * Due to XState dependency, the status can be any string value defined in the
-     * state machine definition. This allows for custom states specific to the
-     * business logic implemented in the state machine.
+     * Custom values can be defined in the state machine configuration.
      */
     status: string;
-    /** Current value stored in the machine state */
+    /** Current state value (string for simple states, object for compound states) */
     value: string | Record<string, any> | null;
-    /** XState snapshot representing the machine's current state */
+    /** XState snapshot representing the complete machine state */
     state: Snapshot<any>;
+    /**
+     * Event history from the last execution session.
+     */
     events: {
-        /** The event consumed by the machine in the last session */
+        /** Event consumed by the machine in the last session */
         consumed: InferArvoEvent<ArvoEvent> | null;
-        /**
-         * The events produced by the machine in the last session
-         */
+        /** Events produced by the machine in the last session */
         produced: InferArvoEvent<ArvoEvent>[];
     };
-    /** Machine definition string */
+    /** Serialized machine definition for debugging and inspection */
     machineDefinition: string | null;
 }>;
 /**
- * Interface defining the core components of an Arvo orchestrator.
+ * Configuration parameters for ArvoOrchestrator constructor.
+ *
+ * Defines all required components and settings for orchestrator initialization.
+ * For simplified creation with default components, use {@link createArvoOrchestrator}.
  */
 export type ArvoOrchestratorParam = {
-    /** The cost of the execution of the orchestrator */
+    /** Computational cost metric assigned to orchestrator operations */
     executionunits: number;
-    /** Memory interface for storing and retrieving machine state */
+    /** Memory interface for state persistence and retrieval */
     memory: IMachineMemory<MachineMemoryRecord>;
     /** Registry for managing and resolving machine instances */
     registry: IMachineRegistry;
-    /** Engine responsible for machine execution */
+    /** Engine responsible for executing state machine logic */
     executionEngine: IMachineExectionEngine;
+    /** Whether to enforce resource locking for concurrent safety */
     requiresResourceLocking: boolean;
     /**
-     * Optional configuration to customize where system error events are emitted.
+     * Optional domains for system error event routing.
      *
-     * This overrides the default system error domain fallback of:
+     * Overrides the default fallback sequence of:
      * `[event.domain, self.contract.domain, null]`
      *
-     * Use this to precisely control the set of domains that should receive structured
-     * `sys.*.error` events when uncaught exceptions occur in the handler.
+     * Controls where structured `sys.*.error` events are emitted when
+     * uncaught exceptions occur. Supports symbolic constants from {@link ArvoDomain}.
      *
-     * Symbolic constants from {@link ArvoDomain} are supported.
-     *
-     * @default undefined — uses standard fallback broadcast domains
+     * @default undefined - uses standard fallback broadcast domains
      */
     systemErrorDomain?: (string | null)[];
-    /**
-     * The OpenTelemetry span options
-     */
+    /** OpenTelemetry span configuration for distributed tracing */
     spanOptions?: ArvoEventHandlerOtelSpanOptions;
 };
 /**
- * Configuration interface for creating an Arvo orchestrator instance.
+ * Configuration parameters for creating an orchestrator via factory function.
+ *
+ * Simplified interface for {@link createArvoOrchestrator} that automatically
+ * constructs default registry and execution engine components.
  */
 export type CreateArvoOrchestratorParam = Pick<ArvoOrchestratorParam, 'memory' | 'executionunits' | 'spanOptions' | 'systemErrorDomain'> & {
     /**
-     * Collection of state machines to be managed by the orchestrator.
-     * All machines must have the same source identifier.
+     * Optional override for resource locking requirement.
+     *
+     * When undefined, locking is automatically enabled if any machine requires it.
+     * Explicitly set to control locking behavior regardless of machine requirements.
+     *
+     * Resource locking is needed when:
+     * - Machines contain parallel states with simultaneous active states
+     * - Preventing race conditions in concurrent event processing
+     * - Maintaining state consistency across distributed executions
+     *
+     * @default undefined - auto-determined from machines
+     */
+    requiresResourceLocking?: ArvoOrchestratorParam['requiresResourceLocking'];
+    /**
+     * State machines to register with the orchestrator.
+     *
+     * All machines must share the same source identifier and have unique versions.
+     * At least one machine is required.
      */
     machines: ArvoMachine<any, any, any, any, any>[];
 };

package/dist/ArvoResumable/factory.d.ts

@@ -1,44 +1,39 @@
 import type { ArvoOrchestratorContract, VersionedArvoContract } from 'arvo-core';
 import { ArvoResumable } from '.';
-import type { IMachineMemory } from '../MachineMemory/interface';
-import type { ArvoEventHandlerOtelSpanOptions } from '../types';
-import type { ArvoResumableHandler, ArvoResumableState } from './types';
+import type { CreateArvoResumableParam } from './types';
 /**
- * Factory function for creating ArvoResumable orchestrator instances
+ * Creates a new {@link ArvoResumable} orchestrator instance.
  *
- * Creates a new ArvoResumable orchestrator with type safety and sensible defaults.
- * ArvoResumable provides handler-based workflow orchestration with explicit context management,
- * contract validation, and distributed locking capabilities.
+ * Factory function that constructs a resumable workflow handler with automatic
+ * resource locking determination and contract validation. Validates that service
+ * contracts have unique URIs and no circular dependencies exist.
  *
- * @param param - Configuration object for the orchestrator
- * @param param.types - Optional type hints for better TypeScript inference
- * @param param.types.context - Partial type hint for the workflow context structure (not used at runtime)
- * @param param.contracts - Contract definitions for the orchestrator and its services
- * @param param.contracts.self - The orchestrator's own contract defining accepted events and emitted events
- * @param param.contracts.services - Record of service contracts this orchestrator can invoke, keyed by service name
- * @param param.memory - Generic memory interface for state persistence, locking, and retrieval operations
- * @param param.handler - Versioned orchestration logic handlers mapped by semantic version
- * @param param.executionunits - Resource allocation cost for this orchestrator's execution (default: 0)
- * @param param.requiresResourceLocking - Enable distributed locking for concurrent safety (default: auto-determined by service count)
- * @param param.systemErrorDomain - The domain override of the system error events. (default [event.domain, self.contract.domain, null])
+ * @param param - Configuration parameters for the resumable
+ * @returns Configured ArvoResumable instance ready for event handling
  *
- * @returns A new ArvoResumable orchestrator instance configured with the provided parameters
+ * @throws {ConfigViolation} When service contracts have duplicate URIs
+ * @throws {ConfigViolation} When circular dependency detected (self contract registered as service)
  *
- * @throws {Error} Service contracts have duplicate URIs - Multiple versions of the same contract are not allowed
- * @throws {Error} Circular dependency detected - Self contract is registered as a service, creating execution loops
+ * @example
+ * ```typescript
+ * const resumable = createArvoResumable({
+ *   contracts: {
+ *     self: myOrchestratorContract,
+ *     services: {
+ *      userService: userContract.version('1.0.0'),
+ *      paymentService: paymentContract.version('1.0.0') }
+ *   },
+ *   memory: new SimpleMachineMemory(),
+ *   handler: {
+ *     '1.0.0': async ({ input, service, context }) => {
+ *       // Handler implementation
+ *     }
+ *   },
+ *   executionunits: 1
+ * });
+ * ```
+ *
+ * @see {@link ArvoResumable} For the orchestrator class documentation
+ * @see {@link ArvoResumableHandler} For handler interface details
  */
-export declare const createArvoResumable: <TMemory extends Record<string, any>, TSelfContract extends ArvoOrchestratorContract = ArvoOrchestratorContract, TServiceContract extends Record<string, VersionedArvoContract<any, any>> = Record<string, VersionedArvoContract<any, any>>>(param: {
-    types?: {
-        context?: Partial<TMemory>;
-    };
-    contracts: {
-        self: TSelfContract;
-        services: TServiceContract;
-    };
-    memory: IMachineMemory<Record<string, any>>;
-    handler: ArvoResumableHandler<ArvoResumableState<TMemory>, TSelfContract, TServiceContract>;
-    executionunits?: number;
-    requiresResourceLocking?: boolean;
-    systemErrorDomain?: (string | null)[];
-    spanOptions?: ArvoEventHandlerOtelSpanOptions;
-}) => ArvoResumable<TMemory, TSelfContract, TServiceContract>;
+export declare const createArvoResumable: <TMemory extends Record<string, any> = Record<string, any>, TSelfContract extends ArvoOrchestratorContract = ArvoOrchestratorContract, TServiceContract extends Record<string, VersionedArvoContract<any, any>> = Record<string, VersionedArvoContract<any, any>>>(param: CreateArvoResumableParam<TMemory, TSelfContract, TServiceContract>) => ArvoResumable<TMemory, TSelfContract, TServiceContract>;

package/dist/ArvoResumable/factory.js

@@ -4,28 +4,39 @@ exports.createArvoResumable = void 0;
 var _1 = require(".");
 var servicesValidation_1 = require("../ArvoOrchestrationUtils/servicesValidation");
 /**
- * Factory function for creating ArvoResumable orchestrator instances
+ * Creates a new {@link ArvoResumable} orchestrator instance.
  *
- * Creates a new ArvoResumable orchestrator with type safety and sensible defaults.
- * ArvoResumable provides handler-based workflow orchestration with explicit context management,
- * contract validation, and distributed locking capabilities.
+ * Factory function that constructs a resumable workflow handler with automatic
+ * resource locking determination and contract validation. Validates that service
+ * contracts have unique URIs and no circular dependencies exist.
  *
- * @param param - Configuration object for the orchestrator
- * @param param.types - Optional type hints for better TypeScript inference
- * @param param.types.context - Partial type hint for the workflow context structure (not used at runtime)
- * @param param.contracts - Contract definitions for the orchestrator and its services
- * @param param.contracts.self - The orchestrator's own contract defining accepted events and emitted events
- * @param param.contracts.services - Record of service contracts this orchestrator can invoke, keyed by service name
- * @param param.memory - Generic memory interface for state persistence, locking, and retrieval operations
- * @param param.handler - Versioned orchestration logic handlers mapped by semantic version
- * @param param.executionunits - Resource allocation cost for this orchestrator's execution (default: 0)
- * @param param.requiresResourceLocking - Enable distributed locking for concurrent safety (default: auto-determined by service count)
- * @param param.systemErrorDomain - The domain override of the system error events. (default [event.domain, self.contract.domain, null])
+ * @param param - Configuration parameters for the resumable
+ * @returns Configured ArvoResumable instance ready for event handling
  *
- * @returns A new ArvoResumable orchestrator instance configured with the provided parameters
+ * @throws {ConfigViolation} When service contracts have duplicate URIs
+ * @throws {ConfigViolation} When circular dependency detected (self contract registered as service)
  *
- * @throws {Error} Service contracts have duplicate URIs - Multiple versions of the same contract are not allowed
- * @throws {Error} Circular dependency detected - Self contract is registered as a service, creating execution loops
+ * @example
+ * ```typescript
+ * const resumable = createArvoResumable({
+ *   contracts: {
+ *     self: myOrchestratorContract,
+ *     services: {
+ *      userService: userContract.version('1.0.0'),
+ *      paymentService: paymentContract.version('1.0.0') }
+ *   },
+ *   memory: new SimpleMachineMemory(),
+ *   handler: {
+ *     '1.0.0': async ({ input, service, context }) => {
+ *       // Handler implementation
+ *     }
+ *   },
+ *   executionunits: 1
+ * });
+ * ```
+ *
+ * @see {@link ArvoResumable} For the orchestrator class documentation
+ * @see {@link ArvoResumableHandler} For handler interface details
  */
 var createArvoResumable = function (param) {
     var _a, _b;

package/dist/ArvoResumable/index.d.ts

@@ -1,98 +1,102 @@
 import { type Span } from '@opentelemetry/api';
 import { type ArvoEvent, type ArvoOrchestratorContract, type VersionedArvoContract } from 'arvo-core';
-import type { z } from 'zod';
+import { type EventValidationResult } from '../ArvoOrchestrationUtils/inputValidation';
 import type IArvoEventHandler from '../IArvoEventHandler';
 import type { IMachineMemory } from '../MachineMemory/interface';
 import { SyncEventResource } from '../SyncEventResource/index';
 import type { ArvoEventHandlerOpenTelemetryOptions, ArvoEventHandlerOtelSpanOptions } from '../types';
-import type { ArvoResumableHandler, ArvoResumableState } from './types';
+import type { ArvoResumableHandler, ArvoResumableParam, ArvoResumableState } from './types';
 /**
- * ArvoResumable - A stateful orchestration handler for managing distributed workflows
+ * ArvoResumable complements {@link ArvoOrchestrator} by providing imperative
+ * handler functions for orchestration logic instead of declarative state machines.
+ * While ArvoOrchestrator excels at complex static workflows with deterministic
+ * branching, ArvoResumable handles dynamic orchestrations where branching logic
+ * depends on runtime context and event data.
  *
- * ArvoResumable provides a handler-based approach to workflow orchestration that prioritizes
- * explicit control and simplicity over declarative abstractions. It excels at straightforward
- * request-response patterns and linear workflows while maintaining full type safety and
- * contract validation throughout the execution lifecycle.
- *
- * This class addresses fundamental issues in event-driven architecture including:
- * - Contract management with runtime validation and type safety
- * - Graduated complexity allowing simple workflows to remain simple
- * - Unified event handling across initialization and service responses
- * - Explicit state management without hidden abstractions
- *
- * Key capabilities:
- * - Handler-based workflow orchestration with explicit state control
- * - Contract-driven event validation with runtime schema enforcement
- * - Distributed resource locking for transaction safety
- * - Comprehensive OpenTelemetry integration for observability
- * - Automatic error handling with system error event generation
- * - Support for orchestrator chaining and nested workflow patterns
- * - Domain-based event routing and organization
- *
- * Unlike state machine approaches, ArvoResumable uses imperative handler functions
- * that provide direct control over workflow logic. This makes debugging easier and
- * reduces the learning curve for teams familiar with traditional programming patterns.
- *
- * @see {@link createArvoResumable} Factory function for creating instances
- * @see {@link ArvoResumableHandler} Handler interface documentation
- * @see {@link ArvoResumableState} State structure documentation
+ * Use this for dynamic orchestrations with context-dependent branching
+ * or when preferring imperative programming patterns over state machines.
  */
 export declare class ArvoResumable<TMemory extends Record<string, any> = Record<string, any>, TSelfContract extends ArvoOrchestratorContract = ArvoOrchestratorContract, TServiceContract extends Record<string, VersionedArvoContract<any, any>> = Record<string, VersionedArvoContract<any, any>>> implements IArvoEventHandler {
+    /** Computational cost metric for workflow operations */
     readonly executionunits: number;
+    /** Resource manager for state synchronization and memory access */
     readonly syncEventResource: SyncEventResource<ArvoResumableState<TMemory>>;
-    readonly source: string;
+    /** Versioned handler map for processing workflow events. */
     readonly handler: ArvoResumableHandler<ArvoResumableState<TMemory>, TSelfContract, TServiceContract>;
+    /** Optional domains for routing system error events */
     readonly systemErrorDomain?: (string | null)[];
-    private readonly spanOptions;
+    /** OpenTelemetry span configuration for observability */
+    readonly spanOptions: ArvoEventHandlerOtelSpanOptions;
+    /** Source identifier from the first registered machine */
+    readonly source: string;
+    /**
+     * Contract definitions for the resumable's event interface.
+     * Defines accepted events, emitted events, and service integrations.
+     */
     readonly contracts: {
+        /**
+         * Self contract defining initialization input and completion output structures.
+         */
         self: TSelfContract;
+        /**
+         * Service contracts defining external service interfaces.
+         */
         services: TServiceContract;
     };
+    /** Whether this resumable requires resource locking for concurrent safety */
     get requiresResourceLocking(): boolean;
+    /** Memory interface for state persistence and retrieval */
     get memory(): IMachineMemory<ArvoResumableState<TMemory>>;
+    /** The contract-defined domain for the handler */
     get domain(): string | null;
-    constructor(param: {
-        contracts: {
-            self: TSelfContract;
-            services: TServiceContract;
-        };
-        executionunits: number;
-        memory: IMachineMemory<ArvoResumableState<TMemory>>;
-        requiresResourceLocking?: boolean;
-        handler: ArvoResumableHandler<ArvoResumableState<TMemory>, TSelfContract, TServiceContract>;
-        systemErrorDomain?: (string | null)[];
-        spanOptions?: ArvoEventHandlerOtelSpanOptions;
-    });
-    protected validateInput(event: ArvoEvent, span: Span): {
-        contractType: 'self' | 'service';
-    };
+    constructor(param: ArvoResumableParam<TMemory, TSelfContract, TServiceContract>);
     /**
-     * Executes the orchestration workflow for an incoming event
+     * Validates incoming event against self or service contracts.
+     *
+     * Resolves the appropriate contract (self for initialization, service for responses),
+     * validates schema compatibility, and ensures event data matches contract requirements.
      *
-     * @param event - The triggering event to process
-     * @param opentelemetry - OpenTelemetry configuration for trace inheritance
+     * See {@link validateInputEvent} for more infromation
+     */
+    protected validateInput(event: ArvoEvent, span?: Span): EventValidationResult;
+    /**
+     * Executes the workflow handler for an incoming event.
      *
-     * @returns Object containing domained events
+     * Processes initialization events or service responses through the versioned handler,
+     * manages state persistence, tracks expected events, and generates output events.
+     * Workflows in 'done' status ignore subsequent events without processing.
+     *
+     * For violation errors (transaction, config, contract), the error is thrown to enable
+     * retry mechanisms. For non-violation errors, system error events are emitted to the
+     * workflow initiator, and the workflow enters a terminal failure state.
+     *
+     * @param event - The incoming event triggering handler execution
+     * @param opentelemetry - Optional OpenTelemetry configuration for tracing
+     * @returns Object containing emitted events from the handler or system errors
      *
      * @throws {TransactionViolation} When distributed lock acquisition fails
      * @throws {ConfigViolation} When handler resolution or contract validation fails
      * @throws {ContractViolation} When event schema validation fails
-     * @throws {ExecutionViolation} When workflow execution encounters critical errors
+     * @throws {ExecutionViolation} When workflow execution encounters critical errors defined by the handler developer
      */
     execute(event: ArvoEvent, opentelemetry?: ArvoEventHandlerOpenTelemetryOptions): Promise<{
         events: ArvoEvent[];
     }>;
-    get systemErrorSchema(): import("arvo-core").ArvoContractRecord<`sys.arvo.orc.${string}.error`, z.ZodObject<{
-        errorName: z.ZodString;
-        errorMessage: z.ZodString;
-        errorStack: z.ZodNullable<z.ZodString>;
-    }, "strip", z.ZodTypeAny, {
-        errorName: string;
-        errorMessage: string;
-        errorStack: string | null;
-    }, {
-        errorName: string;
-        errorMessage: string;
-        errorStack: string | null;
-    }>>;
+    get systemErrorSchema(): {
+        domain: (string | null)[] | undefined;
+        type: `sys.arvo.orc.${string}.error`;
+        schema: import("zod").ZodObject<{
+            errorName: import("zod").ZodString;
+            errorMessage: import("zod").ZodString;
+            errorStack: import("zod").ZodNullable<import("zod").ZodString>;
+        }, "strip", import("zod").ZodTypeAny, {
+            errorName: string;
+            errorMessage: string;
+            errorStack: string | null;
+        }, {
+            errorName: string;
+            errorMessage: string;
+            errorStack: string | null;
+        }>;
+    };
 }