[Custom scalars] Handle scalar parsing during cache reads and writes by jerelmiller · Pull Request #13259 · apollographql/apollo-client

jerelmiller · 2026-06-04T21:53:15Z

Part of the custom scalars work: #13227

Adds scalar value serialization for scalar fields during cache writes. This allows users to provide either the parsed or serialized value to the cache and have it work as expected.

Copilot

Pull request overview

This PR extends the InMemoryCache custom-scalars work by allowing scalar fields (configured via a new scalar field policy option) to be coerced during cache writes/merges and during cache.extract()/cache.restore(), so users can provide either parsed or serialized values and get consistent behavior.

Changes:

Adds scalar?: ScalarNames to field policies and plumbing to resolve a scalar per (typename, fieldName).
Coerces scalar values to parsed form during writes/merges, and serializes them during cache extraction (with complementary parsing during restore via the merge path).
Adds extensive runtime tests and TypeScript type-tests validating scalar policy typing and scalar coercion behavior.

Reviewed changes

Copilot reviewed 25 out of 26 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
src/cache/inmemory/writeToStore.ts	Coerces scalar field values during write paths (including post-merge-function).
src/cache/inmemory/readFromStore.ts	Adds a DEV warning when `scalar` is configured on a field that actually has a selection set.
src/cache/inmemory/policies.ts	Adds `scalar` to `FieldPolicy` plus scalar lookup/coercion helpers (`getScalarForField`, `maybeCoerce*`).
src/cache/inmemory/entityStore.ts	Parses scalar values before merging and serializes scalar values during `extract()`.
src/cache/inmemory/types.ts	Introduces `KnownScalars`/`ScalarNames` typing helpers used by the new `FieldPolicy.scalar` option.
src/cache/inmemory/inMemoryCache.ts	Refactors scalar-related types to reuse `KnownScalars` from `types.ts`.
src/cache/inmemory/tests/scalars.ts	Adds comprehensive behavioral tests for scalar parsing/serialization across cache APIs.
integration-tests/type-tests/customScalars/mixed/index.ts	Adds type-test coverage restricting `FieldPolicy.scalar` to known scalar names in this scenario.
integration-tests/type-tests/customScalars/matchingTypes/index.ts	Adds type-test coverage for allowed/disallowed scalar names in field policies.
integration-tests/type-tests/customScalars/empty/index.ts	Adds type-test coverage ensuring no scalar names are allowed when none are declared.
integration-tests/type-tests/customScalars/differentTypes/index.ts	Adds type-test coverage restricting scalar names when only some scalars are declared.
integration-tests/type-tests/customScalars/all-unknown/mixed/index.ts	Adds type-test coverage allowing any scalar name when scalar typing is fully unknown.
integration-tests/type-tests/customScalars/all-unknown/matchingTypes/index.ts	Adds type-test coverage allowing any scalar name when scalar typing is fully unknown.
integration-tests/type-tests/customScalars/all-unknown/empty/index.ts	Adds type-test coverage allowing any scalar name when scalar typing is fully unknown.
integration-tests/type-tests/customScalars/all-unknown/differentTypes/index.ts	Adds type-test coverage allowing any scalar name when scalar typing is fully unknown.
integration-tests/type-tests/customScalars/all-structured/mixed/index.ts	Adds type-test coverage allowing any scalar name in the “all-structured” scenario.
integration-tests/type-tests/customScalars/all-structured/matchingTypes/index.ts	Adds type-test coverage allowing any scalar name in the “all-structured” scenario.
integration-tests/type-tests/customScalars/all-structured/empty/index.ts	Adds type-test coverage allowing any scalar name in the “all-structured” scenario.
integration-tests/type-tests/customScalars/all-structured/differentTypes/index.ts	Adds type-test coverage allowing any scalar name in the “all-structured” scenario.
integration-tests/type-tests/customScalars/all-any/mixed/index.ts	Adds type-test coverage allowing any scalar name when scalar typing is `any`.
integration-tests/type-tests/customScalars/all-any/matchingTypes/index.ts	Adds type-test coverage allowing any scalar name when scalar typing is `any`.
integration-tests/type-tests/customScalars/all-any/empty/index.ts	Fixes imports and adds type-test coverage allowing any scalar name when scalar typing is `any`.
integration-tests/type-tests/customScalars/all-any/differentTypes/index.ts	Adds type-test coverage allowing any scalar name when scalar typing is `any`.
.changeset/strong-shoes-sell.md	Documents the new `FieldPolicy.scalar` option and its effect on reads/writes/extract/restore.
.api-reports/api-report.api.md	Updates API report for new public types/methods introduced by scalar coercion support.
.api-reports/api-report-cache.api.md	Updates cache API report for the new `FieldPolicy.scalar` option and `Policies` APIs.

jerelmiller · 2026-06-10T15:50:22Z

