@blokjs/helper 0.2.1 → 0.6.0

package/dist/components/AddElse.d.ts

@@ -13,18 +13,27 @@ 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"]>>;
+        active: z.ZodOptional<z.ZodBoolean>;
+        stop: z.ZodOptional<z.ZodBoolean>;
+        stream_logs: z.ZodOptional<z.ZodBoolean>;
     }, "strip", z.ZodTypeAny, {
         name: string;
         node: string;
         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;
+        active?: boolean | undefined;
+        stop?: boolean | undefined;
+        stream_logs?: boolean | undefined;
     }, {
         name: string;
         node: string;
         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;
+        active?: boolean | undefined;
+        stop?: boolean | undefined;
+        stream_logs?: boolean | undefined;
     }>, "many">>;
 }, "strip", z.ZodTypeAny, {
     type: "if" | "else";
@@ -34,6 +43,9 @@ 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;
+        active?: boolean | undefined;
+        stop?: boolean | undefined;
+        stream_logs?: boolean | undefined;
     }[] | undefined;
 }, {
     type: "if" | "else";
@@ -43,6 +55,9 @@ 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;
+        active?: boolean | undefined;
+        stop?: boolean | undefined;
+        stream_logs?: boolean | undefined;
     }[] | undefined;
 }>;
 export type ConditionElseOpts = z.infer<typeof ConditionElseSchema>;

package/dist/components/AddIf.d.ts

@@ -16,18 +16,27 @@ 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"]>>;
+        active: z.ZodOptional<z.ZodBoolean>;
+        stop: z.ZodOptional<z.ZodBoolean>;
+        stream_logs: z.ZodOptional<z.ZodBoolean>;
     }, "strip", z.ZodTypeAny, {
         name: string;
         node: string;
         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;
+        active?: boolean | undefined;
+        stop?: boolean | undefined;
+        stream_logs?: boolean | undefined;
     }, {
         name: string;
         node: string;
         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;
+        active?: boolean | undefined;
+        stop?: boolean | undefined;
+        stream_logs?: boolean | undefined;
     }>, "many">>;
 }, "strip", z.ZodTypeAny, {
     type: "if" | "else";
@@ -38,6 +47,9 @@ 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;
+        active?: boolean | undefined;
+        stop?: boolean | undefined;
+        stream_logs?: boolean | undefined;
     }[] | undefined;
 }, {
     type: "if" | "else";
@@ -48,6 +60,9 @@ 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;
+        active?: boolean | undefined;
+        stop?: boolean | undefined;
+        stream_logs?: boolean | undefined;
     }[] | undefined;
 }>;
 export type ConditionOpts = z.infer<typeof ConditionSchema>;

package/dist/components/StepNode.d.ts

@@ -1,5 +1,11 @@
 import { type StepConditionOpts, type StepOpts } from "../types/StepOpts";
 import HelperResponse from "./HelperResponse";
