createTrigger

Stable · since 0.1.0

The only constructor in Triggery. Returns a Trigger<Schema> registered in the given runtime (or the default runtime if omitted). Most apps create one trigger per scenario, one file per trigger.

Import

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

Signature

// Imperative form — v0.1+ — from '@triggery/core'
function createTrigger<S extends TriggerSchema>(
  config: CreateTriggerConfig<S>,
  runtime?: Runtime,
): Trigger<S>;

// Builder form — v0.10+ — from '@triggery/core/builder'
function createTrigger<S extends TriggerSchema>(runtime?: Runtime): TriggerBuilder<S>;

The generic S is the schema — three optional maps for events, conditions and actions. It is never inferred in normal use; always passed explicitly.

Both forms produce the same Trigger<S> object at runtime — the builder is purely a typing convenience that narrows required conditions automatically (no !, no if (!conditions.x) return;). See TriggerBuilder below.

Schema

type TriggerSchema = {
  events?:     Record<string, unknown>;  // payload type per event name
  conditions?: Record<string, unknown>;  // value type per condition name
  actions?:    Record<string, unknown>;  // payload type per action name
};

For a void payload, use void (events) or undefined (actions). Names can be any valid string; convention is kebab-case verbs for events, camelCase for conditions and actions.

Config

Field	Type	Required	Default	Description
id	string (literal)	yes	—	Unique runtime registry key. Must be a string literal — see no-dynamic-id.
events	readonly EventKey<S>[]	yes	—	Event names from S['events'] this trigger reacts to.
conditions	{ [K in ConditionKey<S>]?: ConditionMap<S>[K] | null }	no	—	v0.10+ Initial values for conditions owned by this trigger. Updated via trigger.setCondition(name, value).
required	readonly ConditionKey<S>[]	no	[]	Conditions that must be registered (and non-null/non-undefined) for the handler to run.
schedule	'microtask' | 'sync'	no	'microtask'	When to dispatch matching events.
concurrency	ConcurrencyStrategy	no	'take-latest'	How async handler runs interact.
scope	string	no	''	Restrict to a <TriggerScope id="…"> subtree.
handler	TriggerHandler<S>	yes	—	Function called when an event matches and required are satisfied.

Returns

A Trigger<S> object — a stable identity you can pass to React/Solid/Vue hooks.

Method	Description
trigger.id	Same string you passed in.
trigger.enable()	Re-enable a disabled trigger.
trigger.disable()	Skip future events (records 'disabled' in inspector).
trigger.isEnabled()	Boolean.
trigger.setCondition(name, value)	v0.10+ Update an inline condition declared in conditions: config. No-op (DEV warn-once) for keys not in config.
trigger.action(name)	v0.10+ Get the typed multi-subscriber channel for an action. Cached per (trigger, name). See ActionChannel.
trigger.inspect()	Latest TriggerInspectSnapshot or undefined.
trigger.dispose()	Unregister from the runtime. Rare — use in tests.
trigger.namedHooks()	Throws on @triggery/core directly — use createNamedHooks from a binding.

Examples

Minimal trigger

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

const ping = createTrigger<{
  events: { tick: number };
}>({
  id: 'demo:ping',
  events: ['tick'],
  handler({ event }) {
    console.log('tick', event.payload);
  },
});

Full schema with all three maps

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

type Settings = { sound: boolean; notifications: boolean };
type Message  = { author: string; text: string; channelId: string };

const messageTrigger = createTrigger<{
  events:     { 'new-message': Message };
  conditions: { settings: Settings; activeChannelId: string | null };
  actions:    { showToast: { title: string; body: string }; playSound: 'beep' };
}>({
  id: 'message-received',
  events: ['new-message'],
  required: ['settings'],
  handler({ event, conditions, actions, check }) {
    if (event.payload.channelId === conditions.activeChannelId) return;
    if (!check.is('settings', s => s.notifications)) return;

    actions.debounce(800).playSound?.('beep');
    actions.showToast?.({
      title: event.payload.author,
      body:  event.payload.text,
    });
  },
});

