@blokjs/runner 0.4.0 → 0.6.0

package/dist/LoopNode.js

@@ -0,0 +1,182 @@
+/**
+ * LoopNode — v0.5 primitive. While-loop with hard maxIterations safety
+ * cap. Runs a sub-pipeline as long as the `while` condition evaluates
+ * truthy against the live ctx. Each iteration carries forward state
+ * mutations (sequential by definition) so condition variables can
+ * advance between iterations.
+ *
+ * The runtime config is read from `ctx.config[this.name]`:
+ *   {
+ *     while: string,          // JS expression evaluated against ctx
+ *     maxIterations: number,  // hard safety cap; throws LoopMaxIterationsError on hit
+ *     steps: NodeBase[],      // pre-resolved by Configuration's isFlowWithProperties path
+ *   }
+ *
+ * The loop counter is exposed as `ctx.state[<stepId>Index]` (0-based)
+ * so the `while` expression can reference it. Each iteration's final
+ * step output is the loop step's overall data (the last iteration's
+ * `ctx.response.data`).
+ */
+import _ from "lodash";
+import { LoopMaxIterationsError } from "./LoopMaxIterationsError";
+import RunnerNode from "./RunnerNode";
+import { consumeRehydratedCursor, popPrimitiveFrame, pushPrimitiveFrame, readRehydratedCursor, } from "./runtime/PrimitiveStack";
+import { applyStepOutput } from "./workflow/PersistenceHelper";
+const DEFAULT_MAX_ITERATIONS = 1000;
+export class LoopNode extends RunnerNode {
+    /**
+     * v0.6 marker — RunnerSteps stamps `_blokActivePrimitiveNodeRunId`
+     * on ctx around `step.process()` calls when this flag is true so a
+     * nested wait fired inside an iteration body knows which NodeRun to
+     * write its `iteration_context` cursor to. Mirrors ForEachNode's
+     * marker (Phase 2). Static `true` (vs an instance method) avoids
+     * importing LoopNode inside RunnerSteps, which would create a
+     * circular dependency.
+     */
+    isPrimitiveIterator = true;
+    async run(ctx) {
+        this.contentType = "application/json";
+        const response = { success: true, data: null, error: null };
+        const opts = (ctx.config?.[this.name] ?? {});
+        const whileExpr = typeof opts.while === "string" ? opts.while : "false";
+        const envCap = process.env.BLOK_LOOP_MAX_ITERATIONS
+            ? Number.parseInt(process.env.BLOK_LOOP_MAX_ITERATIONS, 10)
+            : undefined;
+        const maxIterations = typeof opts.maxIterations === "number" && opts.maxIterations > 0
+            ? opts.maxIterations
+            : envCap && envCap > 0
+                ? envCap
+                : DEFAULT_MAX_ITERATIONS;
+        const steps = (opts.steps ?? []);
+        if (steps.length === 0) {
+            return response;
+        }
+        // v0.6 — read the resume hint. Phase 4 — cursors are keyed by
+        // NodeRun id in the rehydrated map so a loop nested inside
+        // another primitive (or vice versa) finds its OWN cursor.
+        // Falls back to the legacy single-slot field for back-compat.
+        const ctxAny = ctx;
+        const myNodeRunId = ctxAny._traceNodeId;
+        // Phase 4 — lookup by step NAME (stable across re-entries).
+        let resume = readRehydratedCursor(ctx, this.name);
+        if (resume) {
+            consumeRehydratedCursor(ctx, this.name);
+        }
+        if (resume === undefined) {
+            const legacyResume = ctxAny._blokIterationResume;
+            if (legacyResume !== undefined) {
+                resume = legacyResume;
+                ctxAny._blokIterationResume = undefined;
+            }
+        }
+        const { default: Runner } = await import("./Runner");
+        const counterKey = `${this.name}Index`;
+        const state = (ctx.state ?? {});
+        let iteration = resume?.iteration ?? 0;
+        let lastData = null;
+        // v0.6 Phase 4 — push a primitive frame for THIS loop so a
+        // nested wait persists THIS loop's iteration cursor to THIS
+        // loop's NodeRun (and outer primitives' cursors to THEIRS).
+        // Loop returns the LAST iteration's output, so `completedResults`
+        // is always `[]` — preserved at schema level for parity with
+        // forEach.
+        const initialCursor = {
+            mode: "sequential",
+            iteration: 0,
+            innerStepIndex: 0,
+            completedResults: [],
+        };
+        const frame = myNodeRunId
+            ? { nodeRunId: myNodeRunId, cursor: initialCursor }
+            : undefined;
+        if (frame)
+            pushPrimitiveFrame(ctx, frame);
+        try {
+            while (true) {
+                state[counterKey] = iteration;
+                // v0.6 Phase 3 — on the first iteration after a wait-resume,
+                // skip the while-condition check. The condition was already
+                // TRUE when the wait fired (otherwise iter N wouldn't have
+                // started), and we've committed to finishing iter N's body
+                // — re-evaluating now would compare against post-iter-N
+                // state (e.g. a counter advanced by the pre-wait steps) and
+                // could falsely terminate the loop. Subsequent iterations
+                // re-check normally.
+                const isFirstIterationAfterResume = resume !== undefined && iteration === resume.iteration;
+                if (!isFirstIterationAfterResume) {
+                    // Re-clone config each iteration so mapper-resolved
+                    // values from prior iterations don't bleed into the
+                    // next condition eval.
+                    const evalCtx = { ...ctx, config: _.cloneDeep(ctx.config) };
+                    const shouldContinue = this.evaluateCondition(whileExpr, evalCtx);
+                    if (!shouldContinue)
+                        break;
+                }
+                if (iteration >= maxIterations) {
+                    throw new LoopMaxIterationsError(this.name, maxIterations, iteration);
+                }
+                // v0.6 Phase 4 — update the frame cursor before launching
+                // the iteration body. The wait-throw site walks the stack
+                // and writes the cursor; the TOP frame is THIS loop's,
+                // so we need `iteration` to point at the in-flight pass.
+                if (frame) {
+                    frame.cursor.iteration = iteration;
+                }
+                const childCtx = this.cloneCtxForIteration(ctx);
+                // v0.5.3 — stash iteration index on the per-iteration
+                // child ctx so RunnerSteps propagates it to
+                // NodeRun.iterationIndex (Studio groups inner steps under
+                // "iteration N" headers).
+                childCtx._blokIterationIndex = iteration;
+                // v0.6 Phase 3 — pass the inner-step resume cursor on the
+                // child ctx for the first iteration after resume.
+                // Phase 4 — propagate the index-0 case so the deep
+                // runSteps' wait re-entry detection sees innerResumeIndex
+                // defined even when the wait is at body[0].
+                if (isFirstIterationAfterResume && resume !== undefined) {
+                    childCtx._blokInnerResumeIndex = resume.innerStepIndex;
+                }
+                const runner = new Runner(steps);
+                // `deep: true` — inner pipelines must not inherit the
+                // outer run's `lastCompletedStepIndex` cursor.
+                await runner.run(childCtx, { deep: true, stepName: this.name });
+                // Carry state forward into the parent ctx so subsequent
+                // iterations see updates.
+                const childState = (childCtx.state ?? {});
+                for (const [k, v] of Object.entries(childState)) {
+                    state[k] = v;
+                }
+                lastData = childCtx.response;
+                iteration++;
+            }
+            response.data = lastData;
+            // Persist to ctx.state[this.name] (see ForEachNode comment).
+            applyStepOutput(ctx, this, { data: lastData });
+            return response;
+        }
+        finally {
+            // v0.6 Phase 4 — always pop so sibling loops / outer
+            // runSteps see a clean stack, including on wait re-throw.
+            if (frame)
+                popPrimitiveFrame(ctx);
+        }
+    }
+    evaluateCondition(expr, ctx) {
+        const data = (ctx.response?.data ?? ctx.request?.body ?? {});
+        const vars = (ctx.vars ?? {});
+        const fn = new Function("ctx", "data", "vars", `"use strict";return (${expr});`);
+        return fn(ctx, data, vars);
+    }
+    cloneCtxForIteration(ctx) {
+        // State is shared by reference (mutations carry forward — that's
+        // the loop semantic). Config is deep-cloned so mapper resolutions
+        // don't bleed across iterations.
+        const config = _.cloneDeep(ctx.config);
+        return {
+            ...ctx,
+            config,
+            response: { data: null, success: true, error: null, contentType: "application/json" },
+        };
+    }
+}
+//# sourceMappingURL=LoopNode.js.map

