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

package/src/simulation/simulator.ts

@@ -0,0 +1,359 @@
+import { createEvaluator } from "@f-o-t/condition-evaluator";
+import { evaluateRule, evaluateRules } from "../core/evaluate";
+import type {
+   ConsequenceDefinitions,
+   DefaultConsequences,
+} from "../types/consequence";
+import type {
+   EvaluationContext,
+   RuleEvaluationResult,
+} from "../types/evaluation";
+import type { Rule } from "../types/rule";
+
+export type SimulationContext<TContext = unknown> = {
+   readonly data: TContext;
+   readonly metadata?: Record<string, unknown>;
+};
+
+export type SimulationResult<
+   TContext = unknown,
+   TConsequences extends ConsequenceDefinitions = DefaultConsequences,
+> = {
+   readonly context: SimulationContext<TContext>;
+   readonly matchedRules: ReadonlyArray<
+      RuleEvaluationResult<TContext, TConsequences>
+   >;
+   readonly unmatchedRules: ReadonlyArray<{
+      ruleId: string;
+      ruleName: string;
+      reason: string;
+   }>;
+   readonly consequences: ReadonlyArray<{
+      type: keyof TConsequences;
+      payload: unknown;
+      ruleId: string;
+      ruleName: string;
+   }>;
+   readonly executionTimeMs: number;
+};
+
+export type WhatIfResult<
+   TContext = unknown,
+   TConsequences extends ConsequenceDefinitions = DefaultConsequences,
+> = {
+   readonly original: SimulationResult<TContext, TConsequences>;
+   readonly modified: SimulationResult<TContext, TConsequences>;
+   readonly differences: {
+      readonly newMatches: ReadonlyArray<string>;
+      readonly lostMatches: ReadonlyArray<string>;
+      readonly consequenceChanges: ReadonlyArray<{
+         type: "added" | "removed" | "modified";
+         consequenceType: string;
+         ruleId: string;
+      }>;
+   };
+};
+
+export type BatchSimulationResult<
+   TContext = unknown,
+   TConsequences extends ConsequenceDefinitions = DefaultConsequences,
+> = {
+   readonly results: ReadonlyArray<SimulationResult<TContext, TConsequences>>;
+   readonly summary: {
+      readonly totalContexts: number;
+      readonly averageMatchedRules: number;
+      readonly ruleMatchFrequency: ReadonlyMap<string, number>;
+      readonly consequenceFrequency: ReadonlyMap<string, number>;
+      readonly averageExecutionTimeMs: number;
+   };
+};
+
+const toEvaluationContext = <TContext>(
+   simContext: SimulationContext<TContext>,
+): EvaluationContext<TContext> => ({
+   data: simContext.data,
+   timestamp: new Date(),
+   metadata: simContext.metadata,
+});
+
+export const simulate = <
+   TContext = unknown,
+   TConsequences extends ConsequenceDefinitions = DefaultConsequences,
+>(
+   rules: ReadonlyArray<Rule<TContext, TConsequences>>,
+   context: SimulationContext<TContext>,
+   evaluator: ReturnType<typeof createEvaluator> = createEvaluator(),
+): SimulationResult<TContext, TConsequences> => {
+   const startTime = performance.now();
+
+   const enabledRules = rules.filter((r) => r.enabled);
+   const evalContext = toEvaluationContext(context);
+   const results = evaluateRules(enabledRules, evalContext, evaluator);
+
+   const matchedRules = results.results.filter((r) => r.matched);
+   const unmatchedRules: Array<{
+      ruleId: string;
+      ruleName: string;
+      reason: string;
+   }> = [];
+
+   for (const result of results.results) {
+      if (!result.matched) {
+         const reason = result.skipped
+            ? (result.skipReason ?? "Skipped")
+            : result.error
+              ? `Error: ${result.error.message}`
+              : "Conditions not met";
+         unmatchedRules.push({
+            ruleId: result.ruleId,
+            ruleName: result.ruleName,
+            reason,
+         });
+      }
+   }
+
+   const consequences: Array<{
+      type: keyof TConsequences;
+      payload: unknown;
+      ruleId: string;
+      ruleName: string;
+   }> = [];
+
+   for (const match of matchedRules) {
+      for (const consequence of match.consequences) {
+         consequences.push({
+            type: consequence.type,
+            payload: consequence.payload,
+            ruleId: consequence.ruleId,
+            ruleName: consequence.ruleName ?? match.ruleName,
+         });
+      }
+   }
+
+   const executionTimeMs = performance.now() - startTime;
+
+   return {
+      context,
+      matchedRules,
+      unmatchedRules,
+      consequences,
+      executionTimeMs,
+   };
+};
+
+export const simulateSingleRule = <
+   TContext = unknown,
+   TConsequences extends ConsequenceDefinitions = DefaultConsequences,
+>(
+   rule: Rule<TContext, TConsequences>,
+   context: SimulationContext<TContext>,
+   evaluator: ReturnType<typeof createEvaluator> = createEvaluator(),
+): {
+   matched: boolean;
+   conditionResult: unknown;
+   consequences: ReadonlyArray<{ type: keyof TConsequences; payload: unknown }>;
+} => {
+   const evalContext = toEvaluationContext(context);
+   const result = evaluateRule(rule, evalContext, evaluator);
+
+   return {
+      matched: result.matched,
+      conditionResult: result.conditionResult,
+      consequences: result.matched
+         ? rule.consequences.map((c) => ({ type: c.type, payload: c.payload }))
+         : [],
+   };
+};
+
+export const whatIf = <
+   TContext = unknown,
+   TConsequences extends ConsequenceDefinitions = DefaultConsequences,
+>(
+   originalRules: ReadonlyArray<Rule<TContext, TConsequences>>,
+   modifiedRules: ReadonlyArray<Rule<TContext, TConsequences>>,
+   context: SimulationContext<TContext>,
+   evaluator: ReturnType<typeof createEvaluator> = createEvaluator(),
+): WhatIfResult<TContext, TConsequences> => {
+   const original = simulate(originalRules, context, evaluator);
+   const modified = simulate(modifiedRules, context, evaluator);
+
+   const originalMatchIds = new Set(original.matchedRules.map((r) => r.ruleId));
+   const modifiedMatchIds = new Set(modified.matchedRules.map((r) => r.ruleId));
+
+   const newMatches = [...modifiedMatchIds].filter(
+      (id) => !originalMatchIds.has(id),
+   );
+   const lostMatches = [...originalMatchIds].filter(
+      (id) => !modifiedMatchIds.has(id),
+   );
+
+   const consequenceChanges: Array<{
+      type: "added" | "removed" | "modified";
+      consequenceType: string;
+      ruleId: string;
+   }> = [];
+
+   const originalConsequenceKeys = new Set(
+      original.consequences.map((c) => `${c.ruleId}:${c.type as string}`),
+   );
+   const modifiedConsequenceKeys = new Set(
+      modified.consequences.map((c) => `${c.ruleId}:${c.type as string}`),
+   );
+
+   for (const key of modifiedConsequenceKeys) {
+      if (!originalConsequenceKeys.has(key)) {
+         const [ruleId, consequenceType] = key.split(":");
+         consequenceChanges.push({
+            type: "added",
+            consequenceType: consequenceType ?? "",
+            ruleId: ruleId ?? "",
+         });
+      }
+   }
+
+   for (const key of originalConsequenceKeys) {
+      if (!modifiedConsequenceKeys.has(key)) {
+         const [ruleId, consequenceType] = key.split(":");
+         consequenceChanges.push({
+            type: "removed",
+            consequenceType: consequenceType ?? "",
+            ruleId: ruleId ?? "",
+         });
+      }
+   }
+
+   return {
+      original,
+      modified,
+      differences: {
+         newMatches,
+         lostMatches,
+         consequenceChanges,
+      },
+   };
+};
+
+export const batchSimulate = <
+   TContext = unknown,
+   TConsequences extends ConsequenceDefinitions = DefaultConsequences,
+>(
+   rules: ReadonlyArray<Rule<TContext, TConsequences>>,
+   contexts: ReadonlyArray<SimulationContext<TContext>>,
+   evaluator: ReturnType<typeof createEvaluator> = createEvaluator(),
+): BatchSimulationResult<TContext, TConsequences> => {
+   const results = contexts.map((context) => simulate(rules, context, evaluator));
+
+   const ruleMatchFrequency = new Map<string, number>();
+   const consequenceFrequency = new Map<string, number>();
+   let totalMatchedRules = 0;
+   let totalExecutionTime = 0;
+
+   for (const result of results) {
+      totalMatchedRules += result.matchedRules.length;
+      totalExecutionTime += result.executionTimeMs;
+
+      for (const match of result.matchedRules) {
+         const count = ruleMatchFrequency.get(match.ruleId) ?? 0;
+         ruleMatchFrequency.set(match.ruleId, count + 1);
+      }
+
+      for (const consequence of result.consequences) {
+         const key = consequence.type as string;
+         const count = consequenceFrequency.get(key) ?? 0;
+         consequenceFrequency.set(key, count + 1);
+      }
+   }
+
+   return {
+      results,
+      summary: {
+         totalContexts: contexts.length,
+         averageMatchedRules:
+            contexts.length > 0 ? totalMatchedRules / contexts.length : 0,
+         ruleMatchFrequency,
+         consequenceFrequency,
+         averageExecutionTimeMs:
+            contexts.length > 0 ? totalExecutionTime / contexts.length : 0,
+      },
+   };
+};
+
+export const findRulesAffectedByContextChange = <
+   TContext = unknown,
+   TConsequences extends ConsequenceDefinitions = DefaultConsequences,
+>(
+   rules: ReadonlyArray<Rule<TContext, TConsequences>>,
+   originalContext: SimulationContext<TContext>,
+   modifiedContext: SimulationContext<TContext>,
+   evaluator: ReturnType<typeof createEvaluator> = createEvaluator(),
+): {
+   becameTrue: ReadonlyArray<Rule<TContext, TConsequences>>;
+   becameFalse: ReadonlyArray<Rule<TContext, TConsequences>>;
+   unchanged: ReadonlyArray<Rule<TContext, TConsequences>>;
+} => {
+   const originalResult = simulate(rules, originalContext, evaluator);
+   const modifiedResult = simulate(rules, modifiedContext, evaluator);
+
+   const originalMatchIds = new Set(
+      originalResult.matchedRules.map((r) => r.ruleId),
+   );
+   const modifiedMatchIds = new Set(
+      modifiedResult.matchedRules.map((r) => r.ruleId),
+   );
+
+   const becameTrue: Rule<TContext, TConsequences>[] = [];
+   const becameFalse: Rule<TContext, TConsequences>[] = [];
+   const unchanged: Rule<TContext, TConsequences>[] = [];
+
+   for (const rule of rules) {
+      const wasMatched = originalMatchIds.has(rule.id);
+      const isMatched = modifiedMatchIds.has(rule.id);
+
+      if (!wasMatched && isMatched) {
+         becameTrue.push(rule);
+      } else if (wasMatched && !isMatched) {
+         becameFalse.push(rule);
+      } else {
+         unchanged.push(rule);
+      }
+   }
+
+   return { becameTrue, becameFalse, unchanged };
+};
+
+export const formatSimulationResult = <
+   TContext = unknown,
+   TConsequences extends ConsequenceDefinitions = DefaultConsequences,
+>(
+   result: SimulationResult<TContext, TConsequences>,
+): string => {
+   const lines: string[] = [
+      "=== Simulation Result ===",
+      "",
+      `Execution Time: ${result.executionTimeMs.toFixed(2)}ms`,
+      "",
+      `Matched Rules (${result.matchedRules.length}):`,
+   ];
+
+   for (const match of result.matchedRules) {
+      lines.push(`  - ${match.ruleName} (${match.ruleId})`);
+   }
+
+   lines.push("");
+   lines.push(`Unmatched Rules (${result.unmatchedRules.length}):`);
+
+   for (const unmatched of result.unmatchedRules) {
+      lines.push(`  - ${unmatched.ruleName}: ${unmatched.reason}`);
+   }
+
+   lines.push("");
+   lines.push(`Consequences (${result.consequences.length}):`);
+
+   for (const consequence of result.consequences) {
+      lines.push(
+         `  - ${consequence.type as string} from "${consequence.ruleName}"`,
+      );
+   }
+
+   return lines.join("\n");
+};

