@apollo/client 4.1.0-alpha.8 → 4.1.0-alpha.9

package/__cjs/utilities/internal/index.d.cts

@@ -62,6 +62,8 @@ export { toQueryResult } from "./toQueryResult.cjs";
 export { filterMap } from "./filterMap.cjs";
 export { equalByQuery } from "./equalByQuery.cjs";
 export { canonicalStringify } from "./canonicalStringify.cjs";
+export { mapObservableFragmentMemoized } from "./mapObservableFragment.cjs";
+export { extensionsSymbol, variablesUnknownSymbol } from "./constants.cjs";
 export { getApolloCacheMemoryInternals, getApolloClientMemoryInternals, getInMemoryCacheMemoryInternals, registerGlobalCache, } from "../internal/getMemoryInternals.cjs";
 export { AutoCleanedStrongCache, AutoCleanedWeakCache } from "./caches.cjs";
 export type { ApplyHKT } from "./types/ApplyHKT.cjs";

package/__cjs/utilities/internal/mapObservableFragment.cjs

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mapObservableFragmentMemoized = void 0;
+const rxjs_1 = require("rxjs");
+const memoize_js_1 = require("./memoize.cjs");
+function mapObservableFragment(observable, mapFn) {
+    let currentResult;
+    let stableMappedResult;
+    function toMapped(result) {
+        if (result !== currentResult) {
+            currentResult = result;
+            stableMappedResult = mapFn(currentResult);
+        }
+        return stableMappedResult;
+    }
+    return Object.assign(observable.pipe((0, rxjs_1.map)(toMapped), (0, rxjs_1.shareReplay)({ bufferSize: 1, refCount: true })), {
+        getCurrentResult: () => toMapped(observable.getCurrentResult()),
+    });
+}
+exports.mapObservableFragmentMemoized = (0, memoize_js_1.memoize)(function mapObservableFragmentMemoized(observable, 
+/**
+ * used together with `observable` as memoization key, `mapFn` is explicitly not used as memoization key
+ */
+_cacheKey, mapFn) {
+    return mapObservableFragment(observable, mapFn);
+}, { max: 1, makeCacheKey: (args) => args.slice(0, 2) });
+//# sourceMappingURL=mapObservableFragment.cjs.map

