@apollo/client 4.1.0-alpha.5 → 4.1.0-alpha.7

package/cache/core/types/Cache.d.ts

@@ -110,13 +110,7 @@ export declare namespace Cache {
          */
         optimistic?: boolean;
     }
-    interface ReadFragmentOptions<TData, TVariables extends OperationVariables> {
-        /**
-         * The root id to be used. This id should take the same form as the
-         * value returned by the `cache.identify` function. If a value with your
-         * id does not exist in the store, `null` will be returned.
-         */
-        id?: string;
+    type ReadFragmentOptions<TData, TVariables extends OperationVariables> = {
         /**
          * A GraphQL document created using the `gql` template string tag from
          * `graphql-tag` with one or more fragments which will be used to determine
@@ -147,7 +141,7 @@ export declare namespace Cache {
          * @defaultValue false
          */
         optimistic?: boolean;
-    }
+    } & Cache.CacheIdentifierOption<TData>;
     interface WriteQueryOptions<TData, TVariables extends OperationVariables> {
         /**
          * The GraphQL query shape to be used constructed using the `gql` template
@@ -181,13 +175,7 @@ export declare namespace Cache {
          */
         overwrite?: boolean;
     }
-    interface WriteFragmentOptions<TData, TVariables extends OperationVariables> {
-        /**
-         * The root id to be used. This id should take the same form as the
-         * value returned by the `cache.identify` function. If a value with your
-         * id does not exist in the store, `null` will be returned.
-         */
-        id?: string;
+    type WriteFragmentOptions<TData, TVariables extends OperationVariables> = {
         /**
          * A GraphQL document created using the `gql` template string
          * with one or more fragments which will be used to determine
@@ -221,11 +209,10 @@ export declare namespace Cache {
          * @defaultValue false
          */
         overwrite?: boolean;
-    }
+    } & Cache.CacheIdentifierOption<TData>;
     interface UpdateQueryOptions<TData, TVariables extends OperationVariables> extends Omit<ReadQueryOptions<TData, TVariables> & WriteQueryOptions<TData, TVariables>, "data"> {
     }
-    interface UpdateFragmentOptions<TData, TVariables extends OperationVariables> extends Omit<ReadFragmentOptions<TData, TVariables> & WriteFragmentOptions<TData, TVariables>, "data"> {
-    }
+    type UpdateFragmentOptions<TData, TVariables extends OperationVariables> = Omit<ReadFragmentOptions<TData, TVariables> & WriteFragmentOptions<TData, TVariables>, "data" | "id" | "from"> & Cache.CacheIdentifierOption<TData>;
     type DiffResult<TData> = {
         result: DataValue.Complete<TData>;
         complete: true;
@@ -237,5 +224,40 @@ export declare namespace Cache {
         missing?: MissingFieldError;
         fromOptimisticTransaction?: boolean;
     };
+    type CacheIdentifierOption<TData> = {
+        /**
+         * The root id to be used. This id should take the same form as the
+         * value returned by the `cache.identify` function. If a value with your
+         * id does not exist in the store, `null` will be returned.
+         */
+        id?: string;
+        /**
+         * An object containing a `__typename` and primary key fields
+         * (such as `id`) identifying the entity object from which the fragment will
+         * be retrieved, or a `{ __ref: "..." }` reference, or a `string` ID
+         * (uncommon).
+         *
+         * @remarks
+         * `from` is given precedence over `id` when both are provided.
+         */
+        from?: never;
+    } | {
+        /**
+         * The root id to be used. This id should take the same form as the
+         * value returned by the `cache.identify` function. If a value with your
+         * id does not exist in the store, `null` will be returned.
+         */
+        id?: never;
+        /**
+         * An object containing a `__typename` and primary key fields
+         * (such as `id`) identifying the entity object from which the fragment will
+         * be retrieved, or a `{ __ref: "..." }` reference, or a `string` ID
+         * (uncommon).
+         *
+         * @remarks
+         * `from` is given precedence over `id` when both are provided.
+         */
+        from?: ApolloCache.FromOptionValue<TData>;
+    };
 }
 //# sourceMappingURL=Cache.d.ts.map

package/cache/core/types/Cache.js.map