Async handler with AbortSignal

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

const fetchTrigger = createTrigger<{
  events:  { 'fetch-user': string };
  actions: { setUser: { id: string; name: string } };
}>({
  id: 'fetch-user',
  events: ['fetch-user'],
  concurrency: 'take-latest',
  async handler({ event, actions, signal }) {
    const res = await fetch(`/api/users/${event.payload}`, { signal });
    if (signal.aborted) return;
    actions.setUser?.(await res.json());
  },
});

Registered in a specific runtime

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

const runtime = createRuntime({ inspector: { dev: true, prod: false } });

const trigger = createTrigger<{ events: { hi: void } }>(
  {
    id: 'demo:hi',
    events: ['hi'],
    handler() {
      console.log('hi');
    },
  },
  runtime,
);

Trigger builder (v0.10+)

Calling createTrigger<S>() with no arguments returns a TriggerBuilder<S>. The builder accumulates configuration through chainable methods and finalizes with .handle(handler) — at which point the handler sees required conditions narrowed to NonNullable<...>. Import from @triggery/core/builder — the subpath keeps the builder machinery out of the main bundle.

import { createTrigger } from '@triggery/core/builder';

const messageTrigger = createTrigger<{
  events:     { 'new-message': { author: string; text: string } };
  conditions: { user: { id: string }; settings: { sound: boolean } };
  actions:    { showToast: { title: string }; playSound: void };
}>()
  .id('message-received')
  .events(['new-message'])
  .conditions({ user: null, settings: null })
  .require('user', 'settings')
  .handle(({ event, conditions, actions }) => {
    // conditions.user: { id: string }      (no `!`, no early-return guard)
    // conditions.settings: { sound: boolean }
    actions.showToast?.({ title: conditions.user.id });
    if (conditions.settings.sound) actions.playSound?.();
  });

Methods:

Method	Description
.id(string)	Required. Same as the imperative id field.
.events([...])	Required. Same as the imperative events field.
.conditions({ ... })	Optional inline values, same shape as the imperative conditions: field.
.require(...keys)	Add required condition keys. Calling .require('a').require('b') ≡ .require('a', 'b'). Narrows conditions.<key> to NonNullable<...> in .handle.
.schedule('sync' | 'microtask')	Override the scheduler.
.concurrency(strategy)	Override the concurrency strategy.
.scope(string)	Set the scope id (for <TriggerScope> isolation).
.handle(handler)	Finalize and register the trigger with the default runtime. Returns Trigger<S>.

The chained order doesn’t matter; .handle validates that id and events were set.

ActionChannel

Returned by trigger.action(name). A typed multi-subscriber channel for one action of the trigger — the v0.10 replacement for the v0.9 Set<callback> + for-of fan-out pattern.

type ActionChannel<P> = {
  subscribe(cb: (payload: P) => void): () => void;
  readonly subscribed: number;
};

Channel subscribers and any runtime.registerAction(...) handler for the same key both fire on every emit — the channel path is additive, not a replacement. The channel itself is cached per (trigger, name) so repeat calls return the same object.

const toast = messageTrigger.action('showToast');
const unsubA = toast.subscribe((p) => console.log('A', p));
const unsubB = toast.subscribe((p) => console.log('B', p));
// channel.subscribed === 2
unsubA();
// channel.subscribed === 1

Notes

Type narrowing in the builder form

The builder API (v0.10+) automatically narrows required conditions to NonNullable<...> inside .handle(...). The imperative form keeps the v0.9 behaviour — required conditions stay T | undefined and need an early guard or check.is/all/any.

Tip

Triggers can be created at module top level. Bindings (useEvent, useCondition, useAction) discover them by stable identity — there is no string-name lookup at the hook level.

Related

createRuntime The container that holds triggers, conditions and actions.

TriggerSchema The generic type — events / conditions / actions maps.

TriggerHandler The function type of the handler argument.

Trigger anatomy guide Field-by-field walkthrough, in narrative form.