@triggery/core 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,9 @@
+# @triggery/core
+
+## 0.1.0
+
+First public preview release.
+
+Declarative business-logic orchestration for React — core runtime
+
+See the [repository-level CHANGELOG](../../CHANGELOG.md#010--2026-05-16) for the full set of packages and the umbrella feature list. Future entries on this file are appended automatically by changesets.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aleksey Skhomenko
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,23 @@
+# @triggery/core
+
+Core runtime for [Triggery](https://github.com/triggeryjs/triggery) — a declarative orchestration layer for React business logic.
+
+This package contains:
+
+- `createTrigger<Schema>(config)` — define a trigger.
+- `createRuntime()` — isolated runtime (registry + scheduler + inspector).
+- `getDefaultRuntime()` / `setDefaultRuntime()` — global singleton.
+- Lifecycle middleware chain.
+- Public types and helpers.
+
+You usually do not consume this package directly — use [`@triggery/react`](../react).
+
+## Install
+
+```bash
+pnpm add @triggery/core
+```
+
+## License
+
+MIT &copy; Aleksey Skhomenko

package/dist/index.d.ts

@@ -0,0 +1,461 @@
+/**
+ * Public types of Triggery Core.
+ *
+ * Convention:
+ *   `S` — trigger schema (`TriggerSchema`).
+ *   `R` — tuple/union of required condition keys (`required`).
+ */
+/** Fallback "empty map" type used when part of the schema is omitted. */
+type EmptyRecord = Record<string, never>;
+type TriggerSchema = {
+    events?: Record<string, unknown>;
+    conditions?: Record<string, unknown>;
+    actions?: Record<string, unknown>;
+};
+type EventMap<S extends TriggerSchema> = S['events'] extends Record<string, unknown> ? S['events'] : EmptyRecord;
+type ConditionMap<S extends TriggerSchema> = S['conditions'] extends Record<string, unknown> ? S['conditions'] : EmptyRecord;
+type ActionMap<S extends TriggerSchema> = S['actions'] extends Record<string, unknown> ? S['actions'] : EmptyRecord;
+type EventKey<S extends TriggerSchema> = Extract<keyof EventMap<S>, string>;
+type ConditionKey<S extends TriggerSchema> = Extract<keyof ConditionMap<S>, string>;
+type ActionKey<S extends TriggerSchema> = Extract<keyof ActionMap<S>, string>;
+/**
+ * Discriminated union over all events in the schema.
+ * Used in `TriggerCtx.event` — handlers can branch on `event.name`.
+ */
+type EventOf<S extends TriggerSchema> = {
+    [K in EventKey<S>]: {
+        readonly name: K;
+        readonly payload: EventMap<S>[K];
+    };
+}[EventKey<S>];
+/**
+ * Conditions: required keys are non-optional, the rest are optional.
+ */
+type ConditionsCtx<C extends Record<string, unknown>, R extends keyof C = never> = {
+    readonly [K in R]: C[K];
+} & {
+    readonly [K in Exclude<keyof C, R>]?: C[K];
+};
+type ActionFn<P> = [P] extends [void] ? () => void : (payload: P) => void;
+/**
+ * Actions: all entries are optional (they may not be registered) plus
+ * chainable `debounce/throttle/defer` (V1: stubs, full implementation in V1.1+).
+ */
+type ActionsCtx<A extends Record<string, unknown>> = {
+    readonly [K in keyof A]?: ActionFn<A[K]>;
+} & {
+    debounce(ms: number): ActionsCtx<A>;
+    throttle(ms: number): ActionsCtx<A>;
+    defer(ms: number): ActionsCtx<A>;
+};
+/**
+ * `check` helpers — DSL for condition checks inside a handler.
+ *   - `is(key, predicate)` — true when the condition exists and the predicate matches.
+ *   - `all({ key: predicate, ... })` — every listed condition must exist and match.
+ *   - `any({ key: predicate, ... })` — at least one must match.
+ */
+type CheckCtx<C extends Record<string, unknown>> = {
+    is<K extends keyof C>(key: K, predicate: (value: NonNullable<C[K]>) => boolean): boolean;
+    all<M extends Partial<{
+        [K in keyof C]: (value: NonNullable<C[K]>) => boolean;
+    }>>(map: M): boolean;
+    any<M extends Partial<{
+        [K in keyof C]: (value: NonNullable<C[K]>) => boolean;
+    }>>(map: M): boolean;
+};
+/**
+ * `meta` — runtime metadata about the current run (runId, parentRunId for cascade, etc.).
+ */
+type MetaCtx = {
+    readonly runId: string;
+    readonly triggerId: string;
+    readonly scheduledAt: number;
+    readonly cascadeDepth: number;
+    readonly parentRunId?: string;
+    readonly parentTriggerId?: string;
+};
+/**
+ * The context object passed to a handler on every run.
+ */
+type TriggerCtx<S extends TriggerSchema, R extends ConditionKey<S> = never> = {
+    readonly event: EventOf<S>;
+    readonly conditions: ConditionsCtx<ConditionMap<S>, R>;
+    readonly actions: ActionsCtx<ActionMap<S>>;
+    readonly check: CheckCtx<ConditionMap<S>>;
+    readonly meta: MetaCtx;
+    readonly signal: AbortSignal;
+};
+type TriggerHandler<S extends TriggerSchema, R extends ConditionKey<S> = never> = (ctx: TriggerCtx<S, R>) => void | Promise<void>;
+type SchedulerStrategy = 'sync' | 'microtask';
+type ConcurrencyStrategy = 'sync' | 'take-latest' | 'take-every' | 'take-first' | 'queue' | 'exhaust';
+type TriggerConfig<S extends TriggerSchema, R extends ConditionKey<S> = never> = {
+    /** Unique trigger id within a runtime. */
+    id: string;
+    /** Required condition keys. The handler will not run unless all of them are registered. */
+    required?: readonly R[];
+    /** Dispatch scheduling strategy (default: `'microtask'`). */
+    schedule?: SchedulerStrategy;
+    /** Default concurrency for async actions inside the handler. */
+    concurrency?: ConcurrencyStrategy;
+    /** Scope id (for `<TriggerScope>` isolation; ignored in V1). */
+    scope?: string;
+    /** Trigger body. */
+    handler: TriggerHandler<S, R>;
+};
+/**
+ * Capitalize the first character of a string. Used to build named hook identifiers.
+ * @internal
+ */
+type CapFirst<S extends string> = S extends `${infer A}${infer B}` ? `${Uppercase<A>}${B}` : S;
+/**
+ * Convert a kebab-case key to camelCase: `'new-message'` → `'newMessage'`.
+ * @internal
+ */
+type KebabToCamel<S extends string> = S extends `${infer A}-${infer B}` ? `${A}${CapFirst<KebabToCamel<B>>}` : S;
+/** kebab-case or camelCase → PascalCase, for substitution into `use<Name>...`. */
+type ToPascal<S extends string> = CapFirst<KebabToCamel<S>>;
+/**
+ * Event hook signature — returns an emitter with a correctly typed payload.
+ */
+type EventHook<P> = () => [P] extends [void] ? () => void : (payload: P) => void;
+/**
+ * Condition hook signature.
+ */
+type ConditionHook<V> = (getter: () => V, deps?: readonly unknown[], options?: {
+    readonly subscribe?: boolean;
+}) => void;
+/**
+ * Action hook signature — registers an executor.
+ */
+type ActionHook<P> = (handler: [P] extends [void] ? () => void : (payload: P) => void) => void;
+/**
+ * Generated named hooks. Returned by `trigger.namedHooks()`.
+ */
+type NamedHooks<S extends TriggerSchema> = {
+    readonly [K in EventKey<S> as `use${ToPascal<K>}Event`]: EventHook<EventMap<S>[K]>;
+} & {
+    readonly [K in ConditionKey<S> as `use${ToPascal<K>}Condition`]: ConditionHook<ConditionMap<S>[K]>;
+} & {
+    readonly [K in ActionKey<S> as `use${ToPascal<K>}Action`]: ActionHook<ActionMap<S>[K]>;
+};
+/**
+ * The public trigger object returned by `createTrigger`.
+ */
+type Trigger<S extends TriggerSchema> = {
+    readonly id: string;
+    readonly schedule: SchedulerStrategy;
+    /** Enable / disable the trigger at runtime. */
+    enable(): void;
+    disable(): void;
+    isEnabled(): boolean;
+    /** Get the named hooks proxy (typed via template literal types). */
+    namedHooks(): NamedHooks<S>;
+    /** Snapshot of the most recent run (for devtools / `useInspect`). */
+    inspect(): TriggerInspectSnapshot | undefined;
+    /** Remove the trigger from its runtime permanently. */
+    dispose(): void;
+};
+type TriggerInspectSnapshot = {
+    readonly triggerId: string;
+    readonly runId: string;
+    readonly eventName: string;
+    readonly status: 'fired' | 'skipped' | 'errored' | 'aborted';
+    readonly reason?: string;
+    readonly durationMs: number;
+    readonly executedActions: readonly string[];
+    readonly snapshotKeys: readonly string[];
+};
+type ConditionGetter<V = unknown> = () => V;
+type UntypedActionFn = (payload: unknown) => void | Promise<void>;
+type RegistrationToken = {
+    /** Idempotent unregister. */
+    unregister(): void;
+};
+/**
+ * Per-environment override for the inspector flag. Either field may be omitted,
+ * in which case the auto default applies (DEV on, PROD off).
+ */
+type InspectorEnvOverride = {
+    readonly dev?: boolean;
+    readonly prod?: boolean;
+};
+/**
+ * Inspector configuration for `createRuntime`.
+ *
+ * - `undefined` (default) — auto: on in DEV (`process.env.NODE_ENV !== 'production'`), off in PROD.
+ * - `true` — always on regardless of env.
+ * - `false` — always off regardless of env.
+ * - `{ dev?, prod? }` — per-env override; unset fields fall back to the auto default.
+ *
+ * When off, the runtime skips the per-run buffer write, `subscribe()` callbacks
+ * never fire, `getInspectorBuffer()` returns `[]`, and the hot path drops the
+ * snapshot allocation entirely (~30-40% extra throughput on a simple dispatch).
+ * Devtools — `@triggery/devtools-redux`, `@triggery/devtools-bridge`, the React
+ * `useInspectHistory` hook — require the inspector to be on.
+ */
+type InspectorOption = boolean | InspectorEnvOverride;
+type RuntimeOptions = {
+    /** Global middleware applied to every trigger in this runtime. */
+    middleware?: readonly Middleware[];
+    /** Maximum cascade depth (action → fireEvent → ...). Default: 3. */
+    maxCascadeDepth?: number;
+    /** Inspector ring buffer size (default: 50). Ignored when the inspector is disabled. */
+    inspectorBufferSize?: number;
+    /** Enable / disable the per-run inspector. See {@link InspectorOption}. */
+    inspector?: InspectorOption;
+};
+type FireContext = {
+    readonly eventName: string;
+    readonly payload: unknown;
+    readonly cascadeDepth: number;
+    readonly parentRunId?: string;
+    readonly parentTriggerId?: string;
+    /**
+     * Linked-list reference to the parent dispatch context (the trigger
+     * currently running whose handler/action called this `fire`). The
+     * dispatcher walks this chain to detect cycles without ever allocating a
+     * `Set` of visited ids on the hot path. `undefined` on top-level fires.
+     *
+     * The full `DispatchContext` shape is internal — middleware should treat
+     * this field as opaque.
+     */
+    readonly parentContext?: {
+        readonly triggerId: string;
+        readonly parent: unknown;
+    } | undefined;
+};
+type SkipContext = {
+    readonly triggerId: string;
+    readonly eventName: string;
+    readonly reason: string;
+};
+type MatchContext = {
+    readonly triggerId: string;
+    readonly eventName: string;
+    readonly payload: unknown;
+    readonly cascadeDepth: number;
+};
+type ActionContext = {
+    readonly triggerId: string;
+    readonly runId: string;
+    readonly actionName: string;
+    readonly payload: unknown;
+};
+type CascadeContext = {
+    readonly parentTriggerId: string;
+    readonly parentRunId: string;
+    readonly newEventName: string;
+    readonly cascadeDepth: number;
+    readonly kind: 'overflow' | 'cycle';
+};
+type Middleware = {
+    readonly name: string;
+    onFire?(ctx: FireContext): void | {
+        cancel: true;
+        reason: string;
+    };
+    /**
+     * Called once per (event, trigger) pair right after dispatch picks the
+     * trigger out of `eventIndex[eventName]`, before any concurrency gate /
+     * required-check / handler invocation. Useful for tracing "which triggers
+     * were considered for this event" without instrumenting `onSkip` and
+     * `onActionStart` separately. Purely observational — there is no `cancel`
+     * here, use `onFire` if you need to short-circuit a fire entirely.
+     */
+    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;
+};
+/**
+ * Optional scoping for `registerCondition` / `registerAction`. A scope is just
+ * a string id — registrations live in their own bucket per scope. A trigger
+ * whose `scope` matches receives that bucket; triggers without scope see the
+ * global bucket (scope `''`).
+ *
+ * @see `<TriggerScope id="…">` in `@triggery/react`.
+ */
+type RegisterScopeOptions = {
+    readonly scope?: string;
+};
+/**
+ * Static, serializable description of a trigger — used by `runtime.graph()`,
+ * devtools panels, the CLI and any code that wants to introspect the registry
+ * without holding a reference to the live runtime objects.
+ */
+type TriggerGraphNode = {
+    readonly id: string;
+    readonly scope: string;
+    readonly events: readonly string[];
+    readonly required: readonly string[];
+    readonly schedule: SchedulerStrategy;
+    readonly concurrency: ConcurrencyStrategy;
+    readonly enabled: boolean;
+};
+/**
+ * JSON-friendly snapshot of the runtime's trigger registry. Stable shape —
+ * safe to log, send over a postMessage bridge, or render in devtools.
+ */
+type RuntimeGraph = {
+    readonly triggers: readonly TriggerGraphNode[];
+    /** Map of `eventName → triggerId[]`. Empty events are not included. */
+    readonly eventIndex: Readonly<Record<string, readonly string[]>>;
+};
+type Runtime = {
+    readonly id: string;
+    /**
+     * Whether the per-run inspector is active on this runtime. Devtools bridges
+     * can use this to detect "you mounted me but the runtime won't emit anything"
+     * and surface a one-time DEV warning.
+     */
+    readonly inspectorEnabled: boolean;
+    /** Register a trigger. Returns a token for later disposal. */
+    registerTrigger(config: InternalTriggerConfig): RegistrationToken;
+    /** Register a condition getter for a trigger. */
+    registerCondition(triggerId: string, name: string, getter: ConditionGetter, options?: RegisterScopeOptions): RegistrationToken;
+    /** Register an action handler for a trigger. */
+    registerAction(triggerId: string, name: string, handler: UntypedActionFn, options?: RegisterScopeOptions): RegistrationToken;
+    /** Fire an event asynchronously (through the scheduler). */
+    fire(eventName: string, payload?: unknown): void;
+    /** Run dispatch synchronously (for tests and benchmarks). */
+    fireSync(eventName: string, payload?: unknown): void;
+    /** Subscribe to all runtime events (read-only). */
+    subscribe(listener: (snapshot: TriggerInspectSnapshot) => void): RegistrationToken;
+    /** Get the most recent N runs (newest first). */
+    getInspectorBuffer(): readonly TriggerInspectSnapshot[];
+    /** Look up a trigger by id (for `useInspect` and CLI tools). */
+    getTrigger(triggerId: string): Trigger<TriggerSchema> | undefined;
+    /**
+     * JSON-friendly snapshot of the trigger registry — for devtools, the CLI's
+     * `triggery graph` command, and tooling that introspects connections.
+     */
+    graph(): RuntimeGraph;
+    /** Tear down the runtime completely. */
+    dispose(): void;
+};
+/** Internal (non-public for end users) shape consumed by the runtime. */
+type InternalTriggerConfig = {
+    readonly id: string;
+    readonly schedule: SchedulerStrategy;
+    readonly concurrency: ConcurrencyStrategy;
+    readonly required: readonly string[];
+    readonly events: readonly string[];
+    /** Scope key — `undefined`/`''` means global. See `RegisterScopeOptions`. */
+    readonly scope: string;
+    readonly handler: (ctx: InternalHandlerCtx) => void | Promise<void>;
+};
+type InternalHandlerCtx = {
+    readonly event: {
+        readonly name: string;
+        readonly payload: unknown;
+    };
+    readonly conditions: Record<string, unknown>;
+    readonly actions: Record<string, ((payload: unknown) => void) | undefined> & {
+        debounce(ms: number): InternalHandlerCtx['actions'];
+        throttle(ms: number): InternalHandlerCtx['actions'];
+        defer(ms: number): InternalHandlerCtx['actions'];
+    };
+    readonly check: CheckCtx<Record<string, unknown>>;
+    readonly meta: MetaCtx;
+    readonly signal: AbortSignal;
+};
+
+/**
+ * Builds the `check` helper bound to a specific conditions snapshot.
+ *
+ * `is`, `all` and `any` accept predicates over `NonNullable<C[K]>`: if a condition is
+ * absent (`undefined` or `null`), the predicate is not invoked and the result is `false`
+ * for that key.
+ */
+declare function createCheck<C extends Record<string, unknown>>(conditions: C): CheckCtx<C>;
+
+/**
+ * Public trigger configuration.
+ *
+ * @remarks
+ * **V1 type limitation:** `required` is enforced at runtime only — it does not narrow
+ * the types of `conditions.*` inside the handler. Every condition is `T | undefined` in
+ * the handler (even when listed in `required`). Use an early return:
+ * `if (!conditions.user) return;` — TS narrows `conditions.user` to `User` after that.
+ *
+ * Alternative: `check.is('user', (u) => u.isActive)` — typesafe predicate with NonNullable narrowing.
+ *
+ * **V1.1+** will introduce a builder API (`createTrigger<S>().require(['user']).handle(...)`)
+ * that automatically narrows required conditions.
+ */
+type CreateTriggerConfig<S extends TriggerSchema> = {
+    readonly id: string;
+    readonly events: readonly EventKey<S>[];
+    /** Required condition keys. The trigger will not run unless all of them are registered. */
+    readonly required?: readonly ConditionKey<S>[];
+    readonly schedule?: SchedulerStrategy;
+    /**
+     * Concurrency strategy applied across handler runs (default: `'take-latest'`).
+     *
+     * - `take-latest` — new run aborts the previous (`signal.aborted` becomes true).
+     * - `take-every`  — every run proceeds independently, no aborts.
+     * - `take-first` / `exhaust` — new runs are skipped while one is still in flight.
+     * - `queue`       — new runs wait for the previous to finish (serialized).
+     * - `sync`        — like `take-every`; provided as a documentation marker.
+     */
+    readonly concurrency?: ConcurrencyStrategy;
+    readonly scope?: string;
+    readonly handler: TriggerHandler<S, never>;
+};
+/**
+ * Create a trigger and register it in a runtime (the default runtime if none is passed).
+ *
+ * @example
+ * ```ts
+ * 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'],
+ *   required: ['user', 'settings'],
+ *   handler({ event, conditions, actions, check }) {
+ *     if (!conditions.user || !conditions.settings) return; // V1: manual narrowing
+ *     if (check.is('settings', (s) => s.sound)) actions.playSound?.();
+ *     actions.showToast?.({ title: event.payload.author });
+ *   },
+ * });
+ * ```
+ */
+declare function createTrigger<S extends TriggerSchema>(config: CreateTriggerConfig<S>, runtime?: Runtime): Trigger<S>;
+
+type InspectorImpl = {
+    record(snapshot: TriggerInspectSnapshot): void;
+    getBuffer(): readonly TriggerInspectSnapshot[];
+    getLastForTrigger(triggerId: string): TriggerInspectSnapshot | undefined;
+    subscribe(listener: (snapshot: TriggerInspectSnapshot) => void): () => void;
+    clear(): void;
+};
+/**
+ * Ring-buffer inspector. `record` is O(1) — writes into a fixed-size slot array
+ * with a wrap-around index, no `unshift`/`shift` allocations. `getBuffer`
+ * materializes a newest-first array on demand (rare relative to fires).
+ */
+declare function createInspector(bufferSize: number): InspectorImpl;
+
+declare function createRuntime(options?: RuntimeOptions): Runtime;
+declare function getDefaultRuntime(): Runtime;
+declare function setDefaultRuntime(runtime: Runtime): void;
+
+type Task = () => void;
+type SchedulerImpl = {
+    enqueue(task: Task): void;
+    /** Drain all pending tasks synchronously (for tests and `fireSync`). */
+    flush(): void;
+};
+declare function createScheduler(strategy: SchedulerStrategy): SchedulerImpl;
+
+export { type ActionContext, type ActionFn, type ActionHook, type ActionKey, type ActionMap, type ActionsCtx, type CascadeContext, type CheckCtx, type ConcurrencyStrategy, type ConditionGetter, type ConditionHook, type ConditionKey, type ConditionMap, type ConditionsCtx, type CreateTriggerConfig, type EmptyRecord, type EventHook, type EventKey, type EventMap, type EventOf, type FireContext, type InspectorImpl, type InternalHandlerCtx, type InternalTriggerConfig, type MatchContext, type MetaCtx, type Middleware, type NamedHooks, type RegisterScopeOptions, type RegistrationToken, type Runtime, type RuntimeGraph, type RuntimeOptions, type SchedulerImpl, type SchedulerStrategy, type SkipContext, type Task, type ToPascal, type Trigger, type TriggerConfig, type TriggerCtx, type TriggerGraphNode, type TriggerHandler, type TriggerInspectSnapshot, type TriggerSchema, type UntypedActionFn, createCheck, createInspector, createRuntime, createScheduler, createTrigger, getDefaultRuntime, setDefaultRuntime };