@blokjs/shared 0.2.1 → 0.4.0

package/dist/utils/MapperResolutionError.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Structured error thrown by `Mapper` when a workflow input expression
+ * cannot be resolved against the live `Context`.
+ *
+ * The Mapper resolves two template syntaxes inside step `inputs`:
+ * - **`${path.to.value}`** — interpolated string (lodash-path lookup
+ *   with a JS-eval fallback)
+ * - **`"js/..."`** — full-string JS evaluation against `ctx`
+ *
+ * When evaluation throws (typo, undefined access, syntax error,
+ * unknown identifier), the Mapper packages the failure in a
+ * `MapperResolutionError` carrying full diagnostic context — the
+ * literal expression, which syntax it was, the workflow + step name,
+ * and the original underlying error as `cause`.
+ *
+ * **What happens next depends on `BLOK_MAPPER_MODE`** (read from env):
+ *
+ * - `"warn"` (default) — the error is caught inside the Mapper, logged
+ *   via `ctx.logger.logLevel("warn", ...)` (which routes to both the
+ *   console AND Studio's log viewer via `TracingLogger`), and the
+ *   original expression string passes through to the node. Backward-
+ *   compatible with v1 behavior + actionable diagnostics.
+ *
+ * - `"strict"` — the error escapes the Mapper, is re-thrown by
+ *   `NodeBase.blueprintMapper`, and the step fails fast with a
+ *   structured error. **Recommended for production deployments** —
+ *   silent input resolution failures are a source of subtle bugs
+ *   (the node receives a literal `"js/ctx.bad.path"` string instead
+ *   of the resolved value, then produces wrong output downstream).
+ *
+ * - `"silent"` — pre-v0.3.x behavior: completely suppress the error
+ *   (no log, no throw). Provided as an opt-out for tests / workflows
+ *   that intentionally use undefined-tolerant resolution for optional
+ *   fields. Discouraged.
+ *
+ * This class is a `core/shared` concern (not `core/runner`) because
+ * the Mapper itself lives in shared. Consumers in any package may
+ * `instanceof` check it to handle resolution failures specifically
+ * (e.g., a custom trigger may want to translate it into a 400-class
+ * HTTP response).
+ */
+export declare class MapperResolutionError extends Error {
+    /** Always the literal string `"MapperResolutionError"`. */
+    readonly name = "MapperResolutionError";
+    /** Structured diagnostic context attached at construction time. */
+    readonly context: {
+        /**
+         * The literal expression that failed, WITHOUT the surrounding
+         * syntax markers. For `js/ctx.bad.path` the value is
+         * `"ctx.bad.path"`; for `${ctx.user.name}` it is `"ctx.user.name"`.
+         */
+        readonly expression: string;
+        /**
+         * Which template syntax was being parsed.
+         * - `"js"`  — full-string `"js/..."` expression
+         * - `"template"` — interpolated `${...}` placeholder
+         */
+        readonly syntax: "js" | "template";
+        /**
+         * The workflow's `name:` field, when known. Read from
+         * `ctx.workflow_name`. Absent on hand-rolled test contexts.
+         */
+        readonly workflowName?: string;
+        /**
+         * The step's `id` (or v1 `name`), when known. Read from
+         * `ctx._stepInfo.name` which is set by `RunnerSteps` before
+         * each step runs. Absent during early-boot or test contexts.
+         */
+        readonly stepName?: string;
+        /**
+         * The original error thrown by the JS evaluator (typically a
+         * `TypeError` or `ReferenceError`). Preserved for full stack
+         * trace + downstream `instanceof` checks.
+         */
+        readonly cause?: unknown;
+    };
+    constructor(message: string, context: {
+        readonly expression: string;
+        readonly syntax: "js" | "template";
+        readonly workflowName?: string;
+        readonly stepName?: string;
+        readonly cause?: unknown;
+    });
+}

package/dist/utils/MapperResolutionError.js

@@ -0,0 +1,61 @@
+/**
+ * Structured error thrown by `Mapper` when a workflow input expression
+ * cannot be resolved against the live `Context`.
+ *
+ * The Mapper resolves two template syntaxes inside step `inputs`:
+ * - **`${path.to.value}`** — interpolated string (lodash-path lookup
+ *   with a JS-eval fallback)
+ * - **`"js/..."`** — full-string JS evaluation against `ctx`
+ *
+ * When evaluation throws (typo, undefined access, syntax error,
+ * unknown identifier), the Mapper packages the failure in a
+ * `MapperResolutionError` carrying full diagnostic context — the
+ * literal expression, which syntax it was, the workflow + step name,
+ * and the original underlying error as `cause`.
+ *
+ * **What happens next depends on `BLOK_MAPPER_MODE`** (read from env):
+ *
+ * - `"warn"` (default) — the error is caught inside the Mapper, logged
+ *   via `ctx.logger.logLevel("warn", ...)` (which routes to both the
+ *   console AND Studio's log viewer via `TracingLogger`), and the
+ *   original expression string passes through to the node. Backward-
+ *   compatible with v1 behavior + actionable diagnostics.
+ *
+ * - `"strict"` — the error escapes the Mapper, is re-thrown by
+ *   `NodeBase.blueprintMapper`, and the step fails fast with a
+ *   structured error. **Recommended for production deployments** —
+ *   silent input resolution failures are a source of subtle bugs
+ *   (the node receives a literal `"js/ctx.bad.path"` string instead
+ *   of the resolved value, then produces wrong output downstream).
+ *
+ * - `"silent"` — pre-v0.3.x behavior: completely suppress the error
+ *   (no log, no throw). Provided as an opt-out for tests / workflows
+ *   that intentionally use undefined-tolerant resolution for optional
+ *   fields. Discouraged.
+ *
+ * This class is a `core/shared` concern (not `core/runner`) because
+ * the Mapper itself lives in shared. Consumers in any package may
+ * `instanceof` check it to handle resolution failures specifically
+ * (e.g., a custom trigger may want to translate it into a 400-class
+ * HTTP response).
+ */
+export class MapperResolutionError extends Error {
+    /** Always the literal string `"MapperResolutionError"`. */
+    name = "MapperResolutionError";
+    /** Structured diagnostic context attached at construction time. */
+    context;
+    constructor(message, context) {
+        super(message);
+        this.context = context;
+        // Preserve the prototype chain across Babel/TS down-compilation —
+        // without this, `instanceof MapperResolutionError` fails on
+        // constructors transpiled to ES5 targets.
+        Object.setPrototypeOf(this, MapperResolutionError.prototype);
+        // Standard `Error.cause` mirror (Node 16.9+, ES2022). Lets
+        // `console.error(e)` pretty-print the underlying cause too.
+        if (context.cause !== undefined) {
+            this.cause = context.cause;
+        }
+    }
+}
+//# sourceMappingURL=MapperResolutionError.js.map

package/dist/utils/MapperResolutionError.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"MapperResolutionError.js","sourceRoot":"","sources":["../../src/utils/MapperResolutionError.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,MAAM,OAAO,qBAAsB,SAAQ,KAAK;IAC/C,2DAA2D;IAClC,IAAI,GAAG,uBAAuB,CAAC;IAExD,mEAAmE;IACnD,OAAO,CA8BrB;IAEF,YACC,OAAe,EACf,OAMC;QAED,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,kEAAkE;QAClE,4DAA4D;QAC5D,0CAA0C;QAC1C,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,qBAAqB,CAAC,SAAS,CAAC,CAAC;QAC7D,2DAA2D;QAC3D,4DAA4D;QAC5D,IAAI,OAAO,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;YAChC,IAAoC,CAAC,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC;QAC7D,CAAC;IACF,CAAC;CACD"}

package/dist/utils/index.d.ts

@@ -1,5 +1,6 @@
 export { default as CpuUsage } from "./CpuUsage";
-export { default as Mapper } from "./Mapper";
+export { default as Mapper, type MapperMode } from "./Mapper";
+export { MapperResolutionError } from "./MapperResolutionError";
 export { default as MemoryUsage } from "./MemoryUsage";
 export { default as Metrics } from "./MetricsBase";
 export { default as Time } from "./Time";

package/dist/utils/index.js

@@ -1,5 +1,6 @@
 export { default as CpuUsage } from "./CpuUsage";
 export { default as Mapper } from "./Mapper";
+export { MapperResolutionError } from "./MapperResolutionError";
 export { default as MemoryUsage } from "./MemoryUsage";
 export { default as Metrics } from "./MetricsBase";
 export { default as Time } from "./Time";

package/dist/utils/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,IAAI,QAAQ,EAAE,MAAM,YAAY,CAAC;AACjD,OAAO,EAAE,OAAO,IAAI,MAAM,EAAE,MAAM,UAAU,CAAC;AAC7C,OAAO,EAAE,OAAO,IAAI,WAAW,EAAE,MAAM,eAAe,CAAC;AACvD,OAAO,EAAE,OAAO,IAAI,OAAO,EAAE,MAAM,eAAe,CAAC;AACnD,OAAO,EAAE,OAAO,IAAI,IAAI,EAAE,MAAM,QAAQ,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,IAAI,QAAQ,EAAE,MAAM,YAAY,CAAC;AACjD,OAAO,EAAE,OAAO,IAAI,MAAM,EAAmB,MAAM,UAAU,CAAC;AAC9D,OAAO,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AAChE,OAAO,EAAE,OAAO,IAAI,WAAW,EAAE,MAAM,eAAe,CAAC;AACvD,OAAO,EAAE,OAAO,IAAI,OAAO,EAAE,MAAM,eAAe,CAAC;AACnD,OAAO,EAAE,OAAO,IAAI,IAAI,EAAE,MAAM,QAAQ,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@blokjs/shared",
-	"version": "0.2.1",
+	"version": "0.4.0",
 	"description": "Shared class, interfaces and types",
 	"type": "module",
 	"main": "dist/index.js",
@@ -11,10 +11,7 @@
 		"test": "vitest run",
 		"test:dev": "vitest"
 	},
-	"keywords": [
-		"api",
-		"blueprint"
-	],
+	"keywords": ["api", "blueprint"],
 	"author": "Deskree Inc",
 	"license": "MIT",
 	"devDependencies": {