@lindorm/hermes

@lindorm/hermes

Hermes is a decorator-driven CQRS + Event Sourcing framework for TypeScript. It combines Aggregates, Sagas (process managers), Views (projections) and Queries with a pluggable infrastructure layer so the same domain code runs locally with in-memory drivers, in docker-compose, or in production Kubernetes backed by Postgres, MongoDB, Redis and RabbitMQ.

The philosophy is simple:

• Commands are validated, then handled by an Aggregate.
• The Aggregate applies Events that mutate its state.
• Events are persisted in an Event Store and published on a Message Bus.
• Sagas react to events, dispatch new commands and schedule timeouts.
• Views project events into read-optimised entities.
• Queries read from views for fast, scalable reads.

Installation

npm install @lindorm/hermes

Hermes does not bundle database or messaging drivers. Install them separately:

npm install @lindorm/proteus   # persistence (event store, views, sagas)
npm install @lindorm/iris      # messaging (command bus, event bus)
npm install @lindorm/logger    # structured logging

For production you also need the concrete Proteus and Iris drivers for your infrastructure (e.g. @lindorm/postgres, @lindorm/mongo, @lindorm/rabbit). For local development the built-in memory drivers work out of the box.

Table of contents

• Core concepts
• Quick start
• Module discovery
• Defining Commands
• Defining Events
• Defining an Aggregate
• Defining a Saga
• Defining a View
• Defining Queries
• Defining Timeouts
• Event Upcasting (schema evolution)
• Validation with Zod
• Lifecycle guards
• Error handling
• Setting up Hermes
• Dispatching commands
• Querying views
• Event emitter
• Admin API
• Decorator reference
• Context reference
• Type reference
• Error reference

Core concepts

Concept	Purpose
Aggregate	Owns business state and invariants. Accepts Commands, produces Events.
Saga	Long-running process manager. Reacts to events, dispatches commands, schedules timeouts.
View	Read-model / projection updated by events. Backed by a Proteus entity.
Query	Stateless handler that reads from a view's repository.
Timeout	Delayed message dispatched by a saga, processed later.

All modules are plain classes decorated with Hermes decorators. They are discovered automatically by the scanner or registered manually.

Quick start

import { Hermes } from "@lindorm/hermes";
import { ProteusSource } from "@lindorm/proteus";
import { IrisSource } from "@lindorm/iris";

const proteus = new ProteusSource({ driver: "memory", logger });
const iris = new IrisSource({ driver: "memory", logger });

const hermes = new Hermes({
  proteus,
  iris,
  modules: [AccountAggregate, OverdraftProtectionSaga, AccountSummaryProjection],
  logger,
  namespace: "banking",
});

await hermes.setup();

// Issue a command (creates a new aggregate)
const { id } = await hermes.command(new OpenAccount("Alice", "USD", 500));

// Issue a command against an existing aggregate
await hermes.command(new DepositFunds(200, "USD"), { id });

// Query a view
const summary = await hermes.query<AccountSummaryView>(new GetAccountSummary(id));

await hermes.teardown();

For a comprehensive runnable example covering all features (CQRS flow, sagas, views, queries, upcasting, event emitter, admin inspect, error handling), run:

cd packages/hermes
npm run example

The example source lives in src/banking-example.test.ts with module definitions in example/modules/.

Module discovery

Hermes automatically discovers all your commands, events, aggregates, sagas, views, queries and timeouts. Just point it at a directory and it recursively scans every file, reads the decorator metadata, and wires everything together.

const hermes = new Hermes({
  proteus,
  iris,
  logger,
  modules: [path.resolve(__dirname, "modules")],
});

Given a directory structure like this:

modules/
├── commands/
│   ├── OpenAccount.ts
│   ├── DepositFunds.ts
│   └── WithdrawFunds.ts
├── events/
│   ├── AccountOpened.ts
│   ├── FundsDeposited_V1.ts
│   └── FundsDeposited_V2.ts
├── aggregates/
│   └── AccountAggregate.ts
├── sagas/
│   └── OverdraftProtectionSaga.ts
├── views/
│   ├── AccountSummaryView.ts
│   └── AccountSummaryProjection.ts
├── timeouts/
│   └── InactivityTimeout.ts
└── queries/
    └── GetAccountSummary.ts

Hermes will find every decorated class automatically. The directory structure is purely organisational — Hermes doesn't care about folder names. A flat directory with all files in one place works just as well.

The scanner skips files with test, spec, fixture, or integration in their name, and ignores index files.

