arvo-event-handler 2.3.1 → 3.0.1

package/dist/ArvoMachine/index.js

@@ -0,0 +1,160 @@
+"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");
+/**
+ * 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;
+        this.version = version;
+        this.contracts = contracts;
+        this.logic = logic;
+        this.requiresResourceLocking = requiresResourceLocking;
+    }
+    Object.defineProperty(ArvoMachine.prototype, "source", {
+        /**
+         * Gets the event type that this machine accepts, as defined in its contract.
+         */
+        get: function () {
+            return this.contracts.self.accepts.type;
+        },
+        enumerable: false,
+        configurable: true
+    });
+    /**
+     * Validates an event against the machine's contracts and data schemas.
+     * 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
+     */
+    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, "')"),
+        });
+        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;
+}());
+exports.default = ArvoMachine;

package/dist/ArvoMachine/types.d.ts

@@ -0,0 +1,194 @@
+import type { ArvoContract, ArvoEventData, ArvoOrchestratorEventTypeGen, ArvoSemanticVersion, CloudEventExtension, InferVersionedArvoContract, VersionedArvoContract } from 'arvo-core';
+import type { Invert, IsNever, ParameterizedObject, UnknownActorLogic, Values } from 'xstate';
+import type { z } from 'zod';
+/**
+ * Represents an extended context for Arvo XState machines, including additional properties
+ * for volatile and internal data.
+ *
+ * @remarks
+ * This type extends the base XState MachineContext with additional properties
+ * to provide more flexibility and organization in storing machine-related data.
+ *
+ * The `$$` suffix in property names is used to indicate special storage objects within the context.
+ *
+ * @note
+ * To avoid runtime errors, it is recommended not to use `arvo$$` object at all in the
+ * machine context
+ */
+export type ArvoMachineContext = {
+    arvo$$?: {
+        volatile$$?: {
+            [key: string]: any;
+            eventQueue$$?: EnqueueArvoEventActionParam[];
+        };
+    };
+};
+/**
+ * Represents the parameters for the emitArvoEvent action in ArvoXState.
+ * This type defines a subset of properties from the CreateArvoEvent type,
+ * specifically tailored for emitting an ArvoEvent within the state machine context.
+ *
+ * @remarks
+ * The EmitArvoEventActionParam type is crucial for maintaining consistency and
+ * type safety when emitting events in an ArvoXState machine. It ensures that
+ * only relevant properties are included and properly typed.
+ * ```
+ */
+export type EnqueueArvoEventActionParam<TData extends ArvoEventData = ArvoEventData, TType extends string = string, TExtension extends CloudEventExtension = CloudEventExtension> = {
+    /**
+     * The event domain configuration for multi-domain broadcasting.
+     *
+     * **Domain Broadcasting Rules:**
+     * - Each element in the array creates a separate ArvoEvent instance
+     * - `undefined` elements resolve using inheritance: `event.domain ?? contract.domain ?? null`
+     * - Duplicate domains are automatically removed to prevent redundant events
+     * - Omitting this field (or setting to `undefined`) defaults to `[null]`
+     *
+     * **Domain Broadcasting Patterns:**
+     * - `['domain1', 'domain2']` → Creates 2 events for different processing contexts
+     * - `['analytics', undefined, 'audit']` → Creates events for analytics, inherited context, and audit
+     * - `[null]` → Creates single event with no domain routing (standard processing)
+     * - `undefined` (or omitted) → Creates single event with `domain: null`
+     */
+    domain?: (string | null | undefined)[];
+    /**
+     * Custom extensions for the CloudEvent.
+     * Allows for additional metadata to be attached to the event.
+     *
+     * @remarks
+     * Use this field to include any non-standard attributes that are not
+     * covered by the core CloudEvent specification or Arvo extensions.
+     */
+    __extensions?: TExtension;
+    /**
+     * Defines access controls for the event.
+     * Can be a UserID, encrypted string, or key-value pairs.
+     *
+     * @remarks
+     * This field is used to implement fine-grained access control on event
+     * consumption. The exact format and interpretation may depend on your
+     * system's access control mechanisms.
+     */
+    accesscontrol?: string;
+    /**
+     * The event payload. This payload must be JSON serializable.
+     *
+     * @remarks
+     * The data field contains the event-specific information. Ensure that
+     * the structure of this data conforms to the schema specified in the
+     * `dataschema` field, if provided.
+     */
+    data: TData;
+    /**
+     * Identifies the schema that the `data` adheres to.
+     * Must be a valid URI if present.
+     *
+     * @remarks
+     * Use this field to provide a link to the schema definition for the
+     * event data. This helps consumers understand and validate the event structure.
+     */
+    dataschema?: string;
+    /**
+     * Indicates alternative recipients or destinations for events.
+     * Must be a valid URI if present.
+     *
+     * @remarks
+     * Use this field to implement event forwarding or to specify secondary
+     * event consumers in addition to the primary one specified in the `to` field.
+     */
+    redirectto?: string;
+    /**
+     * Defines the consumer machine of the event. Used for event routing.
+     * Must be a valid URI if present. If not available, the `type` field
+     * is used as a default.
+     *
+     * @remarks
+     * This field is crucial for directing events to specific services or
+     * components in your system. Ensure the URI is correctly formatted and
+     * recognized by your event routing infrastructure.
+     */
+    to?: string;
+    /**
+     * Describes the type of event.
+     * Should be prefixed with a reverse-DNS name.
+     *
+     * @remarks
+     * The event type is a key field for consumers to understand the nature
+     * of the event without inspecting its data. Use a consistent naming convention
+     * to enhance system-wide event comprehension.
+     */
+    type: TType;
+    /**
+     * Represents the cost associated with generating the cloudevent.
+     *
+     * @remarks
+     * By default, it uses the actor's executionunits. This field can be used for
+     * resource accounting or billing purposes. Only override this if you have a specific
+     * reason to assign a different cost to this particular event emission.
+     */
+    executionunits?: number;
+};
+/**
+ * @remarks
+ * This is an internal type. Copied as it is from the
+ * xstate core [here](https://github.com/statelyai/xstate/blob/main/packages/core/src/setup.ts#L26)
+ */
+export type ToParameterizedObject<TParameterizedMap extends Record<string, ParameterizedObject['params'] | undefined>> = IsNever<TParameterizedMap> extends true ? never : Values<{
+    [K in keyof TParameterizedMap & string]: {
+        type: K;
+        params: TParameterizedMap[K];
+    };
+}>;
+/**
+ * @remarks
+ * This is an internal type. Copied as it is from the
+ * xstate core [here](https://github.com/statelyai/xstate/blob/main/packages/core/src/setup.ts#L43)
+ */
+export type ToProvidedActor<TChildrenMap extends Record<string, string>, TActors extends Record<string, UnknownActorLogic>> = IsNever<TActors> extends true ? never : Values<{
+    [K in keyof TActors & string]: {
+        src: K;
+        logic: TActors[K];
+        id: IsNever<TChildrenMap> extends true ? string | undefined : K extends keyof Invert<TChildrenMap> ? Invert<TChildrenMap>[K] & string : string | undefined;
+    };
+}>;
+/**
+ * Infers emittable events from a versioned Arvo contract.
+ *
+ * @template T - Versioned Arvo contract type
+ *
+ * @remarks
+ * Extracts all possible events that can be emitted by a contract,
+ * including system error events.
+ */
+export type InferEmittableEventsFromVersionedArvoContract<T extends VersionedArvoContract<ArvoContract, ArvoSemanticVersion>> = {
+    [K in keyof InferVersionedArvoContract<T>['emits']]: InferVersionedArvoContract<T>['emits'][K];
+}[keyof InferVersionedArvoContract<T>['emits']] | InferVersionedArvoContract<T>['systemError'];
+/**
+ * Extracts the orchestrator type from an event type string.
+ *
+ * @template T - Event type string
+ *
+ * @remarks
+ * Parses the specific orchestrator type from a fully qualified event type string.
+ */
+export type ExtractOrchestratorType<T extends string> = T extends `${typeof ArvoOrchestratorEventTypeGen.prefix}.${infer Type}` ? Type : never;
+/**
+ * Infers the complete service contract from a record of versioned Arvo contracts.
+ *
+ * @template T - Record of versioned Arvo contracts
+ *
+ * @remarks
+ * Generates a comprehensive type definition including both emitted and received events
+ * for all services in the contract.
+ *
+ * @property emitted - Events that can be emitted by the orchestrator
+ * @property events - Events that can be received by the orchestrator
+ */
+export type InferServiceContract<T extends Record<string, VersionedArvoContract<ArvoContract, ArvoSemanticVersion>>> = {
+    emitted: {
+        [K in keyof T]: EnqueueArvoEventActionParam<z.input<T[K]['accepts']['schema']>, T[K]['accepts']['type']>;
+    }[keyof T];
+    events: {
+        [K in keyof T]: InferEmittableEventsFromVersionedArvoContract<T[K]>;
+    }[keyof T];
+};

