> ## Documentation Index
> Fetch the complete documentation index at: https://crafts69guy.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Performance Guide

> Optimize rule evaluation for maximum speed

## Quick Wins

<CardGroup cols={2}>
  <Card title="Enable Caching" icon="bolt">
    Cache expressions and paths (enabled by default)
  </Card>

  <Card title="Reuse Engine" icon="recycle">
    Create once, use many times
  </Card>

  <Card title="Order Rules" icon="sort">
    Put fastest checks first
  </Card>

  <Card title="Batch Evaluate" icon="layer-group">
    Evaluate multiple rules at once
  </Card>
</CardGroup>

***

## Caching

### Expression Cache

Caches evaluated expressions for repeated use.

```javascript theme={null}
const engine = createRuleEngine({
  enableCache: true,      // Default: true
  maxCacheSize: 1000      // Default: 500
});

// First call - cache miss
engine.evaluateExpr(rule, data); // ~2ms

// Second call - cache hit
engine.evaluateExpr(rule, data); // ~0.1ms (20x faster!)
```

**Benefits:**

* ✅ 10-20x faster for repeated rules
* ✅ Automatic LRU eviction
* ✅ Memory efficient

**When to disable:**

* Highly dynamic rules
* Memory constraints
* Rules evaluated once

### Path Cache

Caches path resolutions.

```javascript theme={null}
// Cached automatically
engine.resolvePath(data, 'user.profile.name'); // Cache miss
engine.resolvePath(data, 'user.profile.name'); // Cache hit

// Clear when data structure changes
engine.clearCache();
```

***

## Rule Ordering

Put fastest checks first to fail fast.

### Performance Hierarchy

1. **Fastest**: Simple comparisons (`eq`, `neq`, `gt`, `lt`)
2. **Fast**: Array checks (`in`, `notIn`)
3. **Medium**: String operations (`contains`, `startsWith`)
4. **Slow**: Regex patterns (`regex`)
5. **Slowest**: State changes (`changed`, `increased`)

### Bad vs Good

<Tabs>
  <Tab title="❌ Bad - Slow First">
    ```javascript theme={null}
    // Regex first (slow!)
    const rule = {
      and: [
        { regex: ['email', '^[a-z]+@example\\.com$'] },  // 1ms
        { eq: ['status', 'active'] },                     // 0.01ms
        { gte: ['age', 18] }                              // 0.01ms
      ]
    };
    // Total: ~1ms even if status check would fail
    ```
  </Tab>

  <Tab title="✅ Good - Fast First">
    ```javascript theme={null}
    // Fast checks first
    const rule = {
      and: [
        { eq: ['status', 'active'] },                     // 0.01ms - fails fast
        { gte: ['age', 18] },                             // 0.01ms
        { regex: ['email', '^[a-z]+@example\\.com$'] }  // Only if above pass
      ]
    };
    // Total: ~0.01ms when status check fails (100x faster!)
    ```
  </Tab>
</Tabs>

***

## Reuse Engine

Create once, reuse everywhere.

<Tabs>
  <Tab title="❌ Bad">
    ```javascript theme={null}
    // DON'T create new engine each time
    function checkUser(user) {
      const engine = createRuleEngine(); // Expensive!
      return engine.evaluateExpr(rule, user);
    }
    ```
  </Tab>

  <Tab title="✅ Good">
    ```javascript theme={null}
    // Create once
    const engine = createRuleEngine();

    // Reuse many times
    function checkUser(user) {
      return engine.evaluateExpr(rule, user);
    }
    ```
  </Tab>
</Tabs>

***

## Batch Operations

Use `StatefulRuleEngine.evaluateBatch()` for multiple rules.

```javascript theme={null}
// Inefficient
rules.forEach(rule => {
  statefulEngine.evaluate(rule.id, rule.expr, data);
});

// Efficient - single pass
const results = statefulEngine.evaluateBatch({
  'rule1': rule1Expr,
  'rule2': rule2Expr,
  'rule3': rule3Expr
}, data);
```

**Benefits:**

* Single context preparation
* Shared path resolutions
* Better cache utilization

***

## Minimize Depth

Flatten nested rules when possible.