You can also mix directory paths and explicit class references:

modules: [
  path.resolve(__dirname, "modules"),  // scan a directory
  SomeOtherAggregate,                  // add a class directly
],

How wiring works

During setup(), Hermes reads the decorator metadata from every discovered class to understand the relationships:

• @Command(), @Event(), @Query(), @Timeout() register DTO classes
• @Aggregate() registers command and event handlers
• @Saga(AggregateClass) binds to one or more aggregates
• @View(AggregateClass, EntityClass) binds to aggregates and captures the view entity class — Hermes automatically registers it with the Proteus source

This means you never need to manually register view entities with Proteus. The @View decorator is the single point of connection between your projection logic, the aggregate it listens to, and the Proteus entity it persists to.

Defining Commands

Commands are simple DTOs decorated with @Command(). They carry the intent to do something. The class name determines the command name and version automatically (or you can override them).

import { z } from "zod";
import { Command } from "@lindorm/hermes";

@Command()
export class OpenAccount {
  public constructor(
    public readonly ownerName: string,
    public readonly currency: string,
    public readonly initialDeposit: number,
  ) {}
}

// Optional: Zod schema for runtime validation
export const OpenAccountSchema = z.object({
  ownerName: z.string().min(1),
  currency: z.string().length(3),
  initialDeposit: z.number().nonnegative(),
});

Commands with no payload are also valid:

@Command()
export class CloseAccount {}

Defining Events

Events are immutable facts that have happened. Like commands, they are DTOs decorated with @Event().

import { Event } from "@lindorm/hermes";

@Event()
export class AccountOpened {
  public constructor(
    public readonly ownerName: string,
    public readonly currency: string,
    public readonly initialBalance: number,
  ) {}
}

@Event()
export class FundsWithdrawn {
  public constructor(public readonly amount: number) {}
}

When evolving event schemas over time, use versioned class names (FundsDeposited_V1, FundsDeposited_V2) together with @EventUpcaster.

Defining an Aggregate

An Aggregate is the core domain object. It receives commands, enforces business rules, and applies events that mutate its state.

import {
  Aggregate,
  AggregateCommandHandler,
  AggregateEventHandler,
  AggregateErrorHandler,
  EventUpcaster,
  Namespace,
  RequireCreated,
  RequireNotCreated,
  Validate,
  DomainError,
} from "@lindorm/hermes";
import type {
  AggregateCommandCtx,
  AggregateEventCtx,
  AggregateErrorCtx,
} from "@lindorm/hermes";

type AccountState = {
  ownerName: string;
  currency: string;
  balance: number;
  status: "open" | "closed" | "flagged";
  transactionCount: number;
};

@Aggregate()
@Namespace("banking")
export class AccountAggregate {
  // -- Command handlers --

  @AggregateCommandHandler(OpenAccount)
  @RequireNotCreated()
  @Validate(OpenAccountSchema)
  async onOpenAccount(
    ctx: AggregateCommandCtx<OpenAccount, AccountState>,
  ): Promise<void> {
    await ctx.apply(
      new AccountOpened(
        ctx.command.ownerName,
        ctx.command.currency,
        ctx.command.initialDeposit,
      ),
    );
  }

  @AggregateCommandHandler(DepositFunds)
  @RequireCreated()
  @Validate(DepositFundsSchema)
  async onDepositFunds(
    ctx: AggregateCommandCtx<DepositFunds, AccountState>,
  ): Promise<void> {
    await ctx.apply(new FundsDeposited_V2(ctx.command.amount, ctx.command.currency));
  }

  @AggregateCommandHandler(WithdrawFunds)
  @RequireCreated()
  @Validate(WithdrawFundsSchema)
  async onWithdrawFunds(
    ctx: AggregateCommandCtx<WithdrawFunds, AccountState>,
  ): Promise<void> {
    if (ctx.state.balance < ctx.command.amount) {
      throw new DomainError("Insufficient funds", {
        data: { balance: ctx.state.balance, requested: ctx.command.amount },
      });
    }
    await ctx.apply(new FundsWithdrawn(ctx.command.amount));
  }

  @AggregateCommandHandler(CloseAccount)
  @RequireCreated()
  async onCloseAccount(
    ctx: AggregateCommandCtx<CloseAccount, AccountState>,
  ): Promise<void> {
    if (ctx.state.balance !== 0) {
      throw new DomainError("Cannot close account with non-zero balance", {
        data: { balance: ctx.state.balance },
      });
    }
    await ctx.apply(new AccountClosed());
  }

