arvo-event-handler 2.3.3 → 3.0.1

package/dist/ArvoResumable/types.d.ts

@@ -0,0 +1,147 @@
+import type { VersionedArvoContract, ArvoSemanticVersion, InferVersionedArvoContract, ArvoContract, ArvoEvent, InferArvoEvent } from 'arvo-core';
+import type { EnqueueArvoEventActionParam } from '../ArvoMachine/types';
+import type { Span } from '@opentelemetry/api';
+type ExtractServiceEventTypes<TServiceContract extends Record<string, VersionedArvoContract<any, any>>> = {
+    [K in keyof TServiceContract]: {
+        [L in keyof InferVersionedArvoContract<TServiceContract[K]>['emits']]: {
+            type: InferVersionedArvoContract<TServiceContract[K]>['emits'][L]['type'];
+            event: InferVersionedArvoContract<TServiceContract[K]>['emits'][L];
+        };
+    }[keyof InferVersionedArvoContract<TServiceContract[K]>['emits']] | {
+        type: InferVersionedArvoContract<TServiceContract[K]>['systemError']['type'];
+        event: InferVersionedArvoContract<TServiceContract[K]>['systemError'];
+    };
+}[keyof TServiceContract];
+type AllServiceEventTypes<TServiceContract extends Record<string, VersionedArvoContract<any, any>>> = ExtractServiceEventTypes<TServiceContract>['type'];
+type ServiceEventTypeMap<TServiceContract extends Record<string, VersionedArvoContract<any, any>>> = {
+    [T in ExtractServiceEventTypes<TServiceContract> as T['type']]: T['event'];
+};
+type Handler<TState extends ArvoResumableState<Record<string, any>>, TSelfContract extends VersionedArvoContract<any, any>, TServiceContract extends Record<string, VersionedArvoContract<any, any>>> = (param: {
+    span: Span;
+    metadata: Omit<TState, 'state$$'> | null;
+    collectedEvents: Partial<{
+        [K in AllServiceEventTypes<TServiceContract>]: ServiceEventTypeMap<TServiceContract>[K][];
+    }>;
+    context: TState['state$$'] | null;
+    input: InferVersionedArvoContract<TSelfContract>['accepts'] | null;
+    service: {
+        [K in keyof TServiceContract]: {
+            [L in keyof InferVersionedArvoContract<TServiceContract[K]>['emits']]: InferVersionedArvoContract<TServiceContract[K]>['emits'][L];
+        }[keyof InferVersionedArvoContract<TServiceContract[K]>['emits']] | InferVersionedArvoContract<TServiceContract[K]>['systemError'];
+    }[keyof TServiceContract] | null;
+    contracts: {
+        self: TSelfContract;
+        services: TServiceContract;
+    };
+}) => Promise<{
+    context?: TState['state$$'];
+    output?: {
+        [L in keyof InferVersionedArvoContract<TSelfContract>['emits']]: EnqueueArvoEventActionParam<InferVersionedArvoContract<TSelfContract>['emits'][L]['data'], InferVersionedArvoContract<TSelfContract>['emits'][L]['type']>['data'];
+    }[keyof InferVersionedArvoContract<TSelfContract>['emits']];
+    services?: Array<{
+        [K in keyof TServiceContract]: EnqueueArvoEventActionParam<InferVersionedArvoContract<TServiceContract[K]>['accepts']['data'], InferVersionedArvoContract<TServiceContract[K]>['accepts']['type']>;
+    }[keyof TServiceContract]>;
+} | void>;
+/**
+ * The versioned orchestration handlers in ArvoResumable workflows
+ *
+ * It maps each version of an orchestrator contract to its corresponding handler function.
+ * Each handler receives workflow context (state, events, contracts) and returns execution results
+ * that can update state, complete the workflow, or invoke external services.
+ *
+ * The handler is called for each event that matches the orchestrator's contract, whether it's
+ * an initialization event or a service response. The handler must be deterministic and
+ * idempotent to ensure reliable workflow execution across potential retries.
+ *
+ * @param param - Handler execution context
+ * @param param.span - OpenTelemetry span for distributed tracing
+ * @param param.metadata - Complete workflow metadata (null for new workflows)
+ * @param param.collectedEvents - Type-safe map of event types to their corresponding typed event arrays,
+ *                                enabling strongly-typed access with full IntelliSense support.
+ * @param param.context - Current workflow state (null for new workflows)
+ * @param param.init - Initialization event data (only present for workflow start events)
+ * @param param.service - Service response event data (only present for service callbacks)
+ * @param param.contracts - Available contracts for type validation and event creation
+ * @param param.contracts.self - The orchestrator's own versioned contract
+ * @param param.contracts.services - External service contracts for invocation
+ *
+ * @returns Promise resolving to execution result or void
+ * @returns result.context - Updated workflow state to persist
+ * @returns result.complete - Workflow completion event to emit (ends the workflow)
+ * @returns result.services - Array of service invocation events to emit
+ *
+ * @remarks
+ * - Each version key must match a valid semantic version in the self contract
+ * - Handlers should be pure functions without side effects beyond the returned actions
+ * - State updates are atomic - either all changes persist or none do
+ * - Only one of `init` or `service` will be non-null for any given invocation
+ * - Returning void or an empty object indicates no state changes or events to emit
+ * - Service events are supposed to queued for execution and may trigger callback events
+ * - Completion events terminate the workflow and route to the parent orchestrator
+ */
+export type ArvoResumableHandler<TState extends ArvoResumableState<Record<string, any>>, TSelfContract extends ArvoContract, TServiceContract extends Record<string, VersionedArvoContract<any, any>>> = {
+    [V in ArvoSemanticVersion & keyof TSelfContract['versions']]: Handler<TState, VersionedArvoContract<TSelfContract, V>, TServiceContract>;
+};
+export type ArvoResumableState<T extends Record<string, any>> = {
+    /**
+     * Current execution status of the orchestration workflow
+     *
+     * This field tracks the lifecycle state of the workflow instance to determine
+     * whether it can accept new events and continue processing or has reached
+     * its terminal state.
+     *
+     * @remarks
+     * - **active**: The workflow is running and can accept events for processing.
+     *   It may be waiting for service responses, processing initialization events,
+     *   or handling intermediate workflow steps. The orchestrator will continue
+     *   to route events to active workflows.
+     *
+     * - **done**: The workflow has completed its execution lifecycle. This status
+     *   is set when the handler returns a `complete` event, indicating the workflow
+     *   has finished successfully. Done workflows will not process additional events
+     *   and their state is preserved for audit/debugging purposes.
+     */
+    status: 'active' | 'done';
+    /** 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;
+    events: {
+        /** The event consumed by the machine in the last session */
+        consumed: InferArvoEvent<ArvoEvent> | null;
+        /**
+         * The domained events produced by the machine in the last session
+         */
+        produced: InferArvoEvent<ArvoEvent>[];
+        /**
+         * The events expected by the resumable. These events are collected on each execution
+         * as long as the event parent id and the expected key matches. The expected key is the
+         * event.id of the produced event.
+         */
+        expected: Record<string, InferArvoEvent<ArvoEvent>[]> | null;
+    };
+    /** The state used by the resumable */
+    state$$: T | null;
+};
+export {};