package/src/types/config.ts

@@ -0,0 +1,184 @@
+import { z } from "zod";
+import type { OperatorMap } from "@f-o-t/condition-evaluator";
+import type {
+   AggregatedConsequence,
+   ConsequenceDefinitions,
+   DefaultConsequences,
+} from "./consequence";
+import type {
+   ConflictResolutionStrategy,
+   EngineExecutionResult,
+   EvaluationContext,
+   RuleEvaluationResult,
+} from "./evaluation";
+import type { Rule } from "./rule";
+
+// ============================================================================
+// Zod Schemas - Define schemas first, then infer types
+// ============================================================================
+
+export const LogLevelSchema = z.enum([
+   "none",
+   "error",
+   "warn",
+   "info",
+   "debug",
+]);
+export type LogLevel = z.infer<typeof LogLevelSchema>;
+
+export const CacheConfigSchema = z.object({
+   enabled: z.boolean().default(true),
+   ttl: z.number().int().positive().default(60000),
+   maxSize: z.number().int().positive().default(1000),
+});
+export type CacheConfig = z.infer<typeof CacheConfigSchema>;
+
+export const ValidationConfigSchema = z.object({
+   enabled: z.boolean().default(true),
+   strict: z.boolean().default(false),
+});
+export type ValidationConfig = z.infer<typeof ValidationConfigSchema>;
+
+export const VersioningConfigSchema = z.object({
+   enabled: z.boolean().default(false),
+   maxVersions: z.number().int().positive().default(10),
+});
+export type VersioningConfig = z.infer<typeof VersioningConfigSchema>;
+
+// ============================================================================
+// Types that cannot be Zod schemas (contain functions or generics)
+// ============================================================================
+
+export type Logger = {
+   readonly error: (...args: unknown[]) => void;
+   readonly warn: (...args: unknown[]) => void;
+   readonly info: (...args: unknown[]) => void;
+   readonly debug: (...args: unknown[]) => void;
+};
+
+export type EngineHooks<
+   TContext = unknown,
+   TConsequences extends ConsequenceDefinitions = DefaultConsequences,
+> = {
+   readonly beforeEvaluation?: (
+      context: EvaluationContext<TContext>,
+      rules: ReadonlyArray<Rule<TContext, TConsequences>>,
+   ) => void | Promise<void>;
+
+   readonly afterEvaluation?: (
+      result: EngineExecutionResult<TContext, TConsequences>,
+   ) => void | Promise<void>;
+
+   readonly beforeRuleEvaluation?: (
+      rule: Rule<TContext, TConsequences>,
+      context: EvaluationContext<TContext>,
+   ) => void | Promise<void>;
+
+   readonly afterRuleEvaluation?: (
+      rule: Rule<TContext, TConsequences>,
+      result: RuleEvaluationResult<TContext, TConsequences>,
+   ) => void | Promise<void>;
+
+   readonly onRuleMatch?: (
+      rule: Rule<TContext, TConsequences>,
+      context: EvaluationContext<TContext>,
+   ) => void | Promise<void>;
+
+   readonly onRuleSkip?: (
+      rule: Rule<TContext, TConsequences>,
+      reason: string,
+   ) => void | Promise<void>;
+
+   readonly onRuleError?: (
+      rule: Rule<TContext, TConsequences>,
+      error: Error,
+   ) => void | Promise<void>;
+
+   readonly onConsequenceCollected?: (
+      rule: Rule<TContext, TConsequences>,
+      consequence: AggregatedConsequence<TConsequences>,
+   ) => void | Promise<void>;
+
+   readonly onCacheHit?: (
+      key: string,
+      result: EngineExecutionResult<TContext, TConsequences>,
+   ) => void | Promise<void>;
+
+   readonly onCacheMiss?: (key: string) => void | Promise<void>;
+
+   readonly onSlowRule?: (
+      rule: Rule<TContext, TConsequences>,
+      timeMs: number,
+      threshold: number,
+   ) => void | Promise<void>;
+
+   readonly onHookError?: (hookName: string, error: Error) => void;
+};
+
+export type EngineConfig<
+   TContext = unknown,
+   TConsequences extends ConsequenceDefinitions = DefaultConsequences,
+> = {
+   readonly consequences?: TConsequences;
+   readonly conflictResolution?: ConflictResolutionStrategy;
+   readonly cache?: Partial<CacheConfig>;
+   readonly validation?: Partial<ValidationConfig>;
+   readonly versioning?: Partial<VersioningConfig>;
+   readonly hooks?: EngineHooks<TContext, TConsequences>;
+   readonly logLevel?: LogLevel;
+   readonly logger?: Logger;
+   readonly continueOnError?: boolean;
+   readonly slowRuleThresholdMs?: number;
+   readonly hookTimeoutMs?: number;
+   // NEW: Evaluator configuration (mutually exclusive)
+   readonly evaluator?: ReturnType<typeof import("@f-o-t/condition-evaluator").createEvaluator>;
+   readonly operators?: OperatorMap;
+};
+
+export type ResolvedEngineConfig<
+   TContext = unknown,
+   TConsequences extends ConsequenceDefinitions = DefaultConsequences,
+> = {
+   readonly consequences: TConsequences | undefined;
+   readonly conflictResolution: ConflictResolutionStrategy;
+   readonly cache: CacheConfig;
+   readonly validation: ValidationConfig;
+   readonly versioning: VersioningConfig;
+   readonly hooks: EngineHooks<TContext, TConsequences>;
+   readonly logLevel: LogLevel;
+   readonly logger: Logger;
+   readonly continueOnError: boolean;
+   readonly slowRuleThresholdMs: number;
+   readonly hookTimeoutMs: number | undefined;
+   // NEW: Resolved evaluator instance
+   readonly evaluator: ReturnType<typeof import("@f-o-t/condition-evaluator").createEvaluator>;
+};
+
+// ============================================================================
+// Helper functions for parsing/resolving configs with defaults
+// ============================================================================
+
+export const parseCacheConfig = (input?: Partial<CacheConfig>): CacheConfig =>
+   CacheConfigSchema.parse(input ?? {});
+
+export const parseValidationConfig = (
+   input?: Partial<ValidationConfig>,
+): ValidationConfig => ValidationConfigSchema.parse(input ?? {});
+
+export const parseVersioningConfig = (
+   input?: Partial<VersioningConfig>,
+): VersioningConfig => VersioningConfigSchema.parse(input ?? {});
+
+export const getDefaultCacheConfig = (): CacheConfig =>
+   CacheConfigSchema.parse({});
+
+export const getDefaultValidationConfig = (): ValidationConfig =>
+   ValidationConfigSchema.parse({});
+
+export const getDefaultVersioningConfig = (): VersioningConfig =>
+   VersioningConfigSchema.parse({});
+
+export const getDefaultLogLevel = (): LogLevel => "warn";
+
+export const getDefaultConflictResolution = (): ConflictResolutionStrategy =>
+   "priority";

