Rename introspectSchema to schemaFromExecutor

.changeset/early-lemons-change.md

@@ -0,0 +1,6 @@
+---
+'@graphql-tools/url-loader': minor
+'@graphql-tools/wrap': minor
+---
+
+Deprecate \`introspectSchema\` in favor of the new \`schemaFromExecutor\`

packages/loaders/url/src/index.ts

@@ -11,7 +11,7 @@ import {
   parseGraphQLSDL,
   getOperationASTFromRequest,
 } from '@graphql-tools/utils';
-import { introspectSchema, wrapSchema } from '@graphql-tools/wrap';
+import { schemaFromExecutor, wrapSchema } from '@graphql-tools/wrap';
 import WebSocket from 'isomorphic-ws';
 import { ValueOrPromise } from 'value-or-promise';
 import { defaultAsyncFetch } from './defaultAsyncFetch.js';
@@ -360,7 +360,7 @@ export class UrlLoader implements Loader<LoadFromUrlOptions> {
           : undefined);
     } else {
       executor = this.getExecutorAsync(pointer, options);
-      source.schema = await introspectSchema(executor, {}, options);
+      source.schema = await schemaFromExecutor(executor, {}, options);
     }
 
     if (!source.schema) {
@@ -406,7 +406,7 @@ export class UrlLoader implements Loader<LoadFromUrlOptions> {
           : undefined);
     } else {
       executor = this.getExecutorSync(pointer, options);
-      source.schema = introspectSchema(executor, {}, options);
+      source.schema = schemaFromExecutor(executor, {}, options);
     }
 
     if (!source.schema) {

packages/testing/fixtures/schemas.ts

@@ -1,7 +1,7 @@
 import { PubSub } from 'graphql-subscriptions';
 import { GraphQLSchema, Kind, GraphQLScalarType, ValueNode, GraphQLResolveInfo, GraphQLInterfaceType } from 'graphql';
 
-import { introspectSchema } from '@graphql-tools/wrap';
+import { schemaFromExecutor } from '@graphql-tools/wrap';
 import { AsyncExecutor, createGraphQLError, IResolvers } from '@graphql-tools/utils';
 import { makeExecutableSchema } from '@graphql-tools/schema';
 
@@ -648,7 +648,7 @@ export const subscriptionSchema: GraphQLSchema = makeExecutableSchema({
 
 export async function makeSchemaRemote(schema: GraphQLSchema): Promise<SubschemaConfig> {
   const executor = createDefaultExecutor(schema);
-  const clientSchema = await introspectSchema(executor as AsyncExecutor);
+  const clientSchema = await schemaFromExecutor(executor as AsyncExecutor);
   return {
     schema: clientSchema,
     executor,

packages/wrap/CHANGELOG.md

@@ -194,7 +194,7 @@
 
 ### Minor Changes
 
-- [#4703](https://github.com/ardatan/graphql-tools/pull/4703) [`dd8886d1`](https://github.com/ardatan/graphql-tools/commit/dd8886d1534fdf73b7cfb6d54b13a3db5812b38b) Thanks [@ardatan](https://github.com/ardatan)! - Better error handling for introspectSchema
+- [#4703](https://github.com/ardatan/graphql-tools/pull/4703) [`dd8886d1`](https://github.com/ardatan/graphql-tools/commit/dd8886d1534fdf73b7cfb6d54b13a3db5812b38b) Thanks [@ardatan](https://github.com/ardatan)! - Better error handling for schemaFromExecutor
 
 ## 9.0.6
 
@@ -757,7 +757,7 @@
   for (const error of aggregateError.errors)
   ```
 - c0ca3190: BREAKING CHANGE
-  - Remove unnecessary `introspectSchemaSync`, `introspectSchema` already handles sync execution
+  - Remove unnecessary `introspectSchemaSync`, `schemaFromExecutor` already handles sync execution
 - 74581cf3: fix(getDirectives): preserve order around repeatable directives
 
   BREAKING CHANGE: getDirectives now always return an array of individual DirectiveAnnotation objects consisting of `name` and `args` properties.
@@ -839,7 +839,7 @@
 
 ### Patch Changes
 
-- 4240a959: enhance(wrap): use introspectSchema for both sync and async executors
+- 4240a959: enhance(wrap): use schemaFromExecutor for both sync and async executors
 - Updated dependencies [4240a959]
   - @graphql-tools/utils@7.1.4
 

packages/wrap/src/introspect.ts

@@ -19,6 +19,7 @@ import {
   AggregateError,
   createGraphQLError,
   inspect,
+  MaybePromise,
 } from '@graphql-tools/utils';
 
 function getSchemaFromIntrospection(
@@ -41,21 +42,32 @@ function getSchemaFromIntrospection(
   );
 }
 
