@stackables/bridge 1.0.0

package/build/bridge-transform.d.ts

@@ -0,0 +1,15 @@
+import { type GraphQLSchema } from "graphql";
+import type { Instruction, ToolMap } from "./types.js";
+export type BridgeOptions = {
+    /** Tool functions available to the engine.
+     *  Supports namespaced nesting: `{ myNamespace: { myTool } }`.
+     *  The built-in `std` namespace and `httpCall` are always included;
+     *  user tools are merged on top (shallow). */
+    tools?: ToolMap;
+    /** Optional function to reshape/restrict the GQL context before it reaches bridge files.
+     *  By default the full context is exposed via `with context`. */
+    contextMapper?: (context: any) => Record<string, any>;
+};
+/** Instructions can be a static array or a function that selects per-request */
+export type InstructionSource = Instruction[] | ((context: any) => Instruction[]);
+export declare function bridgeTransform(schema: GraphQLSchema, instructions: InstructionSource, options?: BridgeOptions): GraphQLSchema;

package/build/bridge-transform.js

@@ -0,0 +1,57 @@
+import { MapperKind, mapSchema } from "@graphql-tools/utils";
+import { GraphQLList, GraphQLNonNull, defaultFieldResolver, } from "graphql";
+import { ExecutionTree } from "./ExecutionTree.js";
+import { builtinTools } from "./tools/index.js";
+import { SELF_MODULE } from "./types.js";
+export function bridgeTransform(schema, instructions, options) {
+    const userTools = options?.tools;
+    const contextMapper = options?.contextMapper;
+    return mapSchema(schema, {
+        [MapperKind.OBJECT_FIELD]: (fieldConfig, fieldName, typeName) => {
+            let array = false;
+            if (fieldConfig.type instanceof GraphQLNonNull) {
+                if (fieldConfig.type.ofType instanceof GraphQLList) {
+                    array = true;
+                }
+            }
+            if (fieldConfig.type instanceof GraphQLList) {
+                array = true;
+            }
+            const trunk = { module: SELF_MODULE, type: typeName, field: fieldName };
+            const { resolve = defaultFieldResolver } = fieldConfig;
+            return {
+                ...fieldConfig,
+                resolve: async function (source, args, context, info) {
+                    // Start execution tree at query/mutation root
+                    if (!source && !info.path.prev) {
+                        const bridgeContext = contextMapper
+                            ? contextMapper(context)
+                            : (context ?? {});
+                        const activeInstructions = typeof instructions === "function"
+                            ? instructions(context)
+                            : instructions;
+                        // Always include builtinTools; user tools merge on top (shallow)
+                        const allTools = {
+                            ...builtinTools,
+                            ...(userTools ?? {}),
+                        };
+                        source = new ExecutionTree(trunk, activeInstructions, allTools, bridgeContext);
+                    }
+                    if (source instanceof ExecutionTree &&
+                        args &&
+                        Object.keys(args).length > 0) {
+                        source.push(args);
+                    }
+                    // Kick off forced wires (<-!) at the root entry point
+                    if (source instanceof ExecutionTree && !info.path.prev) {
+                        source.executeForced();
+                    }
+                    if (source instanceof ExecutionTree) {
+                        return source.response(info.path, array);
+                    }
+                    return resolve(source, args, context, info);
+                },
+            };
+        },
+    });
+}

package/build/index.d.ts

@@ -0,0 +1,5 @@
+export { parseBridge } from "./bridge-format.js";
+export { bridgeTransform } from "./bridge-transform.js";
+export type { BridgeOptions, InstructionSource } from "./bridge-transform.js";
+export { builtinTools, std, createHttpCall } from "./tools/index.js";
+export type { CacheStore, ConstDef, Instruction, ToolCallFn, ToolDef, ToolMap } from "./types.js";

package/build/index.js

@@ -0,0 +1,3 @@
+export { parseBridge } from "./bridge-format.js";
+export { bridgeTransform } from "./bridge-transform.js";
+export { builtinTools, std, createHttpCall } from "./tools/index.js";

package/build/tools/find-object.d.ts

