Add Almanac addFact method

The addFact method is stright from the engine class. It's able
to either add a fact with a name and value / implementation
or add a fact as a fact subclass.

Author: chris-pardy

Diff for: 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)
@@ -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

Diff for: examples/07-rule-chaining.js

@@ -39,16 +39,16 @@ async function start () {
     event: { type: 'drinks-screwdrivers' },
     priority: 10, // IMPORTANT!  Set a higher priority for the drinkRule, so it runs first
     onSuccess: async function (event, almanac) {
-      almanac.addRuntimeFact('screwdriverAficionado', true)
+      almanac.addFact('screwdriverAficionado', true)
 
       // asychronous operations can be performed within callbacks
       // engine execution will not proceed until the returned promises is resolved
       const accountId = await almanac.factValue('accountId')
       const accountInfo = await getAccountInformation(accountId)
-      almanac.addRuntimeFact('accountInfo', accountInfo)
+      almanac.addFact('accountInfo', accountInfo)
     },
     onFailure: function (event, almanac) {
-      almanac.addRuntimeFact('screwdriverAficionado', false)
+      almanac.addFact('screwdriverAficionado', false)
     }
   }
   engine.addRule(drinkRule)

Diff for: src/almanac.js

@@ -103,8 +103,32 @@ export default class Almanac {
     return factValue
   }
 
+  /**
+   * Add a fact definition to the engine.  Facts are called by rules as they are evaluated.
+   * @param {object|Fact} id - fact identifier or instance of Fact
+   * @param {function} definitionFunc - function to be called when computing the fact value for a given rule
+   * @param {Object} options - options to initialize the fact with. used when "id" is not a Fact instance
+   */
+  addFact (id, valueOrMethod, options) {
+    let factId = id
+    let fact
+    if (id instanceof Fact) {
+      factId = id.id
+      fact = id
+    } else {
+      fact = new Fact(id, valueOrMethod, options)
+    }
+    debug(`almanac::addFact id:${factId}`)
+    this.factMap.set(factId, fact)
+    if (fact.isConstant()) {
+      this._setFactValue(fact, {}, fact.value)
+    }
+    return this
+  }
+
   /**
    * Adds a constant fact during runtime.  Can be used mid-run() to add additional information
+   * @deprecated use addFact
    * @param {String} fact - fact identifier
    * @param {Mixed} value - constant value of the fact
    */

Diff for: test/almanac.test.js

@@ -41,6 +41,31 @@ describe('Almanac', () => {
     })
   })
 
+  describe('addFact', () => {
+    it('supports runtime facts as key => values', () => {
+      almanac = new Almanac()
+      almanac.addFact('fact1', 3)
+      return expect(almanac.factValue('fact1')).to.eventually.equal(3)
+    })
+
+    it('supporrts runtime facts as dynamic callbacks', async () => {
+      almanac = new Almanac()
+      almanac.addFact('fact1', () => {
+        factSpy()
+        return Promise.resolve(3)
+      })
+      await expect(almanac.factValue('fact1')).to.eventually.equal(3)
+      await expect(factSpy).to.have.been.calledOnce()
+    })
+
+    it('supports runtime fact instances', () => {
+      const fact = new Fact('fact1', 3)
+      almanac = new Almanac()
+      almanac.addFact(fact)
+      return expect(almanac.factValue('fact1')).to.eventually.equal(fact.value)
+    })
+  })
+
   describe('addEvent() / getEvents()', () => {
     const event = {};
     ['success', 'failure'].forEach(outcome => {

Diff for: types/index.d.ts

@@ -71,6 +71,12 @@ export class Almanac {
     params?: Record<string, any>,
     path?: string
   ): Promise<T>;
+  addFact<T>(fact: Fact<T>): this;
+  addFact<T>(
+    id: string,
+    valueCallback: DynamicFactCallback<T> | T,
+    options?: FactOptions
+  ): this;
   addRuntimeFact(factId: string, value: any): void;
 }