arvo-event-handler 2.3.1 → 3.0.1

package/dist/ArvoOrchestrator/types.d.ts

@@ -0,0 +1,98 @@
+import type { ArvoEvent, InferArvoEvent } from 'arvo-core';
+import type { Snapshot } from 'xstate';
+import type ArvoMachine from '../ArvoMachine';
+import type { IMachineExectionEngine } from '../MachineExecutionEngine/interface';
+import type { IMachineMemory } from '../MachineMemory/interface';
+import type { IMachineRegistry } from '../MachineRegistry/interface';
+export type TryFunctionOutput<TData, TError extends Error> = {
+    type: 'success';
+    data: TData;
+} | {
+    type: 'error';
+    error: TError;
+};
+/**
+ * Represents the state record stored in machine memory.
+ */
+export type MachineMemoryRecord = {
+    /** Unique identifier for the machine 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.
+     *
+     * - For root orchestrations: null
+     * - For nested orchestrations: contains the subject of the parent orchestration
+     * - Extracted from the `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.
+     *
+     * - 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
+     *
+     * This enables tracing the entire execution path and ensures completion events reference
+     * the original triggering event rather than just the immediate previous step.
+     */
+    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
+     *
+     * 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.
+     */
+    status: string;
+    /** Current value stored in the machine state */
+    value: string | Record<string, any> | null;
+    /** XState snapshot representing the machine's current state */
+    state: Snapshot<any>;
+    events: {
+        /** The event consumed by the machine in the last session */
+        consumed: InferArvoEvent<ArvoEvent> | null;
+        /**
+         * The events produced by the machine in the last session
+         */
+        produced: InferArvoEvent<ArvoEvent>[];
+    };
+    /** Machine definition string */
+    machineDefinition: string | null;
+};
+/**
+ * Interface defining the core components of an Arvo orchestrator.
+ */
+export interface IArvoOrchestrator {
+    /** The cost of the execution of the orchestrator */
+    executionunits: number;
+    /** Memory interface for storing and retrieving machine state */
+    memory: IMachineMemory<MachineMemoryRecord>;
+    /** Registry for managing and resolving machine instances */
+    registry: IMachineRegistry;
+    /** Engine responsible for machine execution */
+    executionEngine: IMachineExectionEngine;
+    requiresResourceLocking: boolean;
+}
+/**
+ * Configuration interface for creating an Arvo orchestrator instance.
+ */
+export interface ICreateArvoOrchestrator {
+    /** Memory interface for storing and retrieving machine state */
+    memory: IMachineMemory<MachineMemoryRecord>;
+    /** The cost of the execution of the orchestrator */
+    executionunits: number;
+    /**
+     * Collection of state machines to be managed by the orchestrator.
+     * All machines must have the same source identifier.
+     */
+    machines: ArvoMachine<any, any, any, any, any>[];
+}

package/dist/ArvoResumable/factory.d.ts

@@ -0,0 +1,50 @@
+import type { ArvoOrchestratorContract, VersionedArvoContract } from 'arvo-core';
+import type { ArvoResumableHandler, ArvoResumableState } from './types';
+import type { IMachineMemory } from '../MachineMemory/interface';
+import { ArvoResumable } from '.';
+/**
+ * Factory function for creating ArvoResumable orchestrator instances
+ *
+ * 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.
+ *
+ * @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)
+ *
+ * @returns A new ArvoResumable orchestrator instance configured with the provided parameters
+ *
+ * @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
+ *
+ * @remarks
+ * **Resource Locking:**
+ * When `requiresResourceLocking` is not specified, it defaults to `true` when multiple
+ * services are configured (indicating potential concurrent operations) and `false` for
+ * single-service orchestrations.
+ *
+ * **Contract Validation:**
+ * The factory validates that all service contracts have unique URIs and prevents
+ * circular dependencies where the orchestrator's own contract is registered as a service.
+ */
+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;
+}) => ArvoResumable<TMemory, TSelfContract, TServiceContract>;

package/dist/ArvoResumable/factory.js

@@ -0,0 +1,70 @@
+"use strict";
+var __assign = (this && this.__assign) || function () {
+    __assign = Object.assign || function(t) {
+        for (var s, i = 1, n = arguments.length; i < n; i++) {
+            s = arguments[i];
+            for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p))
+                t[p] = s[p];
+        }
+        return t;
+    };
+    return __assign.apply(this, arguments);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createArvoResumable = void 0;
+var _1 = require(".");
+var utils_1 = require("../ArvoMachine/utils");
+var uuid_1 = require("uuid");
+/**
+ * Factory function for creating ArvoResumable orchestrator instances
+ *
+ * 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.
+ *
+ * @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)
+ *
+ * @returns A new ArvoResumable orchestrator instance configured with the provided parameters
+ *
+ * @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
+ *
+ * @remarks
+ * **Resource Locking:**
+ * When `requiresResourceLocking` is not specified, it defaults to `true` when multiple
+ * services are configured (indicating potential concurrent operations) and `false` for
+ * single-service orchestrations.
+ *
+ * **Contract Validation:**
+ * The factory validates that all service contracts have unique URIs and prevents
+ * circular dependencies where the orchestrator's own contract is registered as a service.
+ */
+var createArvoResumable = function (param) {
+    var _a;
+    var _b, _c;
+    var __areServiceContractsUnique = (0, utils_1.areServiceContractsUnique)(param.contracts.services);
+    if (!__areServiceContractsUnique.result) {
+        throw new Error("The service contracts must have unique URIs. Multiple versions of the same contract are not allow. The contracts '".concat(__areServiceContractsUnique.keys[0], "' and '").concat(__areServiceContractsUnique.keys[1], "' have the same URI '").concat(__areServiceContractsUnique.contractUri, "'"));
+    }
+    var __checkIfSelfIsAService = (0, utils_1.areServiceContractsUnique)(__assign(__assign({}, param.contracts.services), (_a = {}, _a[(0, uuid_1.v4)()] = param.contracts.self, _a)));
+    if (!__checkIfSelfIsAService.result) {
+        throw new Error("Circular dependency detected: Machine with URI '".concat(param.contracts.self.uri, "' is registered as service '").concat(__checkIfSelfIsAService.keys[1], "'. Self-referential services create execution loops and are prohibited."));
+    }
+    return new _1.ArvoResumable({
+        contracts: param.contracts,
+        memory: param.memory,
+        handler: param.handler,
+        executionunits: (_b = param.executionunits) !== null && _b !== void 0 ? _b : 0,
+        requiresResourceLocking: (_c = param.requiresResourceLocking) !== null && _c !== void 0 ? _c : Object.keys(param.contracts.services).length > 1,
+    });
+};
+exports.createArvoResumable = createArvoResumable;

