[Custom scalars] Implement scalar option in field policies with cache reads

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

@@ -345,6 +345,14 @@ export { canonicalStringify }
 // @public (undocumented)
 type CanReadFunction = (value: StoreValue) => boolean;
 
+// @public (undocumented)
+interface CoerceValueOptions {
+    // (undocumented)
+    field: FieldNode;
+    // (undocumented)
+    typename: string;
+}
+
 // @public (undocumented)
 export function createFragmentRegistry(...fragments: DocumentNode[]): FragmentRegistryAPI;
 
@@ -495,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)
@@ -872,6 +881,10 @@ export class Policies {
     hasKeyArgs(typename: string | undefined, fieldName: string): boolean;
     // (undocumented)
     identify(object: StoreObject, partialContext?: Partial<KeyFieldsContext>): [string?, StoreObject?];
+    // Warning: (ae-forgotten-export) The symbol "CoerceValueOptions" needs to be exported by the entry point index.d.ts
+    //
+    // (undocumented)
+    maybeCoerceToScalarValue(value: StoreValue, options: CoerceValueOptions): any;
     // (undocumented)
     readField<V = StoreValue>(options: ReadFieldOptions, context: ReadMergeModifyContext): SafeReadonly<V> | undefined;
     // (undocumented)
@@ -996,6 +1009,9 @@ export class Scalar<TSerialized, TParsed> {
     serialize(value: TParsed): TSerialized;
 }
 
+// @public (undocumented)
+type ScalarNames = keyof KnownScalars | (string extends keyof ApolloCache.Scalars ? string & {} : never);
+
 // @public (undocumented)
 type StorageType = Record<string, any>;
 
@@ -1078,9 +1094,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:136:3 - (ae-forgotten-export) The symbol "KeyFieldsFunction" needs to be exported by the entry point index.d.ts
+// src/cache/inmemory/policies.ts:175:3 - (ae-forgotten-export) The symbol "KeySpecifier" needs to be exported by the entry point index.d.ts
+// src/cache/inmemory/policies.ts:175:3 - (ae-forgotten-export) The symbol "KeyArgsFunction" needs to be exported by the entry point index.d.ts
+// src/cache/inmemory/policies.ts:178: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.api.md

@@ -946,6 +946,14 @@ class ClientAwarenessLink extends ApolloLink {
     constructor(options?: ClientAwarenessLink.Options);
 }
 
+// @public (undocumented)
+interface CoerceValueOptions {
+    // (undocumented)
+    field: FieldNode;
+    // (undocumented)
+    typename: string;
+}
+
 // @public (undocumented)
 export namespace CombinedGraphQLErrors {
     // (undocumented)
@@ -1327,6 +1335,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)
@@ -2371,6 +2380,10 @@ class Policies {
     hasKeyArgs(typename: string | undefined, fieldName: string): boolean;
     // (undocumented)
     identify(object: StoreObject, partialContext?: Partial<KeyFieldsContext>): [string?, StoreObject?];
+    // Warning: (ae-forgotten-export) The symbol "CoerceValueOptions" needs to be exported by the entry point index.d.ts
+    //
+    // (undocumented)
+    maybeCoerceToScalarValue(value: StoreValue, options: CoerceValueOptions): any;
     // Warning: (ae-forgotten-export) The symbol "ReadFieldOptions" needs to be exported by the entry point index.d.ts
     //
     // (undocumented)
@@ -2823,6 +2836,9 @@ export class Scalar<TSerialized, TParsed> {
     serialize(value: TParsed): TSerialized;
 }
 
+// @public (undocumented)
+type ScalarNames = keyof KnownScalars | (string extends keyof ApolloCache.Scalars ? string & {} : never);
+
 // Warning: (ae-forgotten-export) The symbol "HttpConfig" needs to be exported by the entry point index.d.ts
 //
 // @public (undocumented)
@@ -3139,11 +3155,12 @@ interface WriteContext extends ReadMergeModifyContext {
 // Warnings were encountered during analysis:
 //
 // src/cache/core/cache.ts:127:11 - (ae-forgotten-export) The symbol "MissingTree" needs to be exported by the entry point index.d.ts
-// src/cache/inmemory/policies.ts:101:3 - (ae-forgotten-export) The symbol "FragmentMap" needs to be exported by the entry point index.d.ts
-// 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:136:3 - (ae-forgotten-export) The symbol "KeyFieldsFunction" needs to be exported by the entry point index.d.ts
-// src/cache/inmemory/types.ts:143:3 - (ae-forgotten-export) The symbol "FragmentRegistryAPI" needs to be exported by the entry point index.d.ts
+// src/cache/inmemory/policies.ts:103:3 - (ae-forgotten-export) The symbol "FragmentMap" needs to be exported by the entry point index.d.ts
+// src/cache/inmemory/policies.ts:175:3 - (ae-forgotten-export) The symbol "KeySpecifier" needs to be exported by the entry point index.d.ts
+// src/cache/inmemory/policies.ts:175:3 - (ae-forgotten-export) The symbol "KeyArgsFunction" needs to be exported by the entry point index.d.ts
+// src/cache/inmemory/policies.ts:178: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
+// src/cache/inmemory/types.ts:146:3 - (ae-forgotten-export) The symbol "FragmentRegistryAPI" needs to be exported by the entry point index.d.ts
 // src/core/ApolloClient.ts:201:5 - (ae-forgotten-export) The symbol "IgnoreModifier" needs to be exported by the entry point index.d.ts
 // src/core/ApolloClient.ts:633:5 - (ae-forgotten-export) The symbol "NextFetchPolicyContext" needs to be exported by the entry point index.d.ts
 // src/core/ObservableQuery.ts:375:5 - (ae-forgotten-export) The symbol "QueryManager" needs to be exported by the entry point index.d.ts

.changeset/strong-shoes-sell.md

@@ -0,0 +1,28 @@
+---
+"@apollo/client": minor
+---
+
+Adds a `scalar` option to `InMemoryCache` field policies that dictates whether to parse the raw value using the custom scalar definition. Scalar parsing is now performed on cache reads.
+
+```ts
+import { Scalar } from "@apollo/client";
+
+new InMemoryCache({
+  scalars: {
+    DateTime: new Scalar({
+      parse: (dateString) => new Date(dateString),
+      serialize: (date) => date.toISOString(),
+    }),
+  },
+  typePolicies: {
+    Event: {
+      fields: {
+        startTime: {
+          // Parse this field using the DateTime scalar
+          scalar: "DateTime",
+        },
+      },
+    },
+  },
+});
+```

integration-tests/type-tests/customScalars/all-any/differentTypes/index.ts

@@ -209,3 +209,26 @@ test("InMemoryCache.getScalar returns the resolved scalar for a declared scalar"
     Scalar<any, any> | undefined
   >();
 });
+
+test("allows any scalar name in field policies", () => {
+  new InMemoryCache({
+    scalars: {
+      DateTime: new Scalar({
+        serialize: (value) => value.toISOString(),
+        parse: (value) => new Date(value),
+      }),
+    },
+    typePolicies: {
+      Event: {
+        fields: {
+          startDate: {
+            scalar: "DateTime",
+          },
+          metadata: {
+            scalar: "JSONObject",
+          },
+        },
+      },
+    },
+  });
+});

integration-tests/type-tests/customScalars/all-any/empty/index.ts

@@ -152,3 +152,20 @@ test("getScalar returns the resolved scalar or undefined", () => {
     Scalar<any, any> | undefined
   >();
 });
+
+test("allows any scalar name in field policies", () => {
+  new InMemoryCache({
+    typePolicies: {
+      Event: {
+        fields: {
+          startDate: {
+            scalar: "DateTime",
+          },
+          metadata: {
+            scalar: "JSONObject",
+          },
+        },
+      },
+    },
+  });
+});

integration-tests/type-tests/customScalars/all-any/matchingTypes/index.ts

@@ -228,3 +228,23 @@ test("getScalar returns the resolved scalar or undefined", () => {
     Scalar<any, any> | undefined
   >();
 });
+
+test("allows any scalar name in field policies", () => {
+  new InMemoryCache({
+    typePolicies: {
+      Event: {
+        fields: {
+          startDate: {
+            scalar: "RelativeDate",
+          },
+          metadata: {
+            scalar: "JSONObject",
+          },
+          unknown: {
+            scalar: "Unknown",
+          },
+        },
+      },
+    },
+  });
+});

integration-tests/type-tests/customScalars/all-any/mixed/index.ts

@@ -128,3 +128,29 @@ test("getScalar resolves each scalar according to its declaration", () => {
     Scalar<any, any> | undefined
   >();
 });
+
+test("allows any scalar name in field policies", () => {
+  new InMemoryCache({
+    scalars: {
+      DateTime: new Scalar({
+        serialize: (value) => value.toISOString(),
+        parse: (value) => new Date(value),
+      }),
+    },
+    typePolicies: {
+      Event: {
+        fields: {
+          startDate: {
+            scalar: "DateTime",
+          },
+          endDate: {
+            scalar: "RelativeDate",
+          },
+          metadata: {
+            scalar: "Unknown",
+          },
+        },
+      },
+    },
+  });
+});

integration-tests/type-tests/customScalars/all-structured/differentTypes/index.ts

@@ -32,3 +32,27 @@ test("a transforming scalar that conflicts with the index cannot be configured",
     },
   });
 });
