v12.0.0

Relay Release Notes - 12.0.0

Commits: v11.0.2...main

About the Release

This is release contains a long list of new fixes and additions to Relay that was added in the last few months: runtime optimizations, react integration updates, logger updates, internal type-safety, documentation updates, and more.

It also contains a few small, but possibly, breaking changes. One of which is related to the Abstract Type Refinement, others to the live query behavior.

The Relay team is continuing work on the new rust-version of the compiler, and VS Code extension. As well as experimenting with the new features: multi-environment runtime support, advanced client-state management APIs. We hope to include these in the upcoming releases.

Thanks to all contributors for your work and support!

Breaking

• Relay Runtime: Promote type refinement to default feature (no flag). In OSS this flag was false by default, but true in internal configuration [2732db5].
• useQueryLoader will not cancel network requests, except for live queries [211d6fe].
• useLazyLoadQuery will not cancel network requests, except for live queries [a75da57].

Added

• Add Suspense logging to Relay Network Logger.
• Add log event for when QueryResource suspends.
• Add suspense logging when suspending from containers.
• Add log event for when FragmentResource suspends.
• Website: First draft of Relay Compiler Playground.
• React: Support double invoking effects in QueryRenderer.
• Runtime: Enabled unique subscription root: every response received is now processed in a unique Relay store root.
• Runtime: Enable batched store updates by default.
• Runtime: FragmentResource store revision optimization.
• Add Suspense logging to Relay Network Logger.
• Add execute.* events to the Relay Logger.
• Expose various hooks utils from relay-runtime: getPaginationMetadata, getPaginationVariables, getRefetchMetadata, getValueAtPath, type Direction [3b6f70d].

Fixed