package/dist/ArvoMachine/utils.d.ts

@@ -0,0 +1,40 @@
+import type { ArvoContract, VersionedArvoContract } from 'arvo-core';
+import type { MachineConfig } from 'xstate';
+/**
+ * Detects if an XState machine configuration contains any parallel states.
+ * Uses a stack-based approach for efficient traversal of the state hierarchy.
+ *
+ * @param config - XState machine configuration
+ * @returns True if the machine contains at least one parallel state, false otherwise
+ *
+ * @example
+ * const machine = {
+ *   states: {
+ *     processing: {
+ *       type: 'parallel',
+ *       states: {
+ *         upload: { ... },
+ *         scan: { ... }
+ *       }
+ *     }
+ *   }
+ * }
+ * const hasParallel = detectParallelStates(machine) // Returns true
+ */
+export declare const detectParallelStates: (config?: MachineConfig<any, any, any, any, any, any, any, any, any, any, any>) => boolean;
+/**
+ * Validates that all service contracts in a collection have unique URIs.
+ *
+ * Iterates through the provided contracts and checks if any URI appears more than once.
+ * Multiple versions of the same contract (with the same URI) are not allowed.
+ *
+ * @param contracts - A record mapping contract keys to their respective ArvoContract objects
+ * @returns An object with a boolean result indicating if all contracts are unique, and the error keys if not
+ */
+export declare const areServiceContractsUnique: (contracts: Record<string, ArvoContract | VersionedArvoContract<any, any>>) => {
+    result: false;
+    keys: [string, string];
+    contractUri: string;
+} | {
+    result: true;
+};

