0
# @urql/core
1

2
@urql/core is the foundational GraphQL client library that provides a highly customizable and versatile approach to GraphQL operations. It implements a modular exchange system for handling requests, caching, subscriptions, and other GraphQL client concerns, with full TypeScript support and framework-agnostic design.
3

4
## Package Information
5

6
- **Package Name**: @urql/core
7
- **Package Type**: npm  
8
- **Language**: TypeScript
9
- **Installation**: `npm install @urql/core`
10

11
## Core Imports
12

13
```typescript
14
import { Client, createClient, gql, cacheExchange, fetchExchange } from "@urql/core";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const { Client, createClient, gql, cacheExchange, fetchExchange } = require("@urql/core");
21
```
22

23
## Basic Usage
24

25
```typescript
26
import { createClient, gql, cacheExchange, fetchExchange } from "@urql/core";
27

28
// Create a client
29
const client = createClient({
30
  url: "https://api.example.com/graphql",
31
  exchanges: [cacheExchange, fetchExchange],
32
});
33

34
// Define a query
35
const GetUserQuery = gql`
36
  query GetUser($id: ID!) {
37
    user(id: $id) {
38
      id
39
      name
40
      email
41
    }
42
  }
43
`;
44

45
// Execute query
46
const result = await client.query(GetUserQuery, { id: "123" }).toPromise();
47

48
if (result.error) {
49
  console.error("GraphQL Error:", result.error);
50
} else {
51
  console.log("User data:", result.data.user);
52
}
53
```
54

55
## Architecture
56

57
@urql/core is built around several key architectural components:
58

59
- **Client**: Central hub managing GraphQL operations and their state
60
- **Exchange System**: Modular pipeline for processing operations (caching, fetching, debugging, etc.)
61
- **Operation Flow**: Request/response cycle using Wonka streams for reactive programming
62
- **Type Safety**: Full TypeScript integration with strongly typed GraphQL operations
63
- **Framework Agnostic**: Core functionality independent of any specific UI framework
64

65
## Capabilities
66

67
### Client Management
68

69
Core client creation and configuration for managing GraphQL operations and state.
70

71
```typescript { .api }
72
interface ClientOptions {
73
  url: string;
74
  exchanges: Exchange[];
75
  fetchOptions?: RequestInit | (() => RequestInit);
76
  fetch?: typeof fetch;
77
  fetchSubscriptions?: boolean;
78
  suspense?: boolean;
79
  requestPolicy?: RequestPolicy;
80
  preferGetMethod?: boolean | 'force' | 'within-url-limit';
81
}
82

83
function createClient(options: ClientOptions): Client;
84
```
85

86
[Client Management](./client.md)
87

88
### GraphQL Operations
89

90
Execute queries, mutations, and subscriptions with full type safety and reactive streams.
91

92
```typescript { .api }
93
class Client {
94
  query<Data = any, Variables extends AnyVariables = AnyVariables>(
95
    query: DocumentInput<Data, Variables>,
96
    variables: Variables,
97
    context?: Partial<OperationContext>
98
  ): OperationResultSource<OperationResult<Data, Variables>>;
99

100
  mutation<Data = any, Variables extends AnyVariables = AnyVariables>(
101
    query: DocumentInput<Data, Variables>,
102
    variables: Variables,
103
    context?: Partial<OperationContext>
104
  ): OperationResultSource<OperationResult<Data, Variables>>;
105

106
  subscription<Data = any, Variables extends AnyVariables = AnyVariables>(
107
    query: DocumentInput<Data, Variables>,
108
    variables: Variables,
109
    context?: Partial<OperationContext>
110
  ): OperationResultSource<OperationResult<Data, Variables>>;
111
}
112
```
113

114
[GraphQL Operations](./operations.md)
115

116
### Exchange System
117

118
Modular pipeline system for handling caching, fetching, debugging, and custom operation processing.
119

120
```typescript { .api }
121
type Exchange = (input: ExchangeInput) => ExchangeIO;
122
type ExchangeIO = (ops$: Source<Operation>) => Source<OperationResult>;
123

124
function cacheExchange(): Exchange;
125
function fetchExchange(): Exchange; 
126
function debugExchange(): Exchange;
127
function subscriptionExchange(options: SubscriptionExchangeOpts): Exchange;
128
function ssrExchange(params: SSRExchangeParams): SSRExchange;
129
function composeExchanges(exchanges: Exchange[]): Exchange;
130
```
131

132
[Exchange System](./exchanges.md)
133

134
### GraphQL Parsing and Utilities
135

136
GraphQL document parsing, request creation, utility functions for operation processing, and internal HTTP transport utilities.
137

138
```typescript { .api }
139
function gql<Data = any, Variables extends AnyVariables = AnyVariables>(
140
  strings: TemplateStringsArray,
141
  ...interpolations: Array<TypedDocumentNode | DocumentNode | string>
142
): TypedDocumentNode<Data, Variables>;
143

144
function createRequest<Data = any, Variables extends AnyVariables = AnyVariables>(
145
  query: DocumentInput<Data, Variables>,
146
  variables: Variables
147
): GraphQLRequest<Data, Variables>;
148

149
function makeOperation<Data = any, Variables extends AnyVariables = AnyVariables>(
150
  kind: OperationType,
151
  request: GraphQLRequest<Data, Variables>,
152
  context: OperationContext
153
): Operation<Data, Variables>;
154
```
155

