@stackables/bridge 1.1.1 → 1.3.0

package/README.md

@@ -7,10 +7,11 @@ Wire data between APIs, tools, and fields using `.bridge` files—no resolvers,
 npm install @stackables/bridge
 ```
 
-> **Developer Preview**  
+> **Developer Preview**
 > The Bridge v1.x is a public preview and is not recommended for production use.
->  - Stability: Breaking changes to the .bridge language and TypeScript API will occur frequently.
->  - Versioning: We follow strict SemVer starting from v2.0.0.
+>
+> * Stability: Breaking changes to the .bridge language and TypeScript API will occur frequently.
+> * Versioning: We follow strict SemVer starting from v2.0.0.
 >
 > Feedback: We are actively looking for use cases. Please share yours in our GitHub Discussions.
 
@@ -29,10 +30,36 @@ The Bridge is a **Smart Mapping Outgoing Proxy**, not a replacement for your app
 * **Use it to:** Morph external API shapes, enforce single exit points for security, and swap providers (e.g., SendGrid to Postmark) without changing app code.
 * **Don't use it for:** Complex business logic or database transactions. Keep the "intelligence" in your Tools; keep the "connectivity" in your Bridge.
 
+### Wiring, not Programming
+
+The Bridge is not a programming language. It is a Data Topology Language.
+
+Unlike Python or JavaScript, where you write a list of instructions for a computer to execute in order, a .bridge file describes a static circuit. There is no "execution pointer" that moves from the top of the file to the bottom.
+
+No Sequential Logic: Shuffling the lines inside a define or bridge block changes nothing. The engine doesn't "run" your file; it uses your file to understand how your GraphQL fields are physically wired to your tools.
+
+Pull, Don't Push: In a normal language, you "push" data into variables. In The Bridge, the GraphQL query "pulls" data through the wires. If a client doesn't ask for a field, the wire is "dead"—no code runs, and no API is called.
+
+Declarative Connections: When you write o.name <- api.name, you aren't commanding a copy operation; you are soldering a permanent link between two points in your graph.
+
+**Don't think in scripts. Think in schematics.**
+
+### Portability & Performance
+
+While the reference engine is implemented in TypeScript, the Bridge language itself is a simple, high-level specification for data flow. Because it describes intent rather than execution, it is architecturally "runtime-blind." It can be interpreted by any high-performance engines written in Rust, Go, or C++ without changing a single line of your .bridge files.
+
 ---
 
 ## The Language
 
+Every `.bridge` file must begin with a version declaration.
+
+```hcl
+version 1.4
+```
+
+This is the first non-blank, non-comment line. Everything else follows after it.
+
 ### 1. Const Blocks (`const`)
 
 Named JSON values reusable across tools and bridges. Avoids repetition for fallback payloads, defaults, and config fragments.
@@ -45,69 +72,161 @@ const maxRetries = 3
 
 Access const values in bridges or tools via `with const as c`, then reference as `c.<name>.<path>`.
 
-### 2. Extend Blocks (`extend`)
+### 2. Tool Blocks (`tool ... from`)
 
-Defines the "Where" and the "How." Takes a function (or parent tool) and configures i, giving it a new name.
+Defines the "Where" and the "How." Takes a function (or parent tool) and configures it, giving it a new name.
 
 ```hcl
-extend <source> as <name>
+tool <name> from <source> {
   [with context]                  # Injects GraphQL context (auth, secrets, etc.)
   [on error = <json_fallback>]    # Fallback value if tool fails
   [on error <- <source>]          # Pull fallback from context/tool
-  
-  <param> = <value>               # Constant/Default value
-  <param> <- <source>             # Dynamic wire
 
+  .<param> = <value>              # Constant/Default value (dot = "this tool's param")
+  .<param> <- <source>            # Dynamic wire
+}
 ```
 
+Param lines use a `.` prefix — the dot means "this tool's own field". `with` and `on error` lines do not use a dot; they are control flow, not param assignments.
+
 When `<source>` is a function name (e.g. `httpCall`), a new tool is created.
 When `<source>` is an existing tool name, the new tool inherits its configuration.
 
-### 3. Bridge Blocks (`bridge`)
+### 3. Define Blocks (`define`)
+
+Reusable named subgraphs — compose tools and wires into a pipeline, then invoke it from any bridge.
+
+```hcl
+define <name> {
+  with <tool> as <handle>     # Tools used inside the pipeline
+  with input as <handle>      # Inputs provided by the caller
+  with output as <handle>     # Outputs returned to the caller
+
+  <handle>.<param> <- <source>  # Wiring (same syntax as bridge)
+  <handle>.<param> = <value>    # Constants
+}
+```
+
+Use a define in a bridge with `with <define> as <handle>`:
+
+```hcl
+define geocode {
+  with std.httpCall as geo
+  with input as i
+  with output as o
+
+  geo.baseUrl = "https://nominatim.openstreetmap.org"
+  geo.method = GET
+  geo.path = /search
+  geo.q <- i.city
+  o.lat <- geo[0].lat
+  o.lon <- geo[0].lon
+}
+
+bridge Query.location {
+  with geocode as g
+  with input as i
+  with output as o
+
+  g.city <- i.city
+  o.lat <- g.lat
+  o.lon <- g.lon
+}
+```
+
+Each invocation is fully isolated — calling the same define twice creates independent tool instances with no namespace collisions.
+
+### 4. Bridge Blocks (`bridge`)
 
 The resolver logic connecting GraphQL schema fields to your tools.
 
 ```hcl
