@stackables/bridge-graphql 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/bridge-transform.d.ts

@@ -0,0 +1,58 @@
+import { type GraphQLSchema } from "graphql";
+import { type Logger, type ToolTrace, type TraceLevel } from "@stackables/bridge-core";
+import type { Instruction, ToolMap } from "@stackables/bridge-core";
+export type { Logger };
+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>;
+    /** Enable tool-call tracing.
+     *  - `"off"` (default) — no collection, zero overhead
+     *  - `"basic"` — tool, fn, timing, errors; no input/output
+     *  - `"full"` — everything including input and output */
+    trace?: TraceLevel;
+    /**
+     * Structured logger for engine-level events (tool errors, warnings, debug).
+     * Accepts any logger with `debug`, `info`, `warn`, and `error` methods —
+     * pino, winston, `console`, or any compatible interface.
+     * Defaults to silent no-ops so there is zero output unless you opt in.
+     */
+    logger?: Logger;
+};
+/** 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;
+/**
+ * Read traces that were collected during the current request.
+ * Pass the GraphQL context object; returns an empty array when tracing is
+ * disabled or no traces were recorded.
+ */
+export declare function getBridgeTraces(context: any): ToolTrace[];
+/**
+ * Envelop-compatible plugin for GraphQL Yoga (or any Envelop-based server).
+ * When bridge tracing is enabled, this plugin copies the recorded traces into
+ * the GraphQL response `extensions.traces` field.
+ *
+ * Usage:
+ * ```ts
+ * createYoga({ schema, plugins: [useBridgeTracing()] })
+ * ```
+ */
+export declare function useBridgeTracing(): {
+    onExecute({ args }: {
+        args: {
+            contextValue: any;
+        };
+    }): {
+        onExecuteDone({ result, setResult, }: {
+            result: any;
+            setResult: (r: any) => void;
+        }): void;
+    };
+};
+//# sourceMappingURL=bridge-transform.d.ts.map

package/build/bridge-transform.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bridge-transform.d.ts","sourceRoot":"","sources":["../src/bridge-transform.ts"],"names":[],"mappings":"AACA,OAAO,EAGL,KAAK,aAAa,EAEnB,MAAM,SAAS,CAAC;AACjB,OAAO,EAGL,KAAK,MAAM,EACX,KAAK,SAAS,EACd,KAAK,UAAU,EAChB,MAAM,yBAAyB,CAAC;AAEjC,OAAO,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,yBAAyB,CAAC;AAGpE,YAAY,EAAE,MAAM,EAAE,CAAC;AAUvB,MAAM,MAAM,aAAa,GAAG;IAC1B;;;kDAG8C;IAC9C,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB;qEACiE;IACjE,aAAa,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,KAAK,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IACtD;;;6DAGyD;IACzD,KAAK,CAAC,EAAE,UAAU,CAAC;IACnB;;;;;OAKG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,gFAAgF;AAChF,MAAM,MAAM,iBAAiB,GACzB,WAAW,EAAE,GACb,CAAC,CAAC,OAAO,EAAE,GAAG,KAAK,WAAW,EAAE,CAAC,CAAC;AAEtC,wBAAgB,eAAe,CAC7B,MAAM,EAAE,aAAa,EACrB,YAAY,EAAE,iBAAiB,EAC/B,OAAO,CAAC,EAAE,aAAa,GACtB,aAAa,CAqHf;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,GAAG,GAAG,SAAS,EAAE,CAEzD;AAED;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB;wBAER;QAAE,IAAI,EAAE;YAAE,YAAY,EAAE,GAAG,CAAA;SAAE,CAAA;KAAE;8CAK5C;YACD,MAAM,EAAE,GAAG,CAAC;YACZ,SAAS,EAAE,CAAC,CAAC,EAAE,GAAG,KAAK,IAAI,CAAC;SAC7B;;EAeR"}

package/build/bridge-transform.js