package/__cjs/utilities/internal/mapObservableFragment.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"mapObservableFragment.cjs","sources":["../../../../src/utilities/internal/mapObservableFragment.ts"],"sourcesContent":["import { map, shareReplay } from \"rxjs\";\n\nimport type { ApolloCache } from \"@apollo/client\";\n\nimport { memoize } from \"./memoize.js\";\n\nfunction mapObservableFragment<From, To>(\n  observable: ApolloCache.ObservableFragment<From>,\n  mapFn: (\n    from: ApolloCache.WatchFragmentResult<From>\n  ) => ApolloCache.WatchFragmentResult<To>\n): ApolloCache.ObservableFragment<To> {\n  let currentResult: ApolloCache.WatchFragmentResult<From>;\n  let stableMappedResult: ApolloCache.WatchFragmentResult<To>;\n\n  function toMapped(\n    result: ApolloCache.WatchFragmentResult<From>\n  ): ApolloCache.WatchFragmentResult<To> {\n    if (result !== currentResult) {\n      currentResult = result;\n      stableMappedResult = mapFn(currentResult);\n    }\n    return stableMappedResult;\n  }\n\n  return Object.assign(\n    observable.pipe(\n      map(toMapped),\n      shareReplay({ bufferSize: 1, refCount: true })\n    ),\n    {\n      getCurrentResult: () => toMapped(observable.getCurrentResult()),\n    }\n  );\n}\n\nexport const mapObservableFragmentMemoized = memoize(\n  function mapObservableFragmentMemoized<From, To>(\n    observable: ApolloCache.ObservableFragment<From>,\n    /**\n     * used together with `observable` as memoization key, `mapFn` is explicitly not used as memoization key\n     */\n    _cacheKey: symbol,\n    mapFn: (\n      from: ApolloCache.WatchFragmentResult<From>\n    ) => ApolloCache.WatchFragmentResult<To>\n  ): ApolloCache.ObservableFragment<To> {\n    return mapObservableFragment(observable, mapFn);\n  },\n  { max: 1, makeCacheKey: (args) => args.slice(0, 2) }\n);\n"],"names":[],"mappings":";;;AAAA,CAAA,CAAA,CAAA,CAAA,EAAA,CAAA,CAAA,CAAA,CAAA,CAAA,EAAA,EAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA;AAIA,CAAA,CAAA,CAAA,CAAA,EAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,EAAA,EAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,gBAAA,CAAA;AAEA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,EAAS,CAAT,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAA8B,CAC5B,CADF,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CACkD,EAChD,CAFF,CAAA,CAAA,CAAA,CAI0C,EAJ1C;IAME,CAAF,CAAA,EAAM,CAAN,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAA0D;IACxD,CAAF,CAAA,EAAM,CAAN,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAA6D;IAE3D,CAAF,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,EAAW,CAAX,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAmB,CACf,CADJ,CAAA,CAAA,CAAA,CAAA,CACiD,EADjD;QAGI,CAAJ,EAAA,CAAQ,CAAR,CAAA,CAAA,CAAA,CAAA,EAAA,CAAA,CAAA,EAAmB,CAAnB,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAgC,EAAE;YAC5B,CAAN,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,EAAA,EAAsB,CAAtB,CAAA,CAAA,CAAA,CAAA,CAA4B;YACtB,CAAN,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,EAAA,EAA2B,CAA3B,CAAA,CAAA,CAAA,CAAgC,CAAC,CAAjC,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAA8C,CAAC;QAC3C;QACA,CAAJ,CAAA,CAAA,CAAA,CAAA,EAAW,CAAX,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAA6B;IAC3B;IAEA,CAAF,CAAA,CAAA,CAAA,CAAA,EAAS,CAAT,CAAA,CAAA,CAAA,CAAA,CAAe,CAAC,CAAhB,CAAA,CAAA,CAAA,CAAA,CAAsB,CAClB,CADJ,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CACc,CAAC,CADf,CAAA,CAAA,CACmB,CACb,CAFN,CAAA,EAEM,CAFN,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAES,CAFT,CAEU,CAFV,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAEkB,CAAC,EACb,CAHN,CAAA,EAGM,CAHN,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAGiB,CAHjB,CAGkB,EAAE,CAHpB,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAG8B,EAAE,CAAC,EAAE,CAHnC,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAG2C,EAAE,CAH7C,CAAA,CAAA,EAAA,CAGmD,CAAC,CAC/C,EACD;QACE,CAAN,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAsB,EAAE,CAAxB,EAA2B,CAA3B,EAA8B,CAA9B,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAsC,CAAC,CAAvC,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAiD,CAAC,CAAlD,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAkE,CAAlE,CAAoE,CAAC;IACrE,CAAK,CACF;AACH;AAEa,CAAb,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAa,CAAb,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,EAAA,EAA6C,CAA7C,CAAA,EAA6C,CAA7C,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAoD,CAApD,CACE,CADF,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,EACW,CADX,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CACwC,CACpC,CAFJ,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAEoD;AAChD,CAAJ,CAAA;;CAEA,CAAA;AACI,CAAJ,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAqB,EACjB,CADJ,CAAA,CAAA,CAAA,CAG4C,EAH5C;IAKI,CAAJ,CAAA,CAAA,CAAA,CAAA,EAAW,CAAX,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAgC,CAAC,CAAjC,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAA2C,EAAE,CAA7C,CAAA,CAAA,CAAA,CAAkD,CAAC;AACjD,CAAC,EACD,EAAE,CADJ,CAAA,CACO,EAAE,CAAC,EAAE,CADZ,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CACwB,EAAE,CAAC,CAD3B,CAAA,CAAA,CAC+B,EAAE,CADjC,EACoC,CADpC,CAAA,CAAA,CACwC,CAAC,CADzC,CAAA,CAAA,CAAA,CAC8C,CAAC,CAAC,EAAE,CAAC,EADnD,CACsD,CACrD;"}

package/__cjs/utilities/internal/mapObservableFragment.d.cts

