@graphql-tools/federation/dist/index.d.ts

Useful tools to create and manipulate GraphQL schemas.

import { GatewayInterface, GatewayApolloConfig, GatewayLoadResult, GatewaySchemaLoadOrUpdateCallback } from '@apollo/server-gateway-interface';
import { HTTPExecutorOptions, FetchFn } from '@graphql-tools/executor-http';
import { TypedEventTarget } from '@graphql-yoga/typed-event-target';
import { DisposableSymbols } from '@whatwg-node/disposablestack';
import * as graphql from 'graphql';
import { DocumentNode, GraphQLSchema, SelectionSetNode, TypeNode } from 'graphql';
import { SubschemaConfig, MergedTypeConfig, BatchingOptions } from '@graphql-tools/delegate';
import { ValidationLevel, MergeFieldConfigCandidate } from '@graphql-tools/stitch';
import { Executor } from '@graphql-tools/utils';

declare function ensureSupergraphSDLAst(supergraphSdl: string | DocumentNode): DocumentNode;
interface FederationSubschemaConfig extends Omit<SubschemaConfig, 'executor' | 'name'> {
    executor: Executor;
    name: string;
    endpoint: string;
}
interface GetStitchingOptionsFromSupergraphSdlOpts {
    supergraphSdl: string | DocumentNode;
    httpExecutorOpts?: Partial<HTTPExecutorOptions> | ((subgraphInfo: {
        name: string;
        endpoint?: string;
    }) => Partial<HTTPExecutorOptions>);
    onSubschemaConfig?: (subschemaConfig: FederationSubschemaConfig) => void;
    onMergedTypeConfig?: (typeName: string, mergedTypeConfig: MergedTypeConfig) => void;
    onSubgraphAST?: (name: string, subgraphAST: DocumentNode) => DocumentNode;
    /**
     * Enable query batching for all subschemas.
     *
     * @default false
     */
    batch?: boolean;
    /**
     * Configure the query batching options for all subschemas.
     */
    batchingOptions?: BatchingOptions;
    /**
     * Configure the batch delegation options for all merged types in all subschemas.
     */
    batchDelegateOptions?: MergedTypeConfig['dataLoaderOptions'];
}
declare function getStitchingOptionsFromSupergraphSdl(opts: GetStitchingOptionsFromSupergraphSdlOpts): {
    subschemas: SubschemaConfig<any, any, any, Record<string, any>>[];
    typeDefs: DocumentNode;
    assumeValid: boolean;
    assumeValidSDL: boolean;
    typeMergingOptions: {
        useNonNullableFieldOnConflict: boolean;
        validationSettings: {
            validationLevel: ValidationLevel;
        };
        fieldConfigMerger: (candidates: MergeFieldConfigCandidate<Record<string, any>>[]) => graphql.GraphQLFieldConfig<any, Record<string, any>, any>;
    };
};
interface GetStitchedSchemaFromSupergraphSdlOpts extends GetStitchingOptionsFromSupergraphSdlOpts {
    supergraphSdl: string | DocumentNode;
    onStitchingOptions?(opts: ReturnType<typeof getStitchingOptionsFromSupergraphSdl>): void;
    onStitchedSchema?(schema: GraphQLSchema): GraphQLSchema | void;
}
declare function getStitchedSchemaFromSupergraphSdl(opts: GetStitchedSchemaFromSupergraphSdlOpts): GraphQLSchema;