@@ -0,0 +1,135 @@
+import { MapperKind, mapSchema } from "@graphql-tools/utils";
+import { GraphQLList, GraphQLNonNull, defaultFieldResolver, } from "graphql";
+import { ExecutionTree, TraceCollector, } from "@stackables/bridge-core";
+import { std } from "@stackables/bridge-stdlib";
+import { SELF_MODULE } from "@stackables/bridge-core";
+const noop = () => { };
+const defaultLogger = {
+    debug: noop,
+    info: noop,
+    warn: noop,
+    error: noop,
+};
+export function bridgeTransform(schema, instructions, options) {
+    const userTools = options?.tools;
+    const contextMapper = options?.contextMapper;
+    const traceLevel = options?.trace ?? "off";
+    const logger = options?.logger ?? defaultLogger;
+    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 activeInstructions = typeof instructions === "function"
+                            ? instructions(context)
+                            : instructions;
+                        // Only intercept fields that have a matching bridge instruction.
+                        // Fields without one fall through to their original resolver,
+                        // allowing hand-coded resolvers to coexist with bridge-powered ones.
+                        const hasBridge = activeInstructions.some((i) => i.kind === "bridge" &&
+                            i.type === typeName &&
+                            i.field === fieldName);
+                        if (!hasBridge) {
+                            return resolve(source, args, context, info);
+                        }
+                        const bridgeContext = contextMapper
+                            ? contextMapper(context)
+                            : (context ?? {});
+                        // std is always included; user tools merge on top (shallow)
+                        // internal tools are injected automatically by ExecutionTree
+                        const allTools = {
+                            std,
+                            ...(userTools ?? {}),
+                        };
+                        source = new ExecutionTree(trunk, activeInstructions, allTools, bridgeContext);
+                        source.logger = logger;
+                        if (traceLevel !== "off") {
+                            source.tracer = new TraceCollector(traceLevel);
+                            // Stash tracer on GQL context so the tracing plugin can read it
+                            context.__bridgeTracer = source.tracer;
+                        }
+                    }
+                    if (source instanceof ExecutionTree &&
+                        args &&
+                        Object.keys(args).length > 0) {
+                        source.push(args);
+                    }
+                    // Kick off forced handles (force <handle>) at the root entry point
+                    if (source instanceof ExecutionTree && !info.path.prev) {
+                        // Ensure input state exists even with no args (prevents
+                        // recursive scheduling of the input trunk → stack overflow).
+                        if (!args || Object.keys(args).length === 0) {
+                            source.push({});
+                        }
+                        const criticalForces = source.executeForced();
+                        if (criticalForces.length > 0) {
+                            source.setForcedExecution(Promise.all(criticalForces).then(() => { }));
+                        }
+                    }
+                    if (source instanceof ExecutionTree) {
+                        const result = source.response(info.path, array);
+                        // At the leaf level (not root), race data pull with critical
+                        // force promises so errors propagate into GraphQL `errors[]`
+                        // while still allowing parallel execution.
+                        if (info.path.prev && source.getForcedExecution()) {
+                            return Promise.all([result, source.getForcedExecution()]).then(([data]) => data);
+                        }
+                        return result;
+                    }
+                    return resolve(source, args, context, info);
+                },
+            };
+        },
+    });
+}
+/**
+ * Read traces that were collected during the current request.
+ * Pass the GraphQL context object; returns an empty array when tracing is
+ * disabled or no traces were recorded.
+ */
+export function getBridgeTraces(context) {
+    return context?.__bridgeTracer?.traces ?? [];
+}
+/**
+ * Envelop-compatible plugin for GraphQL Yoga (or any Envelop-based server).
+ * When bridge tracing is enabled, this plugin copies the recorded traces into
+ * the GraphQL response `extensions.traces` field.
+ *
+ * Usage:
+ * ```ts
+ * createYoga({ schema, plugins: [useBridgeTracing()] })
+ * ```
+ */
+export function useBridgeTracing() {
+    return {
+        onExecute({ args }) {
+            return {
+                onExecuteDone({ result, setResult, }) {
+                    const traces = getBridgeTraces(args.contextValue);
+                    if (traces.length > 0 && result && "data" in result) {
+                        setResult({
+                            ...result,
+                            extensions: {
+                                ...(result.extensions ?? {}),
+                                traces,
+                            },
+                        });
+                    }
+                },
+            };
+        },
+    };
+}

package/build/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @stackables/bridge-graphql — Wire bridges into a GraphQL schema.
+ *
+ * Provides `bridgeTransform()` to map bridge instructions onto GraphQL
+ * resolvers, plus tracing utilities for request-level tool-call visibility.
+ *
+ * Peer dependencies: `graphql`, `@graphql-tools/utils`.
+ */
+export { bridgeTransform, getBridgeTraces, useBridgeTracing, } from "./bridge-transform.ts";
+export type { BridgeOptions, InstructionSource } from "./bridge-transform.ts";
+//# sourceMappingURL=index.d.ts.map

package/build/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EACL,eAAe,EACf,eAAe,EACf,gBAAgB,GACjB,MAAM,uBAAuB,CAAC;AAC/B,YAAY,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC"}

package/build/index.js

@@ -0,0 +1,9 @@
+/**
+ * @stackables/bridge-graphql — Wire bridges into a GraphQL schema.
+ *
+ * Provides `bridgeTransform()` to map bridge instructions onto GraphQL
+ * resolvers, plus tracing utilities for request-level tool-call visibility.
+ *
+ * Peer dependencies: `graphql`, `@graphql-tools/utils`.
+ */
+export { bridgeTransform, getBridgeTraces, useBridgeTracing, } from "./bridge-transform.js";

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@stackables/bridge-graphql",
+  "version": "0.0.1",
+  "description": "Bridge GraphQL adapter — wire bridges into a GraphQL schema",
+  "main": "./build/index.js",
+  "type": "module",
+  "types": "./build/index.d.ts",
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "import": "./build/index.js",
+      "types": "./build/index.d.ts"
+    }
+  },
+  "files": [
+    "build",
+    "README.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/stackables/bridge.git"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "@stackables/bridge-stdlib": "0.0.1",
+    "@stackables/bridge-core": "0.0.1"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3"
+  },
+  "peerDependencies": {
+    "graphql": "^16",
+    "@graphql-tools/utils": "^11"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json"
+  }
+}