Ability to run Tasks.js and Targets.js code without Nools (medic#8065)

This is a proposed change which allows CHT Application code to run without the Nools library.

- This provides a workaround for medic#6506 and medic/cht-conf#225
- Step in the direction of medic#5906. When ready we can remove the nools.emitter
- Probable minor performance gains since nools is a weird box of mysteries. May improve medic#5515 if that issue is correct about Nools holding target instances in memory.

Author: kennsippell

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "medic",
-  "version": "4.1.0",
+  "version": "4.2.0",
   "private": true,
   "license": "AGPL-3.0-only",
   "repository": {

package.json

@@ -22,6 +22,9 @@ module.exports = db => {
      * @param {Object[]} settings.targets Target definitions from settings doc
      * @param {Boolean} settings.enableTasks Flag to enable tasks
      * @param {Boolean} settings.enableTargets Flag to enable targets
+     * @param {Boolean} [settings.rulesAreDeclarative=false] Flag to indicate the content of settings.rules. When true, 
+     * rules is processed as native JavaScript. When false, nools is used.
+     * @param {RulesEmitter} [settings.customEmitter] Optional custom RulesEmitter object
      * @param {Object} settings.contact User's hydrated contact document
      * @param {Object} settings.user User's settings document
      */
@@ -79,6 +82,9 @@ module.exports = db => {
      * @param {Object[]} settings.targets Target definitions from settings doc
      * @param {Boolean} settings.enableTasks Flag to enable tasks
      * @param {Boolean} settings.enableTargets Flag to enable targets
+     * @param {Boolean} [settings.rulesAreDeclarative=false] Flag to indicate the content of settings.rules. When true, 
+     * rules is native JavaScript. When false, nools is used
+     * @param {RulesEmitter} [settings.customEmitter] Optional custom RulesEmitter object
      * @param {Object} settings.contact User's hydrated contact document
      * @param {Object} settings.user User's user-settings document
      */

shared-libs/rules-engine/src/index.js

@@ -25,6 +25,9 @@ module.exports = {
    * @param {Object[]} settings.targets Target definitions from settings doc
    * @param {Boolean} settings.enableTasks Flag to enable tasks
    * @param {Boolean} settings.enableTargets Flag to enable targets
+   * @param {Boolean} [settings.rulesAreDeclarative=true] Flag to indicate the content of settings.rules. When true,
+   * rules is processed as native JavaScript. When false, nools is used.
+   * @param {RulesEmitter} [settings.customEmitter] Optional custom RulesEmitter object
    * @param {number} settings.monthStartDate reporting interval start date
    * @param {Object} userDoc User's hydrated contact document
    */

shared-libs/rules-engine/src/provider-wireup.js

@@ -0,0 +1,76 @@
+/**
+ * @module emitter.javascript
+ * Processes declarative configuration code by executing javascript rules directly
+ */
+
+class Contact {
+  constructor({ contact, reports, tasks}) {
+    this.contact = contact;
+    this.reports = reports;
+    this.tasks = tasks;
+  }
+}
+
+// required by marshalDocsByContact
+Contact.prototype.tasks = 'defined';
+
+class Task {
+  constructor(x) {
+    Object.assign(this, x);
+  }
+}
+
+class Target {
+  constructor(x) {
+    Object.assign(this, x);
+  }
+}
+
+let processDocsByContact;
+const results = { tasks: [], targets: [] };
+
+module.exports = {
+  getContact: () => Contact,
+  initialize: (settings, scope) => {
+    const rawFunction = new Function('c', 'Task', 'Target', 'Utils', 'user', 'cht', 'emit', settings.rules);
+    processDocsByContact = container => rawFunction(
+      container,
+      Task,
+      Target,
+      scope.Utils,
+      scope.user,
+      scope.cht,
+      emitCallback,
+    );
+    return true;
+  },
+
+  startSession: () => {
+    if (!processDocsByContact) {
+      throw Error('Failed to start task session. Not initialized');
+    }
+
+    results.tasks = [];
+    results.targets = [];
+    
+    return {
+      processDocsByContact,
+      result: () => Promise.resolve(results),
+      dispose: () => {},
+    };
+  },
+
+  isLatestNoolsSchema: () => true,
+
+  shutdown: () => {
+    processDocsByContact = undefined;
+  },
+};
+
+const emitCallback = (instanceType, instance) => {
+  if (instanceType === 'task') {
+    results.tasks.push(instance);
+  } else if (instanceType === 'target') {
+    results.targets.push(instance);
+  }
+};

shared-libs/rules-engine/src/rules-emitter/emitter.javascript.js

@@ -0,0 +1,82 @@
+/**
+ * @module emitter.nools
+ * Encapsulates interactions with the nools library
+ * Promisifies the execution of partner "rules" code
+ * Ensures memory allocated by nools is freed after each run
+ */
+const nools = require('nools');
+
+let flow;
+
+const startSession = function() {
+  if (!flow) {
+    throw Error('Failed to start task session. Not initialized');
+  }
+
+  const session = flow.getSession();
+  const tasks = [];
+  const targets = [];
+  session.on('task', task => tasks.push(task));
+  session.on('target', target => targets.push(target));
+
+  return {
+    assert: session.assert.bind(session),
+    dispose: session.dispose.bind(session),
+
+    // session.match can return a thenable but not a promise. so wrap it in a real promise
+    match: () => new Promise((resolve, reject) => {
+      session.match(err => {
+        session.dispose();
+        if (err) {
+          return reject(err);
+        }
+
+        resolve({ tasks, targets });
+      });
+    }),
+  };
+};
+
+module.exports = {
+  getContact: () => flow.getDefined('contact'),
+  initialize: (settings, scope) => {
+    flow = nools.compile(settings.rules, {
+      name: 'medic',
+      scope,
+    });
+
+    return !!flow;
+  },
+  startSession: () => {
+    const session = startSession();
+    return {
+      processDocsByContact: session.assert,
+      dispose: session.dispose,
+      result: session.match,
+    };
+  },
+
+  /**
+   * When upgrading to version 3.8, partners are required to make schema changes in their partner code
+   * https://docs.communityhealthtoolkit.org/core/releases/3.8.0/#breaking-changes
+   *
+   * @returns True if the schema changes are in place
+   */
+  isLatestNoolsSchema: () => {
+    if (!flow) {
+      throw Error('task emitter is not enabled -- cannot determine schema version');
+    }
+
+    const Task = flow.getDefined('task');
+    const Target = flow.getDefined('target');
+    const hasProperty = (obj, attr) => Object.hasOwnProperty.call(obj, attr);
+    return hasProperty(Task.prototype, 'readyStart') &&
+      hasProperty(Task.prototype, 'readyEnd') &&
+      hasProperty(Target.prototype, 'contact');
+  },
+
+  shutdown: () => {
+    nools.deleteFlows();
+    flow = undefined;
+  },
+};