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

package/src/types/rule.ts

@@ -0,0 +1,112 @@
+import type { ConditionGroup } from "@f-o-t/condition-evaluator";
+import { z } from "zod";
+import type {
+   Consequence,
+   ConsequenceDefinitions,
+   DefaultConsequences,
+} from "./consequence";
+
+export type Rule<
+   _TContext = unknown,
+   TConsequences extends ConsequenceDefinitions = DefaultConsequences,
+> = {
+   readonly id: string;
+   readonly name: string;
+   readonly description?: string;
+   readonly conditions: ConditionGroup;
+   readonly consequences: ReadonlyArray<Consequence<TConsequences>>;
+   readonly priority: number;
+   readonly enabled: boolean;
+   readonly stopOnMatch: boolean;
+   readonly tags: ReadonlyArray<string>;
+   readonly category?: string;
+   readonly metadata?: Readonly<Record<string, unknown>>;
+   readonly createdAt: Date;
+   readonly updatedAt: Date;
+};
+
+export type RuleInput<
+   _TContext = unknown,
+   TConsequences extends ConsequenceDefinitions = DefaultConsequences,
+> = {
+   id?: string;
+   name: string;
+   description?: string;
+   conditions: ConditionGroup;
+   consequences: Array<{
+      type: keyof TConsequences;
+      payload: z.infer<TConsequences[keyof TConsequences]>;
+   }>;
+   priority?: number;
+   enabled?: boolean;
+   stopOnMatch?: boolean;
+   tags?: string[];
+   category?: string;
+   metadata?: Record<string, unknown>;
+};
+
+export type RuleSet = {
+   readonly id: string;
+   readonly name: string;
+   readonly description?: string;
+   readonly ruleIds: ReadonlyArray<string>;
+   readonly enabled: boolean;
+   readonly metadata?: Readonly<Record<string, unknown>>;
+};
+
+export type RuleSetInput = {
+   id?: string;
+   name: string;
+   description?: string;
+   ruleIds: string[];
+   enabled?: boolean;
+   metadata?: Record<string, unknown>;
+};
+
+export type RuleFilters = {
+   readonly enabled?: boolean;
+   readonly tags?: ReadonlyArray<string>;
+   readonly category?: string;
+   readonly ruleSetId?: string;
+   readonly ids?: ReadonlyArray<string>;
+};
+
+export const RuleSchema = z.object({
+   id: z.string().min(1),
+   name: z.string().min(1),
+   description: z.string().optional(),
+   conditions: z.custom<ConditionGroup>((val) => {
+      return (
+         typeof val === "object" &&
+         val !== null &&
+         "id" in val &&
+         "operator" in val
+      );
+   }, "Invalid condition group"),
+   consequences: z.array(
+      z.object({
+         type: z.string(),
+         payload: z.unknown(),
+      }),
+   ),
+   priority: z.number().int().default(0),
+   enabled: z.boolean().default(true),
+   stopOnMatch: z.boolean().default(false),
+   tags: z.array(z.string()).default([]),
+   category: z.string().optional(),
+   metadata: z.record(z.string(), z.unknown()).optional(),
+   createdAt: z.date().default(() => new Date()),
+   updatedAt: z.date().default(() => new Date()),
+});
+
+export const RuleSetSchema = z.object({
+   id: z.string().min(1),
+   name: z.string().min(1),
+   description: z.string().optional(),
+   ruleIds: z.array(z.string()),
+   enabled: z.boolean().default(true),
+   metadata: z.record(z.string(), z.unknown()).optional(),
+});
+
+export type RuleSchemaType = z.infer<typeof RuleSchema>;
+export type RuleSetSchemaType = z.infer<typeof RuleSetSchema>;

package/src/types/state.ts

