[DO NOT MERGE] Sync upstream 20250522

docs/almanac.md

@@ -3,6 +3,7 @@
 * [Overview](#overview)
 * [Methods](#methods)
     * [almanac.factValue(Fact fact, Object params, String path) -> Promise](#almanacfactvaluefact-fact-object-params-string-path---promise)
+    * [almanac.addFact(String id, Function [definitionFunc], Object [options])](#almanacaddfactstring-id-function-definitionfunc-object-options)
     * [almanac.addRuntimeFact(String factId, Mixed value)](#almanacaddruntimefactstring-factid-mixed-value)
     * [almanac.getEvents(String outcome) -> Events[]](#almanacgeteventsstring-outcome---events)
     * [almanac.getResults() -> RuleResults[]](#almanacgetresults---ruleresults)
@@ -14,8 +15,8 @@
 ## Overview
 
 An almanac collects facts through an engine run cycle.  As the engine computes fact values,
-the results are stored in the almanac and cache'd.  If the engine detects a fact computation has
-been previously computed, it re-uses the cache'd result from the almanac.  Every time ```engine.run()``` is invoked,
+the results are stored in the almanac and cached.  If the engine detects a fact computation has
+been previously computed, it reuses the cached result from the almanac.  Every time ```engine.run()``` is invoked,
 a new almanac is instantiated.
 
 The almanac for the current engine run is available as arguments passed to the fact evaluation methods and
@@ -33,8 +34,28 @@ almanac
   .then( value => console.log(value))
 ```
 
+### almanac.addFact(String id, Function [definitionFunc], Object [options])
+
+Sets a fact in the almanac. Used in conjunction with rule and engine event emissions.
+
+```js
+// constant facts:
+engine.addFact('speed-of-light', 299792458)
+
+// facts computed via function
+engine.addFact('account-type', function getAccountType(params, almanac) {
+  // ...
+})
+
+// facts with options:
+engine.addFact('account-type', function getAccountType(params, almanac) {
+  // ...
+}, { cache: false, priority: 500 })
+```
+
 ### almanac.addRuntimeFact(String factId, Mixed value)
 
+**Deprecated** Use `almanac.addFact` instead
 Sets a constant fact mid-run.  Often used in conjunction with rule and engine event emissions.
 
 ```js

docs/engine.md

@@ -12,6 +12,10 @@ The Engine stores and executes rules, emits events, and maintains state.
     * [engine.removeRule(Rule instance | String ruleId)](#engineremoverulerule-instance)
     * [engine.addOperator(String operatorName, Function evaluateFunc(factValue, jsonValue))](#engineaddoperatorstring-operatorname-function-evaluatefuncfactvalue-jsonvalue)
     * [engine.removeOperator(String operatorName)](#engineremoveoperatorstring-operatorname)
+    * [engine.addOperatorDecorator(String decoratorName, Function evaluateFunc(factValue, jsonValue, next))](#engineaddoperatordecoratorstring-decoratorname-function-evaluatefuncfactvalue-jsonvalue-next)
+    * [engine.removeOperatorDecorator(String decoratorName)](#engineremoveoperatordecoratorstring-decoratorname)
+    * [engine.setCondition(String name, Object conditions)](#enginesetconditionstring-name-object-conditions)
+    * [engine.removeCondition(String name)](#engineremovecondtionstring-name)
     * [engine.run([Object facts], [Object options]) -> Promise ({ events: [], failureEvents: [], almanac: Almanac, results: [], failureResults: []})](#enginerunobject-facts-object-options---promise--events--failureevents--almanac-almanac-results--failureresults-)
     * [engine.stop() -> Engine](#enginestop---engine)
       * [engine.on('success', Function(Object event, Almanac almanac, RuleResult ruleResult))](#engineonsuccess-functionobject-event-almanac-almanac-ruleresult-ruleresult)
@@ -43,6 +47,13 @@ let engine = new Engine([Array rules], options)
 an exception is thrown.  Turning this option on will cause the engine to treat
 undefined facts as `undefined`.  (default: false)
 
+`allowUndefinedConditions` - By default, when a running engine encounters a
+condition reference that cannot be resolved an exception is thrown. Turning
+this option on will cause the engine to treat unresolvable condition references
+as failed conditions. (default: false)
+
+`replaceFactsInEventParams` - By default when rules succeed or fail the events emitted are clones of the event in the rule declaration. When setting this option to true the parameters on the events will be have any fact references resolved. (default: false)
+
 `pathResolver` - Allows a custom object path resolution library to be used. (default: `json-path` syntax). See [custom path resolver](./rules.md#condition-helpers-custom-path-resolver) docs.
 
 ### engine.addFact(String id, Function [definitionFunc], Object [options])
@@ -172,6 +183,127 @@ engine.addOperator('startsWithLetter', (factValue, jsonValue) => {
 engine.removeOperator('startsWithLetter');
 ```
 
+### engine.addOperatorDecorator(String decoratorName, Function evaluateFunc(factValue, jsonValue, next))
+
+Adds a custom operator decorator to the engine.
+
+```js
+/*
+ * decoratorName - operator decorator identifier used in the rule condition
+ * evaluateFunc(factValue, jsonValue, next) - uses the decorated operator to compare the fact result to the condition 'value'
+ *    factValue - the value returned from the fact
+ *    jsonValue - the "value" property stored in the condition itself
+ *    next - the evaluateFunc of the decorated operator
+ */
+engine.addOperatorDecorator('first', (factValue, jsonValue, next) => {
+  if (!factValue.length) return false
+  return next(factValue[0], jsonValue)
+})
+
+engine.addOperatorDecorator('caseInsensitive', (factValue, jsonValue, next) => {
+  return next(factValue.toLowerCase(), jsonValue.toLowerCase())
+})
+
+// and to use the decorator...
+let rule = new Rule(
+  conditions: {
+    all: [
+      {
+        fact: 'username',
+        operator: 'first:caseInsensitive:equal', // reference the decorator:operator in the rule
+        value: 'a'
+      }
+    ]
+  }
+)
+```
+
+See the [operator decorator example](../examples/13-using-operator-decorators.js)
+
+
+
+### engine.removeOperatorDecorator(String decoratorName)
+
+Removes a operator decorator from the engine
+
+```javascript
+engine.addOperatorDecorator('first', (factValue, jsonValue, next) => {
+  if (!factValue.length) return false
+  return next(factValue[0], jsonValue)
+})
+
+engine.addOperatorDecorator('caseInsensitive', (factValue, jsonValue, next) => {
+  return next(factValue.toLowerCase(), jsonValue.toLowerCase())
+})
+
+engine.removeOperatorDecorator('first');
+```
+
+### engine.setCondition(String name, Object conditions)
+
+Adds or updates a condition to the engine. Rules may include references to this condition. Conditions must start with `all`, `any`, `not`, or reference a condition.
+
+```javascript
+engine.setCondition('validLogin', {
+  all: [
+    {
+      operator: 'notEqual',
+      fact: 'loginToken',
+      value: null
+    },
+    {
+      operator: 'greaterThan',
+      fact: 'loginToken',
+      path: '$.expirationTime',
+      value: { fact: 'now' }
+    }
+  ]
+});
+
+engine.addRule({
+  condtions: {
+    all: [
+      {
+        condition: 'validLogin'
+      },
+      {
+        operator: 'contains',
+        fact: 'loginToken',
+        path: '$.role',
+        value: 'admin'
+      }
+    ]
+  },
+  event: {
+    type: 'AdminAccessAllowed'
+  }
+})
+
+```
+
+### engine.removeCondition(String name)
+
+Removes the condition that was previously added.
+
+```javascript
+engine.setCondition('validLogin', {
+  all: [
+    {
+      operator: 'notEqual',
+      fact: 'loginToken',
+      value: null
+    },
+    {
+      operator: 'greaterThan',
+      fact: 'loginToken',
+      path: '$.expirationTime',
+      value: { fact: 'now' }
+    }
+  ]
+});
+
+engine.removeCondition('validLogin');
+```
 
 
 ### engine.run([Object facts], [Object options]) -> Promise ({ events: [], failureEvents: [], almanac: Almanac, results: [], failureResults: []})
@@ -195,6 +327,16 @@ const {
 ```
 Link to the [Almanac documentation](./almanac.md)
 
+Optionally, you may specify a specific almanac instance via the almanac property.
+
+```js
+// create a custom Almanac
+const myCustomAlmanac = new CustomAlmanac();
+
+// run the engine with the custom almanac
+await engine.run({}, { almanac: myCustomAlmanac })
+```
+
 ### engine.stop() -> Engine
 
 Stops the rules engine from running the next priority set of Rules.  All remaining rules will be resolved as undefined,

docs/rules.md

@@ -14,7 +14,8 @@ Rules contain a set of _conditions_ and a single _event_.  When the engine is ru
     * [toJSON(Boolean stringify = true)](#tojsonboolean-stringify--true)
 * [Conditions](#conditions)
     * [Basic conditions](#basic-conditions)
-    * [Boolean expressions: all and any](#boolean-expressions-all-and-any)
+    * [Boolean expressions: all, any, and not](#boolean-expressions-all-any-and-not)
+    * [Condition Reference](#condition-reference)
     * [Condition helpers: params](#condition-helpers-params)
     * [Condition helpers: path](#condition-helpers-path)
     * [Condition helpers: custom path resolver](#condition-helpers-custom-path-resolver)
@@ -26,6 +27,11 @@ Rules contain a set of _conditions_ and a single _event_.  When the engine is ru
     * [String and Numeric operators:](#string-and-numeric-operators)
     * [Numeric operators:](#numeric-operators)
     * [Array operators:](#array-operators)
+* [Operator Decorators](#operator-decorators)
+    * [Array decorators:](#array-decorators)
+    * [Logical decorators:](#logical-decorators)
+    * [Utility decorators:](#utility-decorators)
+    * [Decorator composition:](#decorator-composition)
 * [Rule Results](#rule-results)
 * [Persisting](#persisting)
 
@@ -134,9 +140,9 @@ let rule = new Rule({
 
 See the [hello-world](../examples/01-hello-world.js) example.
 
-### Boolean expressions: `all` and `any`
+### Boolean expressions: `all`, `any`, and `not`
 
-Each rule's conditions *must* have either an `all` or an `any` operator at its root, containing an array of conditions.  The `all` operator specifies that all conditions contained within must be truthy for the rule to be considered a `success`.  The `any` operator only requires one condition to be truthy for the rule to succeed.
+Each rule's conditions *must* have an `all` or `any` operator containing an array of conditions at its root, a `not` operator containing a single condition, or a condition reference. The `all` operator specifies that all conditions contained within must be truthy for the rule to be considered a `success`.  The `any` operator only requires one condition to be truthy for the rule to succeed. The `not` operator will negate whatever condition it contains.
 
 ```js
 // all:
@@ -158,14 +164,46 @@ let rule = new Rule({
       { /* condition 2 */ },
       { /* condition n */ },
       {
-        all: [ /* more conditions */ ]
+        not: {
+          all: [ /* more conditions */ ]
+        }
       }
     ]
   }
 })
+
+// not:
+let rule = new Rule({
+  conditions: {
+    not: { /* condition */ }
+  }
+})
 ```
 
-Notice in the second example how `all` and `any` can be nested within one another to produce complex boolean expressions.  See the [nested-boolean-logic](../examples/02-nested-boolean-logic.js) example.
+Notice in the second example how `all`, `any`, and `not` can be nested within one another to produce complex boolean expressions.  See the [nested-boolean-logic](../examples/02-nested-boolean-logic.js) example.
+
+### Condition Reference
+
+Rules may reference conditions based on their name.
+
+```js
+let rule = new Rule({
+  conditions: {
+    all: [
+      { condition: 'conditionName' },
+      { /* additional condition */ }
+    ]
+  }
+})
+```
+
+Before running the rule the condition should be added to the engine.
+
+```js
+engine.setCondition('conditionName', { /* conditions */ });
+```
+
+Conditions must start with `all`, `any`, `not`, or reference a condition.
 
 ### Condition helpers: `params`
 
@@ -316,9 +354,32 @@ engine.on('failure', function(event, almanac, ruleResult) {
 })
 ```
 
+### Referencing Facts In Events
+
+With the engine option [`replaceFactsInEventParams`](./engine.md#options) the parameters of the event may include references to facts in the same form as [Comparing Facts](#comparing-facts). These references will be replaced with the value of the fact before the event is emitted.
+
+```js
+const engine = new Engine([], { replaceFactsInEventParams: true });
+engine.addRule({
+    conditions: { /* ... */ },
+    event: {
+      type: "gameover",
+      params: {
+        initials: {
+          fact: "currentHighScore",
+          path: "$.initials",
+          params: { foo: 'bar' }
+        }
+      }
+    }
+  })
+```
+
+See [11-using-facts-in-events.js](../examples/11-using-facts-in-events.js) for a complete example.
+
 ## Operators
 
-Each rule condition must begin with a boolean operator(```all``` or ```any```) at its root.
+Each rule condition must begin with a boolean operator(```all```, ```any```, or ```not```) at its root.
 
 The ```operator``` compares the value returned by the ```fact``` to what is stored in the ```value``` property.  If the result is truthy, the condition passes.
 
@@ -350,6 +411,35 @@ The ```operator``` compares the value returned by the ```fact``` to what is stor
 
   ```doesNotContain```  - _fact_ (an array) must not include _value_
 
+## Operator Decorators
+
+Operator Decorators modify the behavior of an operator either by changing the input or the output. To specify one or more decorators prefix the name of the operator with them in the ```operator``` field and use the colon (```:```) symbol to separate decorators and the operator. For instance ```everyFact:greaterThan``` will produce an operator that checks that every element of the _fact_ is greater than the value.
+
+See [12-using-operator-decorators.js](../examples/13-using-operator-decorators.js) for an example.
+
+### Array Decorators:
+
+  ```everyFact``` - _fact_ (an array) must have every element pass the decorated operator for _value_
+
+  ```everyValue``` - _fact_ must pass the decorated operator for every element of _value_ (an array)
+
+  ```someFact``` - _fact_ (an array) must have at-least one element pass the decorated operator for _value_
+
+  ```someValue``` - _fact_ must pass the decorated operator for at-least one element of _value_ (an array)
+
+### Logical Decorators
+
+  ```not``` - negate the result of the decorated operator
+
+### Utility Decorators
+  ```swap``` - Swap _fact_ and _value_ for the decorated operator
+
+### Decorator Composition
+
+Operator Decorators can be composed by chaining them together with the colon to separate them. For example if you wanted to ensure that every number in an array was less than every number in another array you could use ```everyFact:everyValue:lessThan```.
+
+```swap``` and ```not``` are useful when there are not symmetric or negated versions of custom operators, for instance you could check if a _value_ does not start with a letter contained in a _fact_ using the decorated custom operator ```swap:not:startsWithLetter```. This allows a single custom operator to have 4 permutations.
+
 ## Rule Results
 
 After a rule is evaluated, a `rule result` object is provided to the `success` and `failure` events.  This argument is similar to a regular rule, and contains additional metadata about how the rule was evaluated.  Rule results can be used to extract the results of individual conditions, computed fact values, and boolean logic results.  `name` can be used to easily identify a given rule.

examples/02-nested-boolean-logic.js

@@ -31,17 +31,21 @@ async function start () {
           fact: 'personalFoulCount',
           operator: 'greaterThanInclusive',
           value: 5
-        }]
+        }],
+        name: 'short foul limit'
       }, {
         all: [{
           fact: 'gameDuration',
           operator: 'equal',
           value: 48
         }, {
-          fact: 'personalFoulCount',
-          operator: 'greaterThanInclusive',
-          value: 6
-        }]
+          not: {
+            fact: 'personalFoulCount',
+            operator: 'lessThan',
+            value: 6
+          }
+        }],
+        name: 'long foul limit'
       }]
     },
     event: { // define the event to fire when the conditions evaluate truthy