+
+test("allows any scalar name in field policies", () => {
+  new InMemoryCache({
+    // @ts-expect-error `DateTime` is not assignable to index signature
+    scalars: {
+      DateTime: new Scalar({
+        serialize: (value: Date) => value.toISOString(),
+        parse: (value: string) => new Date(value),
+      }),
+    },
+    typePolicies: {
+      Event: {
+        fields: {
+          startDate: {
+            scalar: "DateTime",
+          },
+          metadata: {
+            scalar: "JSONObject",
+          },
+        },
+      },
+    },
+  });
+});

integration-tests/type-tests/customScalars/all-structured/empty/index.ts

@@ -150,3 +150,20 @@ test("getScalar returns the resolved scalar or undefined", () => {
     Scalar<string, string> | undefined
   >();
 });
+
+test("allows any scalar name in field policies", () => {
+  new InMemoryCache({
+    typePolicies: {
+      Event: {
+        fields: {
+          startDate: {
+            scalar: "DateTime",
+          },
+          metadata: {
+            scalar: "JSONObject",
+          },
+        },
+      },
+    },
+  });
+});

integration-tests/type-tests/customScalars/all-structured/matchingTypes/index.ts

@@ -113,3 +113,23 @@ test("getScalar resolves each scalar according to its declaration", () => {
     Scalar<string, string> | undefined
   >();
 });