package/dist/ArvoMachine/utils.js

@@ -0,0 +1,70 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.areServiceContractsUnique = exports.detectParallelStates = void 0;
+/**
+ * Detects if an XState machine configuration contains any parallel states.
+ * Uses a stack-based approach for efficient traversal of the state hierarchy.
+ *
+ * @param config - XState machine configuration
+ * @returns True if the machine contains at least one parallel state, false otherwise
+ *
+ * @example
+ * const machine = {
+ *   states: {
+ *     processing: {
+ *       type: 'parallel',
+ *       states: {
+ *         upload: { ... },
+ *         scan: { ... }
+ *       }
+ *     }
+ *   }
+ * }
+ * const hasParallel = detectParallelStates(machine) // Returns true
+ */
+var detectParallelStates = function (config) {
+    if (!(config === null || config === void 0 ? void 0 : config.states)) {
+        return false;
+    }
+    var stack = [config];
+    while (stack.length) {
+        var currentConfig = stack.pop();
+        if (!(currentConfig === null || currentConfig === void 0 ? void 0 : currentConfig.states))
+            continue;
+        if (currentConfig.type === 'parallel')
+            return true;
+        for (var _i = 0, _a = Object.values(currentConfig.states); _i < _a.length; _i++) {
+            var state = _a[_i];
+            stack.push(state);
+        }
+    }
+    return false;
+};
+exports.detectParallelStates = detectParallelStates;
+/**
+ * Validates that all service contracts in a collection have unique URIs.
+ *
+ * Iterates through the provided contracts and checks if any URI appears more than once.
+ * Multiple versions of the same contract (with the same URI) are not allowed.
+ *
+ * @param contracts - A record mapping contract keys to their respective ArvoContract objects
+ * @returns An object with a boolean result indicating if all contracts are unique, and the error keys if not
+ */
+var areServiceContractsUnique = function (contracts) {
+    var uriToKeyMap = {};
+    for (var _i = 0, _a = Object.entries(contracts); _i < _a.length; _i++) {
+        var _b = _a[_i], key = _b[0], contract = _b[1];
+        if (uriToKeyMap[contract.uri]) {
+            return {
+                result: false,
+                keys: [key, uriToKeyMap[contract.uri]],
+                contractUri: contract.uri,
+            };
+        }
+        uriToKeyMap[contract.uri] = key;
+    }
+    return {
+        result: true,
+    };
+};
+exports.areServiceContractsUnique = areServiceContractsUnique;

