@stackables/bridge 1.1.0 → 1.2.0

package/README.md

@@ -5,9 +5,15 @@ Wire data between APIs, tools, and fields using `.bridge` files—no resolvers,
 
 ```bash
 npm install @stackables/bridge
-
 ```
 
+> **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.
+>
+> Feedback: We are actively looking for use cases. Please share yours in our GitHub Discussions.
+
 ---
 
 ## The Idea
@@ -41,17 +47,17 @@ Access const values in bridges or tools via `with const as c`, then reference as
 
 ### 2. Extend Blocks (`extend`)
 
-Defines the "Where" and the "How." Takes a function (or parent tool) and configures i, giving it a new namet.
+Defines the "Where" and the "How." Takes a function (or parent tool) and configures i, giving it a new name.
 
 ```hcl
-extend <source> as <name>
+extend <source> as <name> {
   [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
-
+}
 ```
 
 When `<source>` is a function name (e.g. `httpCall`), a new tool is created.
@@ -62,7 +68,7 @@ When `<source>` is an existing tool name, the new tool inherits its configuratio
 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>]
 
@@ -81,7 +87,7 @@ bridge <Type.field>
   # Array Mapping
   <field>[] <- <source>[]
     .<sub_field> <- .<sub_src>      # Relative scoping
-
+}
 ```
 
 ---
@@ -97,11 +103,12 @@ Each layer handles a different failure mode. They compose freely.
 Declared inside the `extend` block. Catches any exception thrown by the tool's `fn(input)`. All tools that `extend` this tool inherit the fallback.
 
 ```hcl
-extend httpCall as geo
+extend httpCall as geo {
   baseUrl = "https://nominatim.openstreetmap.org"
   method = GET
   path = /search
   on error = { "lat": 0, "lon": 0 }   # tool-level default
+}
 ```
 
 #### Layer 2 — Wire `||` (null / absent values)
@@ -153,11 +160,12 @@ 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
 
   # 'log' runs even if the client doesn't query the 'status' field
   status <-! log:i.changeData
+}
 ```
 
 ### The Pipe Operator (`:`)
@@ -172,18 +180,20 @@ result <- transform:normalize:i.rawData
 Full example with a tool that has 2 input parameters:
 
 ```hcl
-extend currencyConverter as convert
+extend currencyConverter as convert {
   currency = EUR   # default currency
+}
 
-bridge Query.price
+bridge Query.price {
   with convert as c
   with input as i
 
-c.currency <- i.currency   # overrides the default per request
+  c.currency <- i.currency   # overrides the default per request
 
-# 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
+  itemPrice  <- c:i.itemPrice
+  totalPrice <- c:i.totalPrice
+}
 ```
 
 ---
@@ -260,27 +270,30 @@ The Bridge ships with built-in tools under the `std` namespace, always available
 **No `extend` 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
 
-upper <- up:i.text
-lower <- lo:i.text
+  upper <- up:i.text
+  lower <- lo:i.text
+}
 ```
 
 Use an `extend` block when you need to configure defaults:
 
 ```hcl
-extend std.pickFirst as pf
+extend std.pickFirst as pf {
   strict = true
+}
 
