Custom scalars (#13270)

Feature branch for [custom
scalars](#13227).

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->

## Summary by CodeRabbit

* **New Features**
* Added support for custom GraphQL scalars in the cache, including
serialization, parsing, and field-level scalar mapping.
  * Added support for nested input object scalar configuration.
* Expanded cache behavior so scalar values are handled consistently
across reads, writes, diffs, queries, mutations, subscriptions,
fragments, and refetch flows.
* **Bug Fixes**
* Improved consistency when cached scalar values are restored or
extracted.
* Updated variable handling so scalar values are serialized before
requests are sent.

<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Author: jerelmiller

.api-reports/api-report-cache.api.md

@@ -20,15 +20,18 @@ import type { FragmentType } from '@apollo/client/masking';
 import { getApolloCacheMemoryInternals } from '@apollo/client/utilities/internal';
 import type { GetDataState } from '@apollo/client';
 import { getInMemoryCacheMemoryInternals } from '@apollo/client/utilities/internal';
+import type { GraphQLScalarType } from 'graphql';
 import type { Incremental } from '@apollo/client/incremental';
 import type { InlineFragmentNode } from 'graphql';
 import type { IsAny } from '@apollo/client/utilities/internal';
+import type { IsLooselyEqual } from '@apollo/client/utilities/internal';
 import { isReference } from '@apollo/client/utilities';
 import type { NoInfer as NoInfer_2 } from '@apollo/client/utilities/internal';
 import { Observable } from 'rxjs';
 import type { OperationVariables } from '@apollo/client';
 import type { Prettify } from '@apollo/client/utilities/internal';
 import { Reference } from '@apollo/client/utilities';
+import type { RemoveIndexSignature } from '@apollo/client/utilities/internal';
 import type { SelectionSetNode } from 'graphql';
 import type { StoreObject } from '@apollo/client/utilities';
 import type { StoreValue } from '@apollo/client/utilities';
@@ -46,9 +49,17 @@ type AllFieldsModifier<Entity extends Record<string, any>> = Modifier<Entity[key
 export namespace ApolloCache {
     export type FromOptionValue<TData> = StoreObject | Reference | FragmentType<NoInfer_2<TData>> | string;
     // (undocumented)
+    export type GetScalarType<TKey extends keyof ApolloCache.Scalars> = ApolloCache.Scalars[TKey] extends ({
+        serialized: infer TSerialized;
+        parsed: infer TParsed;
+    }) ? Scalar<TSerialized, TParsed> : never;
+    // (undocumented)
     export interface ObservableFragment<TData = unknown> extends Observable<ApolloCache.WatchFragmentResult<TData>> {
         getCurrentResult: () => ApolloCache.WatchFragmentResult<TData>;
     }
+    // (undocumented)
+    export interface Scalars {
+    }
     export interface WatchFragmentOptions<TData = unknown, TVariables extends OperationVariables = OperationVariables> {
         fragment: DocumentNode | TypedDocumentNode<TData, TVariables>;
         fragmentName?: string;
@@ -92,6 +103,8 @@ export abstract class ApolloCache {
     // @internal @deprecated
     getMemoryInternals?: typeof getApolloCacheMemoryInternals;
     // (undocumented)
+    getScalar<TKey extends keyof ApolloCache.Scalars>(key: TKey): ApolloCache.GetScalarType<TKey> | undefined;
+    // (undocumented)
     identify(object: StoreObject | Reference): string | undefined;
     // (undocumented)
     lookupFragment(fragmentName: string): FragmentDefinitionNode | null;
@@ -117,6 +130,8 @@ export abstract class ApolloCache {
     abstract reset(options?: Cache_2.ResetOptions): Promise<void>;
     resolvesClientField?(typename: string, fieldName: string): boolean;
     abstract restore(serializedState: unknown): this;
+    serializeVariables<TVariables extends OperationVariables = OperationVariables>(document: DocumentNode | TypedDocumentNode<any, TVariables>, variables: NoInfer_2<TVariables>): TVariables;
+    serializeVariables<TVariables extends OperationVariables = OperationVariables>(document: DocumentNode | TypedDocumentNode<any, TVariables>, variables: NoInfer_2<TVariables> | undefined): TVariables | undefined;
     // (undocumented)
     transformDocument(document: DocumentNode): DocumentNode;
     // (undocumented)
@@ -488,6 +503,7 @@ export type FieldPolicy<TExisting = any, TIncoming = TExisting, TReadResult = TI
     keyArgs?: KeySpecifier | KeyArgsFunction | false;
     read?: FieldReadFunction<TExisting, TReadResult, TReadOptions>;
     merge?: FieldMergeFunction<TExisting, TIncoming, TMergeOptions> | boolean;
+    scalar?: ScalarNames;
 };
 
 // @public (undocumented)
@@ -553,9 +569,32 @@ export interface IgnoreModifier {
 // @public (undocumented)
 const _ignoreModifier: unique symbol;
 
+// @public (undocumented)
+export namespace InMemoryCache {
+    // Warning: (ae-forgotten-export) The symbol "KnownScalars" needs to be exported by the entry point index.d.ts
+    //
+    // (undocumented)
+    export type ScalarsOption = {
+        [ScalarName in keyof KnownScalars as IsLooselyEqual<KnownScalars[ScalarName]["serialized"], KnownScalars[ScalarName]["parsed"]> extends true ? ScalarName : never]?: KnownScalars[ScalarName] extends ({
+            serialized: infer TSerialized;
+            parsed: infer TParsed;
+        }) ? Scalar<TSerialized, TParsed> : never;
+    } & {
+        [ScalarName in keyof KnownScalars as IsLooselyEqual<KnownScalars[ScalarName]["serialized"], KnownScalars[ScalarName]["parsed"]> extends true ? never : ScalarName]: KnownScalars[ScalarName] extends ({
+            serialized: infer TSerialized;
+            parsed: infer TParsed;
+        }) ? Scalar<TSerialized, TParsed> : never;
+    } & (ApolloCache.Scalars extends (Record<string, {
+        serialized: infer TSerialized;
+        parsed: infer TParsed;
+    }>) ? Record<string, Scalar<TSerialized, TParsed>> : {});
+}
+
 // @public (undocumented)
 export class InMemoryCache extends ApolloCache {
-    constructor(config?: InMemoryCacheConfig);
+    constructor(...args: {} extends InMemoryCache.ScalarsOption ? [
+    config?: InMemoryCacheConfig
+    ] : [config: InMemoryCacheConfig]);
     // (undocumented)
     readonly assumeImmutableResults = true;
     batch<TUpdateResult>(options: Cache_2.BatchOptions<InMemoryCache, TUpdateResult>): TUpdateResult;
@@ -580,6 +619,8 @@ export class InMemoryCache extends ApolloCache {
     // @internal @deprecated
     getMemoryInternals?: typeof getInMemoryCacheMemoryInternals;
     // (undocumented)
+    getScalar<TKey extends keyof ApolloCache.Scalars>(key: TKey): ApolloCache.GetScalarType<TKey> extends (Scalar<infer TSerialized, infer TParsed>) ? IsLooselyEqual<TSerialized, TParsed> extends true ? ApolloCache.GetScalarType<TKey> | undefined : ApolloCache.GetScalarType<TKey> : never;
+    // (undocumented)
     identify(object: StoreObject | Reference): string | undefined;
     // (undocumented)
     lookupFragment(fragmentName: string): FragmentDefinitionNode | null;
@@ -609,6 +650,8 @@ export class InMemoryCache extends ApolloCache {
     restore(data: NormalizedCacheObject): this;
     // (undocumented)
     retain(rootId: string, optimistic?: boolean): number;
+    serializeVariables<TVariables extends OperationVariables = OperationVariables>(document: DocumentNode | TypedDocumentNode<any, TVariables>, variables: NoInfer_2<TVariables>): TVariables;
+    serializeVariables<TVariables extends OperationVariables = OperationVariables>(document: DocumentNode | TypedDocumentNode<any, TVariables>, variables: NoInfer_2<TVariables> | undefined): TVariables | undefined;
     // (undocumented)
     transformDocument(document: DocumentNode): DocumentNode;
     // (undocumented)
@@ -618,15 +661,30 @@ export class InMemoryCache extends ApolloCache {
 }
 
 // @public (undocumented)
-export interface InMemoryCacheConfig extends ApolloReducerConfig {
-    // (undocumented)
-    fragments?: FragmentRegistryAPI;
-    // (undocumented)
+export type InMemoryCacheConfig = ApolloReducerConfig & {
+    resultCaching?: boolean;
     possibleTypes?: PossibleTypesMap;
+    typePolicies?: TypePolicies;
+    fragments?: FragmentRegistryAPI;
+    inputObjects?: InputObjectsOption;
+} & ({} extends InMemoryCache.ScalarsOption ? InMemoryCache.ScalarsOption extends Record<string, never> ? {
+    scalars?: Record<string, `Scalar types must be declared in ApolloCache.Scalars before usage. See https://www.apollographql.com/docs/react/data/typescript#declaring-scalar-types.`>;
+} : {
+    scalars?: InMemoryCache.ScalarsOption;
+} : {
+    scalars: InMemoryCache.ScalarsOption;
+});
+
+// @public (undocumented)
+export interface InputObjectConfig {
     // (undocumented)
-    resultCaching?: boolean;
+    fields: Record<string, string>;
+}
+
+// @public (undocumented)
+export interface InputObjectsOption {
     // (undocumented)
-    typePolicies?: TypePolicies;
+    [inputObjectName: string]: InputObjectConfig;
 }
 
 // @public (undocumented)
@@ -664,6 +722,9 @@ type KeyFieldsFunction = (object: Readonly<StoreObject>, context: KeyFieldsConte
 // @public (undocumented)
 type KeySpecifier = ReadonlyArray<string | KeySpecifier>;
 
+// @public (undocumented)
+type KnownScalars = RemoveIndexSignature<ApolloCache.Scalars>;
+
 // @public (undocumented)
 class Layer extends EntityStore {
     constructor(id: string, parent: EntityStore, replay: (layer: EntityStore) => any, group: CacheGroup);
@@ -827,6 +888,8 @@ export class Policies {
     getMergeFunction(parentTypename: string | undefined, fieldName: string, childTypename: string | undefined): FieldMergeFunction | undefined;
     // (undocumented)
     getReadFunction(typename: string | undefined, fieldName: string): FieldReadFunction | undefined;
+    // (undocumented)
+    getScalarForField(typename: string, fieldName: string): Scalar<any, any> | undefined;
     // Warning: (ae-forgotten-export) The symbol "FieldSpecifier" needs to be exported by the entry point index.d.ts
     //
     // (undocumented)
@@ -931,6 +994,39 @@ class Root extends EntityStore {
 // @public (undocumented)
 type SafeReadonly<T> = T extends object ? Readonly<T> : T;
 
+// @public (undocumented)
+export namespace Scalar {
+    // (undocumented)
+    export interface Options<TSerialized, TParsed> {
+        // (undocumented)
+        is?(value: TSerialized | TParsed): boolean;
+        // (undocumented)
+        parse(serializedValue: TSerialized): NoInfer_2<TParsed>;
+        // (undocumented)
+        serialize(parsedValue: TParsed): NoInfer_2<TSerialized>;
+    }
+}
+
+// @public (undocumented)
+export class Scalar<TSerialized, TParsed> {
+    constructor(options: Scalar.Options<TSerialized, TParsed>);
+    // (undocumented)
+    coerceToParsed(value: TSerialized | TParsed): TParsed;
+    // (undocumented)
+    coerceToSerialized(value: TSerialized | TParsed): TSerialized;
+    // (undocumented)
+    static fromGraphQLScalarType<TSerialized, TParsed>(scalarType: GraphQLScalarType<TParsed, TSerialized>, options?: Pick<Scalar.Options<NoInfer_2<TSerialized>, NoInfer_2<TParsed>>, "is">): Scalar<TSerialized, TParsed>;
+    // (undocumented)
+    is(value: TSerialized | TParsed): value is TParsed;
+    // (undocumented)
+    parse(value: TSerialized): TParsed;
+    // (undocumented)
+    serialize(value: TParsed): TSerialized;
+}
+
+// @public (undocumented)
+type ScalarNames = keyof KnownScalars | (string extends keyof ApolloCache.Scalars ? string & {} : never);
+
 // @public (undocumented)
 type StorageType = Record<string, any>;
 
@@ -1013,9 +1109,10 @@ interface WriteContext extends ReadMergeModifyContext {
 
 // Warnings were encountered during analysis:
 //
-// src/cache/inmemory/policies.ts:173:3 - (ae-forgotten-export) The symbol "KeySpecifier" needs to be exported by the entry point index.d.ts
-// src/cache/inmemory/policies.ts:173:3 - (ae-forgotten-export) The symbol "KeyArgsFunction" needs to be exported by the entry point index.d.ts
-// src/cache/inmemory/types.ts:135:3 - (ae-forgotten-export) The symbol "KeyFieldsFunction" needs to be exported by the entry point index.d.ts
+// src/cache/inmemory/policies.ts:176:3 - (ae-forgotten-export) The symbol "KeySpecifier" needs to be exported by the entry point index.d.ts
+// src/cache/inmemory/policies.ts:176:3 - (ae-forgotten-export) The symbol "KeyArgsFunction" needs to be exported by the entry point index.d.ts
+// src/cache/inmemory/policies.ts:179:3 - (ae-forgotten-export) The symbol "ScalarNames" needs to be exported by the entry point index.d.ts
+// src/cache/inmemory/types.ts:139:3 - (ae-forgotten-export) The symbol "KeyFieldsFunction" needs to be exported by the entry point index.d.ts
 
 // (No @packageDocumentation comment for this package)
 

.api-reports/api-report-core.api.md

@@ -52,6 +52,8 @@ import type { IgnoreModifier } from '@apollo/client/cache';
 import type { Incremental } from '@apollo/client/incremental';
 import { InMemoryCache } from '@apollo/client/cache';
 import { InMemoryCacheConfig } from '@apollo/client/cache';
+import { InputObjectConfig } from '@apollo/client/cache';
+import { InputObjectsOption } from '@apollo/client/cache';
 import type { InternalTypes as InternalTypes_2 } from '@apollo/client';
 import type { InteropObservable } from 'rxjs';
 import type { IsAny } from '@apollo/client/utilities/internal';
@@ -87,6 +89,7 @@ import type { Reference as Reference_2 } from '@apollo/client/cache';
 import { RequestHandler } from '@apollo/client/link';
 import { resetCaches } from 'graphql-tag';
 import { rewriteURIForGET } from '@apollo/client/link/http';
+import { Scalar } from '@apollo/client/cache';
 import { selectHttpOptionsAndBody } from '@apollo/client/link/http';
 import { selectHttpOptionsAndBodyInternal } from '@apollo/client/link/http';
 import { selectURI } from '@apollo/client/link/http';
@@ -659,6 +662,10 @@ export { InMemoryCache }
 
 export { InMemoryCacheConfig }
 
+export { InputObjectConfig }
+
+export { InputObjectsOption }
+
 // Warning: (ae-forgotten-export) The symbol "RefetchQueriesIncludeShorthand" needs to be exported by the entry point index.d.ts
 //
 // @public (undocumented)
@@ -1000,7 +1007,7 @@ class QueryManager {
     // (undocumented)
     broadcastQueries(): void;
     // (undocumented)
-    get cache(): ApolloCache;
+    get cache(): Cache_2.Implementation;
     // (undocumented)
     clearStore(options?: Cache_2.ResetOptions): Promise<void>;
     // (undocumented)
@@ -1244,6 +1251,8 @@ export { resetCaches }
 
 export { rewriteURIForGET }
 
+export { Scalar }
+
 export { selectHttpOptionsAndBody }
 
 export { selectHttpOptionsAndBodyInternal }

.api-reports/api-report-utilities_internal.api.md

@@ -33,6 +33,7 @@ import type { SelectionSetNode } from 'graphql';
 import { StrongCache } from '@wry/caches';
 import type { Subscription } from 'rxjs';
 import type { Trie } from '@wry/trie';
+import type { TypeNode } from 'graphql';
 import type { TypeOverrides } from '@apollo/client';
 import { WeakCache } from '@wry/caches';
 
@@ -343,6 +344,9 @@ export const getStoreKeyName: ((fieldName: string, args?: Record<string, any> |
     setStringify(s: typeof storeKeyNameStringify): (value: any) => string;
 };
 
+// @internal @deprecated (undocumented)
+export function getUnwrappedType(node: TypeNode): string;
+
 // @public (undocumented)
 const globalCaches: {
     print?: () => number;
@@ -370,6 +374,13 @@ export function isDocumentNode(value: unknown): value is DocumentNode;
 // @internal @deprecated (undocumented)
 export function isField(selection: SelectionNode): selection is FieldNode;
 
+// @public
+export type IsLooselyEqual<A, B> = [
+A
+] extends [B] ? [
+B
+] extends [A] ? true : false : false;
+
 // @internal @deprecated (undocumented)
 export function isNonEmptyArray<T>(value: ArrayLike<T> | null | undefined): value is Array<T>;