  // -- Event handlers (state mutations) --

  @AggregateEventHandler(AccountOpened)
  async onAccountOpened(
    ctx: AggregateEventCtx<AccountOpened, AccountState>,
  ): Promise<void> {
    ctx.mergeState({
      ownerName: ctx.event.ownerName,
      currency: ctx.event.currency,
      balance: ctx.event.initialBalance,
      status: "open",
      transactionCount: ctx.event.initialBalance > 0 ? 1 : 0,
    });
  }

  @AggregateEventHandler(FundsDeposited_V2)
  async onFundsDeposited(
    ctx: AggregateEventCtx<FundsDeposited_V2, AccountState>,
  ): Promise<void> {
    ctx.mergeState({
      balance: ctx.state.balance + ctx.event.amount,
      transactionCount: ctx.state.transactionCount + 1,
    });
  }

  @AggregateEventHandler(FundsWithdrawn)
  async onFundsWithdrawn(
    ctx: AggregateEventCtx<FundsWithdrawn, AccountState>,
  ): Promise<void> {
    ctx.mergeState({
      balance: ctx.state.balance - ctx.event.amount,
      transactionCount: ctx.state.transactionCount + 1,
    });
  }

  @AggregateEventHandler(AccountClosed)
  async onAccountClosed(
    ctx: AggregateEventCtx<AccountClosed, AccountState>,
  ): Promise<void> {
    ctx.mergeState({ status: "closed" });
    ctx.destroy();
  }

  // -- Event upcaster --

  @EventUpcaster(FundsDeposited_V1, FundsDeposited_V2)
  upcastFundsDepositedV1toV2(event: FundsDeposited_V1): FundsDeposited_V2 {
    return new FundsDeposited_V2(event.amount, "USD");
  }

  // -- Error handler --

  @AggregateErrorHandler(DomainError)
  async onDomainError(ctx: AggregateErrorCtx): Promise<void> {
    ctx.logger.warn("Aggregate domain error", { error: ctx.error.message });
  }
}

Aggregate command handler context

The AggregateCommandCtx<C, S> gives you:

Property	Description
ctx.command	The command instance (typed as C)
ctx.state	Current aggregate state (typed as S)
ctx.logger	Scoped logger
ctx.meta	Command metadata
ctx.apply(event)	Apply an event to the aggregate

Aggregate event handler context

The AggregateEventCtx<E, S> gives you:

Property	Description
ctx.event	The event instance (typed as E)
ctx.state	Current aggregate state (typed as S)
ctx.logger	Scoped logger
ctx.mergeState(partial)	Shallow-merge partial state
ctx.setState(state)	Replace entire state
ctx.destroy()	Mark aggregate as destroyed
ctx.destroyNext()	Mark aggregate as destroyed after this event

Defining a Saga

A Saga is a long-running process manager that reacts to events and coordinates cross-aggregate workflows by dispatching commands and scheduling timeouts.

import {
  Saga,
  SagaEventHandler,
  SagaIdHandler,
  SagaTimeoutHandler,
  SagaErrorHandler,
  Namespace,
  RequireCreated,
  RequireNotCreated,
  DomainError,
} from "@lindorm/hermes";
import type {
  SagaEventCtx,
  SagaIdCtx,
  SagaTimeoutCtx,
  SagaErrorCtx,
} from "@lindorm/hermes";

type OverdraftProtectionState = {
  ownerName: string;
  balance: number;
  lowBalanceWarning: boolean;
  lastActivityAt: string;
};

@Saga(AccountAggregate)
@Namespace("banking")
export class OverdraftProtectionSaga {
  @SagaEventHandler(AccountOpened)
  @RequireNotCreated()
  async onAccountOpened(
    ctx: SagaEventCtx<AccountOpened, OverdraftProtectionState>,
  ): Promise<void> {
    ctx.mergeState({
      ownerName: ctx.event.ownerName,
      balance: ctx.event.initialBalance,
      lowBalanceWarning: ctx.event.initialBalance < 100,
      lastActivityAt: new Date().toISOString(),
    });

    // Schedule a timeout (fires after 30 seconds)
    ctx.timeout("inactivity_check", { accountId: ctx.aggregate.id }, 30_000);
  }

  @SagaEventHandler(FundsWithdrawn)
  @RequireCreated()
  async onFundsWithdrawn(
    ctx: SagaEventCtx<FundsWithdrawn, OverdraftProtectionState>,
  ): Promise<void> {
    const newBalance = ctx.state.balance - ctx.event.amount;
    ctx.mergeState({ balance: newBalance });

    if (newBalance < 100) {
      // Dispatch a command to another (or the same) aggregate
      ctx.dispatch(new FlagAccount(`Balance dropped below threshold: ${newBalance}`), {
        id: ctx.aggregate.id,
      });
    }
  }