@@ -0,0 +1,3 @@
+import type { ApolloCache } from "@apollo/client";
+export declare const mapObservableFragmentMemoized: <From, To>(observable: ApolloCache.ObservableFragment<From>, _cacheKey: symbol, mapFn: (from: ApolloCache.WatchFragmentResult<From>) => ApolloCache.WatchFragmentResult<To>) => ApolloCache.ObservableFragment<To>;
+//# sourceMappingURL=mapObservableFragment.d.cts.map

package/__cjs/utilities/internal/memoize.cjs

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.memoize = memoize;
+const trie_1 = require("@wry/trie");
+const caches_js_1 = require("./caches.cjs");
+/**
+ * Naive alternative to `wrap` without any dependency tracking, potentially avoiding resulting memory leaks.
+ */
+function memoize(fn, { max, makeCacheKey = (args) => args, }) {
+    const keys = new trie_1.Trie(true);
+    const cache = new caches_js_1.AutoCleanedWeakCache(max);
+    return (...args) => {
+        const cacheKey = keys.lookupArray(makeCacheKey(args));
+        const cached = cache.get(cacheKey);
+        if (cached) {
+            if (cached.error) {
+                throw cached.error;
+            }
+            return cached.result;
+        }
+        const entry = cache.set(cacheKey, {});
+        try {
+            return (entry.result = fn(...args));
+        }
+        catch (error) {
+            entry.error = error;
+            throw error;
+        }
+    };
+}
+//# sourceMappingURL=memoize.cjs.map

