@blokjs/helper 0.2.1 → 0.6.0

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

@@ -0,0 +1,83 @@
+import { type V2Step } from "../types/StepOpts";
+import type { WorkflowV2 } from "../types/WorkflowOpts";
+/**
+ * V2 workflow author input — strict TypeScript shape with the user-facing
+ * fields the lowercase `workflow()` factory accepts.
+ */
+export interface WorkflowOpts {
+    /** Workflow display name. Min 3 characters. Shown in Studio. */
+    name: string;
+    /** Semantic version (x.x.x). Used for trace recording and audit. */
+    version: string;
+    /** What this workflow does. Optional but recommended. */
+    description?: string;
+    /**
+     * Trigger configuration. Most workflows use a single key:
+     *   `{ http: { method: "GET" } }`
+     *   `{ cron: { schedule: "0 * * * *" } }`
+     *   `{ queue: { provider: "kafka", topic: "..." } }`
+     *
+     * See `TRIGGER_SCHEMAS` for per-kind shapes. Validated per-kind at
+     * factory time.
+     */
+    trigger: Record<string, unknown>;
+    /** Pipeline of steps to execute in order. At least one required. */
+    steps: V2Step[];
+}
+/**
+ * The shape returned by `workflow()`. Tagged with `_blokV2: true` so the
+ * scanner / loader can detect a v2-shape default export and route it
+ * through the v1→v2 normalizer cleanly. The internal `_config` field
+ * mirrors the legacy v1 builder output for back-compat with code that
+ * already reads `step._config.trigger` etc.
+ */
+export interface WorkflowV2Builder {
+    readonly _blokV2: true;
+    readonly _config: WorkflowV2;
+    /**
+     * Serialize the wrapped workflow to a JSON string. Mirrors the
+     * `HelperResponse.toJson()` contract so v2 builders are
+     * structurally compatible with the v1 workflow registry
+     * (`Workflows` map → `LocalStorage.get` fallback).
+     */
+    toJson(): string;
+}
+/**
+ * Lowercase v2 workflow factory. Validates inputs against the v2 schema,
+ * compiles any `$` proxy expressions inside step `inputs` into
+ * `"js/ctx..."` strings at definition time, and returns a tagged object
+ * the runner's normalizer recognizes.
+ *
+ * Differences from the legacy `Workflow()` (capital W):
+ * - **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.
+ * - **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`.
+ * - **`$` proxy** replaces hand-written `js/ctx....` strings with typed
+ *   property access.
+ *
+ * @example
+ *   import { workflow, branch, $ } from "@blokjs/helper";
+ *
+ *   export default workflow({
+ *     name: "World Countries",
+ *     version: "1.0.0",
+ *     trigger: { http: { method: "GET" } },
+ *     steps: [
+ *       { id: "fetch", use: "@blokjs/api-call",
+ *         inputs: { url: "https://countriesnow.space/api/v0.1/countries" } },
+ *       branch({
+ *         id: "route",
+ *         when: $.req.query.kind,
+ *         then: [{ id: "respond", use: "@blokjs/respond",
+ *                  inputs: { body: $.state.fetch } }],
+ *         else: [{ id: "fallback", use: "@blokjs/api-call",
+ *                  inputs: { url: "https://catfact.ninja/fact" } }]
+ *       })
+ *     ]
+ *   });
+ */
+export declare function workflow(opts: WorkflowOpts): WorkflowV2Builder;

package/dist/components/workflowV2.js

