From 6e30fc90a6f7bd630af6096fe7a63de397c87d1f Mon Sep 17 00:00:00 2001 From: Jovi De Croock Date: Thu, 10 Apr 2025 04:45:31 +0200 Subject: [PATCH 1/3] Update docs for execution options --- website/pages/api-v16/execution.mdx | 100 +++++++++++++++++++++++----- 1 file changed, 84 insertions(+), 16 deletions(-) diff --git a/website/pages/api-v16/execution.mdx b/website/pages/api-v16/execution.mdx index 2810ed183a..e3a872c40a 100644 --- a/website/pages/api-v16/execution.mdx +++ b/website/pages/api-v16/execution.mdx @@ -29,14 +29,28 @@ const { execute } = require('graphql'); // CommonJS ### execute ```ts -export function execute( - schema: GraphQLSchema, - documentAST: Document, - rootValue?: mixed, - contextValue?: mixed, - variableValues?: { [key: string]: mixed }, - operationName?: string, -): MaybePromise; +export function execute({ + schema, + documentAST, + rootValue, + contextValue, + variableValues, + operationName, + options, +}: ExecutionParams): MaybePromise; + +type ExecutionParams = { + schema: GraphQLSchema; + document: Document; + rootValue?: unknown; + contextValue?: unknown; + variableValues?: Record; + operationName?: string; + options?: { + /** Set the maximum number of errors allowed for coercing (defaults to 50). */ + maxCoercionErrors?: number; + } +}; type MaybePromise = Promise | T; @@ -50,6 +64,20 @@ interface ExecutionResult< } ``` +We have another approach with positional arguments, this is however deprecated and set +to be removed in v17. + +```ts +export function execute( + schema: GraphQLSchema, + documentAST: Document, + rootValue?: mixed, + contextValue?: mixed, + variableValues?: { [key: string]: mixed }, + operationName?: string, +): MaybePromise; +``` + Implements the "Evaluating requests" section of the GraphQL specification. Returns a Promise that will eventually be resolved and never rejected. @@ -63,6 +91,49 @@ non-empty array if an error occurred. ### executeSync +This is a short-hand method that will call `execute` and when the response can +be returned synchronously it will be returned, when a `Promise` is returned this +method will throw an error. + +```ts +export function executeSync({ + schema, + documentAST, + rootValue, + contextValue, + variableValues, + operationName, + options, +}: ExecutionParams): MaybePromise; + +type ExecutionParams = { + schema: GraphQLSchema; + document: Document; + rootValue?: unknown; + contextValue?: unknown; + variableValues?: Record; + operationName?: string; + options?: { + /** Set the maximum number of errors allowed for coercing (defaults to 50). */ + maxCoercionErrors?: number; + } +}; + +type MaybePromise = Promise | T; + +interface ExecutionResult< + TData = ObjMap, + TExtensions = ObjMap, +> { + errors?: ReadonlyArray; + data?: TData | null; + extensions?: TExtensions; +} +``` + +We have another approach with positional arguments, this is however deprecated and set +to be removed in v17. + ```ts export function executeSync( schema: GraphQLSchema, @@ -72,13 +143,10 @@ export function executeSync( variableValues?: { [key: string]: mixed }, operationName?: string, ): ExecutionResult; - -type ExecutionResult = { - data: Object; - errors?: GraphQLError[]; -}; ``` -This is a short-hand method that will call `execute` and when the response can -be returned synchronously it will be returned, when a `Promise` is returned this -method will throw an error. +#### Execution options + +##### maxCoercionErrors + +Set the maximum number of errors allowed for coercing variables, this implements a default limit of 50 errors. From fb1f3d3efcacf058d457270f378df4b9ebad9bf1 Mon Sep 17 00:00:00 2001 From: Jovi De Croock Date: Thu, 10 Apr 2025 04:47:28 +0200 Subject: [PATCH 2/3] Remove mentions of mixed --- website/pages/api-v16/error.mdx | 2 +- website/pages/api-v16/execution.mdx | 12 ++++++------ 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/website/pages/api-v16/error.mdx b/website/pages/api-v16/error.mdx index 1338d321de..09f5e746a6 100644 --- a/website/pages/api-v16/error.mdx +++ b/website/pages/api-v16/error.mdx @@ -56,7 +56,7 @@ class GraphQLError extends Error { source?: Source, positions?: number[], originalError?: Error, - extensions?: { [key: string]: mixed }, + extensions?: Record, ); } ``` diff --git a/website/pages/api-v16/execution.mdx b/website/pages/api-v16/execution.mdx index e3a872c40a..4f3fdc9ae1 100644 --- a/website/pages/api-v16/execution.mdx +++ b/website/pages/api-v16/execution.mdx @@ -71,9 +71,9 @@ to be removed in v17. export function execute( schema: GraphQLSchema, documentAST: Document, - rootValue?: mixed, - contextValue?: mixed, - variableValues?: { [key: string]: mixed }, + rootValue?: unknown, + contextValue?: unknown, + variableValues?: Record, operationName?: string, ): MaybePromise; ``` @@ -138,9 +138,9 @@ to be removed in v17. export function executeSync( schema: GraphQLSchema, documentAST: Document, - rootValue?: mixed, - contextValue?: mixed, - variableValues?: { [key: string]: mixed }, + rootValue?: unknown, + contextValue?: unknown, + variableValues?: Record, operationName?: string, ): ExecutionResult; ``` From 678a64a2743c5e3dea5bb95c24aee741d0e0ff31 Mon Sep 17 00:00:00 2001 From: Jovi De Croock Date: Thu, 10 Apr 2025 10:21:12 +0200 Subject: [PATCH 3/3] Apply suggestions from code review Co-authored-by: Cris Naranjo <12249221+cristunaranjo@users.noreply.github.com> --- website/pages/api-v16/execution.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/website/pages/api-v16/execution.mdx b/website/pages/api-v16/execution.mdx index 4f3fdc9ae1..4723513d23 100644 --- a/website/pages/api-v16/execution.mdx +++ b/website/pages/api-v16/execution.mdx @@ -31,7 +31,7 @@ const { execute } = require('graphql'); // CommonJS ```ts export function execute({ schema, - documentAST, + document rootValue, contextValue, variableValues, @@ -98,7 +98,7 @@ method will throw an error. ```ts export function executeSync({ schema, - documentAST, + document, rootValue, contextValue, variableValues,