package/dist/ArvoResumable/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/MachineExecutionEngine/index.d.ts

@@ -0,0 +1,29 @@
+import type { IMachineExectionEngine } from './interface';
+import type { ExecuteMachineInput, ExecuteMachineOutput } from './types';
+import type { ArvoEventHandlerOpenTelemetryOptions } from '../types';
+/**
+ * Handles state machine execution, event processing, and lifecycle management.
+ */
+export declare class MachineExecutionEngine implements IMachineExectionEngine {
+    /**
+     * Executes a state machine and manages its lifecycle.
+     *
+     * @description
+     * Handles machine initialization/resumption, event processing, and state transitions.
+     * Manages event queues and volatile context during execution.
+     *
+     * @param params Configuration parameters:
+     *   - machine: State machine definition
+     *   - state: Optional existing state to resume from
+     *   - event: Event triggering the execution
+     * @param opentelemetry Telemetry configuration for tracing
+     *
+     * @returns Object containing:
+     *   - state: Final machine state
+     *   - events: Generated events
+     *   - finalOutput: Machine output or null
+     *
+     * @throws Error on invalid initialization events or execution failures
+     */
+    execute({ machine, state, event }: ExecuteMachineInput, opentelemetry?: ArvoEventHandlerOpenTelemetryOptions): ExecuteMachineOutput;
+}