@@ -0,0 +1,84 @@
+import { unwrapProxies } from "../proxy/$";
+import { V2StepSchema } from "../types/StepOpts";
+import { TriggersSchema, validateTriggerConfig } from "../types/TriggerOpts";
+/**
+ * Lowercase v2 workflow factory. Validates inputs against the v2 schema,
+ * compiles any `$` proxy expressions inside step `inputs` into
+ * `"js/ctx..."` strings at definition time, and returns a tagged object
+ * the runner's normalizer recognizes.
+ *
+ * Differences from the legacy `Workflow()` (capital W):
+ * - **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.
+ * - **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`.
+ * - **`$` proxy** replaces hand-written `js/ctx....` strings with typed
+ *   property access.
+ *
+ * @example
+ *   import { workflow, branch, $ } from "@blokjs/helper";
+ *
+ *   export default workflow({
+ *     name: "World Countries",
+ *     version: "1.0.0",
+ *     trigger: { http: { method: "GET" } },
+ *     steps: [
+ *       { id: "fetch", use: "@blokjs/api-call",
+ *         inputs: { url: "https://countriesnow.space/api/v0.1/countries" } },
+ *       branch({
+ *         id: "route",
+ *         when: $.req.query.kind,
+ *         then: [{ id: "respond", use: "@blokjs/respond",
+ *                  inputs: { body: $.state.fetch } }],
+ *         else: [{ id: "fallback", use: "@blokjs/api-call",
+ *                  inputs: { url: "https://catfact.ninja/fact" } }]
+ *       })
+ *     ]
+ *   });
+ */
+export function workflow(opts) {
+    if (!opts || typeof opts !== "object") {
+        throw new Error("workflow() requires an options object.");
+    }
+    // Compile $ proxy expressions into js/ strings BEFORE schema validation
+    // (the schema sees only strings; proxies would fail z.string().min(1)).
+    const compiledSteps = unwrapProxies(opts.steps);
+    // Per-step schema check — surface authoring errors loudly.
+    for (let i = 0; i < compiledSteps.length; i++) {
+        const parsed = V2StepSchema.safeParse(compiledSteps[i]);
+        if (!parsed.success) {
+            const id = compiledSteps[i]?.id ?? compiledSteps[i]?.name ?? `<step ${i}>`;
+            throw new Error(`workflow("${opts.name}") step "${id}" failed validation: ${parsed.error.message}`);
+        }
+    }
+    // Per-kind trigger validation. Mirrors what `Trigger.addTrigger` does
+    // in the v1 builder so v2 authors get the same error messages.
+    const triggerKeys = Object.keys(opts.trigger ?? {});
+    if (triggerKeys.length === 0) {
+        throw new Error(`workflow("${opts.name}") requires a trigger.`);
+    }
+    const validatedTrigger = {};
+    for (const kind of triggerKeys) {
+        const parsedKind = TriggersSchema.safeParse(kind);
+        if (!parsedKind.success) {
+            throw new Error(`workflow("${opts.name}") trigger kind "${kind}" is not recognized. Allowed: http, queue, pubsub, worker, cron, webhook, sse, websocket, grpc, manual.`);
+        }
+        validatedTrigger[kind] = validateTriggerConfig(parsedKind.data, opts.trigger[kind]);
+    }
+    const _config = {
+        name: opts.name,
+        version: opts.version,
+        description: opts.description,
+        trigger: validatedTrigger,
+        steps: compiledSteps,
+    };
+    return Object.freeze({
+        _blokV2: true,
+        _config,
+        toJson: () => JSON.stringify(_config),
+    });
+}
+//# sourceMappingURL=workflowV2.js.map

