Docs
Launch GraphOS Studio

class InMemoryCache

API reference


Methods of the InMemoryCache class (the cache used by almost every instance of ApolloClient) are here.

Before reading about individual methods, see Caching in Apollo Client.

readQuery

Executes a directly against the cache and returns its result (or null if the cannot be fulfilled):

// Query a cached Todo object with id 5
const { todo } = cache.readQuery({
query: gql`
query ReadTodo {
todo(id: 5) {
id
text
completed
}
}
`,
});

For usage instructions, see Interacting with cached data: readQuery.

Accepts the following parameters:

Name /
Type
Description
options

Object

Required. Provides configuration options for the , including the actual query to execute.

Supported are listed below.

optimistic

Boolean

If true, readQuery returns optimistic results.

The default value is false.

Options

Name /
Type
Description
query

DocumentNode

Required. The to execute, created by wrapping a query string in the gql template literal.

variables

Object

A map of any names and values required by query.

id

String

The root id to use for the .

The default value is ROOT_QUERY, which is the ID of the root object.

By specifying the ID of another cached object, you can arbitrary cached data without conforming to the structure of your schema's supported queries. This enables readQuery to behave similarly to readFragment.

canonizeResults

Boolean

⚠️ Deprecated: Using canonizeResults can result in memory leaks so we generally do not recommend using this option anymore. A future version of will contain a similar feature without the risk of memory leaks.

If true, result objects read from the cache will be canonized, which means deeply-equal objects will also be === (literally the same object), allowing much more efficient comparison of past/present results.

The default value is false.

Signature

src/cache/core/cache.ts
readQuery<QueryType, TVariables = any>(
options: DataProxy.Query<TVariables>,
optimistic: boolean = false,
): QueryType | null

writeQuery

Writes data to the cache in the shape of a provided . Returns a Reference to the written object or undefined if the write failed.

// Create or modify a cached Todo object with id 5
cache.writeQuery({
query: gql`
query ReadTodo($id: ID!) {
todo(id: $id) {
id
text
completed
}
}
`,
data: {
todo: {
__typename: 'Todo',
id: 5,
text: 'Buy grapes 🍇',
completed: false
},
},
variables: {
id: 5
}
});

For usage instructions, see Interacting with cached data: writeQuery.

Takes an options object as a parameter. Supported of this object are described below.

Options

Name /
Type
Description
query

DocumentNode

Required. The that defines the shape of the data to write. Created by wrapping a query string in the gql template literal.

data

Object

Required. The data to write to the cache. This object's must conform to the shape defined by query.

variables

Object

A map of any names and values required by query.

id

String

The id of the root object to use with query.

The default value is ROOT_QUERY, which is the ID of the root object.

By specifying the ID of another cached object, you can modify arbitrary cached data without conforming to the structure of your schema's supported queries. This enables writeQuery to behave similarly to writeFragment.

broadcast

Boolean

If true, automatically refresh all active queries that depend on at least one that's modified by this call. If false, silences the broadcast of cache updates and prevents automatic refresh.

The default value is true.

overwrite

Boolean

If true, ignore existing cache data when calling merge functions, allowing incoming data to replace existing data, without warnings about data loss.

The default value is false.

Signature

src/cache/core/cache.ts
writeQuery<TData = any, TVariables = any>(
options: Cache.WriteQueryOptions<TData, TVariables>,
): Reference | undefined

updateQuery
Since 3.5

Fetches data from the cache in the shape of a provided , then updates that cached data according to a provided update function.

Returns the updated result or null if the update failed.

// Fetches a Todo object with id 5 and flips its `completed` boolean
cache.updateQuery({ // options object
query: gql`
query ReadTodo($id: ID!) {
todo(id: $id) {
id
text
completed
}
}
`,
variables: {
id: 5
}
}, (data) => ({ // update function
todo: {
...data.todo,
completed: !data.todo.completed
}
}));

Takes an options object and an update function as parameters (both described below).

Options

Name /
Type
Description
query

DocumentNode

Required. The that defines the shape of the data to fetch. Created by wrapping a query string in the gql template literal.

variables

Object

A map of any names and values required by query.

id

String

The id of the root object to use with query.

The default value is ROOT_QUERY, which is the ID of the root object.

By specifying the ID of another cached object, you can modify arbitrary cached data without conforming to the structure of your schema's supported queries. This enables updateQuery to behave similarly to updateFragment.

broadcast

Boolean

If true, automatically refresh all active queries that depend on at least one that's modified by this call. If false, silences the broadcast of cache updates and prevents automatic refresh.

The default value is true.

overwrite

Boolean

If true, ignore existing cache data when calling merge functions, allowing incoming data to replace existing data, without warnings about data loss.

The default value is false.

updateQuery update function

The update function of updateQuery takes a 's current cached value and returns the value that should replace it (or undefined if no change should be made).

The returned value is automatically passed to writeQuery, which modifies the cached data.

Please note the update function has to calculate the new value in an immutable way. You can read more about immutable updates in the React documentation.