package/src/types/consequence.ts

@@ -0,0 +1,38 @@
+import type { z } from "zod";
+
+export type ConsequenceDefinitions = Record<string, z.ZodType>;
+
+export type DefaultConsequences = Record<string, z.ZodType>;
+
+export type InferConsequenceType<T extends ConsequenceDefinitions> = keyof T;
+
+export type InferConsequencePayload<
+   T extends ConsequenceDefinitions,
+   K extends keyof T,
+> = z.infer<T[K]>;
+
+export type Consequence<
+   TConsequences extends ConsequenceDefinitions = DefaultConsequences,
+   TType extends keyof TConsequences = keyof TConsequences,
+> = {
+   readonly type: TType;
+   readonly payload: z.infer<TConsequences[TType]>;
+};
+
+export type ConsequenceInput<
+   TConsequences extends ConsequenceDefinitions = DefaultConsequences,
+   TType extends keyof TConsequences = keyof TConsequences,
+> = {
+   type: TType;
+   payload: z.infer<TConsequences[TType]>;
+};
+
+export type AggregatedConsequence<
+   TConsequences extends ConsequenceDefinitions = DefaultConsequences,
+> = {
+   readonly type: keyof TConsequences;
+   readonly payload: unknown;
+   readonly ruleId: string;
+   readonly ruleName?: string;
+   readonly priority: number;
+};

