@stackables/bridge-core 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Stackables
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/build/ExecutionTree.d.ts

@@ -0,0 +1,212 @@
+import type { Bridge, Instruction, NodeRef, ToolMap, Wire } from "./types.ts";
+/** Fatal panic error — bypasses all error boundaries (`?.` and `catch`). */
+export declare class BridgePanicError extends Error {
+    constructor(message: string);
+}
+/** Abort error — raised when an external AbortSignal cancels execution. */
+export declare class BridgeAbortError extends Error {
+    constructor(message?: string);
+}
+/**
+ * Structured logger interface for Bridge engine events.
+ * Accepts any compatible logger: pino, winston, bunyan, `console`, etc.
+ * All methods default to silent no-ops when no logger is provided.
+ */
+export interface Logger {
+    debug?: (...args: any[]) => void;
+    info?: (...args: any[]) => void;
+    warn?: (...args: any[]) => void;
+    error?: (...args: any[]) => void;
+}
+/** Matches graphql's internal Path type (not part of the public exports map) */
+interface Path {
+    readonly prev: Path | undefined;
+    readonly key: string | number;
+    readonly typename: string | undefined;
+}
+type Trunk = {
+    module: string;
+    type: string;
+    field: string;
+    instance?: number;
+};
+/** Trace verbosity level.
+ *  - `"off"` (default) — no collection, zero overhead
+ *  - `"basic"` — tool, fn, timing, errors; no input/output
+ *  - `"full"` — everything including input and output */
+export type TraceLevel = "basic" | "full" | "off";
+/** A single recorded tool invocation. */
+export type ToolTrace = {
+    /** Tool name as resolved (e.g. "hereGeo", "std.str.toUpperCase") */
+    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: "basic" | "full";
+    private readonly epoch;
+    constructor(level?: "basic" | "full");
+    /** 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;
+    private context?;
+    private parent?;
+    state: Record<string, any>;
+    bridge: Bridge | undefined;
+    private toolDepCache;
+    private toolDefCache;
+    private pipeHandleMap;
+    /** Promise that resolves when all critical `force` handles have settled. */
+    private forcedExecution?;
+    /** Shared trace collector — present only when tracing is enabled. */
+    tracer?: TraceCollector;
+    /** Structured logger passed from BridgeOptions. Defaults to no-ops. */
+    logger?: Logger;
+    /** External abort signal — cancels execution when triggered. */
+    signal?: AbortSignal;
+    private toolFns?;
+    constructor(trunk: Trunk, instructions: Instruction[], toolFns?: ToolMap, context?: Record<string, any> | undefined, parent?: ExecutionTree | undefined);
+    /** Derive tool name from a trunk */
+    private getToolName;
+    /** Deep-lookup a tool function by dotted name (e.g. "std.str.toUpperCase").
+     *  Falls back to a flat key lookup for backward compat (e.g. "hereapi.geocode" as literal key). */
+    private lookupToolFn;
+    /** Resolve a ToolDef by name, merging the extends chain (cached) */
+    private resolveToolDefByName;
+    /** Resolve a tool definition's wires into a nested input object */
+    private resolveToolWires;
+    /** Resolve a source reference from a tool wire against its dependencies */
+    private resolveToolSource;
+    /** Call a tool dependency (cached per request) */
+    private resolveToolDep;
+    schedule(target: Trunk): any;
+    /**
+     * Invoke a tool function, recording both an OpenTelemetry span and (when
+     * tracing is enabled) a ToolTrace entry.  All three tool-call sites in the
+     * engine delegate here so instrumentation lives in exactly one place.
+     */
+    private callTool;
+    shadow(): ExecutionTree;
+    /** Returns collected traces (empty array when tracing is disabled). */
+    getTraces(): ToolTrace[];
+    private pullSingle;
+    pull(refs: NodeRef[]): Promise<any>;
+    /**
+     * Safe execution pull: wraps individual safe-flagged pulls in try/catch.
+     * Wires with `safe: true` swallow errors and return undefined.
+     * Non-safe wires propagate errors normally.
+     */
+    pullSafe(pulls: Extract<Wire, {
+        from: NodeRef;
+    }>[]): Promise<any>;
+    push(args: Record<string, any>): void;
+    /** Store the aggregated promise for critical forced handles so
+     *  `response()` can await it exactly once per bridge execution. */
+    setForcedExecution(p: Promise<void>): void;
+    /** Return the critical forced-execution promise (if any). */
+    getForcedExecution(): Promise<void> | undefined;
+    /**
+     * Eagerly schedule tools targeted by `force <handle>` statements.
+     *
+     * Returns an array of promises for **critical** forced handles (those
+     * without `?? null`).  Fire-and-forget handles (`catchError: true`) are
+     * scheduled but their errors are silently suppressed.
+     *
+     * Callers must `await Promise.all(...)` the returned promises so that a
+     * critical force failure propagates as a standard error.
+     */
+    executeForced(): Promise<any>[];
+    /**
+     * Resolve a set of matched wires.
+     *
+     * Architecture: two distinct resolution axes —
+     *
+     *  **Falsy Gate** (`||`, within a wire): `falsyFallbackRefs` + `falsyFallback`
+     *    → truthy check — falsy values (0, "", false) trigger fallback chain.
+     *
+     *  **Overdefinition** (across wires): multiple wires target the same path
+     *    → nullish check — only null/undefined falls through to the next wire.
+     *
+     * Per-wire layers:
+     *   Layer 1  — Execution (pullSingle + safe modifier)
+     *   Layer 2a — Falsy Gate   (falsyFallbackRefs → falsyFallback / falsyControl)
+     *   Layer 2b — Nullish Gate  (nullishFallbackRef / nullishFallback / nullishControl)
+     *   Layer 3  — Catch         (catchFallbackRef / catchFallback / catchControl)
+     *
+     * After layers 1–2b, the overdefinition boundary (`!= null`) decides whether
+     * to return or continue to the next wire.
+     */
+    private resolveWires;
+    /**
+     * Resolve an output field by path for use outside of a GraphQL resolver.
+     *
+     * This is the non-GraphQL equivalent of what `response()` does per field:
+     * it finds all wires targeting `this.trunk` at `path` and resolves them.
+     *
+     * Used by `executeBridge()` so standalone bridge execution does not need to
+     * fabricate GraphQL Path objects to pull output data.
+     *
+     * @param path - Output field path, e.g. `["lat"]`. Pass `[]` for whole-output
+     *               array bridges (`o <- items[] as x { ... }`).
+     * @param array - When `true` and the result is an array, wraps each element
+     *               in a shadow tree (mirrors `response()` array handling).
+     */
+    pullOutputField(path: string[], array?: boolean): Promise<unknown>;
+    /**
+     * Execute the bridge end-to-end without GraphQL.
+     *
+     * Injects `input` as the trunk arguments, runs forced wires, then pulls
+     * and materialises every output field into a plain JS object (or array of
+     * objects for array-mapped bridges).
+     *
+     * This is the single entry-point used by `executeBridge()`.
+     */
+    run(input: Record<string, unknown>): Promise<unknown>;
+    /**
+     * Recursively convert shadow trees into plain JS objects.
+     *
+     * Wire categories at each level (prefix = P):
+     *   Leaf  — `to.path = [...P, name]`, no deeper paths → scalar
+     *   Array — direct wire AND deeper paths → pull as array, recurse
+     *   Nested object — only deeper paths, no direct wire → pull each
+     *             full path and assemble via setNested
+     */
+    private materializeShadows;
+    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

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