Internal operations$Exposes the stream of Operations that is passed to the Exchange pipeline.
This is a Wonka Source that issues the Operations going into the exchange pipeline.
Internal suspenseFlag indicating whether support for “Suspense” is activated.
This flag indicates whether support for “Suspense” has been activated via the suspense flag.
When this is enabled, the Client itself doesn’t function any differently, and the flag only serves as an instructions for the React/Preact bindings to change their behaviour.
suspense for more information.
Creates an Operation from a GraphQLRequest and optionally, overriding OperationContext options.
This method is expected to be called with a kind set to the OperationType of the GraphQL operation.
In development, this is enforced by checking that the GraphQL document's operation matches this kind.
Hint: While bindings will use this method combined with executeRequestOperation, if you’re executing operations manually, you can use one of the other convenience methods instead.
GraphQLRequest from a DocumentNode and variables.The OperationType of GraphQL operation, i.e. query, mutation, or subscription.
A GraphQLRequest created prior to calling this method.
Optional opts: Partial<OperationContext>OperationContext options that'll override and be merged with options from the ClientOptions.
An Operation created from the parameters.
Creates a Source that executes the GraphQL mutation operation for the passed GraphQLRequest.
The Client.executeMutation method is used to programmatically issue a GraphQL mutation operation.
It automatically calls client.createRequestOperation and client.executeRequestOperation for you,
but requires you to create a GraphQLRequest using createRequest yourself first.
mutation for a method that doesn't require calling createRequest yourself.
Optional opts: Partial<OperationContext>OperationContext options that'll override and be merged with options from the ClientOptions.
A PromisifiedSource issuing the OperationResults for the GraphQL operation.
Creates a Source that executes the GraphQL query operation for the passed GraphQLRequest.
The Client.executeQuery method is used to programmatically issue a GraphQL query operation.
It automatically calls client.createRequestOperation and client.executeRequestOperation for you,
but requires you to create a GraphQLRequest using createRequest yourself first.
query for a method that doesn't require calling createRequest yourself.
Optional opts: Partial<OperationContext>OperationContext options that'll override and be merged with options from the ClientOptions.
A PromisifiedSource issuing the OperationResults for the GraphQL operation.
Creates a Source that executes the Operation and issues OperationResults for this Operation.
The Operation will be dispatched to the pipeline of Exchanges when
subscribing to the returned Source, which issues OperationResults
belonging to this Operation.
Internally, OperationResults are filtered and deliverd to this source by
comparing the key on the operation and the operation.
For mutations, the OperationContext._instance will additionally be compared, since two mutations
with, even given the same variables, will have two distinct results and will be executed separately.
The Client dispatches the Operation when we subscribe to the returned Source
and will from then on consider the Operation as “active” until we unsubscribe. When all consumers unsubscribe
from an Operation and it becomes “inactive” a teardown signal will be dispatched to the
Exchanges.
Hint: While bindings will use this method, if you’re executing operations manually, you can use one of the other convenience methods instead, like executeQuery et al.
A Wonka Source of OperationResults for the passed Operation.
Creates a Source that executes the GraphQL subscription operation for the passed GraphQLRequest.
The Client.executeSubscription method is used to programmatically issue a GraphQL subscription operation.
It automatically calls client.createRequestOperation and client.executeRequestOperation for you,
but requires you to create a GraphQLRequest using createRequest yourself first.
subscription for a method that doesn't require calling createRequest yourself.
Optional opts: Partial<OperationContext>OperationContext options that'll override and be merged with options from the ClientOptions.
A PromisifiedSource issuing the OperationResults for the GraphQL operation.
Creates a Source that executes the GraphQL mutation operation created from the passed parameters.
The Client.mutation method is useful to programmatically create and issue a GraphQL mutation operation.
It automatically calls createRequest, client.createRequestOperation, and
client.executeRequestOperation for you, and is a convenience method.
Since it returns a PromisifiedSource it may be chained with a toPromise() call to only
await a single result in an async function. Since mutations will only typically issue one result,
using this method is recommended.
Hint: This is the recommended way to create mutations programmatically when not using the bindings, or when you’re trying to get a single, promisified result.
const createPostMutation = gql`
mutation CreatePost($text: String!) {
createPost(text: $text) {
id
text
}
}
`;
async function createPost(text) {
const result = await client.mutation(createPostMutation, {
text,
}).toPromise();
if (result.error) {
throw result.error;
}
return result.data.createPost;
}
a GraphQL document containing the mutation operation that will be executed.
the variables used to execute the operation.
Optional context: Partial<OperationContext>A PromisifiedSource issuing the OperationResults for the GraphQL operation.
Creates a Source that executes the GraphQL query operation created from the passed parameters.
The Client.query method is useful to programmatically create and issue a GraphQL query operation.
It automatically calls createRequest, client.createRequestOperation, and
client.executeRequestOperation for you, and is a convenience method.
Since it returns a OperationResultSource it may be chained with a toPromise() call to only
await a single result in an async function.
Hint: This is the recommended way to create queries programmatically when not using the bindings, or when you’re trying to get a single, promisified result.
const getBookQuery = gql`
query GetBook($id: ID!) {
book(id: $id) {
id
name
author {
name
}
}
}
`;
async function getBook(id) {
const result = await client.query(getBookQuery, { id }).toPromise();
if (result.error) {
throw result.error;
}
return result.data.book;
}
a GraphQL document containing the query operation that will be executed.
the variables used to execute the operation.
Optional context: Partial<OperationContext>A OperationResultSource issuing the OperationResults for the GraphQL operation.
Returns the first synchronous result a Client provides for a given operation.
The Client.readQuery method returns a result synchronously or defaults to null. This is useful
as it limits the result for a query operation to whatever the cache Exchange of a Client
had stored and available at that moment.
In urql, it's expected that cache exchanges return their results synchronously. The bindings
and this method exploit this by using synchronous results, like these, to check what data is already
in the cache.
This method is similar to what all bindings do to synchronously provide the initial state for queries, regardless of whether effects afterwards that subscribe to the query operation update this state synchronously or asynchronously.
a GraphQL document containing the query operation that will be executed.
the variables used to execute the operation.
Optional context: Partial<OperationContext>An OperationResult if one became available synchronously or null.
Dispatches an Operation to the Exchange pipeline, if this Operation is active.
This method is frequently used in Exchanges, for instance caches, to reexecute
an operation. It’s often either called because an Operation will need to be queried against the
cache again, if a cache result has changed or been invalidated, or it’s called with an Operation's
RequestPolicy set to network-only to issue a network request.
This method will only dispatch an Operation if it has active consumers, meaning,
active subscribers to the sources of OperationResult. For instance, if no bindings
(e.g. useQuery) is subscribed to the Operation, then reexecuteOperation will do nothing.
All operations are put onto a queue and executed after a micro-tick. The queue of operations is emptied eagerly and synchronously, similar to a trampoline scheduler.
Optional subscribeInternal
Subscribe method to add an event listener to debug events.
This is a method that's only available in development, and allows the urql-devtools to receive
to debug events that are issued by exchanges, giving the devtools more information about the flow
and execution of Operations.
DebugEventTypes for a description of all debug events.
A callback called with new debug events, each time an Exchange issues them.
A Wonka Subscription which is used to optionally terminate the event listener.
Creates a Source that executes the GraphQL subscription operation created from the passed parameters.
The Client.subscription method is useful to programmatically create and issue a GraphQL subscription operation.
It automatically calls createRequest, client.createRequestOperation, and
client.executeRequestOperation for you, and is a convenience method.
Hint: This is the recommended way to create subscriptions programmatically when not using the bindings.
import { pipe, subscribe } from 'wonka';
const getNewsSubscription = gql`
subscription GetNews {
breakingNews {
id
text
createdAt
}
}
`;
function subscribeToBreakingNews() {
const subscription = pipe(
client.subscription(getNewsSubscription, {}),
subscribe(result => {
if (result.data) {
console.log(result.data.breakingNews.text);
}
})
);
return subscription.unsubscribe;
}
a GraphQL document containing the subscription operation that will be executed.
the variables used to execute the operation.
Optional context: Partial<OperationContext>A Wonka Source issuing the OperationResults for the GraphQL operation.
Generated using TypeDoc
The
Clientis the central hub for your GraphQL operations and holdsurql's state.Remarks
The
Clientmanages your active GraphQL operations and their state, and contains the Exchange pipeline to execute your GraphQL operations.It contains methods that allow you to execute GraphQL operations manually, but the
Clientis also interacted with by bindings (for React, Preact, Vue, Svelte, etc) to execute GraphQL operations.While Exchanges are ultimately responsible for the control flow of operations, sending API requests, and caching, the
Clientstill has the important responsibility for creating operations, managing consumers of active operations, sharing results for operations, and more tasks as a “central hub”.See
https://urql.dev/goto/docs/architecture/#requests-and-operations-on-the-client for more information on what the
Clientis and does.