@usex/rule-engine

The @usex/rule-engine provides several advanced capabilities for rule processing:

• JSONPath Support: Access nested properties within your data using $.path.to.field syntax.
• 126+ Operators: A wide range of operators including Comparison, String, Numeric, Array, Date/Time, Type, Existence, Boolean, Pattern, and Persian-specific operators.
• Type Safety: Full TypeScript support utilizing generics for robust rule definitions.
• Builder Pattern: A fluent API available via @usex/rule-engine-builder for programmatic rule construction.
• Async Support: All evaluation processes are Promise-based.
• Advanced Processing: Supports batch processing, rule introspection (analyzing rules for possible inputs), and data mutations before evaluation.
• Environment Agnostic: Works seamlessly in both Node.js and browser environments with zero dependencies in the core package.

Use these patterns to implement common logic within your JSON rules:

1. Dynamic Field References (JSONPath)

Reference other fields in your data using $.path.to.field syntax in both field and value.

{
  conditions: {
    and: [{ field: '$.current.price', operator: 'less-than', value: '$.maximum.price' }]
  }
}

2. Complex Nested Conditions

Convert nested if/else or complex boolean logic into nested and/or blocks.

// (A && B) || (C && D) || E
{
  conditions: {
    or: [
      { and: [conditionA, conditionB] },
      { and: [conditionC, conditionD] },
      conditionE
    ]
  }
}

3. Array Operations

Use built-in operators for array content validation.

{
  conditions: {
    and: [
      { field: 'tags', operator: 'contains-any', value: ['urgent', 'critical'] },
      { field: 'assignees', operator: 'not-empty', value: true }
    ]
  }
}

4. Date Comparisons

Use specialized date operators for time-based logic.

{
  conditions: {
    and: [
      { field: 'subscription.expiresAt', operator: 'date-after-now', value: true },
      { field: 'lastPayment', operator: 'date-between', value: ['2025-01-01', '2025-12-31'] }
    ]
  }
}

5. Validation Rules

Include a message field in your conditions to handle validation feedback.

{
  conditions: {
    and: [
      { field: 'username', operator: 'matches', value: '^[a-z]{3,20}$', message: 'Invalid username' }
    ]
  }
}

The RuleEngine is designed with TypeScript generics to ensure type safety for both the input data and the rule results.

1. Rule<TResult>: Defines a rule where the result and default fields must match the shape of TResult.
2. Rule<TResult, TInput>: Defines a rule with specific types for both the output (TResult) and the input data (TInput) used during evaluation.
3. RuleEngine.evaluate<TResult, TInput>(rule, data): When evaluating, passing these generics ensures that the returned result.value is correctly typed.

interface DiscountResult {
  discount: number;
  code: string;
  description: string;
}

// Generic rule with full type inference
const discountRule: Rule<DiscountResult> = {
  conditions: [
    {
      and: [
        { field: "$.user.tier", operator: "equals", value: "premium" },
        { field: "$.order.total", operator: "greater-than", value: 100 }
      ],
      result: {
        discount: 0.20,
        code: "PREMIUM20",
        description: "20% premium discount"
      }
    }
  ],
  default: { discount: 0, code: "", description: "No discount" }
};

// Evaluation with full type inference
const result = await RuleEngine.evaluate<DiscountResult>(discountRule, orderData);
// result.value is automatically typed as DiscountResult

The Rule Engine uses TypeScript method overloads to automatically infer return types based on whether you are processing a single object or an array. This reduces the need for manual type guards.

Evaluator Class

• evaluate(): Returns EvaluationResult<T> for a single object, or Array<EvaluationResult<T>> for arrays.

RuleEngine Class

• evaluate(): Async evaluation with type inference.
• checkIsPassed(): Returns boolean for a single item, or boolean | boolean[] for arrays.
• getEvaluateResult(): Returns T for a single item, or T[] for arrays.
• evaluateMany(): (Renamed from evaluateMultiple) Handles both single and array criteria.

Note: All instance methods are also available as static methods with matching overloads.

ObjectDiscovery Class

• resolveProperty(), updateProperty(), and resolveTextPathExpressions(): All support both single objects and arrays.

The rule engine supports a plugin system via the RuleEnginePlugin interface. Plugins can hook into the engine's lifecycle and extend its core capabilities by providing new operators, mutations, or validators.

Lifecycle Hooks:

• onInit(engine: RuleEngine): Called when the plugin is registered.
• beforeEvaluate(rule: RuleType, criteria: any): Executed before a rule is evaluated.
• afterEvaluate(result: EvaluationResult): Executed after evaluation completes.

Extension Points:

• operators: A record of OperatorDefinition objects.
• mutations: A record of MutationFunction objects.
• validators: A record of ValidatorFunction objects.

interface RuleEnginePlugin {
  name: string;
  version: string;
  
  // Lifecycle hooks
  onInit?(engine: RuleEngine): void;
  beforeEvaluate?(rule: RuleType, criteria: any): void;
  afterEvaluate?(result: EvaluationResult): void;
  
  // Extension points
  operators?: Record<string, OperatorDefinition>;
  mutations?: Record<string, MutationFunction>;
  validators?: Record<string, ValidatorFunction>;
}