+88 -1

docs/basics/react-preact.md

reviewed

··· 222 222 can learn more about how the cache behaves given the four different policies on the "Document 223 223 Caching" page.](../basics/document-caching.md) 224 224 225 225 + ```jsx 226 226 + const [result, reexecuteQuery] = useQuery({ 227 227 + query: TodosListQuery, 228 228 + variables: { from, limit }, 229 229 + requestPolicy: 'cache-and-network', 230 230 + }); 231 231 + ``` 232 232 + 233 233 + Specifically, a new request policy may be passed directly to the `useQuery` hook as an option. 234 234 + This policy is then used for this specific query. In this case, `cache-and-network` is used and 235 235 + the query will be refreshed from our API even after our cache has given us a cached result. 236 236 + 237 237 + Internally, the `requestPolicy` is just one of several "**context** options". The `context` 238 238 + provides metadata apart from the usual `query` and `variables` we may pass. This means that 239 239 + we may also change the `Client`'s default `requestPolicy` by passing it there. 240 240 + 241 241 + ```js 242 242 + import { createClient } from 'urql'; 243 243 + 244 244 + const client = createClient({ 245 245 + url: 'http://localhost:3000/graphql', 246 246 + // every operation will by default use cache-and-network rather 247 247 + // than cache-first now: 248 248 + requestPolicy: 'cache-and-network', 249 249 + }); 250 250 + ``` 251 251 + 252 252 + ### Context Options 253 253 + 254 254 + As mentioned, the `requestPolicy` option on `useQuery` is a part of `urql`'s context options. 255 255 + In fact, there are several more built-in context options, and the `requestPolicy` option is 256 256 + one of them. Another option we've already seen is the `url` option, which determines our 257 257 + API's URL. These options aren't limited to the `Client` and may also be passed per query. 258 258 + 259 259 + ```jsx 260 260 + import { useMemo } from 'react'; 261 261 + import { useQuery } from 'urql'; 262 262 + 263 263 + const Todos = ({ from, limit }) => { 264 264 + const [result, reexecuteQuery] = useQuery({ 265 265 + query: TodosListQuery, 266 266 + variables: { from, limit }, 267 267 + context: useMemo( 268 268 + () => ({ 269 269 + requestPolicy: 'cache-and-network', 270 270 + url: 'http://localhost:3000/graphql?debug=true', 271 271 + }), 272 272 + [] 273 273 + ), 274 274 + }); 275 275 + 276 276 + // ... 277 277 + }; 278 278 + ``` 279 279 + 280 280 + As we can see, the `context` property for `useQuery` accepts any known `context` option and can be 281 281 + used to alter them per query rather than globally. The `Client` accepts a subset of `context` 282 282 + options, while the `useQuery` option does the same for a single query. 283 283 + [You can find a list of all `Context` options in the API docs.](../api/core.md#operationcontext) 284 284 + 225 285 ### Reexecuting Queries 226 286 227 287 The `useQuery` hook updates and executes queries whenever its inputs, like the `query` or ··· 251 311 cache, since we're passing `requestPolicy: 'network-only'`. 252 312 253 313 Furthermore the `reexecuteQuery` function can also be used to programmatically start a query even 254 254 - when `pause` is set to `true`, which would usually stop all automatic queries. 314 314 + when `pause` is set to `true`, which would usually stop all automatic queries. This can be used to 315 315 + perform one-off actions, or to set up polling. 316 316 + 317 317 + ```jsx 318 318 + import { useEffect } from 'react'; 319 319 + import { useQuery } from 'urql'; 320 320 + 321 321 + const Todos = ({ from, limit }) => { 322 322 + const [result, reexecuteQuery] = useQuery({ 323 323 + query: TodosListQuery, 324 324 + variables: { from, limit }, 325 325 + pause: true, 326 326 + }); 327 327 + 328 328 + useEffect(() => { 329 329 + if (result.fetching) return; 330 330 + 331 331 + // Set up to refetch in one second, if the query is idle 332 332 + const timerId = setTimeout(() => { 333 333 + reexecuteQuery({ requestPolicy: 'network-only' }); 334 334 + }, 1000); 335 335 + 336 336 + return () => clearTimeout(timerId); 337 337 + }, [result.fetching, reexecuteQuery]); 338 338 + 339 339 + // ... 340 340 + }; 341 341 + ``` 255 342 256 343 There are some more tricks we can use with `useQuery`. [Read more about its API in the API docs for 257 344 it.](../api/urql.md#usequery)

+61 -19

docs/basics/svelte.md

reviewed