@@ -0,0 +1,4 @@
+export declare function findObject(opts: {
+    in: any[];
+    [key: string]: any;
+}): any;

package/build/tools/find-object.js

@@ -0,0 +1,11 @@
+export function findObject(opts) {
+    const { in: arr, ...criteria } = opts;
+    return arr.find((obj) => {
+        for (const [key, value] of Object.entries(criteria)) {
+            if (obj[key] !== value) {
+                return false;
+            }
+        }
+        return true;
+    });
+}

package/build/tools/http-call.d.ts

@@ -0,0 +1,34 @@
+import type { CacheStore, ToolCallFn } from "../types.js";
+/**
+ * Parse TTL (in seconds) from HTTP response headers.
+ *
+ * Priority: `Cache-Control: s-maxage` > `Cache-Control: max-age` > `Expires`.
+ * Returns 0 if the response is uncacheable (no-store, no-cache, or no headers).
+ */
+declare function parseCacheTTL(response: Response): number;
+/**
+ * Create an httpCall tool function — the built-in REST API tool.
+ *
+ * Receives a fully-built input object from the engine and makes an HTTP call.
+ * The engine resolves all wires (from tool definition + bridge wires) before calling.
+ *
+ * Expected input shape:
+ *   { baseUrl, method?, path?, headers?, cache?, ...shorthandFields }
+ *
+ * Routing rules:
+ *   - GET: shorthand fields → query string parameters
+ *   - POST/PUT/PATCH/DELETE: shorthand fields → JSON body
+ *   - `headers` object passed as HTTP headers
+ *   - `baseUrl` + `path` concatenated for the URL
+ *
+ * Cache modes:
+ *   - `cache = "auto"` (default) — respect HTTP Cache-Control / Expires headers
+ *   - `cache = 0` — disable caching entirely
+ *   - `cache = <seconds>` — explicit TTL override, ignores response headers
+ *
+ * @param fetchFn - Fetch implementation (override for testing)
+ * @param cacheStore - Pluggable cache store (default: in-memory LRU, 1024 entries)
+ */
+export declare function createHttpCall(fetchFn?: typeof fetch, cacheStore?: CacheStore): ToolCallFn;
+/** Exported for testing. */
+export { parseCacheTTL };

package/build/tools/http-call.js

