@xeplr/workflow-engine 3.0.3 → 3.2.0

package/README.md

@@ -105,6 +105,18 @@ host gives workflow is the boundary.
   first match wins (`@xeplr/expression-handler`); a blank condition is the
   catch-all; targets are a `stepKey`, `end_success` or `end_failed`. No match
   and no catch-all **fails the run**.
+- **Screens hand over to screens**: a flow's run view carries `previous` — what
+  every screen submitted earlier in the run, keyed by screen key, the saved row
+  as `values.id` (`lib/flows.js` `previousOf`). Read-only, built from the step
+  runs; nothing new is stored, and nothing is checked between screens.
+- **Letting a function decide**: a transition `{ decide: 'routeByAmount', targets?: [...] }`
+  asks a function the app registered with `@xeplr/actions` under `event: 'decide'`
+  where to go. It is called with `{ output, values (= output), params, item, trigger,
+  step, runId, targets }` and returns a step key, `end_success` or `end_failed`;
+  `targets`, when listed, are the steps it may choose (none: any step). A missing
+  function, one written for another event, no answer, or an answer outside
+  `targets` **fails the run**, naming the function. Functions registered with an
+  `event` are screen functions, never steps: the action catalog leaves them out.
 - **Fan-out**: a matching `each` transition creates one child run per matching
   element (`item`), recorded in `workflow_run_edges`. With `joinStep` the parent
   waits and resumes at the join once all children are terminal (guarded by an

package/lib/actionCatalog.js

@@ -173,7 +173,10 @@ function catalog() {
     // absent here, so no palette ever draws it. Filtered at the point the list
     // leaves the process rather than by not registering it — the two questions
     // ("can this run" and "should anyone pick it") have different answers.
-    return HIDDEN_NAMES.indexOf(a.name) === -1;
+    // A SCREEN FUNCTION (registered with an `event`: beforeSave, decide, …) is
+    // not a step — a screen's events and a flow's arrows pick it by name. A
+    // palette offering it as a step would run it with the wrong context.
+    return HIDDEN_NAMES.indexOf(a.name) === -1 && !a.event;
   }).map(function(a) {
     return {
       name: a.name,

package/lib/flows.js

@@ -72,6 +72,9 @@ var FIELD_PATTERN = /^[A-Za-z0-9_][A-Za-z0-9_.-]*$/;
 // key. Restated here because they are part of this facade's contract too.
 var END_TARGETS = ['end_success', 'end_failed'];
 
+// A registered function's name — the same rule @xeplr/ui-factory's FUNCTION_NAME applies.
+var FUNCTION_NAME = /^[A-Za-z_][\w.-]{0,99}$/;
+
 // Which run statuses mean "still going". `queued` is only ever a fanned-out
 // child's starting state, and a screens flow does not fan out — it is in the
 // list because the column has it, not because a flow reaches it.
@@ -298,6 +301,9 @@ function stepView(step) {
     screen: values.screen || null,
     layout: step.layout || null,
     transitions: (step.transitions || []).map(function(t) {
+      // A function deciding is said as itself: its name, and the steps it may
+      // choose from (none listed: any step of the flow).
+      if (t.decide) return { when: conditionToWhen(t.condition), decide: t.decide, targets: t.targets || [] };
       return { when: conditionToWhen(t.condition), target: t.target };
     })
   };
@@ -408,8 +414,26 @@ function toStepRows(workflowId, steps) {
       if (!t || typeof t !== 'object' || Array.isArray(t)) {
         throw fail(400, 'FLOW_INVALID', label + ': must be an object.');
       }
+      // LET A FUNCTION DECIDE: `decide` names a registered function (event
+      // 'decide') that returns the next step; `targets`, optional, are the
+      // steps it may choose from. Its own arrow has no single target.
+      if (t.decide !== undefined && t.decide !== null && t.decide !== '') {
+        var fn = String(t.decide).trim();
+        if (!FUNCTION_NAME.test(fn)) throw fail(400, 'FLOW_INVALID', label + ': `decide` must be the name of a registered function, e.g. "routeByAmount".');
+        var targets = t.targets === undefined || t.targets === null ? [] : t.targets;
+        if (!Array.isArray(targets) || !targets.every(function(x) { return typeof x === 'string' && x.trim(); })) {
+          throw fail(400, 'FLOW_INVALID', label + ': `targets` must be a list of step keys the function may choose from.');
+        }
+        return {
+          condition: whenToCondition(t.when, label),
+          mode: 'single',
+          decide: fn,
+          targets: targets.map(function(x) { return x.trim(); }),
+          target: null
+        };
+      }
       var target = String(t.target == null ? '' : t.target).trim();
-      if (!target) throw fail(400, 'FLOW_INVALID', label + ': `target` is required.');
+      if (!target) throw fail(400, 'FLOW_INVALID', label + ': `target` is required — or `decide`, to let a function choose.');
       return {
         condition: whenToCondition(t.when, label),
         // Single, always. `each` fans a transition out into one child run per
@@ -447,6 +471,11 @@ function toStepRows(workflowId, steps) {
 
 // ── what publishing checks ──────────────────────────────────────────────
 
+/** A function in the app's registry (@xeplr/actions), or null. */
+function registered(name) {
+  return require('@xeplr/actions').get(name) || null;
+}
+
 /**
  * Everything that must be true before a flow can be run, as a list of
  * { stepKey, message } — all of them, not the first one. A designer fixing a
@@ -493,6 +522,14 @@ function validateFlow(steps) {
       if (t.target && END_TARGETS.indexOf(t.target) === -1 && !byKey[t.target]) {
         problem(step.stepKey, 'Transition ' + (ti + 1) + ' goes to "' + t.target + '", which is not a step of this flow.');
       }
+      if (t.decide) {
+        var def = registered(t.decide);
+        if (!def) problem(step.stepKey, 'Transition ' + (ti + 1) + ' lets "' + t.decide + '" decide, but no function of that name is registered.');
+        else if (def.event !== 'decide') problem(step.stepKey, 'Transition ' + (ti + 1) + ' lets "' + t.decide + '" decide, but it is written for ' + (def.event ? '"' + def.event + '"' : 'a workflow step') + ', not "decide".');
+        (t.targets || []).forEach(function(x) {
+          if (END_TARGETS.indexOf(x) === -1 && !byKey[x]) problem(step.stepKey, 'Transition ' + (ti + 1) + ': "' + t.decide + '" may choose "' + x + '", which is not a step of this flow.');
+        });
+      }
     });
     if (catchAlls > 1) {
       problem(step.stepKey, 'This step has ' + catchAlls + ' catch-alls; only the first could ever match.');
@@ -511,6 +548,8 @@ function validateFlow(steps) {
     reachable[key] = true;
     (byKey[key].transitions || []).forEach(function(t) {
       if (t.target && END_TARGETS.indexOf(t.target) === -1) queue.push(t.target);
+      // A function may lead to any step it may choose — all of them, when it lists none.
+      if (t.decide) (t.targets && t.targets.length ? t.targets : Object.keys(byKey)).forEach(function(x) { if (END_TARGETS.indexOf(x) === -1) queue.push(x); });
     });
   }
   steps.forEach(function(step) {
@@ -558,7 +597,9 @@ function runView(run, steps, stepRuns) {
     // the resolved input is kept (workflowRunner patches `input` as it parks)
     // — the step row holds the tokens, and a browser has nothing to resolve
     // them with.
-    given: {}
+    given: {},
+    // WHAT THE SCREENS BEFORE THIS ONE SAVED, by screen key — see previousOf.
+    previous: {}
   };
   if (!waiting) {
     if (run.status === 'failed' && run.error) view.error = run.error;
@@ -575,9 +616,43 @@ function runView(run, steps, stepRuns) {
     if (sr.stepKey !== waiting.stepKey) return;
     Object.assign(view.values, sr.output || {});
   });
+  view.previous = previousOf(steps, stepRuns, waiting);
   return view;
 }
 
+/**
+ * THE HAND-OVER BETWEEN SCREENS — what every screen submitted earlier in this
+ * run, keyed by the SCREEN's key:
+ *
+ *   { department_edit: { values: { id: "6f2a…", name: "Finance", … } } }
+ *
+ * A field on the next screen fills itself from it with a default of
+ * `{previous.department_edit.values.name}` (@xeplr/ui-factory). By screen and
+ * not by step, because the binding lives ON the screen, and a screen is the
+ * same form in every flow that shows it. `id` is the row that screen saved —
+ * part of the values, as it is of the row.
+ *
+ * Nothing is checked: a screen not reached on this run's branch is simply
+ * absent, and a binding to it comes out empty. A screen shown twice (a loop)
+ * hands over its latest. The step being shown now is not its own "previous".
+ */
+function previousOf(steps, stepRuns, waiting) {
+  var screenOf = {};
+  steps.forEach(function(st) {
+    if (st.actionName === SCREEN_ACTION && st.values && st.values.screen) screenOf[st.stepKey] = st.values.screen;
+  });
+  var out = {};
+  stepRuns.forEach(function(sr) {
+    if (sr.status !== 'success' || (waiting && sr.id === waiting.id)) return;
+    var screen = screenOf[sr.stepKey];
+    if (!screen) return;
+    var values = Object.assign({}, sr.output || {});
+    if (values.recordId !== undefined) { values.id = values.recordId; delete values.recordId; }
+    out[screen] = { values: values };
+  });
+  return out;
+}
+
 async function stepRunsOf(runId) {
   return db.model('WorkflowStepRun').query().where({ runId: runId }).orderBy('recordCreatedDate', 'asc');
 }
@@ -898,6 +973,7 @@ module.exports = {
   fail: fail,
   END_TARGETS: END_TARGETS,
   conditionToWhen: conditionToWhen,
+  previousOf: previousOf,
   toStepRows: toStepRows,
   validateFlow: validateFlow,
   runView: runView,

package/lib/workflowRunner.js

@@ -27,7 +27,8 @@
 var crypto = require('crypto');
 var { generateId } = require('@xeplr/utils/lib/helpers');
 var { runWithMt } = require('@xeplr/db');
-var { runAction } = require('@xeplr/actions');
+var actions = require('@xeplr/actions');
+var { runAction } = actions;
 var { interpolateAll, getPath, applySchema } = require('@xeplr/schema-handler');
 var xf = require('@xeplr/expression-handler');
 var db = require('./db');
@@ -455,6 +456,23 @@ async function routeAfterStep(workflow, steps, run, step, output) {
     var matches = !t.condition || xf.evaluate(t.condition, row);
     if (!matches) continue;
 
+    // LET A FUNCTION DECIDE: the arrow names a registered `decide` function,
+    // and its answer is the next step. It must be a step of this workflow —
+    // one of the arrow's `targets` when it lists them — or an end; anything
+    // else fails the run, by name, rather than wandering somewhere nobody drew.
+    if (t.decide) {
+      var decided;
+      try {
+        decided = await decideTarget(t, row, step, byKey, run);
+      } catch (err) {
+        await finishRun(run, 'failed', { message: err.message });
+        return { done: true };
+      }
+      if (decided === 'end_success') { await finishRun(run, 'success', null); return { done: true }; }
+      if (decided === 'end_failed') { await finishRun(run, 'failed', { message: 'Ended by "' + t.decide + '" on ' + step.stepKey }); return { done: true }; }
+      return { done: false, next: decided };
+    }
+
     if (t.mode === 'each') {
       var fannedOut = await handleFanOut(workflow, steps, run, step, t, output);
       if (fannedOut) return { done: true };
@@ -471,6 +489,29 @@ async function routeAfterStep(workflow, steps, run, step, output) {
   return { done: true };
 }
 
+/**
+ * Ask an arrow's `decide` function where to go. It is called with what the
+ * step produced (`output` — for a screen, what was filled in — also as
+ * `values`), the run's `params`, `item` and `trigger`, the step it is leaving
+ * and the steps it may choose from; it returns a step key, 'end_success' or
+ * 'end_failed'. Throws, with the function's name, for anything else.
+ */
+async function decideTarget(t, row, step, byKey, run) {
+  var def = actions.get(t.decide);
+  if (!def) throw new Error('Step ' + step.stepKey + ' asks "' + t.decide + '" where to go next, but no function of that name is registered');
+  if (def.event !== 'decide') throw new Error('Step ' + step.stepKey + ' asks "' + t.decide + '" where to go next, but it is written for ' + (def.event ? '"' + def.event + '"' : 'a workflow step'));
+  var allowed = Array.isArray(t.targets) && t.targets.length ? t.targets : Object.keys(byKey).concat(['end_success', 'end_failed']);
+  var answer = await def.execute({
+    output: row.output, values: row.output, params: row.params, item: row.item, trigger: row.trigger,
+    step: step.stepKey, runId: run.id, targets: allowed.slice()
+  });
+  var key = typeof answer === 'string' ? answer.trim() : '';
+  if (!key) throw new Error('"' + t.decide + '" did not say where to go next from ' + step.stepKey);
+  if (allowed.indexOf(key) === -1) throw new Error('"' + t.decide + '" chose "' + key + '" from ' + step.stepKey + ', which is not one of: ' + allowed.join(', '));
+  if (key !== 'end_success' && key !== 'end_failed' && !byKey[key]) throw new Error('"' + t.decide + '" chose "' + key + '", which is not a step of this workflow');
+  return key;
+}
+
 /**
  * `t.source` is a dotted path to the array to fan over (resolved against
  * { output, item, params } — usually `output.<field>`). Each element that

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xeplr/workflow-engine",
-  "version": "3.0.3",
+  "version": "3.2.0",
   "license": "MIT",
   "description": "The free workflow engine: runs, actions as steps, branching, waits, and triggers — manual, API, a schedule, a job finishing. No HTTP: @xeplr/workflow-api puts the routes on top.",
   "keywords": [
@@ -31,7 +31,7 @@
     "url": "https://github.com/Xeplr/xeplr-workflow-engine.git"
   },
   "peerDependencies": {
-    "@xeplr/actions": "^1.1.0",
+    "@xeplr/actions": "^1.4.0",
     "@xeplr/auth": "^1.0.0",
     "@xeplr/db": "^1.0.0",
     "@xeplr/expression-handler": "^2.0.0",