arvo-event-handler 3.0.14 → 3.0.16

package/dist/ArvoMachine/createMachine.js

@@ -28,170 +28,22 @@ var arvo_core_1 = require("arvo-core");
 var xstate_1 = require("xstate");
 var _1 = __importDefault(require("."));
 var servicesValidation_1 = require("../ArvoOrchestrationUtils/servicesValidation");
+var errors_1 = require("../errors");
 var object_1 = require("../utils/object");
 var utils_1 = require("./utils");
 /**
  * Establishes the foundation for creating Arvo-compatible state machines.
  *
- * This function configures the core elements of an Arvo state machine, including
- * built-in actions like `enqueueArvoEvent`, and enforces Arvo-specific constraints
- * to ensure compatibility with the Arvo event-driven system.
+ * Designed for synchronous state machine orchestrations in Arvo's event-driven architecture.
+ * Builds upon XState with Arvo-specific constraints to enforce predictable state transitions.
  *
- * @param param - Configuration object for the machine setup
- * @returns An object containing the `createMachine` function
- * @throws {Error} If 'actors', 'delays', or reserved action names are used in the configuration
- *
- * @description
- * `setupArvoMachine` is a crucial function in the Arvo ecosystem, designed to create
- * synchronous state machine orchestrations for Arvo's event-driven architecture.
- * It builds upon XState, providing a tailored implementation that:
- *
- * 1. Enforces synchronous behavior to maintain predictable state transitions
- * 3. Implements Arvo-specific constraints and features
- *
- * Key features:
- * - Synchronous execution: Ensures deterministic behavior in event-driven systems
- * - Built-in actions: Includes `enqueueArvoEvent` for Arvo event handling
- * - Constraint checking: Prevents usage of asynchronous features like 'actors' or 'delays'
- *
- * @remarks
- * While `setupArvoMachine` is based on XState's `setup` and `createMachine` functions,
- * it includes Arvo-specific modifications and restrictions. For a deeper understanding
- * of the underlying XState concepts, refer to the official XState documentation:
- * - XState setup: https://stately.ai/docs/setup
- * - XState createMachine: https://stately.ai/docs/machines
- *
- * @example
- * Here's a comprehensive example demonstrating how to use `setupArvoMachine`:
- *
- * ```typescript
- * import { setupArvoMachine } from 'arvo-xstate'
- * import { createArvoOrchestratorContract, ArvoErrorSchema, createArvoContract } from 'arvo-core'
- * import { z } from 'zod'
- *
- * // Define the LLM orchestrator contract
- * const llmContract = createArvoOrchestratorContract({
- *   uri: `#/orchestrators/llm/`,
- *   type: 'llm',
- *   versions: {
- *     '0.0.1': {
- *       init: z.object({
- *         request: z.string(),
- *         llm: z.enum(['gpt-4', 'gpt-4o']),
- *       }),
- *       complete: z.object({
- *         response: z.string(),
- *       })
- *     }
- *   }
- * })
- *
- * // Define the OpenAI service contract
- * const openAiContract = createArvoContract({
- *   uri: `#/services/openai`,
- *   type: 'com.openai.completions',
- *   versions: {
- *     '0.0.1': {
- *       accepts: z.object({
- *         request: z.string()
- *       }),
- *       emits: {
- *         'evt.openai.completions.success': z.object({
- *           response: z.string(),
- *         })
- *       }
- *     }
- *   }
- * })
- *
- * const machineId = 'machineV100'
- *
- * // Set up the Arvo machine
- * const llmMachine = setupArvoMachine({
- *   contracts: {
- *     self: llmContract.version('0.0.1'),
- *     services: {
- *       openAiContract.version('0.0.1'),
- *     }
- *   },
- *   types: {
- *     context: {} as {
- *       request: string,
- *       llm: string,
- *       response: string | null,
- *       errors: z.infer<typeof ArvoErrorSchema>[]
- *     },
- *     tags: {} as 'pending' | 'success' | 'error',
- *   },
- *   actions: {
- *     log: ({context, event}) => console.log({context, event})
- *   },
- *   guards: {
- *     isValid: ({context, event}) => Boolean(context.request)
- *   }
- * }).createMachine({
- *   id: machineId,
- *   context: ({input}) => ({
- *     request: input.request,
- *     llm: input.llm,
- *     response: null,
- *     errors: [],
- *   }),
- *   initial: 'validate',
- *   states: {
- *     validate: {
- *       always: [
- *         {
- *           guard: 'isValid',
- *           target: 'llm',
- *         },
- *         {
- *           target: 'error',
- *         }
- *       ]
- *     },
- *     llm: {
- *       entry: [
- *         {
- *           type: 'log',
- *         },
- *         emit(({context}) => ({
- *           type: 'com.openai.completions',
- *           data: {
- *             request: context.request,
- *           },
- *         }))
- *       ],
- *       on: {
- *         'evt.openai.completions.success': {
- *           actions: [
- *             assign({response: ({event}) => event.response})
- *           ],
- *           target: 'done'
- *         },
- *         'sys.com.openai.completions.error': {
- *           actions: [
- *             assign({errors: ({context, event}) => [...context.errors, event.body]})
- *           ],
- *           target: 'error'
- *         }
- *       }
- *     },
- *     done: {
- *       type: 'final'
- *     },
- *     error: {
- *       type: 'final'
- *     },
- *   }
- * });
- * ```
- *
- * This example demonstrates:
- * 1. Defining Arvo contracts for the orchestrator and a service
- * 2. Setting up an Arvo machine with contracts, types, actions, and guards
- * 3. Creating a machine with states for validation, LLM interaction, and error handling
- * 4. Using XState features like `emit` bound with Arvo contracts for event emitting and event handling via transitions
+ * @throws {ConfigViolation} When configuration violates Arvo constraints:
+ * - Using `actors` or `delays` (async behavior not supported)
+ * - Overriding reserved `enqueueArvoEvent` action name
+ * - Machine version mismatch with contract version
+ * - Using `invoke` or `after` in state configurations
+ * - Service contracts with duplicate URIs (multiple versions of same contract)
+ * - Circular dependency (self contract URI matches a service contract URI)
  */
 function setupArvoMachine(param) {
     var _a, _b;
@@ -199,13 +51,13 @@ function setupArvoMachine(param) {
         return (0, arvo_core_1.cleanString)("\n      Configuration Error: '".concat(type, "' not supported in Arvo machines\n      \n      Arvo machines do not support XState ").concat(type === 'actor' ? 'actors' : 'delay transitions', " as they introduce asynchronous behavior.\n      \n      To fix:\n      1. Remove the '").concat(type, "' configuration\n      2. Use Arvo's event-driven patterns instead for asynchronous operations\n    "));
     };
     if (param.actors) {
-        throw new Error(createConfigErrorMessage('actor'));
+        throw new errors_1.ConfigViolation(createConfigErrorMessage('actor'));
     }
     if (param.delays) {
-        throw new Error(createConfigErrorMessage('delays'));
+        throw new errors_1.ConfigViolation(createConfigErrorMessage('delays'));
     }
     if ((_a = param.actions) === null || _a === void 0 ? void 0 : _a.enqueueArvoEvent) {
-        throw new Error((0, arvo_core_1.cleanString)("\n        Configuration Error: Reserved action name 'enqueueArvoEvent'\n        \n        'enqueueArvoEvent' is an internal Arvo system action and cannot be overridden.\n        \n        To fix: Use a different name for your action, such as:\n        - 'queueCustomEvent'\n        - 'scheduleEvent'\n        - 'dispatchEvent'\n      "));
+        throw new errors_1.ConfigViolation((0, arvo_core_1.cleanString)("\n        Configuration Error: Reserved action name 'enqueueArvoEvent'\n        \n        'enqueueArvoEvent' is an internal Arvo system action and cannot be overridden.\n        \n        To fix: Use a different name for your action, such as:\n        - 'queueCustomEvent'\n        - 'scheduleEvent'\n        - 'dispatchEvent'\n      "));
     }
     (0, servicesValidation_1.servicesValidation)(param.contracts, 'machine');
     var combinedActions = __assign(__assign({}, ((_b = param.actions) !== null && _b !== void 0 ? _b : {})), { enqueueArvoEvent: (0, xstate_1.assign)(function (_a, param) {
@@ -222,24 +74,12 @@ function setupArvoMachine(param) {
     });
     /**
      * Creates an Arvo-compatible XState machine.
-     *
-     * @param config - The configuration object for the machine
-     * @returns An ArvoMachine instance
-     *
-     * @throws Error if 'invoke' or 'after' configurations are used
-     *
-     * @remarks
-     * This function creates a state machine based on the provided configuration.
-     * It performs additional checks to ensure the machine adheres to Arvo's constraints,
-     * such as disallowing 'invoke' and 'after' configurations which could introduce
-     * asynchronous behavior.
-     * ```
      */
     var createMachine = function (config) {
-        var _a, _b;
+        var _a, _b, _c, _d, _e;
         var machineVersion = (_a = config.version) !== null && _a !== void 0 ? _a : param.contracts.self.version;
         if (machineVersion !== param.contracts.self.version) {
-            throw new Error("Version mismatch: Machine version must be '".concat(param.contracts.self.version, "' or undefined, received '").concat(config.version, "'"));
+            throw new errors_1.ConfigViolation("Version mismatch: Machine version must be '".concat(param.contracts.self.version, "' or undefined, received '").concat(config.version, "'"));
         }
         var createConfigErrorMessage = function (type, path) {
             var location = path.join(' > ');
@@ -253,16 +93,16 @@ function setupArvoMachine(param) {
                 return (0, arvo_core_1.cleanString)("\n          Configuration Error: Reserved action name 'enqueueArvoEvent'\n          \n          Location: ".concat(location, "\n          \n          'enqueueArvoEvent' is an internal Arvo system action and cannot be used in machine configurations.\n          \n          To fix: Use a different name for your action\n        "));
             }
         };
-        for (var _i = 0, _c = (0, object_1.getAllPaths)((_b = config.states) !== null && _b !== void 0 ? _b : {}); _i < _c.length; _i++) {
-            var item = _c[_i];
+        for (var _i = 0, _f = (0, object_1.getAllPaths)((_b = config.states) !== null && _b !== void 0 ? _b : {}); _i < _f.length; _i++) {
+            var item = _f[_i];
             if (item.path.includes('invoke')) {
-                throw new Error(createConfigErrorMessage('invoke', item.path));
+                throw new errors_1.ConfigViolation((_c = createConfigErrorMessage('invoke', item.path)) !== null && _c !== void 0 ? _c : 'Invoke not allowed');
             }
             if (item.path.includes('after')) {
-                throw new Error(createConfigErrorMessage('after', item.path));
+                throw new errors_1.ConfigViolation((_d = createConfigErrorMessage('after', item.path)) !== null && _d !== void 0 ? _d : 'After not allowed');
             }
             if (item.path.includes('enqueueArvoEvent')) {
-                throw new Error(createConfigErrorMessage('enqueueArvoEvent', item.path));
+                throw new errors_1.ConfigViolation((_e = createConfigErrorMessage('enqueueArvoEvent', item.path)) !== null && _e !== void 0 ? _e : 'EnqueueArvoEvent not allowed');
             }
         }
         var machine = systemSetup.createMachine(__assign({}, config));
@@ -271,5 +111,43 @@ function setupArvoMachine(param) {
         var requiresLocking = hasParallelStates || hasMultipleNonSystemErrorEvents;
         return new _1.default(config.id, machineVersion, param.contracts, machine, requiresLocking);
     };
-    return { createMachine: createMachine };
+    return {
+        /**
+         * Creates an Arvo-compatible state machine with the specified configuration.
+         *
+         * Constructs a fully-typed state machine that orchestrates event-driven workflows
+         * using the contracts and types defined in setup. The machine enforces synchronous
+         * execution and validates configuration against Arvo constraints.
+         *
+         * For more information, see [xstate state machine docs](https://stately.ai/docs/states)
+         * @returns {ArvoMachine} A configured Arvo machine ready for execution
+         * @throws {ConfigViolation} When configuration violates Arvo constraints (see {@link setupArvoMachine} docs)
+         *
+         * @example
+         * ```typescript
+         * const machine = setup.createMachine({
+         *   id: 'machineV100',
+         *   initial: 'verifying',
+         *   context: ({ input }) => ({
+         *     userId: input.data.userId,
+         *     verified: false
+         *   }),
+         *   states: {
+         *     verifying: {
+         *       on: {
+         *         'com.user.verified': {
+         *           target: 'active',
+         *           actions: { type: 'updateUser' }
+         *         }
+         *       }
+         *     },
+         *     active: {
+         *       type: 'final'
+         *     }
+         *   }
+         * });
+         * ```
+         */
+        createMachine: createMachine,
+    };
 }

package/dist/ArvoMachine/index.d.ts

@@ -1,13 +1,13 @@
-import { type ArvoContract, type ArvoEvent, type ArvoOrchestratorContract, type ArvoSemanticVersion, type VersionedArvoContract } from 'arvo-core';
+import type { Span } from '@opentelemetry/api';
+import type { ArvoContract, ArvoEvent, ArvoOrchestratorContract, ArvoSemanticVersion, VersionedArvoContract } from 'arvo-core';
 import type { AnyActorLogic } from 'xstate';
-import type { z } from 'zod';
+import { type EventValidationResult } from '../ArvoOrchestrationUtils/inputValidation';
 /**
  * Represents an ArvoMachine object that can be consumed by an Arvo orchestrator.
  * ArvoMachine encapsulates the logic and metadata required for an Arvo-compatible
  * state machine. It combines XState's actor logic with Arvo-specific contracts
  * and versioning information.
  *
- * @remarks
  * It is strongly recommended to use `setupArvoMachine(...).createMachine(...)`
  * instead of creating this object directly. The setup function provides additional
  * type safety and validation that helps prevent runtime errors.
@@ -21,27 +21,6 @@ export default class ArvoMachine<TId extends string, TVersion extends ArvoSemant
     };
     readonly logic: TLogic;
     readonly requiresResourceLocking: boolean;
-    /**
-     * Creates a new ArvoMachine instance.
-     *
-     * @param id - A unique identifier for the machine. This ID must be unique within
-     *            the scope of an orchestrator and is used for routing and logging.
-     *
-     * @param version - The semantic version of the machine. Must follow semver format
-     *                and match the version specified in the contract.
-     *
-     * @param contracts - Configuration object containing contract definitions
-     * @param contracts.self - The contract defining this machine's interface and capabilities
-     * @param contracts.services - Record of contracts for services this machine can interact with
-     *
-     * @param logic - The XState actor logic that defines the machine's behavior,
-     *               including states, transitions, and actions.
-     * @param [requiresResourceLocking] - Optional flag indicating if the machine needs distributed locks.
-     *                                    False when machine has no parallel states and executes sequentially.
-     *                                    Defaults to true.
-     *
-     * @throws {Error} When contracts are invalid or incompatible with the specified version
-     */
     constructor(id: TId, version: TVersion, contracts: {
         self: TSelfContract;
         services: TServiceContract;
@@ -55,39 +34,8 @@ export default class ArvoMachine<TId extends string, TVersion extends ArvoSemant
      * Performs validation for both self-contract events and service contract events.
      *
      * @param event - The event to validate
-     * @returns A validation result object:
-     *   - "VALID" - Event is valid and can be processed
-     *   - "CONTRACT_UNRESOLVED" - No matching contract found for the event
-     *   - "INVALID" - Event dataschema conflict with contract
-     *   - "INVALID_DATA" - Event data conflicts with contract
      *
-     * @example
-     * ```typescript
-     * const result = machine.validateInput(event);
-     *  if (result.type === "VALID") {
-     *   // Process the event
-     * } else if (result.type === "INVALID") {
-     *   console.error(result.error);
-     * } else {
-     *   // Handle unresolved contract
-     * }
-     * ```
-     *
-     * @remarks
-     * The validation process includes:
-     * - Finding a matching contract (self or service)
-     * - Validating dataschema URI and version if present
-     * - Validating event data against the contract schema
+     * See {@link validateInputEvent} for more infromation
      */
-    validateInput(event: ArvoEvent): {
-        type: 'VALID';
-    } | {
-        type: 'CONTRACT_UNRESOLVED';
-    } | {
-        type: 'INVALID';
-        error: Error;
-    } | {
-        type: 'INVALID_DATA';
-        error: z.ZodError;
-    };
+    validateInput(event: ArvoEvent, span?: Span): EventValidationResult;
 }

package/dist/ArvoMachine/index.js

@@ -1,48 +1,17 @@
 "use strict";
-var __spreadArray = (this && this.__spreadArray) || function (to, from, pack) {
-    if (pack || arguments.length === 2) for (var i = 0, l = from.length, ar; i < l; i++) {
-        if (ar || !(i in from)) {
-            if (!ar) ar = Array.prototype.slice.call(from, 0, i);
-            ar[i] = from[i];
-        }
-    }
-    return to.concat(ar || Array.prototype.slice.call(from));
-};
 Object.defineProperty(exports, "__esModule", { value: true });
-var arvo_core_1 = require("arvo-core");
+var inputValidation_1 = require("../ArvoOrchestrationUtils/inputValidation");
 /**
  * Represents an ArvoMachine object that can be consumed by an Arvo orchestrator.
  * ArvoMachine encapsulates the logic and metadata required for an Arvo-compatible
  * state machine. It combines XState's actor logic with Arvo-specific contracts
  * and versioning information.
  *
- * @remarks
  * It is strongly recommended to use `setupArvoMachine(...).createMachine(...)`
  * instead of creating this object directly. The setup function provides additional
  * type safety and validation that helps prevent runtime errors.
  */
 var ArvoMachine = /** @class */ (function () {
-    /**
-     * Creates a new ArvoMachine instance.
-     *
-     * @param id - A unique identifier for the machine. This ID must be unique within
-     *            the scope of an orchestrator and is used for routing and logging.
-     *
-     * @param version - The semantic version of the machine. Must follow semver format
-     *                and match the version specified in the contract.
-     *
-     * @param contracts - Configuration object containing contract definitions
-     * @param contracts.self - The contract defining this machine's interface and capabilities
-     * @param contracts.services - Record of contracts for services this machine can interact with
-     *
-     * @param logic - The XState actor logic that defines the machine's behavior,
-     *               including states, transitions, and actions.
-     * @param [requiresResourceLocking] - Optional flag indicating if the machine needs distributed locks.
-     *                                    False when machine has no parallel states and executes sequentially.
-     *                                    Defaults to true.
-     *
-     * @throws {Error} When contracts are invalid or incompatible with the specified version
-     */
     function ArvoMachine(id, version, contracts, logic, requiresResourceLocking) {
         if (requiresResourceLocking === void 0) { requiresResourceLocking = true; }
         this.id = id;
@@ -66,94 +35,16 @@ var ArvoMachine = /** @class */ (function () {
      * Performs validation for both self-contract events and service contract events.
      *
      * @param event - The event to validate
-     * @returns A validation result object:
-     *   - "VALID" - Event is valid and can be processed
-     *   - "CONTRACT_UNRESOLVED" - No matching contract found for the event
-     *   - "INVALID" - Event dataschema conflict with contract
-     *   - "INVALID_DATA" - Event data conflicts with contract
-     *
-     * @example
-     * ```typescript
-     * const result = machine.validateInput(event);
-     *  if (result.type === "VALID") {
-     *   // Process the event
-     * } else if (result.type === "INVALID") {
-     *   console.error(result.error);
-     * } else {
-     *   // Handle unresolved contract
-     * }
-     * ```
      *
-     * @remarks
-     * The validation process includes:
-     * - Finding a matching contract (self or service)
-     * - Validating dataschema URI and version if present
-     * - Validating event data against the contract schema
+     * See {@link validateInputEvent} for more infromation
      */
-    ArvoMachine.prototype.validateInput = function (event) {
-        var _a, _b, _c;
-        var resovledContract = null;
-        var contractType;
-        if (event.type === this.contracts.self.accepts.type) {
-            resovledContract = this.contracts.self;
-            contractType = 'self';
-        }
-        else {
-            resovledContract =
-                (_a = Object.fromEntries(Object.values(this.contracts.services).reduce(function (acc, cur) { return __spreadArray(__spreadArray([], acc, true), __spreadArray(__spreadArray([], cur.emitList, true), [cur.systemError], false).map(function (item) { return [item.type, cur]; }), true); }, []))[event.type]) !== null && _a !== void 0 ? _a : null;
-            contractType = 'service';
-        }
-        if (!resovledContract) {
-            (0, arvo_core_1.logToSpan)({
-                level: 'WARNING',
-                message: "Contract resolution failed: No matching contract found for event (id='".concat(event.id, "', type='").concat(event.type, "')"),
-            });
-            return {
-                type: 'CONTRACT_UNRESOLVED',
-            };
-        }
-        (0, arvo_core_1.logToSpan)({
-            level: 'INFO',
-            message: "Contract resolved: Contract(uri='".concat(resovledContract.uri, "', version='").concat(resovledContract.version, "', type='").concat(resovledContract.accepts.type, "') for the event(id='").concat(event.id, "', type='").concat(event.type, "')"),
+    ArvoMachine.prototype.validateInput = function (event, span) {
+        return (0, inputValidation_1.validateInputEvent)({
+            event: event,
+            selfContract: this.contracts.self,
+            serviceContracts: this.contracts.services,
+            span: span,
         });
-        var dataschema = arvo_core_1.EventDataschemaUtil.parse(event);
-        if (!dataschema) {
-            (0, arvo_core_1.logToSpan)({
-                level: 'WARNING',
-                message: "Dataschema resolution failed: Unable to parse dataschema='".concat(event.dataschema, "' for event(id='").concat(event.id, "', type='").concat(event.type, "')"),
-            });
-        }
-        else {
-            (0, arvo_core_1.logToSpan)({
-                level: 'INFO',
-                message: "Dataschema resolved: ".concat(event.dataschema, " matches contract(uri='").concat(resovledContract.uri, "', version='").concat(resovledContract.version, "')"),
-            });
-            if (dataschema.uri !== resovledContract.uri) {
-                return {
-                    type: 'INVALID',
-                    error: new Error("Contract URI mismatch: ".concat(contractType, " Contract(uri='").concat(resovledContract.uri, "', type='").concat(resovledContract.accepts.type, "') does not match Event(dataschema='").concat(event.dataschema, "', type='").concat(event.type, "')")),
-                };
-            }
-            if (!(0, arvo_core_1.isWildCardArvoSematicVersion)(dataschema.version) && dataschema.version !== resovledContract.version) {
-                return {
-                    type: 'INVALID',
-                    error: new Error("Contract version mismatch: ".concat(contractType, " Contract(version='").concat(resovledContract.version, "', type='").concat(resovledContract.accepts.type, "', uri=").concat(resovledContract.uri, ") does not match Event(dataschema='").concat(event.dataschema, "', type='").concat(event.type, "')")),
-                };
-            }
-        }
-        var validationSchema = contractType === 'self'
-            ? resovledContract.accepts.schema
-            : ((_b = resovledContract.emits[event.type]) !== null && _b !== void 0 ? _b : resovledContract.systemError.schema);
-        var error = (_c = validationSchema.safeParse(event.data).error) !== null && _c !== void 0 ? _c : null;
-        if (error) {
-            return {
-                type: 'INVALID_DATA',
-                error: error,
-            };
-        }
-        return {
-            type: 'VALID',
-        };
     };
     return ArvoMachine;
 }());