Agnostic Trigger System

An advanced, event-driven rule engine for creating dynamic, conditional logic in any TypeScript/Bun application.

📚 Documentation Directory

Detailed documentation is available in the docs/ folder. Use the links below to navigate.

🚀 Getting Started

Standard installation, concepts, and creating your first rule.

• Installation
• Basic Rule Structure
• Running the Engine

📦 SDK Guide

Create rules programmatically and export them to YAML.

• RuleBuilder (Fluent API)
• RuleExporter (YAML generation)
• Server vs Client SDK

📖 API Reference

Technical details on classes, interfaces, and types.

• RuleEngine
• TriggerLoader
• triggerEmitter (Observability)
• Condition Operators (EQ, GT, MATCHES, etc.)

🧩 Architecture

How the system works under the hood.

• System Diagram
• Core Components (Loader, Engine, Expression)
• Data Flow

🛠️ Developer Tools

Tools to help you build and debug rules.

• CLI Validator (bun run validate)
• VS Code LSP Integration (Autocompletion, Linting Checks)
• Circular Dependency Detection

📝 YAML Best Practices

Recommended formats for writing rule files.

• List Format (Recommended)
• Multi-Document Format (Legacy)
• Migration Guide

💡 Step-by-Step Examples

Learn by doing with progressive tutorials.

• 1.0 Basic Rule
• 1.1 Multiple Conditions
• 1.2 Advanced Operators
• 1.4 Action Groups
• 2.0 SDK Usage
• 2.1 Dynamic Rule Updates
• 2.2 File-Based Rule Updates
• 2.3 Real-Time Rule Updates
• 2.4 Loader Watch
• 3.0 HTTP Methods (Fetch) - TypeScript
• 3.1 HTTP Methods (Fetch) - YAML

🛠️ Linting & Formatting

The project now includes built-in support for Biome to ensure code quality and consistency.

# Check for linting errors and formatting issues
bun run check

# Fix linting issues automatically
bun run lint:fix

# Format code automatically
bun run format:fix

🧠 LSP Features & Directives

The system includes a Language Server Protocol (LSP) implementation that provides:

• Autocompletion: Context-aware suggestions for keys, operators, and paths.
• Path Resolution: Smart autocomplete for file paths in imports (Linux/Windows compatible).
• Directives: Control the validator directly from your YAML files.

Supported Directives

• # @import alias from "./path/to/data.json": Import data for autocomplete context.
• # @disable-lint: Disable all linting for the file.
• # @disable-next-line: Disable linting for the next line.

📦 Installation & Import Options

npm install trigger_system

Import Patterns

The package supports multiple import patterns for different environments:

// Universal import (auto-detects environment)
import * as sdk from "trigger_system";

// Node.js specific import (includes file system features)
import * as nodeSdk from "trigger_system/node";

// Client/Browser import (optimized for browser environments)
import * as clientSdk from "trigger_system/client";
// or
import * as browserSdk from "trigger_system/browser";

Environment-Specific Features

• Node.js: Includes FilePersistence, TriggerLoader for file system access
• Browser: Includes BrowserPersistence, excludes Node.js-specific modules
• Universal: Core functionality that works in any environment

Quick Example

# rules/example.yaml
id: "high-value-transaction"
on: "PAYMENT_RECEIVED"
if:
  field: "data.amount"
  operator: "GT"
  value: 100
do:
  type: "send_alert"
  params:
    message: "Big spender! $${data.amount}"

Features

• Protocol Agnostic: Works with HTTP, WebSockets, Game Events, CLI, etc.
• Hot Reloading: Edit rules in YAML and see changes instantly.
• Type-Safe: Built with TypeScript and ArkType for robust validation.
• Smart Validation: LSP disabled by default to avoid false positives; activates via directives or rule heuristics.