··· 278 278 default, this is set to `cache-first`, which means that we prefer to get results from our cache, but 279 279 are falling back to sending an API request. 280 280 281 281 - In total there are four different policies that we can use: 281 281 + Request policies aren't specific to `urql`'s Svelte bindings, but are a common feature in its core. 282 282 + [You can learn more about how the cache behaves given the four different policies on the "Document 283 283 + Caching" page.](../basics/document-caching.md) 282 284 283 283 - - `cache-first` (the default) prefers cached results and falls back to sending an API request when 284 284 - no prior result is cached. 285 285 - - `cache-and-network` returns cached results but also always sends an API request, which is perfect 286 286 - for displaying data quickly while keeping it up-to-date. 287 287 - - `network-only` will always send an API request and will ignore cached results. 288 288 - - `cache-only` will always return cached results or `null`. 285 285 + ```jsx 286 286 + <script> 287 287 + import { operationStore, query } from '@urql/svelte'; 289 288 290 290 - The `cache-and-network` policy is particularly useful, since it allows us to display data instantly 291 291 - if it has been cached, but also refreshes data in our cache in the background. This means though 292 292 - that `fetching` will be `false` for cached results although an API request may still be ongoing in 293 293 - the background. 289 289 + const todos = operationStore(` 290 290 + query ($from: Int!, $limit: Int!) { 291 291 + todos(from: $from, limit: $limit) { 292 292 + id 293 293 + title 294 294 + } 295 295 + }`, 296 296 + { from, limit }, 297 297 + { requestPolicy: 'cache-and-network' } 298 298 + ); 294 299 295 295 - For this reason there's another field on results, `result.stale`, which indicates that the cached 296 296 - result is either outdated or that another request is being sent in the background. 300 300 + query(todos); 301 301 + </script> 302 302 + 303 303 + ... 304 304 + ``` 305 305 + 306 306 + As we can see, the `requestPolicy` is easily changed by passing it directly as a "context option" 307 307 + when creating an `operationStore`. We can then read our `context` option back from `todos.context`, 308 308 + just as we can check `todos.query` and `todos.variables`. 309 309 + 310 310 + Internally, the `requestPolicy` is just one of several "**context** options". The `context` 311 311 + provides metadata apart from the usual `query` and `variables` we may pass. This means that 312 312 + we may also change the `Client`'s default `requestPolicy` by passing it there. 313 313 + 314 314 + ```js 315 315 + import { createClient } from '@urql/svelte'; 316 316 + 317 317 + const client = createClient({ 318 318 + url: 'http://localhost:3000/graphql', 319 319 + // every operation will by default use cache-and-network rather 320 320 + // than cache-first now: 321 321 + requestPolicy: 'cache-and-network', 322 322 + }); 323 323 + ``` 324 324 + 325 325 + ### Context Options 326 326 + 327 327 + As mentioned, the `requestPolicy` option that we're passing to the `operationStore` is a part of 328 328 + `urql`'s context options. In fact, there are several more built-in context options, and the 329 329 + `requestPolicy` option is one of them. Another option we've already seen is the `url` option, which 330 330 + determines our API's URL. 297 331 298 332 ```jsx 299 333 <script> ··· 307 341 } 308 342 }`, 309 343 { from, limit }, 310 310 - { requestPolicy: 'cache-and-network' } 344 344 + { 345 345 + requestPolicy: 'cache-and-network' 346 346 + url: 'http://localhost:3000/graphql?debug=true', 347 347 + } 311 348 ); 312 349 313 350 query(todos); ··· 316 353 ... 317 354 ``` 318 355 319 319 - As we can see, the `requestPolicy` is easily changed, and we can read our `context` option back 320 320 - from `todos.context`, just as we can check `todos.query` and `todos.variables`. Updating 321 321 - `operationStore.context` can be very useful to also refetch queries, as we'll see in the next 322 322 - section. 356 356 + As we can see, the `context` argument for `operationStore` accepts any known `context` option and 357 357 + can be used to alter them per query rather than globally. The `Client` accepts a subset of `context` 358 358 + options, while the `operationStore` argument does the same for a single query. They're then merged 359 359 + for your operation and form a full `Context` object for each operation, which means that any given 360 360 + query is able to override them as needed. 323 361 324 324 - [You can learn more about request policies on the API docs.](../api/core.md#requestpolicy) 362 362 + [You can find a list of all `Context` options in the API docs.](../api/core.md#operationcontext) 325 363 326 364 ### Reexecuting Queries 327 365 ··· 359 397 360 398 Calling `refresh` in the above example will execute the query again forcefully, and will skip the 361 399 cache, since we're passing `requestPolicy: 'network-only'`. 400 400 + 401 401 + Furthermore the `reexecute` function can also be used to programmatically start a query even 402 402 + when `pause` is set to `true`, which would usually stop all automatic queries. This can be used to 403 403 + perform one-off actions, or to set up polling. 362 404 363 405 ### Reading on 364 406