Signature

src/cache/core/cache.ts
public updateQuery<TData = any, TVariables = any>(
options: Cache.UpdateQueryOptions<TData, TVariables>,
update: (data: TData | null) => TData | null | void,
): TData | null

readFragment

Reads data from the cache in the shape of a provided :

const todo = cache.readFragment({
id: '5', // The value of the to-do item's unique identifier
fragment: gql`
fragment MyTodo on Todo {
id
text
completed
}
`,
});

Returns the requested data or null if data is not available in the cache.

For usage instructions, see Interacting with cached data: readFragment.

Accepts the following parameters:

Name /
Type
Description
options

Object

Required. Provides configuration options, including the actual to use.

Supported are listed below.

optimistic

Boolean

If true, readFragment returns optimistic results.

The default value is false.

Options

Name /
Type
Description
id

String

Required. The ID of the cached object that this call is reading a of.

If the cache does not contain an object with the specified ID, readFragment returns null.

fragment

DocumentNode

Required. A created with the gql template literal tag that includes the to read.

If the includes more than one , you must also provide fragmentName to indicate which to use.

fragmentName

String

The name of the defined in the fragment to use in the call.

You don't need to provide this value if the fragment includes only one .

variables

Object

A map of any names and values required by fragment.

canonizeResults

Boolean

⚠️ Deprecated: Using canonizeResults can result in memory leaks so we generally do not recommend using this option anymore. A future version of will contain a similar feature without the risk of memory leaks.

If true, result objects read from the cache will be canonized, which means deeply-equal objects will also be === (literally the same object), allowing much more efficient comparison of past/present results.

The default value is false.

Signature

src/cache/core/cache.ts
readFragment<FragmentType, TVariables = any>(
options: DataProxy.Fragment<TVariables>,
optimistic: boolean = false,
): FragmentType | null

writeFragment

Writes data to the cache in the shape of the provided . Returns a Reference to the written object or undefined if the write failed.

client.writeFragment({
id: 'Todo:5',
fragment: gql`
fragment MyTodo on Todo {
completed
}
`,
data: {
completed: true,
},
});

For usage instructions, see Interacting with cached data: writeFragment.

Takes an options object as a parameter. Supported of this object are described below.

Options

Name /
Type
Description
id

String

Required. The ID of the cached object that this call is writing a to.

If the cache does not contain an object with the specified ID, writeFragment returns null.

fragment

DocumentNode

Required. A created with the gql template literal tag that includes the to write.

If the includes more than one , you must also provide fragmentName to indicate which to use.

data

Object

Required. The data to write to the cache. This object's must conform to the shape defined by fragment.

fragmentName

String

The name of the defined in the fragment to use in the call.

You don't need to provide this value if the fragment includes only one .

variables

Object

A map of any names and values required by fragment.

broadcast

Boolean

If true, automatically refresh all active queries that depend on at least one that's modified by this call. If false, silences the broadcast of cache updates and prevents automatic refresh.

The default value is true.

overwrite

Boolean

If true, ignore existing cache data when calling merge functions, allowing incoming data to replace existing data, without warnings about data loss.

The default value is false.

Signature

src/cache/core/cache.ts
writeFragment<TData = any, TVariables = any>(
options: Cache.WriteFragmentOptions<TData, TVariables>,
): Reference | undefined

Fetches data from the cache in the shape of a provided , then updates that cached data according to a provided update function.

Returns the updated result or null if the update failed.

// Fetches a Todo object with id 5 and sets its `completed` boolean to true
const todo = cache.updateFragment({ // options object
id: '5', // The value of the to-do item's unique identifier
fragment: gql`
fragment MyTodo on Todo {
completed
}
`,
}, (data) => ({ ...data, completed: true }) // update function
);

Takes an options object and an update function as parameters (both described below).

Options

Name /
Type
Description
id

String

Required. The ID of the cached object that this call is reading a of.

If the cache does not contain an object with the specified ID, updateFragment returns null.

fragment

DocumentNode

Required. A created with the gql template literal tag that includes the to read.

If the includes more than one , you must also provide fragmentName to indicate which to use.

fragmentName

String

The name of the defined in the fragment to use in the call.

You don't need to provide this value if the fragment includes only one .

variables

Object

A map of any names and values required by fragment.

broadcast

Boolean

If true, automatically refresh all active queries that depend on at least one that's modified by this call. If false, silences the broadcast of cache updates and prevents automatic refresh.

The default value is true.

overwrite

Boolean

If true, ignore existing cache data when calling merge functions, allowing incoming data to replace existing data, without warnings about data loss.

The default value is false.

updateFragment update function

The update function of updateFragment takes a 's current cached value and returns the value that should replace it (or undefined if no change should be made).

The returned value is automatically passed to writeFragment, which modifies the cached data.

Please note the update function has to calculate the new value in an immutable way. You can read more about immutable updates in the React documentation.

Signature

src/cache/core/cache.ts
public updateFragment<TData = any, TVariables = any>(
options: Cache.UpdateFragmentOptions<TData, TVariables>,
update: (data: TData | null) => TData | null | void,
): TData | null

