useInspectHistory

Stable · since 0.1.0

Returns the most recent limit inspector snapshots from the active runtime, newest first. The hook subscribes to runtime.subscribe and re-renders whenever a new run is recorded — use it for in-app devtools panels, “last 20 runs” lists, or any UI that needs a live event log.

Snapshots include all triggers in the runtime — there is no per-trigger filter. To narrow to one trigger, filter the returned array.

Import

import { useInspectHistory } from '@triggery/react';

Signature

function useInspectHistory(
  limit?: number,
): readonly TriggerInspectSnapshot[];

Parameters

Param	Type	Default	Description
limit	number	20	Maximum number of snapshots to return. Capped by the runtime’s inspectorBufferSize.

Returns

A readonly TriggerInspectSnapshot[], newest first. Empty when the inspector is disabled or no runs have occurred yet.

Examples

Recent runs panel

import { useInspectHistory } from '@triggery/react';

function RecentRuns() {
  const history = useInspectHistory(50);
  return (
    <ul>
      {history.map(s => (
        <li key={s.runId}>
          <code>{s.triggerId}</code> · {s.status} · {s.durationMs.toFixed(1)}ms
        </li>
      ))}
    </ul>
  );
}

Per-trigger filter

import { useInspectHistory } from '@triggery/react';

function MessageRuns() {
  const history = useInspectHistory(100);
  const ours = history.filter(s => s.triggerId === 'chat:new-message');
  return <pre>{JSON.stringify(ours.slice(0, 10), null, 2)}</pre>;
}

Error-only view

import { useInspectHistory } from '@triggery/react';

function Errors() {
  const history = useInspectHistory(200);
  const errors = history.filter(s => s.status === 'errored');
  if (errors.length === 0) return <span>clean</span>;
  return (
    <ul>
      {errors.map(s => (
        <li key={s.runId}>
          <strong>{s.triggerId}</strong>: {s.reason}
        </li>
      ))}
    </ul>
  );
}

Status counts

import { useInspectHistory } from '@triggery/react';
import { useMemo } from 'react';

function StatusBar() {
  const history = useInspectHistory(500);
  const counts = useMemo(() => {
    const out = { fired: 0, skipped: 0, errored: 0, aborted: 0 };
    for (const s of history) out[s.status] += 1;
    return out;
  }, [history]);
  return (
    <div>
      {counts.fired}/{counts.skipped}/{counts.errored}/{counts.aborted}
    </div>
  );
}

Notes

Tip

The hook re-renders on every recorded run. For high-volume runtimes, throttle the consumer by wrapping useInspectHistory in a useDeferredValue or by displaying only every Nth update. The runtime itself stays cheap — the inspector is O(1) per record.

Inspector required

When inspector is disabled in createRuntime (or the auto default in production), runtime.subscribe is a noop and the buffer is always []. useInspectHistory returns [] and never re-renders. To enable in prod, pass inspector: true to createRuntime — see RuntimeOptions.

Note

limit is read at render time. If you change limit between renders the hook re-seeds from the runtime buffer and re-subscribes. This is fine for occasional UI toggles but not for a limit that changes every render.

Related

useInspect Latest snapshot for one trigger (no subscription).

createInspector The ring-buffer implementation.

RuntimeOptions `inspector` and `inspectorBufferSize`.

@triggery/devtools-panel Drop-in panel that uses this hook.