  @SagaEventHandler(AccountClosed)
  @RequireCreated()
  async onAccountClosed(
    ctx: SagaEventCtx<AccountClosed, OverdraftProtectionState>,
  ): Promise<void> {
    ctx.destroy();
  }

  // Resolve the saga ID from an event (required for all events)
  @SagaIdHandler(AccountOpened)
  resolveId(ctx: SagaIdCtx<AccountOpened>): string {
    return ctx.aggregate.id;
  }

  // Handle scheduled timeouts
  @SagaTimeoutHandler(InactivityTimeout)
  async onInactivityTimeout(
    ctx: SagaTimeoutCtx<InactivityTimeout, OverdraftProtectionState>,
  ): Promise<void> {
    ctx.logger.info("Inactivity timeout fired", {
      accountId: ctx.event.accountId,
    });
    // Re-schedule for continuous monitoring
    ctx.timeout("inactivity_check", { accountId: ctx.event.accountId }, 30_000);
  }

  @SagaErrorHandler(DomainError)
  async onDomainError(ctx: SagaErrorCtx): Promise<void> {
    ctx.logger.warn("Saga domain error", { error: ctx.error.message });
  }
}

Saga event handler context

The SagaEventCtx<E, S> gives you:

Property	Description
ctx.event	The event instance (typed as E)
ctx.state	Current saga state (typed as S)
ctx.aggregate	The source aggregate identity { id, name, namespace }
ctx.logger	Scoped logger
ctx.meta	Event metadata
ctx.mergeState(partial)	Shallow-merge partial state
ctx.setState(state)	Replace entire state
ctx.destroy()	Mark saga as destroyed
ctx.dispatch(command, opts?)	Dispatch a command
ctx.timeout(name, data, delayMs)	Schedule a timeout

Defining a View

A View is a read-model (projection) that materialises events into a queryable entity. Views use Proteus entities for persistence.

Step 1: Define the view entity

import { Entity, Namespace, Field, Index, Default } from "@lindorm/proteus";
import { HermesViewEntity } from "@lindorm/hermes";

@Entity({ name: "account_summary" })
@Namespace("banking")
export class AccountSummaryView extends HermesViewEntity {
  @Field("string")
  @Index()
  @Default("")
  ownerName: string = "";

  @Field("string")
  @Default("USD")
  currency: string = "USD";

  @Field("float")
  @Default(0)
  balance: number = 0;

  @Field("string")
  @Index()
  @Default("open")
  status: string = "open";

  @Field("integer")
  @Default(0)
  transactionCount: number = 0;
}

HermesViewEntity extends the Proteus base entity and provides id, destroyed, revision, createdAt, and updatedAt fields automatically.

Step 2: Define the view projection

import {
  View,
  ViewEventHandler,
  ViewIdHandler,
  ViewQueryHandler,
  ViewErrorHandler,
  Namespace,
  RequireCreated,
  RequireNotCreated,
  DomainError,
} from "@lindorm/hermes";
import type {
  ViewEventCtx,
  ViewIdCtx,
  ViewQueryCtx,
  ViewErrorCtx,
} from "@lindorm/hermes";

@View(AccountAggregate, AccountSummaryView)
@Namespace("banking")
export class AccountSummaryProjection {
  @ViewEventHandler(AccountOpened)
  @RequireNotCreated()
  async onAccountOpened(
    ctx: ViewEventCtx<AccountOpened, AccountSummaryView>,
  ): Promise<void> {
    ctx.entity.ownerName = ctx.event.ownerName;
    ctx.entity.currency = ctx.event.currency;
    ctx.entity.balance = ctx.event.initialBalance;
    ctx.entity.status = "open";
    ctx.entity.transactionCount = ctx.event.initialBalance > 0 ? 1 : 0;
  }

  @ViewEventHandler(FundsDeposited_V2)
  @RequireCreated()
  async onFundsDeposited(
    ctx: ViewEventCtx<FundsDeposited_V2, AccountSummaryView>,
  ): Promise<void> {
    ctx.entity.balance += ctx.event.amount;
    ctx.entity.transactionCount += 1;
  }

