urql Documentation

File: README.md Copy Chapter

✨ Features Copy Chapter

• 📦 One package to get a working GraphQL client in React, Preact, Vue, Solid and Svelte
• ⚙️ Fully customisable behaviour via "exchanges"
• 🗂 Logical but simple default behaviour and document caching
• 🌱 Normalized caching via @urql/exchange-graphcache
• 🔬 Easy debugging with the urql devtools browser extensions

urql is a GraphQL client that exposes a set of helpers for several frameworks. It's built to be highly customisable and versatile so
you can take it from getting started with your first GraphQL project all the way to building complex apps and experimenting with GraphQL clients.

📃 For more information, check out the docs.

💙 [Sponsors](https://github.com/sponsors/urql-graphql) Copy Chapter

🙌 Contributing Copy Chapter

The urql project was founded by Formidable and is actively developed
by the urql GraphQL team.

If you'd like to get involved, check out our Contributor's guide.

📦 [Releases](https://github.com/urql-graphql/urql/releases) Copy Chapter

All new releases and updates are listed on GitHub with full changelogs. Each package in this
repository further contains an independent CHANGELOG.md file with the historical changelog, for
instance, here’s @urql/core’s
changelog.

If you’re upgrading to v4, check out our migration guide, posted as an
issue.

New releases are prepared using
changesets,
which are changelog entries added to each PR, and we have “Version Packages” PRs that once merged
will release new versions of urql packages. You can use @canary releases from npm if you’d
like to get a preview of the merged changes.

📃 [Documentation](https://urql.dev/goto/docs) Copy Chapter

The documentation contains everything you need to know about urql, and contains several sections in order of importance
when you first get started:

• Basics — contains the "Getting Started" guide and all you need to know when first using urql.
• Architecture — explains how urql functions and is built.
• Advanced — covers more uncommon use-cases and things you don't immediately need when getting started.
• Graphcache — documents "Normalized Caching" support which enables more complex apps and use-cases.
• API — the API documentation for each individual package.

Furthermore, all APIs and packages are self-documented using TSDocs. If you’re using a language
server for TypeScript, the documentation for each API should pop up in your editor when hovering
urql’s code and APIs.

You can find the raw markdown files inside this repository's docs folder.

File: docs/api/auth-exchange.md Copy Chapter

title: '@urql/exchange-auth' order: 10 Copy Chapter

Authentication Exchange

Note: These API docs are deprecated as we now keep TSDocs in all published packages.
You can view TSDocs while using these packages in your editor, as long as it supports the
TypeScript Language Server.
We're planning to replace these API docs with a separate web app soon.

The @urql/exchange-auth package contains an addon authExchange for urql that aims to make it
easy to implement complex authentication and reauthentication flows as are typically found with JWT
token based API authentication.

Installation and Setup Copy Chapter

First install @urql/exchange-auth alongside urql:

yarn add @urql/exchange-auth
# or
npm install --save @urql/exchange-auth

You'll then need to add the authExchange, that this package exposes to your Client. The
authExchange is an asynchronous exchange, so it must be placed in front of all fetchExchanges
but after all other synchronous exchanges, like the cacheExchange.

import { createClient, cacheExchange, fetchExchange } from 'urql';
import { authExchange } from '@urql/exchange-auth';

const client = createClient({
  url: 'http://localhost:3000/graphql',
  exchanges: [
    cacheExchange,
    authExchange(async utils => {
      return {
        /* config... */
      };
    }),
    fetchExchange,
  ],
});

The authExchange accepts an initialization function. This function is called when your exchange
and Client first start up, and must return an object of options wrapped in a Promise, which is
used to configure how your authentication method works.

You can use this function to first retrieve your authentication state from a kind
of local storage, or to call your API to validate your authentication state first.

The relevant configuration options, returned to the authExchange, then determine
how the authExchange behaves:

• addAuthToOperation must be provided to tell authExchange how to add authentication information
  to an operation, e.g. how to add the authentication state to an operation's fetch headers.
• willAuthError may be provided to detect expired tokens or tell whether an operation will likely
  fail due to an authentication error.
• didAuthError may be provided to let the authExchange detect authentication errors from the
  API on results.
• refreshAuth is called when an authentication error occurs and gives you an opportunity to update
  your authentication state. Afterwards, the authExchange will retry your operation.

Read more examples in the documentation given here.

File: docs/api/core.md Copy Chapter

title: '@urql/core' order: 0 Copy Chapter

@urql/core

Note: These API docs are deprecated as we now keep TSDocs in all published packages.
You can view TSDocs while using these packages in your editor, as long as it supports the
TypeScript Language Server.
We're planning to replace these API docs with a separate web app soon.

The @urql/core package is the basis of all framework bindings. Each bindings-package,
like urql for React or @urql/preact, will reuse the core logic and
reexport all exports from @urql/core.
Therefore if you're not accessing utilities directly, aren't in a Node.js environment, and are using
framework bindings, you'll likely want to import from your framework bindings package directly.

Read more about urql's core on the "Core Package" page.

Client Copy Chapter

The Client manages all operations and ongoing requests to the exchange pipeline.
It accepts several options on creation.

@urql/core also exposes createClient() that is just a convenient alternative to calling new Client().

client.executeQuery Copy Section

Accepts a GraphQLRequest and optionally Partial<OperationContext>, and returns a
Source<OperationResult> — a stream of query results that can be subscribed to.

Internally, subscribing to the returned source will create an Operation, with
kind set to 'query', and dispatch it on the
exchanges pipeline. If no subscribers are listening to this operation anymore and unsubscribe from
the query sources, the Client will dispatch a "teardown" operation.

• Instead of using this method directly, you may want to use the client.query shortcut
  instead.
• See createRequest for a utility that creates GraphQLRequest objects.

client.executeSubscription Copy Section

This is functionally the same as client.executeQuery, but creates operations for subscriptions
instead, with kind set to 'subscription'.

client.executeMutation Copy Section

This is functionally the same as client.executeQuery, but creates operations for mutations
instead, with kind set to 'mutation'.

A mutation source is always guaranteed to only respond with a single OperationResult and then complete.

client.query Copy Section

This is a shorthand method for client.executeQuery, which accepts a query
(DocumentNode | string) and variables separately and creates a GraphQLRequest createRequest automatically.

The returned Source<OperationResult> will also have an added toPromise method, so the stream can
be conveniently converted to a promise.

import { pipe, subscribe } from 'wonka';

const { unsubscribe } = pipe(
  client.query('{ test }', {
    /* vars */
  }),
  subscribe(result => {
    console.log(result); // OperationResult
  })
);

// or with toPromise, which also limits this to one result
client
  .query('{ test }', {
    /* vars */
  })
  .toPromise()
  .then(result => {
    console.log(result); // OperationResult
  });

Read more about how to use this API on the "Core Package"
page.

client.mutation Copy Section

This is similar to client.query, but dispatches mutations instead.

Read more about how to use this API on the "Core Package"
page.

client.subscription Copy Section

This is similar to client.query, but does not provide a toPromise() helper method on the streams it returns.

Read more about how to use this API on the "Subscriptions" page.

client.reexecuteOperation Copy Section

This method is commonly used in Exchanges to reexecute an Operation on the
Client. It will only reexecute when there are still subscribers for the given
Operation.

For an example, this method is used by the cacheExchange when an
OperationResult is invalidated in the cache and needs to be refetched.

client.readQuery Copy Section

This method is typically used to read data synchronously from a cache. It returns an OperationResult if a value is returned immediately or null if no value is returned while cancelling all side effects.

CombinedError Copy Chapter

The CombinedError is used in urql to normalize network errors and GraphQLErrors if anything
goes wrong during a GraphQL request.

Read more about errors in urql on the "Error" page.

Types Copy Chapter

GraphQLRequest Copy Section

This often comes up as the input for every GraphQL request.
It consists of query and optionally variables.

The key property is a hash of both the query and the variables, to uniquely
identify the request. When variables are passed it is ensured that they're stably stringified so
that the same variables in a different order will result in the same key, since variables are
order-independent in GraphQL.

A GraphQLRequest may be manually created using the createRequest helper.

OperationType Copy Section

This determines what kind of operation the exchanges need to perform.
This is one of:

• 'subscription'
• 'query'
• 'mutation'
• 'teardown'

The 'teardown' operation is special in that it instructs exchanges to cancel
any ongoing operations with the same key as the 'teardown' operation that is
received.

Operation Copy Section

The input for every exchange that informs GraphQL requests.
It extends the GraphQLRequest type and contains these additional properties:

An Operation also contains the operationName property, which is a deprecated alias of the kind
property and outputs a deprecation warning if it's used.

RequestPolicy Copy Section

This determines the strategy that a cache exchange should use to fulfill an operation.
When you implement a custom cache exchange it's recommended that these policies are
handled.

• 'cache-first' (default)
• 'cache-only'
• 'network-only'
• 'cache-and-network'

Read more about request policies on the "Document Caching" page.

OperationContext Copy Section

The context often carries options or metadata for individual exchanges, but may also contain custom
data that can be passed from almost all API methods in urql that deal with
Operations.

Some of these options are set when the Client is initialised, so in the following list of
properties you'll likely see some options that exist on the Client as well.

It also accepts additional, untyped parameters that can be used to send more
information to custom exchanges.

OperationResult Copy Section

The result of every GraphQL request, i.e. an Operation. It's very similar to what comes back from
a typical GraphQL API, but slightly enriched and normalized.

ExchangeInput Copy Section

This is the input that an Exchange receives when it's initialized by the
Client

Exchange Copy Section

An exchange represents abstractions of small chunks of logic in urql.
They're small building blocks and similar to "middleware".

Read more about Exchanges on the "Authoring Exchanges" page.

An exchange is defined to be a function that receives ExchangeInput and returns
an ExchangeIO function. The ExchangeIO function in turn will receive a stream of operations, and
must return a stream of results. If the exchange is purely transforming data, like the
mapExchange for instance, it'll call forward, which is the next Exchange's ExchangeIO
function to get a stream of results.

type ExchangeIO = (Source<Operation>) => Source<OperationResult>;
type Exchange = ExchangeInput => ExchangeIO;

If you haven't yet seen streams you can read more about "Stream Patterns" on the "Architecture"
page.

Exchanges Copy Chapter

cacheExchange Copy Section

The cacheExchange as described on the "Document Caching" page.. It's of type Exchange.

subscriptionExchange Copy Section

The subscriptionExchange as described on the "Subscriptions" page.. It's of type Options => Exchange.

It accepts a single input: { forwardSubscription }. This is a function that
receives an enriched operation and must return an Observable-like object that
streams GraphQLResults with data and errors.

The forwardSubscription function is commonly connected to the subscriptions-transport-ws
package.

ssrExchange Copy Section

The ssrExchange as described on the "Server-side Rendering"
page..
It's of type Options => Exchange.

It accepts three inputs, initialState which is completely
optional and populates the server-side rendered data with
a rehydrated cache, isClient which can be set to
true or false to tell the ssrExchange whether to
write to (server-side) or read from (client-side) the cache, and
staleWhileRevalidate which will treat rehydrated data as stale
and refetch up-to-date data by reexecuring the operation using a network-only requests policy.

By default, isClient defaults to true when the Client.suspense
mode is disabled and to false when the Client.suspense mode
is enabled.

This can be used to extract data that has been queried on
the server-side, which is also described in the Basics section,
and is also used on the client-side to restore server-side
rendered data.

When called, this function creates an Exchange, which also has
two methods on it:

• .restoreData(data) which can be used to inject data, typically
  on the client-side.
• .extractData() which is typically used on the server-side to
  extract the server-side rendered data.

Basically, the ssrExchange is a small cache that collects data
during the server-side rendering pass, and allows you to populate
the cache on the client-side with the same data.

During React rehydration this cache will be emptied, and it will
become inactive and won't change the results of queries after
rehydration.

It needs to be used after other caching Exchanges like the
cacheExchange, but before any asynchronous Exchange like
the fetchExchange.

debugExchange Copy Section

An exchange that writes incoming Operations to console.log and
writes completed OperationResults to console.log.

This exchange is disabled in production and is based on the mapExchange.
If you'd like to customise it, you can replace it with a custom mapExchange.

fetchExchange Copy Section

The fetchExchange of type Exchange is responsible for sending operations of type 'query' and
'mutation' to a GraphQL API using fetch.

mapExchange Copy Section

The mapExchange allows you to:

• react to or replace operations with onOperation,
• react to or replace results with onResult,
• and; react to errors in results with onError.

It can therefore be used to quickly react to the core events in the Client without writing a custom
exchange, effectively allowing you to ship your own debugExchange.

mapExchange({
  onOperation(operation) {
    console.log('operation', operation);
  },
  onResult(result) {
    console.log('result', result);
  },
});

It can also be used to react only to errors, which is the same as checking for result.error:

mapExchange({
  onError(error, operation) {
    console.log(`The operation ${operation.key} has errored with:`, error);
  },
});

Lastly, it can be used to map operations and results, which may be useful to update the
OperationContext or perform other standard tasks that require you to wait for a result:

import { mapExchange, makeOperation } from '@urql/core';

mapExchange({
  async onOperation(operation) {
    // NOTE: This is only for illustration purposes
    return makeOperation(operation.kind, operation, {
      ...operation.context,
      test: true,
    });
  },
  async onResult(result) {
    // NOTE: This is only for illustration purposes
    if (result.data === undefined) result.data = null;
    return result;
  },
});

errorExchange (deprecated) Copy Section

An exchange that lets you inspect errors. This can be useful for logging, or reacting to
different types of errors (e.g. logging the user out in case of a permission error).

In newer versions of @urql/core, it's identical to the mapExchange and its export has been
replaced as the mapExchange also allows you to pass an onError function.

Utilities Copy Chapter

gql Copy Section

This is a gql tagged template literal function, similar to the one that's also commonly known from
graphql-tag. It can be used to write GraphQL documents in a tagged template literal and returns a
parsed DocumentNode that's primed against the createRequest's cache for keys.

import { gql } from '@urql/core';

const SharedFragment = gql`
  fragment UserFrag on User {
    id
    name
  }
`;

gql`
  query {
    user
    ...UserFrag
  }

  ${SharedFragment}
`;

Unlike graphql-tag, this function outputs a warning in development when names of fragments in the
document are duplicated. It does not output warnings when fragment names were duplicated globally
however.

stringifyVariables Copy Section

This function is a variation of JSON.stringify that sorts any object's keys that is being
stringified to ensure that two objects with a different order of keys will be stably stringified to
the same string.

stringifyVariables({ a: 1, b: 2 }); // {"a":1,"b":2}
stringifyVariables({ b: 2, a: 1 }); // {"a":1,"b":2}

createRequest Copy Section

This utility accepts a GraphQL query of type string | DocumentNode and optionally an object of
variables, and returns a GraphQLRequest object.

Since the client.executeQuery and other execute methods only accept
GraphQLRequests, this helper is commonly used to create that request first. The
client.query and client.mutation methods use this helper as
well to create requests.

The helper takes care of creating a unique key for the GraphQLRequest. This is a hash of the
query and variables if they're passed. The variables will be stringified using
stringifyVariables, which outputs a stable JSON string.

Additionally, this utility will ensure that the query reference will remain stable. This means
that if the same query will be passed in as a string or as a fresh DocumentNode, then the output
will always have the same DocumentNode reference.

makeOperation Copy Section

This utility is used to either turn a GraphQLRequest object into a new
Operation object or to copy an Operation. It adds the kind property, and the
operationName alias that outputs a deprecation warning.

It accepts three arguments:

• An Operation's kind (See OperationType
• A GraphQLRequest object or another Operation that should be
  copied.
• and; optionally a partial OperationContext object.. This argument may be
  left out if the context is to be copied from the operation that may be passed as a second argument.

Hence some valid uses of the utility are:

// Create a new operation from scratch
makeOperation('query', createRequest(query, variables), client.createOperationContext(opts));

// Turn an operation into a 'teardown' operation
makeOperation('teardown', operation);

// Copy an existing operation while modifying its context
makeOperation(operation.kind, operation, {
  ...operation.context,
  preferGetMethod: true,
});

makeResult Copy Section

This is a helper function that converts a GraphQL API result to an
OperationResult.

It accepts an Operation, the API result, and optionally the original FetchResponse
for debugging as arguments, in that order.

makeErrorResult Copy Section

This is a helper function that creates an OperationResult for GraphQL API
requests that failed with a generic or network error.

It accepts an Operation, the error, and optionally the original FetchResponse
for debugging as arguments, in that order.

formatDocument Copy Section

This utility is used by the cacheExchange and by
Graphcache to add __typename fields to GraphQL DocumentNodes.

composeExchanges Copy Section

This utility accepts an array of Exchanges and composes them into a single one.
It chains them in the order that they're given, left to right.

function composeExchanges(Exchange[]): Exchange;

This can be used to combine some exchanges and is also used by Client
to handle the exchanges input.

File: docs/api/execute-exchange.md Copy Chapter

title: '@urql/exchange-execute' order: 6 Copy Chapter

Execute Exchange

Note: These API docs are deprecated as we now keep TSDocs in all published packages.
You can view TSDocs while using these packages in your editor, as long as it supports the
TypeScript Language Server.
We're planning to replace these API docs with a separate web app soon.

The @urql/exchange-execute package contains an addon executeExchange for urql that may be used to
execute queries against a local schema. It is therefore a drop-in replacement for the default
fetchExchange and useful for the server-side, debugging, or testing.

Installation and Setup Copy Chapter

First install @urql/exchange-execute alongside urql:

yarn add @urql/exchange-execute
# or
npm install --save @urql/exchange-execute

You'll then need to add the executeExchange, exposed by this package, to your Client.
It'll typically replace the fetchExchange or similar exchanges and must be used last if possible,
since it'll handle operations and return results.

import { createClient, cacheExchange } from 'urql';
import { executeExchange } from '@urql/exchange-execute';

const client = createClient({
  url: 'http://localhost:3000/graphql',
  exchanges: [
    cacheExchange,
    executeExchange({
      /* config */
    }),
  ],
});

The executeExchange accepts an object of options, which are all similar to the arguments that
graphql/execution/execute accepts. Typically you'd pass it the schema option, some resolvers
if your schema isn't already executable as fieldResolver / typeResolver / rootValue,
and a context value or function.

Options Copy Chapter

File: docs/api/graphcache.md Copy Chapter

title: '@urql/exchange-graphcache' order: 4 Copy Chapter

@urql/exchange-graphcache

Note: These API docs are deprecated as we now keep TSDocs in all published packages.
You can view TSDocs while using these packages in your editor, as long as it supports the
TypeScript Language Server.
We're planning to replace these API docs with a separate web app soon.

The @urql/exchange-graphcache package contains an addon cacheExchange for urql that may be
used to replace the default cacheExchange, which switches urql from
using "Document Caching" to "Normalized
Caching".

Read more about how to use and configure Graphcache in the "Graphcache"
section

cacheExchange Copy Chapter

The cacheExchange function, as exported by @urql/exchange-graphcache, accepts a single object of
options and returns an Exchange.

The @urql/exchange-graphcache package also exports the offlineExchange; which is identical to
the cacheExchange but activates offline support when the storage option is passed.

`keys` option Copy Section

This is a mapping of typenames to KeyGenerator functions.

interface KeyingConfig {
  [typename: string]: (data: Data) => null | string;
}

It may be used to alter how Graphcache generates the key it uses for normalization for individual
types. The key generator function may also always return null when a type should always be
embedded.

Read more about how to set up keys in the "Key Generation" section of the "Normalized Caching"
page.

`resolvers` option Copy Section

This configuration is a mapping of typenames to field names to Resolver functions.
A resolver may be defined to override the entity or record that a given field on a type should
resolve on the cache.

interface ResolverConfig {
  [typeName: string]: {
    [fieldName: string]: Resolver;
  };
}

A Resolver receives four arguments when it's called: parent, args, cache, and
info.

We can use the arguments it receives to either return new data based on just the arguments and other
cache information, but we may also read information about the parent and return new data for the
current field.

{
  Todo: {
    createdAt(parent, args, cache) {
      // Read `createdAt` on the parent but return a Date instance
      const date = cache.resolve(parent, 'createdAt');
      return new Date(date);
    }
  }
}

Read more about how to set up resolvers on the "Computed Queries"
page.

`updates` option Copy Section

The updates configuration is a mapping of 'Mutation' | 'Subscription' to field names to
UpdateResolver functions. An update resolver may be defined to add side-effects that run when a
given mutation field or subscription field is written to the cache. These side-effects are helpful
to update data in the cache that is implicitly changed on the GraphQL API, that Graphcache can't
know about automatically.

For mutation fields that don't have an updater, Graphcache has a fallback: if a returned entity
isn't currently found in the cache, it assumes a create-mutation and invalidates cached
entities of that type. This behavior was introduced in Graphcache v7 and is skipped once an updater
for the mutation field is added.

interface UpdatesConfig {
  Mutation: {
    [fieldName: string]: UpdateResolver;
  };
  Subscription: {
    [fieldName: string]: UpdateResolver;
  };
}

An UpdateResolver receives four arguments when it's called: result, args, cache, and
info.

It's possible to derive more information about the current update using the info argument. For
instance this metadata contains the current fieldName of the updater which may be used to make an
updater function more reusable, along with parentKey and other key fields. It also contains
variables and fragments which remain the same for the entire write operation, and additionally
it may have the error field set to describe whether the current field is null because the API
encountered a GraphQLError.

Read more about how to set up updates on the "Custom Updates"
page.

`optimistic` option Copy Section

The optimistic configuration is a mapping of Mutation field names to OptimisticMutationResolver
functions, which return optimistic mutation results for given fields. These results are used by
Graphcache to optimistically update the cache data, which provides an immediate and temporary
change to its data before a mutation completes.

interface OptimisticMutationConfig {
  [mutationFieldName: string]: OptimisticMutationResolver;
}

A OptimisticMutationResolver receives three arguments when it's called: variables, cache, and
info.

Read more about how to set up optimistic on the "Custom Updates"
page.

`schema` option Copy Section

The schema option may be used to pass a IntrospectionQuery data to Graphcache, in other words
it's used to provide schema information to it. This schema is then used to resolve and return
partial results when querying, which are results that the cache can partially resolve as long as no
required fields are missing.

Read more about how to use the schema option on the "Schema Awareness"
page.

`storage` option Copy Section

The storage option is an interface of methods that are used by the offlineExchange to persist
the cache's data to persisted storage on the user's device. it

NOTE: Offline Support is currently experimental! It hasn't been extensively tested yet and
may not always behave as expected. Please try it out with caution!

These options are split into three parts:

• The writeMetadata and readMetadata methods are used to persist in-progress optimistic
  mutations to a storage so that they may be retried if the app has been closed while some
  optimistic mutations were still in progress.
• The writeData and readData methods are used to persist any cache data. This is the normalized
  data that Graphcache usually keeps in memory. The cacheExchange will frequently call
  writeData with a partial object of its cache data, which readData must then be able to return
  in a single combined object on startup. We call the partial objects that writeData is called
  with "deltas".
• The onOnline method is only used to receive a trigger that determines whether the user's device
  has come back online, which is used to retry optimistic mutations that have previously failed due
  to being offline.

The storage option may also be used with the cacheExchange instead of the offlineExchange, but
will then only use readData and writeData to persist its cache data. This is not full offline
support, but will rather be "persistence support".

Read more about how to use the storage option on the "Offline Support"
page.

Cache Copy Chapter

An instance of the Cache interface is passed to every resolvers and updater function. It may be
used to read cached data or write cached data, which may be used in combination with the
cacheExchange configuration to alter the default behaviour of Graphcache.

keyOfEntity Copy Section

The cache.keyOfEntity method may be called with a partial Data object and will return the key
for that object, or null if it's not keyable.

An object may not be keyable if it's missing the __typename or id (which falls back to _id)
fields. This method does take the keys configuration into account.

cache.keyOfEntity({ __typename: 'Todo', id: 1 }); // 'Todo:1'
cache.keyOfEntity({ __typename: 'Query' }); // 'Query'
cache.keyOfEntity({ __typename: 'Unknown' }); // null

There's an alternative method, cache.keyOfField which generates a key for a given field. This is
only rarely needed but similar to cache.keyOfEntity. This method accepts a field name and
optionally a field's arguments.

cache.keyOfField('todo'); // 'todo'
cache.keyOfField('todo', { id: 1 }); // 'todo({"id":1})'

Internally, these are the keys that records and links are stored on per entity.

resolve Copy Section

This method retrieves a value or link for a given field, given a partially keyable Data object or
entity, a field name, and optionally the field's arguments. Internally this method accesses the
cache by using cache.keyOfEntity and cache.keyOfField.

// This may resolve a link:
cache.resolve({ __typename: 'Query' }, 'todo', { id: 1 }); // 'Todo:1'

// This may also resolve records / scalar values:
cache.resolve({ __typename: 'Todo', id: 1 }, 'id'); // 1

// You can also chain multiple calls to `cache.resolve`!
cache.resolve(cache.resolve({ __typename: 'Query' }, 'todo', { id: 1 }), 'id'); // 1

As you can see in the last example of this code snippet, the Data object can also be replaced by
an entity key, which makes it possible to pass a key from cache.keyOfEntity or another call to
cache.resolve instead of the partial entity.

Note: Because cache.resolve may return either a scalar value or another entity key, it may
be dangerous to use in some cases. It's a good idea to make sure first whether the field you're
reading will be a key or a value.

The cache.resolve method may also be called with a field key as generated by cache.keyOfField.

cache.resolve({ __typename: 'Query' }, cache.keyOfField('todo', { id: 1 })); // 'Todo:1'

This specialized case is likely only going to be useful in combination with
cache.inspectFields.

inspectFields Copy Section

The cache.inspectFields method may be used to interrogate the cache about all available fields on
a specific entity. It accepts a partial entity or an entity key, like cache.resolve's
first argument.

When calling the method this returns an array of FieldInfo objects, one per field (including
differing arguments) that is known to the cache. The FieldInfo interface has three properties:
fieldKey, fieldName, and arguments:

This works on any given entity. When calling this method the cache works in reverse on its data
structure, by parsing the entity's individual field keys.
p

cache.inspectFields({ __typename: 'Query' });

/*
  [
    { fieldName: 'todo', arguments: { id: 1 }, fieldKey: 'id({"id":1})' },
    { fieldName: 'todo', arguments: { id: 2 }, fieldKey: 'id({"id":2})' },
    ...
  ]
*/

readFragment Copy Section

cache.readFragment accepts a GraphQL DocumentNode as the first argument and a partial entity or
an entity key as the second, like cache.resolve's first argument.

The method will then attempt to read the entity according to the fragment entirely from the cached
data. If any data is uncached and missing it'll return null.

import { gql } from '@urql/core';

cache.readFragment(
  gql`
    fragment _ on Todo {
      id
      text
    }
  `,
  { id: 1 }
); // Data or null

Note that the __typename may be left out on the partial entity if the fragment isn't on an
interface or union type, since in that case the __typename is already present on the fragment
itself.

If any fields on the fragment require variables, you can pass them as the third argument like so:

import { gql } from '@urql/core';

cache.readFragment(
  gql`
    fragment _ on User {
      id
      permissions(byGroupId: $groupId)
    }
  `,
  { id: 1 }, // this identifies the fragment (User) entity
  { groupId: 5 } // any additional field variables
);

If you need a specific fragment in a document containing multiple you can leverage
the fourth argument like this:

import { gql } from '@urql/core';

cache.readFragment(
  gql`
    fragment todoFields on Todo {
      id
    }

    fragment userFields on User {
      id
    }
  `,
  { id: 1 }, // this identifies the fragment (User) entity
  undefined,
  'userFields' // if not passed we take the first fragment, in this case todoFields
);

[Read more about using readFragment on the "Local Resolvers"
page.

readQuery Copy Section

The cache.readQuery method is similar to cache.readFragment, but instead of reading a fragment
from cache, it reads an entire query. The only difference between how these two methods are used is
cache.readQuery's input, which is an object instead of two arguments.

The method accepts a { query, variables } object as the first argument, where query may either
be a DocumentNode or a string and variables may optionally be an object.

cache.readQuery({
  query: `
    query ($id: ID!) {
      todo(id: $id) { id, text }
    }
  `,
  variables: {
    id: 1
  }
); // Data or null

[Read more about using readQuery on the "Local Resolvers"
page.

link Copy Section

Corresponding to cache.resolve, the cache.link method allows
links in the cache to be updated. While the cache.resolve method reads both
records and links from the cache, the cache.link method will only ever write
links as fragments (See cache.writeFragment below) are more
suitable for updating scalar data in the cache.

The arguments for cache.link are identical to cache.resolve and
the field's arguments are optional. However, the last argument must always be
a link, meaning null, an entity key, a keyable entity, or a list of these.

In other words, cache.link accepts an entity to write to as its first argument,
with the same arguments as cache.keyOfEntity. It then accepts one or two arguments
that are passed to cache.keyOfField to get the targeted field key. And lastly,
you may pass a list or a single entity (or an entity key).

// Link Query.todo field to a todo item
cache.link({ __typename: 'Query' }, 'todo', { __typename: 'Todo', id: 1 });

// You may also pass arguments instead:
cache.link({ __typename: 'Query' }, 'todo', { id: 1 }, { __typename: 'Todo', id: 1 });

// Or use entity keys instead of the entities themselves:
cache.link('Query', 'todo', cache.keyOfEntity({ __typename: 'Todo', id: 1 }));

The method may output a
warning when any of the
entities were passed as objects but aren't keyable, which is useful when a scalar or a non-keyable
object have been passed to cache.link accidentally.

writeFragment Copy Section

Corresponding to cache.readFragment, the cache.writeFragment method allows
data in the cache to be updated.

The arguments for cache.writeFragment are identical to cache.readFragment,
however the second argument, data, should not only contain properties that are necessary to derive
an entity key from the given data, but also the fields that will be written:

import { gql } from '@urql/core';

cache.writeFragment(
  gql`
    fragment _ on Todo {
      text
    }
  `,
  { id: 1, text: 'New Todo Text' }
);

In the example we can see that the writeFragment method returns undefined. Furthermore we pass
id in our data object so that an entity key can be written, but the fragment itself doesn't have
to include these fields.

If you need a specific fragment in a document containing multiple you can leverage
the fourth argument like this:

import { gql } from '@urql/core';

cache.writeFragment(
  gql`
    fragment todoFields on Todo {
      id
      text
    }

    fragment userFields on User {
      id
      name
    }
  `,
  { id: 1, name: 'New Name' }
  undefined,
  'userFields' // if not passed we take the first fragment, in this case todoFields
);

[Read more about using writeFragment on the "Custom Updates"
page.

updateQuery Copy Section

Similarly to cache.writeFragment, there's an analogous method for
cache.readQuery that may be used to update query data.

The cache.updateQuery method accepts the same { query, variables } object input as its first
argument, which is the query we'd like to write to the cache. As a second argument the method
accepts an updater function. This function will be called with the query data that is already in the
cache (which may be null if the data is uncached) and must return the new data that should be
written to the cache.

const TodoQuery = `
  query ($id: ID!) {
    todo(id: $id) { id, text }
  }
`;

cache.updateQuery({ query: TodoQuery, variables: { id: 1 } }, data => {
  if (!data) return null;
  data.todo.text = 'New Todo Text';
  return data;
});

As we can see, our updater may return null to cancel updating any data, which we do in case the
query data is uncached.

We can also see that data can simply be mutated and doesn't have to be altered immutably. This is
because all data from the cache is already a deep copy and hence we can do to it whatever we want.

Read more about using updateQuery on the "Custom Updates"
page.

invalidate Copy Section

The cache.invalidate method can be used to delete (i.e. "evict") an entity from the cache
entirely. This will cause it to disappear from all queries in Graphcache.

Its arguments are identical to cache.resolve.

Since deleting an entity will lead to some queries containing missing and uncached data, calling
invalidate may lead to additional GraphQL requests being sent, unless you're using Graphcache's
"Schema Awareness" feature, which takes optional fields into
account.

This method accepts a partial entity or an entity key as its first argument, similar to
cache.resolve's first argument.

cache.invalidate({ __typename: 'Todo', id: 1 }); // Invalidates Todo:1

Additionally cache.invalidate may be used to delete specific fields only, which can be useful when
for instance a list is supposed to be evicted from cache, where a full invalidation may be
impossible. This is often the case when a field on the root Query needs to be deleted.

This method therefore accepts two additional arguments, similar to cache.resolve.

// Invalidates `Query.todos` with the `first: 10` argument:
cache.invalidate('Query', 'todos', { first: 10 });

Info Copy Chapter

This is a metadata object that is passed to every resolver and updater function. It contains basic
information about the current GraphQL document and query, and also some information on the current
field that a given resolver or updater is called on.

Note: Using info is regarded as a last resort. Please only use information from it if
there's no other solution to get to the metadata you need. We don't regard the Info API as
stable and may change it with a simple minor version bump.

The `/extras` import Copy Chapter

The extras subpackage is published with Graphcache and contains helpers and utilities that don't
have to be included in every app or aren't needed by all users of Graphcache.
All utilities from extras may be imported from @urql/exchange-graphcache/extras.

Currently the extras subpackage only contains the pagination resolvers that have been mentioned
on the "Computed Queries" page.

simplePagination Copy Section

Accepts a single object of optional options and returns a resolver that can be inserted into the
cacheExchange's resolvers configuration.

Once set up, the resulting resolver is able to automatically concatenate all pages of a given field
automatically. Queries to this resolvers will from then on only return the infinite, combined list
of all pages.

Read more about simplePagination on the "Computed Queries"
page.

relayPagination Copy Section

Accepts a single object of optional options and returns a resolver that can be inserted into the
cacheExchange's resolvers configuration.

Once set up, the resulting resolver is able to automatically concatenate all pages of a given field
automatically. Queries to this resolvers will from then on only return the infinite, combined list
of all pages.

Read more about relayPagnation on the "Computed Queries"
page.

The `/default-storage` import Copy Chapter

The default-storage subpackage is published with Graphcache and contains a default storage
interface that may be used with the storage option.

It contains the makeDefaultStorage export which is a factory function that accepts a few options
and returns a full storage interface. This storage by default persists to
IndexedDB.

File: docs/api/preact.md Copy Chapter

title: '@urql/preact' order: 2 Copy Chapter

@urql/preact

Note: These API docs are deprecated as we now keep TSDocs in all published packages.
You can view TSDocs while using these packages in your editor, as long as it supports the
TypeScript Language Server.
We're planning to replace these API docs with a separate web app soon.

The @urql/preact API is the same as the React urql API.
Please refer to the "urql" API docs for details on the Preact API.

File: docs/api/README.md Copy Chapter

title: API order: 9 Copy Chapter

API

urql is a collection of multiple packages. You'll likely be using one of the framework bindings
package or exchange packages, which are all listed in this section.

Most of these packages will refer to or use utilities and types from the @urql/core package. Read
more about the core package on the "Core" page.

Note: These API docs are deprecated as we now keep TSDocs in all published packages.
You can view TSDocs while using these packages in your editor, as long as it supports the
TypeScript Language Server.
We're planning to replace these API docs with a separate web app soon.

• @urql/core API docs
• urql React API docs
• @urql/preact Preact API docs
• @urql/svelte Svelte API docs
• @urql/exchange-graphcache API docs
• @urql/exchange-retry API docs
• @urql/exchange-execute API docs
• @urql/exchange-request-policy API docs
• @urql/exchange-auth API docs
• @urql/exchange-refocus API docs

File: docs/api/refocus-exchange.md Copy Chapter

title: '@urql/exchange-refocus' order: 11 Copy Chapter

Refocus Exchange

Note: These API docs are deprecated as we now keep TSDocs in all published packages.
You can view TSDocs while using these packages in your editor, as long as it supports the
TypeScript Language Server.
We're planning to replace these API docs with a separate web app soon.

@urql/exchange-refocus is an exchange for the urql that tracks currently active operations and redispatches them when the
window regains focus

Quick Start Guide Copy Chapter

First install @urql/exchange-refocus alongside urql:

yarn add @urql/exchange-refocus
# or
npm install --save @urql/exchange-refocus

Then add it to your Client, preferably in front of your cacheExchange

import { createClient, cacheExchange, fetchExchange } from 'urql';
import { refocusExchange } from '@urql/exchange-refocus';

const client = createClient({
  url: 'http://localhost:3000/graphql',
  exchanges: [refocusExchange(), cacheExchange, fetchExchange],
});

File: docs/api/request-policy-exchange.md Copy Chapter

title: '@urql/exchange-request-policy' order: 9 Copy Chapter

Request Policy Exchange

Note: These API docs are deprecated as we now keep TSDocs in all published packages.
You can view TSDocs while using these packages in your editor, as long as it supports the
TypeScript Language Server.
We're planning to replace these API docs with a separate web app soon.

The @urql/exchange-request-policy package contains an addon requestPolicyExchange for urql
that may be used to upgrade Operations' Request Policies on a
time-to-live basis.

Read more about request policies on the "Document Caching" page.

This exchange will conditionally upgrade cache-first and cache-only operations to use
cache-and-network, so that the client gets an opportunity to update its cached data, when the
operation hasn't been seen within the given ttl time. This is often preferable to setting the
default policy to cache-and-network to avoid an unnecessarily high amount of requests to be sent
to the API when switching pages.

Installation and Setup Copy Chapter

First install @urql/exchange-request-policy alongside urql:

yarn add @urql/exchange-request-policy
# or
npm install --save @urql/exchange-request-policy

Then add it to your Client, preferably in front of the cacheExchange and in front of any asynchronous
exchanges, like the fetchExchange:

import { createClient, cacheExchange, fetchExchange } from 'urql';
import { requestPolicyExchange } from '@urql/exchange-request-policy';

const client = createClient({
  url: 'http://localhost:3000/graphql',
  exchanges: [
    requestPolicyExchange({
      /* config */
    }),
    cacheExchange,
    fetchExchange,
  ],
});

Options Copy Chapter

File: docs/api/retry-exchange.md Copy Chapter

title: '@urql/exchange-retry' order: 5 Copy Chapter

Retry Exchange

Note: These API docs are deprecated as we now keep TSDocs in all published packages.
You can view TSDocs while using these packages in your editor, as long as it supports the
TypeScript Language Server.
We're planning to replace these API docs with a separate web app soon.

The @urql/exchange-retry package contains an addon retryExchange for urql that may be used to
let failed operations be retried, typically when a previous operation has failed with a network
error.

Read more about how to use and configure the retryExchange on the "Retry Operations"
page.

Options Copy Chapter