TriggerSchema

Стабильный · с 0.1.0

TriggerSchema — единственный обобщённый параметр, который передают в createTrigger. Он описывает полную типизированную поверхность триггера: каждое событие, на которое тот реагирует, каждое условие, которое он умеет читать, и каждое действие, которое он может вызвать. Все три ключа необязательные; пустая схема ({}) корректна для триггеров без входов и выходов.

Импорт

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

Определение

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
};

Поля

Поле	Тип	Обязательное	Описание
events	Record<string, unknown>	нет	Мапа eventName → payloadType. Для событий без полезной нагрузки используй void.
conditions	Record<string, unknown>	нет	Мапа conditionName → valueType. Значения тянутся в pull-режиме (рантайм вызывает геттер в момент срабатывания).
actions	Record<string, unknown>	нет	Мапа actionName → payloadType. Для действий без параметров используй void.

Соглашения по именованию

Библиотека не навязывает конвенцию кейзинга — любая строка допустима как ключ. Распространённая практика в экосистеме Triggery:

• События: глаголы в kebab-case с доменным префиксом — 'new-message', 'cta:click', 'session-expired'.
• Условия: существительные в camelCase — user, activeChannelId, featureFlags.
• Действия: глаголы в camelCase — showToast, playSound, setUser.

Это хорошо сочетается с хелпером createNamedHooks, который конвертирует kebab/camel-ключи в PascalCase-имена хуков ('new-message' → useNewMessageEvent).

Примеры

Пустая схема

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

createTrigger<{}>({
  id: 'demo:empty',
  events: [],
  handler() {
    // No events, conditions or actions — useful for triggers driven by side
    // channels (timers, external callbacks) where the dispatch keeps a heartbeat.
  },
});

Схема только с событиями

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

createTrigger<{
  events: { tick: number; tock: void };
}>({
  id: 'clock',
  events: ['tick', 'tock'],
  handler({ event }) {
    if (event.name === 'tick') {
      console.log('tick payload', event.payload); // typed number
    } else {
      console.log('tock'); // typed void
    }
  },
});

Полная схема со всеми тремя мапами

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

type User = { id: string; name: string };

createTrigger<{
  events:     { 'new-message': { text: string; channelId: string } };
  conditions: { user: User | null; activeChannelId: string | null };
  actions:    { showToast: { title: string; body: string }; playSound: 'beep' | 'chime' };
}>({
  id: 'message-received',
  events: ['new-message'],
  required: ['user'],
  handler({ event, conditions, actions, check }) {
    if (event.payload.channelId === conditions.activeChannelId) return;
    actions.showToast?.({
      title: conditions.user?.name ?? '',
      body:  event.payload.text,
    });
    actions.playSound?.('beep');
  },
});

Дискриминированный union событий

Поле event в контексте обработчика — дискриминированный union по S['events']:

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

createTrigger<{
  events: { open: { id: string }; close: { id: string; reason: 'ok' | 'cancel' } };
}>({
  id: 'modal',
  events: ['open', 'close'],
  handler({ event }) {
    if (event.name === 'close') {
      // narrowed: event.payload is { id; reason } here
      console.log('closed', event.payload.reason);
    }
  },
});

Замечания

Совет

Дженерик схемы никогда не выводится автоматически — всегда передавай его явно. Id триггера, список событий и список required-условий выводятся отдельно, но типы значений в events / conditions / actions существуют только как информация уровня типов, которую ты предоставляешь.

Осторожно

required: [...] не сужает conditions.<name> до NonNullable<…> внутри обработчика в V1 — для сужения используй check.is / all / any или ранний guard.

См. также

createTrigger Конструктор, который принимает эту схему.

TriggerCtx Контекст обработчика — выводится из схемы.

Анатомия триггера Разбор поле за полем.

createNamedHooks Сгенерировать PascalCase-хуки из схемы.