+
+test("allows any scalar name in field policies", () => {
+  new InMemoryCache({
+    typePolicies: {
+      Event: {
+        fields: {
+          startDate: {
+            scalar: "RelativeDate",
+          },
+          metadata: {
+            scalar: "JSONObject",
+          },
+          unknown: {
+            scalar: "Unknown",
+          },
+        },
+      },
+    },
+  });
+});

integration-tests/type-tests/customScalars/all-structured/mixed/index.ts

@@ -38,3 +38,34 @@ test("a transforming scalar conflicting with the index blocks configuration", ()
     },
   });
 });
+
+test("allows any scalar name in field policies", () => {
+  new InMemoryCache({
+    // @ts-expect-error `DateTime` is not assignable to index signature
+    scalars: {
+      DateTime: new Scalar({
+        serialize: (value) => value.toISOString(),
+        parse: (value) => new Date(value),
+      }),
+      RelativeDate: new Scalar({
+        serialize: (value) => value,
+        parse: (value) => value,
+      }),
+    },
+    typePolicies: {
+      Event: {
+        fields: {
+          startDate: {
+            scalar: "DateTime",
+          },
+          endDate: {
+            scalar: "RelativeDate",
+          },
+          metadata: {
+            scalar: "Unknown",
+          },
+        },
+      },
+    },
+  });
+});

integration-tests/type-tests/customScalars/all-unknown/differentTypes/index.ts

@@ -210,3 +210,26 @@ test("InMemoryCache.getScalar returns the resolved scalar for a declared scalar"
     Scalar<unknown, unknown> | undefined
   >();
 });
+
+test("allows any scalar name in field policies", () => {
+  new InMemoryCache({
+    scalars: {
+      DateTime: new Scalar({
+        serialize: (value) => value.toISOString(),
+        parse: (value) => new Date(value),
+      }),
+    },
+    typePolicies: {
+      Event: {
+        fields: {
+          startDate: {
+            scalar: "DateTime",
+          },
+          metadata: {
+            scalar: "JSONObject",
+          },
+        },
+      },
+    },
+  });
+});