@blokjs/helper 0.2.0 → 0.4.0

package/dist/proxy/$.d.ts

@@ -0,0 +1,95 @@
+/**
+ * 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;
+    /** 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;

package/dist/proxy/$.js

@@ -0,0 +1,130 @@
+/**
+ * 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 const JS_EXPR_TAG = Symbol("blok.jsExpr");
+const IDENT_RE = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+const NUMERIC_RE = /^\d+$/;
+function makeProxy(prefix) {
+    // Use a function as the target so `typeof` is `function` — that lets us
+    // distinguish proxy values from plain objects in `unwrapProxies`. The
+    // function is never called; it's just a tag.
+    const target = (() => prefix);
+    target[JS_EXPR_TAG] = prefix;
+    return new Proxy(target, {
+        get(_target, key) {
+            if (key === JS_EXPR_TAG)
+                return prefix;
+            if (key === Symbol.toPrimitive)
+                return (_hint) => `js/${prefix}`;
+            if (key === "toString")
+                return () => `js/${prefix}`;
+            if (key === "toJSON")
+                return () => `js/${prefix}`;
+            if (key === "valueOf")
+                return () => `js/${prefix}`;
+            // Don't pretend to be a thenable — Promise.resolve() probes `.then`.
+            if (key === "then")
+                return undefined;
+            // Ignore inherited symbols (Symbol.iterator, etc.).
+            if (typeof key === "symbol")
+                return undefined;
+            const k = String(key);
+            let next;
+            if (NUMERIC_RE.test(k)) {
+                next = `${prefix}[${k}]`;
+            }
+            else if (IDENT_RE.test(k)) {
+                next = `${prefix}.${k}`;
+            }
+            else {
+                next = `${prefix}[${JSON.stringify(k)}]`;
+            }
+            return makeProxy(next);
+        },
+    });
+}
+/**
+ * The `$` proxy entry point. All paths root at `ctx`.
+ *
+ * @see DollarProxy for the typed surface.
+ */
+export const $ = makeProxy("ctx");
+/**
+ * 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 function unwrapProxies(value) {
+    return unwrap(value);
+}
+function unwrap(value) {
+    if (value === null || value === undefined)
+        return value;
+    // Detect proxy via the tag symbol.
+    if (typeof value === "function") {
+        const tag = value[JS_EXPR_TAG];
+        if (typeof tag === "string") {
+            return `js/${tag}`;
+        }
+        // Other functions — leave as-is.
+        return value;
+    }
+    if (Array.isArray(value)) {
+        return value.map(unwrap);
+    }
+    // Plain object only — class instances pass through untouched.
+    if (typeof value === "object") {
+        const proto = Object.getPrototypeOf(value);
+        if (proto === null || proto === Object.prototype) {
+            const out = {};
+            for (const k of Object.keys(value)) {
+                out[k] = unwrap(value[k]);
+            }
+            return out;
+        }
+    }
+    return value;
+}
+//# sourceMappingURL=$.js.map

package/dist/proxy/$.js.map

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