@stackables/bridge 1.0.0

package/build/ExecutionTree.js

@@ -0,0 +1,403 @@
+import { parsePath } from "./bridge-format.js";
+import { SELF_MODULE } from "./types.js";
+/** Stable string key for the state map */
+function trunkKey(ref) {
+    if (ref.element)
+        return `${ref.module}:${ref.type}:${ref.field}:*`;
+    return `${ref.module}:${ref.type}:${ref.field}${ref.instance != null ? `:${ref.instance}` : ""}`;
+}
+/** Match two trunks (ignoring path and element) */
+function sameTrunk(a, b) {
+    return (a.module === b.module &&
+        a.type === b.type &&
+        a.field === b.field &&
+        (a.instance ?? undefined) === (b.instance ?? undefined));
+}
+/** Strict path equality */
+function pathEquals(a, b) {
+    return a.length === b.length && a.every((v, i) => v === b[i]);
+}
+/** Set a value at a nested path, creating intermediate objects/arrays as needed */
+function setNested(obj, path, value) {
+    for (let i = 0; i < path.length - 1; i++) {
+        const key = path[i];
+        const nextKey = path[i + 1];
+        if (obj[key] == null) {
+            obj[key] = /^\d+$/.test(nextKey) ? [] : {};
+        }
+        obj = obj[key];
+    }
+    if (path.length > 0) {
+        obj[path[path.length - 1]] = value;
+    }
+}
+export class ExecutionTree {
+    trunk;
+    instructions;
+    toolFns;
+    context;
+    parent;
+    state = {};
+    bridge;
+    toolDepCache = new Map();
+    toolDefCache = new Map();
+    pipeHandleMap;
+    constructor(trunk, instructions, toolFns, context, parent) {
+        this.trunk = trunk;
+        this.instructions = instructions;
+        this.toolFns = toolFns;
+        this.context = context;
+        this.parent = parent;
+        this.bridge = instructions.find((i) => i.kind === "bridge" && i.type === trunk.type && i.field === trunk.field);
+        if (this.bridge?.pipeHandles) {
+            this.pipeHandleMap = new Map(this.bridge.pipeHandles.map((ph) => [ph.key, ph]));
+        }
+        if (context) {
+            this.state[trunkKey({ module: SELF_MODULE, type: "Context", field: "context" })] = context;
+        }
+        // Collect const definitions into a single namespace object
+        const constObj = {};
+        for (const inst of instructions) {
+            if (inst.kind === "const") {
+                constObj[inst.name] = JSON.parse(inst.value);
+            }
+        }
+        if (Object.keys(constObj).length > 0) {
+            this.state[trunkKey({ module: SELF_MODULE, type: "Const", field: "const" })] = constObj;
+        }
+    }
+    /** Derive tool name from a trunk */
+    getToolName(target) {
+        if (target.module === SELF_MODULE)
+            return target.field;
+        return `${target.module}.${target.field}`;
+    }
+    /** Deep-lookup a tool function by dotted name (e.g. "std.upperCase").
+     *  Falls back to a flat key lookup for backward compat (e.g. "hereapi.geocode" as literal key). */
+    lookupToolFn(name) {
+        if (name.includes(".")) {
+            // Try namespace traversal first
+            const parts = name.split(".");
+            let current = this.toolFns;
+            for (const part of parts) {
+                if (current == null || typeof current !== "object") {
+                    current = undefined;
+                    break;
+                }
+                current = current[part];
+            }
+            if (typeof current === "function")
+                return current;
+            // Fall back to flat key (e.g. "hereapi.geocode" as a literal property name)
+            const flat = this.toolFns?.[name];
+            return typeof flat === "function" ? flat : undefined;
+        }
+        // Try root level first
+        const fn = this.toolFns?.[name];
+        if (typeof fn === "function")
+            return fn;
+        // Fall back to std namespace (builtins are callable without std. prefix)
+        const stdFn = this.toolFns?.std?.[name];
+        return typeof stdFn === "function" ? stdFn : undefined;
+    }
+    /** Resolve a ToolDef by name, merging the extends chain (cached) */
+    resolveToolDefByName(name) {
+        if (this.toolDefCache.has(name))
+            return this.toolDefCache.get(name) ?? undefined;
+        const toolDefs = this.instructions.filter((i) => i.kind === "tool");
+        const base = toolDefs.find((t) => t.name === name);
+        if (!base) {
+            this.toolDefCache.set(name, null);
+            return undefined;
+        }
+        // Build extends chain: root → ... → leaf
+        const chain = [base];
+        let current = base;
+        while (current.extends) {
+            const parent = toolDefs.find((t) => t.name === current.extends);
+            if (!parent)
+                throw new Error(`Tool "${current.name}" extends unknown tool "${current.extends}"`);
+            chain.unshift(parent);
+            current = parent;
+        }
+        // Merge: root provides base, each child overrides
+        const merged = {
+            kind: "tool",
+            name,
+            fn: chain[0].fn, // fn from root ancestor
+            deps: [],
+            wires: [],
+        };
+        for (const def of chain) {
+            // Merge deps (dedupe by handle)
+            for (const dep of def.deps) {
+                if (!merged.deps.some((d) => d.handle === dep.handle)) {
+                    merged.deps.push(dep);
+                }
+            }
+            // Merge wires (child overrides parent by target; onError replaces onError)
+            for (const wire of def.wires) {
+                if (wire.kind === "onError") {
+                    const idx = merged.wires.findIndex((w) => w.kind === "onError");
+                    if (idx >= 0)
+                        merged.wires[idx] = wire;
+                    else
+                        merged.wires.push(wire);
+                }
+                else {
+                    const idx = merged.wires.findIndex((w) => "target" in w && w.target === wire.target);
+                    if (idx >= 0)
+                        merged.wires[idx] = wire;
+                    else
+                        merged.wires.push(wire);
+                }
+            }
+        }
+        this.toolDefCache.set(name, merged);
+        return merged;
+    }
+    /** Resolve a tool definition's wires into a nested input object */
+    async resolveToolWires(toolDef, input) {
+        // Constants applied synchronously
+        for (const wire of toolDef.wires) {
+            if (wire.kind === "constant") {
+                setNested(input, parsePath(wire.target), wire.value);
+            }
+        }
+        // Pull wires resolved in parallel (independent deps shouldn't wait on each other)
+        const pullWires = toolDef.wires.filter((w) => w.kind === "pull");
+        if (pullWires.length > 0) {
+            const resolved = await Promise.all(pullWires.map(async (wire) => ({
+                target: wire.target,
+                value: await this.resolveToolSource(wire.source, toolDef),
+            })));
+            for (const { target, value } of resolved) {
+                setNested(input, parsePath(target), value);
+            }
+        }
+    }
+    /** Resolve a source reference from a tool wire against its dependencies */
+    async resolveToolSource(source, toolDef) {
+        const dotIdx = source.indexOf(".");
+        const handle = dotIdx === -1 ? source : source.substring(0, dotIdx);
+        const restPath = dotIdx === -1 ? [] : source.substring(dotIdx + 1).split(".");
+        const dep = toolDef.deps.find((d) => d.handle === handle);
+        if (!dep)
+            throw new Error(`Unknown source "${handle}" in tool "${toolDef.name}"`);
+        let value;
+        if (dep.kind === "context") {
+            value = this.context ?? this.parent?.context;
+        }
+        else if (dep.kind === "const") {
+            value = this.state[trunkKey({ module: SELF_MODULE, type: "Const", field: "const" })] ?? this.parent?.state[trunkKey({ module: SELF_MODULE, type: "Const", field: "const" })];
+        }
+        else if (dep.kind === "tool") {
+            value = await this.resolveToolDep(dep.tool);
+        }
+        for (const segment of restPath) {
+            value = value?.[segment];
+        }
+        return value;
+    }
+    /** Call a tool dependency (cached per request) */
+    resolveToolDep(toolName) {
+        // Check parent first (shadow trees delegate)
+        if (this.parent)
+            return this.parent.resolveToolDep(toolName);
+        if (this.toolDepCache.has(toolName))
+            return this.toolDepCache.get(toolName);
+        const promise = (async () => {
+            const toolDef = this.resolveToolDefByName(toolName);
+            if (!toolDef)
+                throw new Error(`Tool dependency "${toolName}" not found`);
+            const input = {};
+            await this.resolveToolWires(toolDef, input);
+            const fn = this.lookupToolFn(toolDef.fn);
+            if (!fn)
+                throw new Error(`Tool function "${toolDef.fn}" not registered`);
+            // on error: wrap the tool call with fallback from onError wire
+            const onErrorWire = toolDef.wires.find((w) => w.kind === "onError");
+            try {
+                return await fn(input);
+            }
+            catch (err) {
+                if (!onErrorWire)
+                    throw err;
+                if ("value" in onErrorWire)
+                    return JSON.parse(onErrorWire.value);
+                return this.resolveToolSource(onErrorWire.source, toolDef);
+            }
+        })();
+        this.toolDepCache.set(toolName, promise);
+        return promise;
+    }
+    schedule(target) {
+        // Delegate to parent (shadow trees don't schedule directly)
+        if (this.parent) {
+            return this.parent.schedule(target);
+        }
+        return (async () => {
+            // If this target is a pipe fork, also apply bridge wires from its base
+            // handle (non-pipe wires, e.g. `c.currency <- i.currency`) as defaults
+            // before the fork-specific pipe wires.
+            const targetKey = trunkKey(target);
+            const pipeFork = this.pipeHandleMap?.get(targetKey);
+            const baseTrunk = pipeFork?.baseTrunk;
+            const baseWires = baseTrunk
+                ? (this.bridge?.wires.filter((w) => !("pipe" in w) && sameTrunk(w.to, baseTrunk)) ?? [])
+                : [];
+            // Fork-specific wires (pipe wires targeting the fork's own instance)
+            const forkWires = this.bridge?.wires.filter((w) => sameTrunk(w.to, target)) ?? [];
+            // Merge: base provides defaults, fork overrides
+            const bridgeWires = [...baseWires, ...forkWires];
+            // Look up ToolDef for this target
+            const toolName = this.getToolName(target);
+            const toolDef = this.resolveToolDefByName(toolName);
+            // Build input object: tool wires first (base), then bridge wires (override)
+            const input = {};
+            if (toolDef) {
+                await this.resolveToolWires(toolDef, input);
+            }
+            // Resolve bridge wires and apply on top
+            const resolved = await Promise.all(bridgeWires.map(async (w) => {
+                const value = "value" in w ? w.value : await this.pullSingle(w.from);
+                return [w.to.path, value];
+            }));
+            for (const [path, value] of resolved) {
+                setNested(input, path, value);
+            }
+            // Call ToolDef-backed tool function
+            if (toolDef) {
+                const fn = this.lookupToolFn(toolDef.fn);
+                if (!fn)
+                    throw new Error(`Tool function "${toolDef.fn}" not registered`);
+                // on error: wrap the tool call with fallback from onError wire
+                const onErrorWire = toolDef.wires.find((w) => w.kind === "onError");
+                try {
+                    return await fn(input);
+                }
+                catch (err) {
+                    if (!onErrorWire)
+                        throw err;
+                    if ("value" in onErrorWire)
+                        return JSON.parse(onErrorWire.value);
+                    return this.resolveToolSource(onErrorWire.source, toolDef);
+                }
+            }
+            // Direct tool function lookup by name (simple or dotted)
+            const directFn = this.lookupToolFn(toolName);
+            if (directFn) {
+                return directFn(input);
+            }
+            throw new Error(`No tool found for "${toolName}"`);
+        })();
+    }
+    shadow() {
+        return new ExecutionTree(this.trunk, this.instructions, this.toolFns, undefined, this);
+    }
+    async pullSingle(ref) {
+        const key = trunkKey(ref);
+        let value = this.state[key] ?? this.parent?.state[key];
+        if (value === undefined) {
+            this.state[key] = this.schedule(ref);
+            value = this.state[key];
+        }
+        // Always await in case the stored value is a Promise (e.g. from schedule()).
+        const resolved = await Promise.resolve(value);
+        if (!ref.path.length) {
+            return resolved;
+        }
+        let result = resolved;
+        for (const segment of ref.path) {
+            if (Array.isArray(result) && !/^\d+$/.test(segment)) {
+                console.warn(`[bridge] Accessing ".${segment}" on an array (${result.length} items) — did you mean to use pickFirst or array mapping? Source: ${trunkKey(ref)}.${ref.path.join(".")}`);
+            }
+            result = result?.[segment];
+        }
+        return result;
+    }
+    async pull(refs) {
+        return Promise.any(refs.map((ref) => this.pullSingle(ref)));
+    }
+    push(args) {
+        this.state[trunkKey(this.trunk)] = args;
+    }
+    /** Eagerly schedule tools targeted by forced (<-!) wires. */
+    executeForced() {
+        const forcedWires = this.bridge?.wires.filter((w) => "from" in w && !!w.force) ?? [];
+        const scheduled = new Set();
+        for (const wire of forcedWires) {
+            // For pipe wires the target is the fork trunk; for regular wires it's
+            // the tool trunk.  In both cases scheduling the target kicks off
+            // resolution of all its input wires (including the forced source).
+            const key = trunkKey(wire.to);
+            if (scheduled.has(key) || this.state[key] !== undefined)
+                continue;
+            scheduled.add(key);
+            this.state[key] = this.schedule(wire.to);
+            // Fire-and-forget: suppress unhandled rejection for side-effect tools
+            // whose output is never consumed.
+            Promise.resolve(this.state[key]).catch(() => { });
+        }
+    }
+    /** Resolve a set of matched wires — constants win, then pull from sources.\n   *  If a wire has a `fallback` value and all sources reject, return the fallback. */
+    resolveWires(wires) {
+        const constant = wires.find((w) => "value" in w);
+        if (constant)
+            return Promise.resolve(constant.value);
+        const pulls = wires.filter((w) => "from" in w);
+        // Collect any fallback value from the wires (first one wins)
+        const fallbackWire = pulls.find((w) => w.fallback != null);
+        const result = this.pull(pulls.map((w) => w.from));
+        if (!fallbackWire)
+            return result;
+        return result.catch(() => {
+            try {
+                return JSON.parse(fallbackWire.fallback);
+            }
+            catch {
+                // Not valid JSON — return as raw string
+                return fallbackWire.fallback;
+            }
+        });
+    }
+    async response(ipath, array) {
+        // Build path segments from GraphQL resolver info
+        const pathSegments = [];
+        let index = ipath;
+        while (index.prev) {
+            pathSegments.unshift(`${index.key}`);
+            index = index.prev;
+        }
+        if (pathSegments.length === 0) {
+            // Direct output for scalar/list return types (e.g. [String!])
+            const directOutput = this.bridge?.wires.filter((w) => sameTrunk(w.to, this.trunk) &&
+                w.to.path.length === 1 &&
+                w.to.path[0] === this.trunk.field) ?? [];
+            if (directOutput.length > 0) {
+                return this.resolveWires(directOutput);
+            }
+        }
+        // Strip numeric indices (array positions) from path for wire matching
+        const cleanPath = pathSegments.filter((p) => !/^\d+$/.test(p));
+        // Find wires whose target matches this trunk + path
+        const matches = this.bridge?.wires.filter((w) => !w.to.element &&
+            sameTrunk(w.to, this.trunk) &&
+            pathEquals(w.to.path, cleanPath)) ?? [];
+        if (matches.length > 0) {
+            const response = this.resolveWires(matches);
+            if (!array) {
+                return response;
+            }
+            // Array: create shadow trees for per-element resolution
+            const items = (await response);
+            return items.map((item) => {
+                const s = this.shadow();
+                s.state[trunkKey({ ...this.trunk, element: true })] = item;
+                return s;
+            });
+        }
+        // Return self to trigger downstream resolvers
+        return this;
+    }
+}

package/build/bridge-format.d.ts

@@ -0,0 +1,24 @@
+import type { Instruction } from "./types.js";
+/**
+ * Parse .bridge text format into structured instructions.
+ *
+ * The .bridge format is a human-readable representation of connection wires.
+ * Multiple blocks are separated by `---`.
+ * Tool blocks define API tools, bridge blocks define wire mappings.
+ *
+ * @param text - Bridge definition text
+ * @returns Array of instructions (Bridge, ToolDef)
+ */
+export declare function parseBridge(text: string): Instruction[];
+/**
+ * Parse a dot-separated path with optional array indices.
+ *
+ * "items[0].position.lat" → ["items", "0", "position", "lat"]
+ * "properties[]"          → ["properties"]  ([] is stripped, signals array)
+ * "x-message-id"          → ["x-message-id"]
+ */
+export declare function parsePath(text: string): string[];
+/**
+ * Serialize structured instructions back to .bridge text format.
+ */
+export declare function serializeBridge(instructions: Instruction[]): string;