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

package/src/core/evaluate.ts

@@ -0,0 +1,185 @@
+import {
+  createEvaluator,
+  type GroupEvaluationResult,
+} from "@f-o-t/condition-evaluator";
+import type {
+   AggregatedConsequence,
+   ConsequenceDefinitions,
+   DefaultConsequences,
+} from "../types/consequence";
+import type {
+   EvaluateConfig,
+   EvaluationContext,
+   RuleEvaluationResult,
+} from "../types/evaluation";
+import type { Rule } from "../types/rule";
+import { measureTime } from "../utils/time";
+
+export type EvaluateRuleOptions = {
+   readonly skipDisabled?: boolean;
+};
+
+export const evaluateRule = <
+   TContext = unknown,
+   TConsequences extends ConsequenceDefinitions = DefaultConsequences,
+>(
+   rule: Rule<TContext, TConsequences>,
+   context: EvaluationContext<TContext>,
+   evaluator: ReturnType<typeof createEvaluator>,
+   options: EvaluateRuleOptions = {},
+): RuleEvaluationResult<TContext, TConsequences> => {
+   if (options.skipDisabled && !rule.enabled) {
+      return {
+         ruleId: rule.id,
+         ruleName: rule.name,
+         matched: false,
+         conditionResult: createEmptyGroupResult(rule.conditions.id),
+         consequences: [],
+         evaluationTimeMs: 0,
+         skipped: true,
+         skipReason: "Rule is disabled",
+      };
+   }
+
+   const { result: conditionResult, durationMs } = measureTime(() => {
+      try {
+         const evalContext = {
+            data: context.data as Record<string, unknown>,
+            metadata: context.metadata as Record<string, unknown> | undefined,
+         };
+         // Use the provided evaluator instead of hardcoded evaluateConditionGroup
+         return evaluator.evaluateConditionGroup(rule.conditions, evalContext);
+      } catch (error) {
+         return {
+            error,
+            result: createEmptyGroupResult(rule.conditions.id),
+         };
+      }
+   });
+
+   if ("error" in conditionResult) {
+      return {
+         ruleId: rule.id,
+         ruleName: rule.name,
+         matched: false,
+         conditionResult: conditionResult.result,
+         consequences: [],
+         evaluationTimeMs: durationMs,
+         skipped: false,
+         error:
+            conditionResult.error instanceof Error
+               ? conditionResult.error
+               : new Error(String(conditionResult.error)),
+      };
+   }
+
+   const matched = conditionResult.passed;
+
+   const consequences: AggregatedConsequence<TConsequences>[] = matched
+      ? rule.consequences.map((consequence) => ({
+           type: consequence.type,
+           payload: consequence.payload,
+           ruleId: rule.id,
+           ruleName: rule.name,
+           priority: rule.priority,
+        }))
+      : [];
+
+   return {
+      ruleId: rule.id,
+      ruleName: rule.name,
+      matched,
+      conditionResult,
+      consequences,
+      evaluationTimeMs: durationMs,
+      skipped: false,
+   };
+};
+
+const createEmptyGroupResult = (groupId: string): GroupEvaluationResult => ({
+   groupId,
+   operator: "AND",
+   passed: false,
+   results: [],
+});
+
+export type EvaluateRulesOptions<
+   TContext = unknown,
+   TConsequences extends ConsequenceDefinitions = DefaultConsequences,
+> = {
+   readonly config?: Partial<EvaluateConfig>;
+   readonly onRuleEvaluated?: (
+      result: RuleEvaluationResult<TContext, TConsequences>,
+   ) => void;
+};
+
+export type EvaluateRulesResult<
+   TContext = unknown,
+   TConsequences extends ConsequenceDefinitions = DefaultConsequences,
+> = {
+   readonly results: ReadonlyArray<
+      RuleEvaluationResult<TContext, TConsequences>
+   >;
+   readonly matchedRules: ReadonlyArray<Rule<TContext, TConsequences>>;
+   readonly consequences: ReadonlyArray<AggregatedConsequence<TConsequences>>;
+   readonly stoppedEarly: boolean;
+   readonly stoppedByRuleId?: string;
+};
+
+export const evaluateRules = <
+   TContext = unknown,
+   TConsequences extends ConsequenceDefinitions = DefaultConsequences,
+>(
+   rules: ReadonlyArray<Rule<TContext, TConsequences>>,
+   context: EvaluationContext<TContext>,
+   evaluator: ReturnType<typeof createEvaluator>,
+   options: EvaluateRulesOptions<TContext, TConsequences> = {},
+): EvaluateRulesResult<TContext, TConsequences> => {
+   const config: EvaluateConfig = {
+      conflictResolution: options.config?.conflictResolution ?? "priority",
+      continueOnError: options.config?.continueOnError ?? true,
+      collectAllConsequences: options.config?.collectAllConsequences ?? true,
+   };
+
+   const results: RuleEvaluationResult<TContext, TConsequences>[] = [];
+   const matchedRules: Rule<TContext, TConsequences>[] = [];
+   const consequences: AggregatedConsequence<TConsequences>[] = [];
+   let stoppedEarly = false;
+   let stoppedByRuleId: string | undefined;
+
+   for (const rule of rules) {
+      const result = evaluateRule(rule, context, evaluator, { skipDisabled: true });
+      results.push(result);
+
+      options.onRuleEvaluated?.(result);
+
+      if (result.error && !config.continueOnError) {
+         break;
+      }
+
+      if (result.matched) {
+         matchedRules.push(rule);
+         consequences.push(...result.consequences);
+
+         if (rule.stopOnMatch) {
+            stoppedEarly = true;
+            stoppedByRuleId = rule.id;
+            break;
+         }
+
+         if (config.conflictResolution === "first-match") {
+            stoppedEarly = true;
+            stoppedByRuleId = rule.id;
+            break;
+         }
+      }
+   }
+
+   return {
+      results,
+      matchedRules,
+      consequences,
+      stoppedEarly,
+      stoppedByRuleId,
+   };
+};