156
[Utilities and Parsing](./utilities.md)
157

158
### Error Handling
159

160
Comprehensive error handling for GraphQL and network errors with detailed error information.
161

162
```typescript { .api }
163
class CombinedError extends Error {
164
  constructor(params: {
165
    networkError?: Error;
166
    graphQLErrors?: readonly GraphQLError[];
167
    response?: Response;
168
  });
169
  networkError?: Error;
170
  graphQLErrors: GraphQLError[];
171
  response?: Response;
172
}
173

174
function makeErrorResult<Data = any, Variables extends AnyVariables = AnyVariables>(
175
  operation: Operation<Data, Variables>,
176
  error: Error | CombinedError,
177
  response?: ExecutionResult
178
): OperationResult<Data, Variables>;
179
```
180

181
[Error Handling](./errors.md)
182

183
### Internal APIs (Advanced)
184

185
Low-level HTTP transport utilities for custom exchange development and advanced use cases.
186

187
```typescript { .api }
188
function makeFetchBody<Data = any, Variables extends AnyVariables = AnyVariables>(
189
  request: Omit<GraphQLRequest<Data, Variables>, 'key'>
190
): FetchBody;
191

192
function makeFetchURL(operation: Operation, body?: FetchBody): string;
193

194
function makeFetchOptions(operation: Operation, body?: FetchBody): RequestInit;
195

196
function makeFetchSource(
197
  operation: Operation,
198
  url: string,
199
  fetchOptions: RequestInit
200
): Source<OperationResult>;
201
```
202

203
[Internal APIs](./internal.md)
204

205
## Types
206

207
### Core Operation Types
208

209
```typescript { .api }
210
type OperationType = 'subscription' | 'query' | 'mutation' | 'teardown';
211

212
type RequestPolicy = 
213
  | 'cache-first' 
214
  | 'cache-and-network' 
215
  | 'network-only' 
216
  | 'cache-only';
217

218
type AnyVariables = { [prop: string]: any } | void | undefined;
219

220
type DocumentInput<Result = { [key: string]: any }, Variables = { [key: string]: any }> = 
221
  string | DocumentNode | TypedDocumentNode<Result, Variables>;
222
```
223

224
### Request and Result Types  
225

226
```typescript { .api }
227
interface GraphQLRequest<Data = any, Variables extends AnyVariables = AnyVariables> {
228
  key: number;
229
  query: DocumentNode | PersistedDocument | TypedDocumentNode<Data, Variables>;
230
  variables: Variables;
231
  extensions?: RequestExtensions | undefined;
232
}
233

234
interface OperationResult<Data = any, Variables extends AnyVariables = AnyVariables> {
235
  operation: Operation<Data, Variables>;
236
  data?: Data;
237
  error?: CombinedError;
238
  extensions?: Record<string, any>;
239
  stale: boolean;
240
  hasNext: boolean;
241
}
242
```
243

244
### Context and Configuration Types
245

246
```typescript { .api }
247
interface OperationContext {
248
  url: string;
249
  fetchOptions?: RequestInit | (() => RequestInit);
250
  fetch?: typeof fetch;
251
  fetchSubscriptions?: boolean;
252
  requestPolicy: RequestPolicy;
253
  preferGetMethod?: boolean | 'force' | 'within-url-limit';
254
  suspense?: boolean;
255
  additionalTypenames?: string[];
256
  meta?: OperationDebugMeta;
257
  [key: string]: any;
258
}
259

260
interface Operation<Data = any, Variables extends AnyVariables = AnyVariables> 
261
  extends GraphQLRequest<Data, Variables> {
262
  readonly kind: OperationType;
263
  context: OperationContext;
264
}
265
```
266

267
### Advanced Types
268

269
```typescript { .api }
270
type OperationResultSource<T extends OperationResult> = Source<T> & 
271
  PromiseLike<T> & {
272
    toPromise(): Promise<T>;
273
    subscribe(onResult: (value: T) => void): Subscription;
274
  };
275

276
interface ExecutionResult<Data = any> {
277
  data?: Data;
278
  errors?: GraphQLError[];
279
  extensions?: Record<string, any>;
280
  incremental?: IncrementalPayload[];
281
  pending?: { id: string; path: Array<string | number> }[];
282
}
283

284
interface IncrementalPayload {
285
  id?: string;
286
  subPath?: Array<string | number>;
287
  path?: Array<string | number>;
288
  data?: any;
289
  errors?: GraphQLError[];
290
  extensions?: Record<string, any>;
291
}
292

293
interface PersistedDocument {
294
  documentId: string;
295
  definitions?: DefinitionNode[];
296
}
297

298
type FileMap = Map<string, File | Blob>;
299

300
interface FetchBody {
301
  query?: string;
302
  documentId?: string;
303
  operationName: string | undefined;
304
  variables: undefined | Record<string, any>;
305
  extensions: undefined | Record<string, any>;
306
}
307
```