package/dist/components/workflowV2.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflowV2.js","sourceRoot":"","sources":["../../src/components/workflowV2.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,EAAe,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAC9D,OAAO,EAAE,cAAc,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AA+C7E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;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;IAED,wEAAwE;IACxE,wEAAwE;IACxE,MAAM,aAAa,GAAG,aAAa,CAAC,IAAI,CAAC,KAAK,CAAa,CAAC;IAE5D,2DAA2D;IAC3D,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,aAAa,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QAC/C,MAAM,MAAM,GAAG,YAAY,CAAC,SAAS,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC;QACxD,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;YACrB,MAAM,EAAE,GACN,aAAa,CAAC,CAAC,CAAqB,EAAE,EAAE,IAAK,aAAa,CAAC,CAAC,CAAuB,EAAE,IAAI,IAAI,SAAS,CAAC,GAAG,CAAC;YAC7G,MAAM,IAAI,KAAK,CAAC,aAAa,IAAI,CAAC,IAAI,YAAY,EAAE,wBAAwB,MAAM,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;QACrG,CAAC;IACF,CAAC;IAED,sEAAsE;IACtE,+DAA+D;IAC/D,MAAM,WAAW,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC;IACpD,IAAI,WAAW,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC9B,MAAM,IAAI,KAAK,CAAC,aAAa,IAAI,CAAC,IAAI,wBAAwB,CAAC,CAAC;IACjE,CAAC;IACD,MAAM,gBAAgB,GAA4B,EAAE,CAAC;IACrD,KAAK,MAAM,IAAI,IAAI,WAAW,EAAE,CAAC;QAChC,MAAM,UAAU,GAAG,cAAc,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;QAClD,IAAI,CAAC,UAAU,CAAC,OAAO,EAAE,CAAC;YACzB,MAAM,IAAI,KAAK,CACd,aAAa,IAAI,CAAC,IAAI,oBAAoB,IAAI,yGAAyG,CACvJ,CAAC;QACH,CAAC;QACD,gBAAgB,CAAC,IAAI,CAAC,GAAG,qBAAqB,CAAC,UAAU,CAAC,IAAI,EAAG,IAAI,CAAC,OAAmC,CAAC,IAAI,CAAC,CAAC,CAAC;IAClH,CAAC;IAED,MAAM,OAAO,GAAe;QAC3B,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,OAAO,EAAE,IAAI,CAAC,OAAO;QACrB,WAAW,EAAE,IAAI,CAAC,WAAW;QAC7B,OAAO,EAAE,gBAAgB;QACzB,KAAK,EAAE,aAAa;KACpB,CAAC;IAEF,OAAO,MAAM,CAAC,MAAM,CAAC;QACpB,OAAO,EAAE,IAAa;QACtB,OAAO;QACP,MAAM,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC;KACrC,CAAC,CAAC;AACJ,CAAC"}

package/dist/index.d.ts

@@ -4,6 +4,15 @@ import HelperResponse from "./components/HelperResponse";
 import Step from "./components/StepNode";
 import Trigger from "./components/Trigger";
 import Workflow from "./components/Workflow";