-bridge <Type.field>
+bridge <Type.field> {
   with <tool> [as <alias>]
-  with input [as <i>]
+  with input as i
+  with output as o
 
   # Field Mapping
-  <field> = <json>                  # Constant value
-  <field> <- <source>               # Standard Pull (lazy)
-  <field> <-! <source>              # Forced Push (eager/side-effect)
+  o.<field> = <json>                    # Constant output value
+  o.<field> <- <source>                 # Standard Pull (lazy)
+  o.<field> <-! <source>               # Forced Push (eager/side-effect)
 
   # Pipe chain (tool transformation)
-  <field> <- handle:source          # Route source through tool handle
+  o.<field> <- handle:source            # Route source through tool handle
 
   # Fallbacks
-  <field> <- <source> || <alt> || <alt> # Null-coalesce: use alt if source is null
-  <field> <- <source> ?? <fallback>     # Error-fallback: use fallback if chain throws
+  o.<field> <- <source> || <alt> || <alt> # Null-coalesce: use alt if source is null
+  o.<field> <- <source> ?? <fallback>     # Error-fallback: use fallback if chain throws
+
+  # Array Mapping (brace block per element)
+  o.<field> <- <source>[] as <iter> {
+    .<sub_field> <- <iter>.<sub_src>    # Element field via iterator
+    .<sub_field> = "constant"           # Element constant
+  }
+}
+```
 
-  # Array Mapping
-  <field>[] <- <source>[]
-    .<sub_field> <- .<sub_src>      # Relative scoping
+Bridge can be fully implemented in the defined pipeline.
 
+```
+define namedOperation {
+  ....
+}
+
+bridge <Type.field> with namedOperation
 ```
 
 ---
 
 ## Key Features
 
+### Reserved Words
+
+**Keywords** — cannot be used as tool names, handle aliases, or const names:
+
+> `bridge` `with` `as` `from` `const` `tool` `version` `define`
+
+**Source identifiers** — reserved for their specific role inside `bridge` and `tool` blocks:
+
+> `input` `output` `context`
+
+A parse error is thrown immediately if any of these appear where a user-defined name is expected.
+
+### Scope Rules
+
+Bridge uses explicit scoping. Any entity referenced inside a `bridge` or `tool` block must first be introduced into scope using a `with` clause.
+
+This includes:
+
+* `tools`
+* `input`
+* `output`
+* `context`
+* `tool aliases`
+
+The `input` and `output` handles represents GraphQL field arguments and output type. They exists **only inside `bridge` blocks**.
+
+Because `tool` blocks are evaluated before any GraphQL execution occurs, they cannot reference `input` or `output`.
+
+> **Rule of thumb:**
+> `tool ... from` defines tools, `bridge` executes the graph.
+> Since `input` and `output` belong to GraphQL execution, they only exist inside bridges.
+
 ### Resiliency
 
 Each layer handles a different failure mode. They compose freely.
 
 #### Layer 1 — Tool `on error` (execution errors)
 
-Declared inside the `extend` block. Catches any exception thrown by the tool's `fn(input)`. All tools that `extend` this tool inherit the fallback.
+Declared inside the `tool` block. Catches any exception thrown by the tool's `fn(input)`. All tools that inherit from this tool inherit the fallback.
 
 ```hcl
