arvo-event-handler/dist/MachineMemory/Simple.d.ts

A complete set of orthogonal event handler and orchestration primitives for Arvo based applications, featuring declarative state machines (XState), imperative resumables for agentic workflows, contract-based routing, OpenTelemetry observability, and in-me

import type { IMachineMemory } from './interface';
/**
 * In-memory implementation of machine state storage for single-instance NodeJS applications.
 *
 * @example
 * const memory = new SimpleMachineMemory();
 * const orchestrator = createArvoOrchestrator({
 *   memory,
 *   machines: [workflow]
 * });
 *
 * @warning Concurrency Limitations
 *
 * This implementation is NOT concurrency-safe. Lock acquisition is not atomic,
 * making it unsuitable for parallel event processing where multiple handlers
 * might process events for the same workflow simultaneously.
 *
 * **Safe Usage:**
 * - {@link SimpleEventBroker} (sequential event processing)
 * - Isolated handlers without shared durable state requirements
 *
 * **Unsafe Usage:**
 * - In-memory parallel/concurrent event brokers (e.g., p-queue with prefetch > 1)
 *
 * For concurrent in-process event processing, use the concurrency-safe memory
 * backend from the `@arvo-tools/concurrent` package, which provides atomic lock
 * operations suitable for parallel execution within a single process.
 *
 * **Unsuitable For:**
 * - Multi-instance deployments
 * - Distributed systems requiring shared state across processes
 *
 * For these scenarios, implement or use a database-backed memory backend
 * (Redis, PostgreSQL, DynamoDB, etc.) that provides distributed state
 * persistence and atomic locking across instances. You can also explore the
 * Arvo tool eco-system `@arvo-tools`
 */
export declare class SimpleMachineMemory<T extends Record<string, any> = Record<string, any>> implements IMachineMemory<T> {
    private readonly memoryMap;
    private readonly lockMap;
    private readonly enableCleanup;
    constructor(config?: {
        enableCleanup?: boolean;
    });
    /**
     * 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>;
    cleanup(id: string): Promise<void>;
    clear(): void;
}