+66 -22

docs/basics/vue.md

reviewed

··· 335 335 default this is set to `cache-first`, which means that we prefer to get results from our cache, but 336 336 are falling back to sending an API request. 337 337 338 338 - In total there are four different policies that we can use: 338 338 + Request policies aren't specific to `urql`'s Vue bindings, but are a common feature in its core. 339 339 + [You can learn more about how the cache behaves given the four different policies on the "Document 340 340 + Caching" page.](../basics/document-caching.md) 339 341 340 340 - - `cache-first` (the default) prefers cached results and falls back to sending an API request when 341 341 - no prior result is cached. 342 342 - - `cache-and-network` returns cached results but also always sends an API request, which is perfect 343 343 - for displaying data quickly while keeping it up-to-date. 344 344 - - `network-only` will always send an API request and will ignore cached results. 345 345 - - `cache-only` will always return cached results or `null`. 342 342 + ```js 343 343 + import { useQuery } from '@urql/vue'; 346 344 347 347 - The `cache-and-network` policy is particularly useful, since it allows us to display data instantly 348 348 - if it has been cached, but also refreshes data in our cache in the background. This means though 349 349 - that `fetching` will be `false` for cached results although an API request may still be ongoing in 350 350 - the background. 345 345 + export default { 346 346 + setup() { 347 347 + return useQuery({ 348 348 + query: TodosQuery, 349 349 + requestPolicy: 'cache-and-network', 350 350 + }); 351 351 + }, 352 352 + }; 353 353 + ``` 351 354 352 352 - For this reason there's another field on results, `result.stale`, which indicates that the cached 353 353 - result is either outdated or that another request is being sent in the background. 355 355 + Specifically, a new request policy may be passed directly to `useQuery` as an option. 356 356 + This policy is then used for this specific query. In this case, `cache-and-network` is used and 357 357 + the query will be refreshed from our API even after our cache has given us a cached result. 354 358 355 355 - Request policies aren't specific to `urql`'s Vue bindings, but are a common feature in its core. [You 356 356 - can learn more about request policies on the API docs.](../api/core.md#requestpolicy) 359 359 + Internally, the `requestPolicy` is just one of several "**context** options". The `context` 360 360 + provides metadata apart from the usual `query` and `variables` we may pass. This means that 361 361 + we may also change the `Client`'s default `requestPolicy` by passing it there. 362 362 + 363 363 + ```js 364 364 + import { createClient } from '@urql/vue'; 365 365 + 366 366 + const client = createClient({ 367 367 + url: 'http://localhost:3000/graphql', 368 368 + // every operation will by default use cache-and-network rather 369 369 + // than cache-first now: 370 370 + requestPolicy: 'cache-and-network', 371 371 + }); 372 372 + ``` 373 373 + 374 374 + ### Context Options 375 375 + 376 376 + As mentioned, the `requestPolicy` option on `useQuery` is a part of `urql`'s context options. 377 377 + In fact, there are several more built-in context options, and the `requestPolicy` option is 378 378 + one of them. Another option we've already seen is the `url` option, which determines our 379 379 + API's URL. These options aren't limited to the `Client` and may also be passed per query. 380 380 + 381 381 + ```jsx 382 382 + import { useQuery } from '@urql/vue'; 383 383 + 384 384 + export default { 385 385 + setup() { 386 386 + return useQuery({ 387 387 + query: TodosQuery, 388 388 + context: { 389 389 + requestPolicy: 'cache-and-network', 390 390 + url: 'http://localhost:3000/graphql?debug=true', 391 391 + }, 392 392 + }); 393 393 + }, 394 394 + }; 395 395 + ``` 396 396 + 397 397 + As we can see, the `context` property for `useQuery` accepts any known `context` option and can be 398 398 + used to alter them per query rather than globally. The `Client` accepts a subset of `context` 399 399 + options, while the `useQuery` option does the same for a single query. 400 400 + [You can find a list of all `Context` options in the API docs.](../api/core.md#operationcontext) 357 401 358 402 ### Reexecuting Queries 359 403 ··· 379 423 title 380 424 } 381 425 } 382 382 - ` 426 426 + `, 383 427 }); 384 428 385 429 return { ··· 388 432 error: result.error, 389 433 refresh() { 390 434 result.executeQuery({ 391 391 - requestPolicy: 'network-only' 435 435 + requestPolicy: 'network-only', 392 436 }); 393 393 - } 437 437 + }, 394 438 }; 395 395 - } 439 439 + }, 396 440 }; 397 397 - </script> 398 441 ``` 399 442 400 443 Calling `refresh` in the above example will execute the query again forcefully, and will skip the 401 444 cache, since we're passing `requestPolicy: 'network-only'`. 402 445 403 403 - Furthermore the `executeQuery` method can also be used to programmatically start a query even 404 404 - when `pause` is `true`, which would usually stop all automatic queries. 446 446 + Furthermore the `executeQuery` function can also be used to programmatically start a query even 447 447 + when `pause` is set to `true`, which would usually stop all automatic queries. This can be used to 448 448 + perform one-off actions, or to set up polling. 405 449 406 450 ### Vue Suspense 407 451