  @ViewEventHandler(AccountClosed)
  @RequireCreated()
  async onAccountClosed(
    ctx: ViewEventCtx<AccountClosed, AccountSummaryView>,
  ): Promise<void> {
    ctx.entity.status = "closed";
    ctx.destroy();
  }

  @ViewIdHandler(AccountOpened)
  resolveId(ctx: ViewIdCtx<AccountOpened>): string {
    return ctx.aggregate.id;
  }

  @ViewQueryHandler(GetAccountSummary)
  async onGetAccountSummary(
    ctx: ViewQueryCtx<GetAccountSummary, AccountSummaryView>,
  ): Promise<AccountSummaryView | null> {
    return ctx.repository.findOne({ id: ctx.query.accountId });
  }

  @ViewErrorHandler(DomainError)
  onDomainError(ctx: ViewErrorCtx<AccountSummaryView>): void {
    ctx.logger.warn("View domain error", { error: ctx.error.message });
  }
}

Views use direct entity mutation (ctx.entity.balance += amount) rather than mergeState. The entity is automatically persisted after each handler invocation.

View event handler context

Property	Description
ctx.event	The event instance (typed as E)
ctx.entity	The view entity instance (typed as V) -- mutate directly
ctx.logger	Scoped logger
ctx.meta	Event metadata
ctx.destroy()	Mark view entity as destroyed

View query handler context

Property	Description
ctx.query	The query instance (typed as Q)
ctx.logger	Scoped logger
ctx.repository	IProteusRepository<V> for the view entity

Defining Queries

Queries are simple DTOs that carry read parameters:

import { Query } from "@lindorm/hermes";

@Query()
export class GetAccountSummary {
  public constructor(public readonly accountId: string) {}
}

Queries are handled by @ViewQueryHandler methods on view classes.

Defining Timeouts

Timeouts are DTOs scheduled by sagas for delayed processing:

import { Timeout } from "@lindorm/hermes";

@Timeout()
export class InactivityTimeout {
  public constructor(public readonly accountId: string) {}
}

Timeouts are dispatched from saga handlers via ctx.timeout(name, data, delayMs) and handled by @SagaTimeoutHandler methods.

Event Upcasting (schema evolution)

When an event schema changes, old events in the store need to be read with the new schema. Hermes solves this with @EventUpcaster decorators that transparently transform old event versions to new ones at load time. The original events in the store are never modified.

// V1: original event (amount only)
@Event()
export class FundsDeposited_V1 {
  public constructor(public readonly amount: number) {}
}

// V2: new event (amount + currency)
@Event()
export class FundsDeposited_V2 {
  public constructor(
    public readonly amount: number,
    public readonly currency: string,
  ) {}
}

Register the upcaster on the aggregate:

@EventUpcaster(FundsDeposited_V1, FundsDeposited_V2)
upcastFundsDepositedV1toV2(event: FundsDeposited_V1): FundsDeposited_V2 {
  return new FundsDeposited_V2(event.amount, "USD");
}

Upcasters can be chained: V1 -> V2 -> V3. Hermes resolves the full chain automatically.

Validation with Zod

Use @Validate(schema) on command handlers to validate payloads at runtime before the handler executes:

import { z } from "zod";

const DepositFundsSchema = z.object({
  amount: z.number().positive(),
  currency: z.string().min(1),
});

@AggregateCommandHandler(DepositFunds)
@RequireCreated()
@Validate(DepositFundsSchema)
async onDepositFunds(ctx: AggregateCommandCtx<DepositFunds, AccountState>): Promise<void> {
  await ctx.apply(new FundsDeposited_V2(ctx.command.amount, ctx.command.currency));
}

If validation fails, a CommandSchemaValidationError is thrown (permanent, not retried).

Lifecycle guards

Use @RequireCreated() and @RequireNotCreated() to enforce aggregate/saga/view lifecycle constraints:

@AggregateCommandHandler(OpenAccount)
@RequireNotCreated()   // fails if aggregate already exists
async onOpenAccount(ctx) { ... }

@AggregateCommandHandler(DepositFunds)
@RequireCreated()      // fails if aggregate doesn't exist yet
async onDepositFunds(ctx) { ... }

These work on aggregate command handlers, saga event handlers, and view event handlers.

Error handling

Domain errors are handled by dedicated error handlers on each domain type:

@AggregateErrorHandler(DomainError)
async onDomainError(ctx: AggregateErrorCtx): Promise<void> {
  ctx.logger.warn("Domain error occurred", { error: ctx.error.message });
}