@@ -1 +1 @@
-{"version":3,"file":"Cache.js","sourceRoot":"","sources":["../../../../src/cache/core/types/Cache.ts"],"names":[],"mappings":"","sourcesContent":["import type {\n  DataValue,\n  DocumentNode,\n  OperationVariables,\n  TypedDocumentNode,\n} from \"@apollo/client\";\nimport type { Unmasked } from \"@apollo/client/masking\";\n\nimport type { ApolloCache } from \"../cache.js\";\n\nimport type {\n  AllFieldsModifier,\n  MissingFieldError,\n  Modifiers,\n} from \"./common.js\";\nexport declare namespace Cache {\n  export type WatchCallback<TData = unknown> = (\n    diff: Cache.DiffResult<TData>,\n    lastDiff?: Cache.DiffResult<TData>\n  ) => void;\n\n  export interface ReadOptions<\n    TData = unknown,\n    TVariables extends OperationVariables = OperationVariables,\n  > {\n    /**\n     * The GraphQL query shape to be used constructed using the `gql` template\n     * string tag from `graphql-tag`. The query will be used to determine the\n     * shape of the data to be read.\n     */\n    query: DocumentNode | TypedDocumentNode<TData, TVariables>;\n\n    /**\n     * Any variables that the GraphQL query may depend on.\n     */\n    variables?: TVariables;\n\n    /**\n     * The root id to be used. Defaults to \"ROOT_QUERY\", which is the ID of the\n     * root query object. This property makes writeQuery capable of writing data\n     * to any object in the cache.\n     */\n    id?: string;\n    rootId?: string;\n    previousResult?: any;\n    optimistic: boolean;\n    returnPartialData?: boolean;\n  }\n\n  export interface WriteOptions<\n    TData = unknown,\n    TVariables extends OperationVariables = OperationVariables,\n  > {\n    /**\n     * The GraphQL query shape to be used constructed using the `gql` template\n     * string tag from `graphql-tag`. The query will be used to determine the\n     * shape of the data to be read.\n     */\n    query: DocumentNode | TypedDocumentNode<TData, TVariables>;\n\n    /**\n     * Any variables that the GraphQL query may depend on.\n     */\n    variables?: TVariables;\n\n    dataId?: string;\n    result: Unmasked<TData>;\n\n    /**\n     * Whether to notify query watchers.\n     * @defaultValue true\n     */\n    broadcast?: boolean;\n    /**\n     * When true, ignore existing field data rather than merging it with\n     * incoming data.\n     * @defaultValue false\n     */\n    overwrite?: boolean;\n  }\n\n  export interface DiffOptions<\n    TData = unknown,\n    TVariables extends OperationVariables = OperationVariables,\n  > extends Omit<ReadOptions<TData, TVariables>, \"rootId\"> {\n    // The DiffOptions interface is currently just an alias for\n    // ReadOptions, though DiffOptions used to be responsible for\n    // declaring the returnPartialData option.\n  }\n\n  export interface WatchOptions<\n    TData = unknown,\n    TVariables extends OperationVariables = OperationVariables,\n  > extends DiffOptions<TData, TVariables> {\n    watcher?: object;\n    immediate?: boolean;\n    callback: WatchCallback<TData>;\n    lastDiff?: DiffResult<TData>;\n  }\n\n  export interface EvictOptions {\n    id?: string;\n    fieldName?: string;\n    args?: Record<string, any>;\n    broadcast?: boolean;\n  }\n\n  // Although you can call cache.reset() without options, its behavior can be\n  // configured by passing a Cache.ResetOptions object.\n  export interface ResetOptions {\n    discardWatches?: boolean;\n  }\n\n  export interface ModifyOptions<\n    Entity extends Record<string, any> = Record<string, any>,\n  > {\n    id?: string;\n    fields: Modifiers<Entity> | AllFieldsModifier<Entity>;\n    optimistic?: boolean;\n    broadcast?: boolean;\n  }\n\n  export interface BatchOptions<\n    TCache extends ApolloCache,\n    TUpdateResult = void,\n  > {\n    // Same as the first parameter of performTransaction, except the cache\n    // argument will have the subclass type rather than ApolloCache.\n    update(cache: TCache): TUpdateResult;\n\n    // Passing a string for this option creates a new optimistic layer, with the\n    // given string as its layer.id, just like passing a string for the\n    // optimisticId parameter of performTransaction. Passing true is the same as\n    // passing undefined to performTransaction (running the batch operation\n    // against the current top layer of the cache), and passing false is the\n    // same as passing null (running the operation against root/non-optimistic\n    // cache data).\n    optimistic?: string | boolean;\n\n    // If you specify the ID of an optimistic layer using this option, that\n    // layer will be removed as part of the batch transaction, triggering at\n    // most one broadcast for both the transaction and the removal of the layer.\n    // Note: this option is needed because calling cache.removeOptimistic during\n    // the transaction function may not be not safe, since any modifications to\n    // cache layers may be discarded after the transaction finishes.\n    removeOptimistic?: string;\n\n    // If you want to find out which watched queries were invalidated during\n    // this batch operation, pass this optional callback function. Returning\n    // false from the callback will prevent broadcasting this result.\n    onWatchUpdated?: (\n      this: TCache,\n      watch: Cache.WatchOptions,\n      diff: Cache.DiffResult<any>,\n      lastDiff?: Cache.DiffResult<any> | undefined\n    ) => any;\n  }\n\n  export interface ReadQueryOptions<\n    TData,\n    TVariables extends OperationVariables,\n  > {\n    /**\n     * The GraphQL query shape to be used constructed using the `gql` template\n     * string tag. The query will be used to determine the\n     * shape of the data to be read.\n     */\n    query: DocumentNode | TypedDocumentNode<TData, TVariables>;\n\n    /**\n     * Any variables that the GraphQL query may depend on.\n     */\n    variables?: TVariables;\n\n    /**\n     * The root id to be used. Defaults to \"ROOT_QUERY\", which is the ID of the\n     * root query object. This property makes readQuery capable of reading data\n     * from any object in the cache.\n     */\n    id?: string;\n    /**\n     * Whether to return incomplete data rather than null.\n     * @defaultValue false\n     */\n    returnPartialData?: boolean;\n    /**\n     * Whether to read from optimistic or non-optimistic cache data. If\n     * this named option is provided, the optimistic parameter of the\n     * readQuery method can be omitted.\n     * @defaultValue false\n     */\n    optimistic?: boolean;\n  }\n\n  export interface ReadFragmentOptions<\n    TData,\n    TVariables extends OperationVariables,\n  > {\n    /**\n     * The root id to be used. This id should take the same form as the\n     * value returned by the `cache.identify` function. If a value with your\n     * id does not exist in the store, `null` will be returned.\n     */\n    id?: string;\n\n    /**\n     * A GraphQL document created using the `gql` template string tag from\n     * `graphql-tag` with one or more fragments which will be used to determine\n     * the shape of data to read. If you provide more than one fragment in this\n     * document then you must also specify `fragmentName` to specify which\n     * fragment is the root fragment.\n     */\n    fragment: DocumentNode | TypedDocumentNode<TData, TVariables>;\n\n    /**\n     * The name of the fragment in your GraphQL document to be used. If you do\n     * not provide a `fragmentName` and there is only one fragment in your\n     * `fragment` document then that fragment will be used.\n     */\n    fragmentName?: string;\n\n    /**\n     * Any variables that your GraphQL fragments depend on.\n     */\n    variables?: TVariables;\n\n    /**\n     * Whether to return incomplete data rather than null.\n     * @defaultValue false\n     */\n    returnPartialData?: boolean;\n    /**\n     * Whether to read from optimistic or non-optimistic cache data. If\n     * this named option is provided, the optimistic parameter of the\n     * readFragment method can be omitted.\n     * @defaultValue false\n     */\n    optimistic?: boolean;\n  }\n\n  export interface WriteQueryOptions<\n    TData,\n    TVariables extends OperationVariables,\n  > {\n    /**\n     * The GraphQL query shape to be used constructed using the `gql` template\n     * string tag from `graphql-tag`. The query will be used to determine the\n     * shape of the data to be read.\n     */\n    query: DocumentNode | TypedDocumentNode<TData, TVariables>;\n\n    /**\n     * Any variables that the GraphQL query may depend on.\n     */\n    variables?: TVariables;\n\n    /**\n     * The root id to be used. Defaults to \"ROOT_QUERY\", which is the ID of the\n     * root query object. This property makes writeQuery capable of writing data\n     * to any object in the cache.\n     */\n    id?: string;\n\n    /**\n     * The data to write to the store.\n     */\n    data: Unmasked<TData>;\n    /**\n     * Whether to notify query watchers.\n     * @defaultValue true\n     */\n    broadcast?: boolean;\n    /**\n     * When true, ignore existing field data rather than merging it with\n     * incoming data.\n     * @defaultValue false\n     */\n    overwrite?: boolean;\n  }\n\n  export interface WriteFragmentOptions<\n    TData,\n    TVariables extends OperationVariables,\n  > {\n    /**\n     * The root id to be used. This id should take the same form as the\n     * value returned by the `cache.identify` function. If a value with your\n     * id does not exist in the store, `null` will be returned.\n     */\n    id?: string;\n\n    /**\n     * A GraphQL document created using the `gql` template string\n     * with one or more fragments which will be used to determine\n     * the shape of data to read. If you provide more than one fragment in this\n     * document then you must also specify `fragmentName` to specify specify which\n     * fragment is the root fragment.\n     */\n    fragment: DocumentNode | TypedDocumentNode<TData, TVariables>;\n\n    /**\n     * The name of the fragment in your GraphQL document to be used. If you do\n     * not provide a `fragmentName` and there is only one fragment in your\n     * `fragment` document then that fragment will be used.\n     */\n    fragmentName?: string;\n\n    /**\n     * Any variables that your GraphQL fragments depend on.\n     */\n    variables?: TVariables;\n    /**\n     * The data to write to the store.\n     */\n    data: Unmasked<TData>;\n    /**\n     * Whether to notify query watchers.\n     * @defaultValue true\n     */\n    broadcast?: boolean;\n    /**\n     * When true, ignore existing field data rather than merging it with\n     * incoming data.\n     * @defaultValue false\n     */\n    overwrite?: boolean;\n  }\n\n  export interface UpdateQueryOptions<\n    TData,\n    TVariables extends OperationVariables,\n  > extends Omit<\n      ReadQueryOptions<TData, TVariables> &\n        WriteQueryOptions<TData, TVariables>,\n      \"data\"\n    > {}\n\n  export interface UpdateFragmentOptions<\n    TData,\n    TVariables extends OperationVariables,\n  > extends Omit<\n      ReadFragmentOptions<TData, TVariables> &\n        WriteFragmentOptions<TData, TVariables>,\n      \"data\"\n    > {}\n\n  export type DiffResult<TData> =\n    | {\n        result: DataValue.Complete<TData>;\n        complete: true;\n        missing?: never;\n        fromOptimisticTransaction?: boolean;\n      }\n    | {\n        result: DataValue.Partial<TData> | null;\n        complete: false;\n        missing?: MissingFieldError;\n        fromOptimisticTransaction?: boolean;\n      };\n}\n"]}
+{"version":3,"file":"Cache.js","sourceRoot":"","sources":["../../../../src/cache/core/types/Cache.ts"],"names":[],"mappings":"","sourcesContent":["import type {\n  DataValue,\n  DocumentNode,\n  OperationVariables,\n  TypedDocumentNode,\n} from \"@apollo/client\";\nimport type { Unmasked } from \"@apollo/client/masking\";\n\nimport type { ApolloCache } from \"../cache.js\";\n\nimport type {\n  AllFieldsModifier,\n  MissingFieldError,\n  Modifiers,\n} from \"./common.js\";\nexport declare namespace Cache {\n  export type WatchCallback<TData = unknown> = (\n    diff: Cache.DiffResult<TData>,\n    lastDiff?: Cache.DiffResult<TData>\n  ) => void;\n\n  export interface ReadOptions<\n    TData = unknown,\n    TVariables extends OperationVariables = OperationVariables,\n  > {\n    /**\n     * The GraphQL query shape to be used constructed using the `gql` template\n     * string tag from `graphql-tag`. The query will be used to determine the\n     * shape of the data to be read.\n     */\n    query: DocumentNode | TypedDocumentNode<TData, TVariables>;\n\n    /**\n     * Any variables that the GraphQL query may depend on.\n     */\n    variables?: TVariables;\n\n    /**\n     * The root id to be used. Defaults to \"ROOT_QUERY\", which is the ID of the\n     * root query object. This property makes writeQuery capable of writing data\n     * to any object in the cache.\n     */\n    id?: string;\n    rootId?: string;\n    previousResult?: any;\n    optimistic: boolean;\n    returnPartialData?: boolean;\n  }\n\n  export interface WriteOptions<\n    TData = unknown,\n    TVariables extends OperationVariables = OperationVariables,\n  > {\n    /**\n     * The GraphQL query shape to be used constructed using the `gql` template\n     * string tag from `graphql-tag`. The query will be used to determine the\n     * shape of the data to be read.\n     */\n    query: DocumentNode | TypedDocumentNode<TData, TVariables>;\n\n    /**\n     * Any variables that the GraphQL query may depend on.\n     */\n    variables?: TVariables;\n\n    dataId?: string;\n    result: Unmasked<TData>;\n\n    /**\n     * Whether to notify query watchers.\n     * @defaultValue true\n     */\n    broadcast?: boolean;\n    /**\n     * When true, ignore existing field data rather than merging it with\n     * incoming data.\n     * @defaultValue false\n     */\n    overwrite?: boolean;\n  }\n\n  export interface DiffOptions<\n    TData = unknown,\n    TVariables extends OperationVariables = OperationVariables,\n  > extends Omit<ReadOptions<TData, TVariables>, \"rootId\"> {\n    // The DiffOptions interface is currently just an alias for\n    // ReadOptions, though DiffOptions used to be responsible for\n    // declaring the returnPartialData option.\n  }\n\n  export interface WatchOptions<\n    TData = unknown,\n    TVariables extends OperationVariables = OperationVariables,\n  > extends DiffOptions<TData, TVariables> {\n    watcher?: object;\n    immediate?: boolean;\n    callback: WatchCallback<TData>;\n    lastDiff?: DiffResult<TData>;\n  }\n\n  export interface EvictOptions {\n    id?: string;\n    fieldName?: string;\n    args?: Record<string, any>;\n    broadcast?: boolean;\n  }\n\n  // Although you can call cache.reset() without options, its behavior can be\n  // configured by passing a Cache.ResetOptions object.\n  export interface ResetOptions {\n    discardWatches?: boolean;\n  }\n\n  export interface ModifyOptions<\n    Entity extends Record<string, any> = Record<string, any>,\n  > {\n    id?: string;\n    fields: Modifiers<Entity> | AllFieldsModifier<Entity>;\n    optimistic?: boolean;\n    broadcast?: boolean;\n  }\n\n  export interface BatchOptions<\n    TCache extends ApolloCache,\n    TUpdateResult = void,\n  > {\n    // Same as the first parameter of performTransaction, except the cache\n    // argument will have the subclass type rather than ApolloCache.\n    update(cache: TCache): TUpdateResult;\n\n    // Passing a string for this option creates a new optimistic layer, with the\n    // given string as its layer.id, just like passing a string for the\n    // optimisticId parameter of performTransaction. Passing true is the same as\n    // passing undefined to performTransaction (running the batch operation\n    // against the current top layer of the cache), and passing false is the\n    // same as passing null (running the operation against root/non-optimistic\n    // cache data).\n    optimistic?: string | boolean;\n\n    // If you specify the ID of an optimistic layer using this option, that\n    // layer will be removed as part of the batch transaction, triggering at\n    // most one broadcast for both the transaction and the removal of the layer.\n    // Note: this option is needed because calling cache.removeOptimistic during\n    // the transaction function may not be not safe, since any modifications to\n    // cache layers may be discarded after the transaction finishes.\n    removeOptimistic?: string;\n\n    // If you want to find out which watched queries were invalidated during\n    // this batch operation, pass this optional callback function. Returning\n    // false from the callback will prevent broadcasting this result.\n    onWatchUpdated?: (\n      this: TCache,\n      watch: Cache.WatchOptions,\n      diff: Cache.DiffResult<any>,\n      lastDiff?: Cache.DiffResult<any> | undefined\n    ) => any;\n  }\n\n  export interface ReadQueryOptions<\n    TData,\n    TVariables extends OperationVariables,\n  > {\n    /**\n     * The GraphQL query shape to be used constructed using the `gql` template\n     * string tag. The query will be used to determine the\n     * shape of the data to be read.\n     */\n    query: DocumentNode | TypedDocumentNode<TData, TVariables>;\n\n    /**\n     * Any variables that the GraphQL query may depend on.\n     */\n    variables?: TVariables;\n\n    /**\n     * The root id to be used. Defaults to \"ROOT_QUERY\", which is the ID of the\n     * root query object. This property makes readQuery capable of reading data\n     * from any object in the cache.\n     */\n    id?: string;\n    /**\n     * Whether to return incomplete data rather than null.\n     * @defaultValue false\n     */\n    returnPartialData?: boolean;\n    /**\n     * Whether to read from optimistic or non-optimistic cache data. If\n     * this named option is provided, the optimistic parameter of the\n     * readQuery method can be omitted.\n     * @defaultValue false\n     */\n    optimistic?: boolean;\n  }\n\n  export type ReadFragmentOptions<\n    TData,\n    TVariables extends OperationVariables,\n  > = {\n    /**\n     * A GraphQL document created using the `gql` template string tag from\n     * `graphql-tag` with one or more fragments which will be used to determine\n     * the shape of data to read. If you provide more than one fragment in this\n     * document then you must also specify `fragmentName` to specify which\n     * fragment is the root fragment.\n     */\n    fragment: DocumentNode | TypedDocumentNode<TData, TVariables>;\n\n    /**\n     * The name of the fragment in your GraphQL document to be used. If you do\n     * not provide a `fragmentName` and there is only one fragment in your\n     * `fragment` document then that fragment will be used.\n     */\n    fragmentName?: string;\n\n    /**\n     * Any variables that your GraphQL fragments depend on.\n     */\n    variables?: TVariables;\n\n    /**\n     * Whether to return incomplete data rather than null.\n     * @defaultValue false\n     */\n    returnPartialData?: boolean;\n    /**\n     * Whether to read from optimistic or non-optimistic cache data. If\n     * this named option is provided, the optimistic parameter of the\n     * readFragment method can be omitted.\n     * @defaultValue false\n     */\n    optimistic?: boolean;\n  } & Cache.CacheIdentifierOption<TData>;\n\n  export interface WriteQueryOptions<\n    TData,\n    TVariables extends OperationVariables,\n  > {\n    /**\n     * The GraphQL query shape to be used constructed using the `gql` template\n     * string tag from `graphql-tag`. The query will be used to determine the\n     * shape of the data to be read.\n     */\n    query: DocumentNode | TypedDocumentNode<TData, TVariables>;\n\n    /**\n     * Any variables that the GraphQL query may depend on.\n     */\n    variables?: TVariables;\n\n    /**\n     * The root id to be used. Defaults to \"ROOT_QUERY\", which is the ID of the\n     * root query object. This property makes writeQuery capable of writing data\n     * to any object in the cache.\n     */\n    id?: string;\n\n    /**\n     * The data to write to the store.\n     */\n    data: Unmasked<TData>;\n    /**\n     * Whether to notify query watchers.\n     * @defaultValue true\n     */\n    broadcast?: boolean;\n    /**\n     * When true, ignore existing field data rather than merging it with\n     * incoming data.\n     * @defaultValue false\n     */\n    overwrite?: boolean;\n  }\n\n  export type WriteFragmentOptions<\n    TData,\n    TVariables extends OperationVariables,\n  > = {\n    /**\n     * A GraphQL document created using the `gql` template string\n     * with one or more fragments which will be used to determine\n     * the shape of data to read. If you provide more than one fragment in this\n     * document then you must also specify `fragmentName` to specify specify which\n     * fragment is the root fragment.\n     */\n    fragment: DocumentNode | TypedDocumentNode<TData, TVariables>;\n\n    /**\n     * The name of the fragment in your GraphQL document to be used. If you do\n     * not provide a `fragmentName` and there is only one fragment in your\n     * `fragment` document then that fragment will be used.\n     */\n    fragmentName?: string;\n\n    /**\n     * Any variables that your GraphQL fragments depend on.\n     */\n    variables?: TVariables;\n    /**\n     * The data to write to the store.\n     */\n    data: Unmasked<TData>;\n    /**\n     * Whether to notify query watchers.\n     * @defaultValue true\n     */\n    broadcast?: boolean;\n    /**\n     * When true, ignore existing field data rather than merging it with\n     * incoming data.\n     * @defaultValue false\n     */\n    overwrite?: boolean;\n  } & Cache.CacheIdentifierOption<TData>;\n\n  export interface UpdateQueryOptions<\n    TData,\n    TVariables extends OperationVariables,\n  > extends Omit<\n      ReadQueryOptions<TData, TVariables> &\n        WriteQueryOptions<TData, TVariables>,\n      \"data\"\n    > {}\n\n  export type UpdateFragmentOptions<\n    TData,\n    TVariables extends OperationVariables,\n  > = Omit<\n    ReadFragmentOptions<TData, TVariables> &\n      WriteFragmentOptions<TData, TVariables>,\n    \"data\" | \"id\" | \"from\"\n  > &\n    Cache.CacheIdentifierOption<TData>;\n\n  export type DiffResult<TData> =\n    | {\n        result: DataValue.Complete<TData>;\n        complete: true;\n        missing?: never;\n        fromOptimisticTransaction?: boolean;\n      }\n    | {\n        result: DataValue.Partial<TData> | null;\n        complete: false;\n        missing?: MissingFieldError;\n        fromOptimisticTransaction?: boolean;\n      };\n\n  export type CacheIdentifierOption<TData> =\n    | {\n        /**\n         * The root id to be used. This id should take the same form as the\n         * value returned by the `cache.identify` function. If a value with your\n         * id does not exist in the store, `null` will be returned.\n         */\n        id?: string;\n\n        /**\n         * An object containing a `__typename` and primary key fields\n         * (such as `id`) identifying the entity object from which the fragment will\n         * be retrieved, or a `{ __ref: \"...\" }` reference, or a `string` ID\n         * (uncommon).\n         *\n         * @remarks\n         * `from` is given precedence over `id` when both are provided.\n         */\n        from?: never;\n      }\n    | {\n        /**\n         * The root id to be used. This id should take the same form as the\n         * value returned by the `cache.identify` function. If a value with your\n         * id does not exist in the store, `null` will be returned.\n         */\n        id?: never;\n\n        /**\n         * An object containing a `__typename` and primary key fields\n         * (such as `id`) identifying the entity object from which the fragment will\n         * be retrieved, or a `{ __ref: \"...\" }` reference, or a `string` ID\n         * (uncommon).\n         *\n         * @remarks\n         * `from` is given precedence over `id` when both are provided.\n         */\n        from?: ApolloCache.FromOptionValue<TData>;\n      };\n}\n"]}

