From 84a49f7856c2a95cd99d5d66235c98c7b53e38b9 Mon Sep 17 00:00:00 2001
From: Jovi De Croock <decroockjovi@gmail.com>
Date: Mon, 4 Nov 2024 18:05:56 +0100
Subject: [PATCH] Solve some low hanging fruit in the documentation (#4279)

Ultimately I was trying this out to see whether we can tweak the docs
easily, it made me realize that our docs are tailored to general GraphQL
rather than how do we use this library. It made me come up with a few
suggestions

- We should have a toggle on code examples to switch between
`buildSchema` and programatically creating the schema with i.e.
`GraphQLObjectType`
- Our documentation starts with a tutorial, this ultimately feels like a
mistake, we should lead with an explanation of what GraphQL.JS is and
what it aims to do, clearly outlining the goals of this project
- We should line out use-cases for building on this library and best
practices of how to go to production

Resolves #2941
Resolves #2567
---
 website/pages/execution.mdx | 34 ++++++++++++++++++++++++++++----
 website/pages/graphql.mdx   |  9 +++++++++
 website/pages/type.mdx      | 39 +++++++++++++++++++++++++------------
 3 files changed, 66 insertions(+), 16 deletions(-)

diff --git a/website/pages/execution.mdx b/website/pages/execution.mdx
index 9b97c6e67f..2810ed183a 100644
--- a/website/pages/execution.mdx
+++ b/website/pages/execution.mdx
@@ -40,10 +40,14 @@ export function execute(
 
 type MaybePromise<T> = Promise<T> | T;
 
-type ExecutionResult = {
-  data: Object;
-  errors?: GraphQLError[];
-};
+interface ExecutionResult<
+  TData = ObjMap<unknown>,
+  TExtensions = ObjMap<unknown>,
+> {
+  errors?: ReadonlyArray<GraphQLError>;
+  data?: TData | null;
+  extensions?: TExtensions;
+}
 ```
 
 Implements the "Evaluating requests" section of the GraphQL specification.
@@ -56,3 +60,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.
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<GraphQLResult>;
+
+interface ExecutionResult<
+  TData = ObjMap<unknown>,
+  TExtensions = ObjMap<unknown>,
+> {
+  errors?: ReadonlyArray<GraphQLError>;
+  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 0eb05d3302..4ab3d7d1a2 100644
--- a/website/pages/type.mdx
+++ b/website/pages/type.mdx
@@ -188,16 +188,20 @@ const MyAppSchema = new GraphQLSchema({
 ### GraphQLScalarType
 
 ```ts
-class GraphQLScalarType<InternalType> {
-  constructor(config: GraphQLScalarTypeConfig<InternalType>);
+class GraphQLScalarType<InternalType, ExternalType> {
+  constructor(config: GraphQLScalarTypeConfig<InternalType, ExternalType>);
 }
 
-type GraphQLScalarTypeConfig<InternalType> = {
+type GraphQLScalarTypeConfig<InternalType, ExternalType> = {
   name: string;
   description?: string;
-  serialize: (value: mixed) => InternalType;
-  parseValue?: (value: mixed) => InternalType;
-  parseLiteral?: (valueAST: Value) => InternalType;
+  specifiedByURL?: Maybe<string>;
+  serialize: (outputValue: unknown) => ExternalType;
+  parseValue?: (inputValue: unknown) => InternalType;
+  parseLiteral?: (
+    valueAST: Value,
+    variables?: Maybe<Record<string, unknown>>,
+  ) => InternalType;
 };
 ```
 
@@ -210,19 +214,30 @@ functions used to ensure validity.
 ```js
 const OddType = new GraphQLScalarType({
   name: 'Odd',
-  serialize: oddValue,
-  parseValue: oddValue,
+  // 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) => {
+    // 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));
     }
     return null;
   },
 });
-
-function oddValue(value) {
-  return value % 2 === 1 ? value : null;
-}
 ```
 
 ### GraphQLObjectType