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

package/package.json

@@ -1,7 +1,10 @@
 {
   "name": "@f-o-t/rules-engine",
-  "version": "3.0.0",
+  "version": "3.0.1",
   "type": "module",
+  "files": [
+    "dist"
+  ],
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {

package/CHANGELOG.md

@@ -1,168 +0,0 @@
-# Changelog
-
-All notable changes to this project will be documented in this file.
-
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
-and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
-
-## [3.0.0] - 2026-01-31
-
-### ⚠️ BREAKING CHANGES
-
-- Engine now requires `evaluator` or `operators` configuration
-- `evaluateRule()` function signature changed to accept evaluator parameter
-- `evaluateRules()` function signature changed to accept evaluator parameter
-
-### 🎉 Features
-
-- **Custom operators support**: Use custom operators from any library (e.g., `@f-o-t/money/operators`)
-- **Plugin system integration**: Full integration with `@f-o-t/condition-evaluator` plugin system
-- **Better extensibility**: Easily compose multiple operator sets
-- **Type-safe operators**: Better TypeScript support for custom operator types
-
-### 📚 Documentation
-
-- Added migration guide for v2 → v3
-- Updated README with custom operator examples
-- Added examples for money operators integration
-
-### 🔧 Migration
-
-See [MIGRATION-v3.md](./docs/MIGRATION-v3.md) for detailed migration instructions.
-
-**Quick migration:**
-```typescript
-// Before (v2.x)
-const engine = createEngine({ consequences: MyConsequences });
-
-// After (v3.x)
-const engine = createEngine({
-  consequences: MyConsequences,
-  evaluator: createEvaluator() // Add this
-});
-```
-
----
-
-## [2.0.2] - 2026-01-25
-
-### Changed
-
-- Updated dependencies to latest versions
-
-## [2.0.1] - 2025-12-31
-
-### Changed
-
-- Removed unused imports and dead code
-  - Removed unused `ConditionGroup` type import from index-builder
-  - Removed unused `ConflictResolutionStrategySchema` import from config types
-  - Removed unused `_cacheStats` variable from engine stats
-  - Removed unused `_collectAllConditionIds` helper function from integrity validation
-
-## [2.0.0] - 2025-12-24
-
-### Added
-
-- **Zod Schema-First Types**: All configuration types now built from Zod schemas
-  - `CacheConfigSchema`, `ValidationConfigSchema`, `VersioningConfigSchema`, `LogLevelSchema`
-  - `ConflictResolutionStrategySchema`, `EvaluateOptionsSchema`, `EvaluateConfigSchema`
-  - `RuleStatsSchema`, `CacheStatsSchema`, `EngineStatsSchema`
-  - `ValidationErrorSchema`, `ValidationResultSchema`, `ValidationOptionsSchema`
-- **Hook Error Handling**: New `onHookError` callback for capturing hook errors
-  - Previously hooks failed silently; now errors are reported via callback
-- **Hook Timeout Protection**: New `hookTimeoutMs` config option
-  - Prevents slow hooks from blocking engine execution indefinitely
-  - Timeout errors are reported through `onHookError`
-- **Orphaned Reference Detection**: `ImportResult` now includes `orphanedReferences`
-  - Detects when imported RuleSets reference non-existent rule IDs
-  - New `OrphanedReference` type exported
-- **Shared Conditions Utility**: New internal `src/utils/conditions.ts`
-  - `collectConditionFields()`, `collectConditionOperators()`, `countConditions()`
-  - `calculateMaxDepth()`, `countConditionGroups()`
-- **Config Helper Functions**: New functions replace constants
-  - `getDefaultCacheConfig()`, `getDefaultValidationConfig()`, `getDefaultVersioningConfig()`
-  - `getDefaultLogLevel()`, `getDefaultConflictResolution()`
-  - `parseCacheConfig()`, `parseValidationConfig()`, `parseVersioningConfig()`
-
-### Changed
-
-- **Cache Eviction Performance**: O(n) → O(1) for oldest entry eviction
-  - Now uses ES6 Map insertion order for FIFO eviction
-- **Strict Mode Behavior**: `strictMode: true` now implicitly enables consequence validation
-  - Previously required both `strictMode: true` and `validateConsequences: true`
-
-### Removed
-
-- **BREAKING**: Removed FP utility exports from `src/utils/pipe.ts`
-  - `pipe()`, `compose()`, `identity()`, `always()`, `tap()`
-  - These generic utilities are not domain-specific; use lodash/ramda instead
-- **BREAKING**: Removed `delay()` from `src/utils/time.ts`
-  - Low value utility; use `Bun.sleep()` or inline `new Promise(resolve => setTimeout(resolve, ms))`
-- **BREAKING**: Removed `DEFAULT_*` constant exports
-  - `DEFAULT_CACHE_CONFIG` → use `getDefaultCacheConfig()`
-  - `DEFAULT_VALIDATION_CONFIG` → use `getDefaultValidationConfig()`
-  - `DEFAULT_VERSIONING_CONFIG` → use `getDefaultVersioningConfig()`
-  - `DEFAULT_ENGINE_CONFIG` → removed (use schema defaults)
-- **BREAKING**: Removed internal mutable type exports
-  - `MutableEngineState`, `MutableOptimizerState`, `MutableRuleStats`
-  - These are internal implementation details
-
-### Fixed
-
-- **Silent Hook Errors**: All 11 hook execution functions now report errors via `onHookError`
-- **Redundant Sorting**: Removed unnecessary sort in `evaluate()` (rules already sorted on add/update)
-
-## [1.0.0] - 2025-12-10
-
-### Added
-
-- Initial release of the rules engine library
-- **Engine**: Stateful rule management with `createEngine()`
-  - Add, update, remove, enable/disable rules
-  - Rule sets for grouping related rules
-  - Configurable caching with TTL and max size
-  - Lifecycle hooks (onBeforeEvaluation, onAfterEvaluation, onRuleMatch, onRuleError, onCacheHit)
-  - Conflict resolution strategies: "all", "first-match", "highest-priority"
-- **Fluent Builders**: Chainable APIs for building rules and conditions
-  - `rule()` builder with full configuration options
-  - Shorthand condition helpers: `num()`, `str()`, `bool()`, `date()`, `arr()`
-  - Logical operators: `all()`, `any()`, `and()`, `or()`
-- **Core Evaluation**: Built on `@f-o-t/condition-evaluator`
-  - `evaluateRule()` and `evaluateRules()` functions
-  - Filter rules by tags, category, enabled status
-  - Sort rules by priority, name, created/updated date
-  - Group rules by category, priority, enabled status, or custom function
-- **Validation**: Comprehensive rule validation
-  - Schema validation with Zod
-  - Conflict detection (duplicate IDs, overlapping conditions, priority collisions, unreachable rules)
-  - Integrity checks (negative priority, missing fields, invalid operators)
-- **Simulation**: Test rules without side effects
-  - `simulate()` for single context testing
-  - `batchSimulate()` for multiple contexts
-  - `whatIf()` for comparing rule set changes
-- **Versioning**: Track rule changes with rollback support
-  - Version store with full history
-  - Rollback to any previous version
-  - Prune old versions
-- **Indexing & Optimization**: Fast rule lookups
-  - Build indexes by field, tag, category, priority
-  - Optimization suggestions for rule sets
-- **Analysis**: Rule set analytics
-  - Complexity analysis per rule
-  - Field, operator, and consequence usage statistics
-  - Find most complex rules
-- **Serialization**: Import/export capabilities
-  - JSON export/import with optional ID regeneration
-  - Clone rules
-  - Merge and diff rule sets
-- **Utilities**: Functional programming helpers
-  - `pipe()`, `compose()`, `identity()`, `always()`, `tap()`
-  - `measureTime()`, `measureTimeAsync()`, `withTimeout()`, `delay()`
-  - `generateId()`, `hashContext()`, `hashRules()`
-
-### Changed
-
-- **Internal refactor**: Removed 12 internal barrel files
-  - All imports now use direct file paths instead of barrel re-exports
-  - No public API changes - only internal module structure improvements

package/__tests__/builder.test.ts

@@ -1,363 +0,0 @@
-import { beforeEach, describe, expect, it } from "bun:test";
-import { z } from "zod";
-import {
-   all,
-   and,
-   any,
-   arr,
-   bool,
-   conditions,
-   date,
-   num,
-   or,
-   resetBuilderIds,
-   str,
-} from "../src/builder/conditions";
-import { createRule, rule } from "../src/builder/rule";
-import type { ConsequenceDefinitions } from "../src/types/consequence";
-
-type TestContext = {
-   age: number;
-   country: string;
-   premium: boolean;
-   score: number;
-};
-
-const TestConsequences = {
-   applyDiscount: z.object({
-      percentage: z.number(),
-      reason: z.string(),
-   }),
-   sendNotification: z.object({
-      type: z.enum(["email", "sms", "push"]),
-      message: z.string(),
-   }),
-   setFlag: z.object({
-      name: z.string(),
-      value: z.boolean(),
-   }),
-} satisfies ConsequenceDefinitions;
-
-type TestConsequences = typeof TestConsequences;
-
-describe("Condition Builder", () => {
-   beforeEach(() => {
-      resetBuilderIds();
-   });
-
-   describe("conditions()", () => {
-      it("should create an empty condition builder", () => {
-         const builder = conditions();
-         expect(builder.getConditions()).toHaveLength(0);
-      });
-
-      it("should chain number conditions", () => {
-         const group = conditions()
-            .number("age", "gte", 18)
-            .number("score", "gt", 100)
-            .build();
-
-         expect(group.operator).toBe("AND");
-         expect(group.conditions).toHaveLength(2);
-      });
-
-      it("should chain string conditions", () => {
-         const group = conditions()
-            .string("country", "eq", "US")
-            .string("status", "in", ["active", "pending"])
-            .build();
-
-         expect(group.conditions).toHaveLength(2);
-      });
-
-      it("should chain boolean conditions", () => {
-         const group = conditions()
-            .boolean("premium", "eq", true)
-            .boolean("verified", "neq", false)
-            .build();
-
-         expect(group.conditions).toHaveLength(2);
-      });
-
-      it("should handle date conditions with Date objects", () => {
-         const now = new Date();
-         const group = conditions().date("createdAt", "gte", now).build();
-
-         expect(group.conditions).toHaveLength(1);
-      });
-
-      it("should handle array conditions", () => {
-         const group = conditions()
-            .array("tags", "contains", "vip")
-            .array("items", "is_not_empty", undefined)
-            .build();
-
-         expect(group.conditions).toHaveLength(2);
-      });
-
-      it("should support nested AND groups", () => {
-         const group = conditions()
-            .number("age", "gte", 18)
-            .and((cb) =>
-               cb.string("country", "eq", "US").boolean("premium", "eq", true),
-            )
-            .build();
-
-         expect(group.conditions).toHaveLength(2);
-         const nestedGroup = group.conditions[1] as { operator: string };
-         expect(nestedGroup.operator).toBe("AND");
-      });
-
-      it("should support nested OR groups", () => {
-         const group = conditions()
-            .number("age", "gte", 18)
-            .or((cb) =>
-               cb.string("country", "eq", "US").string("country", "eq", "CA"),
-            )
-            .build();
-
-         expect(group.conditions).toHaveLength(2);
-         const nestedGroup = group.conditions[1] as { operator: string };
-         expect(nestedGroup.operator).toBe("OR");
-      });
-   });
-
-   describe("and() / or()", () => {
-      it("should create AND group from builder function", () => {
-         const group = and((cb) =>
-            cb.number("age", "gte", 18).string("country", "eq", "US"),
-         );
-
-         expect(group.operator).toBe("AND");
-         expect(group.conditions).toHaveLength(2);
-      });
-
-      it("should create OR group from builder function", () => {
-         const group = or((cb) =>
-            cb.boolean("premium", "eq", true).number("score", "gte", 90),
-         );
-
-         expect(group.operator).toBe("OR");
-         expect(group.conditions).toHaveLength(2);
-      });
-   });
-
-   describe("all() / any()", () => {
-      it("should create AND group from conditions", () => {
-         const group = all(
-            num("age", "gte", 18),
-            str("country", "eq", "US"),
-            bool("premium", "eq", true),
-         );
-
-         expect(group.operator).toBe("AND");
-         expect(group.conditions).toHaveLength(3);
-      });
-
-      it("should create OR group from conditions", () => {
-         const group = any(
-            bool("premium", "eq", true),
-            num("score", "gte", 90),
-         );
-
-         expect(group.operator).toBe("OR");
-         expect(group.conditions).toHaveLength(2);
-      });
-
-      it("should support nested groups", () => {
-         const group = all(
-            num("age", "gte", 18),
-            any(bool("premium", "eq", true), num("score", "gte", 90)),
-         );
-
-         expect(group.operator).toBe("AND");
-         expect(group.conditions).toHaveLength(2);
-         const nestedGroup = group.conditions[1] as { operator: string };
-         expect(nestedGroup.operator).toBe("OR");
-      });
-   });
-
-   describe("condition helpers", () => {
-      it("num() should create number condition", () => {
-         const cond = num("age", "gte", 18);
-         expect(cond.type).toBe("number");
-         expect(cond.field).toBe("age");
-         expect(cond.operator).toBe("gte");
-         expect(cond.value).toBe(18);
-      });
-
-      it("str() should create string condition", () => {
-         const cond = str("country", "eq", "US");
-         expect(cond.type).toBe("string");
-         expect(cond.field).toBe("country");
-         expect(cond.operator).toBe("eq");
-      });
-
-      it("bool() should create boolean condition", () => {
-         const cond = bool("premium", "eq", true);
-         expect(cond.type).toBe("boolean");
-         expect(cond.field).toBe("premium");
-         expect(cond.operator).toBe("eq");
-         expect(cond.value).toBe(true);
-      });
-
-      it("date() should create date condition", () => {
-         const cond = date("createdAt", "gte", "2024-01-01");
-         expect(cond.type).toBe("date");
-         expect(cond.field).toBe("createdAt");
-         expect(cond.operator).toBe("gte");
-      });
-
-      it("arr() should create array condition", () => {
-         const cond = arr("tags", "contains", "vip");
-         expect(cond.type).toBe("array");
-         expect(cond.field).toBe("tags");
-         expect(cond.operator).toBe("contains");
-      });
-   });
-});
-
-describe("Rule Builder", () => {
-   beforeEach(() => {
-      resetBuilderIds();
-   });
-
-   describe("rule()", () => {
-      it("should create a rule builder", () => {
-         const builder = rule<TestContext, TestConsequences>();
-         const state = builder.getState();
-
-         expect(state.consequences).toHaveLength(0);
-         expect(state.priority).toBe(0);
-         expect(state.enabled).toBe(true);
-         expect(state.stopOnMatch).toBe(false);
-         expect(state.tags).toHaveLength(0);
-      });
-
-      it("should build a complete rule", () => {
-         const ruleInput = rule<TestContext, TestConsequences>()
-            .id("rule-1")
-            .named("Adult Discount")
-            .describedAs("Apply discount for adults")
-            .when(all(num("age", "gte", 18)))
-            .then("applyDiscount", { percentage: 10, reason: "Adult discount" })
-            .withPriority(100)
-            .tagged("pricing", "adult")
-            .inCategory("discounts")
-            .build();
-
-         expect(ruleInput.id).toBe("rule-1");
-         expect(ruleInput.name).toBe("Adult Discount");
-         expect(ruleInput.description).toBe("Apply discount for adults");
-         expect(ruleInput.priority).toBe(100);
-         expect(ruleInput.enabled).toBe(true);
-         expect(ruleInput.stopOnMatch).toBe(false);
-         expect(ruleInput.tags).toContain("pricing");
-         expect(ruleInput.tags).toContain("adult");
-         expect(ruleInput.category).toBe("discounts");
-         expect(ruleInput.consequences).toHaveLength(1);
-      });
-
-      it("should support multiple consequences", () => {
-         const ruleInput = rule<TestContext, TestConsequences>()
-            .named("Multi-consequence rule")
-            .when(all(bool("premium", "eq", true)))
-            .then("applyDiscount", { percentage: 20, reason: "VIP" })
-            .then("sendNotification", {
-               type: "email",
-               message: "Discount applied",
-            })
-            .then("setFlag", { name: "vip_treated", value: true })
-            .build();
-
-         expect(ruleInput.consequences).toHaveLength(3);
-      });
-
-      it("should support disabling rules", () => {
-         const ruleInput = rule<TestContext, TestConsequences>()
-            .named("Disabled rule")
-            .when(all())
-            .then("setFlag", { name: "test", value: true })
-            .disabled()
-            .build();
-
-         expect(ruleInput.enabled).toBe(false);
-      });
-
-      it("should support stopOnMatch", () => {
-         const ruleInput = rule<TestContext, TestConsequences>()
-            .named("Stop rule")
-            .when(all())
-            .then("setFlag", { name: "test", value: true })
-            .stopOnMatch()
-            .build();
-
-         expect(ruleInput.stopOnMatch).toBe(true);
-      });
-
-      it("should support metadata", () => {
-         const ruleInput = rule<TestContext, TestConsequences>()
-            .named("Rule with metadata")
-            .when(all())
-            .then("setFlag", { name: "test", value: true })
-            .withMetadata({ author: "admin", version: 1 })
-            .build();
-
-         expect(ruleInput.metadata).toEqual({ author: "admin", version: 1 });
-      });
-
-      it("should throw error if name is missing", () => {
-         expect(() => {
-            rule<TestContext, TestConsequences>()
-               .when(all())
-               .then("setFlag", { name: "test", value: true })
-               .build();
-         }).toThrow("Rule must have a name");
-      });
-
-      it("should throw error if conditions are missing", () => {
-         expect(() => {
-            rule<TestContext, TestConsequences>()
-               .named("Test rule")
-               .then("setFlag", { name: "test", value: true })
-               .build();
-         }).toThrow("Rule must have conditions");
-      });
-
-      it("should throw error if consequences are missing", () => {
-         expect(() => {
-            rule<TestContext, TestConsequences>()
-               .named("Test rule")
-               .when(all())
-               .build();
-         }).toThrow("Rule must have at least one consequence");
-      });
-
-      it("should support builder function in when()", () => {
-         const ruleInput = rule<TestContext, TestConsequences>()
-            .named("Builder condition")
-            .when((cb) =>
-               cb.number("age", "gte", 18).boolean("premium", "eq", true),
-            )
-            .then("setFlag", { name: "test", value: true })
-            .build();
-
-         expect(ruleInput.conditions.operator).toBe("AND");
-         expect(ruleInput.conditions.conditions).toHaveLength(2);
-      });
-   });
-
-   describe("createRule()", () => {
-      it("should create rule using function", () => {
-         const ruleInput = createRule<TestContext, TestConsequences>((rb) =>
-            rb
-               .named("Test rule")
-               .when(all(num("age", "gte", 18)))
-               .then("setFlag", { name: "adult", value: true }),
-         );
-
-         expect(ruleInput.name).toBe("Test rule");
-         expect(ruleInput.consequences).toHaveLength(1);
-      });
-   });
-});

package/__tests__/cache.test.ts

@@ -1,130 +0,0 @@
-import { describe, expect, test } from "bun:test";
-import { createCache } from "../src/cache/cache";
-import { createNoopCache } from "../src/cache/noop";
-
-describe("createCache", () => {
-   test("should store and retrieve values", () => {
-      const cache = createCache<string>({ ttl: 1000, maxSize: 100 });
-
-      cache.set("key1", "value1");
-      expect(cache.get("key1")).toBe("value1");
-   });
-
-   test("should return undefined for missing keys", () => {
-      const cache = createCache<string>({ ttl: 1000, maxSize: 100 });
-
-      expect(cache.get("missing")).toBeUndefined();
-   });
-
-   test("should track hits and misses", () => {
-      const cache = createCache<string>({ ttl: 1000, maxSize: 100 });
-
-      cache.set("key1", "value1");
-      cache.get("key1");
-      cache.get("missing");
-
-      const stats = cache.getStats();
-      expect(stats.hits).toBe(1);
-      expect(stats.misses).toBe(1);
-   });
-
-   test("should expire entries after TTL", async () => {
-      const cache = createCache<string>({ ttl: 50, maxSize: 100 });
-
-      cache.set("key1", "value1");
-      expect(cache.get("key1")).toBe("value1");
-
-      await new Promise((resolve) => setTimeout(resolve, 100));
-
-      expect(cache.get("key1")).toBeUndefined();
-   });
-
-   test("should evict oldest entries when maxSize is reached", () => {
-      const cache = createCache<string>({ ttl: 10000, maxSize: 3 });
-
-      cache.set("key1", "value1");
-      cache.set("key2", "value2");
-      cache.set("key3", "value3");
-      cache.set("key4", "value4");
-
-      expect(cache.get("key1")).toBeUndefined();
-      expect(cache.get("key4")).toBe("value4");
-   });
-
-   test("should calculate hit rate correctly", () => {
-      const cache = createCache<string>({ ttl: 1000, maxSize: 100 });
-
-      cache.set("key1", "value1");
-      cache.get("key1");
-      cache.get("key1");
-      cache.get("missing");
-
-      const stats = cache.getStats();
-      expect(stats.hitRate).toBeCloseTo(0.67, 1);
-   });
-
-   test("should check if key exists", () => {
-      const cache = createCache<string>({ ttl: 1000, maxSize: 100 });
-
-      cache.set("key1", "value1");
-      expect(cache.has("key1")).toBe(true);
-      expect(cache.has("missing")).toBe(false);
-   });
-
-   test("should delete entries", () => {
-      const cache = createCache<string>({ ttl: 1000, maxSize: 100 });
-
-      cache.set("key1", "value1");
-      expect(cache.delete("key1")).toBe(true);
-      expect(cache.get("key1")).toBeUndefined();
-   });
-
-   test("should clear all entries", () => {
-      const cache = createCache<string>({ ttl: 1000, maxSize: 100 });
-
-      cache.set("key1", "value1");
-      cache.set("key2", "value2");
-      cache.clear();
-
-      expect(cache.getStats().size).toBe(0);
-   });
-
-   test("should call onEvict callback", async () => {
-      const evicted: string[] = [];
-      const cache = createCache<string>({
-         ttl: 50,
-         maxSize: 100,
-         onEvict: (key) => evicted.push(key),
-      });
-
-      cache.set("key1", "value1");
-      await new Promise((resolve) => setTimeout(resolve, 100));
-      cache.get("key1");
-
-      expect(evicted).toContain("key1");
-   });
-});
-
-describe("createNoopCache", () => {
-   test("should not store values", () => {
-      const cache = createNoopCache<string>();
-
-      cache.set("key1", "value1");
-      expect(cache.get("key1")).toBeUndefined();
-   });
-
-   test("should always return false for has", () => {
-      const cache = createNoopCache<string>();
-
-      expect(cache.has("key1")).toBe(false);
-   });
-
-   test("should return empty stats", () => {
-      const cache = createNoopCache<string>();
-
-      const stats = cache.getStats();
-      expect(stats.size).toBe(0);
-      expect(stats.hits).toBe(0);
-      expect(stats.misses).toBe(0);
-   });
-});