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

package/CHANGELOG.md

@@ -0,0 +1,168 @@
+# 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/LICENSE.md

@@ -1,9 +1,21 @@
 MIT License
 
-Copyright (c) 2025 FOT
+Copyright (c) 2026 FOT (F-O-T)
 
-Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
 
-The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
 
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -23,35 +23,65 @@ bun add @f-o-t/rules-engine
 ## Quick Start
 
 ```typescript
-import { createEngine, rule, all, num, str } from "@f-o-t/rules-engine";
+import { createEngine, createEvaluator } from "@f-o-t/rules-engine";
+import { z } from "zod";
 
-// Create an engine
-const engine = createEngine();
+// Define your consequence types
+const MyConsequences = {
+  send_email: z.object({
+    to: z.string().email(),
+    subject: z.string(),
+  }),
+  apply_discount: z.object({
+    percentage: z.number(),
+  }),
+};
+
+// Create engine with built-in operators
+const engine = createEngine({
+  consequences: MyConsequences,
+  evaluator: createEvaluator(), // Required!
+});
 
-// Add rules using the fluent builder
-engine.addRule(
-   rule()
-      .named("Premium Discount")
-      .when(
-         all(
-            num("orderTotal", "gt", 100),
-            str("customerType", "eq", "premium")
-         )
-      )
-      .then("apply_discount", { percentage: 15 })
-      .withPriority(100)
-      .tagged("pricing", "discount")
-      .build()
-);
+// Or with custom operators
+import { moneyOperators } from "@f-o-t/money/operators";
+
+const engine = createEngine({
+  consequences: MyConsequences,
+  operators: moneyOperators, // Convenience: engine creates evaluator
+});
 
-// Evaluate against context
+// Add rules
+engine.addRule({
+  name: "high-value-customer",
+  conditions: {
+    id: "g1",
+    operator: "AND",
+    conditions: [
+      {
+        id: "c1",
+        type: "number",
+        field: "totalPurchases",
+        operator: "gt",
+        value: 1000,
+      },
+    ],
+  },
+  consequences: [
+    {
+      type: "apply_discount",
+      payload: { percentage: 10 },
+    },
+  ],
+});
+
+// Evaluate
 const result = await engine.evaluate({
-   orderTotal: 150,
-   customerType: "premium",
+  totalPurchases: 1500,
 });
 
-console.log(result.matchedRules);    // Rules that matched
-console.log(result.consequences);    // Actions to execute
+console.log(result.matchedRules); // Rules that matched
+console.log(result.consequences); // Actions to take
 ```
 
 ## Building Conditions
@@ -125,6 +155,59 @@ const myRule = rule()
    .build();
 ```
 
+## Custom Operators
+
+Use custom operators from libraries like `@f-o-t/money`:
+
+```typescript
+import { createEngine } from "@f-o-t/rules-engine";
+import { moneyOperators } from "@f-o-t/money/operators";
+
+const engine = createEngine({
+  operators: moneyOperators,
+});
+
+engine.addRule({
+  name: "large-transaction",
+  conditions: {
+    id: "g1",
+    operator: "AND",
+    conditions: [
+      {
+        id: "c1",
+        type: "custom",
+        field: "amount",
+        operator: "money_gt",
+        value: { amount: "5000.00", currency: "BRL" },
+      },
+    ],
+  },
+  consequences: [
+    { type: "flag_for_review", payload: {} },
+  ],
+});
+```
+
+Create your own custom operators:
+
+```typescript
+import { createEngine, createOperator } from "@f-o-t/rules-engine";
+
+const customOperator = createOperator({
+  name: "is_valid_cpf",
+  type: "custom",
+  description: "Validate Brazilian CPF",
+  evaluate: (actual, expected) => {
+    // Your validation logic
+    return validateCPF(actual as string);
+  },
+});
+
+const engine = createEngine({
+  operators: { is_valid_cpf: customOperator },
+});
+```
+
 ## Engine API
 
 ### Rule Management