package/dist/MachineExecutionEngine/index.js

@@ -0,0 +1,132 @@
+"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.MachineExecutionEngine = void 0;
+var api_1 = require("@opentelemetry/api");
+var arvo_core_1 = require("arvo-core");
+var xstate_1 = require("xstate");
+/**
+ * Handles state machine execution, event processing, and lifecycle management.
+ */
+var MachineExecutionEngine = /** @class */ (function () {
+    function MachineExecutionEngine() {
+    }
+    /**
+     * Executes a state machine and manages its lifecycle.
+     *
+     * @description
+     * Handles machine initialization/resumption, event processing, and state transitions.
+     * Manages event queues and volatile context during execution.
+     *
+     * @param params Configuration parameters:
+     *   - machine: State machine definition
+     *   - state: Optional existing state to resume from
+     *   - event: Event triggering the execution
+     * @param opentelemetry Telemetry configuration for tracing
+     *
+     * @returns Object containing:
+     *   - state: Final machine state
+     *   - events: Generated events
+     *   - finalOutput: Machine output or null
+     *
+     * @throws Error on invalid initialization events or execution failures
+     */
+    MachineExecutionEngine.prototype.execute = function (_a, opentelemetry) {
+        var machine = _a.machine, state = _a.state, event = _a.event;
+        if (opentelemetry === void 0) { opentelemetry = {
+            inheritFrom: 'CONTEXT',
+        }; }
+        return arvo_core_1.ArvoOpenTelemetry.getInstance().startActiveSpan({
+            name: 'Execute Machine',
+            spanOptions: {
+                kind: api_1.SpanKind.INTERNAL,
+                attributes: __assign({ 'arvo.machine.type': machine.source, 'arvo.machine.version': machine.version }, event.otelAttributes),
+            },
+            context: opentelemetry.inheritFrom === 'EVENT'
+                ? {
+                    inheritFrom: 'TRACE_HEADERS',
+                    traceHeaders: {
+                        traceparent: event.traceparent,
+                        tracestate: event.tracestate,
+                    },
+                }
+                : {
+                    inheritFrom: 'CONTEXT',
+                    context: api_1.context.active(),
+                },
+            fn: function () {
+                var _a, _b, _c, _d, _e, _f, _g;
+                var eventQueue = [];
+                var errors = [];
+                var actor;
+                if (!state) {
+                    (0, arvo_core_1.logToSpan)({
+                        level: 'INFO',
+                        message: "Starting new orchestration for machine '".concat(machine.source, "' with event type '").concat(event.type, "'"),
+                    });
+                    if (event.type !== machine.source) {
+                        throw new Error("Invalid initialization event: Machine requires source event '".concat(machine.source, "' to start, but received event '").concat(event.type, "' instead. This likely indicates a mismatch between the expected workflow trigger and the actual event sent."));
+                    }
+                    actor = (0, xstate_1.createActor)(machine.logic, {
+                        input: event.toJSON(),
+                    });
+                    actor.on('*', function (event) { return eventQueue.push(event); });
+                    actor.subscribe({ error: function (err) { return errors.push(err); } });
+                    actor.start();
+                }
+                else {
+                    (0, arvo_core_1.logToSpan)({
+                        level: 'INFO',
+                        message: "Resuming orchestration for machine '".concat(machine.source, "' from existing state with event '").concat(event.type, "'"),
+                    });
+                    actor = (0, xstate_1.createActor)(machine.logic, {
+                        snapshot: state,
+                    });
+                    actor.on('*', function (event) { return eventQueue.push(event); });
+                    actor.subscribe({ error: function (err) { return errors.push(err); } });
+                    actor.start();
+                    actor.send(event.toJSON());
+                }
+                (0, arvo_core_1.logToSpan)({
+                    level: 'INFO',
+                    message: "Machine '".concat(machine.source, "' execution completed successfully with ").concat(eventQueue.length, " queued events"),
+                });
+                (0, arvo_core_1.logToSpan)({
+                    level: 'INFO',
+                    message: "Extracting final state snapshot from machine '".concat(machine.source, "'"),
+                });
+                var extractedSnapshot = actor.getPersistedSnapshot();
+                if ((_b = (_a = extractedSnapshot === null || extractedSnapshot === void 0 ? void 0 : extractedSnapshot.context) === null || _a === void 0 ? void 0 : _a.arvo$$) === null || _b === void 0 ? void 0 : _b.volatile$$) {
+                    // biome-ignore lint/complexity/noForEach: TODO - fix it later
+                    ((_e = (_d = (_c = extractedSnapshot === null || extractedSnapshot === void 0 ? void 0 : extractedSnapshot.context) === null || _c === void 0 ? void 0 : _c.arvo$$) === null || _d === void 0 ? void 0 : _d.volatile$$) === null || _e === void 0 ? void 0 : _e.eventQueue$$).forEach(function (item) { return eventQueue.push(item); });
+                    extractedSnapshot.context.arvo$$.volatile$$ = undefined;
+                }
+                if (errors.length) {
+                    throw errors[0];
+                }
+                var finalOutput = (_f = extractedSnapshot === null || extractedSnapshot === void 0 ? void 0 : extractedSnapshot.output) !== null && _f !== void 0 ? _f : null;
+                var existingOutput = (_g = state === null || state === void 0 ? void 0 : state.output) !== null && _g !== void 0 ? _g : null;
+                if (JSON.stringify(finalOutput !== null && finalOutput !== void 0 ? finalOutput : {}) === JSON.stringify(existingOutput !== null && existingOutput !== void 0 ? existingOutput : {})) {
+                    finalOutput = null;
+                }
+                return {
+                    state: extractedSnapshot,
+                    events: eventQueue,
+                    finalOutput: finalOutput,
+                };
+            },
+        });
+    };
+    return MachineExecutionEngine;
+}());
+exports.MachineExecutionEngine = MachineExecutionEngine;