identify

Returns the canonical ID for a specified cached object.

You can provide either an object or an object reference to this function:

  • If you provide an object, identify returns the object's string-based ID (e.g., Car:1).
  • If you provide a reference, identify return the reference's __ref ID string.

For usage instructions, see Interacting with cached data: Identify cached entities.

Accepts the following parameters:

Name /
Type
Description
object

StoreObject or Reference

Required. The cached object (or object reference) to obtain the canonical ID for.

Signature

src/cache/inmemory/inMemoryCache.ts
identify(object: StoreObject | Reference): string | undefined

modify

Modifies one or more values of a cached object. Must provide a modifier function for each to modify. A modifier function takes a cached field's current value and returns the value that should replace it.

Returns true if the cache was modified successfully and false otherwise.

For usage instructions, see Using cache.modify.

Takes an options object as a parameter. Supported of this object are described below.

Options

Name /
Type
Description
fields

Object

Required. A map that specifies the modifier function to call for each modified of the cached object.

See Modifier function API below.

id

string

The ID of the cached object to modify.

The default value is ROOT_QUERY (the ID of the root singleton object).

optimistic

Boolean

If true, also modifies the optimistically cached values for included .

The default value is false.

broadcast

Boolean

If true, automatically refresh all active queries that depend on at least one that's modified by this call. If false, silences the broadcast of cache updates and prevents automatic refresh.

The default value is true.

Modifier function API

A modifier function takes a cached 's current value and returns the value that should replace it, or the DELETE sentinel object to delete the entirely.

The first parameter passed to a modifier function is the current cached value of the being modified.

The second parameter is a helper object that contains the following utilities:

Name /
Type
Description
fieldName

String

The name of the being modified.

storeFieldName

String

The full key for the used internally, including serialized key .

readField

Function

A helper function for reading other on the object passed to the modifier function as the first parameter.

canRead

Function

A helper function that returns true for non-normalized StoreObjects and non-dangling References. This indicates that readField(name, objOrRef) has a chance of working.

Useful for filtering dangling references out of lists.

isReference

Function

A helper function that returns true if a particular object is a reference to a cached .

DELETE

Object

A sentinel object that you can return from a modifier function to indicate that the should be deleted entirely.

Signature

src/cache/inmemory/inMemoryCache.ts
modify(options: Cache.ModifyOptions): boolean

gc

Performs garbage collection of unreachable normalized objects in the cache:

cache.gc();

Returns an array containing the IDs of all objects removed from the cache.

For usage instructions, see cache.gc.

Signature

src/cache/inmemory/inMemoryCache.ts
gc()

evict

Either removes a normalized object from the cache or removes a specific from a normalized object in the cache:

cache.evict({ id: 'my-object-id', fieldName: 'myFieldName' });

Returns true if data was removed from the cache, false otherwise.

For usage instructions, see cache.evict.

Takes an options object as a parameter. Supported of this object are described below.

Options

Name /
Type
Description
id

String

The ID of the cached object to remove (or remove a from).

The default value is ROOT_QUERY, which is the ID of the root object.

fieldName

String

The name of the to remove from the cached object.

Omit this option if you are removing the entire object.

args

Record<string, any>

If provided with fieldName, only instances of the with the specified are removed from the cache.

Otherwise, all instances of the are removed for the cached object.

broadcast

Boolean

If true, automatically refresh all active queries that depend on at least one that's removed by this call. If false, silences the broadcast of cache updates and prevents automatic refresh.

The default value is true.

Signature

src/cache/inmemory/inMemoryCache.ts
evict(options: Cache.EvictOptions): boolean

extract

Returns a serialized representation of the cache's current contents as a NormalizedCacheObject.

Accepts the following parameters:

Name /
Type
Description
optimistic

Boolean

If true, optimistic data is included in the serialization.

The default value is false.

Signature

src/cache/inmemory/inMemoryCache.ts
extract(optimistic: boolean = false): NormalizedCacheObject

restore

Restores the cache's state from a serialized NormalizedCacheObject (such as one returned by extract). This removes all existing data from the cache.

Returns the InMemoryCache instance it's called on.

Accepts the following parameters:

Name /
Type
Description
data

NormalizedCacheObject

Required. The serialization to restore the cache from.

Signature

src/cache/inmemory/inMemoryCache.ts
restore(data: NormalizedCacheObject): this

makeVar

Creates a reactive with an optional initial value:

const cartItems = makeVar([]);

Returns the reactive function you use to read or modify the variable's value.

For usage instructions, see Reactive variables.

Accepts the following parameters:

Name /
Type
Description
value

Any

The reactive 's initial value.

Signature

src/cache/inmemory/inMemoryCache.ts
makeVar<T>(value: T): ReactiveVar<T>
Previous
ApolloClient
Next
ObservableQuery
Edit on GitHubEditForumsDiscord

© 2024 Apollo Graph Inc.

Privacy Policy

Company