-78

docs/common-questions.md

reviewed

··· 1 1 - --- 2 2 - title: Common questions 3 3 - order: 6 4 4 - --- 5 5 - 6 6 - # Common questions 7 7 - 8 8 - ## How do we achieve asynchronous fetchOptions? 9 9 - 10 10 - If you need `async fetchOptions` you can add an exchange that looks like this: 11 11 - 12 12 - ```js 13 13 - import { makeOperation } from '@urql/core'; 14 14 - import { Exchange, Operation } from 'urql'; 15 15 - import { pipe, mergeMap, map, fromPromise, fromValue } from 'wonka'; 16 16 - 17 17 - const isPromise = (value: any): value is Promise<unknown> => { 18 18 - return typeof value.then === 'function'; 19 19 - }; 20 20 - 21 21 - export const fetchOptionsExchange = 22 22 - ( 23 23 - fn: (fetchOptions: RequestInit) => Promise<RequestInit> | RequestInit, 24 24 - ): Exchange => 25 25 - ({ forward }) => 26 26 - (ops$) => { 27 27 - return pipe( 28 28 - ops$, 29 29 - mergeMap((operation: Operation) => { 30 30 - const currentOptions = 31 31 - typeof operation.context.fetchOptions === 'function' 32 32 - ? operation.context.fetchOptions() 33 33 - : operation.context.fetchOptions || {}; 34 34 - 35 35 - const finalOptions = fn(currentOptions); 36 36 - 37 37 - return pipe( 38 38 - isPromise(finalOptions) 39 39 - ? fromPromise(finalOptions) 40 40 - : fromValue(finalOptions), 41 41 - map((fetchOptions) => { 42 42 - return makeOperation(operation.kind, operation, { 43 43 - ...operation.context, 44 44 - fetchOptions, 45 45 - }); 46 46 - }), 47 47 - ); 48 48 - }), 49 49 - forward, 50 50 - ); 51 51 - }; 52 52 - ``` 53 53 - 54 54 - If we add the above exchange before our `fetchExchange` our `fetchOptions` will be handled. 55 55 - 56 56 - ```js 57 57 - const client = createClient({ 58 58 - url: 'http://yourUrl.dev/', 59 59 - exchanges: [ 60 60 - dedupExchange, 61 61 - cacheExchange, 62 62 - fetchOptionsExchange(async (fetchOptions) => { 63 63 - return Promise.resolve({ 64 64 - ...fetchOptions, 65 65 - headers: { 66 66 - Authorization: 'Bearer mySuperToken', 67 67 - }, 68 68 - }); 69 69 - }), 70 70 - fetchExchange, 71 71 - ], 72 72 - }); 73 73 - ``` 74 74 - 75 75 - This scenario can for instance occur when dealing with React-native AsyncStorage, this way we can 76 76 - asynchronously get a value from there. 77 77 - 78 78 - [Credits to @RodolfoSilva](https://github.com/FormidableLabs/urql/issues/234#issuecomment-602305153)

+1 -1

docs/comparison.md

reviewed

··· 43 43 | Devtools | ✅ | ✅ | ✅ | 44 44 | Subscriptions | ✅ | ✅ | ✅ | 45 45 | Client-side Rehydration | ✅ | ✅ | ✅ | 46 46 - | Polled Queries | ✅ | ✅ | ✅ | 46 46 + | Polled Queries | 🔶 | ✅ | ✅ | 47 47 | Lazy Queries | ✅ | ✅ | ✅ | 48 48 | Stale while Revalidate / Cache and Network | ✅ | ✅ | ✅ | 49 49 | Focus Refetching | ✅ `@urql/exchange-refocus` | 🛑 | 🛑 |