package/src/core/filter.ts

@@ -0,0 +1,85 @@
+import type {
+   ConsequenceDefinitions,
+   DefaultConsequences,
+} from "../types/consequence";
+import type { Rule, RuleFilters } from "../types/rule";
+
+export const filterRules = <
+   TContext = unknown,
+   TConsequences extends ConsequenceDefinitions = DefaultConsequences,
+>(
+   filters: RuleFilters,
+) => {
+   return (
+      rules: ReadonlyArray<Rule<TContext, TConsequences>>,
+   ): ReadonlyArray<Rule<TContext, TConsequences>> => {
+      return rules.filter((rule) => {
+         if (
+            filters.enabled !== undefined &&
+            rule.enabled !== filters.enabled
+         ) {
+            return false;
+         }
+
+         if (filters.tags && filters.tags.length > 0) {
+            const hasMatchingTag = filters.tags.some((tag) =>
+               rule.tags.includes(tag),
+            );
+            if (!hasMatchingTag) {
+               return false;
+            }
+         }
+
+         if (
+            filters.category !== undefined &&
+            rule.category !== filters.category
+         ) {
+            return false;
+         }
+
+         if (filters.ids && filters.ids.length > 0) {
+            if (!filters.ids.includes(rule.id)) {
+               return false;
+            }
+         }
+
+         return true;
+      });
+   };
+};
+
+export const filterByEnabled = <
+   TContext = unknown,
+   TConsequences extends ConsequenceDefinitions = DefaultConsequences,
+>(
+   enabled: boolean,
+) => {
+   return filterRules<TContext, TConsequences>({ enabled });
+};
+
+export const filterByTags = <
+   TContext = unknown,
+   TConsequences extends ConsequenceDefinitions = DefaultConsequences,
+>(
+   tags: ReadonlyArray<string>,
+) => {
+   return filterRules<TContext, TConsequences>({ tags });
+};
+
+export const filterByCategory = <
+   TContext = unknown,
+   TConsequences extends ConsequenceDefinitions = DefaultConsequences,
+>(
+   category: string,
+) => {
+   return filterRules<TContext, TConsequences>({ category });
+};
+
+export const filterByIds = <
+   TContext = unknown,
+   TConsequences extends ConsequenceDefinitions = DefaultConsequences,
+>(
+   ids: ReadonlyArray<string>,
+) => {
+   return filterRules<TContext, TConsequences>({ ids });
+};

package/src/core/group.ts

