arvo-event-handler

Arvo - A toolkit for event driven applications (arvo-event-handler)

The orchestration and event processing foundation for Arvo, providing everything from simple event handlers to complex workflow orchestration with state machines and imperative resumables.

This package provides three core handler patterns and essential infrastructure for building reliable event-driven systems:

ArvoEventHandler - Stateless event processors that transform contract-defined events. Perfect for microservices, API endpoints, and simple request-response patterns.

ArvoOrchestrator - Declarative state machine-based workflow orchestration using XState. Ideal for complex business processes with clear states, transitions, and parallel execution.

ArvoResumable - Imperative workflow handlers with explicit state management. Best for dynamic workflows, AI-driven decision logic, and teams preferring traditional programming patterns.

Installation

npm install arvo-event-handler arvo-core xstate@5 zod@3

Quick Start

Simple Event Handler

import { createArvoEventHandler } from 'arvo-event-handler';
import { createArvoContract } from 'arvo-core';
import { z } from 'zod';

const contract = createArvoContract({
  uri: '#/contracts/user',
  type: 'user.validate',
  versions: {
    '1.0.0': {
      accepts: z.object({ email: z.string().email() }),
      emits: {
        'evt.user.validate.success': z.object({ valid: z.boolean() })
      }
    }
  }
});

const handler = createArvoEventHandler({
  contract,
  executionunits: 0,
  handler: {
    '1.0.0': async ({ event }) => ({
      type: 'evt.user.validate.success',
      data: { valid: true }
    })
  }
});

State Machine Orchestrator

import { createArvoOrchestrator, setupArvoMachine } from 'arvo-event-handler';
import { createArvoOrchestratorContract } from 'arvo-core';

const orchestratorContract = createArvoOrchestratorContract({
  uri: '#/orchestrator/workflow',
  name: 'workflow',
  versions: {
    '1.0.0': {
      init: z.object({ userId: z.string() }),
      complete: z.object({ result: z.string() })
    }
  }
});

const machine = setupArvoMachine({
  contracts: {
    self: orchestratorContract.version('1.0.0'),
    services: { /* service contracts */ }
  }
}).createMachine({
  // XState machine definition
});

const orchestrator = createArvoOrchestrator({
  machines: [machine],
  memory, // IMachineMemory implementation
  executionunits: 0
});

Imperative Resumable

import { createArvoResumable } from 'arvo-event-handler';

const resumable = createArvoResumable({
  contracts: {
    self: orchestratorContract,
    services: { /* service contracts */ }
  },
  memory,
  executionunits: 0,
  handler: {
    '1.0.0': async ({ input, service, context }) => {
      if (input) {
        return {
          context: { userId: input.data.userId },
          services: [{ type: 'user.validate', data: { /* ... */ } }]
        };
      }
      // Handle service responses and return output
    }
  }
});

Additional Core Components

IMachineMemory - State persistence interface with optimistic locking for distributed workflow coordination. Includes SimpleMachineMemory for local development.

Error Handling - Three-tier system: business logic failures as contract events, transient errors as system events, and violations for critical failures requiring immediate intervention.

SimpleEventBroker - Local in-memory FIFO queue-based event broker for testing and development without external message infrastructure. Also suitable for production deployments with limited scale (≤1000 users).

SimpleMachineMemory - Local in-memory hash map based storage for testing and development without external database infrastructure.

All handlers implement the same interface IArvoEventHandler regardless of complexity, enabling consistent patterns across your entire system. Contract-first development ensures type safety and validation at every boundary. Built-in OpenTelemetry integration provides complete observability. State management through pluggable interfaces supports any storage backend from memory to distributed databases.

The same handler code works locally with in-memory brokers during development and in production with distributed message systems and persistent state stores.

What is `arvo-event-handler`?

The arvo-event-handler is one of the two foundational packages in the Arvo ecosystem, alongside arvo-core. Together, they provide the complete foundation for building event-driven applications that are distributed system-compliant. Explore additional tools and integrations in the @arvo-tools namespace.

Learn more at the official Arvo website: https://www.arvo.land/