package/__cjs/utilities/internal/memoize.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"memoize.cjs","sources":["../../../../src/utilities/internal/memoize.ts"],"sourcesContent":["import { Trie } from \"@wry/trie\";\n\nimport { AutoCleanedWeakCache } from \"./caches.js\";\n\n/**\n * Naive alternative to `wrap` without any dependency tracking, potentially avoiding resulting memory leaks.\n */\nexport function memoize<TArgs extends any[], TResult>(\n  fn: (...args: TArgs) => TResult,\n  {\n    max,\n    makeCacheKey = (args) => args,\n  }: { max: number; makeCacheKey?: (args: TArgs) => [...any[]] }\n): (...args: TArgs) => TResult {\n  const keys = new Trie<{}>(true);\n  const cache = new AutoCleanedWeakCache<\n    {},\n    { result?: TResult; error?: unknown }\n  >(max);\n\n  return (...args: TArgs): TResult => {\n    const cacheKey = keys.lookupArray(makeCacheKey(args));\n    const cached = cache.get(cacheKey);\n    if (cached) {\n      if (cached.error) {\n        throw cached.error;\n      }\n      return cached.result!;\n    }\n\n    const entry = cache.set(cacheKey, {});\n    try {\n      return (entry.result = fn(...args));\n    } catch (error) {\n      entry.error = error;\n      throw error;\n    }\n  };\n}\n"],"names":[],"mappings":";;AAOA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,EAAA,EAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA;AAPA,CAAA,CAAA,CAAA,CAAA,EAAA,CAAA,CAAA,CAAA,CAAA,CAAA,EAAA,EAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA;AAEA,CAAA,CAAA,CAAA,CAAA,EAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,EAAA,EAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,eAAA,CAAA;AAEA,CAAA,CAAA;;CAEA,CAAA;AACA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,EAAgB,CAAhB,CAAA,CAAA,CAAA,CAAA,CAAA,CAAuB,CACrB,CADF,CACiC,EAC/B,EACE,CAHJ,CAAA,CAGO,EACH,CAJJ,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,EAAA,EAImB,CAAC,CAJpB,CAAA,CAAA,CAIwB,EAAE,CAJ1B,EAI6B,CAJ7B,CAAA,CAAA,CAIiC,EAJjC,CAKgE,EALhE;IAOE,CAAF,CAAA,CAAA,CAAA,EAAQ,CAAR,CAAA,CAAA,EAAA,EAAe,CAAf,CAAA,EAAmB,CAAnB,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAuB,CAAK,CAA5B,CAAA,CAAA,CAAgC,CAAC;IAC/B,CAAF,CAAA,CAAA,CAAA,EAAQ,CAAR,CAAA,CAAA,CAAA,EAAA,EAAgB,CAAhB,CAAA,EAAoB,CAApB,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAwC,CAGpC,CAHJ,CAAA,CAGO,CAAC;IAEN,CAAF,CAAA,CAAA,CAAA,CAAA,EAAS,CAAC,CAAV,CAAA,CAAa,CAAb,CAAA,CAAA,CAAwB,EAAW,CAAnC,EAAA;QACI,CAAJ,CAAA,CAAA,CAAA,EAAU,CAAV,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,EAAA,EAAqB,CAArB,CAAA,CAAA,CAAyB,CAAC,CAA1B,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAqC,CAAC,CAAtC,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAkD,CAAC,CAAnD,CAAA,CAAA,CAAuD,CAAC,CAAC;QACrD,CAAJ,CAAA,CAAA,CAAA,EAAU,CAAV,CAAA,CAAA,CAAA,CAAA,EAAA,EAAmB,CAAnB,CAAA,CAAA,CAAA,CAAwB,CAAC,CAAzB,CAAA,CAA4B,CAAC,CAA7B,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAqC,CAAC;QAClC,CAAJ,EAAA,CAAQ,CAAR,CAAA,CAAA,CAAA,CAAA,CAAc,EAAE;YACV,CAAN,EAAA,CAAU,CAAV,CAAA,CAAA,CAAA,CAAA,CAAgB,CAAC,CAAjB,CAAA,CAAA,CAAA,CAAsB,EAAE;gBAChB,CAAR,CAAA,CAAA,CAAA,EAAc,CAAd,CAAA,CAAA,CAAA,CAAA,CAAoB,CAAC,CAArB,CAAA,CAAA,CAAA,CAA0B;YACpB;YACA,CAAN,CAAA,CAAA,CAAA,CAAA,EAAa,CAAb,CAAA,CAAA,CAAA,CAAA,CAAmB,CAAC,CAApB,CAAA,CAAA,CAAA,CAAA,CAA2B;QACvB;QAEA,CAAJ,CAAA,CAAA,CAAA,EAAU,CAAV,CAAA,CAAA,CAAA,EAAA,EAAkB,CAAlB,CAAA,CAAA,CAAA,CAAuB,CAAC,CAAxB,CAAA,CAA2B,CAAC,CAA5B,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAoC,EAAE,CAAtC,CAAwC,CAAC;QACrC,CAAJ,CAAA,EAAQ;YACF,CAAN,CAAA,CAAA,CAAA,CAAA,EAAa,CAAC,CAAd,CAAA,CAAA,CAAA,CAAmB,CAAC,CAApB,CAAA,CAAA,CAAA,CAAA,EAAA,EAA6B,CAA7B,CAA+B,CAAC,CAAhC,CAAA,CAAmC,CAAnC,CAAA,CAAA,CAAuC,CAAC,CAAC;QACrC;QAAE,CAAN,CAAA,CAAA,CAAA,EAAA,CAAa,CAAb,CAAA,CAAA,CAAA,CAAkB,EAAE;YACd,CAAN,CAAA,CAAA,CAAA,CAAW,CAAC,CAAZ,CAAA,CAAA,CAAA,EAAA,EAAoB,CAApB,CAAA,CAAA,CAAA,CAAyB;YACnB,CAAN,CAAA,CAAA,CAAA,EAAY,CAAZ,CAAA,CAAA,CAAA,CAAiB;QACb;IACF,CAAC;AACH;"}

package/__cjs/utilities/internal/memoize.d.cts

@@ -0,0 +1,8 @@
+/**
+ * Naive alternative to `wrap` without any dependency tracking, potentially avoiding resulting memory leaks.
+ */
+export declare function memoize<TArgs extends any[], TResult>(fn: (...args: TArgs) => TResult, { max, makeCacheKey, }: {
+    max: number;
+    makeCacheKey?: (args: TArgs) => [...any[]];
+}): (...args: TArgs) => TResult;
+//# sourceMappingURL=memoize.d.cts.map