@@ -0,0 +1,103 @@
+import type {
+   ConsequenceDefinitions,
+   DefaultConsequences,
+} from "../types/consequence";
+import type { Rule } from "../types/rule";
+
+export type GroupByField = "category" | "priority" | "enabled";
+
+export type GroupedRules<
+   TContext = unknown,
+   TConsequences extends ConsequenceDefinitions = DefaultConsequences,
+> = ReadonlyMap<
+   string | number | boolean,
+   ReadonlyArray<Rule<TContext, TConsequences>>
+>;
+
+export const groupRules = <
+   TContext = unknown,
+   TConsequences extends ConsequenceDefinitions = DefaultConsequences,
+>(
+   field: GroupByField,
+) => {
+   return (
+      rules: ReadonlyArray<Rule<TContext, TConsequences>>,
+   ): GroupedRules<TContext, TConsequences> => {
+      const groups = new Map<
+         string | number | boolean,
+         Rule<TContext, TConsequences>[]
+      >();
+
+      for (const rule of rules) {
+         let key: string | number | boolean;
+
+         switch (field) {
+            case "category":
+               key = rule.category ?? "uncategorized";
+               break;
+            case "priority":
+               key = rule.priority;
+               break;
+            case "enabled":
+               key = rule.enabled;
+               break;
+         }
+
+         const existing = groups.get(key);
+         if (existing) {
+            existing.push(rule);
+         } else {
+            groups.set(key, [rule]);
+         }
+      }
+
+      return groups;
+   };
+};
+
+export const groupByCategory = <
+   TContext = unknown,
+   TConsequences extends ConsequenceDefinitions = DefaultConsequences,
+>() => {
+   return groupRules<TContext, TConsequences>("category");
+};
+
+export const groupByPriority = <
+   TContext = unknown,
+   TConsequences extends ConsequenceDefinitions = DefaultConsequences,
+>() => {
+   return groupRules<TContext, TConsequences>("priority");
+};
+
+export const groupByEnabled = <
+   TContext = unknown,
+   TConsequences extends ConsequenceDefinitions = DefaultConsequences,
+>() => {
+   return groupRules<TContext, TConsequences>("enabled");
+};
+
+export const groupByCustom = <
+   TContext = unknown,
+   TConsequences extends ConsequenceDefinitions = DefaultConsequences,
+   TKey extends string | number | boolean = string,
+>(
+   keyFn: (rule: Rule<TContext, TConsequences>) => TKey,
+) => {
+   return (
+      rules: ReadonlyArray<Rule<TContext, TConsequences>>,
+   ): ReadonlyMap<TKey, ReadonlyArray<Rule<TContext, TConsequences>>> => {
+      const groups = new Map<TKey, Rule<TContext, TConsequences>[]>();
+
+      for (const rule of rules) {
+         const key = keyFn(rule);
+         const existing = groups.get(key);
+         if (existing) {
+            existing.push(rule);
+         } else {
+            groups.set(key, [rule]);
+         }
+      }
+
+      return groups;
+   };
+};

package/src/core/sort.ts

@@ -0,0 +1,90 @@
+import type {
+   ConsequenceDefinitions,
+   DefaultConsequences,
+} from "../types/consequence";
+import type { Rule } from "../types/rule";
+
+export type SortField = "priority" | "name" | "createdAt" | "updatedAt";
+export type SortDirection = "asc" | "desc";
+
+export type SortOptions = {
+   readonly field: SortField;
+   readonly direction?: SortDirection;
+};
+
+export const sortRules = <
+   TContext = unknown,
+   TConsequences extends ConsequenceDefinitions = DefaultConsequences,
+>(
+   options: SortField | SortOptions,
+) => {
+   const normalizedOptions: SortOptions =
+      typeof options === "string"
+         ? { field: options, direction: "desc" }
+         : options;
+
+   const { field, direction = "desc" } = normalizedOptions;
+
+   return (
+      rules: ReadonlyArray<Rule<TContext, TConsequences>>,
+   ): ReadonlyArray<Rule<TContext, TConsequences>> => {
+      const sorted = [...rules].sort((a, b) => {
+         let comparison = 0;
+
+         switch (field) {
+            case "priority":
+               comparison = a.priority - b.priority;
+               break;
+            case "name":
+               comparison = a.name.localeCompare(b.name);
+               break;
+            case "createdAt":
+               comparison = a.createdAt.getTime() - b.createdAt.getTime();
+               break;
+            case "updatedAt":
+               comparison = a.updatedAt.getTime() - b.updatedAt.getTime();
+               break;
+         }
+
+         return direction === "desc" ? -comparison : comparison;
+      });
+
+      return sorted;
+   };
+};
+
+export const sortByPriority = <
+   TContext = unknown,
+   TConsequences extends ConsequenceDefinitions = DefaultConsequences,
+>(
+   direction: SortDirection = "desc",
+) => {
+   return sortRules<TContext, TConsequences>({ field: "priority", direction });
+};
+
+export const sortByName = <
+   TContext = unknown,
+   TConsequences extends ConsequenceDefinitions = DefaultConsequences,
+>(
+   direction: SortDirection = "asc",
+) => {
+   return sortRules<TContext, TConsequences>({ field: "name", direction });
+};
+
+export const sortByCreatedAt = <
+   TContext = unknown,
+   TConsequences extends ConsequenceDefinitions = DefaultConsequences,
+>(
+   direction: SortDirection = "desc",
+) => {
+   return sortRules<TContext, TConsequences>({ field: "createdAt", direction });
+};
+
+export const sortByUpdatedAt = <
+   TContext = unknown,
+   TConsequences extends ConsequenceDefinitions = DefaultConsequences,
+>(
+   direction: SortDirection = "desc",
+) => {
+   return sortRules<TContext, TConsequences>({ field: "updatedAt", direction });
+};