-bridge Query.onlyResult
+bridge Query.onlyResult {
   with pf
   with someApi as api
   with input as i
 
-value <- pf:api.items
+  value <- pf:api.items
+}
 ```
 
 ### Adding Custom Tools
@@ -315,11 +328,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
+extend httpCall as geo {
   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/bridge-format.js

@@ -85,7 +85,28 @@ function isJsonLiteral(s) {
         s === "true" || s === "false" || s === "null";
 }
 function parseBridgeBlock(block, lineOffset) {
-    const lines = block.split("\n").map((l) => l.trimEnd());
+    // Validate mandatory braces: `bridge Foo.bar {` ... `}`
+    const rawLines = block.split("\n");
+    const keywordIdx = rawLines.findIndex((l) => /^bridge\s/i.test(l.trim()));
+    if (keywordIdx !== -1) {
+        const kw = rawLines[keywordIdx].trim();
+        if (!kw.endsWith("{")) {
+            throw new Error(`Line ${lineOffset + keywordIdx + 1}: bridge block must use braces: bridge Type.field {`);
+        }
+        const hasClose = rawLines.some((l) => l.trimEnd() === "}");
+        if (!hasClose) {
+            throw new Error(`Line ${lineOffset + keywordIdx + 1}: bridge block missing closing }`);
+        }
+    }
+    // Strip braces for internal parsing
+    const lines = rawLines.map((l) => {
+        const trimmed = l.trimEnd();
+        if (trimmed === "}")
+            return "";
+        if (/^bridge\s/i.test(trimmed) && trimmed.endsWith("{"))
+            return trimmed.replace(/\s*\{\s*$/, "");
+        return trimmed;
+    });
     const instructions = [];
     /** 1-based global line number for error messages */
     const ln = (i) => lineOffset + i + 1;
@@ -650,7 +671,35 @@ function parseConstLines(block, lineOffset) {
  * is treated as a function name.
  */
 function parseToolBlock(block, lineOffset, previousInstructions) {
-    const lines = block.split("\n").map((l) => l.trimEnd());
+    // Validate mandatory braces for blocks that have a body (deps / wires)
+    const rawLines = block.split("\n");
+    const keywordIdx = rawLines.findIndex((l) => /^(tool|extend)\s/i.test(l.trim()));
+    if (keywordIdx !== -1) {
+        // Check if there are non-blank, non-comment body lines after the keyword
+        const bodyLines = rawLines.slice(keywordIdx + 1).filter((l) => {
+            const t = l.trim();
+            return t !== "" && !t.startsWith("#") && t !== "}";
+        });
+        const kw = rawLines[keywordIdx].trim();
+        if (bodyLines.length > 0) {
+            if (!kw.endsWith("{")) {
+                throw new Error(`Line ${lineOffset + keywordIdx + 1}: extend/tool block with body must use braces: extend Foo as bar {`);
+            }
+            const hasClose = rawLines.some((l) => l.trimEnd() === "}");
+            if (!hasClose) {
+                throw new Error(`Line ${lineOffset + keywordIdx + 1}: extend/tool block missing closing }`);
+            }
+        }
+    }
+    // Strip braces for internal parsing
+    const lines = rawLines.map((l) => {
+        const trimmed = l.trimEnd();
+        if (trimmed === "}")
+            return "";
+        if (/^(tool|extend)\s/i.test(trimmed) && trimmed.endsWith("{"))
+            return trimmed.replace(/\s*\{\s*$/, "");
+        return trimmed;
+    });
     /** 1-based global line number for error messages */
     const ln = (i) => lineOffset + i + 1;
     let toolName = "";
@@ -826,16 +875,17 @@ export function serializeBridge(instructions) {
     for (const bridge of bridges) {
         blocks.push(serializeBridgeBlock(bridge));
     }
-    return blocks.join("\n\n---\n\n") + "\n";
+    return blocks.join("\n\n") + "\n";
 }
 function serializeToolBlock(tool) {
     const lines = [];
+    const hasBody = tool.deps.length > 0 || tool.wires.length > 0;
     // Declaration line — use `extend` format
     if (tool.extends) {
-        lines.push(`extend ${tool.extends} as ${tool.name}`);
+        lines.push(hasBody ? `extend ${tool.extends} as ${tool.name} {` : `extend ${tool.extends} as ${tool.name}`);
     }
     else {
-        lines.push(`extend ${tool.fn} as ${tool.name}`);
+        lines.push(hasBody ? `extend ${tool.fn} as ${tool.name} {` : `extend ${tool.fn} as ${tool.name}`);
     }
     // Dependencies
     for (const dep of tool.deps) {
@@ -882,6 +932,8 @@ function serializeToolBlock(tool) {
             lines.push(`  ${wire.target} <- ${wire.source}`);
         }
     }
+    if (hasBody)
+        lines.push(`}`);
     return lines.join("\n");
 }
 /**
@@ -934,7 +986,7 @@ function serializePipeOrRef(ref, pipeHandleTrunkKeys, toInMap, handleMap, bridge
 function serializeBridgeBlock(bridge) {
     const lines = [];
     // ── Header ──────────────────────────────────────────────────────────
-    lines.push(`bridge ${bridge.type}.${bridge.field}`);
+    lines.push(`bridge ${bridge.type}.${bridge.field} {`);
     for (const h of bridge.handles) {
         switch (h.kind) {
             case "tool": {
@@ -966,6 +1018,8 @@ function serializeBridgeBlock(bridge) {
         }
     }
     lines.push("");
+    // Mark where the wire body starts — everything after this gets 2-space indent
+    const wireBodyStart = lines.length;
     // ── Build handle map for reverse resolution ─────────────────────────
     const { handleMap, inputHandle } = buildHandleMap(bridge);
     // ── Pipe fork registry ──────────────────────────────────────────────
@@ -1096,10 +1150,15 @@ function serializeBridgeBlock(bridge) {
             lines.push(`${destStr} ${arrow} ${handleChain.join(":")}:${sourceStr}${nfb}${errf}`);
         }
     }
+    // Indent wire body lines and close the block
+    for (let i = wireBodyStart; i < lines.length; i++) {
+        if (lines[i] !== "")
+            lines[i] = `  ${lines[i]}`;
+    }
+    lines.push(`}`);
     return lines.join("\n");
 }
 /**
- * Build a reverse lookup: trunk key → handle name.
  * Recomputes instance numbers from handle bindings in declaration order.
  */
 function buildHandleMap(bridge) {

package/package.json

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