@f-o-t/rules-engine 2.0.2 → 3.0.0

package/src/engine/engine.ts

@@ -0,0 +1,462 @@
+import { type Cache, createCache } from "../cache/cache";
+import { createNoopCache } from "../cache/noop";
+import { evaluateRule } from "../core/evaluate";
+import { createEvaluator } from "@f-o-t/condition-evaluator";
+import {
+   type EngineConfig,
+   getDefaultCacheConfig,
+   getDefaultConflictResolution,
+   getDefaultLogLevel,
+   getDefaultValidationConfig,
+   getDefaultVersioningConfig,
+   type ResolvedEngineConfig,
+} from "../types/config";
+import type {
+   AggregatedConsequence,
+   ConsequenceDefinitions,
+   DefaultConsequences,
+} from "../types/consequence";
+import type {
+   EngineExecutionResult,
+   EvaluateOptions,
+   EvaluationContext,
+} from "../types/evaluation";
+import type {
+   Rule,
+   RuleFilters,
+   RuleInput,
+   RuleSet,
+   RuleSetInput,
+} from "../types/rule";
+import type {
+   CacheStats,
+   EngineState,
+   EngineStats,
+   MutableEngineState,
+} from "../types/state";
+import { createInitialState } from "../types/state";
+import { hashContext, hashRules } from "../utils/hash";
+import { generateId } from "../utils/id";
+import { measureTime } from "../utils/time";
+import {
+   executeAfterEvaluation,
+   executeAfterRuleEvaluation,
+   executeBeforeEvaluation,
+   executeBeforeRuleEvaluation,
+   executeOnCacheHit,
+   executeOnCacheMiss,
+   executeOnConsequenceCollected,
+   executeOnRuleError,
+   executeOnRuleMatch,
+   executeOnRuleSkip,
+   executeOnSlowRule,
+} from "./hooks";
+import {
+   addRule,
+   addRuleSet,
+   addRules,
+   clearRules,
+   disableRule,
+   enableRule,
+   getRule,
+   getRuleSet,
+   getRuleSets,
+   getRules,
+   getRulesInSet,
+   removeRule,
+   removeRuleSet,
+   updateRule,
+} from "./state";
+
+export type Engine<
+   TContext = unknown,
+   TConsequences extends ConsequenceDefinitions = DefaultConsequences,
+> = {
+   readonly addRule: (
+      input: RuleInput<TContext, TConsequences>,
+   ) => Rule<TContext, TConsequences>;
+   readonly addRules: (
+      inputs: RuleInput<TContext, TConsequences>[],
+   ) => Rule<TContext, TConsequences>[];
+   readonly removeRule: (ruleId: string) => boolean;
+   readonly updateRule: (
+      ruleId: string,
+      updates: Partial<RuleInput<TContext, TConsequences>>,
+   ) => Rule<TContext, TConsequences> | undefined;
+   readonly getRule: (
+      ruleId: string,
+   ) => Rule<TContext, TConsequences> | undefined;
+   readonly getRules: (
+      filters?: RuleFilters,
+   ) => ReadonlyArray<Rule<TContext, TConsequences>>;
+   readonly enableRule: (ruleId: string) => boolean;
+   readonly disableRule: (ruleId: string) => boolean;
+   readonly clearRules: () => void;
+
+   readonly addRuleSet: (input: RuleSetInput) => RuleSet;
+   readonly getRuleSet: (ruleSetId: string) => RuleSet | undefined;
+   readonly getRuleSets: () => ReadonlyArray<RuleSet>;
+   readonly removeRuleSet: (ruleSetId: string) => boolean;
+
+   readonly evaluate: (
+      context: TContext,
+      options?: EvaluateOptions,
+   ) => Promise<EngineExecutionResult<TContext, TConsequences>>;
+
+   readonly clearCache: () => void;
+   readonly getCacheStats: () => CacheStats;
+
+   readonly getState: () => Readonly<EngineState<TContext, TConsequences>>;
+   readonly getStats: () => EngineStats;
+};
+
+const resolveConfig = <
+   TContext = unknown,
+   TConsequences extends ConsequenceDefinitions = DefaultConsequences,
+>(
+   config: EngineConfig<TContext, TConsequences>,
+): ResolvedEngineConfig<TContext, TConsequences> => {
+   // Validate evaluator config
+   if (!config.evaluator && !config.operators) {
+      throw new Error(
+         "Engine requires either 'evaluator' or 'operators' config. " +
+         "Pass { evaluator: createEvaluator() } for built-in operators only, " +
+         "or { operators: customOperators } to use custom operators."
+      );
+   }
+
+   // Create evaluator from config
+   const evaluator = config.evaluator
+      ? config.evaluator
+      : createEvaluator({ operators: config.operators });
+
+   return {
+      consequences: config.consequences,
+      conflictResolution:
+         config.conflictResolution ?? getDefaultConflictResolution(),
+      cache: {
+         ...getDefaultCacheConfig(),
+         ...config.cache,
+      },
+      validation: {
+         ...getDefaultValidationConfig(),
+         ...config.validation,
+      },
+      versioning: {
+         ...getDefaultVersioningConfig(),
+         ...config.versioning,
+      },
+      hooks: config.hooks ?? {},
+      logLevel: config.logLevel ?? getDefaultLogLevel(),
+      logger: config.logger ?? console,
+      continueOnError: config.continueOnError ?? true,
+      slowRuleThresholdMs: config.slowRuleThresholdMs ?? 10,
+      hookTimeoutMs: config.hookTimeoutMs,
+      evaluator, // Add to resolved config
+   };
+};
+
+export const createEngine = <
+   TContext = unknown,
+   TConsequences extends ConsequenceDefinitions = DefaultConsequences,
+>(
+   config: EngineConfig<TContext, TConsequences> = {},
+): Engine<TContext, TConsequences> => {
+   const resolvedConfig = resolveConfig(config);
+   const state: MutableEngineState<TContext, TConsequences> =
+      createInitialState();
+
+   const cache: Cache<EngineExecutionResult<TContext, TConsequences>> =
+      resolvedConfig.cache.enabled
+         ? createCache({
+              ttl: resolvedConfig.cache.ttl,
+              maxSize: resolvedConfig.cache.maxSize,
+           })
+         : createNoopCache();
+
+   let totalEvaluations = 0;
+   let totalMatches = 0;
+   let totalErrors = 0;
+   let cacheHits = 0;
+   let cacheMisses = 0;
+   let totalEvaluationTime = 0;
+
+   const evaluate = async (
+      contextData: TContext,
+      options: EvaluateOptions = {},
+   ): Promise<EngineExecutionResult<TContext, TConsequences>> => {
+      const context: EvaluationContext<TContext> = {
+         data: contextData,
+         timestamp: new Date(),
+         correlationId: generateId(),
+      };
+
+      let rulesToEvaluate = getRules(state, {
+         enabled: options.skipDisabled !== false ? true : undefined,
+         tags: options.tags,
+         category: options.category,
+      });
+
+      if (options.ruleSetId) {
+         const ruleSetRules = getRulesInSet(state, options.ruleSetId);
+         const ruleSetIds = new Set(ruleSetRules.map((r) => r.id));
+         rulesToEvaluate = rulesToEvaluate.filter((r) => ruleSetIds.has(r.id));
+      }
+
+      // Rules are already sorted by priority via state.ruleOrder (sorted on add/update)
+
+      if (options.maxRules && options.maxRules > 0) {
+         rulesToEvaluate = rulesToEvaluate.slice(0, options.maxRules);
+      }
+
+      const cacheKey = !options.bypassCache
+         ? `${hashContext(contextData)}:${hashRules(rulesToEvaluate.map((r) => r.id))}`
+         : null;
+
+      if (cacheKey && cache.has(cacheKey)) {
+         const cached = cache.get(cacheKey);
+         if (cached) {
+            cacheHits++;
+            await executeOnCacheHit(
+               resolvedConfig.hooks,
+               cacheKey,
+               cached,
+               resolvedConfig.hookTimeoutMs,
+            );
+            return { ...cached, cacheHit: true };
+         }
+      }
+
+      if (cacheKey) {
+         cacheMisses++;
+         await executeOnCacheMiss(
+            resolvedConfig.hooks,
+            cacheKey,
+            resolvedConfig.hookTimeoutMs,
+         );
+      }
+
+      await executeBeforeEvaluation(
+         resolvedConfig.hooks,
+         context,
+         rulesToEvaluate,
+         resolvedConfig.hookTimeoutMs,
+      );
+
+      const { result: evaluationResult, durationMs } = measureTime(() => {
+         const results: Array<{
+            rule: Rule<TContext, TConsequences>;
+            result: ReturnType<typeof evaluateRule<TContext, TConsequences>>;
+         }> = [];
+
+         for (const rule of rulesToEvaluate) {
+            const result = evaluateRule(rule, context, resolvedConfig.evaluator, { skipDisabled: true });
+            results.push({ rule, result });
+         }
+
+         return results;
+      });
+
+      const ruleResults: ReturnType<
+         typeof evaluateRule<TContext, TConsequences>
+      >[] = [];
+      const matchedRules: Rule<TContext, TConsequences>[] = [];
+      const consequences: AggregatedConsequence<TConsequences>[] = [];
+      let stoppedEarly = false;
+      let stoppedByRuleId: string | undefined;
+      let rulesErrored = 0;
+
+      const conflictResolution =
+         options.conflictResolution ?? resolvedConfig.conflictResolution;
+
+      for (const { rule, result } of evaluationResult) {
+         await executeBeforeRuleEvaluation(
+            resolvedConfig.hooks,
+            rule,
+            context,
+            resolvedConfig.hookTimeoutMs,
+         );
+
+         ruleResults.push(result);
+
+         if (result.error) {
+            rulesErrored++;
+            await executeOnRuleError(
+               resolvedConfig.hooks,
+               rule,
+               result.error,
+               resolvedConfig.hookTimeoutMs,
+            );
+            if (!resolvedConfig.continueOnError) {
+               break;
+            }
+         }
+
+         if (result.skipped) {
+            await executeOnRuleSkip(
+               resolvedConfig.hooks,
+               rule,
+               result.skipReason ?? "Unknown",
+               resolvedConfig.hookTimeoutMs,
+            );
+         }
+
+         if (result.evaluationTimeMs > resolvedConfig.slowRuleThresholdMs) {
+            await executeOnSlowRule(
+               resolvedConfig.hooks,
+               rule,
+               result.evaluationTimeMs,
+               resolvedConfig.slowRuleThresholdMs,
+               resolvedConfig.hookTimeoutMs,
+            );
+         }
+
+         await executeAfterRuleEvaluation(
+            resolvedConfig.hooks,
+            rule,
+            result,
+            resolvedConfig.hookTimeoutMs,
+         );
+
+         if (result.matched) {
+            matchedRules.push(rule);
+
+            for (const consequence of result.consequences) {
+               consequences.push(consequence);
+               await executeOnConsequenceCollected(
+                  resolvedConfig.hooks,
+                  rule,
+                  consequence,
+                  resolvedConfig.hookTimeoutMs,
+               );
+            }
+
+            await executeOnRuleMatch(
+               resolvedConfig.hooks,
+               rule,
+               context,
+               resolvedConfig.hookTimeoutMs,
+            );
+
+            if (rule.stopOnMatch) {
+               stoppedEarly = true;
+               stoppedByRuleId = rule.id;
+               break;
+            }
+
+            if (conflictResolution === "first-match") {
+               stoppedEarly = true;
+               stoppedByRuleId = rule.id;
+               break;
+            }
+         }
+      }
+
+      totalEvaluations++;
+      totalMatches += matchedRules.length;
+      totalErrors += rulesErrored;
+      totalEvaluationTime += durationMs;
+
+      const executionResult: EngineExecutionResult<TContext, TConsequences> = {
+         context,
+         results: ruleResults,
+         matchedRules,
+         consequences,
+         totalRulesEvaluated: ruleResults.length,
+         totalRulesMatched: matchedRules.length,
+         totalRulesSkipped: ruleResults.filter((r) => r.skipped).length,
+         totalRulesErrored: rulesErrored,
+         executionTimeMs: durationMs,
+         stoppedEarly,
+         stoppedByRuleId,
+         cacheHit: false,
+      };
+
+      if (cacheKey) {
+         cache.set(cacheKey, executionResult);
+      }
+
+      await executeAfterEvaluation(
+         resolvedConfig.hooks,
+         executionResult,
+         resolvedConfig.hookTimeoutMs,
+      );
+
+      return executionResult;
+   };
+
+   return {
+      addRule: (input) => addRule(state, input),
+      addRules: (inputs) => addRules(state, inputs),
+      removeRule: (ruleId) => {
+         const result = removeRule(state, ruleId);
+         if (result) cache.clear();
+         return result;
+      },
+      updateRule: (ruleId, updates) => {
+         const result = updateRule(state, ruleId, updates);
+         if (result) cache.clear();
+         return result;
+      },
+      getRule: (ruleId) => getRule(state, ruleId),
+      getRules: (filters) => getRules(state, filters),
+      enableRule: (ruleId) => {
+         const result = enableRule(state, ruleId);
+         if (result) cache.clear();
+         return result;
+      },
+      disableRule: (ruleId) => {
+         const result = disableRule(state, ruleId);
+         if (result) cache.clear();
+         return result;
+      },
+      clearRules: () => {
+         clearRules(state);
+         cache.clear();
+      },
+
+      addRuleSet: (input) => addRuleSet(state, input),
+      getRuleSet: (ruleSetId) => getRuleSet(state, ruleSetId),
+      getRuleSets: () => getRuleSets(state),
+      removeRuleSet: (ruleSetId) => removeRuleSet(state, ruleSetId),
+
+      evaluate,
+
+      clearCache: () => cache.clear(),
+      getCacheStats: () => cache.getStats(),
+
+      getState: () => ({
+         rules: state.rules as ReadonlyMap<
+            string,
+            Rule<TContext, TConsequences>
+         >,
+         ruleSets: state.ruleSets as ReadonlyMap<string, RuleSet>,
+         ruleOrder: state.ruleOrder,
+      }),
+
+      getStats: () => {
+         const enabledRules = Array.from(state.rules.values()).filter(
+            (r) => r.enabled,
+         ).length;
+         return {
+            totalRules: state.rules.size,
+            enabledRules,
+            disabledRules: state.rules.size - enabledRules,
+            totalRuleSets: state.ruleSets.size,
+            totalEvaluations,
+            totalMatches,
+            totalErrors,
+            avgEvaluationTimeMs:
+               totalEvaluations > 0
+                  ? totalEvaluationTime / totalEvaluations
+                  : 0,
+            cacheHits,
+            cacheMisses,
+            cacheHitRate:
+               cacheHits + cacheMisses > 0
+                  ? cacheHits / (cacheHits + cacheMisses)
+                  : 0,
+         };
+      },
+   };
+};

