Middleware

Stable · since 0.1.0

A pluggable observer attached to every trigger in a runtime. The seven hooks fire at predictable points around dispatch — three of them (onFire, onSkip, onError) often pair to form a complete audit trail; the others (onBeforeMatch, onActionStart, onActionEnd, onCascade) are for tracing, metrics, and devtools.

All hooks are optional. Throwing inside a hook is caught and logged by the runtime but does not abort the run — middleware must not be load-bearing.

Import

import type { Middleware } from '@triggery/core';

Definition

type Middleware = {
  readonly name: string;

  onFire?(ctx: FireContext): void | { cancel: true; reason: string };
  onBeforeMatch?(ctx: MatchContext): void;
  onSkip?(ctx: SkipContext): void;
  onActionStart?(ctx: ActionContext): void;
  onActionEnd?(ctx: ActionContext & { durationMs: number; result?: unknown }): void;
  onError?(ctx: ActionContext & { error: unknown }): void;
  onCascade?(ctx: CascadeContext): void;
};

Hooks

name — string

Stable id for the middleware. Required. Useful in error messages and devtools panels.

onFire(ctx) -> void | { cancel: true; reason: string }

Called once per top-level (or cascade) fire(eventName, payload) before any trigger is matched. Return { cancel: true, reason } to abort the entire dispatch — no triggers run and an 'overflow'-style record is not emitted. This is the only short-circuit hook.

FireContext field	Description
eventName	The event being dispatched.
payload	The payload, opaque to middleware.
cascadeDepth	0 for top-level fires; n inside a cascade.
parentRunId?	Set when the fire happens inside a running handler.
parentTriggerId?	Same — id of the upstream trigger.
parentContext?	Opaque linked-list reference for cycle detection.

onBeforeMatch(ctx) -> void

Called once per (event, trigger) pair right after dispatch picks the trigger out of the event index — before any concurrency gate or required check. Purely observational; useful for “which triggers were considered for this event” without instrumenting onSkip and onActionStart separately.

onSkip(ctx) -> void

Called when a trigger is matched but skipped. reason is one of 'disabled', 'required-missing', 'concurrency-take-first', 'aborted', 'cycle', 'overflow', etc. Use this to track “why didn’t my trigger run”.

onActionStart(ctx) -> void

Called immediately before an action is invoked by a handler. actionName and payload are the arguments. Use for per-action tracing.

onActionEnd(ctx & { durationMs; result? }) -> void

Called when the action returns (or its returned promise resolves). durationMs is the wall-clock time from onActionStart to onActionEnd. The runtime only measures this when at least one middleware listens — there’s no cost when no middleware needs timing.

onError(ctx & { error }) -> void

Called when an action throws or its promise rejects. Pair with onActionStart to bracket a full attempt. Errors are also recorded on the inspector snapshot with status: 'errored'.

onCascade(ctx) -> void

Called when a cascade event is suppressed — kind: 'overflow' (cascadeDepth exceeded maxCascadeDepth) or kind: 'cycle' (a trigger appears in its own ancestor chain).

Examples

Tracing every fire

import { createRuntime, type Middleware } from '@triggery/core';

const tracing: Middleware = {
  name: 'tracing',
  onFire({ eventName, cascadeDepth }) {
    console.log(`[fire] ${eventName}${cascadeDepth ? ` (cascade ${cascadeDepth})` : ''}`);
  },
  onActionEnd({ triggerId, actionName, durationMs }) {
    console.log(`  ${triggerId}.${actionName} ${durationMs.toFixed(2)}ms`);
  },
};

const runtime = createRuntime({ middleware: [tracing] });

Auditing errors to a backend

import { createRuntime, type Middleware } from '@triggery/core';

const audit: Middleware = {
  name: 'audit',
  onError({ triggerId, actionName, error }) {
    void fetch('/api/log', {
      method: 'POST',
      body: JSON.stringify({
        triggerId,
        actionName,
        message: error instanceof Error ? error.message : String(error),
        stack: error instanceof Error ? error.stack : undefined,
      }),
    });
  },
};

const runtime = createRuntime({ middleware: [audit] });

Veto by onFire return

import { createRuntime, type Middleware } from '@triggery/core';

const featureFlag: Middleware = {
  name: 'feature-flag',
  onFire({ eventName }) {
    if (eventName === 'beta:experiment' && globalThis.localStorage?.getItem('beta') !== 'on') {
      return { cancel: true, reason: 'beta-disabled' };
    }
  },
};

const runtime = createRuntime({ middleware: [featureFlag] });

Track skip reasons

import { createRuntime, type Middleware } from '@triggery/core';

const skipCounter = new Map<string, number>();

const counter: Middleware = {
  name: 'skip-counter',
  onSkip({ triggerId, reason }) {
    const key = `${triggerId}:${reason}`;
    skipCounter.set(key, (skipCounter.get(key) ?? 0) + 1);
  },
};

const runtime = createRuntime({ middleware: [counter] });

Detect cycles

import { createRuntime, type Middleware } from '@triggery/core';

const guard: Middleware = {
  name: 'cycle-guard',
  onCascade({ kind, parentTriggerId, newEventName }) {
    if (kind === 'cycle') {
      console.warn(`Cycle: ${parentTriggerId} → ${newEventName} would loop back`);
    }
  },
};

const runtime = createRuntime({ middleware: [guard] });

Notes

Tip

Middleware runs in array order. onActionEnd runs in registration order even though it conceptually fires “after” the action — there is no reverse-order traversal. Order your middleware deliberately when one observes another’s behaviour.

Caution

Hooks must be cheap. The hot path skips middleware entirely when middleware.length === 0; once you add one, every hook runs on every fire. Avoid heavy work — push to a worker or queue if you need to do something expensive.

Middleware errors are swallowed

Throwing from a hook is caught and console.error-logged but doesn’t abort dispatch. Middleware is observational by design — if a hook depends on the runtime’s state, treat the hook itself as best-effort.

Related

RuntimeOptions How to attach middleware.

createRuntime The constructor that accepts middleware.

createInspector Inspector — the other observation surface.

Middleware guide Patterns: tracing, error reporting, feature flags.