package/src/types/evaluation.ts

@@ -0,0 +1,87 @@
+import type { GroupEvaluationResult } from "@f-o-t/condition-evaluator";
+import { z } from "zod";
+import type {
+   AggregatedConsequence,
+   ConsequenceDefinitions,
+   DefaultConsequences,
+} from "./consequence";
+import type { Rule } from "./rule";
+
+// ============================================================================
+// Zod Schemas - Define schemas first, then infer types
+// ============================================================================
+
+export const ConflictResolutionStrategySchema = z.enum([
+   "priority",
+   "first-match",
+   "all",
+   "most-specific",
+]);
+export type ConflictResolutionStrategy = z.infer<
+   typeof ConflictResolutionStrategySchema
+>;
+
+export const EvaluateOptionsSchema = z.object({
+   conflictResolution: ConflictResolutionStrategySchema.optional(),
+   maxRules: z.number().int().positive().optional(),
+   timeout: z.number().int().positive().optional(),
+   skipDisabled: z.boolean().optional(),
+   tags: z.array(z.string()).optional(),
+   category: z.string().optional(),
+   ruleSetId: z.string().optional(),
+   bypassCache: z.boolean().optional(),
+});
+export type EvaluateOptions = z.infer<typeof EvaluateOptionsSchema>;
+
+export const EvaluateConfigSchema = z.object({
+   conflictResolution: ConflictResolutionStrategySchema,
+   continueOnError: z.boolean(),
+   collectAllConsequences: z.boolean(),
+});
+export type EvaluateConfig = z.infer<typeof EvaluateConfigSchema>;
+
+// ============================================================================
+// Types that cannot be Zod schemas (contain complex generics)
+// ============================================================================
+
+export type EvaluationContext<TContext = unknown> = {
+   readonly data: TContext;
+   readonly timestamp: Date;
+   readonly correlationId?: string;
+   readonly metadata?: Readonly<Record<string, unknown>>;
+};
+
+export type RuleEvaluationResult<
+   _TContext = unknown,
+   TConsequences extends ConsequenceDefinitions = DefaultConsequences,
+> = {
+   readonly ruleId: string;
+   readonly ruleName: string;
+   readonly matched: boolean;
+   readonly conditionResult: GroupEvaluationResult;
+   readonly consequences: ReadonlyArray<AggregatedConsequence<TConsequences>>;
+   readonly evaluationTimeMs: number;
+   readonly skipped: boolean;
+   readonly skipReason?: string;
+   readonly error?: Error;
+};
+
+export type EngineExecutionResult<
+   TContext = unknown,
+   TConsequences extends ConsequenceDefinitions = DefaultConsequences,
+> = {
+   readonly context: EvaluationContext<TContext>;
+   readonly results: ReadonlyArray<
+      RuleEvaluationResult<TContext, TConsequences>
+   >;
+   readonly matchedRules: ReadonlyArray<Rule<TContext, TConsequences>>;
+   readonly consequences: ReadonlyArray<AggregatedConsequence<TConsequences>>;
+   readonly totalRulesEvaluated: number;
+   readonly totalRulesMatched: number;
+   readonly totalRulesSkipped: number;
+   readonly totalRulesErrored: number;
+   readonly executionTimeMs: number;
+   readonly stoppedEarly: boolean;
+   readonly stoppedByRuleId?: string;
+   readonly cacheHit: boolean;
+};