+  public maybeCoerceToScalarValue(
+    value: StoreValue,
+    options: CoerceValueOptions
+  ): StoreValue {


Turns out I don't need these anymore now that all of the logic lives in EntityStore. Removed in 03945ef

…13259) _Part of the custom scalars work: https://github.com/apollographql/apollo-client/issues/13227_ Adds scalar value serialization for scalar fields during cache writes. This allows users to provide either the parsed or serialized value to the cache and have it work as expected.

phryneas · 2026-06-12T11:32:28Z

+    coerce: (scalar: Scalar<any, any>, value: unknown) => unknown,
+    typename = obj.__typename
+  ): StoreObject {
+    if (!typename) {


@jerelmiller could we add an early bailout for a "no scalars defined" case?

I caught this after I merged this PR and put it in #13273: https://github.com/apollographql/apollo-client/pull/13273/changes#diff-246cd7915328b250bf54f58d58c38b3101c8c65be631f0cf93318d79405432c4 🙂

phryneas · 2026-06-12T11:39:27Z

+        this.policies.rootTypenamesById[dataId]
+    );
+
    const merged: StoreObject = new DeepMerger({


Does DeepMerger need new safeguards so it doesn't smush together the implementation details of user-defined distinct scalar values?

I don't think so? We would have had this problem already I would think since you still have the possibility of e.g. object scalars (like JSON), and that seems to be working fine 🤔

I would assume that this has been wonky all the time until now, and nobody ever noticed/reported it.

@jerelmiller

This PR was opened by the [Changesets release](https://github.com/changesets/action) GitHub action. When you're ready to do a release, you can merge this and the packages will be published to npm automatically. If you're not ready to do a release yet, that's fine, whenever you add more changesets to release-4.3, this PR will be updated. ⚠️

⚠️

⚠️ `release-4.3` is currently in **pre mode** so this branch has prereleases rather than normal releases. If you want to exit prereleases, run `changeset pre exit` on `release-4.3`. ⚠️

⚠️

⚠️ # Releases ## @apollo/client@4.3.0-alpha.2 ### Minor Changes - [#13274](#13274) [`7b10078`](7b10078) Thanks [@jerelmiller](https://github.com/jerelmiller)! - Adds `Scalar.fromGraphQLScalarType` helper to create a `Scalar` instance from an existing graphql.js `GraphQLScalarType`. ```ts import { GraphQLScalarType } from "graphql"; import { Scalar } from "@apollo/client"; const dateTimeScalarType = new GraphQLScalarType<Date, string>({ // ... }); const dateTimeScalar = Scalar.fromGraphQLScalarType(dateTimeScalarType, { is: (value) => value instanceof Date, }); ``` - [#13252](#13252) [`ed86234`](ed86234) Thanks [@jerelmiller](https://github.com/jerelmiller)! - Adds the plumbing and types implementation for declaring custom scalars and configuring custom scalars in `InMemoryCache`. You can declare custom scalar types with declaration merging on the `ApolloCache.Scalars` interface: ```ts // apollo.d.ts import "@apollo/client"; declare module "@apollo/client" { namespace ApolloCache { interface Scalars { Date: { serialized: string; parsed: Date }; } } } ``` This enables the `scalars` option in `InMemoryCache`: ```ts import { Scalar } from "@apollo/client"; const cache = new InMemoryCache({ scalars: { Date: new Scalar({ parse: (dateString) => new Date(dateString), serialize: (date) => date.toISOString(), is: (value) => value instanceof Date, }), }, }); ``` - [#13259](#13259) [`ccaf686`](ccaf686) Thanks [@jerelmiller](https://github.com/jerelmiller)! - Adds a `scalar` option to `InMemoryCache` field policies that tells the cache which scalar to use when parsing or serializing the field value. ```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", }, }, }, }, }); ``` This scalar definition is now used to properly parse or serialize the field value for cache reads and writes as well as `cache.extract()` and `cache.restore()`. - [#13273](#13273) [`0886de1`](0886de1) Thanks [@jerelmiller](https://github.com/jerelmiller)! - Automatically serialize variables that include custom scalar values. This includes cache reads and writes as well as requests to the network. For more complex input objects, a new `inputObjects` option is available to `InMemoryCache` that specifies where nested scalar fields are found. ```ts const cache = new InMemoryCache({ scalars: { DateTime: new Scalar({ parse: (value) => new Date(value), serialize: (value) => value.toISOString(), is: (value) => value instanceof Date, }), }, inputObjects: { EventFilter: { fields: { date: "DateTime", }, }, }, }); const client = new ApolloClient({ cache, link }); await client.query({ query: gql` query Event($filter: EventFilter!) { event(filter: $filter) { name } } `, variables: { filter: { date: new Date("2026-01-01T00:00:00.000Z"), }, }, }); // The link receives: // { filter: { date: "2026-01-01T00:00:00.000Z" } } ``` - [#13252](#13252) [`ed86234`](ed86234) Thanks [@jerelmiller](https://github.com/jerelmiller)! - Adds the `getScalar` abstract method to `ApolloCache` that cache subclasses override to provide scalar behavior to Apollo Client. Defaults to unconditionally return `undefined` if not specified. --------- Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> Co-authored-by: Jerel Miller <jerelmiller@gmail.com>

jerelmiller added 30 commits June 3, 2026 20:38

Add scalar option to FieldPolicy

1d8b11d

Use 2026 as year

ba2f61b

Add scalar to internal type

58898ee

Set scalar on field policy

22fb795

Add failing tests for custom scalars

8afe099

Add scalar coercion to policies

ce9c806

Better handle parsing scalars from nested arrays

57726f9

Don't try and coerce null

46bbdf0

Handle object-based scalar values

2192a3f

Add test for primitive to primitive transform

45522d5

Add test for scalar in object array

2a435d2

Add test to ensure multiple scalars work

abede49

Add test for named/inline fragment

9f77b9e

Add tests for union type

44bcc67

Add test for interface type

7465d90

Add kitchen sink test

92fa896

Add changeset

0a20a22

Add dev-only warning for scalars configured on non-scalar fields

4ce0ebf

Remove outdated comment

d9ec3d9

Add test for cache.watchFragment

584ded7

Move KnownScalars type to types file

6320ddf

Provide better autocomplete for scalars that extends Record<string, ...>

b323aeb

Update type tests with scalar config

eb8f3b8

Remove unused import

9df3afd

Add test for scalar field but no implementation

2fa16e0

Update api report

79bb57b

Add test to ensure addTypePolicies deep merges scalar field

a671aca

Add tests for validating value remains unchanged

fe7ae37

Handle coercing array values

5748c88

Add test for validating 2d array

380e1d2

jerelmiller added 2 commits June 9, 2026 11:04

Let merge handle coercion

8093ca3

Maintain referential equality when no field changes

6bdd540

jerelmiller marked this pull request as ready for review June 9, 2026 19:59

jerelmiller added 2 commits June 9, 2026 15:17

Revert coercion in readFromStore

3628a90

Refine changesets

346d50f

jerelmiller force-pushed the jerel/scalar-cache-writes branch from acd4729 to 31b8365 Compare June 9, 2026 21:33

Add additional type in type check

f073d14

jerelmiller force-pushed the jerel/scalar-cache-writes branch from 31b8365 to 9ba29b6 Compare June 9, 2026 21:34

Rename arg

99f627a

jerelmiller requested a review from Copilot June 9, 2026 23:16

Copilot started reviewing on behalf of jerelmiller June 9, 2026 23:16 View session

jerelmiller requested a review from DaleSeo June 9, 2026 23:16

Copilot AI reviewed Jun 9, 2026

View reviewed changes

DaleSeo reviewed Jun 10, 2026

View reviewed changes

Comment thread src/cache/inmemory/writeToStore.ts Outdated

Comment thread src/cache/inmemory/entityStore.ts

jerelmiller added 4 commits June 10, 2026 09:44

Remove double coercion when writing data to the cache

c1860ab

Fix calling coerceToValue more than once accidentally

8144496

Remove unused maybeCoerce* methods in Policies

889ab23

Swap args

260a649

jerelmiller requested a review from DaleSeo June 10, 2026 15:55

DaleSeo approved these changes Jun 10, 2026

View reviewed changes

github-actions Bot added the auto-cleanup 🤖 label Jun 10, 2026

jerelmiller force-pushed the jerel/scalar-cache-writes branch from adcaf51 to 260a649 Compare June 10, 2026 16:04

Base automatically changed from jerel/custom-scalar-config to feat/custom-scalars June 10, 2026 16:04

jerelmiller merged commit ccaf686 into feat/custom-scalars Jun 10, 2026
44 of 46 checks passed

jerelmiller deleted the jerel/scalar-cache-writes branch June 10, 2026 16:31

phryneas reviewed Jun 12, 2026

View reviewed changes

jerelmiller mentioned this pull request Jun 30, 2026

Version Packages (alpha) #13297

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

[Custom scalars] Handle scalar parsing during cache reads and writes - #13259

[Custom scalars] Handle scalar parsing during cache reads and writes#13259
jerelmiller merged 84 commits into
feat/custom-scalarsfrom
jerel/scalar-cache-writes

jerelmiller commented Jun 4, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

jerelmiller Jun 10, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

phryneas Jun 12, 2026

Uh oh!

jerelmiller Jun 17, 2026

Uh oh!

phryneas Jun 12, 2026

Uh oh!

jerelmiller Jun 17, 2026

Uh oh!

phryneas Jun 18, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Uh oh!

Conversation

jerelmiller commented Jun 4, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

jerelmiller Jun 10, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

phryneas Jun 12, 2026

Choose a reason for hiding this comment

Uh oh!

jerelmiller Jun 17, 2026

Choose a reason for hiding this comment

Uh oh!

phryneas Jun 12, 2026

Choose a reason for hiding this comment

Uh oh!

jerelmiller Jun 17, 2026

Choose a reason for hiding this comment

Uh oh!

phryneas Jun 18, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants