From abb5612e144ff38c89ed209f919908503abe335f Mon Sep 17 00:00:00 2001
From: Jerel Miller <jerelmiller@gmail.com>
Date: Wed, 6 Aug 2025 20:40:49 -0600
Subject: [PATCH 01/13] Add AI release notes

---
 release-notes.md | 226 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 226 insertions(+)
 create mode 100644 release-notes.md

diff --git a/release-notes.md b/release-notes.md
new file mode 100644
index 00000000000..4564844ceb6
--- /dev/null
+++ b/release-notes.md
@@ -0,0 +1,226 @@
+# Apollo Client v4.0 Release Notes
+
+Apollo Client v4 represents our most significant release yet, featuring comprehensive improvements to error handling, TypeScript support, and developer experience. This release modernizes the codebase while maintaining the powerful GraphQL client capabilities you rely on.
+
+## Major Themes
+
+### Enhanced Error Handling
+
+Apollo Client v4 completely reimagines error handling with a new, more granular error system that replaces the monolithic `ApolloError` class.
+
+**Key Changes:**
+- **Specialized Error Classes**: Errors are now categorized into distinct types:
+  - `CombinedGraphQLErrors` for GraphQL errors (replacing `graphqlErrors`)
+  - Network errors are passed through directly without wrapping
+  - `CombinedProtocolErrors` for transport-level errors
+- **Type-Safe Error Handling**: Use `instanceof` checks to handle specific error types
+- **Improved Error Wrapping**: String errors are automatically wrapped in `Error` instances, and non-error objects are wrapped in `UnknownError` with a `cause` property
+- **GraphQL over HTTP Spec Compliance**: Full support for `application/graphql-response+json` media type with stricter adherence to the GraphQL over HTTP specification
+
+**Migration Example:**
+```typescript
+// Apollo Client v3
+if (error instanceof ApolloError) {
+  console.log(error.graphQLErrors);
+  console.log(error.networkError);
+}
+
+// Apollo Client v4
+if (error instanceof CombinedGraphQLErrors) {
+  console.log(error.graphQLErrors);
+} else if (error instanceof NetworkError) {
+  console.log(error.message);
+}
+```
+
+### TypeScript Improvements
+
+Apollo Client v4 delivers substantial TypeScript enhancements that improve type safety and developer experience.
+
+**dataState Type System Overhaul:**
+- The `TData` generic is no longer modified by the `DataState` generic
+- Type narrowing is now more precise and predictable
+- New type signature pattern: `QueryRef<TData, TVariables, 'partial'>` instead of `QueryRef<DeepPartial<TData>, TVariables>`
+
+**Context Type Extensions:**
+- Define types for `context` passed to the link chain using declaration merging
+- Built-in support for `HttpLink.ContextOptions` and `BatchHttpLink.ContextOptions`
+
+**Namespace Organization:**
+- Link types now live on the `ApolloLink` namespace
+- MockLink types moved to the `MockLink` namespace
+- Cleaner, more discoverable API surface
+
+**Type Override System:**
+- New `DataValue` namespace with `Complete`, `Streaming`, and `Partial` types
+- Support for data masking type overrides
+- Extensible type system for custom implementations
+
+### The New `dataState` Property
+
+The `dataState` property is a powerful new addition that provides clear visibility into the completeness of your query results.
+
+**Values:**
+- `empty`: No data available (`data` is `undefined`)
+- `partial`: Incomplete data from cache when `returnPartialData` is `true`
+- `streaming`: Incomplete data from a deferred query still streaming
+- `complete`: Fully satisfied query result
+
+**Benefits:**
+- **Type Narrowing**: The `dataState` property helps TypeScript narrow the type of the `data` property
+- **Clear Data Status**: No more guessing about whether your data is complete or partial
+- **Better Developer Experience**: Available on `ObservableQuery` and all React hooks returning `data`
+
+**Example:**
+```typescript
+const { data, dataState } = useQuery(MY_QUERY);
+
+if (dataState === 'complete') {
+  // TypeScript knows data is fully typed here
+  console.log(data.allFields);
+} else if (dataState === 'partial') {
+  // TypeScript knows data might be missing fields
+  console.log(data?.someField);
+}
+```
+
+### `@defer` Support Evolution
+
+Apollo Client v4 introduces a pluggable incremental delivery system for the `@defer` directive.
+
+**Pluggable Implementation:**
+- Configure incremental delivery through the `incrementalHandler` option
+- Ships without a default implementation for maximum flexibility
+- Available handlers:
+  - `NotImplementedHandler` (default)
+  - `Defer20220824Handler` (Apollo Router format)
+  - `GraphQL17Alpha2Handler` (GraphQL 17.0.0-alpha.2 format)
+
+**HTTP Multipart Improvements:**
+- Stricter error handling for connection issues
+- Better handling of non-WhatWG response bodies
+- Improved reliability for long-running deferred queries
+
+### Local State Management Enhancements
+
+Local state management in Apollo Client v4 has been completely revamped for better reliability and type safety.
+
+**Resolver System Overhaul:**
+- Errors thrown in resolvers now set the field to `null` and add to the `errors` array
+- Remote results are dealiased before being passed to resolvers
+- New `context` function for customizing `requestContext`
+- `Resolvers` generic provides autocompletion and type checking
+
+**Breaking Change - Resolver Context:**
+The resolver `context` argument (3rd argument) has been restructured:
+```typescript
+// Apollo Client v3
+const resolver = (parent, args, context, info) => {
+  const { cache } = context;
+};
+
+// Apollo Client v4
+const resolver = (parent, args, context, info) => {
+  const { client, requestContext, phase } = context;
+  const cache = client.cache;
+};
+```
+
+**New Codegen Plugin:**
+- `@apollo/client-graphql-codegen` package for creating resolver types
+- Type-safe resolver development
+- Tailored specifically for `LocalState` usage
+
+## Additional Improvements
+
+### React Integration Changes
+
+**React Exports Migration:**
+All React-related exports have moved to dedicated entrypoints:
+- Main exports: `@apollo/client/react`
+- Testing utilities: `@apollo/client/testing/react`
+
+This change allows core client usage without requiring React as a dependency.
+
+### Modern Package Format
+
+- Ships both ESM and CJS formats
+- Modern runtime target (browserslist: "since 2023, node >= 20, not dead")
+- Improved tree-shaking with proper `exports` field
+- Development/production export conditions instead of `globalThis.__DEV__`
+- Fixed source maps for better debugging
+
+### RxJS as Observable Implementation
+
+- Migrated from `zen-observable` to RxJS
+- RxJS is now a peer dependency
+- Full RxJS operator support
+- Links using observables must use `.pipe(map())` instead of `.map()`
+
+### Link System Improvements
+
+**Class-Based Links:**
+All links are now available as classes, with creator functions deprecated:
+```typescript
+// Apollo Client v3
+const link = createHttpLink({ uri: '/graphql' });
+
+// Apollo Client v4
+const link = new HttpLink({ uri: '/graphql' });
+```
+
+**Enhanced Client Awareness:**
+- `HttpLink` and `BatchHttpLink` automatically send client library information
+- New `ClientAwarenessLink` for custom implementations
+- Can be disabled with `enhancedClientAwareness: { transport: false }`
+
+### Cache and Query Enhancements
+
+- **ObservableQuery Lifecycle**: Queries only registered while they have subscribers
+- **fetchMore Improvements**: Better option inheritance and variable handling
+- **InMemoryCache**: Fields with empty argument objects stored same as fields without arguments
+- **Promise-based API Cleanup**: Removed `loading` and `networkStatus` from promise resolutions
+
+### Testing Improvements
+
+**MockLink Enhancements:**
+- Default `delay` configuration (global and per-instance)
+- New `realisticDelay` helper for realistic network simulation
+- Improved variable matching with callback support
+
+**Testing Utilities:**
+- Internal utilities moved to `@apollo/client/testing/internal`
+- Cleaner, more stable testing API
+
+### Network and Fetch Requirements
+
+- Requires WhatWG ReadableStream specification compliance
+- No longer supports Node Streams or Async Iterators as `Response.body`
+- Better abort signal handling
+- WebSocketLink deprecation warning added
+
+### SSR Improvements
+
+- `disableNetworkFetches` renamed to `prioritizeCacheValues`
+- Better handling of fetch policies during SSR
+- Improved hydration behavior
+
+## Breaking Changes Summary
+
+Apollo Client v4 includes breaking changes that require migration. The most significant include:
+
+1. **Error System**: Replace `ApolloError` checks with specific error class checks
+2. **React Exports**: Update imports from `@apollo/client` to `@apollo/client/react`
+3. **Link Classes**: Replace creator functions with class constructors
+4. **ApolloClient Constructor**: `link` option is now required
+5. **Resolver Context**: Update resolver signatures to use new context structure
+6. **RxJS Migration**: Update observable transformations to use `.pipe()`
+7. **Type System**: Update type signatures for `dataState` changes
+
+## Migration Resources
+
+For detailed migration guides and examples, visit our documentation at [apollographql.com/docs/react/migrating/apollo-client-4-migration](https://www.apollographql.com/docs/react/migrating/apollo-client-4-migration).
+
+## Acknowledgments
+
+This release represents months of work from the Apollo Client team and our amazing community. Thank you to all our contributors who helped make Apollo Client v4 the best version yet!
\ No newline at end of file

From a79d3f273b0e8909144a0ff606f454811c3d5d7d Mon Sep 17 00:00:00 2001
From: Jeff Auriemma <bignimbus@users.noreply.github.com>
Date: Mon, 11 Aug 2025 06:52:01 -0400
Subject: [PATCH 02/13] Address accuracy issues

---
 release-notes.md | 45 ++++++++++++++++++++++++++++++++++++---------
 1 file changed, 36 insertions(+), 9 deletions(-)

diff --git a/release-notes.md b/release-notes.md
index 4564844ceb6..172f94a0070 100644
--- a/release-notes.md
+++ b/release-notes.md
@@ -11,10 +11,10 @@ Apollo Client v4 completely reimagines error handling with a new, more granular
 **Key Changes:**
 - **Specialized Error Classes**: Errors are now categorized into distinct types:
   - `CombinedGraphQLErrors` for GraphQL errors (replacing `graphqlErrors`)
-  - Network errors are passed through directly without wrapping
+  - Network errors are passed through directly as-is (no wrapper class)
   - `CombinedProtocolErrors` for transport-level errors
 - **Type-Safe Error Handling**: Use `instanceof` checks to handle specific error types
-- **Improved Error Wrapping**: String errors are automatically wrapped in `Error` instances, and non-error objects are wrapped in `UnknownError` with a `cause` property
+- **Improved Error Wrapping**: String errors are automatically wrapped in `Error` instances, and non-error objects are wrapped in `UnconventionalError` with a `cause` property
 - **GraphQL over HTTP Spec Compliance**: Full support for `application/graphql-response+json` media type with stricter adherence to the GraphQL over HTTP specification
 
 **Migration Example:**
@@ -28,7 +28,10 @@ if (error instanceof ApolloError) {
 // Apollo Client v4
 if (error instanceof CombinedGraphQLErrors) {
   console.log(error.graphQLErrors);
-} else if (error instanceof NetworkError) {
+} else if (error instanceof CombinedProtocolErrors) {
+  console.log(error.protocolErrors);
+} else {
+  // Network errors and other errors are passed through as-is
   console.log(error.message);
 }
 ```
@@ -94,7 +97,7 @@ Apollo Client v4 introduces a pluggable incremental delivery system for the `@de
 - Available handlers:
   - `NotImplementedHandler` (default)
   - `Defer20220824Handler` (Apollo Router format)
-  - `GraphQL17Alpha2Handler` (GraphQL 17.0.0-alpha.2 format)
+  - `GraphQL17Alpha2Handler` (alias for Defer20220824Handler, for GraphQL 17.0.0-alpha.2 compatibility)
 
 **HTTP Multipart Improvements:**
 - Stricter error handling for connection issues
@@ -106,11 +109,33 @@ Apollo Client v4 introduces a pluggable incremental delivery system for the `@de
 Local state management in Apollo Client v4 has been completely revamped for better reliability and type safety.
 
 **Resolver System Overhaul:**
+- Resolvers have been moved from `ApolloClient` to a new `LocalState` class
+- The `resolvers` option on `ApolloClient` has been replaced with a `localState` option
 - Errors thrown in resolvers now set the field to `null` and add to the `errors` array
 - Remote results are dealiased before being passed to resolvers
 - New `context` function for customizing `requestContext`
 - `Resolvers` generic provides autocompletion and type checking
 
+**Breaking Change - Resolver Migration:**
+Resolvers must now be configured through the `LocalState` class:
+```typescript
+// Apollo Client v3
+const client = new ApolloClient({
+  cache,
+  resolvers: { /* ... */ }
+});
+
+// Apollo Client v4
+import { LocalState } from '@apollo/client/local-state';
+
+const client = new ApolloClient({
+  cache,
+  localState: new LocalState({
+    resolvers: { /* ... */ }
+  })
+});
+```
+
 **Breaking Change - Resolver Context:**
 The resolver `context` argument (3rd argument) has been restructured:
 ```typescript
@@ -139,6 +164,7 @@ const resolver = (parent, args, context, info) => {
 All React-related exports have moved to dedicated entrypoints:
 - Main exports: `@apollo/client/react`
 - Testing utilities: `@apollo/client/testing/react`
+- Note: `gql` should be imported from `@apollo/client`, not from `@apollo/client/react`
 
 This change allows core client usage without requiring React as a dependency.
 
@@ -209,13 +235,14 @@ const link = new HttpLink({ uri: '/graphql' });
 
 Apollo Client v4 includes breaking changes that require migration. The most significant include:
 
-1. **Error System**: Replace `ApolloError` checks with specific error class checks
-2. **React Exports**: Update imports from `@apollo/client` to `@apollo/client/react`
+1. **Error System**: Replace `ApolloError` checks with specific error class checks (`CombinedGraphQLErrors`, `CombinedProtocolErrors`, etc.)
+2. **React Exports**: Update imports from `@apollo/client` to `@apollo/client/react` (except `gql` which stays in `@apollo/client`)
 3. **Link Classes**: Replace creator functions with class constructors
 4. **ApolloClient Constructor**: `link` option is now required
-5. **Resolver Context**: Update resolver signatures to use new context structure
-6. **RxJS Migration**: Update observable transformations to use `.pipe()`
-7. **Type System**: Update type signatures for `dataState` changes
+5. **Local State**: Move `resolvers` from `ApolloClient` to new `LocalState` class
+6. **Resolver Context**: Update resolver signatures to use new context structure
+7. **RxJS Migration**: Update observable transformations to use `.pipe()`
+8. **Type System**: Update type signatures for `dataState` changes
 
 ## Migration Resources
 

From 0afad0e45901c2d8c03ad0fa49d5975018f88e4e Mon Sep 17 00:00:00 2001
From: Jeff Auriemma <bignimbus@users.noreply.github.com>
Date: Mon, 11 Aug 2025 07:07:45 -0400
Subject: [PATCH 03/13] Small improvements for clarity and readability

Removes puffery and adds some context for readers
---
 release-notes.md | 23 +++++++++++------------
 1 file changed, 11 insertions(+), 12 deletions(-)

diff --git a/release-notes.md b/release-notes.md
index 172f94a0070..c47788923a4 100644
--- a/release-notes.md
+++ b/release-notes.md
@@ -1,12 +1,12 @@
 # Apollo Client v4.0 Release Notes
 
-Apollo Client v4 represents our most significant release yet, featuring comprehensive improvements to error handling, TypeScript support, and developer experience. This release modernizes the codebase while maintaining the powerful GraphQL client capabilities you rely on.
+Apollo Client v4 contains comprehensive improvements to error handling, TypeScript support, and developer experience. This release modernizes the codebase and reduces bundle size while maintaining the powerful GraphQL client capabilities you rely on.
 
 ## Major Themes
 
 ### Enhanced Error Handling
 
-Apollo Client v4 completely reimagines error handling with a new, more granular error system that replaces the monolithic `ApolloError` class.
+Apollo Client v4 introduces more precise error abstractions that replace the monolithic `ApolloError` class.
 
 **Key Changes:**
 - **Specialized Error Classes**: Errors are now categorized into distinct types:
@@ -15,7 +15,6 @@ Apollo Client v4 completely reimagines error handling with a new, more granular
   - `CombinedProtocolErrors` for transport-level errors
 - **Type-Safe Error Handling**: Use `instanceof` checks to handle specific error types
 - **Improved Error Wrapping**: String errors are automatically wrapped in `Error` instances, and non-error objects are wrapped in `UnconventionalError` with a `cause` property
-- **GraphQL over HTTP Spec Compliance**: Full support for `application/graphql-response+json` media type with stricter adherence to the GraphQL over HTTP specification
 
 **Migration Example:**
 ```typescript
@@ -38,7 +37,7 @@ if (error instanceof CombinedGraphQLErrors) {
 
 ### TypeScript Improvements
 
-Apollo Client v4 delivers substantial TypeScript enhancements that improve type safety and developer experience.
+Apollo Client v4 improves type safety and developer experience through its type definitions.
 
 **dataState Type System Overhaul:**
 - The `TData` generic is no longer modified by the `DataState` generic
@@ -61,7 +60,7 @@ Apollo Client v4 delivers substantial TypeScript enhancements that improve type
 
 ### The New `dataState` Property
 
-The `dataState` property is a powerful new addition that provides clear visibility into the completeness of your query results.
+The `dataState` property provides clear visibility into the completeness of your query results.
 
 **Values:**
 - `empty`: No data available (`data` is `undefined`)
@@ -89,7 +88,7 @@ if (dataState === 'complete') {
 
 ### `@defer` Support Evolution
 
-Apollo Client v4 introduces a pluggable incremental delivery system for the `@defer` directive.
+Apollo Client v4 introduces a pluggable incremental delivery system for the `@defer` directive. This gives developers the flexibility to define which incremental delivery protocol to use, with the flexibility needed to adapt to any further specification changes.
 
 **Pluggable Implementation:**
 - Configure incremental delivery through the `incrementalHandler` option
@@ -106,7 +105,7 @@ Apollo Client v4 introduces a pluggable incremental delivery system for the `@de
 
 ### Local State Management Enhancements
 
-Local state management in Apollo Client v4 has been completely revamped for better reliability and type safety.
+Local state management in Apollo Client v4 has been revamped for modularity, reliability and type safety.
 
 **Resolver System Overhaul:**
 - Resolvers have been moved from `ApolloClient` to a new `LocalState` class
@@ -152,9 +151,8 @@ const resolver = (parent, args, context, info) => {
 ```
 
 **New Codegen Plugin:**
-- `@apollo/client-graphql-codegen` package for creating resolver types
-- Type-safe resolver development
-- Tailored specifically for `LocalState` usage
+
+This release introduces the `@apollo/client-graphql-codegen` package for creating resolver types for GraphQL Code Generator. It is tailored specifically for `LocalState` usage and allows for type-safe resolver development.
 
 ## Additional Improvements
 
@@ -166,7 +164,7 @@ All React-related exports have moved to dedicated entrypoints:
 - Testing utilities: `@apollo/client/testing/react`
 - Note: `gql` should be imported from `@apollo/client`, not from `@apollo/client/react`
 
-This change allows core client usage without requiring React as a dependency.
+In previous versions, users sometimes inadvertently imported React modules through seemingly unrelated paths.  In v4 we resolve these footguns to make it more transparent when React-only modules are being imported.
 
 ### Modern Package Format
 
@@ -224,6 +222,7 @@ const link = new HttpLink({ uri: '/graphql' });
 - No longer supports Node Streams or Async Iterators as `Response.body`
 - Better abort signal handling
 - WebSocketLink deprecation warning added
+- Full support for `application/graphql-response+json` media type with stricter adherence to the GraphQL over HTTP specification
 
 ### SSR Improvements
 
@@ -250,4 +249,4 @@ For detailed migration guides and examples, visit our documentation at [apollogr
 
 ## Acknowledgments
 
-This release represents months of work from the Apollo Client team and our amazing community. Thank you to all our contributors who helped make Apollo Client v4 the best version yet!
\ No newline at end of file
+This release represents years of work from the Apollo Client team and our amazing community. Thank you to all our contributors who helped make v4 possible!

From 1520a75b68ab9bfbe3f856ac8c4d52163793b84d Mon Sep 17 00:00:00 2001
From: Jeff Auriemma <bignimbus@users.noreply.github.com>
Date: Mon, 11 Aug 2025 07:28:39 -0400
Subject: [PATCH 04/13] Corrections and additions

* Add React Compiler section
* Clarify some existing parts of release-notes.md
---
 release-notes.md | 21 +++++++++++++++++++--
 1 file changed, 19 insertions(+), 2 deletions(-)

diff --git a/release-notes.md b/release-notes.md
index c47788923a4..827d1211781 100644
--- a/release-notes.md
+++ b/release-notes.md
@@ -88,11 +88,10 @@ if (dataState === 'complete') {
 
 ### `@defer` Support Evolution
 
-Apollo Client v4 introduces a pluggable incremental delivery system for the `@defer` directive. This gives developers the flexibility to define which incremental delivery protocol to use, with the flexibility needed to adapt to any further specification changes.
+Apollo Client v4 introduces a pluggable incremental delivery system for the `@defer` directive. This gives developers the flexibility to define which incremental delivery protocol to use without sacrificing compatibility with any further specification changes. Please note that Apollo Client 4.0 intentionally does not specifcy a default implementation since incremental delivery is still not merged into the draft GraphQL specification. Users must opt into a specific protocol version.
 
 **Pluggable Implementation:**
 - Configure incremental delivery through the `incrementalHandler` option
-- Ships without a default implementation for maximum flexibility
 - Available handlers:
   - `NotImplementedHandler` (default)
   - `Defer20220824Handler` (Apollo Router format)
@@ -166,6 +165,24 @@ All React-related exports have moved to dedicated entrypoints:
 
 In previous versions, users sometimes inadvertently imported React modules through seemingly unrelated paths.  In v4 we resolve these footguns to make it more transparent when React-only modules are being imported.
 
+**React Compiler Support (Experimental):**
+Apollo Client v4 ships with React Compiler-optimized hooks available at `@apollo/client/react/compiled`. This experimental feature provides:
+- Pre-compiled React hooks optimized by the React Compiler
+- Drop-in replacement for standard React hooks
+- Potential performance improvements in React 19+ applications
+- Same API surface as `@apollo/client/react`
+
+To use the compiled hooks:
+```typescript
+// Instead of importing from @apollo/client/react
+import { useQuery, useMutation } from '@apollo/client/react/compiled';
+
+// Use exactly the same as before - the API is identical
+const { data, loading } = useQuery(MY_QUERY);
+```
+
+Note: This is an experimental optimization. The standard `@apollo/client/react` hooks remain the recommended default for most applications.
+
 ### Modern Package Format
 
 - Ships both ESM and CJS formats

From 34e03eee234f1e9f8e2a2e5ef0331ff3f23675ea Mon Sep 17 00:00:00 2001
From: Jeff Auriemma <bignimbus@users.noreply.github.com>
Date: Tue, 19 Aug 2025 17:57:24 -0400
Subject: [PATCH 05/13] WIP - new release notes doc

---
 release-notes-v2.md | 307 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 307 insertions(+)
 create mode 100644 release-notes-v2.md

diff --git a/release-notes-v2.md b/release-notes-v2.md
new file mode 100644
index 00000000000..00b889e3aab
--- /dev/null
+++ b/release-notes-v2.md
@@ -0,0 +1,307 @@
+# Apollo Client 4.0 Release Notes
+
+Apollo Client 4.0 delivers a more modern, efficient, and type-safe GraphQL client experience through significant architectural improvements and API refinements. This release focuses on developer experience, bundle size optimization, and framework flexibility.
+
+## Key Improvements
+
+### 🎯 Framework-Agnostic Core
+Apollo Client 4.0 separates React functionality from the core library, making `@apollo/client` truly framework-agnostic. React exports now live in `@apollo/client/react`, allowing developers to use Apollo Client with any JavaScript framework without React dependencies.
+
+### 📦 Smaller Bundle Sizes
+- **Opt-in Local State Management**: The `@client` directive functionality is now opt-in via the `LocalState` class, reducing bundle size when not using local state
+- **Modern Build Target**: Transpiled to target `since 2023, node >= 20, not dead`, leveraging modern JavaScript features for better performance
+- **Improved Tree-Shaking**: Proper `exports` field in package.json enables better dead code elimination
+
+### 🔧 Enhanced TypeScript Support
+- **Namespaced Types**: Types are now colocated with their APIs (e.g., `useQuery.Options` instead of `QueryHookOptions`)
+- **Precise Return Types**: Return types accurately reflect the options passed (e.g., `returnPartialData` makes `data` type `DeepPartial<TData>`)
+- **New `dataState` Property**: Enables accurate type narrowing of query results
+- **Module Augmentation**: Custom context types via declaration merging instead of fragile generics
+
+### ⚡ Modern Observable Implementation
+Apollo Client 4.0 migrates from `zen-observable` to **RxJS**, providing:
+- Industry-standard Observable implementation
+- Rich operator ecosystem
+- Better debugging tools
+- Improved performance
+
+## Major Features
+
+### Unified Error Handling
+
+Apollo Client 4.0 completely reimagines error handling for better clarity and debugging:
+
+**Key Changes:**
+- `ApolloError` removed in favor of specific error classes
+- Network errors now respect `errorPolicy` settings
+- External errors passed through without wrapping
+- New error classes with static `.is()` methods for type checking
+
+**Error Classes:**
+- `CombinedGraphQLErrors` - GraphQL errors from the server
+- `ServerError` - Non-GraphQL server errors
+- `ServerParseError` - Server response parsing errors
+- `UnconventionalError` - Wrapper for non-error thrown values
+- `LinkError` - Errors from the link chain (via `.is()` check)
+
+**Migration Example:**
+```typescript
+// Apollo Client 3
+if (error instanceof ApolloError) {
+  console.log(error.graphQLErrors);
+  console.log(error.networkError);
+}
+
+// Apollo Client 4
+import { CombinedGraphQLErrors } from "@apollo/client";
+
+if (CombinedGraphQLErrors.is(error)) {
+  console.log(error.errors); // GraphQL errors
+} else if (error) {
+  console.log(error.message); // Other errors
+}
+```
+
+### The `dataState` Property
+
+A new property that clearly indicates the completeness of query results:
+
+**Values:**
+- `empty` - No data available (`data` is `undefined`)
+- `partial` - Incomplete data from cache when `returnPartialData` is `true`
+- `streaming` - Incomplete data from a deferred query still streaming
+- `complete` - Fully satisfied query result
+
+**Benefits:**
+- Accurate TypeScript type narrowing
+- Clear loading state distinction
+- Better handling of partial results
+
+```typescript
+const { data, dataState } = useQuery(MY_QUERY);
+
+if (dataState === 'complete') {
+  // TypeScript knows data is fully populated
+  console.log(data.allFields);
+} else if (dataState === 'partial') {
+  // TypeScript knows data might be missing fields
+  console.log(data?.someField);
+}
+```
+
+### Pluggable Incremental Delivery (`@defer` Support)
+
+Apollo Client 4.0 makes incremental delivery configurable and future-proof:
+
+```typescript
+import { Defer20220824Handler } from "@apollo/client/incremental";
+
+const client = new ApolloClient({
+  // ...
+  incrementalHandler: new Defer20220824Handler(),
+});
+```
+
+**Available Handlers:**
+- `NotImplementedHandler` - Default, throws if `@defer` is used
+- `Defer20220824Handler` - Apollo Router format support (also aliased as `GraphQL17Alpha2Handler`)
+
+### Local State Management Improvements
+
+Local state is now opt-in via the `LocalState` class:
+
+```typescript
+import { LocalState } from "@apollo/client/local-state";
+
+const client = new ApolloClient({
+  cache,
+  localState: new LocalState({
+    resolvers: {
+      Query: {
+        myField: () => "Hello World",
+      },
+    },
+  }),
+});
+```
+
+**Resolver Context Changes:**
+```typescript
+// Apollo Client 3
+const resolver = (parent, args, context, info) => {
+  const { cache } = context;
+};
+
+// Apollo Client 4
+const resolver = (parent, args, context, info) => {
+  const { client, requestContext, phase } = context;
+  const cache = client.cache;
+};
+```
+
+## React-Specific Improvements
+
+### More Predictable Hooks
+
+**`useLazyQuery` Overhaul:**
+- No longer accepts `variables` or `context` options (pass to `execute` instead)
+- `execute` function only accepts `variables` and `context`
+- Cannot be called during render or SSR
+- Automatic cancellation of in-flight queries when new ones start
+
+**`useMutation` Changes:**
+- Removed `ignoreResults` option - use `client.mutate` directly for fire-and-forget mutations
+
+**`useQuery` Changes:**
+- `notifyOnNetworkStatusChange` now defaults to `true`
+- Removed deprecated `onCompleted` and `onError` callbacks
+
+### New SSR API
+
+The new `prerenderStatic` API replaces deprecated SSR functions:
+
+```typescript
+import { prerenderStatic } from "@apollo/client/react/ssr";
+
+// Works with React 19's prerender APIs
+const html = await prerenderStatic(<App />, {
+  client,
+});
+```
+
+### React Compiler Support
+
+Pre-compiled React hooks optimized by the React Compiler:
+
+```typescript
+// Use compiled hooks for potential performance improvements
+import { useQuery } from '@apollo/client/react/compiled';
+```
+
+The compiled hooks are built with React Compiler v19.1.0-rc.2 and include a runtime polyfill for compatibility with React 17+.
+
+## Link System Evolution
+
+### All Links Now Classes
+
+Migration from creator functions to classes:
+
+```typescript
+// Apollo Client 3
+import { createHttpLink, setContext } from "@apollo/client";
+const httpLink = createHttpLink({ uri: "/graphql" });
+const authLink = setContext((operation, prevContext) => {/*...*/});
+
+// Apollo Client 4
+import { HttpLink, SetContextLink } from "@apollo/client";
+const httpLink = new HttpLink({ uri: "/graphql" });
+const authLink = new SetContextLink((prevContext, operation) => {/*...*/});
+```
+
+### ErrorLink Changes
+
+```typescript
+// Apollo Client 3
+onError(({ graphQLErrors, networkError }) => {
+  // Handle errors separately
+});
+
+// Apollo Client 4
+new ErrorLink(({ error }) => {
+  if (CombinedGraphQLErrors.is(error)) {
+    // Handle GraphQL errors
+  } else if (error) {
+    // Handle other errors
+  }
+});
+```
+
+## Migration Tools
+
+### Automated Codemod
+
+Apollo Client 4.0 provides a comprehensive codemod to automate migration:
+
+```bash
+# Basic usage
+npx apollo-client-codemod-migrate-3-to-4 src
+
+# TypeScript projects (run separately)
+npx apollo-client-codemod-migrate-3-to-4 --parser ts --extensions ts src
+npx apollo-client-codemod-migrate-3-to-4 --parser tsx --extensions tsx src
+```
+
+The codemod handles:
+1. **Import updates** - Moves React imports to `@apollo/client/react`
+2. **Type migrations** - Updates types to new namespaced locations
+3. **Link updates** - Converts creator functions to classes
+4. **Removed exports** - Moves to `@apollo/client/v4-migration` with migration instructions
+
+## Breaking Changes Summary
+
+### Installation
+```bash
+# RxJS is now a peer dependency
+npm install @apollo/client graphql rxjs
+```
+
+### ApolloClient Constructor
+- `link` option is now required (no more implicit `HttpLink` creation)
+- `uri`, `headers`, `credentials` removed - use `HttpLink` directly
+- `name` and `version` moved to `clientAwareness` option
+- `resolvers` moved to `LocalState` constructor
+- `connectToDevTools` replaced with `devtools.enabled`
+- `disableNetworkFetches` renamed to `prioritizeCacheValues`
+
+### Type System
+- Removed `TContext` and `TCacheShape` generics
+- Types moved to namespaces (see migration guide for full list)
+- Custom context via module augmentation
+
+### Observable Changes
+- Requires calling `.pipe()` for transformations
+- Use RxJS operators instead of method chaining
+
+### Testing
+- `MockedProvider` now has realistic delays by default (20-50ms)
+- `createMockClient` removed - use `MockLink` directly
+
+## Performance & Build Improvements
+
+- **Modern JavaScript**: No downlevel transpilation for modern features
+- **No Polyfills**: Cleaner bundles, bring your own if needed
+- **Development Mode**: Controlled via export conditions, not global `__DEV__`
+- **ESM Support**: Proper `exports` field for better module resolution
+- **Source Maps**: Fixed and improved for better debugging
+
+## Deprecations & Removals
+
+### Removed Packages/Exports
+- React render prop components (`@apollo/client/react/components`)
+- Higher-order components (`@apollo/client/react/hoc`)
+- `@apollo/client/react/parser`
+- `@apollo/client/utilities/globals`
+
+### Removed Methods
+- `client.writeData` - use `writeQuery`/`writeFragment`
+- `ObservableQuery.result()` - use RxJS `firstValueFrom`
+- `InMemoryCache.canonizeResults` option
+
+## Upgrade Path
+
+1. **Update to Apollo Client 3.14** first for deprecation warnings
+2. **Install peer dependencies**: `npm install rxjs`
+3. **Run the codemod** to automate import and type updates
+4. **Update ApolloClient initialization** (explicit `HttpLink`, `LocalState` if needed)
+5. **Review error handling** - update to use new error classes
+6. **Test thoroughly** - especially SSR, error handling, and local state
+
+## Resources
+
+- [Migration Guide](https://www.apollographql.com/docs/react/migrating/apollo-client-4-migration)
+- [Changelog](https://github.com/apollographql/apollo-client/blob/main/CHANGELOG.md)
+- [API Reference](https://www.apollographql.com/docs/react/api)
+
+## Acknowledgments
+
+Apollo Client 4.0 represents years of community feedback and contributions. Thank you to all our contributors, early adopters, and the entire GraphQL community for making this release possible.
\ No newline at end of file

From f4c860328b494d543d8ce1bc3a2987f9303b6192 Mon Sep 17 00:00:00 2001
From: Jeff Auriemma <bignimbus@users.noreply.github.com>
Date: Tue, 19 Aug 2025 18:22:55 -0400
Subject: [PATCH 06/13] Add blog post draft

---
 apollo-client-4-blog-post.md | 85 ++++++++++++++++++++++++++++++++++++
 1 file changed, 85 insertions(+)
 create mode 100644 apollo-client-4-blog-post.md

diff --git a/apollo-client-4-blog-post.md b/apollo-client-4-blog-post.md
new file mode 100644
index 00000000000..ea03dc3d592
--- /dev/null
+++ b/apollo-client-4-blog-post.md
@@ -0,0 +1,85 @@
+# Apollo Client 4.0: a leaner and cleaner GraphQL client with no compromises
+
+Today, we're thrilled to announce the release of Apollo Client 4.0, a milestone release that delivers significant improvements in bundle size, TypeScript support, and developer experience. After extensive community feedback and months of iteration through release candidates, version 4.0 represents our most refined and performant Apollo Client yet.
+
+The JavaScript ecosystem has evolved dramatically since Apollo Client 3.0's release. Modern build tools offer sophisticated tree-shaking, the state of the art of TypeScript has significantly improved, and applications demand smaller bundles to meet Core Web Vitals targets. Apollo Client 4.0 embraces these changes while maintaining the developer experience you love.
+
+## Dramatically Smaller Bundles
+
+Bundle size has been a top concern in community feedback, and we've taken it seriously. Apollo Client 4.0 introduces opt-in architecture for features that not everyone needs. The most impactful change is making local state management opt-in. If you're not using `@client` directives for local state, you no longer carry that code in your bundle. When you do need it, importing `LocalState` from `@apollo/client/local-state` gives you the same powerful local state management you're used to, but only when you actually use it.
+
+We've also modernized our build targets. Apollo Client 4.0 ships JavaScript transpiled for browsers from 2023 and Node.js 20+, taking advantage of native language features instead of polyfills. Combined with proper ESM support and improved tree-shaking, most applications will see a **20-30%** reduction in Apollo Client's bundle size contribution. For teams fighting to stay under performance budgets, this improvement alone makes upgrading worthwhile.
+
+## TypeScript That Helps
+
+We've completely reimagined our TypeScript architecture based on a simple principle: types should be discoverable where you use them. Instead of hunting through documentation for type names, types now live alongside their APIs through namespaces. When you import `useQuery`, you get `useQuery.Options` and `useQuery.Result` right there. It's a small change that makes a big difference in day-to-day development.
+
+```typescript
+import { useQuery } from "@apollo/client/react";
+
+function UserProfile(props: {
+  userId: string;
+  options?: useQuery.Options<UserData, UserVariables>
+}) {
+  const { data, dataState } = useQuery(USER_QUERY, props.options);
+  
+  if (dataState === 'complete') {
+    // TypeScript knows data is fully populated
+    return <Profile user={data.user} />;
+  }
+  // ...
+}
+```
+
+Speaking of `dataState`, this new property solves one of the most common TypeScript frustrations with Apollo Client. Previously, determining whether `data` was partial, complete, or missing required checking multiple flags. Now, `dataState` gives you a single source of truth with four clear states: `empty`, `partial`, `streaming`, and `complete`. TypeScript can narrow types based on these states, eliminating runtime errors from accessing undefined data.
+
+## More Intuitive Error Handling
+
+Error handling in Apollo Client 3 often required developers to dig through nested properties in order to grasp what went wrong. Apollo Client 4.0 replaces the monolithic `ApolloError` with specific error classes that tell you exactly what happened. GraphQL errors from your server are now clearly distinguished from network failures or parsing errors. Each error type has static methods for type checking, making error handling both more intuitive and more type-safe.
+
+```typescript
+import { CombinedGraphQLErrors } from "@apollo/client";
+
+// Clear, specific error handling
+if (CombinedGraphQLErrors.is(error)) {
+  error.errors.forEach(e => console.log(e.message));
+} else if (error) {
+  console.error("Network error:", error.message);
+}
+```
+
+This clarity extends throughout the API. Hooks like `useLazyQuery` now have clearer boundaries about what options go where—initial options on the hook, execution options on the execute function. The `loading` state actually means loading now, with `notifyOnNetworkStatusChange` defaulting to `true` so refetches are properly reflected in your UI.
+
+## Built for Modern JavaScript
+
+Apollo Client 4.0 fully embraces modern JavaScript standards. We've migrated from `zen-observable` to RxJS, giving you access to a massive ecosystem of operators and debugging tools. RxJS is now a peer dependency, so you control the version and can share a single instance across your entire application.
+
+The move to ESM-first packaging isn't just about following trends, it delivers real benefits. Your bundler can now analyze and optimize Apollo Client code just like your own application code. Dead code elimination works properly, dynamic imports are supported, and you get better debugging with proper source maps. For teams using Vite, Webpack 5, or other modern bundlers, the improvement in build times and bundle optimization is immediately noticeable.
+
+React has never been required to use Apollo Client, but in prior versions our exported modules could sometimes muddy the waters in a way that confused non-React users. Apollo Client 4.0 addresses this friction point by making all top-level exported members completely free of React dependencies. React remains a first-class citizen with all the hooks and patterns you're familiar with, they just live in `@apollo/client/react` now.
+
+## A Smooth Migration Path
+
+We know that major version upgrades can be daunting, especially for large codebases. That's why we've invested heavily in migration tooling. Our comprehensive codemod handles the mechanical changes automatically—updating imports, converting link creator functions to classes, and migrating deprecated APIs. For most applications, you can run the codemod and be 90% done with your migration in minutes.
+
+```bash
+npx apollo-client-codemod-migrate-3-to-4 src
+```
+
+The remaining changes are typically intentional breaking changes that require human judgment, like updating error handling or choosing whether to adopt new features like the `LocalState` class. Our migration guide walks through each change with clear examples and explanations.
+
+## Looking Forward
+
+Apollo Client 4.0 is more than a bundle size reduction or API cleanup—it's a foundation for the next generation of GraphQL development. We're already seeing significant performance improvements from teams using the React Compiler-optimized hooks. The framework-agnostic core opens possibilities for deeper framework integrations. And the cleaner TypeScript architecture makes it easier for us to add new features without breaking existing code.
+
+This release wouldn't have been possible without extensive community feedback and contributions. Thank you to everyone who tested release candidates, reported issues, and helped shape Apollo Client 4.0 into what it is today.
+
+Ready to upgrade? Install Apollo Client 4.0 today:
+
+```bash
+npm install @apollo/client@latest graphql rxjs
+```
+
+For detailed upgrade instructions, check out our [migration guide](https://www.apollographql.com/docs/react/migrating/apollo-client-4-migration). For the complete list of changes, see the [changelog](https://github.com/apollographql/apollo-client/blob/main/CHANGELOG.md).
+
+Happy querying!

From 3705ed7194c2a4e58ab9a19385e3c237bf140253 Mon Sep 17 00:00:00 2001
From: Jeff Auriemma <bignimbus@users.noreply.github.com>
Date: Wed, 20 Aug 2025 10:24:39 -0400
Subject: [PATCH 07/13] Updates from code review

---
 apollo-client-4-blog-post.md | 23 +++++++++++++++++------
 1 file changed, 17 insertions(+), 6 deletions(-)

diff --git a/apollo-client-4-blog-post.md b/apollo-client-4-blog-post.md
index ea03dc3d592..b7a4c04513d 100644
--- a/apollo-client-4-blog-post.md
+++ b/apollo-client-4-blog-post.md
@@ -6,7 +6,7 @@ The JavaScript ecosystem has evolved dramatically since Apollo Client 3.0's rele
 
 ## Dramatically Smaller Bundles
 
-Bundle size has been a top concern in community feedback, and we've taken it seriously. Apollo Client 4.0 introduces opt-in architecture for features that not everyone needs. The most impactful change is making local state management opt-in. If you're not using `@client` directives for local state, you no longer carry that code in your bundle. When you do need it, importing `LocalState` from `@apollo/client/local-state` gives you the same powerful local state management you're used to, but only when you actually use it.
+Bundle size has been a top concern in community feedback, and we've taken it seriously. Apollo Client 4.0 introduces opt-in architecture for features that not everyone needs. The most impactful change is making local state management opt-in. If you're not using `@client` directives for local state, you no longer carry that code in your bundle. This same principle extends to other commonly-unused features like `HttpLink`, which is no longer bundled by default when you're using custom terminating links. When you do need these features, importing them explicitly gives you the same powerful functionality, but only when you actually use it.
 
 We've also modernized our build targets. Apollo Client 4.0 ships JavaScript transpiled for browsers from 2023 and Node.js 20+, taking advantage of native language features instead of polyfills. Combined with proper ESM support and improved tree-shaking, most applications will see a **20-30%** reduction in Apollo Client's bundle size contribution. For teams fighting to stay under performance budgets, this improvement alone makes upgrading worthwhile.
 
@@ -14,14 +14,17 @@ We've also modernized our build targets. Apollo Client 4.0 ships JavaScript tran
 
 We've completely reimagined our TypeScript architecture based on a simple principle: types should be discoverable where you use them. Instead of hunting through documentation for type names, types now live alongside their APIs through namespaces. When you import `useQuery`, you get `useQuery.Options` and `useQuery.Result` right there. It's a small change that makes a big difference in day-to-day development.
 
+But the improvements go deeper. Apollo Client 4.0 now enforces required variables at the type level—if your query has required variables, TypeScript won't let you forget them. The fragile `TContext` generic has been replaced with module augmentation for defining custom context types across your link chain. And with the new `TypeOverrides` interface, you can customize how Apollo Client handles partial data, streaming responses, and more, all while maintaining type safety.
+
 ```typescript
 import { useQuery } from "@apollo/client/react";
 
-function UserProfile(props: {
-  userId: string;
-  options?: useQuery.Options<UserData, UserVariables>
-}) {
-  const { data, dataState } = useQuery(USER_QUERY, props.options);
+// Variables are now required when the query needs them
+function UserProfile({ userId }: { userId: string }) {
+  // TypeScript error if variables are missing when required!
+  const { data, dataState } = useQuery(USER_QUERY, {
+    variables: { id: userId } // Required by TypeScript
+  });
   
   if (dataState === 'complete') {
     // TypeScript knows data is fully populated
@@ -29,6 +32,14 @@ function UserProfile(props: {
   }
   // ...
 }
+
+// Define context types once for your entire app
+declare module "@apollo/client" {
+  interface DefaultContext {
+    authToken?: string;
+    requestId?: number;
+  }
+}
 ```
 
 Speaking of `dataState`, this new property solves one of the most common TypeScript frustrations with Apollo Client. Previously, determining whether `data` was partial, complete, or missing required checking multiple flags. Now, `dataState` gives you a single source of truth with four clear states: `empty`, `partial`, `streaming`, and `complete`. TypeScript can narrow types based on these states, eliminating runtime errors from accessing undefined data.

From c1b86477add0beecd8083122c30877b58698cf38 Mon Sep 17 00:00:00 2001
From: Jeff Auriemma <bignimbus@users.noreply.github.com>
Date: Thu, 21 Aug 2025 11:13:44 -0400
Subject: [PATCH 08/13] Update apollo-client-4-blog-post.md

Co-authored-by: Lenz Weber-Tronic <lorenz.weber-tronic@apollographql.com>
---
 apollo-client-4-blog-post.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/apollo-client-4-blog-post.md b/apollo-client-4-blog-post.md
index b7a4c04513d..45af03d50a2 100644
--- a/apollo-client-4-blog-post.md
+++ b/apollo-client-4-blog-post.md
@@ -14,7 +14,7 @@ We've also modernized our build targets. Apollo Client 4.0 ships JavaScript tran
 
 We've completely reimagined our TypeScript architecture based on a simple principle: types should be discoverable where you use them. Instead of hunting through documentation for type names, types now live alongside their APIs through namespaces. When you import `useQuery`, you get `useQuery.Options` and `useQuery.Result` right there. It's a small change that makes a big difference in day-to-day development.
 
-But the improvements go deeper. Apollo Client 4.0 now enforces required variables at the type level—if your query has required variables, TypeScript won't let you forget them. The fragile `TContext` generic has been replaced with module augmentation for defining custom context types across your link chain. And with the new `TypeOverrides` interface, you can customize how Apollo Client handles partial data, streaming responses, and more, all while maintaining type safety.
+But the improvements go deeper. Apollo Client 4.0 now enforces required variables at the type level — if your query has required variables, TypeScript won't let you forget them. The fragile `TContext` generic has been replaced with module augmentation for defining custom context types across your link chain. And with the new `TypeOverrides` interface, you can customize how Apollo Client handles partial data, streaming responses, and more, all while maintaining type safety.
 
 ```typescript
 import { useQuery } from "@apollo/client/react";

From bf7380fd16ec36c0b955a9c99f3f19b18eaa4941 Mon Sep 17 00:00:00 2001
From: Jerel Miller <jerelmiller@gmail.com>
Date: Thu, 21 Aug 2025 11:08:48 -0600
Subject: [PATCH 09/13] Review suggestions

Co-authored-by: Lenz Weber-Tronic <lorenz.weber-tronic@apollographql.com>
---
 apollo-client-4-blog-post.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/apollo-client-4-blog-post.md b/apollo-client-4-blog-post.md
index 45af03d50a2..cccb893b89a 100644
--- a/apollo-client-4-blog-post.md
+++ b/apollo-client-4-blog-post.md
@@ -59,7 +59,7 @@ if (CombinedGraphQLErrors.is(error)) {
 }
 ```
 
-This clarity extends throughout the API. Hooks like `useLazyQuery` now have clearer boundaries about what options go where—initial options on the hook, execution options on the execute function. The `loading` state actually means loading now, with `notifyOnNetworkStatusChange` defaulting to `true` so refetches are properly reflected in your UI.
+This clarity extends throughout the API. Hooks like `useLazyQuery` now have clearer boundaries about what options go where — initial options on the hook, execution options on the execute function. The `loading` state actually means loading now, with `notifyOnNetworkStatusChange` defaulting to `true` so refetches are properly reflected in your UI.
 
 ## Built for Modern JavaScript
 

From a8e530bf0512f4eba106589c305ba0128774af7e Mon Sep 17 00:00:00 2001
From: Jerel Miller <jerelmiller@gmail.com>
Date: Thu, 21 Aug 2025 11:17:25 -0600
Subject: [PATCH 10/13] More updates

---
 release-notes-v2.md | 44 +++++++++++++++++++++++++++++++++++++-------
 1 file changed, 37 insertions(+), 7 deletions(-)

diff --git a/release-notes-v2.md b/release-notes-v2.md
index 00b889e3aab..653bd5b1a96 100644
--- a/release-notes-v2.md
+++ b/release-notes-v2.md
@@ -1,25 +1,32 @@
 # Apollo Client 4.0 Release Notes
 
-Apollo Client 4.0 delivers a more modern, efficient, and type-safe GraphQL client experience through significant architectural improvements and API refinements. This release focuses on developer experience, bundle size optimization, and framework flexibility.
+Apollo Client 4.0 delivers a more modern, efficient, and type-safe GraphQL client experience through various architectural improvements and API refinements. This release focuses on developer experience, bundle size optimization, and framework flexibility.
 
 ## Key Improvements
 
 ### 🎯 Framework-Agnostic Core
+
 Apollo Client 4.0 separates React functionality from the core library, making `@apollo/client` truly framework-agnostic. React exports now live in `@apollo/client/react`, allowing developers to use Apollo Client with any JavaScript framework without React dependencies.
 
 ### 📦 Smaller Bundle Sizes
+
 - **Opt-in Local State Management**: The `@client` directive functionality is now opt-in via the `LocalState` class, reducing bundle size when not using local state
 - **Modern Build Target**: Transpiled to target `since 2023, node >= 20, not dead`, leveraging modern JavaScript features for better performance
 - **Improved Tree-Shaking**: Proper `exports` field in package.json enables better dead code elimination
 
 ### 🔧 Enhanced TypeScript Support
+
 - **Namespaced Types**: Types are now colocated with their APIs (e.g., `useQuery.Options` instead of `QueryHookOptions`)
 - **Precise Return Types**: Return types accurately reflect the options passed (e.g., `returnPartialData` makes `data` type `DeepPartial<TData>`)
+- **Stricter Type Safety**: Required variables are now enforced more consistently throughout the client
 - **New `dataState` Property**: Enables accurate type narrowing of query results
 - **Module Augmentation**: Custom context types via declaration merging instead of fragile generics
+- **Customizable Type Implementations**: Select types can be customized to provide your own type implementation to seamlessly integrate with external tools such as GraphQL Codegen or `gql.tada`
 
 ### ⚡ Modern Observable Implementation
+
 Apollo Client 4.0 migrates from `zen-observable` to **RxJS**, providing:
+
 - Industry-standard Observable implementation
 - Rich operator ecosystem
 - Better debugging tools
@@ -32,12 +39,14 @@ Apollo Client 4.0 migrates from `zen-observable` to **RxJS**, providing:
 Apollo Client 4.0 completely reimagines error handling for better clarity and debugging:
 
 **Key Changes:**
+
 - `ApolloError` removed in favor of specific error classes
 - Network errors now respect `errorPolicy` settings
 - External errors passed through without wrapping
 - New error classes with static `.is()` methods for type checking
 
 **Error Classes:**
+
 - `CombinedGraphQLErrors` - GraphQL errors from the server
 - `ServerError` - Non-GraphQL server errors
 - `ServerParseError` - Server response parsing errors
@@ -45,6 +54,7 @@ Apollo Client 4.0 completely reimagines error handling for better clarity and de
 - `LinkError` - Errors from the link chain (via `.is()` check)
 
 **Migration Example:**
+
 ```typescript
 // Apollo Client 3
 if (error instanceof ApolloError) {
@@ -67,12 +77,14 @@ if (CombinedGraphQLErrors.is(error)) {
 A new property that clearly indicates the completeness of query results:
 
 **Values:**
+
 - `empty` - No data available (`data` is `undefined`)
 - `partial` - Incomplete data from cache when `returnPartialData` is `true`
 - `streaming` - Incomplete data from a deferred query still streaming
 - `complete` - Fully satisfied query result
 
 **Benefits:**
+
 - Accurate TypeScript type narrowing
 - Clear loading state distinction
 - Better handling of partial results
@@ -80,10 +92,10 @@ A new property that clearly indicates the completeness of query results:
 ```typescript
 const { data, dataState } = useQuery(MY_QUERY);
 
-if (dataState === 'complete') {
+if (dataState === "complete") {
   // TypeScript knows data is fully populated
   console.log(data.allFields);
-} else if (dataState === 'partial') {
+} else if (dataState === "partial") {
   // TypeScript knows data might be missing fields
   console.log(data?.someField);
 }
@@ -103,6 +115,7 @@ const client = new ApolloClient({
 ```
 
 **Available Handlers:**
+
 - `NotImplementedHandler` - Default, throws if `@defer` is used
 - `Defer20220824Handler` - Apollo Router format support (also aliased as `GraphQL17Alpha2Handler`)
 
@@ -126,6 +139,7 @@ const client = new ApolloClient({
 ```
 
 **Resolver Context Changes:**
+
 ```typescript
 // Apollo Client 3
 const resolver = (parent, args, context, info) => {
@@ -144,15 +158,18 @@ const resolver = (parent, args, context, info) => {
 ### More Predictable Hooks
 
 **`useLazyQuery` Overhaul:**
+
 - No longer accepts `variables` or `context` options (pass to `execute` instead)
 - `execute` function only accepts `variables` and `context`
 - Cannot be called during render or SSR
 - Automatic cancellation of in-flight queries when new ones start
 
 **`useMutation` Changes:**
+
 - Removed `ignoreResults` option - use `client.mutate` directly for fire-and-forget mutations
 
 **`useQuery` Changes:**
+
 - `notifyOnNetworkStatusChange` now defaults to `true`
 - Removed deprecated `onCompleted` and `onError` callbacks
 
@@ -175,7 +192,7 @@ Pre-compiled React hooks optimized by the React Compiler:
 
 ```typescript
 // Use compiled hooks for potential performance improvements
-import { useQuery } from '@apollo/client/react/compiled';
+import { useQuery } from "@apollo/client/react/compiled";
 ```
 
 The compiled hooks are built with React Compiler v19.1.0-rc.2 and include a runtime polyfill for compatibility with React 17+.
@@ -190,12 +207,16 @@ Migration from creator functions to classes:
 // Apollo Client 3
 import { createHttpLink, setContext } from "@apollo/client";
 const httpLink = createHttpLink({ uri: "/graphql" });
-const authLink = setContext((operation, prevContext) => {/*...*/});
+const authLink = setContext((operation, prevContext) => {
+  /*...*/
+});
 
 // Apollo Client 4
 import { HttpLink, SetContextLink } from "@apollo/client";
 const httpLink = new HttpLink({ uri: "/graphql" });
-const authLink = new SetContextLink((prevContext, operation) => {/*...*/});
+const authLink = new SetContextLink((prevContext, operation) => {
+  /*...*/
+});
 ```
 
 ### ErrorLink Changes
@@ -232,6 +253,7 @@ npx apollo-client-codemod-migrate-3-to-4 --parser tsx --extensions tsx src
 ```
 
 The codemod handles:
+
 1. **Import updates** - Moves React imports to `@apollo/client/react`
 2. **Type migrations** - Updates types to new namespaced locations
 3. **Link updates** - Converts creator functions to classes
@@ -240,12 +262,14 @@ The codemod handles:
 ## Breaking Changes Summary
 
 ### Installation
+
 ```bash
 # RxJS is now a peer dependency
 npm install @apollo/client graphql rxjs
 ```
 
 ### ApolloClient Constructor
+
 - `link` option is now required (no more implicit `HttpLink` creation)
 - `uri`, `headers`, `credentials` removed - use `HttpLink` directly
 - `name` and `version` moved to `clientAwareness` option
@@ -254,15 +278,18 @@ npm install @apollo/client graphql rxjs
 - `disableNetworkFetches` renamed to `prioritizeCacheValues`
 
 ### Type System
+
 - Removed `TContext` and `TCacheShape` generics
 - Types moved to namespaces (see migration guide for full list)
 - Custom context via module augmentation
 
 ### Observable Changes
+
 - Requires calling `.pipe()` for transformations
 - Use RxJS operators instead of method chaining
 
 ### Testing
+
 - `MockedProvider` now has realistic delays by default (20-50ms)
 - `createMockClient` removed - use `MockLink` directly
 
@@ -277,12 +304,14 @@ npm install @apollo/client graphql rxjs
 ## Deprecations & Removals
 
 ### Removed Packages/Exports
+
 - React render prop components (`@apollo/client/react/components`)
 - Higher-order components (`@apollo/client/react/hoc`)
 - `@apollo/client/react/parser`
 - `@apollo/client/utilities/globals`
 
 ### Removed Methods
+
 - `client.writeData` - use `writeQuery`/`writeFragment`
 - `ObservableQuery.result()` - use RxJS `firstValueFrom`
 - `InMemoryCache.canonizeResults` option
@@ -304,4 +333,5 @@ npm install @apollo/client graphql rxjs
 
 ## Acknowledgments
 
-Apollo Client 4.0 represents years of community feedback and contributions. Thank you to all our contributors, early adopters, and the entire GraphQL community for making this release possible.
\ No newline at end of file
+Apollo Client 4.0 represents years of community feedback and contributions. Thank you to all our contributors, early adopters, and the entire GraphQL community for making this release possible.
+

From 6b9ce31b00e4b17423e86f2f1061f539863df29b Mon Sep 17 00:00:00 2001
From: Jerel Miller <jerelmiller@gmail.com>
Date: Thu, 21 Aug 2025 11:28:12 -0600
Subject: [PATCH 11/13] Add error handling

---
 release-notes-v2.md | 13 +++++++++++--
 1 file changed, 11 insertions(+), 2 deletions(-)

diff --git a/release-notes-v2.md b/release-notes-v2.md
index 653bd5b1a96..91cd14cb789 100644
--- a/release-notes-v2.md
+++ b/release-notes-v2.md
@@ -14,6 +14,16 @@ Apollo Client 4.0 separates React functionality from the core library, making `@
 - **Modern Build Target**: Transpiled to target `since 2023, node >= 20, not dead`, leveraging modern JavaScript features for better performance
 - **Improved Tree-Shaking**: Proper `exports` field in package.json enables better dead code elimination
 
+### 💥 Unified Error Handling
+
+Apollo Client 4.0 completely reimagines error handling for better clarity and debugging:
+
+- `ApolloError` removed in favor of specific error classes
+- Unification of errors to a single `error` property
+- Network errors now respect `errorPolicy` settings
+- External errors passed through without wrapping
+- New, more granular error classes with static `.is()` methods for robust type narrowing
+
 ### 🔧 Enhanced TypeScript Support
 
 - **Namespaced Types**: Types are now colocated with their APIs (e.g., `useQuery.Options` instead of `QueryHookOptions`)
@@ -21,7 +31,7 @@ Apollo Client 4.0 separates React functionality from the core library, making `@
 - **Stricter Type Safety**: Required variables are now enforced more consistently throughout the client
 - **New `dataState` Property**: Enables accurate type narrowing of query results
 - **Module Augmentation**: Custom context types via declaration merging instead of fragile generics
-- **Customizable Type Implementations**: Select types can be customized to provide your own type implementation to seamlessly integrate with external tools such as GraphQL Codegen or `gql.tada`
+- **Customizable Type Implementations**: Select types can now be customized to provide your own type implementation to seamlessly integrate with external tools such as GraphQL Codegen or `gql.tada`
 
 ### ⚡ Modern Observable Implementation
 
@@ -334,4 +344,3 @@ npm install @apollo/client graphql rxjs
 ## Acknowledgments
 
 Apollo Client 4.0 represents years of community feedback and contributions. Thank you to all our contributors, early adopters, and the entire GraphQL community for making this release possible.
-

From 525828e5e47b3436dbbae3c7f8b1f059f7e6ce08 Mon Sep 17 00:00:00 2001
From: Jerel Miller <jerelmiller@gmail.com>
Date: Thu, 21 Aug 2025 11:35:08 -0600
Subject: [PATCH 12/13] Update observable section

---
 release-notes-v2.md | 7 +------
 1 file changed, 1 insertion(+), 6 deletions(-)

diff --git a/release-notes-v2.md b/release-notes-v2.md
index 91cd14cb789..3d63c118c85 100644
--- a/release-notes-v2.md
+++ b/release-notes-v2.md
@@ -35,12 +35,7 @@ Apollo Client 4.0 completely reimagines error handling for better clarity and de
 
 ### ⚡ Modern Observable Implementation
 
-Apollo Client 4.0 migrates from `zen-observable` to **RxJS**, providing:
-
-- Industry-standard Observable implementation
-- Rich operator ecosystem
-- Better debugging tools
-- Improved performance
+Apollo Client 4.0 migrates from `zen-observable` to **RxJS**, providing the industry-standard Observable implementation backed by a rich ecosystem of utilities.
 
 ## Major Features
 

From 7045de5f1ff856fd0d0a33542c3e23610fcd1cbc Mon Sep 17 00:00:00 2001
From: Jerel Miller <jerelmiller@gmail.com>
Date: Thu, 21 Aug 2025 11:38:01 -0600
Subject: [PATCH 13/13] Remove some more stuff

---
 release-notes-v2.md | 7 -------
 1 file changed, 7 deletions(-)

diff --git a/release-notes-v2.md b/release-notes-v2.md
index 3d63c118c85..adb32615580 100644
--- a/release-notes-v2.md
+++ b/release-notes-v2.md
@@ -315,12 +315,6 @@ npm install @apollo/client graphql rxjs
 - `@apollo/client/react/parser`
 - `@apollo/client/utilities/globals`
 
-### Removed Methods
-
-- `client.writeData` - use `writeQuery`/`writeFragment`
-- `ObservableQuery.result()` - use RxJS `firstValueFrom`
-- `InMemoryCache.canonizeResults` option
-
 ## Upgrade Path
 
 1. **Update to Apollo Client 3.14** first for deprecation warnings
@@ -334,7 +328,6 @@ npm install @apollo/client graphql rxjs
 
 - [Migration Guide](https://www.apollographql.com/docs/react/migrating/apollo-client-4-migration)
 - [Changelog](https://github.com/apollographql/apollo-client/blob/main/CHANGELOG.md)
-- [API Reference](https://www.apollographql.com/docs/react/api)
 
 ## Acknowledgments