@blokjs/helper 0.4.0 → 0.6.0

package/dist/workflow.schema.json

@@ -35,7 +35,12 @@
 					"websocket"
 				]
 			},
-			"description": "Trigger configuration. Most workflows use { http: { method: 'GET' } }. See TRIGGER_SCHEMAS for per-kind shapes."
+			"description": "Trigger configuration. Most workflows use { http: { method: 'GET' } }. Optional ONLY when `middleware: true` is set — middleware-only workflows are invoked from another workflow's `trigger.http.middleware: [...]` array and don't have a public route of their own. See TRIGGER_SCHEMAS for per-kind shapes."
+		},
+		"middleware": {
+			"type": "boolean",
+			"const": true,
+			"description": "v0.5 — when true, this workflow is registered as middleware and is NOT exposed as a public HTTP route. It's invoked by another workflow that lists this one's `name` in its `trigger.http.middleware: [...]` array. Middleware runs on the parent ctx (state mutations carry forward) and can short-circuit by setting `ctx.response` and using a step with `stop: true`. Middleware-only workflows MAY omit `trigger`."
 		},
 		"steps": {
 			"type": "array",
@@ -99,7 +104,7 @@
 							"subworkflow": {
 								"type": "string",
 								"minLength": 1,
-								"description": "Name of the workflow to invoke. Looked up in the WorkflowRegistry at run time — must match the `name:` field of an HTTP-loaded or manually-registered workflow."
+								"description": "Name of the workflow to invoke. Looked up in the WorkflowRegistry at run time. **Literal names** (`\"send-receipt-email\"`) are matched directly. **Polymorphic expressions** (`\"$.req.body.kind\"`, `\"js/ctx.req.body.kind\"`) resolve against the live ctx at dispatch time — pair with `allowList` to constrain which workflows the expression may resolve to."
 							},
 							"inputs": {
 								"type": "object",
@@ -185,6 +190,22 @@
 									}
 								],
 								"description": "OPTIONAL. Per-attempt execution timeout. Caps the synchronous wait for `wait: true` sub-workflows. No-op for `wait: false` (parent returns immediately; the child's max-duration is the child's concern). Number (ms) or duration string. On final-attempt timeout, the run auto-flips to `\"timedOut\"`."
+							},
+							"allowList": {
+								"type": "array",
+								"items": {
+									"type": "string",
+									"minLength": 1
+								},
+								"description": "Exact-match allow-list for polymorphic dispatch. When the resolved workflow name (after any `namespace` prefix is applied) is not in this array, the dispatch is rejected at run time with a structured error. Strongly recommended when `subworkflow` is an expression (`$.<path>` or `js/...`) so a malicious or buggy ctx value can't dispatch arbitrary workflows. Ignored for literal names (they don't need the guard)."
+							},
+							"dispatch": {
+								"type": "string",
+								"enum": [
+									"in-process",
+									"http-self"
+								],
+								"description": "G2 (v0.6) — dispatch strategy. `in-process` (default) invokes the child workflow in the same Node process — synchronous when `wait: true`, `setImmediate`-based when `wait: false`. `http-self` makes an HTTP request to the deployment's own base URL (`BLOK_SELF_BASE_URL` env var, defaults to `http://localhost:${PORT || 4000}`). Use `http-self` when you want each child run to land on a different process in a horizontally-scaled deployment, or to fully isolate child execution from the parent's call stack. The child must have an HTTP trigger; a runtime error is thrown otherwise. Lineage (parentRunId / parentNodeRunId) is preserved across the HTTP hop via `X-Blok-Parent-Run-Id` / `X-Blok-Parent-Node-Run-Id` headers."
 							}
 						},
 						"required": [
@@ -265,6 +286,226 @@
 						],
 						"additionalProperties": false
 					},