@@ -0,0 +1,116 @@
+import { z } from "zod";
+import type {
+   ConsequenceDefinitions,
+   DefaultConsequences,
+} from "./consequence";
+import type { Rule, RuleSet } from "./rule";
+
+// ============================================================================
+// Zod Schemas - Define schemas first, then infer types
+// ============================================================================
+
+export const RuleStatsSchema = z.object({
+   evaluations: z.number().int().nonnegative(),
+   matches: z.number().int().nonnegative(),
+   errors: z.number().int().nonnegative(),
+   totalTimeMs: z.number().nonnegative(),
+   avgTimeMs: z.number().nonnegative(),
+   lastEvaluated: z.date().optional(),
+});
+export type RuleStats = z.infer<typeof RuleStatsSchema>;
+
+export const CacheStatsSchema = z.object({
+   size: z.number().int().nonnegative(),
+   maxSize: z.number().int().positive(),
+   hits: z.number().int().nonnegative(),
+   misses: z.number().int().nonnegative(),
+   hitRate: z.number().min(0).max(1),
+   evictions: z.number().int().nonnegative(),
+});
+export type CacheStats = z.infer<typeof CacheStatsSchema>;
+
+export const EngineStatsSchema = z.object({
+   totalRules: z.number().int().nonnegative(),
+   enabledRules: z.number().int().nonnegative(),
+   disabledRules: z.number().int().nonnegative(),
+   totalRuleSets: z.number().int().nonnegative(),
+   totalEvaluations: z.number().int().nonnegative(),
+   totalMatches: z.number().int().nonnegative(),
+   totalErrors: z.number().int().nonnegative(),
+   avgEvaluationTimeMs: z.number().nonnegative(),
+   cacheHits: z.number().int().nonnegative(),
+   cacheMisses: z.number().int().nonnegative(),
+   cacheHitRate: z.number().min(0).max(1),
+});
+export type EngineStats = z.infer<typeof EngineStatsSchema>;
+
+// ============================================================================
+// Types that cannot be Zod schemas (contain Maps or complex generics)
+// ============================================================================
+
+export type EngineState<
+   TContext = unknown,
+   TConsequences extends ConsequenceDefinitions = DefaultConsequences,
+> = {
+   readonly rules: ReadonlyMap<string, Rule<TContext, TConsequences>>;
+   readonly ruleSets: ReadonlyMap<string, RuleSet>;
+   readonly ruleOrder: ReadonlyArray<string>;
+};
+
+// Internal mutable version - not exported from index.ts
+export type MutableEngineState<
+   TContext = unknown,
+   TConsequences extends ConsequenceDefinitions = DefaultConsequences,
+> = {
+   rules: Map<string, Rule<TContext, TConsequences>>;
+   ruleSets: Map<string, RuleSet>;
+   ruleOrder: string[];
+};
+
+// Internal mutable version - not exported from index.ts
+export type MutableRuleStats = {
+   evaluations: number;
+   matches: number;
+   errors: number;
+   totalTimeMs: number;
+   avgTimeMs: number;
+   lastEvaluated?: Date;
+};
+
+export type OptimizerState = {
+   readonly ruleStats: ReadonlyMap<string, RuleStats>;
+   readonly lastOptimized?: Date;
+};
+
+// Internal mutable version - not exported from index.ts
+export type MutableOptimizerState = {
+   ruleStats: Map<string, MutableRuleStats>;
+   lastOptimized?: Date;
+};
+
+// ============================================================================
+// Factory functions
+// ============================================================================
+
+export const createInitialState = <
+   TContext = unknown,
+   TConsequences extends ConsequenceDefinitions = DefaultConsequences,
+>(): MutableEngineState<TContext, TConsequences> => ({
+   rules: new Map(),
+   ruleSets: new Map(),
+   ruleOrder: [],
+});
+
+export const createInitialOptimizerState = (): MutableOptimizerState => ({
+   ruleStats: new Map(),
+   lastOptimized: undefined,
+});
+
+export const createInitialRuleStats = (): MutableRuleStats => ({
+   evaluations: 0,
+   matches: 0,
+   errors: 0,
+   totalTimeMs: 0,
+   avgTimeMs: 0,
+   lastEvaluated: undefined,
+});

package/src/utils/conditions.ts

