RuleEngine API

Core rule evaluation engine API reference

createRuleEngine()

Factory function to create a rule engine instance.

import { createRuleEngine } from 'rule-engine-js';

const engine = createRuleEngine(config);

Parameters

config · object

Show properties

strict · boolean · default: "false"

Enable strict type checking (no coercion)

maxDepth · number · default: "10"

Maximum rule nesting depth

enableCache · boolean · default: "true"

Enable expression and path caching

maxCacheSize · number · default: "500"

Maximum cache entries (LRU eviction)

maxOperators · number · default: "100"

Maximum operators per rule

allowPrototypeAccess · boolean · default: "false"

Allow prototype property access (unsafe)

Returns

Engine instance with the following methods.

---

evaluateExpr()

Evaluate a rule expression against data.

const result = engine.evaluateExpr(rule, context);

Parameters

rule · object · required

Rule expression object

context · object · required

Data to evaluate against

Returns

{
  success: boolean;  // true if rule passed, false if failed or error
  value?: any;       // Evaluation result value (for non-boolean rules)
  error?: string;    // Error message if evaluation failed
}

Examples

Basic

const rule = { gte: ['age', 18] };
const data = { age: 25 };

const result = engine.evaluateExpr(rule, data);
// { success: true }

Complex

const rule = {
  and: [
    { gte: ['age', 18] },
    { eq: ['role', 'admin'] },
    { in: ['write', 'permissions'] }
  ]
};

const result = engine.evaluateExpr(rule, user);

Error Handling

const result = engine.evaluateExpr(rule, data);

if (!result.success) {
  console.error('Rule failed:', result.error);
}

---

registerOperator()

Register a custom operator.

engine.registerOperator(name, handler, options);

Parameters

name · string · required

Operator name (e.g., ‘custom’)

handler · function · required

Operator implementation: (args, context) => boolean

options · object

Show properties

allowOverwrite · boolean · default: "false"

Allow overwriting existing operators

Example

// Register custom operator
engine.registerOperator('divisibleBy', (args, context) => {
  const [left, right] = args;
  const value = engine.resolvePath(context, left);
  return value % right === 0;
});

// Use it
engine.evaluateExpr({ divisibleBy: ['age', 5] }, { age: 25 });
// { success: true }

---

getOperators()

Get all registered operator names.

const operators = engine.getOperators();
// ['eq', 'neq', 'gt', 'gte', 'lt', 'lte', 'and', 'or', ...]

Returns

string[] - Array of operator names

---

getMetrics()

Get performance metrics.

const metrics = engine.getMetrics();

Returns

{
  evaluations: number;  // Total evaluations
  cacheHits: number;    // Cache hits
  errors: number;       // Total errors
  totalTime: number;    // Total time (ms)
  avgTime: number;      // Average time per evaluation (ms)
}

Example

console.log('Performance:', {
  total: metrics.evaluations,
  hitRate: (metrics.cacheHits / metrics.evaluations * 100).toFixed(1) + '%',
  avgTime: metrics.avgTime.toFixed(2) + 'ms'
});

---

getCacheStats()

Get cache statistics.

const stats = engine.getCacheStats();

Returns

{
  expression: {
    size: number;      // Current cache size
    maxSize: number;   // Maximum cache size
  } | null;
  path: {
    size: number;
    maxSize: number;
  }
}

---

getConfig()

Get current configuration.

const config = engine.getConfig();
// { strict: false, maxDepth: 10, enableCache: true, ... }

Returns

object - Current configuration

---

clearCache()

Clear all caches.

engine.clearCache();

Clears both expression cache and path resolver cache. Useful for memory management or when data schema changes.

---

resolvePath()

Resolve a path in context data.

const value = engine.resolvePath(context, path, defaultValue);

Parameters

context · object · required

Data context

path · string · required

Dot-notation path (e.g., ‘user.profile.name’)

defaultValue · any

Default if path doesn’t exist

Example

const data = { user: { name: 'John', age: 25 } };

engine.resolvePath(data, 'user.name');        // 'John'
engine.resolvePath(data, 'user.email', null); // null

---

Complete Example

import { createRuleEngine } from 'rule-engine-js';

// Create engine with config
const engine = createRuleEngine({
  strict: false,
  maxDepth: 10,
  enableCache: true,
  maxCacheSize: 1000
});

// Register custom operator
engine.registerOperator('isEven', (args, context) => {
  const [path] = args;
  const value = engine.resolvePath(context, path);
  return value % 2 === 0;
});

// Define rule
const rule = {
  and: [
    { gte: ['age', 18] },
    { eq: ['role', 'admin'] },
    { isEven: ['score'] }
  ]
};

// Evaluate
const result = engine.evaluateExpr(rule, {
  age: 25,
  role: 'admin',
  score: 100
});

console.log('Result:', result.success); // true

// Check metrics
const metrics = engine.getMetrics();
console.log('Metrics:', metrics);

// Get operators
const operators = engine.getOperators();
console.log('Operators:', operators.length);

---

Error Handling

All methods handle errors gracefully:

// Invalid rule structure
const result = engine.evaluateExpr(null, data);
// { success: false, error: "Rule must be a non-null object" }

// Unknown operator
const result = engine.evaluateExpr({ unknown: ['field'] }, data);
// { success: false, error: "Unknown operator: unknown" }

// Max depth exceeded
const deepRule = { and: [{ and: [{ and: [/* ...deeply nested */ ] }] }] };
const result = engine.evaluateExpr(deepRule, data);
// { success: false, error: "Rule exceeds maximum depth of 10" }

---

TypeScript

Full TypeScript support:

import { createRuleEngine } from 'rule-engine-js';
import type { RuleEngine, RuleExpression, EvaluationResult, EngineConfig } from 'rule-engine-js';

const config: EngineConfig = {
  strict: true,
  maxDepth: 15
};

const engine: RuleEngine = createRuleEngine(config);
const rule: RuleExpression = { gte: ['age', 18] };
const result: EvaluationResult = engine.evaluateExpr(rule, data);

---

Related

Stateful Engine

Event-driven engine with state tracking

Rule Helpers

Fluent API for building rules

Operators

All built-in operators

Custom Operators

Create custom operators