@@ -0,0 +1,116 @@
+import { LRUCache } from "lru-cache";
+/** Default in-memory LRU cache with per-entry TTL. */
+function createMemoryCache(maxEntries = 1024) {
+    const lru = new LRUCache({ max: maxEntries });
+    return {
+        get(key) { return lru.get(key); },
+        set(key, value, ttlSeconds) {
+            if (ttlSeconds <= 0)
+                return;
+            lru.set(key, value, { ttl: ttlSeconds * 1000 });
+        },
+    };
+}
+/**
+ * Parse TTL (in seconds) from HTTP response headers.
+ *
+ * Priority: `Cache-Control: s-maxage` > `Cache-Control: max-age` > `Expires`.
+ * Returns 0 if the response is uncacheable (no-store, no-cache, or no headers).
+ */
+function parseCacheTTL(response) {
+    const cc = response.headers.get("cache-control");
+    if (cc) {
+        if (/\bno-store\b/i.test(cc) || /\bno-cache\b/i.test(cc))
+            return 0;
+        const sMax = cc.match(/\bs-maxage\s*=\s*(\d+)\b/i);
+        if (sMax)
+            return Number(sMax[1]);
+        const max = cc.match(/\bmax-age\s*=\s*(\d+)\b/i);
+        if (max)
+            return Number(max[1]);
+    }
+    const expires = response.headers.get("expires");
+    if (expires) {
+        const delta = Math.floor((new Date(expires).getTime() - Date.now()) / 1000);
+        return delta > 0 ? delta : 0;
+    }
+    return 0;
+}
+/**
+ * Create an httpCall tool function — the built-in REST API tool.
+ *
+ * Receives a fully-built input object from the engine and makes an HTTP call.
+ * The engine resolves all wires (from tool definition + bridge wires) before calling.
+ *
+ * Expected input shape:
+ *   { baseUrl, method?, path?, headers?, cache?, ...shorthandFields }
+ *
+ * Routing rules:
+ *   - GET: shorthand fields → query string parameters
+ *   - POST/PUT/PATCH/DELETE: shorthand fields → JSON body
+ *   - `headers` object passed as HTTP headers
+ *   - `baseUrl` + `path` concatenated for the URL
+ *
+ * Cache modes:
+ *   - `cache = "auto"` (default) — respect HTTP Cache-Control / Expires headers
+ *   - `cache = 0` — disable caching entirely
+ *   - `cache = <seconds>` — explicit TTL override, ignores response headers
+ *
+ * @param fetchFn - Fetch implementation (override for testing)
+ * @param cacheStore - Pluggable cache store (default: in-memory LRU, 1024 entries)
+ */
+export function createHttpCall(fetchFn = globalThis.fetch, cacheStore = createMemoryCache()) {
+    return async (input) => {
+        const { baseUrl = "", method = "GET", path = "", headers: inputHeaders = {}, cache: cacheMode = "auto", ...rest } = input;
+        // Build URL
+        const url = new URL(baseUrl + path);
+        // Collect headers
+        const headers = {};
+        for (const [key, value] of Object.entries(inputHeaders)) {
+            if (value != null)
+                headers[key] = String(value);
+        }
+        // GET: shorthand fields → query string
+        if (method === "GET") {
+            for (const [key, value] of Object.entries(rest)) {
+                if (value != null) {
+                    url.searchParams.set(key, String(value));
+                }
+            }
+        }
+        // Non-GET: shorthand fields → JSON body
+        let body;
+        if (method !== "GET") {
+            const bodyObj = {};
+            for (const [key, value] of Object.entries(rest)) {
+                if (value != null)
+                    bodyObj[key] = value;
+            }
+            if (Object.keys(bodyObj).length > 0) {
+                body = JSON.stringify(bodyObj);
+                headers["Content-Type"] ??= "application/json";
+            }
+        }
+        // cache = 0 → no caching at all
+        const mode = String(cacheMode);
+        if (mode === "0") {
+            const response = await fetchFn(url.toString(), { method, headers, body });
+            return response.json();
+        }
+        const cacheKey = method + " " + url.toString() + (body ?? "");
+        // Check cache before fetching
+        const cached = await cacheStore.get(cacheKey);
+        if (cached !== undefined)
+            return cached;
+        const response = await fetchFn(url.toString(), { method, headers, body });
+        const data = await response.json();
+        // Determine TTL
+        const ttl = mode === "auto" ? parseCacheTTL(response) : Number(mode);
+        if (ttl > 0) {
+            await cacheStore.set(cacheKey, data, ttl);
+        }
+        return data;
+    };
+}
+/** Exported for testing. */
+export { parseCacheTTL };

package/build/tools/index.d.ts

@@ -0,0 +1,43 @@
+import { upperCase } from "./upper-case.js";
+import { lowerCase } from "./lower-case.js";
+import { findObject } from "./find-object.js";
+import { pickFirst } from "./pick-first.js";
+import { toArray } from "./to-array.js";
+export declare const std: {
+    readonly httpCall: import("../types.js").ToolCallFn;
+    readonly upperCase: typeof upperCase;
+    readonly lowerCase: typeof lowerCase;
+    readonly findObject: typeof findObject;
+    readonly pickFirst: typeof pickFirst;
+    readonly toArray: typeof toArray;
+};
+/**
+ * Built-in tools bundle.
+ *
+ * Used as the base for `BridgeOptions.tools`. The `std` namespace is always
+ * included; user-provided tools are merged on top.
+ *
+ * ```ts
+ * import { builtinTools } from "@stackables/bridge";
+ *
+ * bridgeTransform(schema, instructions, {
+ *   tools: { myCustomTool }  // std + httpCall are still available
+ * });
+ * ```
+ */
+export declare const builtinTools: {
+    readonly std: {
+        readonly httpCall: import("../types.js").ToolCallFn;
+        readonly upperCase: typeof upperCase;
+        readonly lowerCase: typeof lowerCase;
+        readonly findObject: typeof findObject;
+        readonly pickFirst: typeof pickFirst;
+        readonly toArray: typeof toArray;
+    };
+};
+export { createHttpCall } from "./http-call.js";
+export { upperCase } from "./upper-case.js";
+export { lowerCase } from "./lower-case.js";
+export { findObject } from "./find-object.js";
+export { pickFirst } from "./pick-first.js";
+export { toArray } from "./to-array.js";

