Skip to content

Commit 7066b58

Browse files
JoviDeCroockyaacovCR
JoviDeCroock
and
yaacovCR
authored
First draft for upgrade guide to v17 (#4310)
Co-authored-by: Yaacov Rydzinski <yaacovCR@gmail.com>
1 parent 05c92f4 commit 7066b58

File tree

2 files changed

+197
-0
lines changed

2 files changed

+197
-0
lines changed

‎website/pages/_meta.ts

+10
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,16 @@ const meta = {
33
type: 'page',
44
title: 'Documentation',
55
},
6+
'upgrade-guides': {
7+
type: 'menu',
8+
title: 'Upgrade Guides',
9+
items: {
10+
'v16-v17': {
11+
title: 'v16 to v17',
12+
href: '/upgrade-guides/v16-v17',
13+
},
14+
},
15+
},
616
'api-v16': {
717
type: 'menu',
818
title: 'API',

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

+187
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,187 @@
1+
---
2+
title: Upgrading from v16 to v17
3+
sidebarTitle: v16 to v17
4+
---
5+
6+
import { Tabs } from 'nextra/components';
7+
import { Callout } from 'nextra/components'
8+
9+
<Callout type="info" emoji="ℹ️">
10+
Currently GraphQL v17 is in alpha, this guide is based on the alpha release and is subject to change.
11+
</Callout>
12+
13+
# Breaking changes
14+
15+
## Default values
16+
17+
GraphQL schemas allow default values for input fields and arguments. Historically, GraphQL.js did not rigorously validate or coerce these
18+
defaults during schema construction, leading to potential runtime errors or inconsistencies. For example:
19+
20+
- A default value of "5" (string) for an Int-type argument would pass schema validation but fail at runtime.
21+
- Internal serialization methods like astFromValue could produce invalid ASTs if inputs were not properly coerced.
22+
23+
With the new changes default values will be validated and coerced during schema construction.
24+
25+
```graphql
26+
input ExampleInput {
27+
value: Int = "invalid" # Now triggers a validation error
28+
}
29+
```
30+
31+
This goes hand-in-hand with the deprecation of `astFromValue` in favor of `valueToLiteral` or `default: { value: <externalValue> }`.
32+
33+
```ts
34+
// Before (deprecated)
35+
const defaultValue = astFromValue(internalValue, type);
36+
// After
37+
const defaultValue = valueToLiteral(externalValue, type);
38+
```
39+
40+
If you want to continue using the old behavior, you can use `defaultValue` in your schema definitions. The new
41+
behavior will be exposed as `default: { literal: <literal> }`.
42+
43+
## GraphQLError constructor arguments
44+
45+
The `GraphQLError` constructor now only accepts a message and options object as arguments. Previously, it also accepted positional arguments.
46+
47+
```diff
48+
- new GraphQLError('message', 'source', 'positions', 'path', 'originalError', 'extensions');
49+
+ new GraphQLError('message', { source, positions, path, originalError, extensions });
50+
```
51+
52+
## `createSourceEventStream` arguments
53+
54+
The `createSourceEventStream` function now only accepts an object as an argument. Previously, it also accepted positional arguments.
55+
56+
```diff
57+
- createSourceEventStream(schema, document, rootValue, contextValue, variableValues, operationName);
58+
+ createSourceEventStream({ schema, document, rootValue, contextValue, variableValues, operationName });
59+
```
60+
61+
## `execute` will error for incremental delivery
62+
63+
The `execute` function will now throw an error if it sees a `@defer` or `@stream` directive. Use `experimentalExecuteIncrementally` instead.
64+
If you know you are dealing with incremental delivery requests, you can replace the import.
65+
66+
```diff
67+
- import { execute } from 'graphql';
68+
+ import { experimentalExecuteIncrementally as execute } from 'graphql';
69+
```
70+
71+
## Remove incremental delivery support from `subscribe`
72+
73+
In case you have fragments that you use with `defer/stream` that end up in a subscription,
74+
use the `if` argument of the directive to disable it in your subscription operation
75+
76+
## `subscribe` return type
77+
78+
The `subscribe` function can now also return a non-Promise value, previously this was only a Promise.
79+
This shouldn't change a lot as `await value` will still work as expected. This could lead to
80+
some typing inconsistencies though.
81+
82+
## Remove `singleResult` from incremental results
83+
84+
You can remove branches that check for `singleResult` in your code, as it is no longer used.
85+
86+
## Node support
87+
88+
Dropped support for Node 14 (subject to change)
89+
90+
## Removed `TokenKindEnum`, `KindEnum` and `DirectiveLocationEnum` types
91+
92+
We have removed the `TokenKindEnum`, `KindEnum` and `DirectiveLocationEnum` types,
93+
use `Kind`, `TokenKind` and `DirectiveLocation` instead. https://github.com/graphql/graphql-js/pull/3579
94+
95+
## Removed `graphql/subscription` module
96+
97+
use `graphql/execution` instead for subscriptions, all execution related exports have been
98+
unified there.
99+
100+
## Removed `GraphQLInterfaceTypeNormalizedConfig` export
101+
102+
Use `ReturnType<GraphQLInterfaceType['toConfig']>` if you really need this
103+
104+
## Empty AST collections will be undefined
105+
106+
Empty AST collections will be presented by `undefined` rather than an empty array.
107+
108+
## `Info.variableValues`
109+
110+
The shape of `Info.variableValues` has changed to be an object containing
111+
`sources` and `coerced` as keys.
112+
113+
A Source contains the `signature` and provided `value` pre-coercion for the
114+
variable. A `signature` is an object containing the `name`, `input-type` and
115+
`defaultValue` for the variable.
116+
117+
## Stream directive can't be on multiple instances of the same field
118+
119+
The `@stream` directive can't be on multiple instances of the same field,
120+
this won't pass `validate` anymore.
121+
122+
See https://github.com/graphql/graphql-js/pull/4342
123+
124+
## Stream initialCount becomes non-nullable
125+
126+
The `initialCount` argument of the `@stream` directive is now non-nullable.
127+
128+
See https://github.com/graphql/graphql-js/pull/4322
129+
130+
## GraphQLSchemas converted to configuration may no longer be assumed valid
131+
132+
The `assumeValid` config property exported by the `GraphQLSchema.toConfig()` method now passes through the original
133+
flag passed on creation of the `GraphQLSchema`.
134+
Previously, the `assumeValid` property would be to `true` if validation had been run, potentially concealing the original intent.
135+
136+
See https://github.com/graphql/graphql-js/pull/4244 and https://github.com/graphql/graphql-js/issues/3448
137+
138+
## `coerceInputValue` returns `undefined` on error
139+
140+
`coerceInputValue` now aborts early when an error occurs, to optimize execution speed on the happy path.
141+
Use the `validateInputValue` helper to retrieve the actual errors.
142+
143+
## Removals
144+
145+
- Removed deprecated `getOperationType` function, use `getRootType` on the `GraphQLSchema` instance instead
146+
- Removed deprecated `getVisitFn` function, use `getEnterLeaveForKind` instead
147+
- Removed deprecated `printError` and `formatError` utilities, you can use `toString` or `toJSON` on the error as a replacement
148+
- Removed deprecated `assertValidName` and `isValidNameError` utilities, use `assertName` instead
149+
- Removed deprecated `assertValidExecutionArguments` function, use `assertValidSchema` instead
150+
- Removed deprecated `getFieldDefFn` from `TypeInfo`
151+
- Removed deprecated `TypeInfo` from `validate` https://github.com/graphql/graphql-js/pull/4187
152+
153+
## Deprecations
154+
155+
- Deprecated `astFromValue` use `valueToLiteral` instead, when leveraging `valueToLiteral` ensure
156+
that you are working with externally provided values i.e. the SDL provided defaultValue to a variable.
157+
- Deprecated `valueFromAST` use `coerceInputLiteral` instead
158+
- Deprecated `findBreakingChanges()` and `findDangerousChanges()`. Use `findSchemaChanges()` instead, which can also be used to find safe changes.
159+
- Deprecated `serialize`. `parseValue`, and `parseLiteral` properties on scalar type configuration. Use `coerceOutputValue`, `coerceInputValue`, and `coerceInputLiteral` instead.
160+
161+
## Experimental Features
162+
163+
### Experimental Support for Incremental Delivery
164+
165+
- [Spec PR](https://github.com/graphql/graphql-spec/pull/1110) / [RFC](https://github.com/graphql/graphql-wg/blob/main/rfcs/DeferStream.md)
166+
- enabled only when using `experimentalExecuteIncrementally()`, use of a schema or operation with `@defer`/`@stream` directives within `execute()` will now throw.
167+
- enable early execution with the new `enableEarlyExecution` configuration option for `experimentalExecuteIncrementally()`.
168+
169+
### Experimental Support for Fragment Arguments
170+
171+
- [Spec PR](https://github.com/graphql/graphql-spec/pull/1081)
172+
- enable with the new `experimentalFragmentArguments` configuration option for `parse()`.
173+
- new experimental `Kind.FRAGMENT_ARGUMENT` for visiting
174+
- new experimental `TypeInfo` methods and options for handling fragment arguments.
175+
- coerce AST via new function `coerceInputLiteral()` with experimental fragment variables argument (as opposed to deprecated `valueFromAST()` function).
176+
177+
## Features
178+
179+
- Added `hideSuggestions` option to `execute`/`validate`/`subscribe`/... to hide schema-suggestions in error messages
180+
- Added `abortSignal` option to `graphql()`, `execute()`, and `subscribe()` allows cancellation of these methods;
181+
the `abortSignal` can also be passed to field resolvers to cancel asynchronous work that they initiate.
182+
- `extensions` support `symbol` keys, in addition to the normal string keys.
183+
- Added ability for resolver functions to return async iterables.
184+
- Added `perEventExecutor` execution option to allows specifying a custom executor for subscription source stream events, which can be useful for preparing a per event execution context argument.
185+
- Added `validateInputValue` and `validateInputLiteral` helpers to validate input values and literals, respectively.
186+
- Added `replaceVariableValues` helper to replace variables within complex scalars uses as inputs. Internally, this allows variables embedded within complex scalars to finally use the correct default values.
187+
- Added new `printDirective` helper.

0 commit comments

Comments
 (0)