package/dist/LoopNode.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"LoopNode.js","sourceRoot":"","sources":["../src/LoopNode.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAGH,OAAO,CAAC,MAAM,QAAQ,CAAC;AACvB,OAAO,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAClE,OAAO,UAAU,MAAM,cAAc,CAAC;AACtC,OAAO,EAEN,uBAAuB,EACvB,iBAAiB,EACjB,kBAAkB,EAClB,oBAAoB,GACpB,MAAM,0BAA0B,CAAC;AAElC,OAAO,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAqC/D,MAAM,sBAAsB,GAAG,IAAI,CAAC;AAEpC,MAAM,OAAO,QAAS,SAAQ,UAAU;IACvC;;;;;;;;OAQG;IACa,mBAAmB,GAAG,IAAI,CAAC;IAE3C,KAAK,CAAC,GAAG,CAAC,GAAY;QACrB,IAAI,CAAC,WAAW,GAAG,kBAAkB,CAAC;QACtC,MAAM,QAAQ,GAAoB,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;QAE7E,MAAM,IAAI,GAAG,CAAE,GAAG,CAAC,MAA8C,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,CAAa,CAAC;QAClG,MAAM,SAAS,GAAG,OAAO,IAAI,CAAC,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC;QACxE,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,wBAAwB;YAClD,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,wBAAwB,EAAE,EAAE,CAAC;YAC3D,CAAC,CAAC,SAAS,CAAC;QACb,MAAM,aAAa,GAClB,OAAO,IAAI,CAAC,aAAa,KAAK,QAAQ,IAAI,IAAI,CAAC,aAAa,GAAG,CAAC;YAC/D,CAAC,CAAC,IAAI,CAAC,aAAa;YACpB,CAAC,CAAC,MAAM,IAAI,MAAM,GAAG,CAAC;gBACrB,CAAC,CAAC,MAAM;gBACR,CAAC,CAAC,sBAAsB,CAAC;QAC5B,MAAM,KAAK,GAAG,CAAC,IAAI,CAAC,KAAK,IAAI,EAAE,CAAiB,CAAC;QAEjD,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACxB,OAAO,QAAQ,CAAC;QACjB,CAAC;QAED,8DAA8D;QAC9D,2DAA2D;QAC3D,0DAA0D;QAC1D,8DAA8D;QAC9D,MAAM,MAAM,GAAG,GAA8B,CAAC;QAC9C,MAAM,WAAW,GAAG,MAAM,CAAC,YAAkC,CAAC;QAC9D,4DAA4D;QAC5D,IAAI,MAAM,GAA2B,oBAAoB,CAAC,GAAG,EAAE,IAAI,CAAC,IAAI,CAA2B,CAAC;QACpG,IAAI,MAAM,EAAE,CAAC;YACZ,uBAAuB,CAAC,GAAG,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC;QACzC,CAAC;QACD,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;YAC1B,MAAM,YAAY,GAAG,MAAM,CAAC,oBAA8C,CAAC;YAC3E,IAAI,YAAY,KAAK,SAAS,EAAE,CAAC;gBAChC,MAAM,GAAG,YAAY,CAAC;gBACtB,MAAM,CAAC,oBAAoB,GAAG,SAAS,CAAC;YACzC,CAAC;QACF,CAAC;QAED,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,MAAM,MAAM,CAAC,UAAU,CAAC,CAAC;QAErD,MAAM,UAAU,GAAG,GAAG,IAAI,CAAC,IAAI,OAAO,CAAC;QACvC,MAAM,KAAK,GAAG,CAAC,GAAG,CAAC,KAAK,IAAI,EAAE,CAA4B,CAAC;QAC3D,IAAI,SAAS,GAAG,MAAM,EAAE,SAAS,IAAI,CAAC,CAAC;QACvC,IAAI,QAAQ,GAAY,IAAI,CAAC;QAE7B,2DAA2D;QAC3D,4DAA4D;QAC5D,4DAA4D;QAC5D,kEAAkE;QAClE,6DAA6D;QAC7D,WAAW;QACX,MAAM,aAAa,GAA+B;YACjD,IAAI,EAAE,YAAY;YAClB,SAAS,EAAE,CAAC;YACZ,cAAc,EAAE,CAAC;YACjB,gBAAgB,EAAE,EAAE;SACpB,CAAC;QACF,MAAM,KAAK,GAAoC,WAAW;YACzD,CAAC,CAAC,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,EAAE,aAAa,EAAE;YACnD,CAAC,CAAC,SAAS,CAAC;QACb,IAAI,KAAK;YAAE,kBAAkB,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QAE1C,IAAI,CAAC;YACJ,OAAO,IAAI,EAAE,CAAC;gBACb,KAAK,CAAC,UAAU,CAAC,GAAG,SAAS,CAAC;gBAE9B,6DAA6D;gBAC7D,4DAA4D;gBAC5D,2DAA2D;gBAC3D,2DAA2D;gBAC3D,wDAAwD;gBACxD,4DAA4D;gBAC5D,0DAA0D;gBAC1D,qBAAqB;gBACrB,MAAM,2BAA2B,GAAG,MAAM,KAAK,SAAS,IAAI,SAAS,KAAK,MAAM,CAAC,SAAS,CAAC;gBAC3F,IAAI,CAAC,2BAA2B,EAAE,CAAC;oBAClC,oDAAoD;oBACpD,oDAAoD;oBACpD,uBAAuB;oBACvB,MAAM,OAAO,GAAG,EAAE,GAAG,GAAG,EAAE,MAAM,EAAE,CAAC,CAAC,SAAS,CAAC,GAAG,CAAC,MAAM,CAAC,EAAa,CAAC;oBACvE,MAAM,cAAc,GAAG,IAAI,CAAC,iBAAiB,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;oBAClE,IAAI,CAAC,cAAc;wBAAE,MAAM;gBAC5B,CAAC;gBAED,IAAI,SAAS,IAAI,aAAa,EAAE,CAAC;oBAChC,MAAM,IAAI,sBAAsB,CAAC,IAAI,CAAC,IAAI,EAAE,aAAa,EAAE,SAAS,CAAC,CAAC;gBACvE,CAAC;gBAED,0DAA0D;gBAC1D,0DAA0D;gBAC1D,uDAAuD;gBACvD,yDAAyD;gBACzD,IAAI,KAAK,EAAE,CAAC;oBACV,KAAK,CAAC,MAAqC,CAAC,SAAS,GAAG,SAAS,CAAC;gBACpE,CAAC;gBAED,MAAM,QAAQ,GAAG,IAAI,CAAC,oBAAoB,CAAC,GAAG,CAAC,CAAC;gBAChD,sDAAsD;gBACtD,4CAA4C;gBAC5C,0DAA0D;gBAC1D,0BAA0B;gBACzB,QAAoC,CAAC,mBAAmB,GAAG,SAAS,CAAC;gBACtE,0DAA0D;gBAC1D,kDAAkD;gBAClD,mDAAmD;gBACnD,0DAA0D;gBAC1D,4CAA4C;gBAC5C,IAAI,2BAA2B,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;oBACxD,QAAoC,CAAC,qBAAqB,GAAG,MAAM,CAAC,cAAc,CAAC;gBACrF,CAAC;gBACD,MAAM,MAAM,GAAG,IAAI,MAAM,CAAC,KAAK,CAAC,CAAC;gBACjC,sDAAsD;gBACtD,+CAA+C;gBAC/C,MAAM,MAAM,CAAC,GAAG,CAAC,QAAQ,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;gBAChE,wDAAwD;gBACxD,0BAA0B;gBAC1B,MAAM,UAAU,GAAG,CAAC,QAAQ,CAAC,KAAK,IAAI,EAAE,CAA4B,CAAC;gBACrE,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC,EAAE,CAAC;oBACjD,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;gBACd,CAAC;gBACD,QAAQ,GAAG,QAAQ,CAAC,QAAQ,CAAC;gBAC7B,SAAS,EAAE,CAAC;YACb,CAAC;YAED,QAAQ,CAAC,IAAI,GAAG,QAAQ,CAAC;YACzB,6DAA6D;YAC7D,eAAe,CAAC,GAAG,EAAE,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC,CAAC;YAC/C,OAAO,QAAQ,CAAC;QACjB,CAAC;gBAAS,CAAC;YACV,qDAAqD;YACrD,0DAA0D;YAC1D,IAAI,KAAK;gBAAE,iBAAiB,CAAC,GAAG,CAAC,CAAC;QACnC,CAAC;IACF,CAAC;IAEO,iBAAiB,CAAC,IAAY,EAAE,GAAY;QACnD,MAAM,IAAI,GAAG,CAAC,GAAG,CAAC,QAAQ,EAAE,IAAI,IAAI,GAAG,CAAC,OAAO,EAAE,IAAI,IAAI,EAAE,CAA4B,CAAC;QACxF,MAAM,IAAI,GAAG,CAAC,GAAG,CAAC,IAAI,IAAI,EAAE,CAA4B,CAAC;QACzD,MAAM,EAAE,GAAG,IAAI,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,wBAAwB,IAAI,IAAI,CAAC,CAAC;QACjF,OAAO,EAAE,CAAC,GAAG,EAAE,IAAI,EAAE,IAAI,CAAY,CAAC;IACvC,CAAC;IAEO,oBAAoB,CAAC,GAAY;QACxC,iEAAiE;QACjE,kEAAkE;QAClE,iCAAiC;QACjC,MAAM,MAAM,GAAG,CAAC,CAAC,SAAS,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QACvC,OAAO;YACN,GAAG,GAAG;YACN,MAAM;YACN,QAAQ,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,WAAW,EAAE,kBAAkB,EAAE;SAC1E,CAAC;IACd,CAAC;CACD"}