@@ -0,0 +1,108 @@
+import {
+   type Condition,
+   type ConditionGroup,
+   isConditionGroup,
+} from "@f-o-t/condition-evaluator";
+
+/**
+ * Collects all unique field names from a condition tree.
+ * Traverses nested condition groups recursively.
+ */
+export const collectConditionFields = (
+   condition: ConditionGroup,
+): Set<string> => {
+   const fields = new Set<string>();
+
+   const traverse = (c: Condition | ConditionGroup) => {
+      if (isConditionGroup(c)) {
+         for (const child of c.conditions) {
+            traverse(child as Condition | ConditionGroup);
+         }
+      } else {
+         fields.add(c.field);
+      }
+   };
+
+   traverse(condition);
+   return fields;
+};
+
+/**
+ * Collects all unique operators from a condition tree.
+ * Returns a map of operator to its type (e.g., "equals" -> "string").
+ */
+export const collectConditionOperators = (
+   condition: ConditionGroup,
+): Map<string, Set<string>> => {
+   const operators = new Map<string, Set<string>>();
+
+   const traverse = (c: Condition | ConditionGroup) => {
+      if (isConditionGroup(c)) {
+         for (const child of c.conditions) {
+            traverse(child as Condition | ConditionGroup);
+         }
+      } else {
+         const existing = operators.get(c.operator) ?? new Set<string>();
+         existing.add(c.type);
+         operators.set(c.operator, existing);
+      }
+   };
+
+   traverse(condition);
+   return operators;
+};
+
+/**
+ * Counts the total number of leaf conditions in a condition tree.
+ */
+export const countConditions = (
+   condition: Condition | ConditionGroup,
+): number => {
+   if (isConditionGroup(condition)) {
+      return condition.conditions.reduce(
+         (sum: number, c: Condition | ConditionGroup) => sum + countConditions(c as Condition | ConditionGroup),
+         0,
+      );
+   }
+   return 1;
+};
+
+/**
+ * Calculates the maximum depth of a condition tree.
+ */
+export const calculateMaxDepth = (
+   condition: Condition | ConditionGroup,
+   currentDepth = 1,
+): number => {
+   if (isConditionGroup(condition)) {
+      if (condition.conditions.length === 0) return currentDepth;
+      return Math.max(
+         ...condition.conditions.map((c: Condition | ConditionGroup) =>
+            calculateMaxDepth(
+               c as Condition | ConditionGroup,
+               currentDepth + 1,
+            ),
+         ),
+      );
+   }
+   return currentDepth;
+};
+
+/**
+ * Counts the number of condition groups in a condition tree.
+ */
+export const countConditionGroups = (
+   condition: Condition | ConditionGroup,
+): number => {
+   if (isConditionGroup(condition)) {
+      return (
+         1 +
+         condition.conditions.reduce(
+            (sum: number, c: Condition | ConditionGroup) =>
+               sum + countConditionGroups(c as Condition | ConditionGroup),
+            0,
+         )
+      );
+   }
+   return 0;
+};

package/src/utils/hash.ts

@@ -0,0 +1,30 @@
+export const hashContext = (context: unknown): string => {
+   const str = JSON.stringify(context, (_, value) => {
+      if (value instanceof Date) {
+         return value.toISOString();
+      }
+      if (value instanceof Map) {
+         return Object.fromEntries(value);
+      }
+      if (value instanceof Set) {
+         return Array.from(value);
+      }
+      return value;
+   });
+
+   if (typeof Bun !== "undefined" && Bun.hash) {
+      return Bun.hash(str).toString(16);
+   }
+
+   let hash = 0;
+   for (let i = 0; i < str.length; i++) {
+      const char = str.charCodeAt(i);
+      hash = (hash << 5) - hash + char;
+      hash = hash & hash;
+   }
+   return Math.abs(hash).toString(16);
+};
+
+export const hashRules = (ruleIds: ReadonlyArray<string>): string => {
+   return hashContext(ruleIds.slice().sort());
+};

package/src/utils/id.ts

@@ -0,0 +1,6 @@
+export const generateId = (): string => {
+   if (typeof crypto !== "undefined" && crypto.randomUUID) {
+      return crypto.randomUUID();
+   }
+   return `${Date.now().toString(36)}-${Math.random().toString(36).substring(2, 11)}`;
+};

package/src/utils/time.ts

@@ -0,0 +1,42 @@
+export type TimingResult<T> = {
+   readonly result: T;
+   readonly durationMs: number;
+};
+
+export const measureTime = <T>(fn: () => T): TimingResult<T> => {
+   const start = performance.now();
+   const result = fn();
+   const durationMs = performance.now() - start;
+   return { result, durationMs };
+};
+
+export const measureTimeAsync = async <T>(
+   fn: () => Promise<T>,
+): Promise<TimingResult<T>> => {
+   const start = performance.now();
+   const result = await fn();
+   const durationMs = performance.now() - start;
+   return { result, durationMs };
+};
+
+export const withTimeout = <T>(
+   promise: Promise<T>,
+   timeoutMs: number,
+   errorMessage = "Operation timed out",
+): Promise<T> => {
+   return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+         reject(new Error(errorMessage));
+      }, timeoutMs);
+
+      promise
+         .then((result) => {
+            clearTimeout(timer);
+            resolve(result);
+         })
+         .catch((error) => {
+            clearTimeout(timer);
+            reject(error);
+         });
+   });
+};