@stackables/bridge-core 1.0.1 → 1.0.3

package/build/{bridge-core/src/ExecutionTree.d.ts → ExecutionTree.d.ts}

@@ -1,4 +1,4 @@
-import type { Bridge, BridgeDocument, ToolMap } from "./types.ts";
+import type { Bridge, BridgeDocument, ToolMap, Wire } from "./types.ts";
 /** Fatal panic error — bypasses all error boundaries (`?.` and `catch`). */
 export declare class BridgePanicError extends Error {
     constructor(message: string);
@@ -32,6 +32,13 @@ type Trunk = {
     field: string;
     instance?: number;
 };
+/**
+ * A value that may already be resolved (synchronous) or still pending (asynchronous).
+ * Using this instead of always returning `Promise<T>` lets callers skip
+ * microtask scheduling when the value is immediately available.
+ * See docs/performance.md (#10).
+ */
+type MaybePromise<T> = T | Promise<T>;
 /** Trace verbosity level.
  *  - `"off"` (default) — no collection, zero overhead
  *  - `"basic"` — tool, fn, timing, errors; no input/output
@@ -101,6 +108,8 @@ export declare class ExecutionTree {
     private toolFns?;
     /** Shadow-tree nesting depth (0 for root). */
     private depth;
+    /** Pre-computed `trunkKey({ ...this.trunk, element: true })`.  See docs/performance.md (#4). */
+    private elementTrunkKey;
     constructor(trunk: Trunk, document: BridgeDocument, toolFns?: ToolMap, context?: Record<string, any> | undefined, parent?: ExecutionTree | undefined);
     /** Derive tool name from a trunk */
     private getToolName;
@@ -115,7 +124,20 @@ export declare class ExecutionTree {
     private resolveToolSource;
     /** Call a tool dependency (cached per request) */
     private resolveToolDep;
-    schedule(target: Trunk, pullChain?: Set<string>): any;
+    schedule(target: Trunk, pullChain?: Set<string>): MaybePromise<any>;
+    /**
+     * Assemble input from resolved wire values and either invoke a direct tool
+     * function or return the data for pass-through targets (local/define/logic).
+     * Returns synchronously when the tool function (if any) returns sync.
+     * See docs/performance.md (#12).
+     */
+    private scheduleFinish;
+    /**
+     * Full async schedule path for targets backed by a ToolDef.
+     * Resolves tool wires, bridge wires, and invokes the tool function
+     * with error recovery support.
+     */
+    private scheduleToolDef;
     /**
      * Invoke a tool function, recording both an OpenTelemetry span and (when
      * tracing is enabled) a ToolTrace entry.  All three tool-call sites in the
@@ -125,6 +147,16 @@ export declare class ExecutionTree {
     shadow(): ExecutionTree;
     /** Returns collected traces (empty array when tracing is disabled). */
     getTraces(): ToolTrace[];
+    /**
+     * Traverse `ref.path` on an already-resolved value, respecting null guards.
+     * Extracted from `pullSingle` so the sync and async paths can share logic.
+     */
+    private applyPath;
+    /**
+     * Pull a single value.  Returns synchronously when already in state;
+     * returns a Promise only when the value is a pending tool call.
+     * See docs/performance.md (#10).
+     */
     private pullSingle;
     push(args: Record<string, any>): void;
     /** Store the aggregated promise for critical forced handles so
@@ -163,7 +195,16 @@ export declare class ExecutionTree {
      * After layers 1–2b, the overdefinition boundary (`!= null`) decides whether
      * to return or continue to the next wire.
      */
+    /**
+     * Resolve wires, returning synchronously when the hot path allows it.
+     *
+     * Fast path: single `from` wire with no fallback/catch modifiers, which is
+     * the common case for element field wires like `.id <- it.id`.  Delegates to
+     * `resolveWiresAsync` for anything more complex.
+     * See docs/performance.md (#10).
+     */
     private resolveWires;
+    private resolveWiresAsync;
     /**
      * Resolve an output field by path for use outside of a GraphQL resolver.
      *
@@ -179,6 +220,22 @@ export declare class ExecutionTree {
      *               in a shadow tree (mirrors `response()` array handling).
      */
     pullOutputField(path: string[], array?: boolean): Promise<unknown>;
+    /**
+     * Resolve pre-grouped wires on this shadow tree without re-filtering.
+     * Called by the parent's `materializeShadows` to skip per-element wire
+     * filtering.  Returns synchronously when the wire resolves sync (hot path).
+     * See docs/performance.md (#8, #10).
+     */
+    resolvePreGrouped(wires: Wire[]): MaybePromise<unknown>;
+    /**
+     * Materialise all output wires into a plain JS object.
+     *
+     * Used by the GraphQL adapter when a bridge field returns a scalar type
+     * (e.g. `JSON`, `JSONObject`). In that case GraphQL won't call sub-field
+     * resolvers, so we need to eagerly resolve every output wire and assemble
+     * the result ourselves — the same logic `run()` uses for object output.
+     */
+    collectOutput(): Promise<unknown>;
     /**
      * Execute the bridge end-to-end without GraphQL.
      *

package/build/ExecutionTree.d.ts.map

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