<Tabs>
  <Tab title="Nested (Slower)">
    ```javascript theme={null}
    {
      and: [
        { and: [
          { and: [
            { eq: ['a', 1] },
            { eq: ['b', 2] }
          ] },
          { eq: ['c', 3] }
        ] }
      ]
    }
    ```
  </Tab>

  <Tab title="Flat (Faster)">
    ```javascript theme={null}
    {
      and: [
        { eq: ['a', 1] },
        { eq: ['b', 2] },
        { eq: ['c', 3] }
      ]
    }
    ```
  </Tab>
</Tabs>

***

## Monitoring

### Get Metrics

```javascript theme={null}
const metrics = engine.getMetrics();

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

### Cache Stats

```javascript theme={null}
const stats = engine.getCacheStats();

console.log({
  expressionCache: `${stats.expression.size}/${stats.expression.maxSize}`,
  pathCache: `${stats.path.size}/${stats.path.maxSize}`
});
```

***

## Benchmarking

```javascript theme={null}
const rule = { /* your rule */ };
const data = { /* your data */ };

console.time('evaluation');
for (let i = 0; i < 10000; i++) {
  engine.evaluateExpr(rule, data);
}
console.timeEnd('evaluation');

const metrics = engine.getMetrics();
console.log('Avg:', metrics.avgTime.toFixed(3) + 'ms');
console.log('Cache hit rate:', (metrics.cacheHits / metrics.evaluations * 100).toFixed(1) + '%');
```

***

## Real-World Optimization

<Tabs>
  <Tab title="Before">
    ```javascript theme={null}
    // Slow: 5ms per evaluation
    const slowRule = {
      and: [
        { regex: ['description', '\\bimportant\\b.*\\burgent\\b'] },
        { contains: ['tags', 'priority'] },
        { eq: ['status', 'active'] },
        { gte: ['priority', 5] }
      ]
    };
    ```
  </Tab>

  <Tab title="After">
    ```javascript theme={null}
    // Fast: 0.1ms per evaluation (50x faster)
    const fastRule = {
      and: [
        { eq: ['status', 'active'] },         // Fastest first
        { gte: ['priority', 5] },
        { contains: ['tags', 'priority'] },
        { regex: ['description', '\\bimportant\\b.*\\burgent\\b'] }
      ]
    };
    ```
  </Tab>
</Tabs>

***

## Best Practices

<AccordionGroup>
  <Accordion title="1. Enable Caching (Default)">
    ```javascript theme={null}
    const engine = createRuleEngine({
      enableCache: true,
      maxCacheSize: 1000
    });
    ```
  </Accordion>

  <Accordion title="2. Reuse Engine Instance">
    ```javascript theme={null}
    // Singleton pattern
    export const engine = createRuleEngine();
    ```
  </Accordion>

  <Accordion title="3. Order Conditions">
    ```javascript theme={null}
    // Fast → Slow
    rules.and(
      rules.eq('status', 'active'),    // Fast
      rules.gte('age', 18),            // Fast
      rules.regex('email', pattern)    // Slow
    );
    ```
  </Accordion>

  <Accordion title="4. Use Batch Operations">
    ```javascript theme={null}
    statefulEngine.evaluateBatch(allRules, data);
    ```
  </Accordion>

  <Accordion title="5. Monitor Metrics">
    ```javascript theme={null}
    setInterval(() => {
      const metrics = engine.getMetrics();
      console.log('Performance:', metrics);
    }, 60000);
    ```
  </Accordion>
</AccordionGroup>

***

## Performance Checklist

* [ ] Cache enabled
* [ ] Reusing engine instance
* [ ] Fast checks first in `and` rules
* [ ] Slow checks last
* [ ] Using batch operations
* [ ] Monitoring metrics
* [ ] Rules flattened (not deeply nested)
* [ ] Clear cache when data schema changes

***

## Related

<CardGroup cols={2}>
  <Card title="RuleEngine API" icon="gear" href="/api-reference/rule-engine">
    Metrics and caching methods
  </Card>

  <Card title="Operators" icon="list" href="/operators/overview">
    Operator performance characteristics
  </Card>
</CardGroup>