type FetchSupergraphSdlFromManagedFederationOpts = {
    /**
     * The graph ref of the managed federation graph.
     * It is composed of the graph ID and the variant (`<YOUR_GRAPH_ID>@<VARIANT>`).
     *
     * If not provided, `APOLLO_GRAPH_REF` environment variable is used.
     *
     * You can find a a graph's ref at the top of its Schema Reference page in Apollo Studio.
     */
    graphRef?: string;
    /**
     * The API key to use to authenticate with the managed federation up link.
     * It needs at least the `service:read` permission.
     *
     * If not provided, `APOLLO_KEY` environment variable will be used instead.
     *
     * [Learn how to create an API key](https://www.apollographql.com/docs/federation/v1/managed-federation/setup#4-connect-the-gateway-to-studio)
     */
    apiKey?: string;
    /**
     * The URL of the managed federation up link. When retrying after a failure, you should cycle through the default up links using this option.
     *
     * Uplinks are available in `DEFAULT_UPLINKS` constant.
     *
     * This options can also be defined using the `APOLLO_SCHEMA_CONFIG_DELIVERY_ENDPOINT` environment variable.
     * It should be a comma separated list of up links, but only the first one will be used.
     *
     * Default: 'https://uplink.api.apollographql.com/' (Apollo's managed federation up link on GCP)
     *
     * Alternative: 'https://aws.uplink.api.apollographql.com/' (Apollo's managed federation up link on AWS)
     */
    upLink?: string;
    /**
     * The ID of the last fetched supergraph.
     * If provided, a supergraph is returned only if the managed supergraph have changed.
     */
    lastSeenId?: string;
    /**
     * The fetch implementation to use.
     * Default: global.fetch
     */
    fetch?: FetchFn;
    /**
     * Up link can send back messages meant to be logged alongside the supergraph SDL.
     * By default, the console is used.
     */
    loggerByMessageLevel?: typeof DEFAULT_MESSAGE_LOGGER;
};
type RouterConfig = {
    /**
     * The supergraph SDL.
     */
    supergraphSdl: string;
    /**
     * The minimum delay in seconds to wait before trying to fetch this supergraph again.
     */
    minDelaySeconds: number;
    /**
     * The ID of the supergraph. Should be used as `lastSeenId` in the next fetch.
     */
    id: string;
};
type Unchanged = {
    /**
     * The minimum delay in seconds to wait before trying to fetch this supergraph again.
     */
    minDelaySeconds: number;
    /**
     * The ID of the supergraph. Should be used as `lastSeenId` in the next fetch.
     */
    id: string;
};
type FetchError = {
    /**
     * The fetch error reported by the up link. This means it's not the local fetch error.
     * Local fetch errors are thrown as exceptions.
     */
    error: {
        code: string;
        message: string;
    };
    /**
     * The minimum delay in seconds to wait before trying to fetch this supergraph again.
     */
    minDelaySeconds: number;
};
/**
 * The default managed federation up links. In case of failure, you should try to cycle through these up links.
 *
 * The first one is Apollo's managed federation up link on GCP, the second one is on AWS.
 */
declare const DEFAULT_UPLINKS: string[];
/**
 * Fetches the supergraph SDL from a managed federation GraphOS up link.
 * @param options
 * @throws When the fetch fails or the response is not a valid.
 * @returns An object with the supergraph SDL when possible. It also includes metadata to handle polling and retry logic.
 *
 *          If `lastSeenId` is provided and the supergraph has not changed, `supergraphSdl` is not present.
 *
 *          If The up link report a fetch error (which is not a local fetch error), it will be returned along with polling/retry metadata.
 *          Any local fetch error will be thrown as an exception.
 */
declare function fetchSupergraphSdlFromManagedFederation(options?: FetchSupergraphSdlFromManagedFederationOpts): Promise<RouterConfig | Unchanged | FetchError>;
type GetStitchedSchemaFromManagedFederationOpts = FetchSupergraphSdlFromManagedFederationOpts & Omit<GetStitchedSchemaFromSupergraphSdlOpts, 'supergraphSdl'>;
type RouterConfigWithSchema = RouterConfig & {
    /**
     * The stitched schema based on the supergraph SDL.
     */
    schema: GraphQLSchema;
};
/**
 * Fetches the supergraph SDL from a managed federation GraphOS up link and stitches it into an executable schema.
 * @param options
 * @throws When the fetch fails, the response is not a valid or the stitching fails.
 * @returns An object with the supergraph SDL and the stitched schema when possible. It also includes metadata to handle polling and retry logic.
 *
 *          If `lastSeenId` is provided and the supergraph has not changed, `supergraphSdl` is not present.
 *
 *          If The up link report a fetch error (which is not a local fetch error), it will be returned along with polling/retry metadata.
 *          Any local fetch error will be thrown as an exception.
 */
