createRuntime

Stable · since 0.1.0

createRuntime returns an isolated Runtime — the container that holds triggers, conditions and actions for a tree of components. Most apps create one runtime in main.tsx and pass it down via <TriggerRuntimeProvider>. Skip the call entirely and Triggery uses a lazily created default runtime via getDefaultRuntime.

Import

import { createRuntime } from '@triggery/core';

Signature

function createRuntime(options?: RuntimeOptions): Runtime;

Options

Field	Type	Default	Description
`inspector`	`boolean \| { dev?: boolean; prod?: boolean } \| InspectorFactory`	DEV `true`, PROD `false`	Enable / disable the per-run inspector. v0.10+: pass `createInspectorFactory()` from `@triggery/core/inspect` for the bundle-friendly opt-in pattern.
`inspectorBufferSize`	`number`	`50`	Inspector ring-buffer size. Ignored when the inspector is disabled.
`middleware`	`readonly Middleware[]`	`[]`	Middleware chain.
`maxCascadeDepth`	`number`	`3`	Maximum cascade depth — `action → fireEvent → …`. Runs above this are skipped with `'overflow'`.

See RuntimeOptions for the full shape.

Returns

A Runtime object. The methods most apps touch:

Method	Description
`runtime.fire(event, payload)`	Dispatch an event through the scheduler. Returns void.
`runtime.fireSync(event, payload)`	Dispatch synchronously (bypass scheduler). For tests and bench.
`runtime.subscribe(listener)`	Listen for every recorded run. Returns a `RegistrationToken`.
`runtime.getInspectorBuffer()`	Most-recent N inspector snapshots.
`runtime.getTrigger(id)`	Look up a registered trigger.
`runtime.graph()`	JSON-friendly snapshot of the registry — used by `triggery graph` CLI.
`runtime.dispose()`	Abort all in-flight runs and drop all registrations.

register* methods (registerTrigger, registerCondition, registerAction) are also part of the surface, but bindings handle them for you. v0.10+ adds runtime.subscribeAction(triggerId, name, cb, options?) — the additive subscription path that powers trigger.action(name).subscribe(cb) and is what the framework useAction hooks now use under the hood. Every subscriber runs on each emit, alongside any handler registered through registerAction.

Examples

Default — one runtime at the root

import { createRuntime } from '@triggery/core';
import { TriggerRuntimeProvider } from '@triggery/react';
import type { ComponentType } from 'react';
import { StrictMode } from 'react';
import { createRoot } from 'react-dom/client';

const runtime = createRuntime();

declare const App: ComponentType;
createRoot(document.getElementById('root')!).render(
  <StrictMode>
    <TriggerRuntimeProvider runtime={runtime}>
      <App />
    </TriggerRuntimeProvider>
  </StrictMode>,
);

Isolated runtime per test

