@stackables/bridge 1.5.0 → 1.6.1

package/build/ExecutionTree.d.ts

@@ -11,6 +11,45 @@ type Trunk = {
     field: string;
     instance?: number;
 };
+/** Trace verbosity level */
+export type TraceLevel = "basic" | "full";
+/** A single recorded tool invocation. */
+export type ToolTrace = {
+    /** Tool name as resolved (e.g. "hereGeo", "std.upperCase") */
+    tool: string;
+    /** The function that was called (e.g. "httpCall", "upperCase") */
+    fn: string;
+    /** Input object passed to the tool function (only in "full" level) */
+    input?: Record<string, any>;
+    /** Resolved output (only in "full" level, on success) */
+    output?: any;
+    /** Error message (present when the tool threw) */
+    error?: string;
+    /** Wall-clock duration in milliseconds */
+    durationMs: number;
+    /** Monotonic timestamp (ms) relative to the first trace in the request */
+    startedAt: number;
+};
+/** Shared trace collector — one per request, passed through the tree. */
+export declare class TraceCollector {
+    readonly traces: ToolTrace[];
+    readonly level: TraceLevel;
+    private readonly epoch;
+    constructor(level?: TraceLevel);
+    /** Returns ms since the collector was created */
+    now(): number;
+    record(trace: ToolTrace): void;
+    /** Build a trace entry, omitting input/output for basic level. */
+    entry(base: {
+        tool: string;
+        fn: string;
+        startedAt: number;
+        durationMs: number;
+        input?: Record<string, any>;
+        output?: any;
+        error?: string;
+    }): ToolTrace;
+}
 export declare class ExecutionTree {
     trunk: Trunk;
     private instructions;
@@ -22,6 +61,8 @@ export declare class ExecutionTree {
     private toolDepCache;
     private toolDefCache;
     private pipeHandleMap;
+    /** Shared trace collector — present only when tracing is enabled. */
+    tracer?: TraceCollector;
     constructor(trunk: Trunk, instructions: Instruction[], toolFns?: ToolMap | undefined, context?: Record<string, any> | undefined, parent?: ExecutionTree | undefined);
     /** Derive tool name from a trunk */
     private getToolName;
@@ -38,7 +79,15 @@ export declare class ExecutionTree {
     private resolveToolDep;
     schedule(target: Trunk): any;
     shadow(): ExecutionTree;
+    /** Returns collected traces (empty array when tracing is disabled). */
+    getTraces(): ToolTrace[];
     private pullSingle;
+    /**
+     * Infer the cost of resolving a NodeRef.
+     * Cost 0: memory reads (input, context, const) — no I/O.
+     * Cost 1: everything else (tool calls, pipes, defines) — may involve network.
+     */
+    private inferCost;
     pull(refs: NodeRef[]): Promise<any>;
     push(args: Record<string, any>): void;
     /** Eagerly schedule tools targeted by forced (<-!) wires. */
@@ -48,6 +97,14 @@ export declare class ExecutionTree {
      *  `??` (fallback/fallbackRef): fires when all sources reject (throw/error). */
     private resolveWires;
     response(ipath: Path, array: boolean): Promise<any>;
+    /**
+     * Find define output wires for a specific field path.
+     *
+     * Looks for whole-object define forward wires (`o <- defineHandle`)
+     * at path=[] for this trunk, then searches the define's output wires
+     * for ones matching the requested field path.
+     */
+    private findDefineFieldWires;
 }
 export {};
 //# sourceMappingURL=ExecutionTree.d.ts.map

package/build/ExecutionTree.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ExecutionTree.d.ts","sourceRoot":"","sources":["../src/ExecutionTree.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,MAAM,EAEN,WAAW,EACX,OAAO,EAGP,OAAO,EAER,MAAM,YAAY,CAAC;AAGpB,gFAAgF;AAChF,UAAU,IAAI;IACZ,QAAQ,CAAC,IAAI,EAAE,IAAI,GAAG,SAAS,CAAC;IAChC,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC;IAC9B,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC;CACvC;AAED,KAAK,KAAK,GAAG;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAsChF,qBAAa,aAAa;IAQf,KAAK,EAAE,KAAK;IACnB,OAAO,CAAC,YAAY;IACpB,OAAO,CAAC,OAAO,CAAC;IAChB,OAAO,CAAC,OAAO,CAAC;IAChB,OAAO,CAAC,MAAM,CAAC;IAXjB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAM;IAChC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,OAAO,CAAC,YAAY,CAAwC;IAC5D,OAAO,CAAC,YAAY,CAA0C;IAC9D,OAAO,CAAC,aAAa,CAAsE;gBAGlF,KAAK,EAAE,KAAK,EACX,YAAY,EAAE,WAAW,EAAE,EAC3B,OAAO,CAAC,EAAE,OAAO,YAAA,EACjB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,YAAA,EAC7B,MAAM,CAAC,EAAE,aAAa,YAAA;IA8BhC,oCAAoC;IACpC,OAAO,CAAC,WAAW;IAKnB;uGACmG;IACnG,OAAO,CAAC,YAAY;IAsBpB,oEAAoE;IACpE,OAAO,CAAC,oBAAoB;IA8D5B,mEAAmE;YACrD,gBAAgB;IA0B9B,2EAA2E;YAC7D,iBAAiB;IAyC/B,kDAAkD;IAClD,OAAO,CAAC,cAAc;IAgCtB,QAAQ,CAAC,MAAM,EAAE,KAAK,GAAG,GAAG;IA8F5B,MAAM,IAAI,aAAa;YAUT,UAAU;IAmClB,IAAI,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,GAAG,CAAC;IAqCzC,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;IAI9B,6DAA6D;IAC7D,aAAa,IAAI,IAAI;IAqBrB;;oFAEgF;IAChF,OAAO,CAAC,YAAY;IA8Cd,QAAQ,CAAC,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC;CA+E1D"}
+{"version":3,"file":"ExecutionTree.d.ts","sourceRoot":"","sources":["../src/ExecutionTree.ts"],"names":[],"mappings":"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"}

package/build/ExecutionTree.js

@@ -17,6 +17,40 @@ function sameTrunk(a, b) {
 function pathEquals(a, b) {
     return a.length === b.length && a.every((v, i) => v === b[i]);
 }
+/** Shared trace collector — one per request, passed through the tree. */
+export class TraceCollector {
+    traces = [];
+    level;
+    epoch = performance.now();
+    constructor(level = "full") {
+        this.level = level;
+    }
+    /** Returns ms since the collector was created */
+    now() {
+        return Math.round((performance.now() - this.epoch) * 100) / 100;
+    }
+    record(trace) {
+        this.traces.push(trace);
+    }
+    /** Build a trace entry, omitting input/output for basic level. */
+    entry(base) {
+        if (this.level === "basic") {
+            const t = { tool: base.tool, fn: base.fn, durationMs: base.durationMs, startedAt: base.startedAt };
+            if (base.error)
+                t.error = base.error;
+            return t;
+        }
+        // full
+        const t = { tool: base.tool, fn: base.fn, durationMs: base.durationMs, startedAt: base.startedAt };
+        if (base.input)
+            t.input = structuredClone(base.input);
+        if (base.error)
+            t.error = base.error;
+        else if (base.output !== undefined)
+            t.output = base.output;
+        return t;
+    }
+}
 /** 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++) {
@@ -42,6 +76,8 @@ export class ExecutionTree {
     toolDepCache = new Map();
     toolDefCache = new Map();
     pipeHandleMap;
+    /** Shared trace collector — present only when tracing is enabled. */
+    tracer;
     constructor(trunk, instructions, toolFns, context, parent) {
         this.trunk = trunk;
         this.instructions = instructions;
@@ -230,10 +266,19 @@ export class ExecutionTree {
                 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");
+            const tracer = this.tracer;
+            const traceStart = tracer?.now();
             try {
-                return await fn(input);
+                const result = await fn(input);
+                if (tracer && traceStart != null) {
+                    tracer.record(tracer.entry({ tool: toolName, fn: toolDef.fn, input, output: result, durationMs: Math.round((tracer.now() - traceStart) * 100) / 100, startedAt: traceStart }));
+                }
+                return result;
             }
             catch (err) {
+                if (tracer && traceStart != null) {
+                    tracer.record(tracer.entry({ tool: toolName, fn: toolDef.fn, input, error: err.message, durationMs: Math.round((tracer.now() - traceStart) * 100) / 100, startedAt: traceStart }));
+                }
                 if (!onErrorWire)
                     throw err;
                 if ("value" in onErrorWire)
@@ -304,10 +349,19 @@ export class ExecutionTree {
                     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");
+                const tracer = this.tracer;
+                const traceStart = tracer?.now();
                 try {
-                    return await fn(input);
+                    const result = await fn(input);
+                    if (tracer && traceStart != null) {
+                        tracer.record(tracer.entry({ tool: toolName, fn: toolDef.fn, input, output: result, durationMs: Math.round((tracer.now() - traceStart) * 100) / 100, startedAt: traceStart }));
+                    }
+                    return result;
                 }
                 catch (err) {
+                    if (tracer && traceStart != null) {
+                        tracer.record(tracer.entry({ tool: toolName, fn: toolDef.fn, input, error: err.message, durationMs: Math.round((tracer.now() - traceStart) * 100) / 100, startedAt: traceStart }));
+                    }
                     if (!onErrorWire)
                         throw err;
                     if ("value" in onErrorWire)
@@ -318,7 +372,21 @@ export class ExecutionTree {
             // Direct tool function lookup by name (simple or dotted)
             const directFn = this.lookupToolFn(toolName);
             if (directFn) {
-                return directFn(input);
+                const tracer = this.tracer;
+                const traceStart = tracer?.now();
+                try {
+                    const result = await directFn(input);
+                    if (tracer && traceStart != null) {
+                        tracer.record(tracer.entry({ tool: toolName, fn: toolName, input, output: result, durationMs: Math.round((tracer.now() - traceStart) * 100) / 100, startedAt: traceStart }));
+                    }
+                    return result;
+                }
+                catch (err) {
+                    if (tracer && traceStart != null) {
+                        tracer.record(tracer.entry({ tool: toolName, fn: toolName, input, error: err.message, durationMs: Math.round((tracer.now() - traceStart) * 100) / 100, startedAt: traceStart }));
+                    }
+                    throw err;
+                }
             }
             // Define pass-through: synthetic trunks created by define inlining
             // act as data containers — bridge wires set their values, no tool needed.
@@ -329,7 +397,13 @@ export class ExecutionTree {
         })();
     }
     shadow() {
-        return new ExecutionTree(this.trunk, this.instructions, this.toolFns, undefined, this);
+        const child = new ExecutionTree(this.trunk, this.instructions, this.toolFns, undefined, this);
+        child.tracer = this.tracer;
+        return child;
+    }
+    /** Returns collected traces (empty array when tracing is disabled). */
+    getTraces() {
+        return this.tracer?.traces ?? [];
     }
     async pullSingle(ref) {
         const key = trunkKey(ref);
@@ -342,6 +416,18 @@ export class ExecutionTree {
             cursor = cursor.parent;
         }
         if (value === undefined) {
+            // ── Lazy define field resolution ────────────────────────────────
+            // For define trunks (__define_in_* / __define_out_*) with a specific
+            // field path, resolve ONLY the wire(s) targeting that field instead
+            // of scheduling the entire trunk.  This avoids triggering unrelated
+            // dependency chains (e.g. requesting "city" should not fire the
+            // lat/lon coalesce chains that call the geo tool).
+            if (ref.path.length > 0 && ref.module.startsWith("__define_")) {
+                const fieldWires = this.bridge?.wires.filter((w) => sameTrunk(w.to, ref) && pathEquals(w.to.path, ref.path)) ?? [];
+                if (fieldWires.length > 0) {
+                    return this.resolveWires(fieldWires);
+                }
+            }
             this.state[key] = this.schedule(ref);
             value = this.state[key];
         }
@@ -359,37 +445,62 @@ export class ExecutionTree {
         }
         return result;
     }
+    /**
+     * Infer the cost of resolving a NodeRef.
+     * Cost 0: memory reads (input, context, const) — no I/O.
+     * Cost 1: everything else (tool calls, pipes, defines) — may involve network.
+     */
+    inferCost(ref) {
+        // Input args, context, and const live in the state map — free reads
+        if (ref.module === SELF_MODULE) {
+            const key = trunkKey(ref);
+            // Already resolved in state? Free.
+            // eslint-disable-next-line @typescript-eslint/no-this-alias
+            let cursor = this;
+            while (cursor) {
+                if (cursor.state[key] !== undefined)
+                    return 0;
+                cursor = cursor.parent;
+            }
+            // Input/context/const trunks are always cost 0
+            if (ref.type === "Context" || ref.type === "Const")
+                return 0;
+            // Input args trunk: _:Query:fieldName (same as this.trunk) — cost 0
+            if (ref.module === SELF_MODULE && ref.type === this.trunk.type && ref.field === this.trunk.field && !ref.element)
+                return 0;
+        }
+        return 1;
+    }
     async pull(refs) {
         if (refs.length === 1)
             return this.pullSingle(refs[0]);
-        // Multiple sources: all start in parallel.
-        // Return the first that resolves to a non-null/undefined value.
-        // If all resolve to null/undefined → resolve undefined (lets || fire).
-        // If all reject → throw AggregateError (lets ?? fire).
-        return new Promise((resolve, reject) => {
-            let remaining = refs.length;
-            let hasValue = false;
-            const errors = [];
-            const settle = () => {
-                if (--remaining === 0 && !hasValue) {
-                    if (errors.length === refs.length) {
-                        reject(new AggregateError(errors, "All sources failed"));
-                    }
-                    else {
-                        resolve(undefined); // all resolved to null/undefined
-                    }
-                }
-            };
-            for (const ref of refs) {
-                this.pullSingle(ref).then((value) => {
-                    if (!hasValue && value != null) {
-                        hasValue = true;
-                        resolve(value);
-                    }
-                    settle();
-                }, (err) => { errors.push(err); settle(); });
+        // Cost-sorted sequential evaluation with short-circuit.
+        //
+        // Sort by inferred cost (stable — preserves declaration order within
+        // the same cost tier). This means:
+        //   • ||  chains (both sources are tools = same cost) → left-to-right
+        //   • Overdefinition with mixed costs → cheapest first
+        //
+        // Evaluate sequentially. Return the first non-null value.
+        // If all return null/undefined → return undefined (lets || fire).
+        // If all throw → throw AggregateError (lets ?? fire).
+        const sorted = [...refs].sort((a, b) => this.inferCost(a) - this.inferCost(b));
+        const errors = [];
+        for (const ref of sorted) {
+            try {
+                const value = await this.pullSingle(ref);
+                if (value != null)
+                    return value; // Short-circuit: found data
             }
-        });
+            catch (err) {
+                errors.push(err);
+            }
+        }
+        // All resolved to null/undefined, or all threw
+        if (errors.length === refs.length) {
+            throw new AggregateError(errors, "All sources failed");
+        }
+        return undefined;
     }
     push(args) {
         this.state[trunkKey(this.trunk)] = args;
@@ -479,6 +590,20 @@ export class ExecutionTree {
             sameTrunk(w.to, this.trunk) &&
             pathEquals(w.to.path, cleanPath)) ?? [];
         if (matches.length > 0) {
+            // ── Lazy define resolution ──────────────────────────────────────
+            // When ALL matches at the root object level (path=[]) are
+            // whole-object wires sourced from define output modules, defer
+            // resolution to field-by-field GraphQL traversal.  This avoids
+            // eagerly scheduling every tool inside the define block — only
+            // fields actually requested by the query will trigger their
+            // dependency chains.
+            if (cleanPath.length === 0 &&
+                !array &&
+                matches.every((w) => "from" in w &&
+                    w.from.module.startsWith("__define_out_") &&
+                    w.from.path.length === 0)) {
+                return this;
+            }
             const response = this.resolveWires(matches);
             if (!array) {
                 return response;
@@ -491,6 +616,24 @@ export class ExecutionTree {
                 return s;
             });
         }
+        // ── Resolve field from deferred define ────────────────────────────
+        // No direct wires for this field path — check whether a define
+        // forward wire exists at the root level (`o <- defineHandle`) and
+        // resolve only the matching field wire from the define's output.
+        if (cleanPath.length > 0) {
+            const defineFieldWires = this.findDefineFieldWires(cleanPath);
+            if (defineFieldWires.length > 0) {
+                const response = this.resolveWires(defineFieldWires);
+                if (!array)
+                    return response;
+                const items = (await response);
+                return items.map((item) => {
+                    const s = this.shadow();
+                    s.state[trunkKey({ ...this.trunk, element: true })] = item;
+                    return s;
+                });
+            }
+        }
         // Fallback: if this shadow tree has stored element data, resolve the
         // requested field directly from it. This handles passthrough arrays
         // where the bridge maps an inner array (e.g. `.stops <- j.stops`) but
@@ -518,4 +661,28 @@ export class ExecutionTree {
         // Return self to trigger downstream resolvers
         return this;
     }
+    /**
+     * Find define output wires for a specific field path.
+     *
+     * Looks for whole-object define forward wires (`o <- defineHandle`)
+     * at path=[] for this trunk, then searches the define's output wires
+     * for ones matching the requested field path.
+     */
+    findDefineFieldWires(cleanPath) {
+        const forwards = this.bridge?.wires.filter((w) => "from" in w &&
+            sameTrunk(w.to, this.trunk) &&
+            w.to.path.length === 0 &&
+            w.from.module.startsWith("__define_out_") &&
+            w.from.path.length === 0) ?? [];
+        if (forwards.length === 0)
+            return [];
+        const result = [];
+        for (const fw of forwards) {
+            const defOutTrunk = fw.from;
+            const fieldWires = this.bridge?.wires.filter((w) => sameTrunk(w.to, defOutTrunk) &&
+                pathEquals(w.to.path, cleanPath)) ?? [];
+            result.push(...fieldWires);
+        }
+        return result;
+    }
 }

package/build/bridge-transform.d.ts

@@ -1,4 +1,5 @@
 import { type GraphQLSchema } from "graphql";
+import { type ToolTrace, type TraceLevel } from "./ExecutionTree.js";
 import type { Instruction, ToolMap } from "./types.js";
 export type BridgeOptions = {
     /** Tool functions available to the engine.
@@ -9,8 +10,40 @@ export type BridgeOptions = {
     /** Optional function to reshape/restrict the GQL context before it reaches bridge files.
      *  By default the full context is exposed via `with context`. */
     contextMapper?: (context: any) => Record<string, any>;
+    /** Enable tool-call tracing.
+     *  - `true` or `"full"`: record tool, fn, input, output/error, timing
+     *  - `"basic"`: record tool, fn, timing, error (no input/output) */
+    trace?: boolean | TraceLevel;
 };
 /** Instructions can be a static array or a function that selects per-request */
 export type InstructionSource = Instruction[] | ((context: any) => Instruction[]);
 export declare function bridgeTransform(schema: GraphQLSchema, instructions: InstructionSource, options?: BridgeOptions): GraphQLSchema;
+/**
+ * Read traces that were collected during the current request.
+ * Pass the GraphQL context object; returns an empty array when tracing is
+ * disabled or no traces were recorded.
+ */
+export declare function getBridgeTraces(context: any): ToolTrace[];
+/**
+ * Envelop-compatible plugin for GraphQL Yoga (or any Envelop-based server).
+ * When bridge tracing is enabled, this plugin copies the recorded traces into
+ * the GraphQL response `extensions.traces` field.
+ *
+ * Usage:
+ * ```ts
+ * createYoga({ schema, plugins: [useBridgeTracing()] })
+ * ```
+ */
+export declare function useBridgeTracing(): {
+    onExecute({ args }: {
+        args: {
+            contextValue: any;
+        };
+    }): {
+        onExecuteDone({ result, setResult, }: {
+            result: any;
+            setResult: (r: any) => void;
+        }): void;
+    };
+};
 //# sourceMappingURL=bridge-transform.d.ts.map

package/build/bridge-transform.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bridge-transform.d.ts","sourceRoot":"","sources":["../src/bridge-transform.ts"],"names":[],"mappings":"AACA,OAAO,EAGL,KAAK,aAAa,EAEnB,MAAM,SAAS,CAAC;AAGjB,OAAO,KAAK,EAAE,WAAW,EAAc,OAAO,EAAE,MAAM,YAAY,CAAC;AAGnE,MAAM,MAAM,aAAa,GAAG;IAC1B;;;kDAG8C;IAC9C,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB;qEACiE;IACjE,aAAa,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,KAAK,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CACvD,CAAC;AAEF,gFAAgF;AAChF,MAAM,MAAM,iBAAiB,GACzB,WAAW,EAAE,GACb,CAAC,CAAC,OAAO,EAAE,GAAG,KAAK,WAAW,EAAE,CAAC,CAAC;AAEtC,wBAAgB,eAAe,CAC7B,MAAM,EAAE,aAAa,EACrB,YAAY,EAAE,iBAAiB,EAC/B,OAAO,CAAC,EAAE,aAAa,GACtB,aAAa,CA+Ef"}
+{"version":3,"file":"bridge-transform.d.ts","sourceRoot":"","sources":["../src/bridge-transform.ts"],"names":[],"mappings":"AACA,OAAO,EAGL,KAAK,aAAa,EAEnB,MAAM,SAAS,CAAC;AACjB,OAAO,EAAiC,KAAK,SAAS,EAAE,KAAK,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAEpG,OAAO,KAAK,EAAE,WAAW,EAAc,OAAO,EAAE,MAAM,YAAY,CAAC;AAGnE,MAAM,MAAM,aAAa,GAAG;IAC1B;;;kDAG8C;IAC9C,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB;qEACiE;IACjE,aAAa,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,KAAK,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IACtD;;wEAEoE;IACpE,KAAK,CAAC,EAAE,OAAO,GAAG,UAAU,CAAC;CAC9B,CAAC;AAEF,gFAAgF;AAChF,MAAM,MAAM,iBAAiB,GACzB,WAAW,EAAE,GACb,CAAC,CAAC,OAAO,EAAE,GAAG,KAAK,WAAW,EAAE,CAAC,CAAC;AAEtC,wBAAgB,eAAe,CAC7B,MAAM,EAAE,aAAa,EACrB,YAAY,EAAE,iBAAiB,EAC/B,OAAO,CAAC,EAAE,aAAa,GACtB,aAAa,CAuFf;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,GAAG,GAAG,SAAS,EAAE,CAEzD;AAED;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB;wBAER;QAAE,IAAI,EAAE;YAAE,YAAY,EAAE,GAAG,CAAA;SAAE,CAAA;KAAE;8CAK5C;YACD,MAAM,EAAE,GAAG,CAAC;YACZ,SAAS,EAAE,CAAC,CAAC,EAAE,GAAG,KAAK,IAAI,CAAC;SAC7B;;EAeR"}

package/build/bridge-transform.js

@@ -1,11 +1,13 @@
 import { MapperKind, mapSchema } from "@graphql-tools/utils";
 import { GraphQLList, GraphQLNonNull, defaultFieldResolver, } from "graphql";
-import { ExecutionTree } from "./ExecutionTree.js";
+import { ExecutionTree, TraceCollector } from "./ExecutionTree.js";
 import { builtinTools } from "./tools/index.js";
 import { SELF_MODULE } from "./types.js";
 export function bridgeTransform(schema, instructions, options) {
     const userTools = options?.tools;
     const contextMapper = options?.contextMapper;
+    const tracing = options?.trace ?? false;
+    const traceLevel = tracing === true ? "full" : tracing === false ? false : tracing;
     return mapSchema(schema, {
         [MapperKind.OBJECT_FIELD]: (fieldConfig, fieldName, typeName) => {
             let array = false;
@@ -36,6 +38,11 @@ export function bridgeTransform(schema, instructions, options) {
                             ...(userTools ?? {}),
                         };
                         source = new ExecutionTree(trunk, activeInstructions, allTools, bridgeContext);
+                        if (traceLevel) {
+                            source.tracer = new TraceCollector(traceLevel);
+                            // Stash tracer on GQL context so the tracing plugin can read it
+                            context.__bridgeTracer = source.tracer;
+                        }
                     }
                     if (source instanceof ExecutionTree &&
                         args &&
@@ -60,3 +67,41 @@ export function bridgeTransform(schema, instructions, options) {
         },
     });
 }
+/**
+ * Read traces that were collected during the current request.
+ * Pass the GraphQL context object; returns an empty array when tracing is
+ * disabled or no traces were recorded.
+ */
+export function getBridgeTraces(context) {
+    return context?.__bridgeTracer?.traces ?? [];
+}
+/**
+ * Envelop-compatible plugin for GraphQL Yoga (or any Envelop-based server).
+ * When bridge tracing is enabled, this plugin copies the recorded traces into
+ * the GraphQL response `extensions.traces` field.
+ *
+ * Usage:
+ * ```ts
+ * createYoga({ schema, plugins: [useBridgeTracing()] })
+ * ```
+ */
+export function useBridgeTracing() {
+    return {
+        onExecute({ args }) {
+            return {
+                onExecuteDone({ result, setResult, }) {
+                    const traces = getBridgeTraces(args.contextValue);
+                    if (traces.length > 0 && result && "data" in result) {
+                        setResult({
+                            ...result,
+                            extensions: {
+                                ...(result.extensions ?? {}),
+                                traces,
+                            },
+                        });
+                    }
+                },
+            };
+        },
+    };
+}

package/build/index.d.ts

@@ -1,6 +1,7 @@
 export { parseBridge } from "./bridge-format.js";
-export { bridgeTransform } from "./bridge-transform.js";
+export { bridgeTransform, getBridgeTraces, useBridgeTracing } from "./bridge-transform.js";
 export type { BridgeOptions, InstructionSource } from "./bridge-transform.js";
 export { builtinTools, std, createHttpCall } from "./tools/index.js";
+export type { ToolTrace, TraceLevel } from "./ExecutionTree.js";
 export type { CacheStore, ConstDef, Instruction, ToolCallFn, ToolDef, ToolMap } from "./types.js";
 //# sourceMappingURL=index.d.ts.map

package/build/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,YAAY,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAC9E,OAAO,EAAE,YAAY,EAAE,GAAG,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACrE,YAAY,EAAE,UAAU,EAAE,QAAQ,EAAE,WAAW,EAAE,UAAU,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAC3F,YAAY,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAC9E,OAAO,EAAE,YAAY,EAAE,GAAG,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACrE,YAAY,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAChE,YAAY,EAAE,UAAU,EAAE,QAAQ,EAAE,WAAW,EAAE,UAAU,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC"}

package/build/index.js

@@ -1,3 +1,3 @@
 export { parseBridge } from "./bridge-format.js";
-export { bridgeTransform } from "./bridge-transform.js";
+export { bridgeTransform, getBridgeTraces, useBridgeTracing } from "./bridge-transform.js";
 export { builtinTools, std, createHttpCall } from "./tools/index.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stackables/bridge",
-  "version": "1.5.0",
+  "version": "1.6.1",
   "description": "Declarative dataflow for GraphQL",
   "main": "./build/index.js",
   "type": "module",