package/__cjs/version.cjs

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.build = exports.version = void 0;
-exports.version = "4.1.0-alpha.8";
+exports.version = "4.1.0-alpha.9";
 exports.build = "cjs";
 //# sourceMappingURL=version.cjs.map

package/cache/core/cache.d.ts

@@ -159,6 +159,53 @@ export declare abstract class ApolloCache {
      * same as returning `false`.
      */
     resolvesClientField?(typename: string, fieldName: string): boolean;
+    /**
+     * Executes multiple cache operations as a single batch, ensuring that
+     * watchers are only notified once after all operations complete. This is
+     * useful for improving performance when making multiple cache updates, as it
+     * prevents unnecessary re-renders or query refetches between individual
+     * operations.
+     *
+     * The `batch` method supports both optimistic and non-optimistic updates, and
+     * provides fine-grained control over which cache layer receives the updates
+     * and when watchers are notified.
+     *
+     * For usage instructions, see [Interacting with cached data: `cache.batch`](https://www.apollographql.com/docs/react/caching/cache-interaction#using-cachebatch).
+     *
+     * @example
+     *
+     * ```js
+     * cache.batch({
+     *   update(cache) {
+     *     cache.writeQuery({
+     *       query: GET_TODOS,
+     *       data: { todos: updatedTodos },
+     *     });
+     *     cache.evict({ id: "Todo:123" });
+     *   },
+     * });
+     * ```
+     *
+     * @example
+     *
+     * ```js
+     * // Optimistic update with a custom layer ID
+     * cache.batch({
+     *   optimistic: "add-todo-optimistic",
+     *   update(cache) {
+     *     cache.modify({
+     *       fields: {
+     *         todos(existing = []) {
+     *           return [...existing, newTodoRef];
+     *         },
+     *       },
+     *     });
+     *   },
+     * });
+     * ```
+     *
+     * @returns The return value of the `update` function.
+     */
     batch<U>(options: Cache.BatchOptions<this, U>): U;
     abstract performTransaction(transaction: Transaction, optimisticId?: string | null): void;
     recordOptimisticTransaction(transaction: Transaction, optimisticId: string): void;

package/cache/core/cache.js

@@ -5,7 +5,7 @@ import { wrap } from "optimism";
 import { distinctUntilChanged, map, Observable, ReplaySubject, share, shareReplay, tap, timer, } from "rxjs";
 import { cacheSizes, canonicalStringify } from "@apollo/client/utilities";
 import { __DEV__ } from "@apollo/client/utilities/environment";
-import { combineLatestBatched, equalByQuery, getApolloCacheMemoryInternals, getFragmentDefinition, getFragmentQueryDocument, } from "@apollo/client/utilities/internal";
+import { combineLatestBatched, equalByQuery, getApolloCacheMemoryInternals, getFragmentDefinition, getFragmentQueryDocument, mapObservableFragmentMemoized, } from "@apollo/client/utilities/internal";
 import { invariant } from "@apollo/client/utilities/invariant";
 export class ApolloCache {
     assumeImmutableResults = false;
@@ -16,11 +16,53 @@ export class ApolloCache {
         return null;
     }
     // Transactional API
-    // The batch method is intended to replace/subsume both performTransaction
-    // and recordOptimisticTransaction, but performTransaction came first, so we
-    // provide a default batch implementation that's just another way of calling
-    // performTransaction. Subclasses of ApolloCache (such as InMemoryCache) can
-    // override the batch method to do more interesting things with its options.
+    /**
+     * Executes multiple cache operations as a single batch, ensuring that
+     * watchers are only notified once after all operations complete. This is
+     * useful for improving performance when making multiple cache updates, as it
+     * prevents unnecessary re-renders or query refetches between individual
+     * operations.
+     *
+     * The `batch` method supports both optimistic and non-optimistic updates, and
+     * provides fine-grained control over which cache layer receives the updates
+     * and when watchers are notified.
+     *
+     * For usage instructions, see [Interacting with cached data: `cache.batch`](https://www.apollographql.com/docs/react/caching/cache-interaction#using-cachebatch).
+     *
+     * @example
+     *
+     * ```js
+     * cache.batch({
+     *   update(cache) {
+     *     cache.writeQuery({
+     *       query: GET_TODOS,
+     *       data: { todos: updatedTodos },
+     *     });
+     *     cache.evict({ id: "Todo:123" });
+     *   },
+     * });
+     * ```
+     *
+     * @example
+     *
+     * ```js
+     * // Optimistic update with a custom layer ID
+     * cache.batch({
+     *   optimistic: "add-todo-optimistic",
+     *   update(cache) {
+     *     cache.modify({
+     *       fields: {
+     *         todos(existing = []) {
+     *           return [...existing, newTodoRef];
+     *         },
+     *       },
+     *     });
+     *   },
+     * });
+     * ```
+     *
+     * @returns The return value of the `update` function.
+     */
     batch(options) {
         const optimisticId = typeof options.optimistic === "string" ? options.optimistic
             : options.optimistic === false ? null
@@ -79,7 +121,6 @@ export class ApolloCache {
     watchFragment(options) {
         const { fragment, fragmentName, from } = options;
         const query = this.getFragmentDoc(fragment, fragmentName);
-        const transformData = options[Symbol.for("apollo.transformData")] ?? ((data) => data);
         const fromArray = Array.isArray(from) ? from : [from];
         const ids = fromArray.map((value) => {
             // While our TypeScript types do not allow for `undefined` as a valid
@@ -92,26 +133,26 @@ export class ApolloCache {
             if (__DEV__) {
                 const actualFragmentName = fragmentName || getFragmentDefinition(fragment).name.value;
                 if (id === undefined) {
-                    __DEV__ && invariant.warn(112, actualFragmentName);
+                    __DEV__ && invariant.warn(113, actualFragmentName);
                 }
             }
             return id;
         });
         if (!Array.isArray(from)) {
-            return this.watchSingleFragment(ids[0], query, {
-                ...options,
-                transformData: (data) => 
-                // Unfortunately we forgot to allow for `null` on watchFragment in 4.0
-                // when `from` is a single record. As such, we need to fallback to {}
-                // when diff.result is null to maintain backwards compatibility. We
-                // should plan to change this in v5. We do however support `null` if
-                // `from` is explicitly `null`.
-                //
-                // NOTE: Using `from` with an array will maintain `null` properly
-                // without the need for a similar fallback since watchFragment with
-                // arrays is new functionality in v4.1.
-                transformData(from === null ? data : data ?? {}),
-            });
+            const observable = this.watchSingleFragment(ids[0], query, options);
+            // Unfortunately we forgot to allow for `null` on watchFragment in 4.0
+            // when `from` is a single record. As such, we need to fallback to {}
+            // when diff.result is null to maintain backwards compatibility. We
+            // should plan to change this in v5. We do however support `null` if
+            // `from` is explicitly `null`.
+            //
+            // NOTE: Using `from` with an array will maintain `null` properly
+            // without the need for a similar fallback since watchFragment with
+            // arrays is new functionality in v4.1.
+            return from === null ? observable : (mapObservableFragmentMemoized(observable, Symbol.for("apollo.transform.individualResult"), (result) => ({
+                ...result,
+                data: result.data ?? {},
+            })));
         }
         let currentResult;
         function toResult(results) {
@@ -129,7 +170,6 @@ export class ApolloCache {
                 dataState: "complete",
                 complete: true,
             });
-            result.data = transformData(result.data);
             if (!equal(currentResult, result)) {
                 currentResult = result;
             }
@@ -164,7 +204,7 @@ export class ApolloCache {
         if (id === null) {
             return nullObservable;
         }
-        const { optimistic = true, variables, transformData = (data) => data, } = options;
+        const { optimistic = true, variables } = options;
         const cacheKey = [
             fragmentQuery,
             canonicalStringify({ id, optimistic, variables }),
@@ -174,7 +214,7 @@ export class ApolloCache {
             let subscribed = false;
             let currentResult;
             function getNewestResult(diff) {
-                const data = transformData(diff.result);
+                const data = diff.result;
                 if (!currentResult ||
                     !equalByQuery(fragmentQuery, { data: currentResult.data }, { data }, options.variables)) {
                     currentResult = {