-export function introspectSchema(
+export type SchemaFromExecutorOptions = Partial<IntrospectionOptions> &
+  Parameters<typeof buildClientSchema>[1] &
+  ParseOptions;
+
+export const introspectSchema = function introspectSchema(...args) {
+  console.warn(
+    `\`introspectSchema\` is deprecated, and will be removed in the next major. Please use \`schemaFromExecutor\` instead.`
+  );
+  return schemaFromExecutor(...(args as Parameters<typeof schemaFromExecutor>));
+} as typeof schemaFromExecutor;
+
+export function schemaFromExecutor(
   executor: SyncExecutor,
   context?: Record<string, any>,
-  options?: Partial<IntrospectionOptions> & Parameters<typeof buildClientSchema>[1] & ParseOptions
+  options?: SchemaFromExecutorOptions
 ): GraphQLSchema;
-export function introspectSchema(
+export function schemaFromExecutor(
   executor: AsyncExecutor,
   context?: Record<string, any>,
-  options?: Partial<IntrospectionOptions> & Parameters<typeof buildClientSchema>[1] & ParseOptions
+  options?: SchemaFromExecutorOptions
 ): Promise<GraphQLSchema>;
-export function introspectSchema(
+export function schemaFromExecutor(
   executor: Executor,
   context?: Record<string, any>,
-  options?: Partial<IntrospectionOptions> & Parameters<typeof buildClientSchema>[1] & ParseOptions
-): Promise<GraphQLSchema> | GraphQLSchema {
+  options?: SchemaFromExecutorOptions
+): MaybePromise<GraphQLSchema> {
   const parsedIntrospectionQuery = parse(getIntrospectionQuery(options as any), options);
   return new ValueOrPromise(() =>
     executor({

website/algolia-lockfile.json

@@ -527,7 +527,7 @@
                 "anchor": "wrapschemaschemaconfig"
               }
             ],
-            "title": "`introspectSchema(executor, [context])`",
+            "title": "`schemaFromExecutor(executor, [context])`",
             "anchor": "introspectschemaexecutor-context"
           }
         ],

website/src/pages/docs/remote-schemas.mdx

@@ -26,14 +26,14 @@ Check out [Schema Loading](/docs/schema-loading) to load schemas from an URL and
 Generally, to create a remote schema, you generally need just three steps:
 
 1. Create an [executor](#creating-an-executor) that can retrieve results from that schema
-2. Use [`introspectSchema`](#introspectschemaexecutor-context) to get the non-executable schema of the remote server
+2. Use [`schemaFromExecutor`](#introspectschemaexecutor-context) to get the non-executable schema of the remote server
 3. Use [`wrapSchema`](#wrapschemaschemaconfig) to create a schema that uses the executor to delegate requests to the underlying service
 
 ### Creating an Executor
 
 You can use an executor with an HTTP Client implementation (like cross-fetch). An executor is a function capable of retrieving GraphQL results. It is the same way that a GraphQL Client handles fetching data and is used by several `graphql-tools` features to do introspection or fetch results during execution.
 
-We've chosen to split this functionality up to give you the flexibility to choose when to do the introspection step. For example, you might already have the remote schema information, allowing you to skip the `introspectSchema` step entirely. Here's a complete example:
+We've chosen to split this functionality up to give you the flexibility to choose when to do the introspection step. For example, you might already have the remote schema information, allowing you to skip the `schemaFromExecutor` step entirely. Here's a complete example:
 
 ```ts
 type Executor = (request: Request) => Promise<ExecutionResult>
@@ -53,7 +53,7 @@ Basic usage
 ```js
 import { fetch } from '@whatwg-node/fetch'
 import { print } from 'graphql'
-import { introspectSchema, wrapSchema } from '@graphql-tools/wrap'
+import { schemaFromExecutor, wrapSchema } from '@graphql-tools/wrap'
 import { AsyncExecutor } from '@graphql-tools/utils'
 
 const executor: AsyncExecutor = async ({ document, variables }) => {
@@ -70,7 +70,7 @@ const executor: AsyncExecutor = async ({ document, variables }) => {
 
 export default async () => {
   const schema = wrapSchema({
-    schema: await introspectSchema(executor),
+    schema: await schemaFromExecutor(executor),
     executor
   })
   return schema
@@ -82,7 +82,7 @@ Authentication headers from the context
 ```js
 import { fetch } from '@whatwg-node/fetch'
 import { print } from 'graphql'
-import { introspectSchema, wrapSchema } from '@graphql-tools/wrap'
+import { schemaFromExecutor, wrapSchema } from '@graphql-tools/wrap'
 import { AsyncExecutor } from '@graphql-tools/utils'
 
 const executor: AsyncExecutor = async ({ document, variables, context }) => {
@@ -100,7 +100,7 @@ const executor: AsyncExecutor = async ({ document, variables, context }) => {
 
 export default async () => {
   const schema = wrapSchema({
-    schema: await introspectSchema(executor),
+    schema: await schemaFromExecutor(executor),
     executor
   })
 
@@ -119,7 +119,7 @@ For the following example to work, the server must implement the [library's tran
 With this executor, all operations (query, mutation and subscription) will be executed over `graphql-ws`.
 
 ```ts
-import { wrapSchema, introspectSchema } from '@graphql-tools/wrap'
+import { wrapSchema, schemaFromExecutor } from '@graphql-tools/wrap'
 import { observableToAsyncIterable, AsyncExecutor } from '@graphql-tools/utils'
 import { createClient } from 'graphql-ws'
 import { print } from 'graphql'
@@ -159,7 +159,7 @@ const executor: AsyncExecutor = async ({ document, variables }) =>
 
 export default async () => {
   const schema = wrapSchema({
-    schema: await introspectSchema(executor),
+    schema: await schemaFromExecutor(executor),
     executor
   })
 
@@ -174,7 +174,7 @@ For the following example to work, the server must implement the [GraphQL over S
 With this executor, all operations (query, mutation and subscription) will be executed over `graphql-sse`.
 
 ```ts
-import { wrapSchema, introspectSchema } from '@graphql-tools/wrap'
+import { wrapSchema, schemaFromExecutor } from '@graphql-tools/wrap'
 import { AsyncExecutor } from '@graphql-tools/utils'
 import { fetch, AbortController } from '@whatwg-node/fetch'
 import { observableToAsyncIterable } from '@graphql-tools/utils'
@@ -221,7 +221,7 @@ const executor: AsyncExecutor = async ({ document, variables, operationName, ext
 
 export default async () => {
   const schema = wrapSchema({
-    schema: await introspectSchema(executor),
+    schema: await schemaFromExecutor(executor),
     executor
   })
 
@@ -236,7 +236,7 @@ Sometimes you only want to do subscription operations over WebSocket. In that ca
 With this executor query and mutation operations will be executed over HTTP (using `@whatwg-node/fetch`) and subscription operations will be executed via WebSocket (using `graphql-ws`).
 
 ```ts
-import { wrapSchema, introspectSchema } from '@graphql-tools/wrap'
+import { wrapSchema, schemaFromExecutor } from '@graphql-tools/wrap'
 import { fetch } from '@whatwg-node/fetch'
 import { print, getOperationAST, OperationTypeNode } from 'graphql'
 import { observableToAsyncIterable, AsyncExecutor } from '@graphql-tools/utils'
@@ -303,7 +303,7 @@ const executor: AsyncExecutor = async args => {
 
 export default async () => {
   const schema = wrapSchema({
-    schema: await introspectSchema(executor),
+    schema: await schemaFromExecutor(executor),
     executor
   })
 
@@ -313,19 +313,19 @@ export default async () => {
 
 ## API
 
-### `introspectSchema(executor, [context])`
+### `schemaFromExecutor(executor, [context])`
 
-Use `executor` to obtain a non-executable client schema from a remote schema using a full introspection query. `introspectSchema` is used to acquire the non-executable form of a remote schema that must be passed to `wrapSchema`. It returns a promise to a non-executable GraphQL.js schema object. Accepts optional second argument `context`, which is passed to the executor; see the docs about executors above for more details.
+Use `executor` to obtain a non-executable client schema from a remote schema using a full introspection query. `schemaFromExecutor` is used to acquire the non-executable form of a remote schema that must be passed to `wrapSchema`. It returns a promise to a non-executable GraphQL.js schema object. Accepts optional second argument `context`, which is passed to the executor; see the docs about executors above for more details.
 
 ```js
-import { introspectSchema } from '@graphql-tools/wrap'
+import { schemaFromExecutor } from '@graphql-tools/wrap'
 
-introspectSchema(executor).then(schema => {
+schemaFromExecutor(executor).then(schema => {
   // use the schema
 })
 
 // or with async/await:
-const schema = await introspectSchema(executor)
+const schema = await schemaFromExecutor(executor)
 ```
 
 ### `wrapSchema(schemaConfig)`

website/src/pages/docs/schema-stitching/stitch-combining-schemas.mdx

@@ -105,7 +105,7 @@ Also note that these subschema config objects may need to be referenced again in
 To include a remote schema in the combined gateway, you must provide at least the `schema` and `executor` subschema config options.
 
 ```js
-import { introspectSchema } from '@graphql-tools/wrap'
+import { schemaFromExecutor } from '@graphql-tools/wrap'
 import { fetch } from '@whatwg-node/fetch'
 import { print } from 'graphql'
 
@@ -120,7 +120,7 @@ async function remoteExecutor({ document, variables }) {
 }
 
 export const postsSubschema = {
-  schema: await introspectSchema(remoteExecutor),
+  schema: await schemaFromExecutor(remoteExecutor),
   executor: remoteExecutor
 }
 ```