@blokjs/shared 0.2.2 → 0.6.0

package/dist/utils/Mapper.js

@@ -1,55 +1,288 @@
 import _ from "lodash";
+import { MapperResolutionError } from "./MapperResolutionError";
+// =============================================================================
+// Internal sentinels + helpers
+// =============================================================================
+/**
+ * Returned by the template-resolution path to signal "this placeholder
+ * could not be resolved; leave the literal `${...}` in place". Using a
+ * Symbol avoids ambiguity with the legitimate `undefined` value an
+ * expression might produce.
+ */
+const TEMPLATE_RESOLUTION_FAILED = Symbol("TEMPLATE_RESOLUTION_FAILED");
+function readMode() {
+    const raw = process.env.BLOK_MAPPER_MODE;
+    if (raw === "strict")
+        return "strict";
+    if (raw === "silent")
+        return "silent";
+    return "warn";
+}
+function readStepContext(ctx) {
+    const ctxAny = ctx;
+    const stepInfo = ctxAny._stepInfo;
+    const stepName = typeof stepInfo?.name === "string" ? stepInfo.name : undefined;
+    const workflowName = typeof ctx.workflow_name === "string" ? ctx.workflow_name : undefined;
+    return { workflowName, stepName };
+}
+/**
+ * Build the actionable error message — every line carries information
+ * a developer can act on: WHERE it failed, WHAT failed, WHY it likely
+ * failed, and HOW to fix it.
+ */
+function buildErrorMessage(opts) {
+    const wf = opts.workflowName ?? "<unknown workflow>";
+    const step = opts.stepName ?? "<unknown step>";
+    const literal = opts.syntax === "js" ? `js/${opts.expression}` : `\${${opts.expression}}`;
+    const causeMsg = opts.cause instanceof Error ? opts.cause.message : String(opts.cause);
+    const hint = guessHint(opts.expression, causeMsg);
+    const lines = [
+        `[blok][mapper] Failed to resolve \`${literal}\` in step "${step}" of workflow "${wf}"`,
+        `  underlying: ${causeMsg}`,
+    ];
+    if (hint)
+        lines.push(`  hint: ${hint}`);
+    lines.push("  fix: verify the referenced ctx path exists at run time. Set BLOK_MAPPER_MODE=strict in production to fail fast on these errors.");
+    return lines.join("\n");
+}
+/**
+ * Heuristic — translate common JS evaluation errors into actionable
+ * developer hints. Returns `null` when the error doesn't match any
+ * known pattern (the underlying message is still surfaced).
+ */
+function guessHint(expression, errorMessage) {
+    // Most common case — `Cannot read properties of undefined (reading 'X')`
+    // or the older `Cannot read property 'X' of undefined`. Both forms
+    // appear depending on Node/Bun version.
+    const undefMatch = errorMessage.match(/Cannot read propert(?:y '(\w+)' of undefined|ies of undefined \(reading '(\w+)'\))/);
+    if (undefMatch) {
+        const prop = undefMatch[1] ?? undefMatch[2];
+        const segments = expression.split(".");
+        const parent = segments.slice(0, -1).join(".") || expression;
+        return `the path \`${parent}\` is undefined or doesn't have a "${prop}" field at run time. Check the trigger payload (ctx.req.body) or the upstream step's output (ctx.state.<id>).`;
+    }
+    // Identifier not in scope — only `ctx`, `data`, `func`, `vars` are
+    // available inside expressions.
+    const refMatch = errorMessage.match(/(\w+) is not defined/);
+    if (refMatch) {
+        return `\`${refMatch[1]}\` is not in scope. Available identifiers inside expressions: ctx, data, func, vars.`;
+    }
+    // Syntax error.
+    if (/SyntaxError/.test(errorMessage) || /Unexpected token/.test(errorMessage)) {
+        return "the expression is not valid JavaScript. Check for typos, unmatched parentheses, or stray characters.";
+    }
+    return null;
+}
+/**
+ * Route a warn-mode log line to the best available sink. Prefers
+ * `ctx.logger.logLevel("warn", ...)` so the warning lands in BOTH the
+ * console (via DefaultLogger) AND Studio's log viewer (via
+ * TracingLogger.normalizeLevel → addLog). Falls back to console.warn
+ * when no logger is attached (early-boot or hand-rolled test ctx).
+ */
+function logViaCtxOrConsole(ctx, message) {
+    const logger = ctx.logger;
+    if (logger?.logLevel) {
+        try {
+            logger.logLevel("warn", message);
+            return;
+        }
+        catch {
+            // fall through to console.warn — never let logging itself crash a step.
+        }
+    }
+    if (logger?.log) {
+        try {
+            logger.log(message);
+            return;
+        }
+        catch {
+            // fall through
+        }
+    }
+    console.warn(message);
+}
+/**
+ * Coerce a resolved value to its string form for `${...}` interpolation.
+ *
+ * Pre-v0.3.x used `value as string` which fell back to `String(value)`
+ * via implicit coercion — producing `"[object Object]"` for any object/
+ * array. Now JSON-encodes complex values so interpolated strings
+ * preserve information instead of silently miscompiling.
+ *
+ * - `null` / `undefined` → empty string (matches user intent for
+ *   missing optional fields)
+ * - `string` → identity
+ * - `number` / `boolean` / `bigint` → `String(value)`
+ * - everything else → `JSON.stringify(value)` with a defensive fallback
+ *   to `String(value)` for circular structures.
+ */
+function toInterpolatedString(value) {
+    if (value === null || value === undefined)
+        return "";
+    if (typeof value === "string")
+        return value;
+    if (typeof value === "number" || typeof value === "boolean" || typeof value === "bigint") {
+        return String(value);
+    }
+    try {
+        return JSON.stringify(value) ?? String(value);
+    }
+    catch {
+        // JSON.stringify throws on circular references — degrade gracefully.
+        return String(value);
+    }
+}
+// =============================================================================
+// Mapper
+// =============================================================================
 class Mapper {
+    /**
+     * Walk an object recursively, resolving every string value via
+     * `replaceString`. Mutates in place. Used by `NodeBase.process` to
+     * resolve a step's `inputs` against the live `ctx` before the
+     * step runs.
+     *
+     * Object/array values are recursed into; primitive non-string
+     * values are left untouched. Null values are NOT recursed (avoids
+     * a TypeError on `for (const k in null)`).
+     */
     replaceObjectStrings(obj, ctx, data) {
         for (const key in obj) {
             if (Object.prototype.hasOwnProperty.call(obj, key)) {
                 const value = obj[key];
                 if (typeof value === "string") {
+                    // `ParamsDictionary[key]` is typed `string`, but the
+                    // runtime contract has always been "the resolved value
+                    // keeps its actual type" (so `js/ctx.req.body.count`
+                    // produces a number, not the string "42"). The
+                    // `as unknown as string` boundary cast acknowledges
+                    // that the type system can't express this widening
+                    // without changing the global ParamsDictionary shape
+                    // (a much larger refactor).
                     obj[key] = this.replaceString(value, ctx, data);
                 }
-                else if (typeof value === "object") {
+                else if (value !== null && typeof value === "object") {
                     this.replaceObjectStrings(value, ctx, data);
                 }
             }
         }
     }
+    /**
+     * Resolve a single string. Returns `unknown` because a `js/...`
+     * expression may yield any value (number, object, array, etc.) —
+     * type fidelity is preserved across the resolver boundary.
+     *
+     * Pre-v0.3.x return was typed as `string` via `as string` cast
+     * which was a type lie; downstream consumers received the actual
+     * runtime value but couldn't see it through the type system.
+     */
     replaceString = (strData, ctx, data) => {
         let str = strData;
-        // if (str.length > 15000) {
-        // 	throw new Error("Input too long");
-        // }
+        // === 1. `${path}` template interpolation ===
         const regex = /\${(.*?)}/g;
         const matches = str.match(regex);
         if (matches) {
             for (const match of matches) {
-                try {
-                    const key = match.replace(/\${/g, "").replace(/}/g, "");
-                    const value = _.get(data, key) || this.runJs(key, ctx, data);
-                    // if (value) str = this.parseBasedOnType(str.replace(match, value), typeof value);
-                    str = str.replace(match, value);
-                }
-                catch (e) {
-                    console.log("Mapper Error 1", e);
+                const key = match.slice(2, -1); // strip `${` and `}`
+                const value = this.resolveTemplateExpression(key, ctx, data);
+                if (value !== TEMPLATE_RESOLUTION_FAILED) {
+                    str = str.replace(match, toInterpolatedString(value));
                 }
+                // On failure: leave the literal `${...}` placeholder in
+                // place. The failure was already reported per the active
+                // mode (warn/strict/silent).
             }
         }
-        const result = this.jsMapper(str, ctx, data);
-        return result;
+        // === 2. `js/...` full-string evaluation ===
+        return this.jsMapper(str, ctx, data);
     };
-    runJs(str, ctx, data = {}, func = {}, vars = {}) {
-        return Function("ctx", "data", "func", "vars", `"use strict";return (${str});`)(ctx, data, func, vars);
+    /**
+     * Resolve a `${path}` expression. Lodash lookup first; JS-eval
+     * fallback when the path is not in `data`. Returns the resolved
+     * value OR the failure sentinel.
+     */
+    resolveTemplateExpression(key, ctx, data) {
+        // Lodash lookup. Use explicit `=== undefined` instead of `||`
+        // so falsy-but-valid values (0, false, "", null) are preserved.
+        const lookupValue = _.get(data, key);
+        if (lookupValue !== undefined)
+            return lookupValue;
+        // Fallback to JS evaluation against ctx. Symmetric with jsMapper:
+        // pass `ctx.func` and `ctx.vars` so `${func.X}` and `${vars.X}`
+        // have the same scope as `js/func.X` / `js/vars.X`.
+        try {
+            return this.runJs(key, ctx, data, (ctx.func ?? {}), (ctx.vars ?? {}));
+        }
+        catch (cause) {
+            const stepCtx = readStepContext(ctx);
+            const error = new MapperResolutionError(buildErrorMessage({ expression: key, syntax: "template", ...stepCtx, cause }), { expression: key, syntax: "template", ...stepCtx, cause });
+            this.handleResolutionError(ctx, error);
+            return TEMPLATE_RESOLUTION_FAILED;
+        }
     }
+    /**
+     * Evaluate a `js/...` full-string expression. Returns whatever the
+     * expression produces (any type), or — in warn/silent mode on
+     * failure — the original literal `js/...` string.
+     *
+     * Strict-mode failures throw `MapperResolutionError`.
+     */
     jsMapper(str, ctx, data) {
+        if (typeof str !== "string" || !str.startsWith("js/"))
+            return str;
+        // `slice(3)` strips exactly the leading `js/` prefix.
+        // Pre-v0.3.x used `replace("js/", "")` which only strips the
+        // FIRST occurrence — fragile if the expression itself contained
+        // the substring `js/` (e.g., a URL like `https://js/foo`).
+        const expression = str.slice(3);
         try {
-            if (typeof str === "string" && str.startsWith("js/")) {
-                const fn = str.replace("js/", "");
-                return this.runJs(fn, ctx, data, ctx.func, ctx.vars);
-            }
+            return this.runJs(expression, ctx, data, (ctx.func ?? {}), (ctx.vars ?? {}));
         }
-        catch (error) {
-            console.log("Mapper Error 2", error);
+        catch (cause) {
+            const stepCtx = readStepContext(ctx);
+            const error = new MapperResolutionError(buildErrorMessage({ expression, syntax: "js", ...stepCtx, cause }), {
+                expression,
+                syntax: "js",
+                ...stepCtx,
+                cause,
+            });
+            this.handleResolutionError(ctx, error);
+            return str; // pre-v0.3.x behavior — pass through the literal string
         }
-        return str;
+    }
+    /**
+     * Apply the configured mode (`BLOK_MAPPER_MODE`) to a resolution
+     * failure. In strict mode, the error escapes here and propagates
+     * up through `replaceString` → `NodeBase.blueprintMapper` →
+     * `NodeBase.process` → step error envelope.
+     */
+    handleResolutionError(ctx, error) {
+        const mode = readMode();
+        if (mode === "strict")
+            throw error;
+        if (mode === "silent")
+            return;
+        // mode === "warn"
+        logViaCtxOrConsole(ctx, error.message);
+    }
+    /**
+     * Sandboxed JS evaluation. Compiles the expression as a function
+     * body returning the expression value; binds `ctx`, `data`, `func`,
+     * `vars` as positional arguments; runs in `"use strict"` mode.
+     *
+     * Throws on any evaluation error (typo, undefined access, syntax,
+     * unknown identifier). Callers wrap in try/catch and translate to
+     * `MapperResolutionError`.
+     *
+     * Public via the prototype but documented as internal — the only
+     * supported call sites are inside this class.
+     */
+    runJs(str, ctx, data = {}, func = {}, vars = {}) {
+        // Function constructor (NOT eval) — creates a fresh function
+        // scope without lexical access to the surrounding module. Same
+        // security profile as the v1 implementation.
+        return Function("ctx", "data", "func", "vars", `"use strict";return (${str});`)(ctx, data, func, vars);
     }
 }
 export default new Mapper();

package/dist/utils/Mapper.js.map

@@ -1 +1 @@
-{"version":3,"file":"Mapper.js","sourceRoot":"","sources":["../../src/utils/Mapper.ts"],"names":[],"mappings":"AAAA,OAAO,CAAC,MAAM,QAAQ,CAAC;AAMvB,MAAM,MAAM;IACJ,oBAAoB,CAAC,GAAqB,EAAE,GAAY,EAAE,IAAsB;QACtF,KAAK,MAAM,GAAG,IAAI,GAAG,EAAE,CAAC;YACvB,IAAI,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,CAAC,EAAE,CAAC;gBACpD,MAAM,KAAK,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC;gBACvB,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;oBAC/B,GAAG,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,aAAa,CAAC,KAAK,EAAE,GAAG,EAAE,IAAI,CAAC,CAAC;gBACjD,CAAC;qBAAM,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;oBACtC,IAAI,CAAC,oBAAoB,CAAC,KAAK,EAAE,GAAG,EAAE,IAAI,CAAC,CAAC;gBAC7C,CAAC;YACF,CAAC;QACF,CAAC;IACF,CAAC;IAEM,aAAa,GAAG,CAAC,OAAe,EAAE,GAAY,EAAE,IAAsB,EAAE,EAAE;QAChF,IAAI,GAAG,GAAG,OAAO,CAAC;QAElB,4BAA4B;QAC5B,sCAAsC;QACtC,IAAI;QACJ,MAAM,KAAK,GAAG,YAAY,CAAC;QAC3B,MAAM,OAAO,GAAG,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QAEjC,IAAI,OAAO,EAAE,CAAC;YACb,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;gBAC7B,IAAI,CAAC;oBACJ,MAAM,GAAG,GAAG,KAAK,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;oBACxD,MAAM,KAAK,GAAG,CAAC,CAAC,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC,IAAI,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,GAAG,EAAE,IAAI,CAAC,CAAC;oBAC7D,mFAAmF;oBACnF,GAAG,GAAG,GAAG,CAAC,OAAO,CAAC,KAAK,EAAE,KAAe,CAAC,CAAC;gBAC3C,CAAC;gBAAC,OAAO,CAAC,EAAE,CAAC;oBACZ,OAAO,CAAC,GAAG,CAAC,gBAAgB,EAAE,CAAC,CAAC,CAAC;gBAClC,CAAC;YACF,CAAC;QACF,CAAC;QACD,MAAM,MAAM,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,EAAE,GAAG,EAAE,IAAI,CAAW,CAAC;QACvD,OAAO,MAAM,CAAC;IACf,CAAC,CAAC;IAEM,KAAK,CACZ,GAAW,EACX,GAAY,EACZ,OAAyB,EAAE,EAC3B,OAAwB,EAAE,EAC1B,OAAoB,EAAE;QAEtB,OAAO,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,wBAAwB,GAAG,IAAI,CAAC,CAAC,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;IACxG,CAAC;IAEO,QAAQ,CAAC,GAAW,EAAE,GAAY,EAAE,IAAsB;QACjE,IAAI,CAAC;YACJ,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,CAAC,UAAU,CAAC,KAAK,CAAC,EAAE,CAAC;gBACtD,MAAM,EAAE,GAAG,GAAG,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;gBAClC,OAAO,IAAI,CAAC,KAAK,CAAC,EAAE,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC,IAAI,CAAC,CAAC;YACtD,CAAC;QACF,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YAChB,OAAO,CAAC,GAAG,CAAC,gBAAgB,EAAE,KAAK,CAAC,CAAC;QACtC,CAAC;QACD,OAAO,GAAG,CAAC;IACZ,CAAC;CACD;AAED,eAAe,IAAI,MAAM,EAAE,CAAC"}
+{"version":3,"file":"Mapper.js","sourceRoot":"","sources":["../../src/utils/Mapper.ts"],"names":[],"mappings":"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"}

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.2",
+	"version": "0.6.0",
 	"description": "Shared class, interfaces and types",
 	"type": "module",
 	"main": "dist/index.js",