package/build/tools/index.js

@@ -0,0 +1,43 @@
+import { createHttpCall } from "./http-call.js";
+import { upperCase } from "./upper-case.js";
+import { lowerCase } from "./lower-case.js";
+import { findObject } from "./find-object.js";
+import { pickFirst } from "./pick-first.js";
+import { toArray } from "./to-array.js";
+/**
+ * Standard built-in tools — available under the `std` namespace.
+ *
+ * Referenced in `.bridge` files as `std.upperCase`, `std.pickFirst`, etc.
+ */
+const httpCallFn = createHttpCall();
+export const std = {
+    httpCall: httpCallFn,
+    upperCase,
+    lowerCase,
+    findObject,
+    pickFirst,
+    toArray,
+};
+/**
+ * Built-in tools bundle.
+ *
+ * Used as the base for `BridgeOptions.tools`. The `std` namespace is always
+ * included; user-provided tools are merged on top.
+ *
+ * ```ts
+ * import { builtinTools } from "@stackables/bridge";
+ *
+ * bridgeTransform(schema, instructions, {
+ *   tools: { myCustomTool }  // std + httpCall are still available
+ * });
+ * ```
+ */
+export const builtinTools = {
+    std,
+};
+export { createHttpCall } from "./http-call.js";
+export { upperCase } from "./upper-case.js";
+export { lowerCase } from "./lower-case.js";
+export { findObject } from "./find-object.js";
+export { pickFirst } from "./pick-first.js";
+export { toArray } from "./to-array.js";

package/build/tools/lower-case.d.ts

@@ -0,0 +1,3 @@
+export declare function lowerCase(opts: {
+    in: string;
+}): string;

package/build/tools/lower-case.js

@@ -0,0 +1,3 @@
+export function lowerCase(opts) {
+    return opts.in.toLowerCase();
+}

package/build/tools/pick-first.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Returns the first element of the array in `opts.in`.
+ *
+ * By default silently returns `undefined` for empty arrays.
+ * Set `opts.strict` to `true` (or the string "true") to throw when
+ * the array is empty or contains more than one element.
+ */
+export declare function pickFirst(opts: {
+    in: any[];
+    strict?: boolean | string;
+}): any;

package/build/tools/pick-first.js

@@ -0,0 +1,20 @@
+/**
+ * Returns the first element of the array in `opts.in`.
+ *
+ * By default silently returns `undefined` for empty arrays.
+ * Set `opts.strict` to `true` (or the string "true") to throw when
+ * the array is empty or contains more than one element.
+ */
+export function pickFirst(opts) {
+    const arr = opts.in;
+    const strict = opts.strict === true || opts.strict === "true";
+    if (strict) {
+        if (!Array.isArray(arr) || arr.length === 0) {
+            throw new Error("pickFirst: expected a non-empty array");
+        }
+        if (arr.length > 1) {
+            throw new Error(`pickFirst: expected exactly one element but got ${arr.length}`);
+        }
+    }
+    return Array.isArray(arr) ? arr[0] : undefined;
+}

package/build/tools/to-array.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Wraps a single value in an array.
+ *
+ * If `opts.in` is already an array it is returned as-is.
+ */
+export declare function toArray(opts: {
+    in: any;
+}): any[];

package/build/tools/to-array.js

@@ -0,0 +1,8 @@
+/**
+ * Wraps a single value in an array.
+ *
+ * If `opts.in` is already an array it is returned as-is.
+ */
+export function toArray(opts) {
+    return Array.isArray(opts.in) ? opts.in : [opts.in];
+}

package/build/tools/upper-case.d.ts