+					{
+						"type": "object",
+						"properties": {
+							"id": {
+								"type": "string",
+								"minLength": 1,
+								"description": "Stable identifier for the forEach step. Visible in traces."
+							},
+							"forEach": {
+								"type": "object",
+								"properties": {
+									"in": {
+										"description": "Array source. Literal expression string (`'$.state.items'`) or `$` proxy expression."
+									},
+									"as": {
+										"type": "string",
+										"minLength": 1,
+										"pattern": "^[a-zA-Z_][a-zA-Z0-9_]*$",
+										"description": "Per-iteration variable name. Each iteration sets ctx.state[as] = item and ctx.state[as+'Index'] = i."
+									},
+									"mode": {
+										"type": "string",
+										"enum": [
+											"sequential",
+											"parallel"
+										],
+										"description": "Execution mode. `sequential` (default) awaits each iteration; `parallel` runs with bounded concurrency."
+									},
+									"concurrency": {
+										"type": "integer",
+										"minimum": 1,
+										"maximum": 1000,
+										"description": "Max concurrent inner pipelines when `mode: 'parallel'`. Default 10."
+									},
+									"do": {
+										"type": "array",
+										"items": {},
+										"minItems": 1,
+										"description": "Sub-pipeline run for each item."
+									}
+								},
+								"required": [
+									"as",
+									"do"
+								],
+								"additionalProperties": false,
+								"description": "forEach configuration."
+							},
+							"active": {
+								"type": "boolean"
+							},
+							"stop": {
+								"type": "boolean"
+							}
+						},
+						"required": [
+							"id",
+							"forEach"
+						],
+						"additionalProperties": false
+					},
+					{
+						"type": "object",
+						"properties": {
+							"id": {
+								"type": "string",
+								"minLength": 1,
+								"description": "Stable identifier for the loop step. Visible in traces."
+							},
+							"loop": {
+								"type": "object",
+								"properties": {
+									"while": {
+										"type": "string",
+										"minLength": 1,
+										"description": "JS expression evaluated against ctx before each iteration. Loop continues while truthy."
+									},
+									"maxIterations": {
+										"type": "integer",
+										"minimum": 1,
+										"description": "Hard safety cap on iterations. Default 1000 (override via env BLOK_LOOP_MAX_ITERATIONS). Hitting the cap throws LoopMaxIterationsError."
+									},
+									"do": {
+										"type": "array",
+										"items": {},
+										"minItems": 1,
+										"description": "Sub-pipeline run each iteration."
+									}
+								},
+								"required": [
+									"while",
+									"do"
+								],
+								"additionalProperties": false,
+								"description": "loop configuration."
+							},
+							"active": {
+								"type": "boolean"
+							},
+							"stop": {
+								"type": "boolean"
+							}
+						},
+						"required": [
+							"id",
+							"loop"
+						],
+						"additionalProperties": false
+					},
+					{
+						"type": "object",
+						"properties": {
+							"id": {
+								"type": "string",
+								"minLength": 1,
+								"description": "Stable identifier for the switch step. Visible in traces."
+							},
+							"switch": {
+								"type": "object",
+								"properties": {
+									"on": {
+										"description": "Value to match against. Literal, `$` proxy expression, or `js/...` string. Resolved by the blueprint mapper before matching."
+									},
+									"cases": {
+										"type": "array",
+										"items": {
+											"type": "object",
+											"properties": {
+												"when": {
+													"description": "Match value. Literal scalar (number/string/boolean) for `on === when` matching, or an array for `array.includes(on)` matching."
+												},
+												"do": {
+													"type": "array",
+													"items": {},
+													"minItems": 1,
+													"description": "Sub-pipeline run when this case matches."
+												}
+											},
+											"required": [
+												"do"
+											],
+											"additionalProperties": false
+										},
+										"minItems": 1,
+										"description": "Ordered list of cases. First match wins."
+									},
+									"default": {
+										"type": "array",
+										"items": {},
+										"description": "Fallback sub-pipeline when no case matches. Optional."
+									}
+								},
+								"required": [
+									"cases"
+								],
+								"additionalProperties": false,
+								"description": "switch configuration."
+							},
+							"active": {
+								"type": "boolean"
+							},
+							"stop": {
+								"type": "boolean"
+							}
+						},
+						"required": [
+							"id",
+							"switch"
+						],
+						"additionalProperties": false
+					},
+					{
+						"type": "object",
+						"properties": {
+							"id": {
+								"type": "string",
+								"minLength": 1,
+								"description": "Stable identifier for the tryCatch step. Visible in traces."
+							},
+							"tryCatch": {
+								"type": "object",
+								"properties": {
+									"try": {
+										"type": "array",
+										"items": {},
+										"minItems": 1,
+										"description": "Sub-pipeline run first. If any step throws, control jumps to `catch`."
+									},
+									"catch": {
+										"type": "array",
+										"items": {},
+										"minItems": 1,
+										"description": "Sub-pipeline run when `try` throws. Has access to `$.error` (message, name, stack). Errors here propagate — they do NOT re-trigger catch."
+									},
+									"finally": {
+										"type": "array",
+										"items": {},
+										"description": "Sub-pipeline run unconditionally after try/catch. Runs even if `catch` itself throws. Errors here propagate."
+									}
+								},
+								"required": [
+									"try",
+									"catch"
+								],
+								"additionalProperties": false,
+								"description": "tryCatch configuration."
+							},
+							"active": {
+								"type": "boolean"
+							},
+							"stop": {
+								"type": "boolean"
+							}
+						},
+						"required": [
+							"id",
+							"tryCatch"
+						],
+						"additionalProperties": false
+					},
 					{
 						"type": "object",
 						"properties": {
@@ -398,10 +639,6 @@
 									}
 								],
 								"description": "OPTIONAL. Per-attempt execution timeout. Number (ms) or duration string ('30s', '5m', '500ms'). When the step's `step.process()` exceeds this duration, the attempt fails with a StepTimeoutError. Pairs with `retry` — each attempt gets its own timeout (total budget = maxDuration × maxAttempts). On final-attempt timeout, the run auto-flips to `\"timedOut\"` status (distinct from `\"failed\"` so SLA dashboards can separate timeouts from logic failures)."
-							},
-							"set_var": {
-								"type": "boolean",
-								"description": "@deprecated v2 default-stores every step's output. `set_var: true` is a no-op; `set_var: false` is normalized to `ephemeral: true`."
 							}
 						},
 						"required": [
@@ -419,7 +656,6 @@
 	"required": [
 		"name",
 		"version",
-		"trigger",
 		"steps"
 	],
 	"additionalProperties": false

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@blokjs/helper",
-	"version": "0.4.0",
+	"version": "0.6.0",
 	"description": "",
 	"engines": {
 		"node": ">=18.0.0"