Skip to content

Commit edf1802

Browse files
JoviDeCroockJoviDeCroock
committed
Upgrade guide for v17
1 parent 05c92f4 commit edf1802

File tree

1 file changed

+148
-0
lines changed

1 file changed

+148
-0
lines changed

‎website/pages/upgrade-guides/v16-v17.mdx‎

Lines changed: 148 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,148 @@
1+
---
2+
title: Upgrading from v16 to v17
3+
sidebarTitle: v16 to v17
4+
---
5+
6+
import { Tabs } from 'nextra/components';
7+
8+
# Breaking changes
9+
10+
## Default values
11+
12+
GraphQL schemas allow default values for input fields and arguments. Historically, GraphQL.js did not rigorously validate or coerce these
13+
defaults during schema construction, leading to potential runtime errors or inconsistencies. For example:
14+
15+
- A default value of "5" (string) for an Int-type argument would pass schema validation but fail at runtime.
16+
- Internal serialization methods like astFromValue could produce invalid ASTs if inputs were not properly coerced.
17+
18+
With the new changes default values will be validated and coerced during schema construction.
19+
20+
```graphql
21+
input ExampleInput {
22+
value: Int = "invalid" # Now triggers a validation error
23+
}
24+
```
25+
26+
This goes hand-in-hand with the deprecation of `astFromValue` in favor of `valueToLiteral`.
27+
28+
```ts
29+
// Before (deprecated)
30+
const defaultValue = astFromValue(internalValue, type);
31+
// After
32+
const defaultValue = valueToLiteral(externalValue, type);
33+
```
34+
35+
If you want to continue using the old behavior, you can use `externalDefaultValue` rather than `defaultValue` in your schema definitions.
36+
37+
## GraphQLError constructor arguments
38+
39+
The `GraphQLError` constructor now only accepts a message and options object as arguments. Previously, it also accepted positional arguments.
40+
41+
```diff
42+
- new GraphQLError('message', 'source', 'positions', 'path', 'originalError', 'extensions');
43+
+ new GraphQLError('message', { source, positions, path, originalError, extensions });
44+
```
45+
46+
## `createSourceEventStream` arguments
47+
48+
The `createSourceEventStream` function now only accepts an object as an argument. Previously, it also accepted positional arguments.
49+
50+
```diff
51+
- createSourceEventStream(schema, document, rootValue, contextValue, variableValues, operationName);
52+
+ createSourceEventStream({ schema, document, rootValue, contextValue, variableValues, operationName });
53+
```
54+
55+
## `execute` will error for incremental delivery
56+
57+
The `execute` function will now throw an error if it sees a `@defer` or `@stream` directive. Use `experimentalExecuteIncrementally` instead.
58+
If you know you are dealing with incremental delivery requests, you can replace the import.
59+
60+
```diff
61+
- import { execute } from 'graphql';
62+
+ import { experimentalExecuteIncrementally as execute } from 'graphql';
63+
```
64+
65+
## Remove incremental delivery support from `subscribe`
66+
67+
In case you have fragments that you use with `defer/stream` that end up in a subscription,
68+
use the `if` argument of the directive to disable it in your subscription operation
69+
70+
## `subscribe` return type
71+
72+
The `subscribe` function can now also return a non-Promise value, previously this was only a Promise.
73+
This shouldn't change a lot as `await value` will still work as expected. This could lead to
74+
some typing inconsistencies though.
75+
76+
## Remove `singleResult` from incremental results
77+
78+
You can remove branches that check for `singleResult` in your code, as it is no longer used.
79+
80+
## Node support
81+
82+
Dropped support for Node 14 (subject to change)
83+
84+
## Removed `TokenKindEnum`, `KindEnum` and `DirectiveLocationEnum` types
85+
86+
We have removed the `TokenKindEnum`, `KindEnum` and `DirectiveLocationEnum` types,
87+
use `Kind`, `TokenKind` and `DirectiveLocation` instead. https://github.com/graphql/graphql-js/pull/3579
88+
89+
## Removed `graphql/subscription` module
90+
91+
use `graphql/execution` instead for subscriptions, all execution related exports have been
92+
unified there.
93+
94+
## Removed `GraphQLInterfaceTypeNormalizedConfig` export
95+
96+
Use `ReturnType<GraphQLInterfaceType['toConfig']>` if you really need this
97+
98+
## Empty AST collections will be undefined
99+
100+
Empty AST collections will be presented by `undefined` rather than an empty array.
101+
102+
## `Info.variableValues`
103+
104+
The shape of `Info.variableValues` has changed to be an object containing
105+
`sources` and `coerced` as keys.
106+
107+
A Source contains the `signature` and provided `value` pre-coercion for the
108+
variable. A `signature` is an object containing the `name`, `input-type` and
109+
`defaultValue` for the variable.
110+
111+
## Removals
112+
113+
- Removed deprecated `getOperationType` function, use `getRootType` on the `GraphQLSchema` instance instead
114+
- Removed deprecated `getVisitFn` function, use `getEnterLeaveForKind` instead
115+
- Removed deprecated `printError` and `formatError` utilities, you can use `toString` or `toJSON` on the error as a replacement
116+
- Removed deprecated `assertValidName` and `isValidNameError` utilities, use `assertName` instead
117+
- Removed deprecated `assertValidExecutionArguments` function, use `assertValidSchema` instead
118+
- Removed deprecated `getFieldDefFn` from `TypeInfo`
119+
- Removed deprecated `TypeInfo` from `validate` https://github.com/graphql/graphql-js/pull/4187
120+
121+
## Deprecations
122+
123+
- Deprecated `astFromValue` use `valueToLiteral` instead, when leveraging `valueToLiteral` ensure
124+
that you are working with externally provided values i.e. the SDL provided defaultValue to a variable.
125+
- Deprecated `valueFormAST` use `coerceInputLiteral` instead
126+
127+
## New Features
128+
129+
- Added `hideSuggestions` option to `execute`/`validate`/`subscribe`/... to hide schema-suggestions in error messages
130+
- Added `abortSignal` option to `graphql()`, `execute()`, and `subscribe()` allows cancellation of these methods;
131+
the `abortSignal` can also be passed to field resolvers to cancel asynchronous work that they initiate.
132+
- `extensions` support `symbol` keys, in addition to the normal string keys.
133+
134+
## New Experimental Features
135+
136+
### Experimental Support for Incremental Delivery
137+
138+
- [Spec PR](https://github.com/graphql/graphql-spec/pull/1110) / [RFC](https://github.com/graphql/graphql-wg/blob/main/rfcs/DeferStream.md)
139+
- enabled only when using `experimentalExecuteIncrementally()`, use of a schema or operation with `@defer`/`@stream` directives within `execute()` will now throw.
140+
- enable early execution with the new `enableEarlyExecution` configuration option for `experimentalExecuteIncrementally()`.
141+
142+
### Experimental Support for Fragment Arguments
143+
144+
- [Spec PR](https://github.com/graphql/graphql-spec/pull/1081)
145+
- enable with the new `experimentalFragmentArguments` configuration option for `parse()`.
146+
- new experimental `Kind.FRAGMENT_ARGUMENT` for visiting
147+
- new experimental `TypeInfo` methods and options for handling fragment arguments.
148+
- coerce AST via new function `coerceInputLiteral()` with experimental fragment variables argument (as opposed to deprecated `valueFromAST()` function).

0 commit comments

Comments
 (0)