package/dist/Runner.d.ts

@@ -19,7 +19,17 @@ export default class Runner extends RunnerSteps {
      * Executes the series of BlokService steps with the given context.
      *
      * @param ctx - The context to be passed through the steps.
+     * @param options - Optional execution options:
+     *   - `deep`: if true, treats this as a nested flow run — disables
+     *     top-level concerns like the wait/resume cursor
+     *     (`lastCompletedStepIndex`) and parent-run trace updates so
+     *     inner pipelines (forEach, loop, switch, tryCatch) don't
+     *     accidentally inherit the outer run's cursor and skip ahead.
+     *   - `stepName`: parent step's id, surfaced in nested-runner log lines.
      * @returns A promise that resolves to the final context after all steps have been executed.
      */
-    run(ctx: Context): Promise<Context>;
+    run(ctx: Context, options?: {
+        deep?: boolean;
+        stepName?: string;
+    }): Promise<Context>;
 }

package/dist/Runner.js

@@ -23,10 +23,17 @@ export default class Runner extends RunnerSteps {
      * Executes the series of BlokService steps with the given context.
      *
      * @param ctx - The context to be passed through the steps.
+     * @param options - Optional execution options:
+     *   - `deep`: if true, treats this as a nested flow run — disables
+     *     top-level concerns like the wait/resume cursor
+     *     (`lastCompletedStepIndex`) and parent-run trace updates so
+     *     inner pipelines (forEach, loop, switch, tryCatch) don't
+     *     accidentally inherit the outer run's cursor and skip ahead.
+     *   - `stepName`: parent step's id, surfaced in nested-runner log lines.
      * @returns A promise that resolves to the final context after all steps have been executed.
      */
-    async run(ctx) {
-        return await this.runSteps(ctx, this.steps);
+    async run(ctx, options) {
+        return await this.runSteps(ctx, this.steps, options?.deep ?? false, options?.stepName ?? "");
     }
 }
 //# sourceMappingURL=Runner.js.map

package/dist/Runner.js.map

@@ -1 +1 @@
-{"version":3,"file":"Runner.js","sourceRoot":"","sources":["../src/Runner.ts"],"names":[],"mappings":"AACA,OAAO,WAAW,MAAM,eAAe,CAAC;AAExC;;GAEG;AACH,MAAM,CAAC,OAAO,OAAO,MAAO,SAAQ,WAAW;IACtC,KAAK,CAAa;IAE1B;;;;OAIG;IACH,YAAY,QAAoB,EAAE;QACjC,KAAK,EAAE,CAAC;QACR,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;IACpB,CAAC;IAED;;OAEG;IACH,YAAY;QACX,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC;IAC1B,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,GAAG,CAAC,GAAY;QACrB,OAAO,MAAM,IAAI,CAAC,QAAQ,CAAC,GAAG,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC;IAC7C,CAAC;CACD"}
+{"version":3,"file":"Runner.js","sourceRoot":"","sources":["../src/Runner.ts"],"names":[],"mappings":"AACA,OAAO,WAAW,MAAM,eAAe,CAAC;AAExC;;GAEG;AACH,MAAM,CAAC,OAAO,OAAO,MAAO,SAAQ,WAAW;IACtC,KAAK,CAAa;IAE1B;;;;OAIG;IACH,YAAY,QAAoB,EAAE;QACjC,KAAK,EAAE,CAAC;QACR,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;IACpB,CAAC;IAED;;OAEG;IACH,YAAY;QACX,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC;IAC1B,CAAC;IAED;;;;;;;;;;;;OAYG;IACH,KAAK,CAAC,GAAG,CAAC,GAAY,EAAE,OAA+C;QACtE,OAAO,MAAM,IAAI,CAAC,QAAQ,CAAC,GAAG,EAAE,IAAI,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,IAAI,KAAK,EAAE,OAAO,EAAE,QAAQ,IAAI,EAAE,CAAC,CAAC;IAC9F,CAAC;CACD"}