-extend httpCall as geo
-  baseUrl = "https://nominatim.openstreetmap.org"
-  method = GET
-  path = /search
+tool geo from httpCall {
+  .baseUrl = "https://nominatim.openstreetmap.org"
+  .method = GET
+  .path = /search
   on error = { "lat": 0, "lon": 0 }   # tool-level default
+}
 ```
 
 #### Layer 2 — Wire `||` (null / absent values)
@@ -115,14 +234,16 @@ extend httpCall as geo
 Fires when a source resolves **successfully but returns `null` or `undefined`**. The fallback can be a JSON literal or another source expression (handle path or pipe chain). Multiple `||` alternatives chain left-to-right like `COALESCE`.
 
 ```hcl
+with output as o
+
 # JSON literal fallback
-lat <- geo.lat || 0.0
+o.lat <- geo.lat || 0.0
 
 # Alternative source fallback
-label <- api.label || backup.label || "unknown"
+o.label <- api.label || backup.label || "unknown"
 
 # Pipe chain as alternative
-textPart <- i.textBody || convert:i.htmlBody || "empty"
+o.textPart <- i.textBody || convert:i.htmlBody || "empty"
 ```
 
 #### Layer 3 — Wire `??` (errors and exceptions)
@@ -130,11 +251,13 @@ textPart <- i.textBody || convert:i.htmlBody || "empty"
 Fires when the **entire resolution chain throws** (network failure, tool down, dependency error). Does not fire on null values — that's `||`'s job. The fallback can be a JSON literal or a source/pipe expression (evaluated lazily, only when the error fires).
 
 ```hcl
+with output as o
+
 # JSON literal error fallback
-lat <- geo.lat ?? 0.0
+o.lat <- geo.lat ?? 0.0
 
 # Error fallback pulls from another source
-label <- api.label ?? errorHandler:i.fallbackMsg
+o.label <- api.label ?? errorHandler:i.fallbackMsg
 ```
 
 #### Full COALESCE — composing all three layers
@@ -142,8 +265,10 @@ label <- api.label ?? errorHandler:i.fallbackMsg
 `||` and `??` compose into a Postgres-style `COALESCE` with an error guard at the end:
 
 ```hcl
-# label <- A || B || C || "literal" ?? errorSource
-label <- api.label || tool:api.backup.label || "unknown" ?? tool:const.errorString
+with output as o
+
+# o.label <- A || B || C || "literal" ?? errorSource
+o.label <- api.label || tool:api.backup.label || "unknown" ?? tool:const.errorString
 
 # Evaluation order:
 # api.label non-null     → use it immediately
@@ -159,11 +284,14 @@ Multiple `||` sources desugar to **parallel wires** — all sources are evaluate
 By default, the engine is **lazy**. Use `<-!` to force execution regardless of demand—perfect for side-effects like analytics, audit logging, or cache warming.
 
 ```hcl
-bridge Mutation.updateUser
+bridge Mutation.updateUser {
   with audit.logger as log
+  with input as in
+  with output as out
 
   # 'log' runs even if the client doesn't query the 'status' field
-  status <-! log:i.changeData
+  out.status <-! log:in.changeData
+}
 ```
 
 ### The Pipe Operator (`:`)
@@ -171,25 +299,52 @@ bridge Mutation.updateUser
 Routes data right-to-left through one or more tool handles: `dest <- handle:source`.
 
 ```hcl
+with output as o
+
 # i.rawData → normalize → transform → result
-result <- transform:normalize:i.rawData
+o.result <- transform:normalize:i.rawData
 ```
 
 Full example with a tool that has 2 input parameters:
 
 ```hcl
-extend currencyConverter as convert
-  currency = EUR   # default currency
+tool convert from currencyConverter {
+  .currency = EUR   # default currency
+}
 
-bridge Query.price
+# example with pipe syntax
+bridge Query.price {
   with convert as c
   with input as i
+  with output as o
+
+  c.currency <- i.currency   # overrides the default per request
+
+  # Safe to use repeatedly — each is an independent tool call
+  o.itemPrice  <- c:i.itemPrice
+  o.totalPrice <- c:i.totalPrice
+}
+
+# same without the pipe syntax
+tool c1 from convert
+tool c2 from convert
+
+bridge Query.price {
+  with c1
+  with c2
+  with input as i
+  with output as o
+
+  c1.currency <- i.currency   # overrides the default per request
+  c2.currency <- i.currency   # overrides the default per request
 
-c.currency <- i.currency   # overrides the default per request
+  c1.in <- i.itemPrice
+  c2.in <- i.totalPrice
 
-# Safe to use repeatedly — each is an independent tool call
-itemPrice  <- c:i.itemPrice
-totalPrice <- c:i.totalPrice
+  # Safe to use repeatedly — each is an independent tool call
+  o.itemPrice  <- c1
+  o.totalPrice <- c2
+}
 ```
 
 ---
