●Change8

v4.0.0-alpha.10

Breaking Changes
📦 apollo-client
⚠ 6 breaking✨ 9 features🐛 2 fixes🔧 16 symbols

Summary

This release introduces stricter variable handling, new error utilities, and several breaking changes such as removal of `standby` fetchPolicy and deprecation of `never` as a TVariables type.

⚠️ Breaking Changes

  • `never` is no longer supported as a valid `TVariables` generic argument for APIs that require `variables`. Use `Record<string, never>` instead.
  • `client.query` no longer supports a `fetchPolicy` of `standby`. Remove or replace this option.
  • `client.query` no longer supports `notifyOnNetworkStatusChange` in options; an error is thrown if set.
  • TypeScript now enforces required `variables` for APIs (`client.query`, `client.mutate`, `client.subscribe`, `client.watchQuery`, `useBackgroundQuery`, `useQuery`, `useSubscription`, `useSuspenseQuery`). Missing required variables will cause compile errors.
  • `ObservableQuery.variables` now returns `TVariables` (never undefined) and can be reset to empty via `reobserve({ variables: undefined })`. Code expecting `undefined` may break.
  • When passing `variables` with `undefined`, the value is replaced by the query's default value, changing previous behavior.

Migration Steps

  1. Replace any usage of `never` as TVariables with `Record<string, never>`.
  2. Remove `fetchPolicy: "standby"` from `client.query` calls or switch to watched queries.
  3. Remove `notifyOnNetworkStatusChange` from `client.query` options.
  4. Ensure all required variables are provided to client APIs; update TypeScript calls accordingly.
  5. Adjust code that relied on `ObservableQuery.variables` being possibly undefined; treat it as always defined (empty object if none).
  6. If you relied on undefined variables being kept unchanged, update to handle the new default replacement behavior.
  7. Update any custom error message formatting by overriding `CombinedGraphQLErrors.formatMessage` or `CombinedProtocolErrors.formatMessage` as needed.
  8. Use `LinkError.is` instead of custom checks to detect link chain errors.

✨ New Features

  • Ability to reset `ObservableQuery.variables` back to empty by calling `reobserve` with `variables: undefined`.
  • When `variables` are passed as `undefined`, they are replaced by the query's default values.
  • Add static `formatMessage` property on `CombinedGraphQLErrors` and `CombinedProtocolErrors` to customize error messages.
  • Add static `is` method to error types (`CombinedGraphQLErrors`, `CombinedProtocolErrors`, `ServerError`, `ServerParseError`, `UnconventionalError`) for type narrowing.
  • Add `LinkError.is` method to detect errors emitted from the link chain.
  • Enforced consistent `variables` option typing across client APIs; TypeScript will now require required variables.
  • `useLazyQuery` now returns `variables` as `Partial<TVariables>` when not called.
  • Updated error message format for `CombinedGraphQLErrors` and `CombinedProtocolErrors` to match v3.x style.
  • `ObservableQuery.variables` now returns `TVariables` instead of `TVariables | undefined` for consistency.

🐛 Bug Fixes

  • Fixed type of `variables` returned from `useLazyQuery` when `called` is false.
  • Updated error message formatting for `CombinedGraphQLErrors` and `CombinedProtocolErrors` to be more like v3.x.

🔧 Affected Symbols

ObservableQueryclient.queryCombinedGraphQLErrorsCombinedProtocolErrorsServerErrorServerParseErrorUnconventionalErrorLinkErroruseLazyQueryuseBackgroundQueryuseQueryuseSubscriptionuseSuspenseQueryclient.mutateclient.subscribeclient.watchQuery