package/dist/MachineExecutionEngine/interface.d.ts

@@ -0,0 +1,14 @@
+import type { ArvoEventHandlerOpenTelemetryOptions } from '../types';
+import type { ExecuteMachineInput, ExecuteMachineOutput } from './types';
+/**
+ * Interface defining a machine execution engine.
+ */
+export interface IMachineExectionEngine {
+    /**
+     * Executes a state machine and processes events.
+     * @param param - Input parameters for machine execution
+     * @param opentelemetry - Telemetry configuration options
+     * @returns Machine execution results including state and events
+     */
+    execute: (param: ExecuteMachineInput, opentelemetry: ArvoEventHandlerOpenTelemetryOptions) => ExecuteMachineOutput;
+}

package/dist/MachineExecutionEngine/interface.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/MachineExecutionEngine/types.d.ts

@@ -0,0 +1,14 @@
+import type { ArvoEvent } from 'arvo-core';
+import type { Snapshot } from 'xstate';
+import type ArvoMachine from '../ArvoMachine';
+import type { EnqueueArvoEventActionParam } from '../ArvoMachine/types';
+export type ExecuteMachineInput = {
+    machine: ArvoMachine<any, any, any, any, any>;
+    state: Snapshot<any> | null;
+    event: ArvoEvent;
+};
+export type ExecuteMachineOutput = {
+    state: Snapshot<any>;
+    events: EnqueueArvoEventActionParam[];
+    finalOutput: any;
+};

package/dist/MachineExecutionEngine/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/MachineMemory/Simple.d.ts

