@graphql-hive/router-runtime 1.1.0-rc-924ffb15d84292a020a45655046fd359ea9f02d5 → 1.1.0-rc-aa2a330ec509cf750e8722741cb18aed3ad01793

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # @graphql-hive/router-runtime
 
-## 1.1.0-rc-924ffb15d84292a020a45655046fd359ea9f02d5
+## 1.1.0-rc-aa2a330ec509cf750e8722741cb18aed3ad01793
 ### Minor Changes
 
 
@@ -17,6 +17,11 @@
   - Updated dependency [`@graphql-hive/router-query-planner@^0.0.4` ↗︎](https://www.npmjs.com/package/@graphql-hive/router-query-planner/v/0.0.4) (from `^0.0.3`, in `dependencies`)
 
 
+- [#1739](https://github.com/graphql-hive/gateway/pull/1739) [`8ff2e47`](https://github.com/graphql-hive/gateway/commit/8ff2e471f368d5e41f91a7fe1f1b0e494ef3e6ff) Thanks [@enisdenjo](https://github.com/enisdenjo)! - dependencies updates:
+  
+  - Updated dependency [`@graphql-hive/router-query-planner@^0.0.6` ↗︎](https://www.npmjs.com/package/@graphql-hive/router-query-planner/v/0.0.6) (from `^0.0.4`, in `dependencies`)
+
+
 - [#1740](https://github.com/graphql-hive/gateway/pull/1740) [`9cfe2a5`](https://github.com/graphql-hive/gateway/commit/9cfe2a555fcbc9a70ba04b32d6844a7a795de624) Thanks [@dependabot](https://github.com/apps/dependabot)! - dependencies updates:
   
   - Updated dependency [`@graphql-hive/router-query-planner@^0.0.6` ↗︎](https://www.npmjs.com/package/@graphql-hive/router-query-planner/v/0.0.6) (from `^0.0.4`, in `dependencies`)
@@ -24,9 +29,13 @@
 
 - [#1708](https://github.com/graphql-hive/gateway/pull/1708) [`bc6cddd`](https://github.com/graphql-hive/gateway/commit/bc6cddd1c53a012dd02a1d8a7217a28e65cc6ae9) Thanks [@ardatan](https://github.com/ardatan)! - Handle listed enum values correctly
   Previously when a field like `[MyEnum!]!` is projected, it was projecting it like it is `MyEnum`.
+
+
+- [#1739](https://github.com/graphql-hive/gateway/pull/1739) [`8ff2e47`](https://github.com/graphql-hive/gateway/commit/8ff2e471f368d5e41f91a7fe1f1b0e494ef3e6ff) Thanks [@enisdenjo](https://github.com/enisdenjo)! - Expose the query plan by using the `useQueryPlan` plugin
+
 - Updated dependencies [[`bc6cddd`](https://github.com/graphql-hive/gateway/commit/bc6cddd1c53a012dd02a1d8a7217a28e65cc6ae9)]:
-  - @graphql-mesh/fusion-runtime@1.6.0-rc-924ffb15d84292a020a45655046fd359ea9f02d5
-  - @graphql-tools/federation@4.2.4-rc-924ffb15d84292a020a45655046fd359ea9f02d5
+  - @graphql-mesh/fusion-runtime@1.6.0-rc-aa2a330ec509cf750e8722741cb18aed3ad01793
+  - @graphql-tools/federation@4.2.4-rc-aa2a330ec509cf750e8722741cb18aed3ad01793
 
 ## 1.0.1
 ### Patch Changes

package/dist/index.cjs

@@ -1071,6 +1071,7 @@ function projectRequires(requiresSelections, entity, supergraphSchema) {
   return result;
 }
 
+const queryPlanForExecutionRequestContext = /* @__PURE__ */ new WeakMap();
 function getLazyValue(factory) {
   let _value;
   return function() {
@@ -1141,52 +1142,59 @@ function unifiedGraphHandler(opts) {
           executionRequest.document,
           executionRequest.operationName || null
         ),
-        (queryPlan) => executeQueryPlan({
-          supergraphSchema,
-          executionRequest,
-          onSubgraphExecute(subgraphName, executionRequest2) {
-            const subschema = getSubschema(subgraphName);
-            if (subschema.transforms?.length) {
-              const transforms = subschema.transforms;
-              const transformationContext = /* @__PURE__ */ Object.create(null);
-              for (const transform of transforms) {
-                if (transform.transformRequest) {
-                  executionRequest2 = transform.transformRequest(
-                    executionRequest2,
-                    void 0,
-                    transformationContext
-                  );
+        (queryPlan) => {
+          queryPlanForExecutionRequestContext.set(
+            // setter like getter
+            executionRequest.context || executionRequest.document,
+            queryPlan
+          );
+          return executeQueryPlan({
+            supergraphSchema,
+            executionRequest,
+            onSubgraphExecute(subgraphName, executionRequest2) {
+              const subschema = getSubschema(subgraphName);
+              if (subschema.transforms?.length) {
+                const transforms = subschema.transforms;
+                const transformationContext = /* @__PURE__ */ Object.create(null);
+                for (const transform of transforms) {
+                  if (transform.transformRequest) {
+                    executionRequest2 = transform.transformRequest(
+                      executionRequest2,
+                      void 0,
+                      transformationContext
+                    );
+                  }
                 }
-              }
-              return promiseHelpers.handleMaybePromise(
-                () => opts.onSubgraphExecute(subgraphName, executionRequest2),
-                (executionResult) => {
-                  function handleResult(executionResult2) {
-                    for (const transform of transforms.toReversed()) {
-                      if (transform.transformResult) {
-                        executionResult2 = transform.transformResult(
-                          executionResult2,
-                          void 0,
-                          transformationContext
-                        );
+                return promiseHelpers.handleMaybePromise(
+                  () => opts.onSubgraphExecute(subgraphName, executionRequest2),
+                  (executionResult) => {
+                    function handleResult(executionResult2) {
+                      for (const transform of transforms.toReversed()) {
+                        if (transform.transformResult) {
+                          executionResult2 = transform.transformResult(
+                            executionResult2,
+                            void 0,
+                            transformationContext
+                          );
+                        }
                       }
+                      return executionResult2;
                     }
-                    return executionResult2;
-                  }
-                  if (utils.isAsyncIterable(executionResult)) {
-                    return promiseHelpers.mapAsyncIterator(
-                      executionResult,
-                      (result) => handleResult(result)
-                    );
+                    if (utils.isAsyncIterable(executionResult)) {
+                      return promiseHelpers.mapAsyncIterator(
+                        executionResult,
+                        (result) => handleResult(result)
+                      );
+                    }
+                    return handleResult(executionResult);
                   }
-                  return handleResult(executionResult);
-                }
-              );
-            }
-            return opts.onSubgraphExecute(subgraphName, executionRequest2);
-          },
-          queryPlan
-        })
+                );
+              }
+              return opts.onSubgraphExecute(subgraphName, executionRequest2);
+            },
+            queryPlan
+          });
+        }
       );
     }
   };
@@ -1215,4 +1223,32 @@ function isIntrospection(document) {
   return containsIntrospectionField || onlyQueryTypenameFields;
 }
 
+function useQueryPlan(opts = {}) {
+  const { expose, onQueryPlan } = opts;
+  return {
+    onExecute({ context, args }) {
+      return {
+        onExecuteDone({ result, setResult }) {
+          const queryPlan = queryPlanForExecutionRequestContext.get(
+            // getter like setter
+            context || args.document
+          );
+          onQueryPlan?.(queryPlan);
+          const shouldExpose = typeof expose === "function" ? expose(context.request) : expose;
+          if (shouldExpose && !utils.isAsyncIterable(result)) {
+            setResult({
+              ...result,
+              extensions: {
+                ...result.extensions,
+                queryPlan
+              }
+            });
+          }
+        }
+      };
+    }
+  };
+}
+
 exports.unifiedGraphHandler = unifiedGraphHandler;
+exports.useQueryPlan = useQueryPlan;

package/dist/index.d.cts

@@ -1,5 +1,262 @@
-import { UnifiedGraphHandlerOpts, UnifiedGraphHandlerResult } from '@graphql-mesh/fusion-runtime';
+import { UnifiedGraphHandlerOpts, UnifiedGraphHandlerResult, UnifiedGraphPlugin, Instrumentation as Instrumentation$2 } from '@graphql-mesh/fusion-runtime';
+import { DisposableSymbols } from '@whatwg-node/disposablestack';
+import { MaybePromise } from '@whatwg-node/promise-helpers';
+import { Plugin, YogaInitialContext, Instrumentation as Instrumentation$1 } from 'graphql-yoga';
+import { MeshFetch, KeyValueCache, MeshFetchRequestInit, Logger as Logger$1 } from '@graphql-mesh/types';
+import { FetchInstrumentation } from '@graphql-mesh/utils';
+import { ExecutionRequest, MaybePromise as MaybePromise$1 } from '@graphql-tools/utils';
+import { GraphQLResolveInfo } from 'graphql/type';
+import { QueryPlan } from '@graphql-hive/router-query-planner';
 
 declare function unifiedGraphHandler(opts: UnifiedGraphHandlerOpts): UnifiedGraphHandlerResult;
 
-export { unifiedGraphHandler };
+type MaybeLazy<T> = T | (() => T);
+type AttributeValue = any;
+type Attributes = AttributeValue[] | {
+    [key: string | number]: AttributeValue;
+};
+
+interface LogWriter {
+    write(level: LogLevel, attrs: Attributes | null | undefined, msg: string | null | undefined): void | Promise<void>;
+    flush?(): void | Promise<void>;
+}
+
+type LogLevel = 'trace' | 'debug' | 'info' | 'warn' | 'error';
+interface LoggerOptions {
+    /**
+     * The minimum log level to log.
+     *
+     * Providing `false` will disable all logging.
+     *
+     * Provided function will always be invoked to get the current log level.
+     *
+     * @default env.LOG_LEVEL || env.DEBUG ? 'debug' : 'info'
+     */
+    level?: MaybeLazy<LogLevel | false>;
+    /** A prefix to include in every log's message. */
+    prefix?: string;
+    /**
+     * The attributes to include in all logs. Is mainly used to pass the parent
+     * attributes when creating {@link Logger.child child loggers}.
+     */
+    attrs?: Attributes;
+    /**
+     * The log writers to use when writing logs.
+     *
+     * @default env.LOG_JSON ? [new JSONLogWriter()] : [new ConsoleLogWriter()]
+     */
+    writers?: [LogWriter, ...LogWriter[]];
+}
+declare class Logger implements AsyncDisposable {
+    #private;
+    constructor(opts?: LoggerOptions);
+    /** The prefix that's prepended to each log message. */
+    get prefix(): string | undefined;
+    /**
+     * The attributes that are added to each log. If the log itself contains
+     * attributes with keys existing in {@link attrs}, the log's attributes will
+     * override.
+     */
+    get attrs(): Attributes | undefined;
+    /** The current {@link LogLevel} of the logger. You can change the level using the {@link setLevel} method. */
+    get level(): false | LogLevel;
+    /**
+     * Sets the new {@link LogLevel} of the logger. All subsequent logs, and {@link child child loggers} whose
+     * level did not change, will respect the new level.
+     */
+    setLevel(level: MaybeLazy<LogLevel | false>): void;
+    write(level: LogLevel, attrs: Attributes | null | undefined, msg: string | null | undefined): void;
+    flush(): Promise<void> | undefined;
+    [DisposableSymbols.asyncDispose](): Promise<void | undefined>;
+    child(prefix: string): Logger;
+    child(attrs: Attributes, prefix?: string): Logger;
+    log(level: LogLevel): void;
+    log(level: LogLevel, attrs: MaybeLazy<Attributes>): void;
+    log(level: LogLevel, msg: string, ...interpol: unknown[]): void;
+    log(level: LogLevel, attrs: MaybeLazy<Attributes>, msg: string, ...interpol: unknown[]): void;
+    trace(): void;
+    trace(attrs: MaybeLazy<Attributes>): void;
+    trace(msg: string, ...interpol: unknown[]): void;
+    trace(attrs: MaybeLazy<Attributes>, msg: string, ...interpol: unknown[]): void;
+    debug(): void;
+    debug(attrs: MaybeLazy<Attributes>): void;
+    debug(msg: string, ...interpol: unknown[]): void;
+    debug(attrs: MaybeLazy<Attributes>, msg: string, ...interpol: unknown[]): void;
+    info(): void;
+    info(attrs: MaybeLazy<Attributes>): void;
+    info(msg: string, ...interpol: unknown[]): void;
+    info(attrs: MaybeLazy<Attributes>, msg: string, ...interpol: unknown[]): void;
+    warn(): void;
+    warn(attrs: MaybeLazy<Attributes>): void;
+    warn(msg: string, ...interpol: unknown[]): void;
+    warn(attrs: MaybeLazy<Attributes>, msg: string, ...interpol: unknown[]): void;
+    error(): void;
+    error(attrs: MaybeLazy<Attributes>): void;
+    error(msg: string, ...interpol: unknown[]): void;
+    error(attrs: MaybeLazy<Attributes>, msg: string, ...interpol: unknown[]): void;
+}
+
+type TopicDataMap = {
+    [topic: string]: any;
+};
+type PubSubListener<Data extends TopicDataMap, Topic extends keyof Data> = (data: Data[Topic]) => void;
+interface PubSub<M extends TopicDataMap = TopicDataMap> {
+    /**
+     * Publish {@link data} for a {@link topic}.
+     * @returns `void` or a `Promise` that resolves when the data has been successfully published
+     */
+    publish<Topic extends keyof M>(topic: Topic, data: M[Topic]): MaybePromise<void>;
+    /**
+     * A distinct list of all topics that are currently subscribed to.
+     * Can be a promise to accomodate distributed systems where subscribers exist on other
+     * locations and we need to know about all of them.
+     */
+    subscribedTopics(): MaybePromise<Iterable<keyof M>>;
+    /**
+     * Subscribe and listen to a {@link topic} receiving its data.
+     *
+     * If the {@link listener} is provided, it will be called whenever data is emitted for the {@link topic},
+     *
+     * @returns an unsubscribe function or a `Promise<unsubscribe function>` that resolves when the subscription is successfully established. the unsubscribe function returns `void` or a `Promise` that resolves on successful unsubscribe and subscription cleanup
+     *
+     * If the {@link listener} is not provided,
+     *
+     * @returns an `AsyncIterable` that yields data for the given {@link topic}
+     */
+    subscribe<Topic extends keyof M>(topic: Topic): AsyncIterable<M[Topic]>;
+    subscribe<Topic extends keyof M>(topic: Topic, listener: PubSubListener<M, Topic>): MaybePromise<() => MaybePromise<void>>;
+    /**
+     * Closes active subscriptions and disposes of all resources. Publishing and subscribing after disposal
+     * is not possible and will throw an error if attempted.
+     */
+    dispose(): MaybePromise<void>;
+    /** @see {@link dispose} */
+    [DisposableSymbols.asyncDispose](): Promise<void>;
+}
+
+interface GatewayConfigContext {
+    /**
+     * WHATWG compatible Fetch implementation.
+     */
+    fetch: MeshFetch;
+    /**
+     * The logger to use throught Hive and its plugins.
+     */
+    log: Logger;
+    /**
+     * Current working directory.
+     * Note that working directory does not exist in serverless environments and will therefore be empty.
+     */
+    cwd: string;
+    /**
+     * Event bus for pub/sub.
+     */
+    pubsub?: PubSub;
+    /**
+     * Cache Storage
+     */
+    cache?: KeyValueCache;
+}
+interface GatewayContext extends GatewayConfigContext, YogaInitialContext {
+    /**
+     * Environment agnostic HTTP headers provided with the request.
+     */
+    headers: Record<string, string>;
+    /**
+     * Runtime context available within WebSocket connections.
+     */
+    connectionParams?: Record<string, string>;
+}
+type GatewayPlugin<TPluginContext extends Record<string, any> = Record<string, any>, TContext extends Record<string, any> = Record<string, any>> = Plugin<Partial<TPluginContext> & GatewayContext & TContext, GatewayConfigContext> & UnifiedGraphPlugin<Partial<TPluginContext> & GatewayContext & TContext> & {
+    onFetch?: OnFetchHook<Partial<TPluginContext> & TContext>;
+    onCacheGet?: OnCacheGetHook;
+    onCacheSet?: OnCacheSetHook;
+    onCacheDelete?: OnCacheDeleteHook;
+    /**
+     * An Instrumentation instance that will wrap each phases of the request pipeline.
+     * This should be used primarily as an observability tool (for monitoring, tracing, etc...).
+     *
+     * Note: The wrapped functions in instrumentation should always be called. Use hooks to
+     *       conditionally skip a phase.
+     */
+    instrumentation?: Instrumentation<TPluginContext & TContext & GatewayContext>;
+};
+interface OnFetchHookPayload<TContext> {
+    url: string;
+    setURL(url: URL | string): void;
+    options: MeshFetchRequestInit;
+    setOptions(options: MeshFetchRequestInit): void;
+    /**
+     * The context is not available in cases where "fetch" is done in
+     * order to pull a supergraph or do some internal work.
+     *
+     * The logger will be available in all cases.
+     */
+    context: (GatewayContext & TContext) | {
+        log: Logger;
+    };
+    /** @deprecated Please use `log` from the {@link context} instead. */
+    logger: Logger$1;
+    info: GraphQLResolveInfo;
+    fetchFn: MeshFetch;
+    setFetchFn: (fetchFn: MeshFetch) => void;
+    executionRequest?: ExecutionRequest;
+    endResponse: (response$: MaybePromise$1<Response>) => void;
+}
+interface OnFetchHookDonePayload {
+    response: Response;
+    setResponse: (response: Response) => void;
+}
+type OnFetchHookDone = (payload: OnFetchHookDonePayload) => MaybePromise$1<void>;
+type OnFetchHook<TContext> = (payload: OnFetchHookPayload<TContext>) => MaybePromise$1<void | OnFetchHookDone>;
+type OnCacheGetHook = (payload: OnCacheGetHookEventPayload) => MaybePromise$1<OnCacheGetHookResult | void>;
+interface OnCacheGetHookEventPayload {
+    cache: KeyValueCache;
+    key: string;
+    ttl?: number;
+}
+interface OnCacheGetHookResult {
+    onCacheHit?: OnCacheHitHook;
+    onCacheMiss?: OnCacheMissHook;
+    onCacheGetError?: OnCacheErrorHook;
+}
+type OnCacheErrorHook = (payload: OnCacheErrorHookPayload) => void;
+interface OnCacheErrorHookPayload {
+    error: Error;
+}
+type OnCacheHitHook = (payload: OnCacheHitHookEventPayload) => void;
+interface OnCacheHitHookEventPayload {
+    value: any;
+}
+type OnCacheMissHook = () => void;
+type OnCacheSetHook = (payload: OnCacheSetHookEventPayload) => MaybePromise$1<OnCacheSetHookResult | void>;
+interface OnCacheSetHookResult {
+    onCacheSetDone?: () => void;
+    onCacheSetError?: OnCacheErrorHook;
+}
+interface OnCacheSetHookEventPayload {
+    cache: KeyValueCache;
+    key: string;
+    value: any;
+    ttl?: number;
+}
+type OnCacheDeleteHook = (payload: OnCacheDeleteHookEventPayload) => MaybePromise$1<OnCacheDeleteHookResult | void>;
+interface OnCacheDeleteHookResult {
+    onCacheDeleteDone?: () => void;
+    onCacheDeleteError?: OnCacheErrorHook;
+}
+interface OnCacheDeleteHookEventPayload {
+    cache: KeyValueCache;
+    key: string;
+}
+type Instrumentation<TContext extends Record<string, any>> = Instrumentation$1<TContext> & Instrumentation$2 & FetchInstrumentation;
+
+interface QueryPlanOptions {
+    /** Callback when the query plan has been successfuly generated. */
+    onQueryPlan?(queryPlan: QueryPlan): void;
+    /** Exposing the query plan inside the GraphQL result extensions. */
+    expose?: boolean | ((request: Request) => boolean);
+}
+declare function useQueryPlan(opts?: QueryPlanOptions): GatewayPlugin;
+
+export { type QueryPlanOptions, unifiedGraphHandler, useQueryPlan };

package/dist/index.d.ts

@@ -1,5 +1,262 @@
-import { UnifiedGraphHandlerOpts, UnifiedGraphHandlerResult } from '@graphql-mesh/fusion-runtime';
+import { UnifiedGraphHandlerOpts, UnifiedGraphHandlerResult, UnifiedGraphPlugin, Instrumentation as Instrumentation$2 } from '@graphql-mesh/fusion-runtime';
+import { DisposableSymbols } from '@whatwg-node/disposablestack';
+import { MaybePromise } from '@whatwg-node/promise-helpers';
+import { Plugin, YogaInitialContext, Instrumentation as Instrumentation$1 } from 'graphql-yoga';
+import { MeshFetch, KeyValueCache, MeshFetchRequestInit, Logger as Logger$1 } from '@graphql-mesh/types';
+import { FetchInstrumentation } from '@graphql-mesh/utils';
+import { ExecutionRequest, MaybePromise as MaybePromise$1 } from '@graphql-tools/utils';
+import { GraphQLResolveInfo } from 'graphql/type';
+import { QueryPlan } from '@graphql-hive/router-query-planner';
 
 declare function unifiedGraphHandler(opts: UnifiedGraphHandlerOpts): UnifiedGraphHandlerResult;
 
-export { unifiedGraphHandler };
+type MaybeLazy<T> = T | (() => T);
+type AttributeValue = any;
+type Attributes = AttributeValue[] | {
+    [key: string | number]: AttributeValue;
+};
+
+interface LogWriter {
+    write(level: LogLevel, attrs: Attributes | null | undefined, msg: string | null | undefined): void | Promise<void>;
+    flush?(): void | Promise<void>;
+}
+
+type LogLevel = 'trace' | 'debug' | 'info' | 'warn' | 'error';
+interface LoggerOptions {
+    /**
+     * The minimum log level to log.
+     *
+     * Providing `false` will disable all logging.
+     *
+     * Provided function will always be invoked to get the current log level.
+     *
+     * @default env.LOG_LEVEL || env.DEBUG ? 'debug' : 'info'
+     */
+    level?: MaybeLazy<LogLevel | false>;
+    /** A prefix to include in every log's message. */
+    prefix?: string;
+    /**
+     * The attributes to include in all logs. Is mainly used to pass the parent
+     * attributes when creating {@link Logger.child child loggers}.
+     */
+    attrs?: Attributes;
+    /**
+     * The log writers to use when writing logs.
+     *
+     * @default env.LOG_JSON ? [new JSONLogWriter()] : [new ConsoleLogWriter()]
+     */
+    writers?: [LogWriter, ...LogWriter[]];
+}
+declare class Logger implements AsyncDisposable {
+    #private;
+    constructor(opts?: LoggerOptions);
+    /** The prefix that's prepended to each log message. */
+    get prefix(): string | undefined;
+    /**
+     * The attributes that are added to each log. If the log itself contains
+     * attributes with keys existing in {@link attrs}, the log's attributes will
+     * override.
+     */
+    get attrs(): Attributes | undefined;
+    /** The current {@link LogLevel} of the logger. You can change the level using the {@link setLevel} method. */
+    get level(): false | LogLevel;
+    /**
+     * Sets the new {@link LogLevel} of the logger. All subsequent logs, and {@link child child loggers} whose
+     * level did not change, will respect the new level.
+     */
+    setLevel(level: MaybeLazy<LogLevel | false>): void;
+    write(level: LogLevel, attrs: Attributes | null | undefined, msg: string | null | undefined): void;
+    flush(): Promise<void> | undefined;
+    [DisposableSymbols.asyncDispose](): Promise<void | undefined>;
+    child(prefix: string): Logger;
+    child(attrs: Attributes, prefix?: string): Logger;
+    log(level: LogLevel): void;
+    log(level: LogLevel, attrs: MaybeLazy<Attributes>): void;
+    log(level: LogLevel, msg: string, ...interpol: unknown[]): void;
+    log(level: LogLevel, attrs: MaybeLazy<Attributes>, msg: string, ...interpol: unknown[]): void;
+    trace(): void;
+    trace(attrs: MaybeLazy<Attributes>): void;
+    trace(msg: string, ...interpol: unknown[]): void;
+    trace(attrs: MaybeLazy<Attributes>, msg: string, ...interpol: unknown[]): void;
+    debug(): void;
+    debug(attrs: MaybeLazy<Attributes>): void;
+    debug(msg: string, ...interpol: unknown[]): void;
+    debug(attrs: MaybeLazy<Attributes>, msg: string, ...interpol: unknown[]): void;
+    info(): void;
+    info(attrs: MaybeLazy<Attributes>): void;
+    info(msg: string, ...interpol: unknown[]): void;
+    info(attrs: MaybeLazy<Attributes>, msg: string, ...interpol: unknown[]): void;
+    warn(): void;
+    warn(attrs: MaybeLazy<Attributes>): void;
+    warn(msg: string, ...interpol: unknown[]): void;
+    warn(attrs: MaybeLazy<Attributes>, msg: string, ...interpol: unknown[]): void;
+    error(): void;
+    error(attrs: MaybeLazy<Attributes>): void;
+    error(msg: string, ...interpol: unknown[]): void;
+    error(attrs: MaybeLazy<Attributes>, msg: string, ...interpol: unknown[]): void;
+}
+
+type TopicDataMap = {
+    [topic: string]: any;
+};
+type PubSubListener<Data extends TopicDataMap, Topic extends keyof Data> = (data: Data[Topic]) => void;
+interface PubSub<M extends TopicDataMap = TopicDataMap> {
+    /**
+     * Publish {@link data} for a {@link topic}.
+     * @returns `void` or a `Promise` that resolves when the data has been successfully published
+     */
+    publish<Topic extends keyof M>(topic: Topic, data: M[Topic]): MaybePromise<void>;
+    /**
+     * A distinct list of all topics that are currently subscribed to.
+     * Can be a promise to accomodate distributed systems where subscribers exist on other
+     * locations and we need to know about all of them.
+     */
+    subscribedTopics(): MaybePromise<Iterable<keyof M>>;
+    /**
+     * Subscribe and listen to a {@link topic} receiving its data.
+     *
+     * If the {@link listener} is provided, it will be called whenever data is emitted for the {@link topic},
+     *
+     * @returns an unsubscribe function or a `Promise<unsubscribe function>` that resolves when the subscription is successfully established. the unsubscribe function returns `void` or a `Promise` that resolves on successful unsubscribe and subscription cleanup
+     *
+     * If the {@link listener} is not provided,
+     *
+     * @returns an `AsyncIterable` that yields data for the given {@link topic}
+     */
+    subscribe<Topic extends keyof M>(topic: Topic): AsyncIterable<M[Topic]>;
+    subscribe<Topic extends keyof M>(topic: Topic, listener: PubSubListener<M, Topic>): MaybePromise<() => MaybePromise<void>>;
+    /**
+     * Closes active subscriptions and disposes of all resources. Publishing and subscribing after disposal
+     * is not possible and will throw an error if attempted.
+     */
+    dispose(): MaybePromise<void>;
+    /** @see {@link dispose} */
+    [DisposableSymbols.asyncDispose](): Promise<void>;
+}
+
+interface GatewayConfigContext {
+    /**
+     * WHATWG compatible Fetch implementation.
+     */
+    fetch: MeshFetch;
+    /**
+     * The logger to use throught Hive and its plugins.
+     */
+    log: Logger;
+    /**
+     * Current working directory.
+     * Note that working directory does not exist in serverless environments and will therefore be empty.
+     */
+    cwd: string;
+    /**
+     * Event bus for pub/sub.
+     */
+    pubsub?: PubSub;
+    /**
+     * Cache Storage
+     */
+    cache?: KeyValueCache;
+}
+interface GatewayContext extends GatewayConfigContext, YogaInitialContext {
+    /**
+     * Environment agnostic HTTP headers provided with the request.
+     */
+    headers: Record<string, string>;
+    /**
+     * Runtime context available within WebSocket connections.
+     */
+    connectionParams?: Record<string, string>;
+}
+type GatewayPlugin<TPluginContext extends Record<string, any> = Record<string, any>, TContext extends Record<string, any> = Record<string, any>> = Plugin<Partial<TPluginContext> & GatewayContext & TContext, GatewayConfigContext> & UnifiedGraphPlugin<Partial<TPluginContext> & GatewayContext & TContext> & {
+    onFetch?: OnFetchHook<Partial<TPluginContext> & TContext>;
+    onCacheGet?: OnCacheGetHook;
+    onCacheSet?: OnCacheSetHook;
+    onCacheDelete?: OnCacheDeleteHook;
+    /**
+     * An Instrumentation instance that will wrap each phases of the request pipeline.
+     * This should be used primarily as an observability tool (for monitoring, tracing, etc...).
+     *
+     * Note: The wrapped functions in instrumentation should always be called. Use hooks to
+     *       conditionally skip a phase.
+     */
+    instrumentation?: Instrumentation<TPluginContext & TContext & GatewayContext>;
+};
+interface OnFetchHookPayload<TContext> {
+    url: string;
+    setURL(url: URL | string): void;
+    options: MeshFetchRequestInit;
+    setOptions(options: MeshFetchRequestInit): void;
+    /**
+     * The context is not available in cases where "fetch" is done in
+     * order to pull a supergraph or do some internal work.
+     *
+     * The logger will be available in all cases.
+     */
+    context: (GatewayContext & TContext) | {
+        log: Logger;
+    };
+    /** @deprecated Please use `log` from the {@link context} instead. */
+    logger: Logger$1;
+    info: GraphQLResolveInfo;
+    fetchFn: MeshFetch;
+    setFetchFn: (fetchFn: MeshFetch) => void;
+    executionRequest?: ExecutionRequest;
+    endResponse: (response$: MaybePromise$1<Response>) => void;
+}
+interface OnFetchHookDonePayload {
+    response: Response;
+    setResponse: (response: Response) => void;
+}
+type OnFetchHookDone = (payload: OnFetchHookDonePayload) => MaybePromise$1<void>;
+type OnFetchHook<TContext> = (payload: OnFetchHookPayload<TContext>) => MaybePromise$1<void | OnFetchHookDone>;
+type OnCacheGetHook = (payload: OnCacheGetHookEventPayload) => MaybePromise$1<OnCacheGetHookResult | void>;
+interface OnCacheGetHookEventPayload {
+    cache: KeyValueCache;
+    key: string;
+    ttl?: number;
+}
+interface OnCacheGetHookResult {
+    onCacheHit?: OnCacheHitHook;
+    onCacheMiss?: OnCacheMissHook;
+    onCacheGetError?: OnCacheErrorHook;
+}
+type OnCacheErrorHook = (payload: OnCacheErrorHookPayload) => void;
+interface OnCacheErrorHookPayload {
+    error: Error;
+}
+type OnCacheHitHook = (payload: OnCacheHitHookEventPayload) => void;
+interface OnCacheHitHookEventPayload {
+    value: any;
+}
+type OnCacheMissHook = () => void;
+type OnCacheSetHook = (payload: OnCacheSetHookEventPayload) => MaybePromise$1<OnCacheSetHookResult | void>;
+interface OnCacheSetHookResult {
+    onCacheSetDone?: () => void;
+    onCacheSetError?: OnCacheErrorHook;
+}
+interface OnCacheSetHookEventPayload {
+    cache: KeyValueCache;
+    key: string;
+    value: any;
+    ttl?: number;
+}
+type OnCacheDeleteHook = (payload: OnCacheDeleteHookEventPayload) => MaybePromise$1<OnCacheDeleteHookResult | void>;
+interface OnCacheDeleteHookResult {
+    onCacheDeleteDone?: () => void;
+    onCacheDeleteError?: OnCacheErrorHook;
+}
+interface OnCacheDeleteHookEventPayload {
+    cache: KeyValueCache;
+    key: string;
+}
+type Instrumentation<TContext extends Record<string, any>> = Instrumentation$1<TContext> & Instrumentation$2 & FetchInstrumentation;
+
+interface QueryPlanOptions {
+    /** Callback when the query plan has been successfuly generated. */
+    onQueryPlan?(queryPlan: QueryPlan): void;
+    /** Exposing the query plan inside the GraphQL result extensions. */
+    expose?: boolean | ((request: Request) => boolean);
+}
+declare function useQueryPlan(opts?: QueryPlanOptions): GatewayPlugin;
+
+export { type QueryPlanOptions, unifiedGraphHandler, useQueryPlan };

package/dist/index.js

@@ -1069,6 +1069,7 @@ function projectRequires(requiresSelections, entity, supergraphSchema) {
   return result;
 }
 
+const queryPlanForExecutionRequestContext = /* @__PURE__ */ new WeakMap();
 function getLazyValue(factory) {
   let _value;
   return function() {
@@ -1139,52 +1140,59 @@ function unifiedGraphHandler(opts) {
           executionRequest.document,
           executionRequest.operationName || null
         ),
-        (queryPlan) => executeQueryPlan({
-          supergraphSchema,
-          executionRequest,
-          onSubgraphExecute(subgraphName, executionRequest2) {
-            const subschema = getSubschema(subgraphName);
-            if (subschema.transforms?.length) {
-              const transforms = subschema.transforms;
-              const transformationContext = /* @__PURE__ */ Object.create(null);
-              for (const transform of transforms) {
-                if (transform.transformRequest) {
-                  executionRequest2 = transform.transformRequest(
-                    executionRequest2,
-                    void 0,
-                    transformationContext
-                  );
+        (queryPlan) => {
+          queryPlanForExecutionRequestContext.set(
+            // setter like getter
+            executionRequest.context || executionRequest.document,
+            queryPlan
+          );
+          return executeQueryPlan({
+            supergraphSchema,
+            executionRequest,
+            onSubgraphExecute(subgraphName, executionRequest2) {
+              const subschema = getSubschema(subgraphName);
+              if (subschema.transforms?.length) {
+                const transforms = subschema.transforms;
+                const transformationContext = /* @__PURE__ */ Object.create(null);
+                for (const transform of transforms) {
+                  if (transform.transformRequest) {
+                    executionRequest2 = transform.transformRequest(
+                      executionRequest2,
+                      void 0,
+                      transformationContext
+                    );
+                  }
                 }
-              }
-              return handleMaybePromise(
-                () => opts.onSubgraphExecute(subgraphName, executionRequest2),
-                (executionResult) => {
-                  function handleResult(executionResult2) {
-                    for (const transform of transforms.toReversed()) {
-                      if (transform.transformResult) {
-                        executionResult2 = transform.transformResult(
-                          executionResult2,
-                          void 0,
-                          transformationContext
-                        );
+                return handleMaybePromise(
+                  () => opts.onSubgraphExecute(subgraphName, executionRequest2),
+                  (executionResult) => {
+                    function handleResult(executionResult2) {
+                      for (const transform of transforms.toReversed()) {
+                        if (transform.transformResult) {
+                          executionResult2 = transform.transformResult(
+                            executionResult2,
+                            void 0,
+                            transformationContext
+                          );
+                        }
                       }
+                      return executionResult2;
                     }
-                    return executionResult2;
-                  }
-                  if (isAsyncIterable(executionResult)) {
-                    return mapAsyncIterator(
-                      executionResult,
-                      (result) => handleResult(result)
-                    );
+                    if (isAsyncIterable(executionResult)) {
+                      return mapAsyncIterator(
+                        executionResult,
+                        (result) => handleResult(result)
+                      );
+                    }
+                    return handleResult(executionResult);
                   }
-                  return handleResult(executionResult);
-                }
-              );
-            }
-            return opts.onSubgraphExecute(subgraphName, executionRequest2);
-          },
-          queryPlan
-        })
+                );
+              }
+              return opts.onSubgraphExecute(subgraphName, executionRequest2);
+            },
+            queryPlan
+          });
+        }
       );
     }
   };
@@ -1213,4 +1221,31 @@ function isIntrospection(document) {
   return containsIntrospectionField || onlyQueryTypenameFields;
 }
 
-export { unifiedGraphHandler };
+function useQueryPlan(opts = {}) {
+  const { expose, onQueryPlan } = opts;
+  return {
+    onExecute({ context, args }) {
+      return {
+        onExecuteDone({ result, setResult }) {
+          const queryPlan = queryPlanForExecutionRequestContext.get(
+            // getter like setter
+            context || args.document
+          );
+          onQueryPlan?.(queryPlan);
+          const shouldExpose = typeof expose === "function" ? expose(context.request) : expose;
+          if (shouldExpose && !isAsyncIterable(result)) {
+            setResult({
+              ...result,
+              extensions: {
+                ...result.extensions,
+                queryPlan
+              }
+            });
+          }
+        }
+      };
+    }
+  };
+}
+
+export { unifiedGraphHandler, useQueryPlan };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@graphql-hive/router-runtime",
-  "version": "1.1.0-rc-924ffb15d84292a020a45655046fd359ea9f02d5",
+  "version": "1.1.0-rc-aa2a330ec509cf750e8722741cb18aed3ad01793",
   "type": "module",
   "repository": {
     "type": "git",
@@ -44,11 +44,11 @@
   "dependencies": {
     "@envelop/core": "^5.4.0",
     "@graphql-hive/router-query-planner": "^0.0.6",
-    "@graphql-mesh/fusion-runtime": "1.6.0-rc-924ffb15d84292a020a45655046fd359ea9f02d5",
+    "@graphql-mesh/fusion-runtime": "1.6.0-rc-aa2a330ec509cf750e8722741cb18aed3ad01793",
     "@graphql-mesh/transport-common": "^1.0.12",
     "@graphql-tools/executor": "^1.4.13",
     "@graphql-tools/executor-common": "^1.0.5",
-    "@graphql-tools/federation": "4.2.4-rc-924ffb15d84292a020a45655046fd359ea9f02d5",
+    "@graphql-tools/federation": "4.2.4-rc-aa2a330ec509cf750e8722741cb18aed3ad01793",
     "@graphql-tools/utils": "^10.10.3",
     "@whatwg-node/promise-helpers": "^1.3.2"
   },