-import { NodeType, NodeTypeSchema, RuntimeKind, RuntimeKindSchema, StepInputs, StepOpts } from "./types/StepOpts";
-import { CronTriggerOpts, CronTriggerOptsSchema, HttpTriggerOptsSchema, PubSubProvider, PubSubProviderSchema, PubSubTriggerOpts, PubSubTriggerOptsSchema, QueueProvider, QueueProviderSchema, QueueTriggerOpts, QueueTriggerOptsSchema, SSETriggerOpts, SSETriggerOptsSchema, TriggerOpts, TriggerOptsSchema, TriggersEnum, TriggersSchema, WebSocketTriggerOpts, WebSocketTriggerOptsSchema, WebhookTriggerOpts, WebhookTriggerOptsSchema, WorkerTriggerOpts, WorkerTriggerOptsSchema } from "./types/TriggerOpts";
-export { AddElse, AddIf, ConditionOpts, HelperResponse, NodeType, NodeTypeSchema, RuntimeKind, RuntimeKindSchema, Step, StepInputs, StepOpts, Trigger, Workflow, TriggerOpts, TriggerOptsSchema, HttpTriggerOptsSchema, QueueProvider, QueueProviderSchema, QueueTriggerOpts, QueueTriggerOptsSchema, PubSubProvider, PubSubProviderSchema, PubSubTriggerOpts, PubSubTriggerOptsSchema, WorkerTriggerOpts, WorkerTriggerOptsSchema, CronTriggerOpts, CronTriggerOptsSchema, WebhookTriggerOpts, WebhookTriggerOptsSchema, WebSocketTriggerOpts, WebSocketTriggerOptsSchema, SSETriggerOpts, SSETriggerOptsSchema, TriggersSchema, TriggersEnum, };
+import { type BranchOpts, branch } from "./components/branch";
+import { type ForEachOpts, forEach } from "./components/forEach";
+import { type LoopOpts, loop } from "./components/loop";
+import { type SwitchCase, type SwitchOpts, switchOn } from "./components/switchOn";
+import { type TryCatchOpts, tryCatch } from "./components/tryCatch";
+import { type WorkflowV2Builder, type WorkflowOpts as WorkflowV2Opts, workflow } from "./components/workflowV2";
+import { $, type DollarProxy, type ExprPath, JS_EXPR_TAG, unwrapProxies } from "./proxy/$";
+import { NodeType, NodeTypeSchema, RetryConfig, RetryConfigSchema, RuntimeKind, RuntimeKindSchema, StepInputs, StepOpts, V2BranchStep, V2BranchStepSchema, V2ForEachStep, V2ForEachStepSchema, V2LoopStep, V2LoopStepSchema, V2RegularStep, V2RegularStepSchema, V2Step, V2StepSchema, V2SubworkflowStep, V2SubworkflowStepSchema, V2SwitchStep, V2SwitchStepSchema, V2TryCatchStep, V2TryCatchStepSchema, V2WaitStep, V2WaitStepSchema, isBranchStep, isForEachStep, isLoopStep, isSubworkflowStep, isSwitchStep, isTryCatchStep, isWaitStep } from "./types/StepOpts";
+import { AnyTriggerOpts, ConcurrencyOpts, ConcurrencyOptsFields, ConcurrencyOptsSchema, CronTriggerOpts, CronTriggerOptsSchema, DebounceOpts, DebounceOptsSchema, HTTP_METHODS, HttpMethod, HttpMethodSchema, HttpTriggerOpts, HttpTriggerOptsSchema, PubSubProvider, PubSubProviderSchema, PubSubTriggerOpts, PubSubTriggerOptsSchema, QueueProvider, QueueProviderSchema, QueueTriggerOpts, QueueTriggerOptsSchema, SSETriggerOpts, SSETriggerOptsSchema, SchedulingOpts, SchedulingOptsFields, SchedulingOptsSchema, TRIGGER_SCHEMAS, TriggerConfigMap, TriggerOpts, TriggerOptsSchema, TriggersEnum, TriggersSchema, WebSocketTriggerOpts, WebSocketTriggerOptsSchema, WebhookTriggerOpts, WebhookTriggerOptsSchema, WorkerProvider, WorkerProviderSchema, WorkerTriggerOpts, WorkerTriggerOptsSchema, concurrencyRefinement, makeSchedulingRefinement, validateTriggerConfig } from "./types/TriggerOpts";
+import { WorkflowV2, WorkflowV2Schema } from "./types/WorkflowOpts";
+import { parseDuration, tryParseDuration } from "./utils/parseDuration";
+export { AddElse, AddIf, ConditionOpts, HelperResponse, NodeType, NodeTypeSchema, RuntimeKind, RuntimeKindSchema, Step, StepInputs, StepOpts, Trigger, Workflow, workflow, branch, forEach, loop, switchOn, tryCatch, $, unwrapProxies, type BranchOpts, type ForEachOpts, type LoopOpts, type SwitchOpts, type SwitchCase, type TryCatchOpts, type WorkflowV2Opts, type WorkflowV2Builder, type DollarProxy, type ExprPath, JS_EXPR_TAG, V2Step, V2StepSchema, V2RegularStep, V2RegularStepSchema, V2BranchStep, V2BranchStepSchema, isBranchStep, V2SubworkflowStep, V2SubworkflowStepSchema, isSubworkflowStep, V2WaitStep, V2WaitStepSchema, isWaitStep, V2ForEachStep, V2ForEachStepSchema, isForEachStep, V2LoopStep, V2LoopStepSchema, isLoopStep, V2SwitchStep, V2SwitchStepSchema, isSwitchStep, V2TryCatchStep, V2TryCatchStepSchema, isTryCatchStep, RetryConfig, RetryConfigSchema, WorkflowV2, WorkflowV2Schema, HTTP_METHODS, HttpMethod, HttpMethodSchema, ConcurrencyOpts, ConcurrencyOptsFields, ConcurrencyOptsSchema, concurrencyRefinement, DebounceOpts, DebounceOptsSchema, makeSchedulingRefinement, SchedulingOpts, SchedulingOptsFields, SchedulingOptsSchema, HttpTriggerOpts, HttpTriggerOptsSchema, TriggerOpts, TriggerOptsSchema, QueueProvider, QueueProviderSchema, QueueTriggerOpts, QueueTriggerOptsSchema, PubSubProvider, PubSubProviderSchema, PubSubTriggerOpts, PubSubTriggerOptsSchema, WorkerProvider, WorkerProviderSchema, WorkerTriggerOpts, WorkerTriggerOptsSchema, CronTriggerOpts, CronTriggerOptsSchema, WebhookTriggerOpts, WebhookTriggerOptsSchema, WebSocketTriggerOpts, WebSocketTriggerOptsSchema, SSETriggerOpts, SSETriggerOptsSchema, TriggersSchema, TriggersEnum, TriggerConfigMap, TRIGGER_SCHEMAS, AnyTriggerOpts, validateTriggerConfig, parseDuration, tryParseDuration, };

