@xeplr/workflow-engine 3.0.0 → 3.0.2

package/README.md

@@ -62,7 +62,7 @@ engine/
 ├─ models/                  Company, Workspace, Workflow, WorkflowStep, WorkflowRun,
 │                           WorkflowStepRun, WorkflowResumeKey, WorkflowRunEdge,
 │                           WorkflowTriggerState
-├─ migrations/              0003–0015, workflow's own tables
+├─ migrations/              0003–0016, workflow's own tables
 ├─ migrations-tenants/      0001–0002: standalone workflow's companies / workspaces
 └─ test/                    run.mjs + *.test.mjs
 ```
@@ -207,6 +207,7 @@ Branch on how a job ended with a `decide` step: it does nothing itself, and the
 - **The period flows.** The next job gets the finished job's `window` unless the step's `inputs` set one, so a chain of workflows covers one period from its first job to its last.
 - **The next job is offered both earlier ranges**, as `@xeplr/jobs`' `previous.given` / `previous.used`.
 - **`carry`** (a `job-run` input) adds values for the jobs after it.
+- **`inputs` and `carry` keep their types.** A binding that is the whole value (`"{trigger.output.totalRows}"`) passes `7`, not `"7"`, and an object stays an object. Every other step's input is text, as bindings make it.
 - **Loops stop.** A job already on the path, or a path 25 jobs long, fails the step with a message.
 
 The next job takes only `window` and the inputs it lists in `acceptsInputs`; `@xeplr/jobs` refuses the rest, naming them.
@@ -220,11 +221,13 @@ await jobs.init({ /* … */ onFinish: (report) => engine.jobFinished(report) });
 
 `jobFinished(report)` takes `@xeplr/jobs`' finish envelope. It resumes the `job-run` step that started the job (retrying while that step parks) and starts every workflow the job triggers. Without `startJob`, `job-run` starts jobs over HTTP (`jobsUrl`, and `WORKFLOW_PUBLIC_URL` for the callback).
 
-**Job chains are gone.** Migration 0015 converted each "After this job" chain (kind `job-chain`) into an ordinary workflow:
-- it gets a `job` trigger (`when: finished`);
-- its `decide` and `job-run` steps keep the same behaviour;
+**Job chains are gone.** Migration 0015 converts each "After this job" chain (kind `job-chain`) into an ordinary workflow:
+- it gets a `job` trigger (`when: finished`) and the key `after-job-<jobId>`, the one the jobs screen's shortcut uses;
+- its `decide` and `job-run` steps keep the same behaviour, and each arrow keeps its rule's `when`;
 - conditions and bindings now read `trigger.*`.
 
+Migration 0016 repairs a database that ran 0015's first release, which left the key empty and the arrows without `when`. A single comparison gets its `when` back. A nested one still runs as before, and the jobs screen says it was changed elsewhere.
+
 ## Tests
 
 ```bash
@@ -244,7 +247,8 @@ No database or network needed, except `triggers.test.mjs`, which runs on a real
 - a loop stopped
 - a workflow that cannot start, recorded as a skip
 - the schedule's first sight, its due time, two ticks starting it once, a changed cron
-- migration 0015 turning an old job chain into a workflow that runs |
+- migration 0015 turning an old job chain into a workflow that runs, with its key and `when` arrows
+- migration 0016 repairing one converted early, and changing nothing on a second run |
 | `actionCatalog.test.mjs` | Ready vs placeholder detection; registered names are kebab-case; `spawnProgram` not offered; `decide` and `job-run` offered |
 | `envExposed.test.mjs` | Nothing exposed by default; exact, case-sensitive matching; globs fail closed (against real `interpolateAll`) |
 | `requires.test.mjs` | Every relative `require` in this package points at a file (Node only notices a missing one when the line runs; a bundler refuses it up front) |

package/lib/actions/jobRun.js

