From f793d50cb49322bd2b5a73166a4f9235e0170e70 Mon Sep 17 00:00:00 2001 From: Yaacov Rydzinski Date: Mon, 15 Jun 2026 12:58:35 +0300 Subject: [PATCH] docs: post 17.rc-0 update --- .../experimental-specification-features.mdx | 9 +++--- website/pages/docs/getting-started.mdx | 21 +++++++------ website/pages/docs/index.mdx | 6 ++-- website/pages/docs/oneof-input-objects.mdx | 30 +++++++++++++++++++ website/pages/upgrade-guides/v14-v15.mdx | 8 ++--- website/pages/upgrade-guides/v15-v16.mdx | 7 ++--- website/pages/upgrade-guides/v16-v17.mdx | 29 +++++++++++++----- 7 files changed, 73 insertions(+), 37 deletions(-) diff --git a/website/pages/docs/experimental-specification-features.mdx b/website/pages/docs/experimental-specification-features.mdx index a87fb40f45..e7f3000c18 100644 --- a/website/pages/docs/experimental-specification-features.mdx +++ b/website/pages/docs/experimental-specification-features.mdx @@ -5,11 +5,10 @@ sidebarTitle: Experimental Specification Features # Experimental Specification Features -GraphQL.js v17 release candidate supports several GraphQL specification -proposals. This page lists experimental features available in the v17 -release-candidate line; not every feature listed here is new to v17. These -features are intentionally explicit: syntax usually requires a parser option or -schema directive, and execution behavior usually requires a specific executor. +GraphQL.js v17 adds several experimental GraphQL specification proposals. +These features are intentionally explicit: syntax usually requires a parser +option or schema directive, and execution behavior usually requires a +specific executor. GraphQL.js-specific runtime APIs, such as abort signals, execution hooks, and the harness API, are documented separately because they are not GraphQL language diff --git a/website/pages/docs/getting-started.mdx b/website/pages/docs/getting-started.mdx index b91d2f8a81..cb141cc4f3 100644 --- a/website/pages/docs/getting-started.mdx +++ b/website/pages/docs/getting-started.mdx @@ -11,21 +11,21 @@ import { Tabs } from 'nextra/components'; ## Prerequisites -Before getting started, you should have at least Node 20 installed, the examples can be tweaked to work with Node versions -before that by switching to require syntax. -For this guide, we won't use any language features that require transpilation, but we will use some ES6 features like -[Promises](http://web.dev/articles/promises/), classes, -and arrow functions, so if you aren't familiar with them you might want to read up on them first. +Before getting started, you should have Node.js 22 or newer installed. For this +guide, we won't use any language features that require transpilation, but we +will use some ES6 features like [Promises](http://web.dev/articles/promises/), +classes, and arrow functions, so if you aren't familiar with them you might want +to read up on them first. > Alternatively you can start from [this StackBlitz](https://stackblitz.com/edit/stackblitz-starters-znvgwr) - if you choose > this route you can skip to [Basic Types](./basic-types.mdx). -GraphQL.js v16 is the current stable release. v17 is available as a release -candidate for final testing and feedback before the stable v17 release. +GraphQL.js v17 is the current stable release. GraphQL.js v16 remains available +for projects that still need older Node.js versions. ## Setting Up Your Project -To create a new project and install the latest stable release (v16) in your +To create a new project and install the latest stable release (v17) in your current directory: ```sh npm2yarn @@ -50,11 +50,10 @@ Update your `package.json` to include `"type": "module"`: } ``` -To try the v17 release candidate instead, use Node.js 22 or newer and install -the `rc` package tag: +To install the latest v16 release instead, use the v16 package tag: ```sh npm2yarn -npm install graphql@rc --save +npm install graphql@16 --save ``` ## Writing Code diff --git a/website/pages/docs/index.mdx b/website/pages/docs/index.mdx index e92178a8d2..f55f0284aa 100644 --- a/website/pages/docs/index.mdx +++ b/website/pages/docs/index.mdx @@ -12,16 +12,14 @@ JavaScript and TypeScript. ## Start here -GraphQL.js v16 is the current stable release line, and a v17 release candidate -is available for final testing and feedback. If you are upgrading from an older +GraphQL.js v17 is the current release line. If you are upgrading from an older major version, follow each upgrade guide in sequence until you reach your target version. - **Upgrade guides:** [v14 to v15](/upgrade-guides/v14-v15), [v15 to v16](/upgrade-guides/v15-v16), [v16 to v17](/upgrade-guides/v16-v17) -- **API reference:** [v16 stable](/api-v16/graphql), - [v17 release candidate](/api-v17/graphql) +- **API reference:** [v16](/api-v16/graphql), [v17](/api-v17/graphql) - **Specification experiments:** [Experimental Specification Features](/docs/experimental-specification-features) - **GraphQL.js runtime APIs:** [GraphQL Harness](/docs/graphql-harness), diff --git a/website/pages/docs/oneof-input-objects.mdx b/website/pages/docs/oneof-input-objects.mdx index bf0b736241..e69c46d715 100644 --- a/website/pages/docs/oneof-input-objects.mdx +++ b/website/pages/docs/oneof-input-objects.mdx @@ -104,3 +104,33 @@ In GraphQL.js v17, OneOf coercion is stricter around defaults, unknown fields, `undefined`, and values that are present before coercion but invalid after coercion. Schemas that accidentally rely on ambiguous OneOf inputs should fail earlier and with clearer errors. + +## Recursive OneOf input objects + +Recursive input objects are valid only when a client can provide a finite value. +For OneOf input objects, that means at least one branch must eventually escape +the cycle through a scalar, enum, list, nullable non-OneOf field, or another +input object that can be provided a finite value. + +This schema is invalid because the only possible value for `A` points back to +`A`: + +```graphql +input A @oneOf { + self: A +} +``` + +Add a real escape branch or move the recursive shape into a nullable field on a +regular input object: + +```graphql +input A @oneOf { + id: ID + nested: NestedA +} + +input NestedA { + value: A +} +``` diff --git a/website/pages/upgrade-guides/v14-v15.mdx b/website/pages/upgrade-guides/v14-v15.mdx index 1aacaf4017..c77fc14f0a 100644 --- a/website/pages/upgrade-guides/v14-v15.mdx +++ b/website/pages/upgrade-guides/v14-v15.mdx @@ -10,11 +10,9 @@ import { Callout } from 'nextra/components'; # What Changed in GraphQL.js v15 - GraphQL.js v15 is an older release line. GraphQL.js v16 is the current stable - release line, and a v17 release candidate is available for final testing and - feedback. If you are upgrading from v14, use this guide first, then continue - through [v15 to v16](/upgrade-guides/v15-v16) and [v16 to - v17](/upgrade-guides/v16-v17). + GraphQL.js v15 is an older release line. If you are upgrading from v14, use + this guide first, then continue through [v15 to v16](/upgrade-guides/v15-v16) + and [v16 to v17](/upgrade-guides/v16-v17). GraphQL.js v15 is mainly a compatibility cleanup and SDL modernization release. diff --git a/website/pages/upgrade-guides/v15-v16.mdx b/website/pages/upgrade-guides/v15-v16.mdx index 6bbd23a4c4..7e77392428 100644 --- a/website/pages/upgrade-guides/v15-v16.mdx +++ b/website/pages/upgrade-guides/v15-v16.mdx @@ -10,11 +10,8 @@ import { Callout } from 'nextra/components'; # What Changed in GraphQL.js v16 - GraphQL.js v16 is the current stable release line on npm, and a v17 release - candidate is available for final testing and feedback. If you are upgrading - from v15, use this guide first, then continue with [v16 to - v17](/upgrade-guides/v16-v17) when you are ready to test the release - candidate. + GraphQL.js v16 is an older release line. If you are upgrading from v15, use + this guide first, then continue with [v16 to v17](/upgrade-guides/v16-v17). GraphQL.js v16 has been the stable major release line since 2021. Upgrading diff --git a/website/pages/upgrade-guides/v16-v17.mdx b/website/pages/upgrade-guides/v16-v17.mdx index b999768c51..ee036366f1 100644 --- a/website/pages/upgrade-guides/v16-v17.mdx +++ b/website/pages/upgrade-guides/v16-v17.mdx @@ -10,9 +10,9 @@ import { Callout } from 'nextra/components'; # What Changed in GraphQL.js v17 - GraphQL.js v17 has a release candidate available for final testing and - feedback. Use this guide to prepare v16 projects for testing the - release-candidate line. + GraphQL.js v17 is the current release line. Use this guide to move v16 + projects onto v17 and to review compatibility work before adopting optional + v17 features. GraphQL.js v17 keeps the core programming model: build a schema, parse a @@ -175,10 +175,10 @@ GraphQL.js runtime APIs. This guide is for projects that depend on GraphQL.js, including applications, servers, libraries, and tools. It compares the latest v16 release line with the -current v17 release candidate, and focuses on differences you will see when -testing that RC from an up-to-date v16 project. If a change is already present -in both lines, including v17 work that also shipped in v16, it is not listed -here as v16-to-v17 migration work. +current v17 release line, and focuses on differences you will see when moving +from an up-to-date v16 project. If a change is already present in both lines, +including v17 work that also shipped in v16, it is not listed here as +v16-to-v17 migration work. Changes described below use these labels: @@ -721,6 +721,16 @@ are now `Boolean! = false`. The `includeDeprecated` argument on should omit the argument or pass a Boolean value; queries that pass `includeDeprecated: null` to those fields are invalid in v17. +**Behavioral tightening.** Input object cycle validation now checks whether an +input object can be provided any finite value. This preserves the existing +non-null input-object cycle checks and also rejects recursive OneOf input +objects where every possible branch leads back into the same unbreakable input +object cycle. + +**Behavioral tightening.** SDL directive validation now applies directive +location rules consistently to field, argument, and input-field definitions +inside type and input-object extensions. + ### Programmatic schema APIs **New stable API.** v17 exposes TypeScript schema element types and runtime @@ -960,6 +970,11 @@ separated from behavior changes. directives and directive extensions are now parsed by default. - Update built-in scalar tests for JavaScript `bigint` values if your host passes `bigint` values directly. +- Fix input-object cycles that cannot produce a finite value, including + recursive OneOf input objects with no scalar, enum, list, or nullable escape + branch. +- Audit directives on type extensions; v17 validates directive locations on + extension fields, arguments, and input fields consistently with definitions. ### Execution and subscriptions