package/dist/index.js

@@ -4,9 +4,30 @@ import HelperResponse from "./components/HelperResponse";
 import Step from "./components/StepNode";
 import Trigger from "./components/Trigger";
 import Workflow from "./components/Workflow";
-import { NodeTypeSchema, RuntimeKindSchema } from "./types/StepOpts";
-import { CronTriggerOptsSchema, HttpTriggerOptsSchema, PubSubProviderSchema, PubSubTriggerOptsSchema, QueueProviderSchema, QueueTriggerOptsSchema, SSETriggerOptsSchema, TriggerOptsSchema, 
+import { branch } from "./components/branch";
+import { forEach } from "./components/forEach";
+import { loop } from "./components/loop";
+import { switchOn } from "./components/switchOn";
+import { tryCatch } from "./components/tryCatch";
+import { workflow } from "./components/workflowV2";
+import { $, JS_EXPR_TAG, unwrapProxies } from "./proxy/$";
+import { NodeTypeSchema, RetryConfigSchema, RuntimeKindSchema, V2BranchStepSchema, V2ForEachStepSchema, V2LoopStepSchema, V2RegularStepSchema, V2StepSchema, V2SubworkflowStepSchema, V2SwitchStepSchema, V2TryCatchStepSchema, V2WaitStepSchema, isBranchStep, isForEachStep, isLoopStep, isSubworkflowStep, isSwitchStep, isTryCatchStep, isWaitStep, } from "./types/StepOpts";
+import { ConcurrencyOptsFields, ConcurrencyOptsSchema, CronTriggerOptsSchema, DebounceOptsSchema, 
+// HTTP method enum (canonical names + legacy * preprocess)
+HTTP_METHODS, HttpMethodSchema, HttpTriggerOptsSchema, PubSubProviderSchema, PubSubTriggerOptsSchema, QueueProviderSchema, QueueTriggerOptsSchema, SSETriggerOptsSchema, SchedulingOptsFields, SchedulingOptsSchema, 
+// Trigger registry
+TRIGGER_SCHEMAS, TriggerOptsSchema, 
 // Triggers enum
-TriggersSchema, WebSocketTriggerOptsSchema, WebhookTriggerOptsSchema, WorkerTriggerOptsSchema, } from "./types/TriggerOpts";
-export { AddElse, AddIf, HelperResponse, NodeTypeSchema, RuntimeKindSchema, Step, Trigger, Workflow, TriggerOptsSchema, HttpTriggerOptsSchema, QueueProviderSchema, QueueTriggerOptsSchema, PubSubProviderSchema, PubSubTriggerOptsSchema, WorkerTriggerOptsSchema, CronTriggerOptsSchema, WebhookTriggerOptsSchema, WebSocketTriggerOptsSchema, SSETriggerOptsSchema, TriggersSchema, };
+TriggersSchema, WebSocketTriggerOptsSchema, WebhookTriggerOptsSchema, WorkerProviderSchema, WorkerTriggerOptsSchema, concurrencyRefinement, makeSchedulingRefinement, validateTriggerConfig, } from "./types/TriggerOpts";
+import { WorkflowV2Schema } from "./types/WorkflowOpts";
+import { parseDuration, tryParseDuration } from "./utils/parseDuration";
+export { AddElse, AddIf, HelperResponse, NodeTypeSchema, RuntimeKindSchema, Step, Trigger, Workflow, 
+// v2 DSL primitives — the canonical authoring surface
+workflow, branch, 
+// v0.5 control-flow primitives
+forEach, loop, switchOn, tryCatch, $, unwrapProxies, JS_EXPR_TAG, V2StepSchema, V2RegularStepSchema, V2BranchStepSchema, isBranchStep, V2SubworkflowStepSchema, isSubworkflowStep, V2WaitStepSchema, isWaitStep, V2ForEachStepSchema, isForEachStep, V2LoopStepSchema, isLoopStep, V2SwitchStepSchema, isSwitchStep, V2TryCatchStepSchema, isTryCatchStep, RetryConfigSchema, WorkflowV2Schema, 
+// HTTP method enum
+HTTP_METHODS, HttpMethodSchema, ConcurrencyOptsFields, ConcurrencyOptsSchema, concurrencyRefinement, DebounceOptsSchema, makeSchedulingRefinement, SchedulingOptsFields, SchedulingOptsSchema, HttpTriggerOptsSchema, TriggerOptsSchema, QueueProviderSchema, QueueTriggerOptsSchema, PubSubProviderSchema, PubSubTriggerOptsSchema, WorkerProviderSchema, WorkerTriggerOptsSchema, CronTriggerOptsSchema, WebhookTriggerOptsSchema, WebSocketTriggerOptsSchema, SSETriggerOptsSchema, TriggersSchema, TRIGGER_SCHEMAS, validateTriggerConfig, 
+// Duration parser (Tier 2 #5 + #7)
+parseDuration, tryParseDuration, };
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,OAAO,MAAM,sBAAsB,CAAC;AAC3C,OAAO,KAAwB,MAAM,oBAAoB,CAAC;AAC1D,OAAO,cAAc,MAAM,6BAA6B,CAAC;AACzD,OAAO,IAAI,MAAM,uBAAuB,CAAC;AACzC,OAAO,OAAO,MAAM,sBAAsB,CAAC;AAC3C,OAAO,QAAQ,MAAM,uBAAuB,CAAC;AAC7C,OAAO,EAAY,cAAc,EAAe,iBAAiB,EAAwB,MAAM,kBAAkB,CAAC;AAClH,OAAO,EAGN,qBAAqB,EACrB,qBAAqB,EAGrB,oBAAoB,EAEpB,uBAAuB,EAGvB,mBAAmB,EAEnB,sBAAsB,EAGtB,oBAAoB,EAGpB,iBAAiB;AAEjB,gBAAgB;AAChB,cAAc,EAGd,0BAA0B,EAG1B,wBAAwB,EAGxB,uBAAuB,GACvB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACN,OAAO,EACP,KAAK,EAEL,cAAc,EAEd,cAAc,EAEd,iBAAiB,EACjB,IAAI,EAGJ,OAAO,EACP,QAAQ,EAGR,iBAAiB,EACjB,qBAAqB,EAErB,mBAAmB,EAEnB,sBAAsB,EAEtB,oBAAoB,EAEpB,uBAAuB,EAEvB,uBAAuB,EAEvB,qBAAqB,EAErB,wBAAwB,EAExB,0BAA0B,EAE1B,oBAAoB,EACpB,cAAc,GAEd,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/proxy/$.d.ts