@@ -205,9 +360,10 @@ totalPrice <- c:i.totalPrice
 | **`\|\|`** | Null-coalesce | Next alternative if current source is `null`/`undefined`. Fires on absent values, not errors. |
 | **`??`** | Error-fallback | Alternative used when the resolution chain **throws**. Fires on errors, not null values. |
 | **`on error`** | Tool Fallback | Returns a default if the tool's `fn(input)` throws. |
-| **`extend`** | Tool Definition | Configures a function or extends a parent tool. |
+| **`tool ... from`** | Tool Definition | Configures a function or inherits from a parent tool. |
+| **`define`** | Reusable Subgraph | Declares a named pipeline template invocable from bridges. |
 | **`const`** | Named Value | Declares reusable JSON constants. |
-| **`[] <- []`** | Map | Iterates over arrays to create nested wire contexts. |
+| **`<- src[] as i { }`** | Map | Iterates over source array; each element accessed via the named iterator `i`. `i.field` references the current element. `.field = "value"` sets an element constant. |
 
 ---
 
@@ -263,30 +419,35 @@ The Bridge ships with built-in tools under the `std` namespace, always available
 
 ### Using Built-in Tools
 
-**No `extend` block needed** for pipe-like tools — reference them with the `std.` prefix in the `with` header:
+**No `tool` block needed** for pipe-like tools — reference them with the `std.` prefix in the `with` header:
 
 ```hcl
-bridge Query.format
+bridge Query.format {
   with std.upperCase as up
   with std.lowerCase as lo
   with input as i
+  with output as o
 
-upper <- up:i.text
-lower <- lo:i.text
+  o.upper <- up:i.text
+  o.lower <- lo:i.text
+}
 ```
 
-Use an `extend` block when you need to configure defaults:
+Use a `tool` block when you need to configure defaults:
 
 ```hcl
-extend std.pickFirst as pf
-  strict = true
+tool pf from std.pickFirst {
+  .strict = true
+}
 
-bridge Query.onlyResult
+bridge Query.onlyResult {
   with pf
   with someApi as api
   with input as i
+  with output as o
 
-value <- pf:api.items
+  o.value <- pf:api.items
+}
 ```
 
 ### Adding Custom Tools
@@ -321,11 +482,12 @@ const schema = bridgeTransform(createSchema({ typeDefs }), instructions, {
 Add `cache = <seconds>` to any `httpCall` tool to enable TTL-based response caching. Identical requests (same method + URL + params) return the cached result without hitting the network.
 
 ```hcl
-extend httpCall as geo
-  cache = 300          # cache for 5 minutes
-  baseUrl = "https://nominatim.openstreetmap.org"
-  method = GET
-  path = /search
+tool geo from httpCall {
+  .cache = 300          # cache for 5 minutes
+  .baseUrl = "https://nominatim.openstreetmap.org"
+  .method = GET
+  .path = /search
+}
 ```
 
 The default is an in-memory store. For Redis or other backends, pass a custom `CacheStore` to `createHttpCall`:

package/build/ExecutionTree.js

@@ -264,7 +264,12 @@ export class ExecutionTree {
                 return [w.to.path, value];
             }));
             for (const [path, value] of resolved) {
-                setNested(input, path, value);
+                if (path.length === 0 && value != null && typeof value === "object") {
+                    Object.assign(input, value);
+                }
+                else {
+                    setNested(input, path, value);
+                }
             }
             // Call ToolDef-backed tool function
             if (toolDef) {
@@ -289,6 +294,11 @@ export class ExecutionTree {
             if (directFn) {
                 return directFn(input);
             }
+            // Define pass-through: synthetic trunks created by define inlining
+            // act as data containers — bridge wires set their values, no tool needed.
+            if (target.module.startsWith("__define_")) {
+                return input;
+            }
             throw new Error(`No tool found for "${toolName}"`);
         })();
     }
@@ -432,7 +442,7 @@ export class ExecutionTree {
         // 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 &&
+        const matches = this.bridge?.wires.filter((w) => (w.to.element ? !!this.parent : true) &&
             sameTrunk(w.to, this.trunk) &&
             pathEquals(w.to.path, cleanPath)) ?? [];
         if (matches.length > 0) {

package/build/bridge-format.d.ts

@@ -1,14 +1,4 @@
 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.