@SagaErrorHandler(DomainError)
async onSagaError(ctx: SagaErrorCtx): Promise<void> {
  // Can dispatch compensating commands
  ctx.dispatch(new CompensateCommand(), { id: ctx.aggregate.id });
}

@ViewErrorHandler(DomainError)
onViewError(ctx: ViewErrorCtx<AccountSummaryView>): void {
  ctx.logger.warn("View error", { error: ctx.error.message });
}

DomainError supports a permanent flag. Permanent errors are never retried; transient errors are retried automatically by the infrastructure.

Setting up Hermes

import { Hermes } from "@lindorm/hermes";
import { ProteusSource } from "@lindorm/proteus";
import { IrisSource } from "@lindorm/iris";

const hermes = new Hermes({
  // Required: persistence source (event store, saga store, view store)
  proteus: new ProteusSource({ driver: "memory", logger }),

  // Optional: additional view sources (for views stored in different databases)
  viewSources: [new ProteusSource({ driver: "postgres", url: "...", logger })],

  // Required: messaging source (command bus, event bus)
  iris: new IrisSource({ driver: "memory", logger }),

  // Required: module classes or glob patterns
  modules: [AccountAggregate, OverdraftProtectionSaga, AccountSummaryProjection],

  // Required: logger
  logger,

  // Optional: default namespace for all modules
  namespace: "banking",

  // Optional: encryption config for @Forgettable fields
  encryption: {
    algorithm: "aes-256-gcm",
  },

  // Optional: checksum mode ("strict" throws, "warn" logs)
  checksumMode: "strict",

  // Optional: how long causation records are kept
  causationExpiry: "7d",
});

await hermes.setup();
// ... use hermes ...
await hermes.teardown();

HermesOptions

Option	Type	Required	Description
proteus	ProteusSource	yes	Primary persistence source
viewSources	ProteusSource[]	no	Additional sources for views
iris	IIrisSource	yes	Messaging source
modules	ClassLike[] | string[]	yes	Module classes or glob paths
logger	ILogger	yes	Logger instance
namespace	string	no	Default namespace
encryption	object	no	Encryption settings for forgettable data
checksumMode	"strict" | "warn"	no	Checksum validation mode
causationExpiry	ReadableTime	no	Causation record TTL

Lifecycle

Method	Description
hermes.setup()	Scans modules, builds registry, initialises stores, starts message consumers
hermes.teardown()	Stops all consumers and closes connections
hermes.clone({ logger? })	Creates a new Hermes instance sharing internal state (useful for per-request loggers)
hermes.status	Returns "created" | "initialising" | "ready" | "stopping" | "stopped"

Dispatching commands

// Create a new aggregate (Hermes generates the ID)
const { id, name, namespace } = await hermes.command(
  new OpenAccount("Alice", "USD", 500),
);

// Target an existing aggregate by ID
await hermes.command(new DepositFunds(200, "USD"), { id });

// With options
await hermes.command(new DepositFunds(100, "USD"), {
  id,
  correlationId: "tx-123", // correlation tracking
  delay: 5000, // delayed delivery (ms)
  meta: { source: "api" }, // arbitrary metadata
});

hermes.command() returns an AggregateIdentifier:

type AggregateIdentifier = {
  id: string;
  name: string;
  namespace: string;
};

Querying views

const summary = await hermes.query<AccountSummaryView>(new GetAccountSummary(accountId));

The return type is determined by the generic parameter and whatever the @ViewQueryHandler method returns.

Event emitter

Hermes exposes an event emitter for real-time change notifications. The pattern is scope.namespace.name.id with progressive specificity:

// Any saga changed
hermes.on("saga", (data) => { ... });

// Any saga in the "banking" namespace
hermes.on("saga.banking", (data) => { ... });

// A specific saga type
hermes.on("saga.banking.overdraft_protection", (data) => { ... });

// A specific saga instance
hermes.on(`saga.banking.overdraft_protection.${id}`, (data) => { ... });

Use hermes.off(event, callback) to unsubscribe.

Admin API

The hermes.admin facade provides inspection, maintenance and replay tools.

Inspect

// Load full aggregate state (replays all events)
const aggregate = await hermes.admin.inspect.aggregate<AccountState>({
  id: "...",
  name: "account_aggregate",
  namespace: "banking",
});
// => { id, name, namespace, destroyed, events, numberOfLoadedEvents, state }

// Load saga state
const saga = await hermes.admin.inspect.saga<OverdraftProtectionState>({
  id: "...",
  name: "overdraft_protection",
  namespace: "banking",
});
// => { id, name, namespace, destroyed, revision, state, ... } | null