import { createRuntimefunction createRuntime(options?: RuntimeOptions): Runtime } from '@triggery/core';
import { afterEachfunction afterEach<ExtraContext = object>(fn: AfterEachListener<ExtraContext>, timeout?: number): voidRegisters a callback function to be executed after each test within the current suite has completed.
This hook is useful for scenarios where you need to clean up or reset the test environment after each test runs, such as deleting temporary files, clearing test-specific database entries, or resetting mocked functions.

**Note:** The `afterEach` hooks are running in reverse order of their registration. You can configure this by changing the `sequence.hooks` option in the config file.
@paramfn - The callback function to be executed after each test. This function receives an `TestContext` parameter if additional test context is needed.@paramtimeout - Optional timeout in milliseconds for the hook. If not provided, the default hook timeout from the runner's configuration is used.@returns@example```ts
// Example of using afterEach to delete temporary files created during a test
afterEach(async () => {
  await fileSystem.deleteTempFiles();
});
```, beforeEachfunction beforeEach<ExtraContext = object>(fn: BeforeEachListener<ExtraContext>, timeout?: number): voidRegisters a callback function to be executed before each test within the current suite.
This hook is useful for scenarios where you need to reset or reinitialize the test environment before each test runs, such as resetting database states, clearing caches, or reinitializing variables.

**Note:** The `beforeEach` hooks are executed in the order they are defined one after another. You can configure this by changing the `sequence.hooks` option in the config file.
@paramfn - The callback function to be executed before each test. This function receives an `TestContext` parameter if additional test context is needed.@paramtimeout - Optional timeout in milliseconds for the hook. If not provided, the default hook timeout from the runner's configuration is used.@returns@example```ts
// Example of using beforeEach to reset a database state
beforeEach(async () => {
  await database.reset();
});
``` } from 'vitest';

let runtimelet runtime: Runtime = createRuntimefunction createRuntime(options?: RuntimeOptions): Runtime();

beforeEachbeforeEach<object>(fn: BeforeEachListener<object>, timeout?: number): voidRegisters a callback function to be executed before each test within the current suite.
This hook is useful for scenarios where you need to reset or reinitialize the test environment before each test runs, such as resetting database states, clearing caches, or reinitializing variables.

**Note:** The `beforeEach` hooks are executed in the order they are defined one after another. You can configure this by changing the `sequence.hooks` option in the config file.
@paramfn - The callback function to be executed before each test. This function receives an `TestContext` parameter if additional test context is needed.@paramtimeout - Optional timeout in milliseconds for the hook. If not provided, the default hook timeout from the runner's configuration is used.@returns@example```ts
// Example of using beforeEach to reset a database state
beforeEach(async () => {
  await database.reset();
});
```(() => {
  runtimelet runtime: Runtime = createRuntimefunction createRuntime(options?: RuntimeOptions): Runtime({ inspectorBufferSizeinspectorBufferSize?: number | undefinedInspector ring buffer size (default: 50). Ignored when the inspector is disabled.: 100 });
});
afterEachafterEach<object>(fn: AfterEachListener<object>, timeout?: number): voidRegisters a callback function to be executed after each test within the current suite has completed.
This hook is useful for scenarios where you need to clean up or reset the test environment after each test runs, such as deleting temporary files, clearing test-specific database entries, or resetting mocked functions.

**Note:** The `afterEach` hooks are running in reverse order of their registration. You can configure this by changing the `sequence.hooks` option in the config file.
@paramfn - The callback function to be executed after each test. This function receives an `TestContext` parameter if additional test context is needed.@paramtimeout - Optional timeout in milliseconds for the hook. If not provided, the default hook timeout from the runner's configuration is used.@returns@example```ts
// Example of using afterEach to delete temporary files created during a test
afterEach(async () => {
  await fileSystem.deleteTempFiles();
});
```(() => {
  runtimelet runtime: Runtime.disposefunction dispose(): voidTear down the runtime completely.();
});

Tight cascade limit

import { createRuntimefunction createRuntime(options?: RuntimeOptions): Runtime } from '@triggery/core';

const runtimeconst runtime: Runtime = createRuntimefunction createRuntime(options?: RuntimeOptions): Runtime({
  maxCascadeDepthmaxCascadeDepth?: number | undefinedMaximum cascade depth (action → fireEvent → ...). Default: 3.: 1,   // refuse any indirect chain — action→event→trigger is enough
});

With middleware

import { createRuntimefunction createRuntime(options?: RuntimeOptions): Runtime, type Middlewaretype 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;
} } from '@triggery/core';

const loggerconst logger: Middleware: Middlewaretype 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;
} = {
  namename: string: 'logger',
  onActionEndonActionEnd?(ctx: ActionContext & {
    durationMs: number;
    result?: unknown;
}): void({ triggerIdtriggerId: string, actionNameactionName: string, durationMsdurationMs: number }) {
    consolevar console: Console.logConsole.log(...data: any[]): voidThe **`console.log()`** static method outputs a message to the console.

[MDN Reference](https://developer.mozilla.org/docs/Web/API/console/log_static)(`[${triggerIdtriggerId: string}] ${actionNameactionName: string} ${durationMsdurationMs: number.toFixedNumber.toFixed(fractionDigits?: number): stringReturns a string representing a number in fixed-point notation.
@paramfractionDigits Number of digits after the decimal point. Must be in the range 0 - 20, inclusive.(2)}ms`);
  },
};

const runtimeconst runtime: Runtime = createRuntimefunction createRuntime(options?: RuntimeOptions): Runtime({ middlewaremiddleware?: readonly Middleware[] | undefinedGlobal middleware applied to every trigger in this runtime.: [loggerconst logger: Middleware] });

Inspector explicitly disabled

import { createRuntimefunction createRuntime(options?: RuntimeOptions): Runtime } from '@triggery/core';

const runtimeconst runtime: Runtime = createRuntimefunction createRuntime(options?: RuntimeOptions): Runtime({ inspectorinspector?: InspectorOption | undefinedEnable / disable the per-run inspector. See 
{@link 
InspectorOption
}
.: false });

Or per-environment:

import { createRuntimefunction createRuntime(options?: RuntimeOptions): Runtime } from '@triggery/core';

const runtimeconst runtime: Runtime = createRuntimefunction createRuntime(options?: RuntimeOptions): Runtime({
  inspectorinspector?: InspectorOption | undefinedEnable / disable the per-run inspector. See 
{@link 
InspectorOption
}
.: { devdev?: boolean | undefined: true, prodprod?: boolean | undefined: false },
});

Notes

getDefaultRuntime Access (and lazily create) the global singleton.

setDefaultRuntime Replace the singleton — useful in tests.

Runtime type Full method surface.

Runtime guide Narrative walkthrough of scopes, isolation, lifecycle.