@@ -0,0 +1,51 @@
+import type { IMachineMemory } from './interface';
+/**
+ * In-memory implementation of machine state storage for single-instance NodeJS apps.
+ *
+ * Best for: Container apps, request-scoped workflows, testing, demos
+ * Not for: Multi-instance deployments, persistent workflows, distributed systems
+ *
+ * @example
+ * const memory = new SimpleMachineMemory();
+ * const orchestrator = createArvoOrchestrator({
+ *   memory,
+ *   executionunits: 1,
+ *   machines: [workflow]
+ * });
+ */
+export declare class SimpleMachineMemory<T extends Record<string, any> = Record<string, any>> implements IMachineMemory<T> {
+    private readonly memoryMap;
+    private readonly lockMap;
+    /**
+     * Gets stored state for a machine instance
+     * @param id Machine instance ID
+     * @returns State data or null if not found
+     * @throws {Error} When id is empty or undefined
+     */
+    read(id: string): Promise<T | null>;
+    /**
+     * Stores state for a machine instance
+     * @param id Machine instance ID
+     * @param data State to store
+     * @throws {Error} When id is empty/undefined or data is null/undefined
+     */
+    write(id: string, data: T): Promise<void>;
+    /**
+     * Attempts to acquire lock for machine instance
+     * @param id Machine instance ID
+     * @returns Success status of lock acquisition
+     * @throws {Error} When id is empty or undefined
+     */
+    lock(id: string): Promise<boolean>;
+    /**
+     * Releases lock for machine instance
+     * @param id Machine instance ID
+     * @returns True when lock is released
+     * @throws {Error} When id is empty or undefined
+     */
+    unlock(id: string): Promise<boolean>;
+    /**
+     * Clears all stored data and locks
+     */
+    clear(key?: string): void;
+}

package/dist/MachineMemory/Simple.js

@@ -0,0 +1,158 @@
+"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);
+};
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __generator = (this && this.__generator) || function (thisArg, body) {
+    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g = Object.create((typeof Iterator === "function" ? Iterator : Object).prototype);
+    return g.next = verb(0), g["throw"] = verb(1), g["return"] = verb(2), typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
+    function verb(n) { return function (v) { return step([n, v]); }; }
+    function step(op) {
+        if (f) throw new TypeError("Generator is already executing.");
+        while (g && (g = 0, op[0] && (_ = 0)), _) try {
+            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
+            if (y = 0, t) op = [op[0] & 2, t.value];
+            switch (op[0]) {
+                case 0: case 1: t = op; break;
+                case 4: _.label++; return { value: op[1], done: false };
+                case 5: _.label++; y = op[1]; op = [0]; continue;
+                case 7: op = _.ops.pop(); _.trys.pop(); continue;
+                default:
+                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) { _ = 0; continue; }
+                    if (op[0] === 3 && (!t || (op[1] > t[0] && op[1] < t[3]))) { _.label = op[1]; break; }
+                    if (op[0] === 6 && _.label < t[1]) { _.label = t[1]; t = op; break; }
+                    if (t && _.label < t[2]) { _.label = t[2]; _.ops.push(op); break; }
+                    if (t[2]) _.ops.pop();
+                    _.trys.pop(); continue;
+            }
+            op = body.call(thisArg, _);
+        } catch (e) { op = [6, e]; y = 0; } finally { f = t = 0; }
+        if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
+    }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SimpleMachineMemory = void 0;
+/**
+ * In-memory implementation of machine state storage for single-instance NodeJS apps.
+ *
+ * Best for: Container apps, request-scoped workflows, testing, demos
+ * Not for: Multi-instance deployments, persistent workflows, distributed systems
+ *
+ * @example
+ * const memory = new SimpleMachineMemory();
+ * const orchestrator = createArvoOrchestrator({
+ *   memory,
+ *   executionunits: 1,
+ *   machines: [workflow]
+ * });
+ */
+var SimpleMachineMemory = /** @class */ (function () {
+    function SimpleMachineMemory() {
+        this.memoryMap = new Map();
+        this.lockMap = new Map();
+    }
+    /**
+     * Gets stored state for a machine instance
+     * @param id Machine instance ID
+     * @returns State data or null if not found
+     * @throws {Error} When id is empty or undefined
+     */
+    SimpleMachineMemory.prototype.read = function (id) {
+        return __awaiter(this, void 0, void 0, function () {
+            var _a;
+            return __generator(this, function (_b) {
+                if (!id) {
+                    throw new Error('Machine ID is required for read operation');
+                }
+                return [2 /*return*/, (_a = this.memoryMap.get(id)) !== null && _a !== void 0 ? _a : null];
+            });
+        });
+    };
+    /**
+     * Stores state for a machine instance
+     * @param id Machine instance ID
+     * @param data State to store
+     * @throws {Error} When id is empty/undefined or data is null/undefined
+     */
+    SimpleMachineMemory.prototype.write = function (id, data) {
+        return __awaiter(this, void 0, void 0, function () {
+            return __generator(this, function (_a) {
+                if (!id) {
+                    throw new Error('Machine ID is required for write operation');
+                }
+                if (!data) {
+                    throw new Error('Data is required for write operation');
+                }
+                this.memoryMap.set(id, __assign({}, data));
+                return [2 /*return*/];
+            });
+        });
+    };
+    /**
+     * Attempts to acquire lock for machine instance
+     * @param id Machine instance ID
+     * @returns Success status of lock acquisition
+     * @throws {Error} When id is empty or undefined
+     */
+    SimpleMachineMemory.prototype.lock = function (id) {
+        return __awaiter(this, void 0, void 0, function () {
+            return __generator(this, function (_a) {
+                if (!id) {
+                    throw new Error('Machine ID is required for lock operation');
+                }
+                if (this.lockMap.get(id)) {
+                    return [2 /*return*/, false];
+                }
+                this.lockMap.set(id, true);
+                return [2 /*return*/, true];
+            });
+        });
+    };
+    /**
+     * Releases lock for machine instance
+     * @param id Machine instance ID
+     * @returns True when lock is released
+     * @throws {Error} When id is empty or undefined
+     */
+    SimpleMachineMemory.prototype.unlock = function (id) {
+        return __awaiter(this, void 0, void 0, function () {
+            return __generator(this, function (_a) {
+                if (!id) {
+                    throw new Error('Machine ID is required for unlock operation');
+                }
+                this.lockMap.delete(id);
+                return [2 /*return*/, !this.lockMap.get(id)];
+            });
+        });
+    };
+    /**
+     * Clears all stored data and locks
+     */
+    SimpleMachineMemory.prototype.clear = function (key) {
+        if (key) {
+            this.memoryMap.delete(key);
+            this.lockMap.delete(key);
+            return;
+        }
+        this.memoryMap.clear();
+        this.lockMap.clear();
+    };
+    return SimpleMachineMemory;
+}());
+exports.SimpleMachineMemory = SimpleMachineMemory;