• React: Subscribe on commit in pagination container.
• React: Actually subscribe on commit in fragment and refetch containers.
• React: Prevent tearing in refetch container between render and commit.
• React: Flip useTransition tuple.
• React: Update relay useTransition tests.
• Don’t keep unnecessary ref to props in FragmentSpecResolver.
• Fix memory leak in containers [5a0c4c6].
• Fix Relay Dev Tools network events.
• Fix throwing promise from RelayModernFragmentSpecResolver.
• Add improved type safety to useSubscription API.
• OperationTracker now exposes pending operations affecting owner; display name for suspense promises are more accurate.
• Do not re-throw errors for incremental payloads that may invalidate the whole query.
• Runtime: Make RelayPublishQueue.run a no-op if no pending updates.
• Runtime: Ship FragmentResource store revision optimization.
• Check if global exists before calling ErrorUtils (#3465).
• Fix double _publishQueue.run() in OperationExecutor.
• Use the provided requestSubscription fn in useSubscription.
• Code Cleanup: Remove RecordSource/RecordSourceMapImpl indirection.
• Remove duplicated active observable tracking in _processModuleImportPayload.
• Do not emit extension in compiler includes (#3518).
• Check if global exists before using it (#3525).
• Improve handling of falsy conditions and @Skip.
• Fix a bug in RelayReplaySubject that caused indefinite suspense in React double invoke.
• Do not read from the store if no onNext callback is provided.
• Make createOperationDescriptor type safe.
• Set unique root ID before processing a non-incremental payload.
• Track store writeEpoch in FragmentResource.
• Update updater docs to include payload.
• Small optimization in RelayPublishQueue [6b95ff8].
• Reduce FragmentResource memory usage [bd35151].
• Avoid calling environment.lookup when not needed in QueryResource.
• Release redundant temporary retains when the component commits.
• Support batched responses in RelayResponseCache.
• OperationTracker now exposes pending operations affecting owner; display name for suspense promises are more accurate.
• Rename QueryExecutor to OperationExecutor.
• Rename transactionID to networkRequestId in log events.
• Documentation/Website/Typo Fixes: #3439, #3456, #3479, #3492, #3493, 3495 #3517, #3530, #3532, #3535, #3545, #3564, #3566, #3569, #3570, #3576, #3552, #3546, #3550, #3577.

Misc

• Update batching async module scheduling [8e3e210].
• Only batch async module payload if there is more than one pending module payload.
• Add ApplyMutation test for RelayEnvironment.
• Additional testing for applyMutation.
• CI: remove node 10 and 15, add node 16 (#3466).
• Bump lodash from 4.17.20 to 4.17.21 in /packages/babel-plugin-relay (#3482).
• Bump path-parse from 1.0.6 to 1.0.7 in /packages/babel-plugin-relay (#3559).
• Update React flow types.
• Add disallowWarnings(...) to some Relay unit-tests.
• Remove useCustomizedBatch from runtime.

v11.0.2

Added

• Add Relay CodeSandbox to website [f71d1e2]
• Add onSubscribe to CacheConfig [0451857]
• Create operation description with correct cache config in usePreloadedQuery [e0713aa]

Improvements

• Documentation Improvements: (#3446), (#3444), (#3440), [1a50269], [e24c5b3], (#3424), (#3434), (#3420), [509f72b], [6ff9413], [954681d], (#3435), (#3436), (#3439), [cacce8c], (#3456), (#3453)
• Improve suspense promise displayName [47be7d6]
• Make operationTracker required in QueryExecutor
• Reduce some boilerplate in RelayModernEnvironment
• Improved warning reporting in Relay Unit-tests
• Batch store updates to once per event [07d5f49]

Fixed

• Fix onNext callback in requestSubscription [579b8f2]

Misc

• Rename QueryExecutor to OperationExecutor
• Remove RelayProfiler from RelayResponseNormalizer.normalize [6294195]
• Drop RelayModern prefix from QueryExecutor [edef218]
• Remove RelayProfiler from RelayModernStore.prototype.lookup and RelayProfiler.instrumentMethods [f486653]
• RelayProfiler no longer skips methods starting with @ [1bfa996]
• Remove RelayProfiler.instrument [cc2758b]
• Remove support for "*" profile event [6e18b96]
• Rename areEqual{OSS => ArgValues} [b8d2694]
• Remove fbjs/lib/ErrorUtils Dependency [5ed076e]
• Remove mapObject [4645888]
• Export type for RequiredFieldLogger [5a5f5c7]
• Replace fbjs/lib/invariant with invariant (#3448) [3982f9d]

v11.0.1

Fixed

• Fixed several broken website redirects
• Store updater directives: do not insert existing node again in connection (#3373)

Documentation Improvements:

This release contains a set of updates to the new Relay website. Some of the PRs are listed here explicitly.
Thank you for your contributions.

• Replace preloadQuery with loadQuery (#3412)
• Remove mutation from the server specification (#3381)
• Fix markdown issue in fragments.md (#3408)
• Fix typos in loading-states.md (#3411)
• Fix typos in docs (#3400)
• Fix typo in the code example in "Introducing Relay Hooks" (#3399)
• Update use-mutation.md (#3393)
• Updated load-query.md (#3391)
• Update use-pagination-fragment.md (#3392)
• Fix typos in the "Introducing Relay Hooks" blog post (#3394)
• Thinking-in-graphql.md small typo (#3386)
• Fixes typo in docs (#3389)
• Switch text under headings to be <p> (#3385)
• Fix markdown issue in use-preloaded-query.md (#3384)
• Use updated Flow object syntax (#3387)

v11.0.0

For our announcement on Relay Hooks, check out our blog posts on relay.dev and Facebook Open Source. For docs, see our updated docs website at relay.dev/docs, and for an update on our upcoming releases, see this issue.

Breaking

• New version of fetchQuery:
  • New: New version of fetchQuery now returns a lazy Observable which you can subscribe to. It will perform in-flight request de-duping of identical requests. Ignores any Network Layercaching by default, but supports a [fetchPolicy](https://relay.dev/docs/en/experimental/a-guided-tour-of-relay#fetch-policies) to check data cached in the Relay Store.
  • Deprecated: Previous version of fetchQuery renamed to **** fetchQuery_DEPRECATED. Previous behavior returns a Promise (can’t be observed). No request de-duping.
  • Changes in Exports:
    • react-relay: fetchQuery exported from react-relay now has updated behavior and function signature. To access previous version of fetchQuery, import fetchQuery_DEPRECATED from react-relay or react-relay/legacy.
    • relay-runtime: fetchQuery exported from relay-runtime now has updated behavior and function signature. To access previous version of fetchQuery, import fetchQuery_DEPRECATED from relay-runtime.
• getDataID was renamed from UNSTABLE_DO_NOT_USE_getDataID. This config option is now stable. It can be passed to the Relay Environment and Relay Store as an option that will be used to compute the Data ID for the given record.
• Default value for gcReleaseBufferSize is now 10 (previously 0).
  • When a query is manually released, for example when a query component unmounts (QueryRenderer or useLazyLoadQuery), Relay will temporarily retain the query in the “release buffer” until the buffer is full. With a buffer size of 0, released queries would not go into the buffer and would be immediately removed from the store cache.
  • With a default buffer size of 10, this means that queries will remained cached in the store for a longer period of time after they unmount, which allows fetch policies like store-or-network. to actually reuse cached data when navigating back to previously visited views.

If upgrading from experimental release

• The default UNSTABLE_renderPolicy is now always “partial”. We don’t expect this to produce any issues, and will only affect you if you are upgrading from an experimental release. This option can still be configured, but we will completely remove it in the upcoming releases.

Added

Relay Hooks

• New Relay Hooks APIs added to react-relay and react-relay/hooks. See this issue for more details.
  • relay-experimental has been removed from the source code, and no new experimental builds will be published to npm.
  • We will share more external communications with the community as well as publish our updated docs once a stable release is published.
• New version of fetchQuery added. See description in Breaking Changes.

General

• Added ConnectionHandler.getConnectionID to make it easier to get a connection ID for usage in updaters or declarative connection mutations (@kyarik: #3332)

Improvements

If upgrading from experimental release

• Hooks are now resilient to React effects being re-invoked (e.g. during Fast Refresh).
• Un-actionable warning that fired when fragment data was missing without being fetched has been removed.
• loadQuery accepts a fetchPolicy of 'store-only'
• loadQuery now warns, instead of throwing, if called during the render phase.

General

• getDataID is now a stable config option. See description in Breaking Changes.
• Default value for gcReleaseBufferSize is now 10. See description in Breaking Changes.
• ConnectionHandler will no longer create edges with an undefined cursor field. This also applies to edges created via @appendNode or @prependNode. (#3278)
• Several tests migrated to be compile their graphql with Rust Compiler.

Fixed

If upgrading from experimental release

• If loadQuery is called and no network request is made (i.e. if the data is available in the store and the fetch policy allows it), the query is retained in the environment.
• loadQuery now includes the network cache config in the operation descriptor that is executed against the environment.

v11.0.0-rc.0

To install, run:

npm install react-relay@dev relay-runtime@dev
npm install relay-compiler@dev babel-plugin-relay@dev --dev

See this issue for more details on upcoming releases. We will publish our updated docs and website with the next stable release, along with additional external communications with the community.

The new docs will be more comprehensive, and are still are ongoing updates. In the meantime, in order to access some documentation for the APIs in this RC, you can access our current experimental docs, or manually build the docs in website-v2.

Breaking

• New version of fetchQuery:
  • New: New version of fetchQuery now returns a lazy Observable which you can subscribe to. It will perform in-flight request de-duping of identical requests. Ignores any Network Layer caching by default, but supports a fetchPolicy to check data cached in the Relay Store.
  • Deprecated: Previous version of fetchQuery renamed to fetchQuery_DEPRECATED. Previous behavior returns a Promise (can’t be observed). No request de-duping.
  • Changes in Exports:
    • react-relay: fetchQuery exported from react-relay now has updated behavior and function signature. To access previous version of fetchQuery, import fetchQuery_DEPRECATED from react-relay or react-relay/legacy.
    • relay-runtime: fetchQuery exported from relay-runtime now has updated behavior and function signature. To access previous version of fetchQuery, import fetchQuery_DEPRECATED from relay-runtime.
• getDataID was renamed from UNSTABLE_DO_NOT_USE_getDataID. This config option is now stable. It can be passed to the Relay Environment and Relay Store as an option that will be used to compute the Data ID for the given record.
• Default value for gcReleaseBufferSize is now 10 (previously 0).
  • When a query is manually released, for example when a query component unmounts (QueryRenderer or useLazyLoadQuery), Relay will temporarily retain the query in the “release buffer” until the buffer is full. With a buffer size of 0, released queries would not go into the buffer and would be immediately removed from the store cache.
  • With a default buffer size of 10, this means that queries will remained cached in the store for a longer period of time after they unmount, which allows fetch policies like store-or-network to actually reuse cached data when navigating back to previously visited views.

If upgrading from experimental release

• The default UNSTABLE_renderPolicy is now always “partial”. We don’t expect this to produce any issues, and will only affect you if you are upgrading from an experimental release. This option can still be configured, but we will completely remove it in the upcoming stable release.

Added

Relay Hooks

• New Relay Hooks APIs added to react-relay and react-relay/hooks. See this issue for more details.
  • relay-experimental has been removed from the source code, and no new experimental builds will be published to npm.
  • We will share more external communications with the community as well as publish our updated docs once a stable release is published.
• New version of fetchQuery added. See description in Breaking Changes.

General

• Added ConnectionHandler.getConnectionID to make it easier to get a connection ID for usage in updaters or declarative connection mutations (@kyarik: #3332)

Improvements

If upgrading from experimental release

• Hooks are now resilient to React effects being re-invoked (e.g. during Fast Refresh).
• Un-actionable warning that fired when fragment data was missing without being fetched has been removed.
• loadQuery accepts a fetchPolicy of 'store-only'
• loadQuery now warns, instead of throwing, if called during the render phase.

General

• getDataID is now a stable config option. See description in Breaking Changes.
• Default value for gcReleaseBufferSize is now 10. See description in Breaking Changes.
• ConnectionHandler will no longer create edges with an undefined cursor field. This also applies to edges created via @appendNode or @prependNode. (#3278)
• Several tests migrated to be compile their graphql with Rust Compiler.

Fixed

If upgrading from experimental release

• If loadQuery is called and no network request is made (i.e. if the data is available in the store and the fetch policy allows it), the query is retained in the environment.
• loadQuery now includes the network cache config in the operation descriptor that is executed against the environment.

10.1.3

Improvements

• Improve testing documentation grammar (#3296)
• Support multiple edges in @appendEdge and @prependEdge [2425572]

Fixed

• Display code context for single error, fixes #3318 (#3322)
• Fix accidental cancelation of network request when using loadQuery APIs [20e8b6b]
• loadQuery dedupes requests even before AST is available [4527a5b]

Misc

• Documentation fixes and improvements (#3327)
• Remove "use strict" directive from ES modules [5d555a4]
• Bump node-notifier from 8.0.0 to 8.0.1 (#3301)
• Convert RelayReader-test.js to use new compiler [c0f0f10]
• Convert ReactRelayFragmentContainer-WithFragmentOwnership-test.js to use the new compiler [ff0ad17]
• Convert ReactRelayPaginationContainer-test.js to use the new compiler [bede32d]
• Convert ReactRelayRefetchContainer-WithFragmentOwnership-test to use the new compiler [20051f6]

10.1.2

Improvements

• Avoid throwing in the DeclarativeMutationHandler when the server returns null [9d31dfb]
• Remove old network event names [5075851]

Fixed

• Bump ini from 1.3.5 to 1.3.7 (#3293)
• Bump ini from 1.3.5 to 1.3.7 in /website (#3292)
• Fix code example typo in homepage (#3290)

10.1.1

Improvements

• Mark failed network requests on preloaded query references (f59d71249)
• Refactor notifying store subscriptions for better consistency update perf (under feature flag) (ad6532807)

Fixed

• Require babel helpers instead of inlining (#3188)
• Ensure network requests are always logged (95606c5ed)
• Memoize the cache config in useMemoOperationDescriptor (81d24d21a)
• Remove unstable_next from useLoadMoreFunction (3242c5800)

Misc

• Add missing peer dependency in website/package.json (#3262)
• Add missing copyright headers (bc55eb6c8)
• Refine typescript type generation (#3239)
• Extract store subscription management into separate module (d64b57987)
• Remove link to GraphCool from prerequisites page (#3173)
• Update website/i18n/en.json (#3261)

10.1.0

Added

• Added @appendNode and @prependNode declarative mutation directives for inserting a node to connections (#3155) [0fe732d]
  • Usage: comments @appendNode(connections: $connections, edgeTypeName: "CommentEdgeType") { id }
• Added @deleteEdge directive for removing the edge from connections (#3177) [01d65b3]
  • Usage: deletedCommentId @deleteEdge(connections: $connections)
• Added plural support for @deleteRecord directive (#3135) [27f938c]
  • Usage: deletedCommentIds @deleteRecord
• Made scheduleGC a public function inside RelayModernStore (#3167) [97401cb]
• Added cacheConfig in RequestDescriptor (#3070) … [eb256a3]

Improvements

• Remove fragment naming enforcement from JS compiler [ff1c10b]

Fixed

• Docs: fix typos of the 'A Guided Tour' page (#3236) [e4413bf]
• Fix prependNode and prependEdge in declarative connection [7c836df]
• Fix warning for plural fragment ref pointing to null data [c1a6831]
• Don't setTimeout in loadQuery in SSR [2da0325]
• Fix @match with __typename: other in MatchContainer [92c8d68]
• Fix conflicting field value warning [7e3deb4]
• Bugfix for validating optimistic updates containing undefined fields … [6a1586d]
• Dispose nested entrypoints when calling dispose() [d5352a2]

Misc

• In @relay/react-relay, we now use ^16.9.0 || ^17 as a peerDependency.

Experimental

• Added various minor improvements and fixes to the loadQuery API.
• useQueryLoader now accepts an initial query reference.
• Prevent usePreloadedQuery from consuming stale cached query refs
• Stop caching errors at fragment boundaries, which prevented
• Warn when attempting to use an already disposed PreloadedQuery or PreloadedEntryPoint [187bd34]
• Make sure loadQuery requests are deduped when started (vs at render time) [a21b1cb]
• Add Relay log event for when an EntryPointContainer uses an entrypoint component resource [7818bfb]
• Create type utility EntryPointElementConfig [7d02240]
• Unsubscribe network requests when releasing temporary retains [933b280]
• Optimize getFragmentIdentifier [ac3a252]
• holdGC for incremental responses in QueryExecutor [b3ecce2]

Relay Compiler in Rust

The Relay team is actively working on the new compiler implemented in Rust. The majority of recent changes you can see in the repo are related to the compiler. This new version won't be included in the release, as we are still working on the migration strategies for our OSS customers.

Thank you for all outstanding contribution to the Relay compiler (#3182)

v10.0.1

Experimental

• Remove persisted query id invariant from loadQuery (4b88a13)
• Dispose nested entrypoints when calling dispose() (d5352a2)