// Load a view entity
const view = await hermes.admin.inspect.view<AccountSummaryView>({
  id: "...",
  entity: AccountSummaryView,
});
// => AccountSummaryView | null

Replay

Rebuild views or re-process aggregate events from the event store:

const handle = hermes.admin.replay.view(AccountSummaryView, {
  strategy: "truncate", // wipe existing data first
});

handle.on("progress", (p: ReplayProgress) => {
  console.log(`${p.phase}: ${p.percent}% (${p.processed}/${p.total})`);
});

handle.on("complete", () => console.log("Replay finished"));
handle.on("error", (err) => console.error(err));

// Await completion
await handle.promise;

// Or cancel early
handle.cancel();

Maintenance

// Purge expired causation records
const removed = await hermes.admin.purgeCausations();

Decorator reference

DTO decorators (class-level)

Decorator	Target	Description
@Command(name?, version?)	class	Marks class as a command DTO
@Event(name?, version?)	class	Marks class as an event DTO
@Query(name?)	class	Marks class as a query DTO
@Timeout(name?, version?)	class	Marks class as a timeout DTO

Domain decorators (class-level)

Decorator	Target	Description
@Aggregate(name?)	class	Marks class as an aggregate handler
@Saga(AggregateClass | AggregateClass[])	class	Marks class as a saga, bound to aggregate(s)
@View(AggregateClass | AggregateClass[], EntityClass)	class	Marks class as a view, bound to aggregate(s) and entity

Composable decorators (class-level)

Decorator	Target	Description
@Namespace(string)	class	Scopes the handler to a namespace
@Forgettable()	class	Marks class as supporting GDPR-style event forgetting

Handler decorators (method-level)

Decorator	Target	Description
@AggregateCommandHandler(CommandClass)	method	Handles a command on an aggregate
@AggregateEventHandler(EventClass)	method	Handles an event on an aggregate (state mutation)
@AggregateErrorHandler(ErrorClass)	method	Handles errors on an aggregate
@EventUpcaster(FromClass, ToClass)	method	Transforms old event version to new one
@SagaEventHandler(EventClass)	method	Handles an event on a saga
@SagaIdHandler(EventClass)	method	Resolves saga ID from an event
@SagaTimeoutHandler(TimeoutClass)	method	Handles a timeout on a saga
@SagaErrorHandler(ErrorClass)	method	Handles errors on a saga
@ViewEventHandler(EventClass)	method	Handles an event on a view
@ViewIdHandler(EventClass)	method	Resolves view ID from an event
@ViewQueryHandler(QueryClass)	method	Handles a query on a view
@ViewErrorHandler(ErrorClass)	method	Handles errors on a view

Guard decorators (method-level)

Decorator	Target	Description
@RequireCreated()	method	Handler only runs if entity exists
@RequireNotCreated()	method	Handler only runs if entity does not exist
@Validate(zodSchema)	method	Validates command payload before handler runs

Context reference

Aggregate contexts

AggregateCommandCtx<C, S> -- passed to @AggregateCommandHandler methods

Property	Type	Description
command	C	Command instance
state	S	Current aggregate state
logger	ILogger	Scoped logger
meta	Dict	Command metadata
apply(event)	(event) => Promise<void>	Apply an event

AggregateEventCtx<E, S> -- passed to @AggregateEventHandler methods

Property	Type	Description
event	E	Event instance
state	S	Current aggregate state
logger	ILogger	Scoped logger
meta	Dict	Event metadata
mergeState(partial)	(Partial<S>) => void	Shallow-merge state
setState(state)	(S) => void	Replace entire state
destroy()	() => void	Mark aggregate as destroyed
destroyNext()	() => void	Destroy after this event

AggregateErrorCtx -- passed to @AggregateErrorHandler methods

Property	Type	Description
error	Error	The error
logger	ILogger	Scoped logger
dispatch(command, opts?)	function	Dispatch a compensating command

Saga contexts

SagaEventCtx<E, S> -- passed to @SagaEventHandler methods

Property	Type	Description
event	E	Event instance
state	S	Current saga state
aggregate	AggregateIdentifier	Source aggregate identity
logger	ILogger	Scoped logger
meta	Dict	Event metadata
mergeState(partial)	(Partial<S>) => void	Shallow-merge state
setState(state)	(S) => void	Replace entire state
destroy()	() => void	Mark saga as destroyed
dispatch(command, opts?)	function	Dispatch a command
timeout(name, data, delayMs)	function	Schedule a timeout