package/dist/MachineMemory/TelemetredSimple.d.ts

@@ -0,0 +1,51 @@
+import type { IMachineMemory } from './interface';
+/**
+ * A telemetred In-memory implementation of machine state storage for single-instance NodeJS apps.
+ *
+ * Best for: Container apps, request-scoped workflows, testing, demos
+ * Not for: Multi-instance deployments, persistent workflows, distributed systems
+ *
+ * @example
+ * const memory = new TelemetredSimpleMachineMemory();
+ * const orchestrator = createArvoOrchestrator({
+ *   memory,
+ *   executionunits: 0.1,
+ *   machines: [workflow]
+ * });
+ */
+export declare class TelemetredSimpleMachineMemory<T extends Record<string, any> = Record<string, any>> implements IMachineMemory<T> {
+    private readonly memoryMap;
+    private readonly lockMap;
+    /**
+     * Gets stored state for a machine instance
+     * @param id Machine instance ID
+     * @returns State data or null if not found
+     * @throws {Error} When id is empty or undefined
+     */
+    read(id: string): Promise<T | null>;
+    /**
+     * Stores state for a machine instance
+     * @param id Machine instance ID
+     * @param data State to store
+     * @throws {Error} When id is empty/undefined or data is null/undefined
+     */
+    write(id: string, data: T): Promise<void>;
+    /**
+     * Attempts to acquire lock for machine instance
+     * @param id Machine instance ID
+     * @returns Success status of lock acquisition
+     * @throws {Error} When id is empty or undefined
+     */
+    lock(id: string): Promise<boolean>;
+    /**
+     * Releases lock for machine instance
+     * @param id Machine instance ID
+     * @returns True when lock is released
+     * @throws {Error} When id is empty or undefined
+     */
+    unlock(id: string): Promise<boolean>;
+    /**
+     * Clears all stored data and locks
+     */
+    clear(key?: string): void;
+}