Merge branch '16.x.x' into handle-unhandled-exception

Author: JoviDeCroock

website/pages/docs/_meta.ts

@@ -17,6 +17,7 @@ const meta = {
     title: 'Advanced Guides',
   },
   'constructing-types': '',
+  'abstract-types': '',
   'oneof-input-objects': '',
   'defer-stream': '',
   'cursor-based-pagination': '',

website/pages/docs/abstract-types.mdx

@@ -0,0 +1,204 @@
+---
+title: Abstract types in GraphQL.js
+---
+
+GraphQL includes two kinds of abstract types: interfaces and unions. These types let a single
+field return values of different object types, while keeping your schema type-safe.
+
+This guide covers how to define and resolve abstract types using GraphQL.js. It focuses on 
+constructing types in JavaScript using the GraphQL.js type system, not the schema definition
+language (SDL).
+
+## What are abstract types?
+
+Most GraphQL types are concrete. They represent a specific kind of object, for example, a
+`Book` or an `Author`. Abstract types let a field return different types of objects depending
+on the data.
+
+This is useful when the return type can vary but comes from a known set. For example, a `search`
+field might return a book, an author, or a publisher. Abstract types let you model this kind of
+flexibility while preserving validation, introspection, and tool support.
+
+GraphQL provides two kinds of abstract types:
+
+- Interfaces define a set of fields that multiple object types must implement.
+    - Use case: A `ContentItem` interface with fields like `id`, `title`, and `publishedAt`,
+    implemented by types such as `Article` and `PodcastEpisode`.
+- Unions group together unrelated types that don't share any fields.
+    - Use case: A `SearchResult` union that includes `Book`, `Author`, and `Publisher` types.
+
+## Defining interfaces
+
+To define an interface in GraphQL.js, use the `GraphQLInterfaceType` constructor. An interface
+must include a `name`, a `fields` function, and a `resolveType` function, which tells GraphQL which
+concrete type a given value corresponds to.
+
+The following example defines a `ContentItem` interface for a publishing platform:
+
+```js
+const { GraphQLInterfaceType, GraphQLString, GraphQLNonNull } = require('graphql');
+
+const ContentItemInterface = new GraphQLInterfaceType({
+  name: 'ContentItem',
+  fields: {
+    id: { type: new GraphQLNonNull(GraphQLString) },
+    title: { type: GraphQLString },
+    publishedAt: { type: GraphQLString },
+  },
+  resolveType(value) {
+    if (value.audioUrl) {
+      return 'PodcastEpisode';
+    }
+    if (value.bodyText) {
+      return 'Article';
+    }
+    return null;
+  },
+});
+```
+
+You can return either the type name as a string or the corresponding `GraphQLObjectType` instance.
+Returning the instance is recommended when possible for better type safety and tooling support.
+
+## Implementing interfaces with object types
+
+To implement an interface, define a `GraphQLObjectType` and include the interface in its
+`interfaces` array. The object type must implement all fields defined by the interface.
+
+The following example implements the `Article` and `PodcastEpisode` types that
+conform to the `ContentItem` interface:
+
+```js
+const { GraphQLObjectType, GraphQLString, GraphQLNonNull } = require('graphql');
+
+const ArticleType = new GraphQLObjectType({
+  name: 'Article',
+  interfaces: [ContentItemInterface],
+  fields: {
+    id: { type: new GraphQLNonNull(GraphQLString) },
+    title: { type: GraphQLString },
+    publishedAt: { type: GraphQLString },
+    bodyText: { type: GraphQLString },
+  },
+  isTypeOf: (value) => value.bodyText !== undefined,
+});
+
+const PodcastEpisodeType = new GraphQLObjectType({
+  name: 'PodcastEpisode',
+  interfaces: [ContentItemInterface],
+  fields: {
+    id: { type: new GraphQLNonNull(GraphQLString) },
+    title: { type: GraphQLString },
+    publishedAt: { type: GraphQLString },
+    audioUrl: { type: GraphQLString },
+  },
+  isTypeOf: (value) => value.audioUrl !== undefined,
+});
+```
+
+The `isTypeOf` function is optional. It provides a fallback when `resolveType` isn't defined, or
+when runtime values could match multiple types. If both `resolveType` and `isTypeOf` are defined,
+GraphQL uses `resolveType`.
+
+## Defining union types
+
+Use the `GraphQLUnionType` constructor to define a union. A union allows a field to return one
+of several object types that don't need to share fields.
+
+A union requires:
+
+- A `name`
+- A list of object types (`types`)
+- A `resolveType` function
+
+The following example defines a `SearchResult` union:
+
+```js
+const { GraphQLUnionType } = require('graphql');
+
+const SearchResultType = new GraphQLUnionType({
+  name: 'SearchResult',
+  types: [BookType, AuthorType, PublisherType],
+  resolveType(value) {
+    if (value.isbn) {
+      return 'Book';
+    }
+    if (value.bio) {
+      return 'Author';
+    }
+    if (value.catalogSize) {
+      return 'Publisher';
+    }
+    return null;
+  },
+});
+```
+
+Unlike interfaces, unions don’t declare any fields of their own. Clients use inline fragments 
+to query fields from the concrete types.
+
+## Resolving abstract types at runtime
+
+GraphQL resolves abstract types dynamically during execution using the `resolveType` function.
+
+This function receives the following arguments:
+
+```js
+resolveType(value, context, info)
+```
+
+It can return:
+
+- A `GraphQLObjectType` instance (recommended)
+- The name of a type as a string
+- A `Promise` resolving to either of the above
+
+If `resolveType` isn't defined, GraphQL falls back to checking each possible type's `isTypeOf` 
+function. This fallback is less efficient and makes type resolution harder to debug. For most cases,
+explicitly defining `resolveType` is recommended.
+
+## Querying abstract types
+
+To query a field that returns an abstract type, use inline fragments to select fields from the 
+possible concrete types. GraphQL evaluates each fragment based on the runtime type of the result.
+
+For example:
+
+```graphql
+{
+  search(term: "deep learning") {
+    ... on Book {
+      title
+      isbn
+    }
+    ... on Author {
+      name
+      bio
+    }
+    ... on Publisher {
+      name
+      catalogSize
+    }
+  }
+}
+```
+
+GraphQL's introspection system lists all possible types for each interface and union, which
+enables code generation and editor tooling to provide type-aware completions.
+
+## Best practices
+
+- Always implement `resolveType` for interfaces and unions to handle runtime type resolution.
+- Return the `GraphQLObjectType` instance when possible for better clarity and static analysis.
+- Keep `resolveType` logic simple, using consistent field shapes or tags to distinguish
+types.
+- Test `resolveType` logic carefully. Errors in `resolveType` can cause runtime errors that can 
+be hard to trace.
+- Use interfaces when types share fields and unions when types are structurally unrelated.
+
+## Additional resources
+
+- [Constructing Types](https://www.graphql-js.org/docs/constructing-types/)
+- GraphQL Specification: 
+    - [Interfaces](https://spec.graphql.org/October2021/#sec-Interfaces)
+    - [Unions](https://spec.graphql.org/October2021/#sec-Unions)

website/pages/docs/advanced-custom-scalars.mdx

@@ -100,25 +100,36 @@ describe('DateTime scalar', () => {
 Integrate the scalar into a schema and run real GraphQL queries to validate end-to-end behavior.
 
 ```js
-const { graphql, buildSchema } = require('graphql');
+const { graphql, GraphQLSchema, GraphQLObjectType } = require('graphql');
+const { DateTimeResolver as DateTime } = require('graphql-scalars');
+
+const Query = new GraphQLObjectType({
+  name: 'Query',
+  fields: {
+    now: {
+      type: DateTime,
+      resolve() {
+        return new Date();
+      },
+    },
+  },
+});
 
-const schema = buildSchema(`
+/*
   scalar DateTime
 
   type Query {
     now: DateTime
   }
-`);
-
-const rootValue = {
-  now: () => new Date('2024-01-01T00:00:00Z'),
-};
+*/
+const schema = new GraphQLSchema({
+  query: Query,
+});
 
 async function testQuery() {
   const response = await graphql({
     schema,
     source: '{ now }',
-    rootValue,
   });
   console.log(response);
 }
@@ -181,13 +192,22 @@ If you need domain-specific behavior, you can wrap an existing scalar with custo
 ```js
 const { EmailAddressResolver } = require('graphql-scalars');
 
-const StrictEmail = new GraphQLScalarType({
+const StrictEmailAddress = new GraphQLScalarType({
   ...EmailAddressResolver,
+  name: 'StrictEmailAddress',
   parseValue(value) {
-    if (!value.endsWith('@example.com')) {
+    const email = EmailAddressResolver.parseValue(value);
+    if (!email.endsWith('@example.com')) {
+      throw new TypeError('Only example.com emails are allowed.');
+    }
+    return email;
+  },
+  parseLiteral(literal, variables) {
+    const email = EmailAddressResolver.parseLiteral(literal, variables);
+    if (!email.endsWith('@example.com')) {
       throw new TypeError('Only example.com emails are allowed.');
     }
-    return EmailAddressResolver.parseValue(value);
+    return email;
   },
 });
 ```

website/pages/docs/cursor-based-pagination.mdx

@@ -2,6 +2,8 @@
 title: Implementing Cursor-based Pagination
 ---
 
+import { Callout } from "nextra/components";
+
 When a GraphQL API returns a list of data, pagination helps avoid
 fetching too much data at once. Cursor-based pagination fetches items
 relative to a specific point in the list, rather than using numeric offsets.
@@ -18,15 +20,15 @@ that works well with clients.
 
 Cursor-based pagination typically uses a structured format that separates
 pagination metadata from the actual data. The most widely adopted pattern follows the
-[Relay Cursor Connections Specification](https://relay.dev/graphql/connections.htm). While
+[GraphQL Cursor Connections Specification](https://relay.dev/graphql/connections.htm). While
 this format originated in Relay, many GraphQL APIs use it independently because of its
 clarity and flexibility.
 
 This pattern wraps your list of items in a connection type, which includes the following fields:
 
-- `edges`: A list of edge objects, each representing an item in the list.
-- `node`: The actual object you want to retrieve, such as user, post, or comment.
-- `cursor`: An opaque string that identifies the position of the item in the list.
+- `edges`: A list of edge objects, representing for each item in the list:
+  - `node`: The actual object you want to retrieve, such as user, post, or comment.
+  - `cursor`: An opaque string that identifies the position of the item in the list.
 - `pageInfo`: Metadata about the list, such as whether more items are available.
 
 The following query and response show how this structure works:
@@ -192,7 +194,7 @@ const usersField = {
     let start = 0;
     if (args.after) {
       const index = decodeCursor(args.after);
-      if (index != null) {
+      if (Number.isFinite(index)) {
         start = index + 1;
       }
     }
@@ -243,7 +245,7 @@ async function resolveUsers(_, args) {
 
   if (args.after) {
     const index = decodeCursor(args.after);
-    if (index != null) {
+    if (Number.isFinite(index)) {
       offset = index + 1;
     }
   }
@@ -279,6 +281,25 @@ an `OFFSET`. To paginate backward, you can reverse the sort order and slice the
 results accordingly, or use keyset pagination for improved performance on large
 datasets.
 
+<Callout type='info'>
+
+The above is just an example to aid understanding; in a production application,
+for most databases it is better to use `WHERE` clauses to implement cursor
+pagination rather than using `OFFSET`. Using `WHERE` can leverage indices
+(indexes) to jump directly to the relevant records, whereas `OFFSET` typically
+must scan over and discard that number of records. When paginating very large
+datasets, `OFFSET` can become more expensive as the value grows, whereas using
+`WHERE` tends to have fixed cost. Using `WHERE` can also typically handle the
+addition or removal of data more gracefully.
+
+For example, if you were ordering a collection of users by username, you could
+use the username itself as the `cursor`, thus GraphQL's `allUsers(first: 10,
+after: $cursor)` could become SQL's `WHERE username > $1 LIMIT 10`. Even if
+that user was deleted, you could still continue to paginate from that position
+onwards.
+
+</Callout>
+
 ## Handling edge cases
 
 When implementing pagination, consider how your resolver should handle the following scenarios:
@@ -297,7 +318,7 @@ errors.
 
 To learn more about cursor-based pagination patterns and best practices, see:
 
-- [Relay Cursor Connections Specification](https://relay.dev/graphql/connections.htm)
+- [GraphQL Cursor Connections Specification](https://relay.dev/graphql/connections.htm)
 - [Pagination](https://graphql.org/learn/pagination/) guide on graphql.org
 - [`graphql-relay-js`](https://github.com/graphql/graphql-relay-js): Utility library for
 building Relay-compatible GraphQL servers using GraphQL.js

website/pages/docs/custom-scalars.mdx

@@ -80,6 +80,10 @@ providing a name, description, and three functions:
 - `serialize`: How the server sends internal values to clients.
 - `parseValue`: How the server parses incoming variable values.
 - `parseLiteral`: How the server parses inline values in queries.
+- `specifiedByURL` (optional): A URL specifying the behavior of your scalar;
+  this can be used by clients and tooling to recognize and handle common scalars
+  such as [date-time](https://scalars.graphql.org/andimarek/date-time.html)
+  independent of their name.
 
 The following example is a custom `DateTime` scalar that handles ISO-8601 encoded
 date strings:
@@ -90,6 +94,7 @@ const { GraphQLScalarType, Kind } = require('graphql');
 const DateTime = new GraphQLScalarType({
   name: 'DateTime',
   description: 'An ISO-8601 encoded UTC date string.',
+  specifiedByURL: 'https://scalars.graphql.org/andimarek/date-time.html',
 
   serialize(value) {
     if (!(value instanceof Date)) {