package/dist/ArvoResumable/index.d.ts

@@ -0,0 +1,141 @@
+import { type ArvoEvent, type ArvoOrchestratorContract, type VersionedArvoContract, type OpenTelemetryHeaders, type ArvoSemanticVersion } from 'arvo-core';
+import type { z } from 'zod';
+import type { ArvoResumableHandler, ArvoResumableState } from './types';
+import type { IMachineMemory } from '../MachineMemory/interface';
+import { SyncEventResource } from '../SyncEventResource/index';
+import type { EnqueueArvoEventActionParam } from '../ArvoMachine/types';
+import AbstractArvoEventHandler from '../AbstractArvoEventHandler';
+import type { ArvoEventHandlerOpenTelemetryOptions } from '../types';
+/**
+ * ArvoResumable - A stateful orchestration handler for managing distributed workflows
+ *
+ * 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
+ */
+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>>> extends AbstractArvoEventHandler {
+    readonly executionunits: number;
+    readonly syncEventResource: SyncEventResource<ArvoResumableState<TMemory>>;
+    readonly source: string;
+    readonly handler: ArvoResumableHandler<ArvoResumableState<TMemory>, TSelfContract, TServiceContract>;
+    readonly contracts: {
+        self: TSelfContract;
+        services: TServiceContract;
+    };
+    get requiresResourceLocking(): boolean;
+    get memory(): IMachineMemory<ArvoResumableState<TMemory>>;
+    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>;
+    });
+    protected validateInput(event: ArvoEvent): {
+        contractType: 'self' | 'service';
+    };
+    /**
+     * Creates emittable event from execution result
+     * @param event - Source event to emit
+     * @param otelHeaders - OpenTelemetry headers
+     * @param orchestrationParentSubject - Parent orchestration subject
+     * @param sourceEvent - Original triggering event
+     * @param selfVersionedContract - The self versioned contract
+     * @param initEventId - The id of the event which initiated the orchestration in the first place
+     * @param _domain - The domain of the event.
+     *
+     * @throws {ContractViolation} On schema/contract mismatch
+     * @throws {ExecutionViolation} On invalid parentSubject$$ format
+     */
+    protected createEmittableEvent(event: EnqueueArvoEventActionParam, otelHeaders: OpenTelemetryHeaders, orchestrationParentSubject: string | null, sourceEvent: ArvoEvent, selfVersionedContract: VersionedArvoContract<TSelfContract, ArvoSemanticVersion>, initEventId: string, _domain: string | null | undefined): ArvoEvent;
+    /**
+     * Executes the orchestration workflow for an incoming event
+     *
+     * This is the main orchestration entry point that coordinates the complete event
+     * processing lifecycle. It implements the core workflow execution pattern including
+     * validation, locking, state management, handler invocation, event creation, and
+     * persistence with comprehensive error handling and observability.
+     *
+     * The execution process follows these phases:
+     * 1. **Validation & Setup** - Subject parsing, handler resolution, contract validation
+     * 2. **Resource Management** - Distributed lock acquisition and state loading
+     * 3. **Handler Execution** - Context preparation and user handler invocation
+     * 4. **Event Processing** - Result transformation and emittable event creation
+     * 5. **State Persistence** - Atomic state updates and event tracking
+     * 6. **Cleanup & Return** - Resource release and structured result return
+     *
+     * @param event - The triggering event to process
+     * @param opentelemetry - OpenTelemetry configuration for trace inheritance
+     *
+     * @returns Object containing domained events
+     *
+     * @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
+     *
+     * @remarks
+     * **Execution Safety:**
+     * The method implements comprehensive error recovery with proper resource cleanup
+     * in all execution paths. ViolationErrors are rethrown for system handling while
+     * workflow errors become system error events for graceful degradation.
+     *
+     * **State Management:**
+     * Workflow state is managed atomically with optimistic concurrency control.
+     * Status transitions from 'active' to 'done' occur only when completion events
+     * are generated, ensuring proper workflow lifecycle management.
+     *
+     * **Observability:**
+     * Complete execution is traced using OpenTelemetry with detailed span attributes
+     * for debugging and monitoring. Event metadata includes processing context and
+     * routing information for operational visibility.
+     *
+     * **Terminal State Handling:**
+     * Workflows in 'done' status ignore additional events to prevent state corruption
+     * while preserving audit trails for completed workflow executions.
+     */
+    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;
+    }>>;
+}