package/dist/ArvoOrchestrator/error.d.ts

@@ -0,0 +1,16 @@
+import { type ArvoEvent, ViolationError } from 'arvo-core';
+export declare enum TransactionViolationCause {
+    READ_FAILURE = "READ_MACHINE_MEMORY_FAILURE",
+    LOCK_FAILURE = "LOCK_MACHINE_MEMORY_FAILURE",
+    WRITE_FAILURE = "WRITE_MACHINE_MEMORY_FAILURE",
+    LOCK_UNACQUIRED = "LOCK_UNACQUIRED",
+    INVALID_SUBJECT = "INVALID_SUBJECT"
+}
+export declare class TransactionViolation extends ViolationError<'OrchestratorTransaction'> {
+    readonly cause: TransactionViolationCause;
+    constructor(param: {
+        cause: TransactionViolationCause;
+        message: string;
+        initiatingEvent: ArvoEvent;
+    });
+}

package/dist/ArvoOrchestrator/error.js

@@ -0,0 +1,43 @@
+"use strict";
+var __extends = (this && this.__extends) || (function () {
+    var extendStatics = function (d, b) {
+        extendStatics = Object.setPrototypeOf ||
+            ({ __proto__: [] } instanceof Array && function (d, b) { d.__proto__ = b; }) ||
+            function (d, b) { for (var p in b) if (Object.prototype.hasOwnProperty.call(b, p)) d[p] = b[p]; };
+        return extendStatics(d, b);
+    };
+    return function (d, b) {
+        if (typeof b !== "function" && b !== null)
+            throw new TypeError("Class extends value " + String(b) + " is not a constructor or null");
+        extendStatics(d, b);
+        function __() { this.constructor = d; }
+        d.prototype = b === null ? Object.create(b) : (__.prototype = b.prototype, new __());
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TransactionViolation = exports.TransactionViolationCause = void 0;
+var arvo_core_1 = require("arvo-core");
+var TransactionViolationCause;
+(function (TransactionViolationCause) {
+    TransactionViolationCause["READ_FAILURE"] = "READ_MACHINE_MEMORY_FAILURE";
+    TransactionViolationCause["LOCK_FAILURE"] = "LOCK_MACHINE_MEMORY_FAILURE";
+    TransactionViolationCause["WRITE_FAILURE"] = "WRITE_MACHINE_MEMORY_FAILURE";
+    TransactionViolationCause["LOCK_UNACQUIRED"] = "LOCK_UNACQUIRED";
+    TransactionViolationCause["INVALID_SUBJECT"] = "INVALID_SUBJECT";
+})(TransactionViolationCause || (exports.TransactionViolationCause = TransactionViolationCause = {}));
+var TransactionViolation = /** @class */ (function (_super) {
+    __extends(TransactionViolation, _super);
+    function TransactionViolation(param) {
+        var _this = _super.call(this, {
+            type: 'OrchestratorTransaction',
+            message: "[".concat(param.cause, "] ").concat(param.message),
+            metadata: {
+                initiatingEvent: param.initiatingEvent,
+            },
+        }) || this;
+        _this.cause = param.cause;
+        return _this;
+    }
+    return TransactionViolation;
+}(arvo_core_1.ViolationError));
+exports.TransactionViolation = TransactionViolation;

package/dist/ArvoOrchestrator/factory.d.ts

@@ -0,0 +1,28 @@
+import { ArvoOrchestrator } from '.';
+import type { ICreateArvoOrchestrator } from './types';
+/**
+ * Creates a new Arvo orchestrator instance with default components.
+ * For custom components, use ArvoOrchestrator constructor directly.
+ *
+ * @param config - Orchestrator configuration
+ * @param config.memory - State persistence interface for storing machine states
+ * @param config.executionunits - Cost units for execution tracking
+ * @param config.machines - Array of state machines to manage. Their resource locking flags determine orchestrator's locking behavior
+ * @returns Configured ArvoOrchestrator instance with default registry and execution engine
+ *
+ * @remarks
+ * The orchestrator's resource locking is enabled if any machine requires it. Locking is needed when:
+ * - Machine contains parallel states where multiple states can be active simultaneously
+ * - Race conditions need to be prevented in concurrent processing
+ * - State consistency must be maintained across distributed executions
+ *
+ * @example
+ * ```typescript
+ * const orchestrator = createArvoOrchestrator({
+ *   memory: new MyMemoryImplementation(),
+ *   executionunits: 1,
+ *   machines: [machineA, machineB]
+ * });
+ * ```
+ */
+export declare const createArvoOrchestrator: ({ executionunits, memory, machines, }: ICreateArvoOrchestrator) => ArvoOrchestrator;

package/dist/ArvoOrchestrator/factory.js

@@ -0,0 +1,56 @@
+"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 });
+exports.createArvoOrchestrator = void 0;
+var _1 = require(".");
+var MachineExecutionEngine_1 = require("../MachineExecutionEngine");
+var MachineRegistry_1 = require("../MachineRegistry");
+/**
+ * Creates a new Arvo orchestrator instance with default components.
+ * For custom components, use ArvoOrchestrator constructor directly.
+ *
+ * @param config - Orchestrator configuration
+ * @param config.memory - State persistence interface for storing machine states
+ * @param config.executionunits - Cost units for execution tracking
+ * @param config.machines - Array of state machines to manage. Their resource locking flags determine orchestrator's locking behavior
+ * @returns Configured ArvoOrchestrator instance with default registry and execution engine
+ *
+ * @remarks
+ * The orchestrator's resource locking is enabled if any machine requires it. Locking is needed when:
+ * - Machine contains parallel states where multiple states can be active simultaneously
+ * - Race conditions need to be prevented in concurrent processing
+ * - State consistency must be maintained across distributed executions
+ *
+ * @example
+ * ```typescript
+ * const orchestrator = createArvoOrchestrator({
+ *   memory: new MyMemoryImplementation(),
+ *   executionunits: 1,
+ *   machines: [machineA, machineB]
+ * });
+ * ```
+ */
+var createArvoOrchestrator = function (_a) {
+    var executionunits = _a.executionunits, memory = _a.memory, machines = _a.machines;
+    if (!(machines === null || machines === void 0 ? void 0 : machines.length)) {
+        throw new Error('At least one machine must be provided');
+    }
+    var registry = new (MachineRegistry_1.MachineRegistry.bind.apply(MachineRegistry_1.MachineRegistry, __spreadArray([void 0], machines, false)))();
+    var requiresResourceLocking = machines.some(function (machine) { return machine.requiresResourceLocking; });
+    return new _1.ArvoOrchestrator({
+        executionunits: executionunits,
+        memory: memory,
+        registry: registry,
+        executionEngine: new MachineExecutionEngine_1.MachineExecutionEngine(),
+        requiresResourceLocking: requiresResourceLocking,
+    });
+};
+exports.createArvoOrchestrator = createArvoOrchestrator;