SagaIdCtx<E> -- passed to @SagaIdHandler methods

Property	Type	Description
event	E	Event instance
aggregate	AggregateIdentifier	Source aggregate identity
logger	ILogger	Scoped logger

SagaTimeoutCtx<E, S> -- passed to @SagaTimeoutHandler methods

Same shape as SagaEventCtx<E, S>.

SagaErrorCtx -- passed to @SagaErrorHandler methods

Property	Type	Description
error	Error	The error
logger	ILogger	Scoped logger
dispatch(command, opts?)	function	Dispatch a compensating command

View contexts

ViewEventCtx<E, V> -- passed to @ViewEventHandler methods

Property	Type	Description
event	E	Event instance
entity	V	View entity instance (mutate directly)
logger	ILogger	Scoped logger
meta	Dict	Event metadata
destroy()	() => void	Mark entity as destroyed

ViewIdCtx<E> -- passed to @ViewIdHandler methods

Property	Type	Description
event	E	Event instance
aggregate	AggregateIdentifier	Source aggregate identity
logger	ILogger	Scoped logger

ViewQueryCtx<Q, V> -- passed to @ViewQueryHandler methods

Property	Type	Description
query	Q	Query instance
logger	ILogger	Scoped logger
repository	IProteusRepository<V>	Full Proteus repository for the view entity

ViewErrorCtx<V> -- passed to @ViewErrorHandler methods

Property	Type	Description
error	Error	The error
entity	V	View entity instance
logger	ILogger	Scoped logger
dispatch(command, opts?)	function	Dispatch a compensating command

Type reference

Identity and state

type AggregateIdentifier = {
  id: string;
  name: string;
  namespace: string;
};

type AggregateState<S> = {
  id: string;
  name: string;
  namespace: string;
  destroyed: boolean;
  events: Array<unknown>;
  numberOfLoadedEvents: number;
  state: S;
};

type SagaState<S> = {
  id: string;
  name: string;
  namespace: string;
  destroyed: boolean;
  messagesToDispatch: Array<unknown>;
  revision: number;
  state: S;
  createdAt: Date;
  updatedAt: Date;
};

Dispatch options

type SagaDispatchOptions = {
  id?: string;
  delay?: number;
  mandatory?: boolean;
  meta?: Dict;
};

type ErrorDispatchOptions = {
  id?: string;
  delay?: number;
  mandatory?: boolean;
  meta?: Dict;
};

Replay

type ReplayOptions = {
  strategy?: "truncate";
};

type ReplayProgress = {
  phase: "truncating" | "replaying" | "resuming" | "complete";
  processed: number;
  total: number;
  percent: number;
  skipped: number;
};

type ReplayHandle = {
  on(event: "progress", cb: (p: ReplayProgress) => void): void;
  on(event: "complete", cb: () => void): void;
  on(event: "error", cb: (err: Error) => void): void;
  cancel(): void;
  promise: Promise<void>;
};

Configuration

type HermesStatus = "created" | "initialising" | "ready" | "stopping" | "stopped";
type ChecksumMode = "strict" | "warn";

Error reference

All domain errors extend DomainError which carries a permanent flag. Permanent errors are never retried by the infrastructure.

Error	Permanent	When
DomainError	configurable	Base class for domain-level errors
AggregateAlreadyCreatedError	yes	Command targets an aggregate that already exists
AggregateNotCreatedError	yes	Command targets an aggregate that doesn't exist
AggregateDestroyedError	yes	Command targets a destroyed aggregate
AggregateNotDestroyedError	yes	Expected aggregate to be destroyed
SagaAlreadyCreatedError	configurable	Event received for an already-created saga
SagaNotCreatedError	configurable	Event received for a non-existent saga
SagaDestroyedError	yes	Event received for a destroyed saga
ViewAlreadyCreatedError	configurable	Event received for an already-created view
ViewNotCreatedError	configurable	Event received for a non-existent view
ViewDestroyedError	yes	Event received for a destroyed view
ViewNotUpdatedError	yes	View handler did not mutate the entity
CommandSchemaValidationError	yes	@Validate schema rejected the command payload
ChecksumError	yes	Event checksum mismatch detected
ConcurrencyError	no	Optimistic concurrency conflict (automatically retried)
CausationMissingEventsError	no	Expected causation events not found
HandlerNotRegisteredError	no	No handler registered for command/event
UpcasterChainError	no	Upcaster chain is broken or circular

License

Distributed under the AGPL-3.0-or-later license. See LICENSE for more information.