@@ -77,7 +77,14 @@ module.exports = {
     // this job unless the step sets one, carried values and the path travel
     // with it, and a job already on the path is refused as a loop
     // (jobs.nextJobCall). Any other run passes the step's inputs as they are.
-    var call = jobs.nextJobCall(ctx.system && ctx.system.trigger, input.jobId, input.inputs, input.carry);
+    // Inputs and carry KEEP THEIR TYPES ("{trigger.output.totalRows}" is 7,
+    // not "7"): they are handed on to a job, not printed.
+    var sys = ctx.system || {};
+    var raw = sys.rawValues || {};
+    var typed = typeof sys.resolveTyped === 'function';
+    var call = jobs.nextJobCall(sys.trigger, input.jobId,
+      typed && raw.inputs !== undefined ? sys.resolveTyped(raw.inputs) : input.inputs,
+      typed && raw.carry !== undefined ? sys.resolveTyped(raw.carry) : input.carry);
     var startJob = jobs.jobStarter();
     if (startJob) {
       call.chain.resumeKey = (ctx.system && ctx.system.resumeKey) || null;

package/lib/workflowRunner.js

@@ -112,6 +112,30 @@ async function finishRun(run, status, error) {
  * the two can differ), params/item are the run's own, resumeKey is injected
  * separately, only for the specific step that needs it.
  */
+/**
+ * Resolve `{path}` bindings KEEPING TYPES: a string that is exactly one
+ * binding takes the bound value as it is (an object stays an object, a number
+ * a number); anything else is text, as interpolate makes it.
+ */
+function resolveTyped(value, context) {
+  if (value == null) return value;
+  if (typeof value === 'string') {
+    var whole = /^\{([^{}]+)\}$/.exec(value.trim());
+    if (whole) {
+      var v = getPath(context, whole[1].trim());
+      return v === undefined ? null : v;
+    }
+    return interpolateAll(value, context);
+  }
+  if (Array.isArray(value)) return value.map(function(v) { return resolveTyped(v, context); });
+  if (typeof value === 'object') {
+    var out = {};
+    Object.keys(value).forEach(function(k) { out[k] = resolveTyped(value[k], context); });
+    return out;
+  }
+  return value;
+}
+
 // What started a run, as {trigger.*} reads it — in bindings AND in the
 // conditions on arrows. A run started by hand has just its kind.
 function triggerOf(run) {
@@ -359,8 +383,14 @@ async function executeFrom(workflow, steps, run, startStepKey) {
         // started in-process reports back through jobs.jobFinished).
         // trigger: what started the run, for an action that carries it on
         // (job-run passes a job's period to the next job).
+        // resolveTyped: a binding that is the WHOLE value keeps its type
+        // ("{trigger.output.totalRows}" stays 7, "{trigger.window}" an object),
+        // for an action that passes values on rather than printing them
+        // (job-run's inputs and carry). Every other action takes `input`, as
+        // resolved above, unchanged.
         system: { runId: run.id, stepId: step.id, stepKey: step.stepKey, resumeKey: resumeKey,
-          trigger: triggerOf(run) }
+          trigger: triggerOf(run), rawValues: step.values || {},
+          resolveTyped: function(value) { return resolveTyped(value, context); } }
       });
 
       if (result.status !== 'success') {
@@ -664,4 +694,5 @@ async function resumeByKey(key, output, opts) {
 // resolveParams and collectParams are exported for their own sake: they are
 // the pieces of the engine that are pure — rows in, a schema or a resolved
 // set out, or a throw — and testing them needs no database.
-module.exports = { startRun: startRun, resumeByKey: resumeByKey, resolveParams: resolveParams, collectParams: collectParams };
+module.exports = {
+  resolveTyped: resolveTyped, startRun: startRun, resumeByKey: resumeByKey, resolveParams: resolveParams, collectParams: collectParams };

package/migrations/0015_workflow_triggers.sql

@@ -53,8 +53,10 @@ CREATE UNIQUE INDEX IF NOT EXISTS "workflow_trigger_states_workflow_unique" ON "
 --   kind 'job-chain'           → 'workflow', with trigger
 --                                { kind: 'job', jobId, when: 'finished' }
 --                                (the decide step still routes on status)
---   key 'job-chain-<jobId>'    → none; the trigger says which job
---   'job-chain-decide' step    → 'decide' (a plain branching step)
+--   key 'job-chain-<jobId>'    → 'after-job-<jobId>', the key the jobs
+--                                screen's "After this job" shortcut keeps
+--   'job-chain-decide' step    → 'decide' (a plain branching step), each
+--                                arrow given its rule's `when` as written
 --   'job-chain-next' steps     → 'job-run', which carries the period on
 --   conditions on params.x     → trigger.x  (status, output, window, carry…)
 --   bindings {output.x} etc.   → {trigger.output.x}
@@ -65,7 +67,17 @@ CREATE UNIQUE INDEX IF NOT EXISTS "workflow_trigger_states_workflow_unique" ON "
 UPDATE "workflow_steps" s
    SET "actionName" = 'decide',
        "values" = '{}'::jsonb,
-       "transitions" = replace(s."transitions"::text, '"params.', '"trigger.')::jsonb
+       -- Arrow N is rule N, so it takes that rule's `when` (fields now read
+       -- the trigger); the closing "nothing matched" arrow is "otherwise".
+       "transitions" = (
+         SELECT COALESCE(jsonb_agg(
+           CASE WHEN x.ord <= COALESCE(jsonb_array_length(s."values"->'rules'), 0)
+                THEN x.t || jsonb_build_object('when', regexp_replace(
+                       COALESCE(s."values"->'rules'->((x.ord - 1)::int)->'when', 'null'::jsonb)::text,
+                       '"field"\s*:\s*"(status|error|output|carry|window|jobId|given|used)', '"field": "trigger.\1', 'g')::jsonb)
+                ELSE x.t || '{"when": null}'::jsonb END
+           ORDER BY x.ord), '[]'::jsonb)
+         FROM jsonb_array_elements(replace(s."transitions"::text, '"params.', '"trigger.')::jsonb) WITH ORDINALITY AS x(t, ord))
   FROM "workflows" w
  WHERE w."id" = s."workflowId" AND w."kind" = 'job-chain' AND s."actionName" = 'job-chain-decide';
 
@@ -81,5 +93,5 @@ UPDATE "workflow_steps" s
 UPDATE "workflows"
    SET "trigger" = jsonb_build_object('kind', 'job', 'jobId', substring("key" from 11), 'when', 'finished'),
        "kind" = 'workflow',
-       "key" = NULL
+       "key" = 'after-job-' || substring("key" from 11)
  WHERE "kind" = 'job-chain' AND "key" LIKE 'job-chain-%';

package/migrations/0016_after_job_shortcut.sql

@@ -0,0 +1,65 @@
+-- 0016_after_job_shortcut.sql
+--
+-- CONVERTED CHAINS, READABLE BY THE JOBS SCREEN AGAIN.
+--
+-- The first release of 0015 converted each job chain into an ordinary
+-- workflow, but with no key and with arrows holding only their compiled
+-- conditions. The jobs screen's "After this job" finds a job's rules by the
+-- key `after-job-<jobId>` and reads each arrow's `when`, so a converted chain
+-- showed as "changed in the workflow screens" instead of as its rules. 0015
+-- now does both; this repairs a database that ran it before it did. On any
+-- other database it changes nothing.
+--
+-- (No jsonb key-exists operator anywhere: the migrator's driver takes that
+-- character as a parameter placeholder. jsonb_typeof(x->'k') is NULL exactly
+-- when k is absent.)
+--
+-- 1. The key, for a converted chain that has none (and only if the job has
+--    no shortcut already).
+UPDATE "workflows" w
+   SET "key" = 'after-job-' || (w."trigger"->>'jobId')
+ WHERE w."key" IS NULL
+   AND w."trigger"->>'kind' = 'job'
+   AND w."description" LIKE 'Made from the "After this job" rules of job %'
+   AND NOT EXISTS (
+     SELECT 1 FROM "workflows" o
+      WHERE o."key" = 'after-job-' || (w."trigger"->>'jobId')
+        AND COALESCE(o."mtId1", '') = COALESCE(w."mtId1", '')
+        AND COALESCE(o."mtId2", '') = COALESCE(w."mtId2", ''));
+
+-- 2. `when` on each of their decide step's arrows, rebuilt from the compiled
+--    condition: none is "otherwise"; a single comparison is { field, op,
+--    value } in the jobs screen's own words. A nested all/any is left as it
+--    is — the jobs screen then says it was changed elsewhere, and it still
+--    runs exactly as before.
+UPDATE "workflow_steps" s
+   SET "transitions" = (
+     SELECT COALESCE(jsonb_agg(
+       CASE
+         WHEN jsonb_typeof(x.t->'when') IS NOT NULL THEN x.t
+         WHEN jsonb_typeof(x.t->'condition') IS NULL OR jsonb_typeof(x.t->'condition') = 'null' THEN x.t || '{"when": null}'::jsonb
+         WHEN jsonb_typeof(x.t->'condition'->'left') IS NOT NULL AND (CASE x.t->'condition'->>'op'
+                WHEN 'eq' THEN '=' WHEN 'neq' THEN '!=' WHEN 'gt' THEN '>' WHEN 'gte' THEN '>='
+                WHEN 'lt' THEN '<' WHEN 'lte' THEN '<=' WHEN 'contains' THEN 'contains'
+                WHEN 'notContains' THEN 'notContains' WHEN 'startsWith' THEN 'startsWith'
+                WHEN 'endsWith' THEN 'endsWith' WHEN 'in' THEN 'in' WHEN 'notIn' THEN 'notIn'
+                WHEN 'between' THEN 'between' WHEN 'isNull' THEN 'isEmpty' WHEN 'isNotNull' THEN 'isNotEmpty'
+              END) IS NOT NULL
+           THEN x.t || jsonb_build_object('when', jsonb_strip_nulls(jsonb_build_object(
+             'field', x.t->'condition'->'left'->>'field',
+             'op', CASE x.t->'condition'->>'op'
+                WHEN 'eq' THEN '=' WHEN 'neq' THEN '!=' WHEN 'gt' THEN '>' WHEN 'gte' THEN '>='
+                WHEN 'lt' THEN '<' WHEN 'lte' THEN '<=' WHEN 'contains' THEN 'contains'
+                WHEN 'notContains' THEN 'notContains' WHEN 'startsWith' THEN 'startsWith'
+                WHEN 'endsWith' THEN 'endsWith' WHEN 'in' THEN 'in' WHEN 'notIn' THEN 'notIn'
+                WHEN 'between' THEN 'between' WHEN 'isNull' THEN 'isEmpty' WHEN 'isNotNull' THEN 'isNotEmpty'
+              END,
+             'value', x.t->'condition'->'right'->'value')))
+         ELSE x.t
+       END ORDER BY x.ord), '[]'::jsonb)
+     FROM jsonb_array_elements(s."transitions") WITH ORDINALITY AS x(t, ord))
+  FROM "workflows" w
+ WHERE w."id" = s."workflowId"
+   AND w."key" LIKE 'after-job-%'
+   AND s."stepKey" = 'decide' AND s."actionName" = 'decide'
+   AND s."transitions" IS NOT NULL;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xeplr/workflow-engine",
-  "version": "3.0.0",
+  "version": "3.0.2",
   "license": "MIT",
   "description": "The workflow engine — workflow's own database and tables, the action catalog, starting and resuming runs, and the flows facade. No HTTP: @xeplr/workflow-api puts the routes on top.",
   "main": "index.js",