package/src/engine/hooks.ts

@@ -0,0 +1,235 @@
+import type { EngineHooks } from "../types/config";
+import type {
+   AggregatedConsequence,
+   ConsequenceDefinitions,
+   DefaultConsequences,
+} from "../types/consequence";
+import type {
+   EngineExecutionResult,
+   EvaluationContext,
+   RuleEvaluationResult,
+} from "../types/evaluation";
+import type { Rule } from "../types/rule";
+import { withTimeout } from "../utils/time";
+
+const toError = (error: unknown): Error =>
+   error instanceof Error ? error : new Error(String(error));
+
+const executeWithTimeout = async (
+   hookName: string,
+   hookFn: () => void | Promise<void>,
+   hooks: EngineHooks<unknown, ConsequenceDefinitions>,
+   timeoutMs?: number,
+): Promise<void> => {
+   try {
+      const promise = Promise.resolve(hookFn());
+      if (timeoutMs !== undefined && timeoutMs > 0) {
+         await withTimeout(
+            promise,
+            timeoutMs,
+            `Hook '${hookName}' timed out after ${timeoutMs}ms`,
+         );
+      } else {
+         await promise;
+      }
+   } catch (error) {
+      hooks.onHookError?.(hookName, toError(error));
+   }
+};
+
+export const executeBeforeEvaluation = async <
+   TContext = unknown,
+   TConsequences extends ConsequenceDefinitions = DefaultConsequences,
+>(
+   hooks: EngineHooks<TContext, TConsequences>,
+   context: EvaluationContext<TContext>,
+   rules: ReadonlyArray<Rule<TContext, TConsequences>>,
+   timeoutMs?: number,
+): Promise<void> => {
+   if (!hooks.beforeEvaluation) return;
+   await executeWithTimeout(
+      "beforeEvaluation",
+      () => hooks.beforeEvaluation?.(context, rules),
+      hooks as EngineHooks<unknown, ConsequenceDefinitions>,
+      timeoutMs,
+   );
+};
+
+export const executeAfterEvaluation = async <
+   TContext = unknown,
+   TConsequences extends ConsequenceDefinitions = DefaultConsequences,
+>(
+   hooks: EngineHooks<TContext, TConsequences>,
+   result: EngineExecutionResult<TContext, TConsequences>,
+   timeoutMs?: number,
+): Promise<void> => {
+   if (!hooks.afterEvaluation) return;
+   await executeWithTimeout(
+      "afterEvaluation",
+      () => hooks.afterEvaluation?.(result),
+      hooks as EngineHooks<unknown, ConsequenceDefinitions>,
+      timeoutMs,
+   );
+};
+
+export const executeBeforeRuleEvaluation = async <
+   TContext = unknown,
+   TConsequences extends ConsequenceDefinitions = DefaultConsequences,
+>(
+   hooks: EngineHooks<TContext, TConsequences>,
+   rule: Rule<TContext, TConsequences>,
+   context: EvaluationContext<TContext>,
+   timeoutMs?: number,
+): Promise<void> => {
+   if (!hooks.beforeRuleEvaluation) return;
+   await executeWithTimeout(
+      "beforeRuleEvaluation",
+      () => hooks.beforeRuleEvaluation?.(rule, context),
+      hooks as EngineHooks<unknown, ConsequenceDefinitions>,
+      timeoutMs,
+   );
+};
+
+export const executeAfterRuleEvaluation = async <
+   TContext = unknown,
+   TConsequences extends ConsequenceDefinitions = DefaultConsequences,
+>(
+   hooks: EngineHooks<TContext, TConsequences>,
+   rule: Rule<TContext, TConsequences>,
+   result: RuleEvaluationResult<TContext, TConsequences>,
+   timeoutMs?: number,
+): Promise<void> => {
+   if (!hooks.afterRuleEvaluation) return;
+   await executeWithTimeout(
+      "afterRuleEvaluation",
+      () => hooks.afterRuleEvaluation?.(rule, result),
+      hooks as EngineHooks<unknown, ConsequenceDefinitions>,
+      timeoutMs,
+   );
+};
+
+export const executeOnRuleMatch = async <
+   TContext = unknown,
+   TConsequences extends ConsequenceDefinitions = DefaultConsequences,
+>(
+   hooks: EngineHooks<TContext, TConsequences>,
+   rule: Rule<TContext, TConsequences>,
+   context: EvaluationContext<TContext>,
+   timeoutMs?: number,
+): Promise<void> => {
+   if (!hooks.onRuleMatch) return;
+   await executeWithTimeout(
+      "onRuleMatch",
+      () => hooks.onRuleMatch?.(rule, context),
+      hooks as EngineHooks<unknown, ConsequenceDefinitions>,
+      timeoutMs,
+   );
+};
+
+export const executeOnRuleSkip = async <
+   TContext = unknown,
+   TConsequences extends ConsequenceDefinitions = DefaultConsequences,
+>(
+   hooks: EngineHooks<TContext, TConsequences>,
+   rule: Rule<TContext, TConsequences>,
+   reason: string,
+   timeoutMs?: number,
+): Promise<void> => {
+   if (!hooks.onRuleSkip) return;
+   await executeWithTimeout(
+      "onRuleSkip",
+      () => hooks.onRuleSkip?.(rule, reason),
+      hooks as EngineHooks<unknown, ConsequenceDefinitions>,
+      timeoutMs,
+   );
+};
+
+export const executeOnRuleError = async <
+   TContext = unknown,
+   TConsequences extends ConsequenceDefinitions = DefaultConsequences,
+>(
+   hooks: EngineHooks<TContext, TConsequences>,
+   rule: Rule<TContext, TConsequences>,
+   ruleError: Error,
+   timeoutMs?: number,
+): Promise<void> => {
+   if (!hooks.onRuleError) return;
+   await executeWithTimeout(
+      "onRuleError",
+      () => hooks.onRuleError?.(rule, ruleError),
+      hooks as EngineHooks<unknown, ConsequenceDefinitions>,
+      timeoutMs,
+   );
+};
+
+export const executeOnConsequenceCollected = async <
+   TContext = unknown,
+   TConsequences extends ConsequenceDefinitions = DefaultConsequences,
+>(
+   hooks: EngineHooks<TContext, TConsequences>,
+   rule: Rule<TContext, TConsequences>,
+   consequence: AggregatedConsequence<TConsequences>,
+   timeoutMs?: number,
+): Promise<void> => {
+   if (!hooks.onConsequenceCollected) return;
+   await executeWithTimeout(
+      "onConsequenceCollected",
+      () => hooks.onConsequenceCollected?.(rule, consequence),
+      hooks as EngineHooks<unknown, ConsequenceDefinitions>,
+      timeoutMs,
+   );
+};
+
+export const executeOnCacheHit = async <
+   TContext = unknown,
+   TConsequences extends ConsequenceDefinitions = DefaultConsequences,
+>(
+   hooks: EngineHooks<TContext, TConsequences>,
+   key: string,
+   result: EngineExecutionResult<TContext, TConsequences>,
+   timeoutMs?: number,
+): Promise<void> => {
+   if (!hooks.onCacheHit) return;
+   await executeWithTimeout(
+      "onCacheHit",
+      () => hooks.onCacheHit?.(key, result),
+      hooks as EngineHooks<unknown, ConsequenceDefinitions>,
+      timeoutMs,
+   );
+};
+
+export const executeOnCacheMiss = async <
+   TContext = unknown,
+   TConsequences extends ConsequenceDefinitions = DefaultConsequences,
+>(
+   hooks: EngineHooks<TContext, TConsequences>,
+   key: string,
+   timeoutMs?: number,
+): Promise<void> => {
+   if (!hooks.onCacheMiss) return;
+   await executeWithTimeout(
+      "onCacheMiss",
+      () => hooks.onCacheMiss?.(key),
+      hooks as EngineHooks<unknown, ConsequenceDefinitions>,
+      timeoutMs,
+   );
+};
+
+export const executeOnSlowRule = async <
+   TContext = unknown,
+   TConsequences extends ConsequenceDefinitions = DefaultConsequences,
+>(
+   hooks: EngineHooks<TContext, TConsequences>,
+   rule: Rule<TContext, TConsequences>,
+   timeMs: number,
+   threshold: number,
+   timeoutMs?: number,
+): Promise<void> => {
+   if (!hooks.onSlowRule) return;
+   await executeWithTimeout(
+      "onSlowRule",
+      () => hooks.onSlowRule?.(rule, timeMs, threshold),
+      hooks as EngineHooks<unknown, ConsequenceDefinitions>,
+      timeoutMs,
+   );
+};