package/core/ApolloClient.d.ts

@@ -1,6 +1,6 @@
 import type { DocumentNode } from "graphql";
 import type { Observable } from "rxjs";
-import type { ApolloCache, IgnoreModifier, Reference } from "@apollo/client/cache";
+import type { ApolloCache, Cache, IgnoreModifier, Reference } from "@apollo/client/cache";
 import type { Incremental } from "@apollo/client/incremental";
 import type { ApolloLink } from "@apollo/client/link";
 import type { ClientAwarenessLink } from "@apollo/client/link/client-awareness";
@@ -522,12 +522,6 @@ export declare namespace ApolloClient {
     }
     namespace Base {
         interface ReadFragmentOptions<TData, TVariables extends OperationVariables> {
-            /**
-             * The root id to be used. This id should take the same form as the
-             * value returned by the `cache.identify` function. If a value with your
-             * id does not exist in the store, `null` will be returned.
-             */
-            id?: string;
             /**
              * A GraphQL document created using the `gql` template string tag
              * with one or more fragments which will be used to determine
@@ -556,7 +550,27 @@ export declare namespace ApolloClient {
             optimistic?: boolean;
         }
     }
-    type ReadFragmentOptions<TData, TVariables extends OperationVariables> = Base.ReadFragmentOptions<TData, TVariables> & VariablesOption<TVariables>;
+    namespace DocumentationTypes {
+        interface ReadFragmentOptions<TData, TVariables extends OperationVariables> extends Base.ReadFragmentOptions<TData, TVariables> {
+            /**
+             * The root id to be used. This id should take the same form as the
+             * value returned by the `cache.identify` function. If a value with your
+             * id does not exist in the store, `null` will be returned.
+             */
+            id?: string;
+            /**
+             * An object containing a `__typename` and primary key fields
+             * (such as `id`) identifying the entity object from which the fragment will
+             * be retrieved, or a `{ __ref: "..." }` reference, or a `string` ID
+             * (uncommon).
+             *
+             * @remarks
+             * `from` is given precedence over `id` when both are provided.
+             */
+            from?: ApolloCache.FromOptionValue<TData>;
+        }
+    }
+    type ReadFragmentOptions<TData, TVariables extends OperationVariables> = Base.ReadFragmentOptions<TData, TVariables> & VariablesOption<TVariables> & Cache.CacheIdentifierOption<TData>;
     namespace DocumentationTypes {
         interface WriteQueryOptions<TData, TVariables extends OperationVariables> extends Base.WriteQueryOptions<TData, TVariables> {
             /**
@@ -607,12 +621,6 @@ export declare namespace ApolloClient {
     }
     namespace Base {
         interface WriteFragmentOptions<TData, TVariables extends OperationVariables> {
-            /**
-             * The root id to be used. This id should take the same form as the
-             * value returned by the `cache.identify` function. If a value with your
-             * id does not exist in the store, `null` will be returned.
-             */
-            id?: string;
             /**
              * A GraphQL document created using the `gql` template string tag from
              * `graphql-tag` with one or more fragments which will be used to determine
@@ -644,9 +652,25 @@ export declare namespace ApolloClient {
             overwrite?: boolean;
         }
     }
-    type WriteFragmentOptions<TData, TVariables extends OperationVariables> = Base.WriteFragmentOptions<TData, TVariables> & VariablesOption<TVariables>;
+    type WriteFragmentOptions<TData, TVariables extends OperationVariables> = Base.WriteFragmentOptions<TData, TVariables> & VariablesOption<TVariables> & Cache.CacheIdentifierOption<TData>;
     namespace DocumentationTypes {
         interface WriteFragmentOptions<TData, TVariables extends OperationVariables> extends Base.WriteFragmentOptions<TData, TVariables> {
+            /**
+             * The root id to be used. This id should take the same form as the
+             * value returned by the `cache.identify` function. If a value with your
+             * id does not exist in the store, `null` will be returned.
+             */
+            id?: string;
+            /**
+             * An object containing a `__typename` and primary key fields
+             * (such as `id`) identifying the entity object from which the fragment will
+             * be retrieved, or a `{ __ref: "..." }` reference, or a `string` ID
+             * (uncommon).
+             *
+             * @remarks
+             * `from` is given precedence over `id` when both are provided.
+             */
+            from?: ApolloCache.FromOptionValue<TData>;
             /**
              * Any variables that your GraphQL fragments depend on.
              */
@@ -830,7 +854,7 @@ export declare class ApolloClient {
      * to optimistic updates.
      */
     watchFragment<TData = unknown, TVariables extends OperationVariables = OperationVariables>(options: ApolloClient.WatchFragmentOptions<TData, TVariables> & {
-        from: Array<NonNullable<ApolloCache.WatchFragmentFromValue<TData>>>;
+        from: Array<ApolloCache.FromOptionValue<TData>>;
     }): ApolloClient.ObservableFragment<Array<TData>>;
     /**
     * Watches the cache store of the fragment according to the options specified
@@ -852,7 +876,7 @@ export declare class ApolloClient {
         from: Array<null>;
     }): ApolloClient.ObservableFragment<Array<null>>;
     watchFragment<TData = unknown, TVariables extends OperationVariables = OperationVariables>(options: ApolloClient.WatchFragmentOptions<TData, TVariables> & {
-        from: Array<ApolloCache.WatchFragmentFromValue<TData>>;
+        from: Array<ApolloCache.FromOptionValue<TData> | null>;
     }): ApolloClient.ObservableFragment<Array<TData | null>>;
     /**
     * Watches the cache store of the fragment according to the options specified
@@ -890,7 +914,7 @@ export declare class ApolloClient {
     * to optimistic updates.
     */
     watchFragment<TData = unknown, TVariables extends OperationVariables = OperationVariables>(options: ApolloClient.WatchFragmentOptions<TData, TVariables> & {
-        from: NonNullable<ApolloCache.WatchFragmentFromValue<TData>>;
+        from: ApolloCache.FromOptionValue<TData>;
     }): ApolloClient.ObservableFragment<TData>;
     /**
     * Watches the cache store of the fragment according to the options specified

package/core/ApolloClient.js

@@ -288,11 +288,7 @@ export class ApolloClient {
     }
     watchFragment(options) {
         const dataMasking = this.queryManager.dataMasking;
-        const observable = this.cache.watchFragment({
-            ...options,
-            fragment: this.transform(options.fragment, dataMasking),
-        });
-        const mask = (result) => {
+        const mask = (data) => {
             // The transform will remove fragment spreads from the fragment
             // document when dataMasking is enabled. The `mask` function
             // remains to apply warnings to fragments marked as
@@ -300,29 +296,17 @@ export class ApolloClient {
             // in dev, we can skip the masking algorithm entirely for production.
             if (__DEV__) {
                 if (dataMasking) {
-                    return {
-                        ...result,
-                        data: this.queryManager.maskFragment({
-                            ...options,
-                            data: result.data,
-                        }),
-                    };
+                    return this.queryManager.maskFragment({ ...options, data });
                 }
             }
-            return result;
+            return data;
         };
-        let currentResult;
-        let stableMaskedResult;
-        return Object.assign(observable.pipe(map(mask)), {
-            getCurrentResult: () => {
-                const result = observable.getCurrentResult();
-                if (result !== currentResult) {
-                    currentResult = result;
-                    stableMaskedResult = mask(currentResult);
-                }
-                return stableMaskedResult;
-            },
+        const observable = this.cache.watchFragment({
+            ...options,
+            fragment: this.transform(options.fragment, dataMasking),
+            [Symbol.for("apollo.transformData")]: mask,
         });
+        return observable;
     }
     readFragment(options, optimistic = false) {
         return this.cache.readFragment({ ...options, fragment: this.transform(options.fragment) }, optimistic);