From 80750dae62b0c60da2baa94505d64e29298de62f Mon Sep 17 00:00:00 2001 From: jdecroock Date: Sat, 2 Nov 2024 09:16:31 +0100 Subject: [PATCH 1/5] Document executeSync (#2941) --- website/pages/execution.mdx | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/website/pages/execution.mdx b/website/pages/execution.mdx index 9b97c6e67f..d9eb7ea819 100644 --- a/website/pages/execution.mdx +++ b/website/pages/execution.mdx @@ -56,3 +56,25 @@ a GraphQLError will be thrown immediately explaining the invalid input. `ExecutionResult` represents the result of execution. `data` is the result of executing the query, `errors` is null if no errors occurred, and is a non-empty array if an error occurred. + +### executeSync + +```ts +export function executeSync( + schema: GraphQLSchema, + documentAST: Document, + rootValue?: mixed, + contextValue?: mixed, + 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. From c24fefde346162878246056344d78ba762c0f3b1 Mon Sep 17 00:00:00 2001 From: jdecroock Date: Sat, 2 Nov 2024 09:16:46 +0100 Subject: [PATCH 2/5] Update ScalarType docs (#2567) --- website/pages/type.mdx | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) diff --git a/website/pages/type.mdx b/website/pages/type.mdx index 0eb05d3302..eb1365c64a 100644 --- a/website/pages/type.mdx +++ b/website/pages/type.mdx @@ -188,16 +188,20 @@ const MyAppSchema = new GraphQLSchema({ ### GraphQLScalarType ```ts -class GraphQLScalarType { - constructor(config: GraphQLScalarTypeConfig); +class GraphQLScalarType { + constructor(config: GraphQLScalarTypeConfig); } -type GraphQLScalarTypeConfig = { +type GraphQLScalarTypeConfig = { name: string; description?: string; - serialize: (value: mixed) => InternalType; - parseValue?: (value: mixed) => InternalType; - parseLiteral?: (valueAST: Value) => InternalType; + specifiedByURL?: Maybe; + serialize: (outputValue: unknown) => ExternalType; + parseValue?: (inputValue: unknown) => InternalType; + parseLiteral?: ( + valueAST: Value, + variables?: Maybe>, + ) => InternalType; }; ``` From e4c0fe48a2d65a3ed5349c0cb9999c436bed4a89 Mon Sep 17 00:00:00 2001 From: jdecroock Date: Sat, 2 Nov 2024 09:23:10 +0100 Subject: [PATCH 3/5] Explain custom scalar example (graphql/graphql.github.io#163) --- website/pages/type.mdx | 15 +++++++++++++-- 1 file changed, 13 insertions(+), 2 deletions(-) diff --git a/website/pages/type.mdx b/website/pages/type.mdx index eb1365c64a..73013f9316 100644 --- a/website/pages/type.mdx +++ b/website/pages/type.mdx @@ -214,9 +214,20 @@ functions used to ensure validity. ```js const OddType = new GraphQLScalarType({ name: 'Odd', - serialize: oddValue, - parseValue: oddValue, + description: + 'This custom scalar will only return a value if the passed in value is an odd integer, when it's not it will return null.' + serialize: (outputValue) => { + // This function gets called for response-data, the application returns data + // for a property and in the schema we see that this value has the "Odd" type. + return typeof outputValue === 'number' && outputValue % 2 === 1 ? value : null; + }, + parseValue: (inputValue) => { + // This function gets called for input-data, i.e. variables being passed in + return typeof inputValue === 'number' && outputValue % 2 === 1 ? value : null; + }, parseLiteral(ast) { + // This function gets called when the value is passed in as a literal on the + // Executable GraphQL Document if (ast.kind === Kind.INT) { return oddValue(parseInt(ast.value, 10)); } From cbb7de940609ae29c0535f2c14408c733bb79d4e Mon Sep 17 00:00:00 2001 From: jdecroock Date: Sat, 2 Nov 2024 09:25:32 +0100 Subject: [PATCH 4/5] Ensure ExecutionResult is defined (graphql/graphql.github.io#1049) --- website/pages/execution.mdx | 12 ++++++++---- website/pages/graphql.mdx | 9 +++++++++ website/pages/type.mdx | 4 ---- 3 files changed, 17 insertions(+), 8 deletions(-) diff --git a/website/pages/execution.mdx b/website/pages/execution.mdx index d9eb7ea819..2810ed183a 100644 --- a/website/pages/execution.mdx +++ b/website/pages/execution.mdx @@ -40,10 +40,14 @@ export function execute( type MaybePromise = Promise | T; -type ExecutionResult = { - data: Object; - errors?: GraphQLError[]; -}; +interface ExecutionResult< + TData = ObjMap, + TExtensions = ObjMap, +> { + errors?: ReadonlyArray; + data?: TData | null; + extensions?: TExtensions; +} ``` Implements the "Evaluating requests" section of the GraphQL specification. diff --git a/website/pages/graphql.mdx b/website/pages/graphql.mdx index 624aeeb10b..e6936f279c 100644 --- a/website/pages/graphql.mdx +++ b/website/pages/graphql.mdx @@ -144,6 +144,15 @@ function graphql( variableValues?: { [key: string]: any }, operationName?: string, ): Promise; + +interface ExecutionResult< + TData = ObjMap, + TExtensions = ObjMap, +> { + errors?: ReadonlyArray; + data?: TData | null; + extensions?: TExtensions; +} ``` The `graphql` function lexes, parses, validates and executes a GraphQL request. diff --git a/website/pages/type.mdx b/website/pages/type.mdx index 73013f9316..ea320a951d 100644 --- a/website/pages/type.mdx +++ b/website/pages/type.mdx @@ -234,10 +234,6 @@ const OddType = new GraphQLScalarType({ return null; }, }); - -function oddValue(value) { - return value % 2 === 1 ? value : null; -} ``` ### GraphQLObjectType From 56e8f5de326a2b6385a0ab38c6367a64ee2dae07 Mon Sep 17 00:00:00 2001 From: Jovi De Croock Date: Sat, 2 Nov 2024 10:05:40 +0100 Subject: [PATCH 5/5] Document specifiedByURL --- website/pages/type.mdx | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/website/pages/type.mdx b/website/pages/type.mdx index ea320a951d..4ab3d7d1a2 100644 --- a/website/pages/type.mdx +++ b/website/pages/type.mdx @@ -214,6 +214,10 @@ functions used to ensure validity. ```js const OddType = new GraphQLScalarType({ name: 'Odd', + // Can be used to link to a specification + // for this scalar, for instance the JSON + // specification. + specifiedByURL: '', description: 'This custom scalar will only return a value if the passed in value is an odd integer, when it's not it will return null.' serialize: (outputValue) => {