@apollo/client 4.1.0-alpha.9 → 4.1.0-rc.0

package/cache/inmemory/policies.d.ts

@@ -1,5 +1,6 @@
 import type { FieldNode, FragmentDefinitionNode, InlineFragmentNode, SelectionSetNode } from "graphql";
 import type { OperationVariables } from "@apollo/client";
+import type { Incremental } from "@apollo/client/incremental";
 import type { Reference, StoreObject, StoreValue } from "@apollo/client/utilities";
 import { isReference } from "@apollo/client/utilities";
 import type { FragmentMap } from "@apollo/client/utilities/internal";
@@ -36,10 +37,10 @@ export type KeyArgsFunction = (args: Record<string, any> | null, context: {
     field: FieldNode | null;
     variables?: Record<string, any>;
 }) => KeySpecifier | false | ReturnType<IdGetter>;
-export type FieldPolicy<TExisting = any, TIncoming = TExisting, TReadResult = TIncoming, TOptions extends FieldFunctionOptions = FieldFunctionOptions> = {
+export type FieldPolicy<TExisting = any, TIncoming = TExisting, TReadResult = TIncoming, TReadOptions extends FieldReadFunctionOptions = FieldReadFunctionOptions, TMergeOptions extends FieldMergeFunctionOptions = FieldMergeFunctionOptions> = {
     keyArgs?: KeySpecifier | KeyArgsFunction | false;
-    read?: FieldReadFunction<TExisting, TReadResult, TOptions>;
-    merge?: FieldMergeFunction<TExisting, TIncoming, TOptions> | boolean;
+    read?: FieldReadFunction<TExisting, TReadResult, TReadOptions>;
+    merge?: FieldMergeFunction<TExisting, TIncoming, TMergeOptions> | boolean;
 };
 export type StorageType = Record<string, any>;
 export interface FieldFunctionOptions<TArgs = Record<string, any>, TVariables extends OperationVariables = Record<string, any>> {
@@ -55,15 +56,36 @@ export interface FieldFunctionOptions<TArgs = Record<string, any>, TVariables ex
     readField: ReadFieldFunction;
     canRead: CanReadFunction;
     mergeObjects: MergeObjectsFunction;
+}
+export interface FieldReadFunctionOptions<TArgs = Record<string, any>, TVariables extends OperationVariables = Record<string, any>> extends FieldFunctionOptions<TArgs, TVariables> {
+}
+export interface FieldMergeFunctionOptions<TArgs = Record<string, any>, TVariables extends OperationVariables = Record<string, any>> extends FieldFunctionOptions<TArgs, TVariables> {
+    /**
+     * Any `extensions` provided when writing the cache.
+     */
+    extensions: Record<string, unknown> | undefined;
+    /**
+     * Details about the field when the `@stream` directive is used. Useful with
+     * custom merge functions to determine how to merge existing cache data with
+     * the incoming stream array.
+     *
+     * This field is only available in `merge` functions when the `@stream`
+     * directive is used on the field.
+     *
+     * > [!NOTE]
+     * > This field is not available when using the `Defer20220824Handler`
+     */
+    streamFieldInfo?: Incremental.StreamFieldInfo;
     /**
-     * Any `extensions` provided when writing the cache. `extensions` is only
-     * available in `merge` functions and never available in `read` functions.
+     * The same value as the `existing` argument, but preserves the `existing`
+     * value on refetches when `refetchWritePolicy` is `overwrite` (the default).
      */
-    extensions?: Record<string, unknown>;
+    existingData: unknown;
 }
 type MergeObjectsFunction = <T extends StoreObject | Reference>(existing: T, incoming: T) => T;
-export type FieldReadFunction<TExisting = any, TReadResult = TExisting, TOptions extends FieldFunctionOptions = FieldFunctionOptions> = (existing: SafeReadonly<TExisting> | undefined, options: TOptions) => TReadResult | undefined;
-export type FieldMergeFunction<TExisting = any, TIncoming = TExisting, TOptions extends FieldFunctionOptions = FieldFunctionOptions> = (existing: SafeReadonly<TExisting> | undefined, incoming: SafeReadonly<TIncoming>, options: TOptions) => SafeReadonly<TExisting>;
+export type FieldReadFunction<TExisting = any, TReadResult = TExisting, TOptions extends FieldReadFunctionOptions = FieldReadFunctionOptions> = (existing: SafeReadonly<TExisting> | undefined, options: TOptions) => TReadResult | undefined;
+export type FieldMergeFunction<TExisting = any, TIncoming = TExisting, TOptions extends FieldMergeFunctionOptions = FieldMergeFunctionOptions> = (existing: SafeReadonly<TExisting> | undefined, incoming: SafeReadonly<TIncoming>, options: TOptions) => SafeReadonly<TExisting>;
+export declare const defaultStreamFieldMergeFn: FieldMergeFunction<Array<any>>;
 export type PossibleTypesMap = {
     [supertype: string]: string[];
 };
@@ -97,7 +119,7 @@ export declare class Policies {
     readField<V = StoreValue>(options: ReadFieldOptions, context: ReadMergeModifyContext): SafeReadonly<V> | undefined;
     getReadFunction(typename: string | undefined, fieldName: string): FieldReadFunction | undefined;
     getMergeFunction(parentTypename: string | undefined, fieldName: string, childTypename: string | undefined): FieldMergeFunction | undefined;
-    runMergeFunction(existing: StoreValue, incoming: StoreValue, { field, typename, merge }: MergeInfo, context: WriteContext, storage?: StorageType): any;
+    runMergeFunction(existing: StoreValue, incoming: StoreValue, { field, typename, merge, path }: MergeInfo, context: WriteContext, storage?: StorageType): any;
 }
 export declare function normalizeReadFieldOptions(readFieldArgs: any[], objectOrReference: StoreObject | Reference | undefined, variables?: ReadMergeModifyContext["variables"]): ReadFieldOptions;
 export {};

package/cache/inmemory/policies.js

@@ -1,6 +1,8 @@
+import { equal } from "@wry/equality";
 import { disableWarningsSlot } from "@apollo/client/masking";
 import { isReference } from "@apollo/client/utilities";
 import { __DEV__ } from "@apollo/client/utilities/environment";
+import { streamInfoSymbol } from "@apollo/client/utilities/internal";
 import { argumentsObjectFromField, getStoreKeyName, isArray, isNonNullObject, storeKeyNameFromField, stringifyForDisplay, } from "@apollo/client/utilities/internal";
 import { invariant, newInvariantError, } from "@apollo/client/utilities/invariant";
 import { defaultDataIdFromObject, fieldNameFromStoreName, hasOwn, selectionSetMatchesResult, storeValueIsStoreObject, TypeOrFieldNameRegExp, } from "./helpers.js";
@@ -17,6 +19,20 @@ const simpleKeyArgsFn = (_args, context) => context.fieldName;
 // merge:false in a field policy.
 const mergeTrueFn = (existing, incoming, { mergeObjects }) => mergeObjects(existing, incoming);
 const mergeFalseFn = (_, incoming) => incoming;
+export const defaultStreamFieldMergeFn = (existing, incoming, { streamFieldInfo, existingData }) => {
+    if (!existing && !existingData) {
+        return incoming;
+    }
+    const results = [];
+    const previous = existing ?? existingData;
+    const length = streamFieldInfo?.isLastChunk ?
+        incoming.length
+        : Math.max(previous.length, incoming.length);
+    for (let i = 0; i < length; i++) {
+        results[i] = incoming[i] === undefined ? previous[i] : incoming[i];
+    }
+    return results;
+};
 export class Policies {
     config;
     typePolicies = {};
@@ -476,7 +492,9 @@ export class Policies {
         }
         return merge;
     }
-    runMergeFunction(existing, incoming, { field, typename, merge }, context, storage) {
+    runMergeFunction(existing, incoming, { field, typename, merge, path }, context, storage) {
+        // Preserve the value in case `context.overwrite` is set.
+        const existingData = existing;
         if (merge === mergeTrueFn) {
             // Instead of going to the trouble of creating a full
             // FieldFunctionOptions object and calling mergeTrueFn, we can
@@ -494,7 +512,18 @@ export class Policies {
         if (context.overwrite) {
             existing = void 0;
         }
-        return merge(existing, incoming, makeFieldFunctionOptions(this, 
+        const streamInfo = context.extensions?.[streamInfoSymbol]
+            ?.deref()
+            ?.peekArray(path);
+        if (streamInfo) {
+            const { current, previous } = streamInfo;
+            if (previous &&
+                equal(previous.incoming, incoming) &&
+                equal(previous.streamFieldInfo, current)) {
+                return previous.result;
+            }
+        }
+        const result = merge(existing, incoming, makeMergeFieldFunctionOptions(this, 
         // Unlike options.readField for read functions, we do not fall
         // back to the current object if no foreignObjOrRef is provided,
         // because it's not clear what the current object should be for
@@ -511,7 +540,16 @@ export class Policies {
             fieldName: field.name.value,
             field,
             variables: context.variables,
-        }, context, storage || {}));
+            path,
+        }, context, storage || {}, existingData));
+        if (streamInfo) {
+            streamInfo.previous = {
+                incoming,
+                streamFieldInfo: streamInfo.current,
+                result,
+            };
+        }
+        return result;
     }
 }
 function makeFieldFunctionOptions(policies, objectOrReference, fieldSpec, context, storage) {
@@ -519,7 +557,7 @@ function makeFieldFunctionOptions(policies, objectOrReference, fieldSpec, contex
     const fieldName = fieldNameFromStoreName(storeFieldName);
     const variables = fieldSpec.variables || context.variables;
     const { toReference, canRead } = context.store;
-    const options = {
+    return {
         args: argsFromFieldSpecifier(fieldSpec),
         field: fieldSpec.field || null,
         fieldName,
@@ -535,13 +573,24 @@ function makeFieldFunctionOptions(policies, objectOrReference, fieldSpec, contex
         },
         mergeObjects: makeMergeObjectsFunction(context.store),
     };
-    // Make `extensions` only available in `merge` functions, but not `read`
-    // functions since we currently only support merge functions. Even though
-    // `context.extensions` will result in `undefined`, we don't want the key to
-    // exist in the options object to avoid the appearance that its supported in
-    // `read` functions.
-    if ("extensions" in context) {
-        options.extensions = context.extensions;
+}
+function makeMergeFieldFunctionOptions(policies, objectOrReference, fieldSpec, context, storage, existingData) {
+    const options = {
+        ...makeFieldFunctionOptions(policies, objectOrReference, fieldSpec, context, storage),
+        extensions: context.extensions,
+        existingData,
+    };
+    const extensions = context.extensions;
+    if (extensions && streamInfoSymbol in extensions) {
+        const { [streamInfoSymbol]: streamInfo, ...otherExtensions } = extensions;
+        const streamFieldInfo = streamInfo?.deref()?.peekArray(fieldSpec.path);
+        if (streamFieldInfo) {
+            options.streamFieldInfo = streamFieldInfo.current;
+        }
+        // If the only key in `extensions` was the stream details key, we didn't
+        // receive any remote extensions, so we reset extensions back to undefined
+        options.extensions =
+            Object.keys(otherExtensions).length === 0 ? undefined : otherExtensions;
     }
     return options;
 }