+/**
+ * Builder step that adds workflow steps and conditional branches.
+ *
+ * Each call returns a new {@link StepNode} carrying the accumulated config
+ * so workflow definitions remain immutable from the outside.
+ */
 export default class StepNode extends HelperResponse {
     addStep(config: StepOpts): StepNode;
     addCondition(conditions: StepConditionOpts): StepNode;

package/dist/components/StepNode.js

@@ -1,5 +1,11 @@
 import { StepConditionSchema, StepOptsSchema, } from "../types/StepOpts";
 import HelperResponse from "./HelperResponse";
+/**
+ * Builder step that adds workflow steps and conditional branches.
+ *
+ * Each call returns a new {@link StepNode} carrying the accumulated config
+ * so workflow definitions remain immutable from the outside.
+ */
 export default class StepNode extends HelperResponse {
     addStep(config) {
         StepOptsSchema.parse(config);
@@ -13,6 +19,8 @@ export default class StepNode extends HelperResponse {
             node: config.node,
             type: config.type,
             runtime: config.runtime,
+            active: config.active,
+            stop: config.stop,
         });
         const helperResponse = new StepNode();
         helperResponse.setConfig(this._config);

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,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;SACvB,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/Trigger.d.ts

@@ -1,8 +1,16 @@
-import { type CronTriggerOpts, type PubSubTriggerOpts, type QueueTriggerOpts, type SSETriggerOpts, type TriggerOpts, type WebSocketTriggerOpts, type WebhookTriggerOpts, type WorkerTriggerOpts } from "../types/TriggerOpts";
+import { type CronTriggerOpts, type HttpTriggerOpts, type PubSubTriggerOpts, type QueueTriggerOpts, type SSETriggerOpts, type WebSocketTriggerOpts, type WebhookTriggerOpts, type WorkerTriggerOpts } from "../types/TriggerOpts";
 import HelperResponse from "./HelperResponse";
 import StepNode from "./StepNode";
+/**
+ * Builder step that attaches a trigger to a workflow.
+ *
+ * Returned by {@link Workflow}; chains into {@link StepNode} via
+ * {@link Trigger.addTrigger}. Type-safe overloads constrain the `config`
+ * argument shape per trigger kind; {@link validateTriggerConfig} runs the
+ * matching Zod schema at call time.
+ */
 export default class Trigger extends HelperResponse {
-    addTrigger(name: "http", config: TriggerOpts): StepNode;
+    addTrigger(name: "http", config: HttpTriggerOpts): StepNode;
     addTrigger(name: "queue", config: QueueTriggerOpts): StepNode;
     addTrigger(name: "pubsub", config: PubSubTriggerOpts): StepNode;
     addTrigger(name: "cron", config: CronTriggerOpts): StepNode;

package/dist/components/Trigger.js

@@ -1,13 +1,24 @@
-import { TriggerOptsSchema, TriggersSchema, } from "../types/TriggerOpts";
+import { TriggersSchema, validateTriggerConfig, } from "../types/TriggerOpts";
 import HelperResponse from "./HelperResponse";
 import StepNode from "./StepNode";
+/**
+ * Builder step that attaches a trigger to a workflow.
+ *
+ * Returned by {@link Workflow}; chains into {@link StepNode} via
+ * {@link Trigger.addTrigger}. Type-safe overloads constrain the `config`
+ * argument shape per trigger kind; {@link validateTriggerConfig} runs the
+ * matching Zod schema at call time.
+ */
 export default class Trigger extends HelperResponse {
     addTrigger(name, config) {
+        // Validate the trigger NAME first so callers get a clear error for typos
+        // before we try to dispatch to a schema.
         TriggersSchema.parse(name);
-        if (name === "http" && config) {
-            TriggerOptsSchema.parse(config);
-        }
-        this._config.trigger = { [name]: config || {} };
+        // Dispatch to the per-kind schema. Returns the parsed config (with
+        // defaults applied) for typed triggers, or the input config for
+        // grpc/manual which have no schema.
+        const validated = validateTriggerConfig(name, config);
+        this._config.trigger = { [name]: validated };
         const helperResponse = new StepNode();
         helperResponse.setConfig(this._config);
         return helperResponse;

package/dist/components/Trigger.js.map

@@ -1 +1 @@
-{"version":3,"file":"Trigger.js","sourceRoot":"","sources":["../../src/components/Trigger.ts"],"names":[],"mappings":"AAAA,OAAO,EAON,iBAAiB,EAEjB,cAAc,GAId,MAAM,sBAAsB,CAAC;AAC9B,OAAO,cAAc,MAAM,kBAAkB,CAAC;AAC9C,OAAO,QAAQ,MAAM,YAAY,CAAC;AAElC,MAAM,CAAC,OAAO,OAAO,OAAQ,SAAQ,cAAc;IAWlD,UAAU,CAAyB,IAAO,EAAE,MAA4B;QACvE,cAAc,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAE3B,IAAI,IAAI,KAAK,MAAM,IAAI,MAAM,EAAE,CAAC;YAC/B,iBAAiB,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;QACjC,CAAC;QACD,IAAI,CAAC,OAAO,CAAC,OAAO,GAAG,EAAE,CAAC,IAAI,CAAC,EAAE,MAAM,IAAI,EAAE,EAAE,CAAC;QAEhD,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":"Trigger.js","sourceRoot":"","sources":["../../src/components/Trigger.ts"],"names":[],"mappings":"AAAA,OAAO,EAQN,cAAc,EAId,qBAAqB,GACrB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,cAAc,MAAM,kBAAkB,CAAC;AAC9C,OAAO,QAAQ,MAAM,YAAY,CAAC;AAElC;;;;;;;GAOG;AACH,MAAM,CAAC,OAAO,OAAO,OAAQ,SAAQ,cAAc;IAUlD,UAAU,CAAyB,IAAO,EAAE,MAA4B;QACvE,yEAAyE;QACzE,yCAAyC;QACzC,cAAc,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAE3B,mEAAmE;QACnE,gEAAgE;QAChE,oCAAoC;QACpC,MAAM,SAAS,GAAG,qBAAqB,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QACtD,IAAI,CAAC,OAAO,CAAC,OAAO,GAAG,EAAE,CAAC,IAAI,CAAC,EAAE,SAAS,EAAE,CAAC;QAE7C,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/branch.d.ts

@@ -0,0 +1,44 @@
+import type { V2BranchStep, V2Step } from "../types/StepOpts";
+/**
+ * Author-facing options for {@link branch}.
+ *
+ * `when` accepts either a plain string (`"$.req.method === 'POST'"`) or
+ * a `$` proxy expression that will compile to a string at definition
+ * time (`$.req.method`). Note that JavaScript's `===` operator can't be
+ * intercepted, so equality comparisons must be expressed as strings.
+ */
+export interface BranchOpts {
+    /** Stable identifier — visible in traces, referenced as `$.state[id]`. */
+    id: string;
+    /** JS condition. Truthy → run `then`; falsy → run `else`. */
+    when: string | unknown;
+    then: V2Step[];
+    /** Optional. Steps to run when `when` is falsy. */
+    else?: V2Step[];
+    /** Skip this branch step at runtime. Default true (active). */
+    active?: boolean;
+    /** Halt the workflow after this branch step completes. */
+    stop?: boolean;
+}
+/**
+ * Create a branch step — a step that runs one of two sub-pipelines based
+ * on a JS condition.
+ *
+ * Compiles down to today's `@blokjs/if-else` flow node at workflow load
+ * time, so the runner core needs no change. Authors get a single primitive
+ * with the same shape as a regular step: `{ id, ... }`.
+ *
+ * @example
+ *   branch({
+ *     id: "route",
+ *     when: '$.req.method === "POST"',
+ *     then: [{ id: "create", use: "...", inputs: {...} }],
+ *     else: [{ id: "read",   use: "...", inputs: {...} }]
+ *   })
+ *
+ * @example
+ *   // `when` accepts a $ proxy expression — compiles to a string at
+ *   // definition time, so `js/ctx.req.query.kind` lands in the workflow.
+ *   branch({ id: "route-by-kind", when: $.req.query.kind, then: [...] })
+ */
+export declare function branch(opts: BranchOpts): V2BranchStep;

package/dist/components/branch.js

@@ -0,0 +1,57 @@
+import { unwrapProxies } from "../proxy/$";
+/**
+ * Create a branch step — a step that runs one of two sub-pipelines based
+ * on a JS condition.
+ *
+ * Compiles down to today's `@blokjs/if-else` flow node at workflow load
+ * time, so the runner core needs no change. Authors get a single primitive
+ * with the same shape as a regular step: `{ id, ... }`.
+ *
+ * @example
+ *   branch({
+ *     id: "route",
+ *     when: '$.req.method === "POST"',
+ *     then: [{ id: "create", use: "...", inputs: {...} }],
+ *     else: [{ id: "read",   use: "...", inputs: {...} }]
+ *   })
+ *
+ * @example
+ *   // `when` accepts a $ proxy expression — compiles to a string at
+ *   // definition time, so `js/ctx.req.query.kind` lands in the workflow.
+ *   branch({ id: "route-by-kind", when: $.req.query.kind, then: [...] })
+ */
+export function branch(opts) {
+    if (!opts || typeof opts !== "object") {
+        throw new Error("branch() requires an options object.");
+    }
+    if (!opts.id || typeof opts.id !== "string") {
+        throw new Error("branch() requires a non-empty `id` string.");
+    }
+    const when = unwrapProxies(opts.when);
+    if (typeof when !== "string" || when.length === 0) {
+        throw new Error(`branch("${opts.id}") requires a non-empty \`when\` string. Use a $ proxy path (e.g. $.req.query.kind) or a plain expression (e.g. '$.req.method === "POST"'). For equality comparisons, use a plain string — JavaScript's === operator can't be intercepted by the proxy.`);
+    }
+    if (!Array.isArray(opts.then)) {
+        throw new Error(`branch("${opts.id}") requires \`then\` to be an array of steps.`);
+    }
+    if (opts.else !== undefined && !Array.isArray(opts.else)) {
+        throw new Error(`branch("${opts.id}") \`else\` must be an array of steps when set.`);
+    }
+    // Walk the steps to convert any inline proxies in their inputs.
+    const thenSteps = unwrapProxies(opts.then);
+    const elseSteps = opts.else ? unwrapProxies(opts.else) : undefined;
+    const result = {
+        id: opts.id,
+        branch: {
+            when,
+            then: thenSteps,
+            ...(elseSteps ? { else: elseSteps } : {}),
+        },
+    };
+    if (opts.active === false)
+        result.active = false;
+    if (opts.stop === true)
+        result.stop = true;
+    return result;
+}
+//# sourceMappingURL=branch.js.map

package/dist/components/branch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"branch.js","sourceRoot":"","sources":["../../src/components/branch.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAyB3C;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,MAAM,CAAC,IAAgB;IACtC,IAAI,CAAC,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;QACvC,MAAM,IAAI,KAAK,CAAC,sCAAsC,CAAC,CAAC;IACzD,CAAC;IACD,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,OAAO,IAAI,CAAC,EAAE,KAAK,QAAQ,EAAE,CAAC;QAC7C,MAAM,IAAI,KAAK,CAAC,4CAA4C,CAAC,CAAC;IAC/D,CAAC;IACD,MAAM,IAAI,GAAG,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACtC,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACnD,MAAM,IAAI,KAAK,CACd,WAAW,IAAI,CAAC,EAAE,yPAAyP,CAC3Q,CAAC;IACH,CAAC;IACD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QAC/B,MAAM,IAAI,KAAK,CAAC,WAAW,IAAI,CAAC,EAAE,+CAA+C,CAAC,CAAC;IACpF,CAAC;IACD,IAAI,IAAI,CAAC,IAAI,KAAK,SAAS,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QAC1D,MAAM,IAAI,KAAK,CAAC,WAAW,IAAI,CAAC,EAAE,iDAAiD,CAAC,CAAC;IACtF,CAAC;IAED,gEAAgE;IAChE,MAAM,SAAS,GAAG,aAAa,CAAC,IAAI,CAAC,IAAI,CAAa,CAAC;IACvD,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,CAAE,aAAa,CAAC,IAAI,CAAC,IAAI,CAAc,CAAC,CAAC,CAAC,SAAS,CAAC;IAEjF,MAAM,MAAM,GAAiB;QAC5B,EAAE,EAAE,IAAI,CAAC,EAAE;QACX,MAAM,EAAE;YACP,IAAI;YACJ,IAAI,EAAE,SAAS;YACf,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACzC;KACD,CAAC;IACF,IAAI,IAAI,CAAC,MAAM,KAAK,KAAK;QAAG,MAA6C,CAAC,MAAM,GAAG,KAAK,CAAC;IACzF,IAAI,IAAI,CAAC,IAAI,KAAK,IAAI;QAAG,MAA2C,CAAC,IAAI,GAAG,IAAI,CAAC;IACjF,OAAO,MAAM,CAAC;AACf,CAAC"}

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":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAsC3C;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,OAAO,CAAC,IAAiB;IACxC,IAAI,CAAC,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;QACvC,MAAM,IAAI,KAAK,CAAC,uCAAuC,CAAC,CAAC;IAC1D,CAAC;IACD,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,OAAO,IAAI,CAAC,EAAE,KAAK,QAAQ,EAAE,CAAC;QAC7C,MAAM,IAAI,KAAK,CAAC,6CAA6C,CAAC,CAAC;IAChE,CAAC;IACD,IAAI,IAAI,CAAC,EAAE,KAAK,SAAS,EAAE,CAAC;QAC3B,MAAM,IAAI,KAAK,CAAC,YAAY,IAAI,CAAC,EAAE,wCAAwC,CAAC,CAAC;IAC9E,CAAC;IACD,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,OAAO,IAAI,CAAC,EAAE,KAAK,QAAQ,EAAE,CAAC;QAC7C,MAAM,IAAI,KAAK,CAAC,YAAY,IAAI,CAAC,EAAE,uDAAuD,CAAC,CAAC;IAC7F,CAAC;IACD,IAAI,CAAC,0BAA0B,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,CAAC;QAC/C,MAAM,IAAI,KAAK,CAAC,YAAY,IAAI,CAAC,EAAE,iDAAiD,IAAI,CAAC,EAAE,KAAK,CAAC,CAAC;IACnG,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,YAAY,IAAI,CAAC,EAAE,sDAAsD,CAAC,CAAC;IAC5F,CAAC;IACD,IAAI,IAAI,CAAC,IAAI,KAAK,SAAS,IAAI,IAAI,CAAC,IAAI,KAAK,YAAY,IAAI,IAAI,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;QACvF,MAAM,IAAI,KAAK,CAAC,YAAY,IAAI,CAAC,EAAE,0DAA0D,CAAC,CAAC;IAChG,CAAC;IACD,IAAI,IAAI,CAAC,WAAW,KAAK,SAAS,EAAE,CAAC;QACpC,IAAI,OAAO,IAAI,CAAC,WAAW,KAAK,QAAQ,IAAI,IAAI,CAAC,WAAW,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,WAAW,CAAC,EAAE,CAAC;YACzG,MAAM,IAAI,KAAK,CAAC,YAAY,IAAI,CAAC,EAAE,gDAAgD,CAAC,CAAC;QACtF,CAAC;IACF,CAAC;IAED,MAAM,MAAM,GAAG,aAAa,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACtC,MAAM,UAAU,GAAG,aAAa,CAAC,IAAI,CAAC,EAAE,CAAa,CAAC;IAEtD,MAAM,MAAM,GAAkB;QAC7B,EAAE,EAAE,IAAI,CAAC,EAAE;QACX,OAAO,EAAE;YACR,EAAE,EAAE,MAAM;YACV,EAAE,EAAE,IAAI,CAAC,EAAE;YACX,EAAE,EAAE,UAAU;YACd,GAAG,CAAC,IAAI,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACvD,GAAG,CAAC,IAAI,CAAC,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAC5E;KACD,CAAC;IACF,IAAI,IAAI,CAAC,MAAM,KAAK,KAAK;QAAG,MAA8C,CAAC,MAAM,GAAG,KAAK,CAAC;IAC1F,IAAI,IAAI,CAAC,IAAI,KAAK,IAAI;QAAG,MAA4C,CAAC,IAAI,GAAG,IAAI,CAAC;IAClF,OAAO,MAAM,CAAC;AACf,CAAC"}

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;