@@ -0,0 +1,3 @@
+export declare function upperCase(opts: {
+    in: string;
+}): string;

package/build/tools/upper-case.js

@@ -0,0 +1,3 @@
+export function upperCase(opts) {
+    return opts.in.toUpperCase();
+}

package/build/types.d.ts

@@ -0,0 +1,218 @@
+/**
+ * Structured node reference — identifies a specific data point in the execution graph.
+ *
+ * Every wire has a "from" and "to", each described by a NodeRef.
+ * The trunk (module + type + field + instance) identifies the node,
+ * while path drills into its data.
+ */
+export type NodeRef = {
+    /** Module identifier: "hereapi", "sendgrid", "zillow", or SELF_MODULE */
+    module: string;
+    /** GraphQL type ("Query" | "Mutation") or "Tools" for tool functions */
+    type: string;
+    /** Field or function name: "geocode", "search", "centsToUsd" */
+    field: string;
+    /** Instance number for tool calls (1, 2, ...) */
+    instance?: number;
+    /** References the current array element in a shadow tree (for per-element mapping) */
+    element?: boolean;
+    /** Path into the data: ["items", "0", "position", "lat"] */
+    path: string[];
+};
+/**
+ * A wire connects a data source (from) to a data sink (to).
+ * Execution is pull-based: when "to" is demanded, "from" is resolved.
+ *
+ * Constant wires (`=`) set a fixed value on the target.
+ * Pull wires (`<-`) resolve the source at runtime.
+ * Pipe wires (`pipe: true`) are generated by the `<- h1|h2|source` shorthand
+ * and route data through declared tool handles; the serializer collapses them
+ * back to pipe notation.
+ */
+export type Wire = {
+    from: NodeRef;
+    to: NodeRef;
+    pipe?: true;
+    force?: true;
+    fallback?: string;
+} | {
+    value: string;
+    to: NodeRef;
+};
+/**
+ * Bridge definition — wires one GraphQL field to its data sources.
+ */
+export type Bridge = {
+    kind: "bridge";
+    /** GraphQL type: "Query" | "Mutation" */
+    type: string;
+    /** GraphQL field name */
+    field: string;
+    /** Declared data sources and their wire handles */
+    handles: HandleBinding[];
+    /** Connection wires */
+    wires: Wire[];
+    /**
+     * Pipe fork registry — one entry per pipe use.
+     * Maps the fork's trunk key to the originating handle name and the base
+     * trunk (used by the executor to inherit non-pipe bridge wires).
+     */
+    pipeHandles?: Array<{
+        /** Unique trunk key for this fork: "module:type:field:instance" */
+        key: string;
+        /** The bridge handle name that was piped, e.g. "pt" or "convertToEur" */
+        handle: string;
+        /** Base trunk — regular (non-pipe) bridge wires targeting this trunk are
+         *  applied to every fork before the fork-specific pipe wires. */
+        baseTrunk: {
+            module: string;
+            type: string;
+            field: string;
+            instance?: number;
+        };
+    }>;
+};
+/**
+ * A handle binding — declares a named data source available in a bridge.
+ *
+ * Every wire reference in the bridge body must trace back to one of these.
+ */
+export type HandleBinding = {
+    handle: string;
+    kind: "tool";
+    name: string;
+} | {
+    handle: string;
+    kind: "input";
+} | {
+    handle: string;
+    kind: "context";
+} | {
+    handle: string;
+    kind: "const";
+};
+/** Internal module identifier for the bridge's own trunk (input args + output fields) */
+export declare const SELF_MODULE = "_";
+/**
+ * Tool definition — a declared tool with wires, dependencies, and optional inheritance.
+ *
+ * Tool blocks define reusable, composable API call configurations:
+ *   tool hereapi httpCall        — root tool with function name
+ *   tool hereapi.geocode extends hereapi  — child inherits parent wires
+ *
+ * The engine resolves extends chains, merges wires, and calls the
+ * registered tool function with the fully-built input object.
+ */
+export type ToolDef = {
+    kind: "tool";
+    /** Tool name: "hereapi", "sendgrid.send", "authService" */
+    name: string;
+    /** Function name — looked up in the tools map. Omitted when extends is used. */
+    fn?: string;
+    /** Parent tool name — inherits fn, deps, and wires */
+    extends?: string;
+    /** Dependencies declared via `with` inside the tool block */
+    deps: ToolDep[];
+    /** Wires: constants (`=`) and pulls (`<-`) defining the tool's input */
+    wires: ToolWire[];
+};
+/**
+ * A dependency declared inside a tool block.
+ *
+ *   with context                 — brings the full GraphQL context into scope
+ *   with authService as auth     — brings another tool's output into scope
+ */
+export type ToolDep = {
+    kind: "context";
+    handle: string;
+} | {
+    kind: "tool";
+    handle: string;
+    tool: string;
+} | {
+    kind: "const";
+    handle: string;
+};
+/**
+ * A wire in a tool block — either a constant value, a pull from a dependency,
+ * or an error fallback.
+ *
+ * Examples:
+ *   baseUrl = "https://api.sendgrid.com/v3"         → constant
+ *   method = POST                                     → constant (unquoted)
+ *   headers.Authorization <- ctx.sendgrid.token      → pull from context
+ *   headers.Authorization <- auth.access_token       → pull from tool dep
+ *   on error = { "lat": 0, "lon": 0 }               → constant fallback
+ *   on error <- ctx.fallbacks.geo                     → pull fallback from context
+ */
+export type ToolWire = {
+    target: string;
+    kind: "constant";
+    value: string;
+} | {
+    target: string;
+    kind: "pull";
+    source: string;
+} | {
+    kind: "onError";
+    value: string;
+} | {
+    kind: "onError";
+    source: string;
+};
+/**
+ * Tool call function — the signature for registered tool functions.
+ *
+ * Receives a fully-built nested input object and returns the response.
+ * The engine builds the input from tool wires + bridge wires.
+ *
+ * Example (httpCall):
+ *   input = { baseUrl: "https://...", method: "GET", path: "/geocode",
+ *             headers: { apiKey: "..." }, q: "Berlin" }
+ */
+export type ToolCallFn = (input: Record<string, any>) => Promise<Record<string, any>>;
+/**
+ * Recursive tool map — supports namespaced tools via nesting.
+ *
+ * Example:
+ *   { std: { upperCase, lowerCase }, httpCall: createHttpCall(), myCompany: { myTool } }
+ *
+ * Lookup is dot-separated: "std.upperCase" → tools.std.upperCase
+ */
+export type ToolMap = {
+    [key: string]: ToolCallFn | ((...args: any[]) => any) | ToolMap;
+};
+/**
+ * Named constant definition — a reusable value defined in the bridge file.
+ *
+ * Constants are available in bridge blocks via `with const as c` and in tool
+ * blocks via `with const`. The engine collects all ConstDef instructions into
+ * a single namespace object keyed by name.
+ *
+ * Examples:
+ *   const fallbackGeo = { "lat": 0, "lon": 0 }
+ *   const defaultCurrency = "EUR"
+ */
+export type ConstDef = {
+    kind: "const";
+    /** Constant name — used as the key in the const namespace */
+    name: string;
+    /** Raw JSON string — parsed at runtime when accessed */
+    value: string;
+};
+/** Union of all instruction types */
+export type Instruction = Bridge | ToolDef | ConstDef;
+/**
+ * Pluggable cache store for httpCall.
+ *
+ * Default: in-memory Map with TTL eviction.
+ * Override: pass any key-value store (Redis, Memcached, etc.) to `createHttpCall`.
+ *
+ * ```ts
+ * const httpCall = createHttpCall(fetch, myRedisStore);
+ * ```
+ */
+export type CacheStore = {
+    get(key: string): Promise<any | undefined> | any | undefined;
+    set(key: string, value: any, ttlSeconds: number): Promise<void> | void;
+};

package/build/types.js

@@ -0,0 +1,2 @@
+/** Internal module identifier for the bridge's own trunk (input args + output fields) */
+export const SELF_MODULE = "_";