declare function getStitchedSchemaFromManagedFederation(options: GetStitchedSchemaFromManagedFederationOpts): Promise<RouterConfigWithSchema | FetchError | Unchanged>;
declare const DEFAULT_MESSAGE_LOGGER: {
    ERROR: (message: string) => void;
    WARN: (message: string) => void;
    INFO: (message: string) => void;
};
type SupergraphSchemaManagerOptions = Omit<GetStitchedSchemaFromManagedFederationOpts, 'lastSeenId'> & {
    maxRetries?: number;
    minDelaySeconds?: number;
    retryDelaySeconds?: number;
};
type SupergraphSchemaManagerSchemaEvent = CustomEvent<{
    schema: GraphQLSchema;
    supergraphSdl: string;
}>;
type SupergraphSchemaManagerErrorEvent = CustomEvent<FetchError | Error>;
type SupergraphSchemaManagerFailureEvent = CustomEvent<{
    error: FetchError['error'] | Error;
    delayInSeconds: number;
}>;
type SupergraphSchemaManagerLogEvent = CustomEvent<{
    source: 'uplink' | 'manager';
    message: string;
    level: 'error' | 'warn' | 'info';
}>;
type SupergraphSchemaManagerEvent = SupergraphSchemaManagerSchemaEvent | SupergraphSchemaManagerErrorEvent | SupergraphSchemaManagerFailureEvent | SupergraphSchemaManagerLogEvent;
declare const TypedEventTargetCtor: new <TEvent extends CustomEvent>() => TypedEventTarget<TEvent>;
declare class SupergraphSchemaManager extends TypedEventTargetCtor<SupergraphSchemaManagerEvent> implements GatewayInterface {
    #private;
    private options;
    schema?: GraphQLSchema;
    constructor(options?: SupergraphSchemaManagerOptions);
    load: (options: {
        apollo: GatewayApolloConfig;
    }) => Promise<GatewayLoadResult>;
    onSchemaLoadOrUpdate: (callback: GatewaySchemaLoadOrUpdateCallback) => () => void;
    start: (delayInSeconds?: number) => void;
    forcePull: () => void;
    stop: () => Promise<void>;
    [DisposableSymbols.dispose](): Promise<void>;
}

declare const getArgsFromKeysForFederation: (representations: readonly any[]) => {
    representations: readonly any[];
};
declare function projectDataSelectionSet(data: any, selectionSet?: SelectionSetNode): any;
declare function getKeyFnForFederation(typeName: string, keys: string[]): (root: any) => any;
declare function getCacheKeyFnFromKey(key: string): (root: any) => any;
declare function filterInternalFieldsAndTypes(finalSchema: GraphQLSchema): GraphQLSchema;
declare function getNamedTypeNode(typeNode: TypeNode): graphql.NamedTypeNode;

export { DEFAULT_UPLINKS, type FederationSubschemaConfig, type FetchError, type FetchSupergraphSdlFromManagedFederationOpts, type GetStitchedSchemaFromManagedFederationOpts, type GetStitchedSchemaFromSupergraphSdlOpts, type GetStitchingOptionsFromSupergraphSdlOpts, type RouterConfig, type RouterConfigWithSchema, SupergraphSchemaManager, type SupergraphSchemaManagerErrorEvent, type SupergraphSchemaManagerEvent, type SupergraphSchemaManagerFailureEvent, type SupergraphSchemaManagerLogEvent, type SupergraphSchemaManagerOptions, type SupergraphSchemaManagerSchemaEvent, type Unchanged, ensureSupergraphSDLAst, fetchSupergraphSdlFromManagedFederation, filterInternalFieldsAndTypes, getArgsFromKeysForFederation, getCacheKeyFnFromKey, getKeyFnForFederation, getNamedTypeNode, getStitchedSchemaFromManagedFederation, getStitchedSchemaFromSupergraphSdl, getStitchingOptionsFromSupergraphSdl, projectDataSelectionSet };