@@ -0,0 +1,102 @@
+/**
+ * The typed `$` proxy — typed sugar over the runtime's `js/...` resolver.
+ *
+ * Property access on `$` builds a path string at definition time. The
+ * `unwrapProxies` deep-walk in the `workflow()` factory replaces each proxy
+ * value with its compiled `"js/ctx.<path>"` string before the workflow is
+ * handed to the runner. This means:
+ *
+ * - Authors get IDE autocomplete on `$.req.body.foo`, `$.state.users[0]`, etc.
+ * - The runtime sees plain strings (no Proxy traversal at execution time).
+ * - The existing `Mapper.jsMapper` resolver works unchanged — it already
+ *   evaluates `js/...` strings against `ctx`.
+ *
+ * @example
+ *   import { workflow, $ } from "@blokjs/helper";
+ *
+ *   workflow({
+ *     trigger: { http: { method: "GET" } },
+ *     steps: [
+ *       { id: "fetch", use: "@blokjs/api-call",
+ *         inputs: { userId: $.req.params.id } },
+ *       { id: "respond", use: "@blokjs/respond",
+ *         inputs: { body: $.state.fetch } }
+ *     ]
+ *   });
+ *   // After `unwrapProxies` runs at definition time:
+ *   //   inputs.userId === "js/ctx.req.params.id"
+ *   //   inputs.body   === "js/ctx.state.fetch"
+ */
+/** Internal symbol used to detect proxy values during the deep-walk. */
+export declare const JS_EXPR_TAG: unique symbol;
+/**
+ * The shape of any sub-path of the `$` proxy. Property and index access
+ * are recursive; string conversion produces a `js/ctx....` literal.
+ *
+ * Typed as `unknown` at the leaves so authors can pass a path anywhere a
+ * value of any type is expected without `as` casts.
+ */
+export type ExprPath = {
+    readonly [key: string]: ExprPath;
+} & {
+    toString(): string;
+    toJSON(): string;
+};
+/**
+ * The top-level `$` proxy. Provides typed access to:
+ * - `$.req`  — request envelope (alias of `ctx.request`)
+ * - `$.prev` — previous step's response envelope (alias of `ctx.response`)
+ * - `$.state` — accumulated step outputs by step id
+ * - `$.env` — process env mirror
+ * - `$.step` — current step metadata (`{ name, index, total, depth }`)
+ * - `$.workflow` — current workflow metadata
+ *
+ * Plus legacy fallbacks for `$.request` (= `$.req`) and `$.response` (= `$.prev`).
+ */
+export interface DollarProxy {
+    readonly req: ExprPath;
+    readonly request: ExprPath;
+    readonly prev: ExprPath;
+    readonly response: ExprPath;
+    readonly state: ExprPath;
+    readonly vars: ExprPath;
+    readonly env: ExprPath;
+    readonly step: ExprPath;
+    readonly workflow: ExprPath;
+    /**
+     * The captured error inside a `tryCatch.catch` block (v0.5).
+     * Resolves to `ctx.error`; undefined inside `try`, `finally`, and
+     * any step outside a tryCatch. Use `$.error.message`, `$.error.name`,
+     * `$.error.stack`.
+     */
+    readonly error: ExprPath;
+    /** Escape hatch — any property; returns a sub-path. */
+    readonly [key: string]: ExprPath;
+}
+/**
+ * The `$` proxy entry point. All paths root at `ctx`.
+ *
+ * @see DollarProxy for the typed surface.
+ */
+export declare const $: DollarProxy;
+/**
+ * Recursively replace any `$` proxy values inside `value` with their
+ * compiled `"js/ctx.<path>"` strings.
+ *
+ * Called by `workflow()` and `branch()` factories at definition time to
+ * convert in-memory proxy references into the wire-shape strings the
+ * runner's `Mapper` expects.
+ *
+ * Unwraps:
+ * - Proxies → `"js/ctx.<path>"` strings
+ * - Plain objects → walked recursively, returning a NEW object
+ * - Arrays → walked, returning a NEW array
+ *
+ * Leaves alone:
+ * - Primitives (string, number, boolean, null, undefined)
+ * - Class instances (anything with a non-Object prototype)
+ * - Functions other than the proxy itself
+ *
+ * Pure — never mutates the input.
+ */
+export declare function unwrapProxies<T>(value: T): T;