@stackables/bridge-compiler 0.0.1 → 1.0.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +49 -0
- package/build/bridge-compiler/src/bridge-format.d.ts +8 -0
- package/build/bridge-compiler/src/bridge-format.d.ts.map +1 -0
- package/build/{bridge-format.js → bridge-compiler/src/bridge-format.js} +9 -5
- package/build/{bridge-lint.d.ts.map → bridge-compiler/src/bridge-lint.d.ts.map} +1 -1
- package/build/{index.d.ts → bridge-compiler/src/index.d.ts} +3 -3
- package/build/bridge-compiler/src/index.d.ts.map +1 -0
- package/build/{index.js → bridge-compiler/src/index.js} +3 -3
- package/build/bridge-compiler/src/language-service.d.ts.map +1 -0
- package/build/{language-service.js → bridge-compiler/src/language-service.js} +47 -6
- package/build/{parser → bridge-compiler/src/parser}/index.d.ts +1 -1
- package/build/bridge-compiler/src/parser/index.d.ts.map +1 -0
- package/build/{parser → bridge-compiler/src/parser}/index.js +1 -1
- package/build/{parser → bridge-compiler/src/parser}/lexer.d.ts +1 -0
- package/build/bridge-compiler/src/parser/lexer.d.ts.map +1 -0
- package/build/{parser → bridge-compiler/src/parser}/lexer.js +155 -31
- package/build/{parser → bridge-compiler/src/parser}/parser.d.ts +12 -3
- package/build/bridge-compiler/src/parser/parser.d.ts.map +1 -0
- package/build/{parser → bridge-compiler/src/parser}/parser.js +63 -13
- package/build/bridge-core/src/ExecutionTree.d.ts +213 -0
- package/build/bridge-core/src/ExecutionTree.d.ts.map +1 -0
- package/build/bridge-core/src/ExecutionTree.js +1323 -0
- package/build/bridge-core/src/execute-bridge.d.ts +69 -0
- package/build/bridge-core/src/execute-bridge.d.ts.map +1 -0
- package/build/bridge-core/src/execute-bridge.js +52 -0
- package/build/bridge-core/src/index.d.ts +18 -0
- package/build/bridge-core/src/index.d.ts.map +1 -0
- package/build/bridge-core/src/index.js +20 -0
- package/build/bridge-core/src/merge-documents.d.ts +25 -0
- package/build/bridge-core/src/merge-documents.d.ts.map +1 -0
- package/build/bridge-core/src/merge-documents.js +91 -0
- package/build/bridge-core/src/tools/index.d.ts +2 -0
- package/build/bridge-core/src/tools/index.d.ts.map +1 -0
- package/build/bridge-core/src/tools/index.js +1 -0
- package/build/bridge-core/src/tools/internal.d.ts +71 -0
- package/build/bridge-core/src/tools/internal.d.ts.map +1 -0
- package/build/bridge-core/src/tools/internal.js +59 -0
- package/build/bridge-core/src/types.d.ts +349 -0
- package/build/bridge-core/src/types.d.ts.map +1 -0
- package/build/bridge-core/src/types.js +3 -0
- package/build/bridge-core/src/utils.d.ts +9 -0
- package/build/bridge-core/src/utils.d.ts.map +1 -0
- package/build/bridge-core/src/utils.js +23 -0
- package/build/bridge-core/src/version-check.d.ts +64 -0
- package/build/bridge-core/src/version-check.d.ts.map +1 -0
- package/build/bridge-core/src/version-check.js +205 -0
- package/build/bridge-stdlib/src/index.d.ts +34 -0
- package/build/bridge-stdlib/src/index.d.ts.map +1 -0
- package/build/bridge-stdlib/src/index.js +40 -0
- package/build/bridge-stdlib/src/tools/arrays.d.ts +28 -0
- package/build/bridge-stdlib/src/tools/arrays.d.ts.map +1 -0
- package/build/bridge-stdlib/src/tools/arrays.js +50 -0
- package/build/bridge-stdlib/src/tools/audit.d.ts +36 -0
- package/build/bridge-stdlib/src/tools/audit.d.ts.map +1 -0
- package/build/bridge-stdlib/src/tools/audit.js +39 -0
- package/build/bridge-stdlib/src/tools/http-call.d.ts +35 -0
- package/build/bridge-stdlib/src/tools/http-call.d.ts.map +1 -0
- package/build/bridge-stdlib/src/tools/http-call.js +118 -0
- package/build/bridge-stdlib/src/tools/strings.d.ts +13 -0
- package/build/bridge-stdlib/src/tools/strings.d.ts.map +1 -0
- package/build/bridge-stdlib/src/tools/strings.js +12 -0
- package/build/bridge-types/src/index.d.ts +63 -0
- package/build/bridge-types/src/index.d.ts.map +1 -0
- package/build/bridge-types/src/index.js +8 -0
- package/package.json +3 -3
- package/build/bridge-format.d.ts +0 -8
- package/build/bridge-format.d.ts.map +0 -1
- package/build/index.d.ts.map +0 -1
- package/build/language-service.d.ts.map +0 -1
- package/build/parser/index.d.ts.map +0 -1
- package/build/parser/lexer.d.ts.map +0 -1
- package/build/parser/parser.d.ts.map +0 -1
- /package/build/{bridge-lint.d.ts → bridge-compiler/src/bridge-lint.d.ts} +0 -0
- /package/build/{bridge-lint.js → bridge-compiler/src/bridge-lint.js} +0 -0
- /package/build/{language-service.d.ts → bridge-compiler/src/language-service.d.ts} +0 -0
|
@@ -5,7 +5,7 @@
|
|
|
5
5
|
* Produces the *exact same* AST types (`Instruction[]`).
|
|
6
6
|
*/
|
|
7
7
|
import { CstParser } from "chevrotain";
|
|
8
|
-
import { allTokens, Identifier, VersionKw, ToolKw, BridgeKw, DefineKw, ConstKw, WithKw, AsKw, FromKw, InputKw, OutputKw, ContextKw, OnKw, ErrorKw, Arrow, ForceKw, AliasKw, AndKw, OrKw, NotKw, ThrowKw, PanicKw, ContinueKw, BreakKw, NullCoalesce, ErrorCoalesce, SafeNav, CatchKw, LParen, RParen, LCurly, RCurly, LSquare, RSquare, Equals, Dot, Colon, Comma, StringLiteral, NumberLiteral, PathToken, TrueLiteral, FalseLiteral, NullLiteral, Star, Slash, Plus, Minus, GreaterEqual, LessEqual, DoubleEquals, NotEquals, GreaterThan, LessThan, QuestionMark, BridgeLexer, } from "./lexer.js";
|
|
8
|
+
import { allTokens, Identifier, VersionKw, ToolKw, BridgeKw, DefineKw, ConstKw, WithKw, AsKw, FromKw, InputKw, OutputKw, ContextKw, OnKw, ErrorKw, Arrow, ForceKw, AliasKw, AndKw, OrKw, NotKw, ThrowKw, PanicKw, ContinueKw, BreakKw, NullCoalesce, ErrorCoalesce, SafeNav, CatchKw, LParen, RParen, LCurly, RCurly, LSquare, RSquare, Equals, Dot, Colon, Comma, StringLiteral, NumberLiteral, PathToken, TrueLiteral, FalseLiteral, NullLiteral, Star, Slash, Plus, Minus, GreaterEqual, LessEqual, DoubleEquals, NotEquals, GreaterThan, LessThan, QuestionMark, VersionTag, BridgeLexer, } from "./lexer.js";
|
|
9
9
|
import { SELF_MODULE } from "@stackables/bridge-core";
|
|
10
10
|
// ── Reserved-word guards (mirroring the regex parser) ──────────────────────
|
|
11
11
|
const RESERVED_KEYWORDS = new Set([
|
|
@@ -160,6 +160,9 @@ class BridgeParser extends CstParser {
|
|
|
160
160
|
},
|
|
161
161
|
ALT: () => {
|
|
162
162
|
this.SUBRULE(this.dottedName, { LABEL: "toolName" });
|
|
163
|
+
this.OPTION3(() => {
|
|
164
|
+
this.CONSUME(VersionTag, { LABEL: "toolVersion" });
|
|
165
|
+
});
|
|
163
166
|
this.CONSUME3(AsKw);
|
|
164
167
|
this.SUBRULE3(this.nameToken, { LABEL: "toolAlias" });
|
|
165
168
|
},
|
|
@@ -350,6 +353,9 @@ class BridgeParser extends CstParser {
|
|
|
350
353
|
},
|
|
351
354
|
ALT: () => {
|
|
352
355
|
this.SUBRULE(this.dottedName, { LABEL: "refName" });
|
|
356
|
+
this.OPTION6(() => {
|
|
357
|
+
this.CONSUME(VersionTag, { LABEL: "refVersion" });
|
|
358
|
+
});
|
|
353
359
|
this.OPTION5(() => {
|
|
354
360
|
this.CONSUME5(AsKw);
|
|
355
361
|
this.SUBRULE5(this.nameToken, { LABEL: "refAlias" });
|
|
@@ -1051,6 +1057,19 @@ const parserInstance = new BridgeParser();
|
|
|
1051
1057
|
// Lenient instance: error recovery enabled (used by parseBridgeDiagnostics)
|
|
1052
1058
|
const diagParserInstance = new BridgeParser({ recovery: true });
|
|
1053
1059
|
const BRIDGE_VERSION = "1.5";
|
|
1060
|
+
/** Minimum major version the parser can handle (inclusive). */
|
|
1061
|
+
const BRIDGE_MIN_MAJOR = 1;
|
|
1062
|
+
/** Maximum major version the parser can handle (inclusive). */
|
|
1063
|
+
const BRIDGE_MAX_MAJOR = 1;
|
|
1064
|
+
/** Exported parser version metadata for runtime use. */
|
|
1065
|
+
export const PARSER_VERSION = {
|
|
1066
|
+
/** Current bridge language version */
|
|
1067
|
+
current: BRIDGE_VERSION,
|
|
1068
|
+
/** Minimum supported major version (inclusive) */
|
|
1069
|
+
minMajor: BRIDGE_MIN_MAJOR,
|
|
1070
|
+
/** Maximum supported major version (inclusive) */
|
|
1071
|
+
maxMajor: BRIDGE_MAX_MAJOR,
|
|
1072
|
+
};
|
|
1054
1073
|
// ═══════════════════════════════════════════════════════════════════════════
|
|
1055
1074
|
// Public API
|
|
1056
1075
|
// ═══════════════════════════════════════════════════════════════════════════
|
|
@@ -1100,11 +1119,11 @@ export function parseBridgeDiagnostics(text) {
|
|
|
1100
1119
|
});
|
|
1101
1120
|
}
|
|
1102
1121
|
// 3. Visit → AST (semantic errors thrown as "Line N: ..." messages)
|
|
1103
|
-
let
|
|
1122
|
+
let document = { instructions: [] };
|
|
1104
1123
|
let startLines = new Map();
|
|
1105
1124
|
try {
|
|
1106
1125
|
const result = toBridgeAst(cst, []);
|
|
1107
|
-
|
|
1126
|
+
document = { version: result.version, instructions: result.instructions };
|
|
1108
1127
|
startLines = result.startLines;
|
|
1109
1128
|
}
|
|
1110
1129
|
catch (err) {
|
|
@@ -1120,7 +1139,7 @@ export function parseBridgeDiagnostics(text) {
|
|
|
1120
1139
|
},
|
|
1121
1140
|
});
|
|
1122
1141
|
}
|
|
1123
|
-
return {
|
|
1142
|
+
return { document, diagnostics, startLines };
|
|
1124
1143
|
}
|
|
1125
1144
|
function internalParse(text, previousInstructions) {
|
|
1126
1145
|
// 1. Lex
|
|
@@ -1137,7 +1156,8 @@ function internalParse(text, previousInstructions) {
|
|
|
1137
1156
|
throw new Error(e.message);
|
|
1138
1157
|
}
|
|
1139
1158
|
// 3. Visit → AST
|
|
1140
|
-
|
|
1159
|
+
const result = toBridgeAst(cst, previousInstructions);
|
|
1160
|
+
return { version: result.version, instructions: result.instructions };
|
|
1141
1161
|
}
|
|
1142
1162
|
// ═══════════════════════════════════════════════════════════════════════════
|
|
1143
1163
|
// CST → AST transformation (imperative visitor)
|
|
@@ -2204,9 +2224,22 @@ function toBridgeAst(cst, previousInstructions) {
|
|
|
2204
2224
|
}
|
|
2205
2225
|
const versionTok = tok(versionDecl, "ver");
|
|
2206
2226
|
const versionNum = versionTok?.image;
|
|
2207
|
-
if (versionNum
|
|
2208
|
-
throw new Error(`
|
|
2227
|
+
if (!versionNum) {
|
|
2228
|
+
throw new Error(`Missing version number. Bridge files must begin with: version ${BRIDGE_VERSION}`);
|
|
2229
|
+
}
|
|
2230
|
+
// Accept any version whose major falls within the supported range.
|
|
2231
|
+
// When the parser supports multiple majors (e.g. 1.x through 2.x),
|
|
2232
|
+
// bridge files from any of them are valid syntax.
|
|
2233
|
+
const vParts = versionNum.split(".");
|
|
2234
|
+
const vMajor = parseInt(vParts[0], 10);
|
|
2235
|
+
const supportedRange = BRIDGE_MIN_MAJOR === BRIDGE_MAX_MAJOR
|
|
2236
|
+
? `${BRIDGE_MIN_MAJOR}.x`
|
|
2237
|
+
: `${BRIDGE_MIN_MAJOR}.x – ${BRIDGE_MAX_MAJOR}.x`;
|
|
2238
|
+
if (isNaN(vMajor) || vMajor < BRIDGE_MIN_MAJOR || vMajor > BRIDGE_MAX_MAJOR) {
|
|
2239
|
+
throw new Error(`Unsupported bridge major version "${versionNum}". This parser supports version ${supportedRange}`);
|
|
2209
2240
|
}
|
|
2241
|
+
// Store the declared version (lives on BridgeDocument, not in instructions).
|
|
2242
|
+
const version = versionNum;
|
|
2210
2243
|
const tagged = [];
|
|
2211
2244
|
for (const n of subs(cst, "constDecl"))
|
|
2212
2245
|
tagged.push({
|
|
@@ -2270,7 +2303,7 @@ function toBridgeAst(cst, previousInstructions) {
|
|
|
2270
2303
|
}
|
|
2271
2304
|
}
|
|
2272
2305
|
}
|
|
2273
|
-
return { instructions, startLines };
|
|
2306
|
+
return { version, instructions, startLines };
|
|
2274
2307
|
}
|
|
2275
2308
|
// ── Const ───────────────────────────────────────────────────────────────
|
|
2276
2309
|
function buildConstDef(node) {
|
|
@@ -2319,7 +2352,13 @@ function buildToolDef(node, previousInstructions) {
|
|
|
2319
2352
|
else if (wc.toolName) {
|
|
2320
2353
|
const tName = extractDottedName(wc.toolName[0]);
|
|
2321
2354
|
const tAlias = extractNameToken(wc.toolAlias[0]);
|
|
2322
|
-
|
|
2355
|
+
const tVersion = wc.toolVersion?.[0]?.image.slice(1);
|
|
2356
|
+
deps.push({
|
|
2357
|
+
kind: "tool",
|
|
2358
|
+
handle: tAlias,
|
|
2359
|
+
tool: tName,
|
|
2360
|
+
...(tVersion ? { version: tVersion } : {}),
|
|
2361
|
+
});
|
|
2323
2362
|
}
|
|
2324
2363
|
continue;
|
|
2325
2364
|
}
|
|
@@ -2400,10 +2439,10 @@ function buildBridge(node, previousInstructions) {
|
|
|
2400
2439
|
`}`,
|
|
2401
2440
|
].join("\n");
|
|
2402
2441
|
const result = internalParse(expandedText, previousInstructions);
|
|
2403
|
-
const bridgeInst = result.find((i) => i.kind === "bridge");
|
|
2442
|
+
const bridgeInst = result.instructions.find((i) => i.kind === "bridge");
|
|
2404
2443
|
if (bridgeInst)
|
|
2405
2444
|
bridgeInst.passthrough = passthroughName;
|
|
2406
|
-
return result;
|
|
2445
|
+
return result.instructions;
|
|
2407
2446
|
}
|
|
2408
2447
|
// Full bridge block
|
|
2409
2448
|
const bodyLines = subs(node, "bridgeBodyLine");
|
|
@@ -2530,6 +2569,7 @@ function buildBridgeBody(bodyLines, bridgeType, bridgeField, previousInstruction
|
|
|
2530
2569
|
}
|
|
2531
2570
|
else if (wc.refName) {
|
|
2532
2571
|
const name = extractDottedName(wc.refName[0]);
|
|
2572
|
+
const versionTag = wc.refVersion?.[0]?.image.slice(1);
|
|
2533
2573
|
const lastDot = name.lastIndexOf(".");
|
|
2534
2574
|
const defaultHandle = lastDot !== -1 ? name.substring(lastDot + 1) : name;
|
|
2535
2575
|
const handle = wc.refAlias
|
|
@@ -2554,7 +2594,12 @@ function buildBridgeBody(bodyLines, bridgeType, bridgeField, previousInstruction
|
|
|
2554
2594
|
const key = `${modulePart}:${fieldPart}`;
|
|
2555
2595
|
const instance = (instanceCounters.get(key) ?? 0) + 1;
|
|
2556
2596
|
instanceCounters.set(key, instance);
|
|
2557
|
-
handleBindings.push({
|
|
2597
|
+
handleBindings.push({
|
|
2598
|
+
handle,
|
|
2599
|
+
kind: "tool",
|
|
2600
|
+
name,
|
|
2601
|
+
...(versionTag ? { version: versionTag } : {}),
|
|
2602
|
+
});
|
|
2558
2603
|
handleRes.set(handle, {
|
|
2559
2604
|
module: modulePart,
|
|
2560
2605
|
type: bridgeType,
|
|
@@ -2566,7 +2611,12 @@ function buildBridgeBody(bodyLines, bridgeType, bridgeField, previousInstruction
|
|
|
2566
2611
|
const key = `Tools:${name}`;
|
|
2567
2612
|
const instance = (instanceCounters.get(key) ?? 0) + 1;
|
|
2568
2613
|
instanceCounters.set(key, instance);
|
|
2569
|
-
handleBindings.push({
|
|
2614
|
+
handleBindings.push({
|
|
2615
|
+
handle,
|
|
2616
|
+
kind: "tool",
|
|
2617
|
+
name,
|
|
2618
|
+
...(versionTag ? { version: versionTag } : {}),
|
|
2619
|
+
});
|
|
2570
2620
|
handleRes.set(handle, {
|
|
2571
2621
|
module: SELF_MODULE,
|
|
2572
2622
|
type: "Tools",
|
|
@@ -0,0 +1,213 @@
|
|
|
1
|
+
import type { Bridge, BridgeDocument, ToolMap } from "./types.ts";
|
|
2
|
+
/** Fatal panic error — bypasses all error boundaries (`?.` and `catch`). */
|
|
3
|
+
export declare class BridgePanicError extends Error {
|
|
4
|
+
constructor(message: string);
|
|
5
|
+
}
|
|
6
|
+
/** Abort error — raised when an external AbortSignal cancels execution. */
|
|
7
|
+
export declare class BridgeAbortError extends Error {
|
|
8
|
+
constructor(message?: string);
|
|
9
|
+
}
|
|
10
|
+
/** Maximum shadow-tree nesting depth before a BridgePanicError is thrown. */
|
|
11
|
+
export declare const MAX_EXECUTION_DEPTH = 30;
|
|
12
|
+
/**
|
|
13
|
+
* Structured logger interface for Bridge engine events.
|
|
14
|
+
* Accepts any compatible logger: pino, winston, bunyan, `console`, etc.
|
|
15
|
+
* All methods default to silent no-ops when no logger is provided.
|
|
16
|
+
*/
|
|
17
|
+
export interface Logger {
|
|
18
|
+
debug?: (...args: any[]) => void;
|
|
19
|
+
info?: (...args: any[]) => void;
|
|
20
|
+
warn?: (...args: any[]) => void;
|
|
21
|
+
error?: (...args: any[]) => void;
|
|
22
|
+
}
|
|
23
|
+
/** Matches graphql's internal Path type (not part of the public exports map) */
|
|
24
|
+
interface Path {
|
|
25
|
+
readonly prev: Path | undefined;
|
|
26
|
+
readonly key: string | number;
|
|
27
|
+
readonly typename: string | undefined;
|
|
28
|
+
}
|
|
29
|
+
type Trunk = {
|
|
30
|
+
module: string;
|
|
31
|
+
type: string;
|
|
32
|
+
field: string;
|
|
33
|
+
instance?: number;
|
|
34
|
+
};
|
|
35
|
+
/** Trace verbosity level.
|
|
36
|
+
* - `"off"` (default) — no collection, zero overhead
|
|
37
|
+
* - `"basic"` — tool, fn, timing, errors; no input/output
|
|
38
|
+
* - `"full"` — everything including input and output */
|
|
39
|
+
export type TraceLevel = "basic" | "full" | "off";
|
|
40
|
+
/** A single recorded tool invocation. */
|
|
41
|
+
export type ToolTrace = {
|
|
42
|
+
/** Tool name as resolved (e.g. "hereGeo", "std.str.toUpperCase") */
|
|
43
|
+
tool: string;
|
|
44
|
+
/** The function that was called (e.g. "httpCall", "upperCase") */
|
|
45
|
+
fn: string;
|
|
46
|
+
/** Input object passed to the tool function (only in "full" level) */
|
|
47
|
+
input?: Record<string, any>;
|
|
48
|
+
/** Resolved output (only in "full" level, on success) */
|
|
49
|
+
output?: any;
|
|
50
|
+
/** Error message (present when the tool threw) */
|
|
51
|
+
error?: string;
|
|
52
|
+
/** Wall-clock duration in milliseconds */
|
|
53
|
+
durationMs: number;
|
|
54
|
+
/** Monotonic timestamp (ms) relative to the first trace in the request */
|
|
55
|
+
startedAt: number;
|
|
56
|
+
};
|
|
57
|
+
/** Shared trace collector — one per request, passed through the tree. */
|
|
58
|
+
export declare class TraceCollector {
|
|
59
|
+
readonly traces: ToolTrace[];
|
|
60
|
+
readonly level: "basic" | "full";
|
|
61
|
+
private readonly epoch;
|
|
62
|
+
constructor(level?: "basic" | "full");
|
|
63
|
+
/** Returns ms since the collector was created */
|
|
64
|
+
now(): number;
|
|
65
|
+
record(trace: ToolTrace): void;
|
|
66
|
+
/** Build a trace entry, omitting input/output for basic level. */
|
|
67
|
+
entry(base: {
|
|
68
|
+
tool: string;
|
|
69
|
+
fn: string;
|
|
70
|
+
startedAt: number;
|
|
71
|
+
durationMs: number;
|
|
72
|
+
input?: Record<string, any>;
|
|
73
|
+
output?: any;
|
|
74
|
+
error?: string;
|
|
75
|
+
}): ToolTrace;
|
|
76
|
+
}
|
|
77
|
+
export declare class ExecutionTree {
|
|
78
|
+
trunk: Trunk;
|
|
79
|
+
private document;
|
|
80
|
+
private context?;
|
|
81
|
+
private parent?;
|
|
82
|
+
state: Record<string, any>;
|
|
83
|
+
bridge: Bridge | undefined;
|
|
84
|
+
private toolDepCache;
|
|
85
|
+
private toolDefCache;
|
|
86
|
+
private pipeHandleMap;
|
|
87
|
+
/**
|
|
88
|
+
* Maps trunk keys to `@version` strings from handle bindings.
|
|
89
|
+
* Populated in the constructor so `schedule()` can prefer versioned
|
|
90
|
+
* tool lookups (e.g. `std.str.toLowerCase@999.1`) over the default.
|
|
91
|
+
*/
|
|
92
|
+
private handleVersionMap;
|
|
93
|
+
/** Promise that resolves when all critical `force` handles have settled. */
|
|
94
|
+
private forcedExecution?;
|
|
95
|
+
/** Shared trace collector — present only when tracing is enabled. */
|
|
96
|
+
tracer?: TraceCollector;
|
|
97
|
+
/** Structured logger passed from BridgeOptions. Defaults to no-ops. */
|
|
98
|
+
logger?: Logger;
|
|
99
|
+
/** External abort signal — cancels execution when triggered. */
|
|
100
|
+
signal?: AbortSignal;
|
|
101
|
+
private toolFns?;
|
|
102
|
+
/** Shadow-tree nesting depth (0 for root). */
|
|
103
|
+
private depth;
|
|
104
|
+
constructor(trunk: Trunk, document: BridgeDocument, toolFns?: ToolMap, context?: Record<string, any> | undefined, parent?: ExecutionTree | undefined);
|
|
105
|
+
/** Derive tool name from a trunk */
|
|
106
|
+
private getToolName;
|
|
107
|
+
/** Deep-lookup a tool function by dotted name (e.g. "std.str.toUpperCase").
|
|
108
|
+
* Falls back to a flat key lookup for backward compat (e.g. "hereapi.geocode" as literal key). */
|
|
109
|
+
private lookupToolFn;
|
|
110
|
+
/** Resolve a ToolDef by name, merging the extends chain (cached) */
|
|
111
|
+
private resolveToolDefByName;
|
|
112
|
+
/** Resolve a tool definition's wires into a nested input object */
|
|
113
|
+
private resolveToolWires;
|
|
114
|
+
/** Resolve a source reference from a tool wire against its dependencies */
|
|
115
|
+
private resolveToolSource;
|
|
116
|
+
/** Call a tool dependency (cached per request) */
|
|
117
|
+
private resolveToolDep;
|
|
118
|
+
schedule(target: Trunk, pullChain?: Set<string>): any;
|
|
119
|
+
/**
|
|
120
|
+
* Invoke a tool function, recording both an OpenTelemetry span and (when
|
|
121
|
+
* tracing is enabled) a ToolTrace entry. All three tool-call sites in the
|
|
122
|
+
* engine delegate here so instrumentation lives in exactly one place.
|
|
123
|
+
*/
|
|
124
|
+
private callTool;
|
|
125
|
+
shadow(): ExecutionTree;
|
|
126
|
+
/** Returns collected traces (empty array when tracing is disabled). */
|
|
127
|
+
getTraces(): ToolTrace[];
|
|
128
|
+
private pullSingle;
|
|
129
|
+
push(args: Record<string, any>): void;
|
|
130
|
+
/** Store the aggregated promise for critical forced handles so
|
|
131
|
+
* `response()` can await it exactly once per bridge execution. */
|
|
132
|
+
setForcedExecution(p: Promise<void>): void;
|
|
133
|
+
/** Return the critical forced-execution promise (if any). */
|
|
134
|
+
getForcedExecution(): Promise<void> | undefined;
|
|
135
|
+
/**
|
|
136
|
+
* Eagerly schedule tools targeted by `force <handle>` statements.
|
|
137
|
+
*
|
|
138
|
+
* Returns an array of promises for **critical** forced handles (those
|
|
139
|
+
* without `?? null`). Fire-and-forget handles (`catchError: true`) are
|
|
140
|
+
* scheduled but their errors are silently suppressed.
|
|
141
|
+
*
|
|
142
|
+
* Callers must `await Promise.all(...)` the returned promises so that a
|
|
143
|
+
* critical force failure propagates as a standard error.
|
|
144
|
+
*/
|
|
145
|
+
executeForced(): Promise<any>[];
|
|
146
|
+
/**
|
|
147
|
+
* Resolve a set of matched wires.
|
|
148
|
+
*
|
|
149
|
+
* Architecture: two distinct resolution axes —
|
|
150
|
+
*
|
|
151
|
+
* **Falsy Gate** (`||`, within a wire): `falsyFallbackRefs` + `falsyFallback`
|
|
152
|
+
* → truthy check — falsy values (0, "", false) trigger fallback chain.
|
|
153
|
+
*
|
|
154
|
+
* **Overdefinition** (across wires): multiple wires target the same path
|
|
155
|
+
* → nullish check — only null/undefined falls through to the next wire.
|
|
156
|
+
*
|
|
157
|
+
* Per-wire layers:
|
|
158
|
+
* Layer 1 — Execution (pullSingle + safe modifier)
|
|
159
|
+
* Layer 2a — Falsy Gate (falsyFallbackRefs → falsyFallback / falsyControl)
|
|
160
|
+
* Layer 2b — Nullish Gate (nullishFallbackRef / nullishFallback / nullishControl)
|
|
161
|
+
* Layer 3 — Catch (catchFallbackRef / catchFallback / catchControl)
|
|
162
|
+
*
|
|
163
|
+
* After layers 1–2b, the overdefinition boundary (`!= null`) decides whether
|
|
164
|
+
* to return or continue to the next wire.
|
|
165
|
+
*/
|
|
166
|
+
private resolveWires;
|
|
167
|
+
/**
|
|
168
|
+
* Resolve an output field by path for use outside of a GraphQL resolver.
|
|
169
|
+
*
|
|
170
|
+
* This is the non-GraphQL equivalent of what `response()` does per field:
|
|
171
|
+
* it finds all wires targeting `this.trunk` at `path` and resolves them.
|
|
172
|
+
*
|
|
173
|
+
* Used by `executeBridge()` so standalone bridge execution does not need to
|
|
174
|
+
* fabricate GraphQL Path objects to pull output data.
|
|
175
|
+
*
|
|
176
|
+
* @param path - Output field path, e.g. `["lat"]`. Pass `[]` for whole-output
|
|
177
|
+
* array bridges (`o <- items[] as x { ... }`).
|
|
178
|
+
* @param array - When `true` and the result is an array, wraps each element
|
|
179
|
+
* in a shadow tree (mirrors `response()` array handling).
|
|
180
|
+
*/
|
|
181
|
+
pullOutputField(path: string[], array?: boolean): Promise<unknown>;
|
|
182
|
+
/**
|
|
183
|
+
* Execute the bridge end-to-end without GraphQL.
|
|
184
|
+
*
|
|
185
|
+
* Injects `input` as the trunk arguments, runs forced wires, then pulls
|
|
186
|
+
* and materialises every output field into a plain JS object (or array of
|
|
187
|
+
* objects for array-mapped bridges).
|
|
188
|
+
*
|
|
189
|
+
* This is the single entry-point used by `executeBridge()`.
|
|
190
|
+
*/
|
|
191
|
+
run(input: Record<string, unknown>): Promise<unknown>;
|
|
192
|
+
/**
|
|
193
|
+
* Recursively convert shadow trees into plain JS objects.
|
|
194
|
+
*
|
|
195
|
+
* Wire categories at each level (prefix = P):
|
|
196
|
+
* Leaf — `to.path = [...P, name]`, no deeper paths → scalar
|
|
197
|
+
* Array — direct wire AND deeper paths → pull as array, recurse
|
|
198
|
+
* Nested object — only deeper paths, no direct wire → pull each
|
|
199
|
+
* full path and assemble via setNested
|
|
200
|
+
*/
|
|
201
|
+
private materializeShadows;
|
|
202
|
+
response(ipath: Path, array: boolean): Promise<any>;
|
|
203
|
+
/**
|
|
204
|
+
* Find define output wires for a specific field path.
|
|
205
|
+
*
|
|
206
|
+
* Looks for whole-object define forward wires (`o <- defineHandle`)
|
|
207
|
+
* at path=[] for this trunk, then searches the define's output wires
|
|
208
|
+
* for ones matching the requested field path.
|
|
209
|
+
*/
|
|
210
|
+
private findDefineFieldWires;
|
|
211
|
+
}
|
|
212
|
+
export {};
|
|
213
|
+
//# sourceMappingURL=ExecutionTree.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"ExecutionTree.d.ts","sourceRoot":"","sources":["../../../../bridge-core/src/ExecutionTree.ts"],"names":[],"mappings":"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"}
|