@blokjs/helper 0.4.0 → 0.6.0

package/dist/components/AddElse.d.ts

@@ -13,7 +13,6 @@ declare const ConditionElseSchema: z.ZodObject<{
         type: z.ZodEnum<["local", "module", "runtime.python3", "runtime.nodejs", "runtime.bun", "runtime.go", "runtime.java", "runtime.rust", "runtime.php", "runtime.csharp", "runtime.ruby", "runtime.docker", "runtime.wasm"]>;
         inputs: z.ZodOptional<z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>>;
         runtime: z.ZodOptional<z.ZodEnum<["nodejs", "bun", "python3", "go", "java", "rust", "php", "csharp", "ruby", "docker", "wasm"]>>;
-        set_var: z.ZodOptional<z.ZodBoolean>;
         active: z.ZodOptional<z.ZodBoolean>;
         stop: z.ZodOptional<z.ZodBoolean>;
         stream_logs: z.ZodOptional<z.ZodBoolean>;
@@ -23,7 +22,6 @@ declare const ConditionElseSchema: z.ZodObject<{
         type: "local" | "module" | "runtime.python3" | "runtime.nodejs" | "runtime.bun" | "runtime.go" | "runtime.java" | "runtime.rust" | "runtime.php" | "runtime.csharp" | "runtime.ruby" | "runtime.docker" | "runtime.wasm";
         inputs?: {} | undefined;
         runtime?: "nodejs" | "bun" | "python3" | "go" | "java" | "rust" | "php" | "csharp" | "ruby" | "docker" | "wasm" | undefined;
-        set_var?: boolean | undefined;
         active?: boolean | undefined;
         stop?: boolean | undefined;
         stream_logs?: boolean | undefined;
@@ -33,7 +31,6 @@ declare const ConditionElseSchema: z.ZodObject<{
         type: "local" | "module" | "runtime.python3" | "runtime.nodejs" | "runtime.bun" | "runtime.go" | "runtime.java" | "runtime.rust" | "runtime.php" | "runtime.csharp" | "runtime.ruby" | "runtime.docker" | "runtime.wasm";
         inputs?: {} | undefined;
         runtime?: "nodejs" | "bun" | "python3" | "go" | "java" | "rust" | "php" | "csharp" | "ruby" | "docker" | "wasm" | undefined;
-        set_var?: boolean | undefined;
         active?: boolean | undefined;
         stop?: boolean | undefined;
         stream_logs?: boolean | undefined;
@@ -46,7 +43,6 @@ declare const ConditionElseSchema: z.ZodObject<{
         type: "local" | "module" | "runtime.python3" | "runtime.nodejs" | "runtime.bun" | "runtime.go" | "runtime.java" | "runtime.rust" | "runtime.php" | "runtime.csharp" | "runtime.ruby" | "runtime.docker" | "runtime.wasm";
         inputs?: {} | undefined;
         runtime?: "nodejs" | "bun" | "python3" | "go" | "java" | "rust" | "php" | "csharp" | "ruby" | "docker" | "wasm" | undefined;
-        set_var?: boolean | undefined;
         active?: boolean | undefined;
         stop?: boolean | undefined;
         stream_logs?: boolean | undefined;
@@ -59,7 +55,6 @@ declare const ConditionElseSchema: z.ZodObject<{
         type: "local" | "module" | "runtime.python3" | "runtime.nodejs" | "runtime.bun" | "runtime.go" | "runtime.java" | "runtime.rust" | "runtime.php" | "runtime.csharp" | "runtime.ruby" | "runtime.docker" | "runtime.wasm";
         inputs?: {} | undefined;
         runtime?: "nodejs" | "bun" | "python3" | "go" | "java" | "rust" | "php" | "csharp" | "ruby" | "docker" | "wasm" | undefined;
-        set_var?: boolean | undefined;
         active?: boolean | undefined;
         stop?: boolean | undefined;
         stream_logs?: boolean | undefined;

package/dist/components/AddIf.d.ts

@@ -16,7 +16,6 @@ declare const ConditionSchema: z.ZodObject<{
         type: z.ZodEnum<["local", "module", "runtime.python3", "runtime.nodejs", "runtime.bun", "runtime.go", "runtime.java", "runtime.rust", "runtime.php", "runtime.csharp", "runtime.ruby", "runtime.docker", "runtime.wasm"]>;
         inputs: z.ZodOptional<z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>>;
         runtime: z.ZodOptional<z.ZodEnum<["nodejs", "bun", "python3", "go", "java", "rust", "php", "csharp", "ruby", "docker", "wasm"]>>;
-        set_var: z.ZodOptional<z.ZodBoolean>;
         active: z.ZodOptional<z.ZodBoolean>;
         stop: z.ZodOptional<z.ZodBoolean>;
         stream_logs: z.ZodOptional<z.ZodBoolean>;
@@ -26,7 +25,6 @@ declare const ConditionSchema: z.ZodObject<{
         type: "local" | "module" | "runtime.python3" | "runtime.nodejs" | "runtime.bun" | "runtime.go" | "runtime.java" | "runtime.rust" | "runtime.php" | "runtime.csharp" | "runtime.ruby" | "runtime.docker" | "runtime.wasm";
         inputs?: {} | undefined;
         runtime?: "nodejs" | "bun" | "python3" | "go" | "java" | "rust" | "php" | "csharp" | "ruby" | "docker" | "wasm" | undefined;
-        set_var?: boolean | undefined;
         active?: boolean | undefined;
         stop?: boolean | undefined;
         stream_logs?: boolean | undefined;
@@ -36,7 +34,6 @@ declare const ConditionSchema: z.ZodObject<{
         type: "local" | "module" | "runtime.python3" | "runtime.nodejs" | "runtime.bun" | "runtime.go" | "runtime.java" | "runtime.rust" | "runtime.php" | "runtime.csharp" | "runtime.ruby" | "runtime.docker" | "runtime.wasm";
         inputs?: {} | undefined;
         runtime?: "nodejs" | "bun" | "python3" | "go" | "java" | "rust" | "php" | "csharp" | "ruby" | "docker" | "wasm" | undefined;
-        set_var?: boolean | undefined;
         active?: boolean | undefined;
         stop?: boolean | undefined;
         stream_logs?: boolean | undefined;
@@ -50,7 +47,6 @@ declare const ConditionSchema: z.ZodObject<{
         type: "local" | "module" | "runtime.python3" | "runtime.nodejs" | "runtime.bun" | "runtime.go" | "runtime.java" | "runtime.rust" | "runtime.php" | "runtime.csharp" | "runtime.ruby" | "runtime.docker" | "runtime.wasm";
         inputs?: {} | undefined;
         runtime?: "nodejs" | "bun" | "python3" | "go" | "java" | "rust" | "php" | "csharp" | "ruby" | "docker" | "wasm" | undefined;
-        set_var?: boolean | undefined;
         active?: boolean | undefined;
         stop?: boolean | undefined;
         stream_logs?: boolean | undefined;
@@ -64,7 +60,6 @@ declare const ConditionSchema: z.ZodObject<{
         type: "local" | "module" | "runtime.python3" | "runtime.nodejs" | "runtime.bun" | "runtime.go" | "runtime.java" | "runtime.rust" | "runtime.php" | "runtime.csharp" | "runtime.ruby" | "runtime.docker" | "runtime.wasm";
         inputs?: {} | undefined;
         runtime?: "nodejs" | "bun" | "python3" | "go" | "java" | "rust" | "php" | "csharp" | "ruby" | "docker" | "wasm" | undefined;
-        set_var?: boolean | undefined;
         active?: boolean | undefined;
         stop?: boolean | undefined;
         stream_logs?: boolean | undefined;

package/dist/components/StepNode.js

@@ -19,7 +19,6 @@ export default class StepNode extends HelperResponse {
             node: config.node,
             type: config.type,
             runtime: config.runtime,
-            set_var: config.set_var,
             active: config.active,
             stop: config.stop,
         });

package/dist/components/StepNode.js.map

@@ -1 +1 @@
-{"version":3,"file":"StepNode.js","sourceRoot":"","sources":["../../src/components/StepNode.ts"],"names":[],"mappings":"AAAA,OAAO,EAGN,mBAAmB,EAEnB,cAAc,GACd,MAAM,mBAAmB,CAAC;AAG3B,OAAO,cAAc,MAAM,kBAAkB,CAAC;AAE9C;;;;;GAKG;AACH,MAAM,CAAC,OAAO,OAAO,QAAS,SAAQ,cAAc;IACnD,OAAO,CAAC,MAAgB;QACvB,cAAc,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;QAE7B,IAAI,IAAI,CAAC,OAAO,CAAC,KAAK,KAAK,SAAS;YAAE,IAAI,CAAC,OAAO,CAAC,KAAK,GAAG,EAAE,CAAC;QAC9D,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG;YACjC,MAAM,EAAE,MAAM,CAAC,MAAM;SACrB,CAAC;QAEF,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,IAAI,CAAC;YACxB,IAAI,EAAE,MAAM,CAAC,IAAI;YACjB,IAAI,EAAE,MAAM,CAAC,IAAI;YACjB,IAAI,EAAE,MAAM,CAAC,IAAI;YACjB,OAAO,EAAE,MAAM,CAAC,OAAO;YACvB,OAAO,EAAE,MAAM,CAAC,OAAO;YACvB,MAAM,EAAE,MAAM,CAAC,MAAM;YACrB,IAAI,EAAE,MAAM,CAAC,IAAI;SACjB,CAAC,CAAC;QAEH,MAAM,cAAc,GAAG,IAAI,QAAQ,EAAE,CAAC;QACtC,cAAc,CAAC,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACvC,OAAO,cAAc,CAAC;IACvB,CAAC;IAED,YAAY,CAAC,UAA6B;QACzC,mBAAmB,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;QACtC,MAAM,IAAI,GAAG,UAAoC,CAAC;QAClD,MAAM,QAAQ,GAAG,IAAI,CAAC,UAAU,EAA2C,CAAC;QAE5E,IAAI,IAAI,CAAC,OAAO,CAAC,KAAK,KAAK,SAAS;YAAE,IAAI,CAAC,OAAO,CAAC,KAAK,GAAG,EAAE,CAAC;QAE9D,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,QAAQ,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YAC1C,MAAM,SAAS,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC;YAC9B,MAAM,KAAK,GAAG,SAAS,CAAC,KAAmB,CAAC;YAE5C,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;gBACvC,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;gBAEtB,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG;oBAC/B,MAAM,EAAE,IAAI,CAAC,MAAM;iBACnB,CAAC;gBAEF,IAAI,CAAC,MAAM,GAAG,SAAS,CAAC;YACzB,CAAC;QACF,CAAC;QAED,IAAI,IAAI,CAAC,OAAO,CAAC,KAAK,KAAK,SAAS;YAAE,IAAI,CAAC,OAAO,CAAC,KAAK,GAAG,EAAE,CAAC;QAC9D,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;QACzC,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG;YAC1C,UAAU,EAAE,QAAQ;SACpB,CAAC;QAEF,MAAM,cAAc,GAAG,IAAI,QAAQ,EAAE,CAAC;QACtC,cAAc,CAAC,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACvC,OAAO,cAAc,CAAC;IACvB,CAAC;CACD"}
+{"version":3,"file":"StepNode.js","sourceRoot":"","sources":["../../src/components/StepNode.ts"],"names":[],"mappings":"AAAA,OAAO,EAGN,mBAAmB,EAEnB,cAAc,GACd,MAAM,mBAAmB,CAAC;AAG3B,OAAO,cAAc,MAAM,kBAAkB,CAAC;AAE9C;;;;;GAKG;AACH,MAAM,CAAC,OAAO,OAAO,QAAS,SAAQ,cAAc;IACnD,OAAO,CAAC,MAAgB;QACvB,cAAc,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;QAE7B,IAAI,IAAI,CAAC,OAAO,CAAC,KAAK,KAAK,SAAS;YAAE,IAAI,CAAC,OAAO,CAAC,KAAK,GAAG,EAAE,CAAC;QAC9D,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG;YACjC,MAAM,EAAE,MAAM,CAAC,MAAM;SACrB,CAAC;QAEF,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,IAAI,CAAC;YACxB,IAAI,EAAE,MAAM,CAAC,IAAI;YACjB,IAAI,EAAE,MAAM,CAAC,IAAI;YACjB,IAAI,EAAE,MAAM,CAAC,IAAI;YACjB,OAAO,EAAE,MAAM,CAAC,OAAO;YACvB,MAAM,EAAE,MAAM,CAAC,MAAM;YACrB,IAAI,EAAE,MAAM,CAAC,IAAI;SACjB,CAAC,CAAC;QAEH,MAAM,cAAc,GAAG,IAAI,QAAQ,EAAE,CAAC;QACtC,cAAc,CAAC,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACvC,OAAO,cAAc,CAAC;IACvB,CAAC;IAED,YAAY,CAAC,UAA6B;QACzC,mBAAmB,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;QACtC,MAAM,IAAI,GAAG,UAAoC,CAAC;QAClD,MAAM,QAAQ,GAAG,IAAI,CAAC,UAAU,EAA2C,CAAC;QAE5E,IAAI,IAAI,CAAC,OAAO,CAAC,KAAK,KAAK,SAAS;YAAE,IAAI,CAAC,OAAO,CAAC,KAAK,GAAG,EAAE,CAAC;QAE9D,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,QAAQ,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YAC1C,MAAM,SAAS,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC;YAC9B,MAAM,KAAK,GAAG,SAAS,CAAC,KAAmB,CAAC;YAE5C,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;gBACvC,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;gBAEtB,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG;oBAC/B,MAAM,EAAE,IAAI,CAAC,MAAM;iBACnB,CAAC;gBAEF,IAAI,CAAC,MAAM,GAAG,SAAS,CAAC;YACzB,CAAC;QACF,CAAC;QAED,IAAI,IAAI,CAAC,OAAO,CAAC,KAAK,KAAK,SAAS;YAAE,IAAI,CAAC,OAAO,CAAC,KAAK,GAAG,EAAE,CAAC;QAC9D,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;QACzC,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG;YAC1C,UAAU,EAAE,QAAQ;SACpB,CAAC;QAEF,MAAM,cAAc,GAAG,IAAI,QAAQ,EAAE,CAAC;QACtC,cAAc,CAAC,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACvC,OAAO,cAAc,CAAC;IACvB,CAAC;CACD"}

package/dist/components/forEach.d.ts

@@ -0,0 +1,53 @@
+import type { V2ForEachStep, V2Step } from "../types/StepOpts";
+/**
+ * Author-facing options for {@link forEach}.
+ *
+ * `in` accepts either a literal expression string (`"$.state.items"` or
+ * `"js/ctx.state.items"`) or a `$` proxy expression that compiles to
+ * the same string at definition time.
+ *
+ * `as` is the per-iteration variable name. Each iteration sets
+ * `ctx.state[as]` to the current item and `ctx.state[as + "Index"]`
+ * to the 0-based position. Avoid using a name that collides with
+ * any step `id` in the surrounding workflow.
+ */
+export interface ForEachOpts {
+    /** Stable identifier — visible in traces, referenced as `$.state[id]`. */
+    id: string;
+    /** Array source. Literal expression string or `$` proxy. */
+    in: string | unknown;
+    /**
+     * Per-iteration variable name. Each iteration sets `ctx.state[as] = item`
+     * and `ctx.state[as + "Index"] = i`. Must be a valid JS identifier
+     * (letters, digits, underscore; can't start with a digit).
+     */
+    as: string;
+    /** Sub-pipeline run for each item. */
+    do: V2Step[];
+    /** `"sequential"` (default) awaits each iteration; `"parallel"` runs with bounded concurrency. */
+    mode?: "sequential" | "parallel";
+    /** When `mode: "parallel"`, max concurrent inner pipelines. Default 10. */
+    concurrency?: number;
+    /** Skip this step at runtime. Default true (active). */
+    active?: boolean;
+    /** Halt the workflow after this step completes. */
+    stop?: boolean;
+}
+/**
+ * Create a forEach step — iterate over a collection running a sub-pipeline
+ * per item. Sequential by default; pass `mode: "parallel"` with a
+ * `concurrency` cap for parallel fan-out.
+ *
+ * @example
+ *   forEach({
+ *     id: "process-items",
+ *     in: $.req.body.items,
+ *     as: "item",
+ *     mode: "parallel",
+ *     concurrency: 5,
+ *     do: [
+ *       { id: "reserve", use: "inventory-reserve", inputs: { sku: $.state.item.sku } },
+ *     ],
+ *   })
+ */
+export declare function forEach(opts: ForEachOpts): V2ForEachStep;

package/dist/components/forEach.js

@@ -0,0 +1,64 @@
+import { unwrapProxies } from "../proxy/$";
+/**
+ * Create a forEach step — iterate over a collection running a sub-pipeline
+ * per item. Sequential by default; pass `mode: "parallel"` with a
+ * `concurrency` cap for parallel fan-out.
+ *
+ * @example
+ *   forEach({
+ *     id: "process-items",
+ *     in: $.req.body.items,
+ *     as: "item",
+ *     mode: "parallel",
+ *     concurrency: 5,
+ *     do: [
+ *       { id: "reserve", use: "inventory-reserve", inputs: { sku: $.state.item.sku } },
+ *     ],
+ *   })
+ */
+export function forEach(opts) {
+    if (!opts || typeof opts !== "object") {
+        throw new Error("forEach() requires an options object.");
+    }
+    if (!opts.id || typeof opts.id !== "string") {
+        throw new Error("forEach() requires a non-empty `id` string.");
+    }
+    if (opts.in === undefined) {
+        throw new Error(`forEach("${opts.id}") requires \`in\` (the array source).`);
+    }
+    if (!opts.as || typeof opts.as !== "string") {
+        throw new Error(`forEach("${opts.id}") requires \`as\` (the per-iteration variable name).`);
+    }
+    if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(opts.as)) {
+        throw new Error(`forEach("${opts.id}") \`as\` must be a valid JS identifier (got "${opts.as}").`);
+    }
+    if (!Array.isArray(opts.do) || opts.do.length === 0) {
+        throw new Error(`forEach("${opts.id}") requires \`do\` to be a non-empty array of steps.`);
+    }
+    if (opts.mode !== undefined && opts.mode !== "sequential" && opts.mode !== "parallel") {
+        throw new Error(`forEach("${opts.id}") \`mode\` must be "sequential" or "parallel" when set.`);
+    }
+    if (opts.concurrency !== undefined) {
+        if (typeof opts.concurrency !== "number" || opts.concurrency < 1 || !Number.isInteger(opts.concurrency)) {
+            throw new Error(`forEach("${opts.id}") \`concurrency\` must be a positive integer.`);
+        }
+    }
+    const inExpr = unwrapProxies(opts.in);
+    const innerSteps = unwrapProxies(opts.do);
+    const result = {
+        id: opts.id,
+        forEach: {
+            in: inExpr,
+            as: opts.as,
+            do: innerSteps,
+            ...(opts.mode !== undefined ? { mode: opts.mode } : {}),
+            ...(opts.concurrency !== undefined ? { concurrency: opts.concurrency } : {}),
+        },
+    };
+    if (opts.active === false)
+        result.active = false;
+    if (opts.stop === true)
+        result.stop = true;
+    return result;
+}
+//# sourceMappingURL=forEach.js.map

package/dist/components/forEach.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"forEach.js","sourceRoot":"","sources":["../../src/components/forEach.ts"],"names":[],"mappings":"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"}

package/dist/components/loop.d.ts

@@ -0,0 +1,52 @@
+import type { V2LoopStep, V2Step } from "../types/StepOpts";
+/**
+ * Author-facing options for {@link loop}.
+ *
+ * `while` is a JS expression evaluated against `ctx` BEFORE each
+ * iteration. Loop continues while truthy. The loop counter is exposed
+ * as `ctx.state[<id>Index]` so the condition can reference it
+ * (e.g. `$.state.pollIndex < 5`).
+ *
+ * `maxIterations` is a HARD cap that throws `LoopMaxIterationsError`
+ * when exceeded — a safety net against infinite loops. Default 1000.
+ */
+export interface LoopOpts {
+    /** Stable identifier. The loop counter is exposed as `ctx.state[<id>Index]`. */
+    id: string;
+    /**
+     * JS expression evaluated against ctx before each iteration. Loop
+     * continues while truthy.
+     */
+    while: string | unknown;
+    /** Sub-pipeline run each iteration. */
+    do: V2Step[];
+    /**
+     * Hard cap on iterations. Default 1000 (override via env
+     * `BLOK_LOOP_MAX_ITERATIONS`). Hitting the cap throws
+     * `LoopMaxIterationsError`.
+     */
+    maxIterations?: number;
+    /** Skip this step at runtime. Default true (active). */
+    active?: boolean;
+    /** Halt the workflow after this step completes. */
+    stop?: boolean;
+}
+/**
+ * Create a loop step — while-loop with a hard maxIterations safety cap.
+ *
+ * State mutations made inside the loop body carry forward to the next
+ * iteration, so condition variables can advance. The current iteration
+ * counter (0-based) is at `ctx.state[<id>Index]`.
+ *
+ * @example
+ *   loop({
+ *     id: "poll-job",
+ *     while: '$.state["check-status"].status !== "done"',
+ *     maxIterations: 60,
+ *     do: [
+ *       { id: "wait-tick", wait: { for: "2s" } },
+ *       { id: "check-status", use: "@blokjs/api-call", inputs: { url: "..." } },
+ *     ],
+ *   })
+ */
+export declare function loop(opts: LoopOpts): V2LoopStep;

package/dist/components/loop.js

@@ -0,0 +1,54 @@
+import { unwrapProxies } from "../proxy/$";
+/**
+ * Create a loop step — while-loop with a hard maxIterations safety cap.
+ *
+ * State mutations made inside the loop body carry forward to the next
+ * iteration, so condition variables can advance. The current iteration
+ * counter (0-based) is at `ctx.state[<id>Index]`.
+ *
+ * @example
+ *   loop({
+ *     id: "poll-job",
+ *     while: '$.state["check-status"].status !== "done"',
+ *     maxIterations: 60,
+ *     do: [
+ *       { id: "wait-tick", wait: { for: "2s" } },
+ *       { id: "check-status", use: "@blokjs/api-call", inputs: { url: "..." } },
+ *     ],
+ *   })
+ */
+export function loop(opts) {
+    if (!opts || typeof opts !== "object") {
+        throw new Error("loop() requires an options object.");
+    }
+    if (!opts.id || typeof opts.id !== "string") {
+        throw new Error("loop() requires a non-empty `id` string.");
+    }
+    const whileExpr = unwrapProxies(opts.while);
+    if (typeof whileExpr !== "string" || whileExpr.length === 0) {
+        throw new Error(`loop("${opts.id}") requires a non-empty \`while\` expression. Use a $ proxy path or a plain string expression.`);
+    }
+    if (!Array.isArray(opts.do) || opts.do.length === 0) {
+        throw new Error(`loop("${opts.id}") requires \`do\` to be a non-empty array of steps.`);
+    }
+    if (opts.maxIterations !== undefined) {
+        if (typeof opts.maxIterations !== "number" || opts.maxIterations < 1 || !Number.isInteger(opts.maxIterations)) {
+            throw new Error(`loop("${opts.id}") \`maxIterations\` must be a positive integer.`);
+        }
+    }
+    const innerSteps = unwrapProxies(opts.do);
+    const result = {
+        id: opts.id,
+        loop: {
+            while: whileExpr,
+            do: innerSteps,
+            ...(opts.maxIterations !== undefined ? { maxIterations: opts.maxIterations } : {}),
+        },
+    };
+    if (opts.active === false)
+        result.active = false;
+    if (opts.stop === true)
+        result.stop = true;
+    return result;
+}
+//# sourceMappingURL=loop.js.map

package/dist/components/loop.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loop.js","sourceRoot":"","sources":["../../src/components/loop.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAoC3C;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,IAAI,CAAC,IAAc;IAClC,IAAI,CAAC,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;QACvC,MAAM,IAAI,KAAK,CAAC,oCAAoC,CAAC,CAAC;IACvD,CAAC;IACD,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,OAAO,IAAI,CAAC,EAAE,KAAK,QAAQ,EAAE,CAAC;QAC7C,MAAM,IAAI,KAAK,CAAC,0CAA0C,CAAC,CAAC;IAC7D,CAAC;IACD,MAAM,SAAS,GAAG,aAAa,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAC5C,IAAI,OAAO,SAAS,KAAK,QAAQ,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC7D,MAAM,IAAI,KAAK,CACd,SAAS,IAAI,CAAC,EAAE,gGAAgG,CAChH,CAAC;IACH,CAAC;IACD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,IAAI,CAAC,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACrD,MAAM,IAAI,KAAK,CAAC,SAAS,IAAI,CAAC,EAAE,sDAAsD,CAAC,CAAC;IACzF,CAAC;IACD,IAAI,IAAI,CAAC,aAAa,KAAK,SAAS,EAAE,CAAC;QACtC,IAAI,OAAO,IAAI,CAAC,aAAa,KAAK,QAAQ,IAAI,IAAI,CAAC,aAAa,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,aAAa,CAAC,EAAE,CAAC;YAC/G,MAAM,IAAI,KAAK,CAAC,SAAS,IAAI,CAAC,EAAE,kDAAkD,CAAC,CAAC;QACrF,CAAC;IACF,CAAC;IAED,MAAM,UAAU,GAAG,aAAa,CAAC,IAAI,CAAC,EAAE,CAAa,CAAC;IAEtD,MAAM,MAAM,GAAe;QAC1B,EAAE,EAAE,IAAI,CAAC,EAAE;QACX,IAAI,EAAE;YACL,KAAK,EAAE,SAAS;YAChB,EAAE,EAAE,UAAU;YACd,GAAG,CAAC,IAAI,CAAC,aAAa,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,aAAa,EAAE,IAAI,CAAC,aAAa,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAClF;KACD,CAAC;IACF,IAAI,IAAI,CAAC,MAAM,KAAK,KAAK;QAAG,MAA2C,CAAC,MAAM,GAAG,KAAK,CAAC;IACvF,IAAI,IAAI,CAAC,IAAI,KAAK,IAAI;QAAG,MAAyC,CAAC,IAAI,GAAG,IAAI,CAAC;IAC/E,OAAO,MAAM,CAAC;AACf,CAAC"}

package/dist/components/switchOn.d.ts

@@ -0,0 +1,68 @@
+import type { V2Step, V2SwitchStep } from "../types/StepOpts";
+/**
+ * Author-facing options for {@link switchOn}.
+ *
+ * `on` accepts either a `$` proxy expression (compiles to a `js/...`
+ * string at definition time) or a literal value. Whatever it resolves
+ * to at run time is matched against each `case.when`:
+ *
+ * - `when` is a literal scalar → match if `on === when`
+ * - `when` is an array → match if `array.includes(on)` (group related cases)
+ *
+ * First matching case wins. Subsequent cases are not evaluated. If no
+ * case matches and a `default` block is provided, those steps run instead.
+ */
+export interface SwitchCase {
+    /**
+     * Match value. Literal scalar (number/string/boolean) for strict
+     * equality, or an array for any-of matching. Resolved by the
+     * blueprint mapper before comparison — `$` proxies and `js/...`
+     * strings are evaluated against the live ctx.
+     */
+    when: unknown;
+    /** Sub-pipeline run when this case matches. */
+    do: V2Step[];
+}
+export interface SwitchOpts {
+    /** Stable identifier — visible in traces, referenced as `$.state[id]`. */
+    id: string;
+    /**
+     * Value to match against. `$` proxy expression (`$.req.headers["x-tenant-id"]`),
+     * `js/...` string, or any literal. Resolved at run time before matching.
+     */
+    on: unknown;
+    /** Ordered list of cases. First match wins. */
+    cases: SwitchCase[];
+    /** Fallback sub-pipeline when no case matches. Optional. */
+    default?: V2Step[];
+    /** Skip this step at runtime. Default true (active). */
+    active?: boolean;
+    /** Halt the workflow after this step completes. */
+    stop?: boolean;
+}
+/**
+ * Create a switch step — N-way branch keyed on a value. First matching
+ * case wins; an optional `default` block runs when no case matches.
+ *
+ * Authoring note: the function is named `switchOn` because `switch` is
+ * a JavaScript reserved word. The resulting step object's discriminator
+ * field is `switch`, matching the JSON shape exactly.
+ *
+ * @example
+ *   switchOn({
+ *     id: "route-by-event",
+ *     on: $.req.headers["x-github-event"],
+ *     cases: [
+ *       { when: "push", do: [{ id: "h", subworkflow: "handle-push" }] },
+ *       {
+ *         when: ["pull_request", "pull_request_review"],
+ *         do: [{ id: "h", subworkflow: "handle-pr-event" }],
+ *       },
+ *     ],
+ *     default: [
+ *       { id: "log-unknown", use: "@blokjs/log",
+ *         inputs: { level: "warn", message: "unknown github event" } },
+ *     ],
+ *   })
+ */
+export declare function switchOn(opts: SwitchOpts): V2SwitchStep;

package/dist/components/switchOn.js

@@ -0,0 +1,76 @@
+import { unwrapProxies } from "../proxy/$";
+/**
+ * Create a switch step — N-way branch keyed on a value. First matching
+ * case wins; an optional `default` block runs when no case matches.
+ *
+ * Authoring note: the function is named `switchOn` because `switch` is
+ * a JavaScript reserved word. The resulting step object's discriminator
+ * field is `switch`, matching the JSON shape exactly.
+ *
+ * @example
+ *   switchOn({
+ *     id: "route-by-event",
+ *     on: $.req.headers["x-github-event"],
+ *     cases: [
+ *       { when: "push", do: [{ id: "h", subworkflow: "handle-push" }] },
+ *       {
+ *         when: ["pull_request", "pull_request_review"],
+ *         do: [{ id: "h", subworkflow: "handle-pr-event" }],
+ *       },
+ *     ],
+ *     default: [
+ *       { id: "log-unknown", use: "@blokjs/log",
+ *         inputs: { level: "warn", message: "unknown github event" } },
+ *     ],
+ *   })
+ */
+export function switchOn(opts) {
+    if (!opts || typeof opts !== "object") {
+        throw new Error("switchOn() requires an options object.");
+    }
+    if (!opts.id || typeof opts.id !== "string") {
+        throw new Error("switchOn() requires a non-empty `id` string.");
+    }
+    if (opts.on === undefined) {
+        throw new Error(`switchOn("${opts.id}") requires \`on\` (the value or expression to match against).`);
+    }
+    if (!Array.isArray(opts.cases) || opts.cases.length === 0) {
+        throw new Error(`switchOn("${opts.id}") requires \`cases\` to be a non-empty array.`);
+    }
+    for (let i = 0; i < opts.cases.length; i++) {
+        const c = opts.cases[i];
+        if (!c || typeof c !== "object") {
+            throw new Error(`switchOn("${opts.id}") cases[${i}] must be an object with \`when\` and \`do\`.`);
+        }
+        if (c.when === undefined) {
+            throw new Error(`switchOn("${opts.id}") cases[${i}] is missing \`when\` (the match value).`);
+        }
+        if (!Array.isArray(c.do) || c.do.length === 0) {
+            throw new Error(`switchOn("${opts.id}") cases[${i}] \`do\` must be a non-empty array of steps.`);
+        }
+    }
+    if (opts.default !== undefined) {
+        if (!Array.isArray(opts.default) || opts.default.length === 0) {
+            throw new Error(`switchOn("${opts.id}") \`default\` must be a non-empty array of steps when set.`);
+        }
+    }
+    const onExpr = unwrapProxies(opts.on);
+    const cases = opts.cases.map((c) => ({
+        when: unwrapProxies(c.when),
+        do: unwrapProxies(c.do),
+    }));
+    const result = {
+        id: opts.id,
+        switch: {
+            on: onExpr,
+            cases,
+            ...(opts.default !== undefined ? { default: unwrapProxies(opts.default) } : {}),
+        },
+    };
+    if (opts.active === false)
+        result.active = false;
+    if (opts.stop === true)
+        result.stop = true;
+    return result;
+}
+//# sourceMappingURL=switchOn.js.map

package/dist/components/switchOn.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"switchOn.js","sourceRoot":"","sources":["../../src/components/switchOn.ts"],"names":[],"mappings":"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"}

package/dist/components/tryCatch.d.ts

@@ -0,0 +1,63 @@
+import type { V2Step, V2TryCatchStep } from "../types/StepOpts";
+/**
+ * Author-facing options for {@link tryCatch}.
+ *
+ * `try` and `catch` are required and non-empty; `finally` is optional.
+ *
+ * Inside the `catch` block, `$.error.message`, `$.error.name`, and
+ * `$.error.stack` resolve at run time to the captured error info. In
+ * `try` and `finally`, `$.error` is undefined (the JS-like contract).
+ */
+export interface TryCatchOpts {
+    /** Stable identifier — visible in traces, referenced as `$.state[id]`. */
+    id: string;
+    /** Sub-pipeline run first. If any step throws, control jumps to `catch`. */
+    try: V2Step[];
+    /**
+     * Sub-pipeline run when `try` throws. Has access to `$.error.{message,name,stack}`.
+     * Errors thrown inside `catch` propagate — they DO NOT re-trigger catch.
+     */
+    catch: V2Step[];
+    /**
+     * Sub-pipeline run unconditionally after try/catch. Runs even if `catch`
+     * itself throws. Errors thrown inside `finally` propagate.
+     */
+    finally?: V2Step[];
+    /** Skip this step at runtime. Default true (active). */
+    active?: boolean;
+    /** Halt the workflow after this step completes. */
+    stop?: boolean;
+}
+/**
+ * Create a tryCatch step — JS-like exception handling for sub-pipelines.
+ *
+ * Semantics mirror JavaScript's `try/catch/finally`:
+ * - `try` runs first.
+ * - On throw, `ctx.error` is set and `catch` runs.
+ * - `finally` runs unconditionally (after try success, after caught error,
+ *   and after an uncaught throw from inside `catch`).
+ * - State mutations from any block are visible to subsequent top-level steps.
+ *
+ * @example
+ *   tryCatch({
+ *     id: "signup-saga",
+ *     try: [
+ *       { id: "create", use: "user-create", inputs: { email: $.req.body.email } },
+ *       { id: "notify", use: "email-send", inputs: { to: $.state.create.email } },
+ *     ],
+ *     catch: [
+ *       branch({
+ *         id: "rollback-if-needed",
+ *         when: '$.state.create !== undefined',
+ *         then: [{ id: "del", use: "user-delete", inputs: { userId: $.state.create.id } }],
+ *       }),
+ *       { id: "respond-fail", use: "@blokjs/respond",
+ *         inputs: { status: 500, body: { error: $.error.message } } },
+ *     ],
+ *     finally: [
+ *       { id: "metric", use: "@blokjs/metrics-emit",
+ *         inputs: { event: "signup-attempt" } },
+ *     ],
+ *   })
+ */
+export declare function tryCatch(opts: TryCatchOpts): V2TryCatchStep;

package/dist/components/tryCatch.js

@@ -0,0 +1,68 @@
+import { unwrapProxies } from "../proxy/$";
+/**
+ * Create a tryCatch step — JS-like exception handling for sub-pipelines.
+ *
+ * Semantics mirror JavaScript's `try/catch/finally`:
+ * - `try` runs first.
+ * - On throw, `ctx.error` is set and `catch` runs.
+ * - `finally` runs unconditionally (after try success, after caught error,
+ *   and after an uncaught throw from inside `catch`).
+ * - State mutations from any block are visible to subsequent top-level steps.
+ *
+ * @example
+ *   tryCatch({
+ *     id: "signup-saga",
+ *     try: [
+ *       { id: "create", use: "user-create", inputs: { email: $.req.body.email } },
+ *       { id: "notify", use: "email-send", inputs: { to: $.state.create.email } },
+ *     ],
+ *     catch: [
+ *       branch({
+ *         id: "rollback-if-needed",
+ *         when: '$.state.create !== undefined',
+ *         then: [{ id: "del", use: "user-delete", inputs: { userId: $.state.create.id } }],
+ *       }),
+ *       { id: "respond-fail", use: "@blokjs/respond",
+ *         inputs: { status: 500, body: { error: $.error.message } } },
+ *     ],
+ *     finally: [
+ *       { id: "metric", use: "@blokjs/metrics-emit",
+ *         inputs: { event: "signup-attempt" } },
+ *     ],
+ *   })
+ */
+export function tryCatch(opts) {
+    if (!opts || typeof opts !== "object") {
+        throw new Error("tryCatch() requires an options object.");
+    }
+    if (!opts.id || typeof opts.id !== "string") {
+        throw new Error("tryCatch() requires a non-empty `id` string.");
+    }
+    if (!Array.isArray(opts.try) || opts.try.length === 0) {
+        throw new Error(`tryCatch("${opts.id}") requires \`try\` to be a non-empty array of steps.`);
+    }
+    if (!Array.isArray(opts.catch) || opts.catch.length === 0) {
+        throw new Error(`tryCatch("${opts.id}") requires \`catch\` to be a non-empty array of steps.`);
+    }
+    if (opts.finally !== undefined) {
+        if (!Array.isArray(opts.finally) || opts.finally.length === 0) {
+            throw new Error(`tryCatch("${opts.id}") \`finally\` must be a non-empty array of steps when set.`);
+        }
+    }
+    const tryBlock = unwrapProxies(opts.try);
+    const catchBlock = unwrapProxies(opts.catch);
+    const result = {
+        id: opts.id,
+        tryCatch: {
+            try: tryBlock,
+            catch: catchBlock,
+            ...(opts.finally !== undefined ? { finally: unwrapProxies(opts.finally) } : {}),
+        },
+    };
+    if (opts.active === false)
+        result.active = false;
+    if (opts.stop === true)
+        result.stop = true;
+    return result;
+}
+//# sourceMappingURL=tryCatch.js.map

package/dist/components/tryCatch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tryCatch.js","sourceRoot":"","sources":["../../src/components/tryCatch.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAiC3C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,UAAU,QAAQ,CAAC,IAAkB;IAC1C,IAAI,CAAC,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;QACvC,MAAM,IAAI,KAAK,CAAC,wCAAwC,CAAC,CAAC;IAC3D,CAAC;IACD,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,OAAO,IAAI,CAAC,EAAE,KAAK,QAAQ,EAAE,CAAC;QAC7C,MAAM,IAAI,KAAK,CAAC,8CAA8C,CAAC,CAAC;IACjE,CAAC;IACD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC,GAAG,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACvD,MAAM,IAAI,KAAK,CAAC,aAAa,IAAI,CAAC,EAAE,uDAAuD,CAAC,CAAC;IAC9F,CAAC;IACD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC3D,MAAM,IAAI,KAAK,CAAC,aAAa,IAAI,CAAC,EAAE,yDAAyD,CAAC,CAAC;IAChG,CAAC;IACD,IAAI,IAAI,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;QAChC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,IAAI,CAAC,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC/D,MAAM,IAAI,KAAK,CAAC,aAAa,IAAI,CAAC,EAAE,6DAA6D,CAAC,CAAC;QACpG,CAAC;IACF,CAAC;IAED,MAAM,QAAQ,GAAG,aAAa,CAAC,IAAI,CAAC,GAAG,CAAa,CAAC;IACrD,MAAM,UAAU,GAAG,aAAa,CAAC,IAAI,CAAC,KAAK,CAAa,CAAC;IACzD,MAAM,MAAM,GAAmB;QAC9B,EAAE,EAAE,IAAI,CAAC,EAAE;QACX,QAAQ,EAAE;YACT,GAAG,EAAE,QAAQ;YACb,KAAK,EAAE,UAAU;YACjB,GAAG,CAAC,IAAI,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,aAAa,CAAC,IAAI,CAAC,OAAO,CAAa,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAC3F;KACD,CAAC;IACF,IAAI,IAAI,CAAC,MAAM,KAAK,KAAK;QAAG,MAA+C,CAAC,MAAM,GAAG,KAAK,CAAC;IAC3F,IAAI,IAAI,CAAC,IAAI,KAAK,IAAI;QAAG,MAA6C,CAAC,IAAI,GAAG,IAAI,CAAC;IACnF,OAAO,MAAM,CAAC;AACf,CAAC"}

package/dist/components/workflowV2.d.ts

@@ -52,7 +52,7 @@ export interface WorkflowV2Builder {
  * - **No chaining.** The full workflow is a single object literal —
  *   exactly what JSON workflows look like.
  * - **No separate `nodes{}` map.** `inputs` lives on each step.
- * - **No `set_var: true`** — every step's output auto-stores in `ctx.state`.
+ * - **Default-store** — every step's output auto-stores in `ctx.state`.
  *   Opt out with `ephemeral: true`. Multi-output: `spread: true`. Rename:
  *   `as: "<name>"`.
  * - **`branch({when, then, else})`** replaces `addCondition + AddIf + AddElse`.

package/dist/components/workflowV2.js

@@ -11,7 +11,7 @@ import { TriggersSchema, validateTriggerConfig } from "../types/TriggerOpts";
  * - **No chaining.** The full workflow is a single object literal —
  *   exactly what JSON workflows look like.
  * - **No separate `nodes{}` map.** `inputs` lives on each step.
- * - **No `set_var: true`** — every step's output auto-stores in `ctx.state`.
+ * - **Default-store** — every step's output auto-stores in `ctx.state`.
  *   Opt out with `ephemeral: true`. Multi-output: `spread: true`. Rename:
  *   `as: "<name>"`.
  * - **`branch({when, then, else})`** replaces `addCondition + AddIf + AddElse`.