kitten.sh
+4
-5
docs/README.md
+4
-5
docs/README.md
···-pages through ["Document Caching"](./concepts/document-caching.md) as well as dynamic and data-heavy···If at this point you're still unsure of whether to use `urql`, [have a look at the **Comparison**···- **Basics** is the section where we'll want to start learning about `urql` as it contains "Getting-- **Main Concepts** then explains more about how `urql` functions, what it's made up of, and covers- **Advanced** covers all more uncommon use-cases and contains guides that we won't need immediately
···+pages through ["Document Caching"](./basics/document-caching.md) as well as dynamic and data-heavy···If at this point you're still unsure of whether to use `urql`, [have a look at the **Comparison**···- **Basics** is the section where we'll want to start learning about `urql` as it contains "Getting+- **Architecture** then explains more about how `urql` functions, what it's made up of, and covers- **Advanced** covers all more uncommon use-cases and contains guides that we won't need immediately
+5
-2
docs/advanced/README.md
+5
-2
docs/advanced/README.md
···- [**Subscriptions**](./subscriptions.md) covers how to use `useSubscription` and how to set up GraphQL subscriptions with···- [**Retrying operations**](./retry-operations.md) shows the `retryExchange` which allows you to retry operations when they've failed.- [**Authentication**](./authentication.md) describes how to implement authentication using the `authExchange`- [**Testing**](./testing.md) covers how to test components that use `urql` particularly in React.- [**Auto-populate Mutations**](./auto-populate-mutations.md) presents the `populateExchange` addon which can make it easier to
···- [**Subscriptions**](./subscriptions.md) covers how to use `useSubscription` and how to set up GraphQL subscriptions with···- [**Retrying operations**](./retry-operations.md) shows the `retryExchange` which allows you to retry operations when they've failed.- [**Authentication**](./authentication.md) describes how to implement authentication using the `authExchange`- [**Testing**](./testing.md) covers how to test components that use `urql` particularly in React.+- [**Authoring Exchanges**](./authoring-exchanges.md) describes how to implement exchanges from- [**Auto-populate Mutations**](./auto-populate-mutations.md) presents the `populateExchange` addon which can make it easier to
+1
-1
docs/advanced/auto-populate-mutations.md
+1
-1
docs/advanced/auto-populate-mutations.md
+2
-2
docs/advanced/debugging.md
+2
-2
docs/advanced/debugging.md
···As demonstrated above, the `client.subscribeToDebugTarget` accepts a callback function and returnsa subscription with an `unsubscribe` method. We've seen this pattern in the prior ["Stream Patterns"···-In the ["Exchanges" section](../concepts/exchanges.md) we've learned about the [`ExchangeInput`
···As demonstrated above, the `client.subscribeToDebugTarget` accepts a callback function and returnsa subscription with an `unsubscribe` method. We've seen this pattern in the prior ["Stream Patterns"···+[On the "Authoring Exchanges" page](./authoring-exchanges.md) we've learned about the [`ExchangeInput`
+7
-3
docs/advanced/subscriptions.md
+7
-3
docs/advanced/subscriptions.md
···-[Read more about _Exchanges_ and how they work on the "Exchanges" page.](../concepts/exchanges.md)In the above example, we add the `subscriptionExchange` to the `Client` with the default exchangesadd before it. The `subscriptionExchange` is a factory that accepts additional options and returns···-When you're using subscriptions directly without `urql`'s framework bindings, you can use the `Client`'s `subscription` method for one-off subscriptions. This method is similar to the ones for mutations and subscriptions [that we've seen before on the "Core Package" page.](../concepts/core-package.md#one-off-queries-and-mutations)-This method will always [returns a Wonka stream](../concepts/stream-patterns.md#the-wonka-library) and doesn't have a `.toPromise()` shortcut method, since promises won't return the multiple values that a subscription may deliver. Let's convert the above example to one without framework code, as we may use subscriptions in a Node.js environment.
···In the above example, we add the `subscriptionExchange` to the `Client` with the default exchangesadd before it. The `subscriptionExchange` is a factory that accepts additional options and returns···+`Client`'s `subscription` method for one-off subscriptions. This method is similar to the ones for+mutations and subscriptions [that we've seen before on the "Core Package" page.](../basics/core.md)+This method will always [returns a Wonka stream](../architecture.md#the-wonka-library) and doesn't have a `.toPromise()` shortcut method, since promises won't return the multiple values that a subscription may deliver. Let's convert the above example to one without framework code, as we may use subscriptions in a Node.js environment.
+4
-1
docs/advanced/testing.md
+4
-1
docs/advanced/testing.md
···-In the section [Stream Patterns](../concepts/stream-patterns.md) we've seen, that all methods on the client operate with and return streams. These streams are created using the [Wonka](../concepts/stream-patterns.md#the-wonka-library) library and we're able to create streams ourselves to mock the different states of our operations, e.g. fetching, errors, or success with data.
···+In the section ["Stream Patterns" on the "Architecture" page](../architecture.md) we've seen, that+ourselves to mock the different states of our operations, e.g. fetching, errors, or success with data.
+1
-1
docs/api/README.md
+1
-1
docs/api/README.md
···Most of these packages will refer to or use utilities and types from the `@urql/core` package. [Read
···Most of these packages will refer to or use utilities and types from the `@urql/core` package. [Read
+9
-9
docs/api/core.md
+9
-9
docs/api/core.md
···Therefore if you're not accessing utilities directly, aren't in a Node.js environment, and are using······| `graphQLErrors` | `?Array<string \| GraphQLError>` | GraphQL Errors (if any) that were returned by the GraphQL API |···-[Read more about request policies on the "Document Caching" page.](../concepts/document-caching.md#request-policies)···An exchange is defined to be a function that receives [`ExchangeInput`](#exchangeinput) and returnsan `ExchangeIO` function. The `ExchangeIO` function in turn will receive a stream of operations, and···-The `cacheExchange` as [described on the "Document Caching" page.](../concepts/document-caching.md). It's of type `Exchange`.
···Therefore if you're not accessing utilities directly, aren't in a Node.js environment, and are using······| `graphQLErrors` | `?Array<string \| GraphQLError>` | GraphQL Errors (if any) that were returned by the GraphQL API |···+[Read more about request policies on the "Document Caching" page.](../basics/document-caching.md#request-policies)···+[Read more about _Exchanges_ on the "Authoring Exchanges" page.](../advanced/authoring-exchanges.md)An exchange is defined to be a function that receives [`ExchangeInput`](#exchangeinput) and returnsan `ExchangeIO` function. The `ExchangeIO` function in turn will receive a stream of operations, and···+[If you haven't yet seen streams you can read more about "Stream Patterns" on the "Architecture"+The `cacheExchange` as [described on the "Document Caching" page.](../basics/document-caching.md). It's of type `Exchange`.
+1
-1
docs/api/request-policy-exchange.md
+1
-1
docs/api/request-policy-exchange.md
···-[Read more about request policies on the "Document Caching" page.](../concepts/document-caching.md#request-policies)
···+[Read more about request policies on the "Document Caching" page.](../basics/document-caching.md#request-policies)
+245
docs/architecture.md
+245
docs/architecture.md
···
···+`urql` is a highly customizable and flexible GraphQL client, that happens to come with some default+By default, `urql` aims to provide the minimal amount of features that allow us to build an app+that grows with our usage and demands. As we go from building our smallest or first GraphQL apps to+utilising its full functionality, we have tools at our disposal to extend and customize `urql` to+You may have worked with a GraphQL API previously and noticed that using GraphQL in your app can be+In the following sections we'll talk about the way that `urql` solves these three problems and how the logic abstracted away internally.+If `urql` was a train it would take several stops to arrive at its terminus, our API. It starts with us+defining queries or mutations. Any GraphQL request can be abstracted into their query documents and+their variables. In `urql`, these GraphQL requests are treated as unique objects which are uniquely+identified by the query document and variables (which is why a `key` is generated from the two). This+[`Client`](./api/core.md#client). It accepts several options like `url` or `requestPolicy` which are+`Client`](./api/core.md#client) directly and are a thin abstraction on top of it. Though some methods can be called on it directly, as seen [on the "Core Usage"+[`Operation`s.](./api/core.md#operation). An "Operation" is an extension of `GraphQLRequest`s. Not+It's the `Client`s responsibility to accept an `Operation` and execute it. The bindings interally+call the `client.executeQuery`, `client.executeMutation`, or `client.executeSubscription` methods+In the diagram we can see that each operation is a signal for our request to start at which point+we can expect to receive our results eventually on a callback. Once we're not interested in results+anymore a special "teardown" signal is issued on the `Client`. While we don't see operations outside+To reiterate, when we use `urql`'s bindings for our framework of choice, methods are called on the+`Client` but we never see the operations that are created in the background from our bindings. We+call a method like `client.executeQuery` (or it's called for us in the bindings), an operation is+issued internally when we subscribe with a callback, and later our callback is called with results.+While we know that, for us, we're only interested in a single [`Operation`](./api/core.md#operation)+and its [`OperationResult`s](./api/core.md#operationresult) at a time, the `Client` treats these as+original `operation`. Because an `OperationResult` also carries an `operation` property the `Client`+However, internally, all of our operations are processed at the same time concurrently. However from+- The `Client` issues the operation and we'll receive some results back eventually as either the+- We eventually unsubscribe and the `Client` issues a "teardown" operation with the same `key` as+The `Client` itself doesn't actually know what to do with operations. Instead, it sends them through+"exchanges". Exchanges are akin to [middleware in Redux](https://redux.js.org/advanced/middleware)+and have access to all operations and all results. Multiple exchanges are chained to process our+operations and to execute logic on them, one of them being the `fetchExchange`, which as the name+- This operation identifies itself as either a `"query"`, `"mutation"` or `"subscription"` and has a+- The operation is sent to the API and a **result** comes back which is wrapped in an `OperationResult`+- The `Client` filters the `OperationResult` by the `operation.key` and — via a callback — gives us+To come back to our train analogy from earlier, an operation, like a train, travels from one end+of the track to the terminus — our API. The results then come back on the same path as they're just+- `cacheExchange`: The default caching logic with ["Document Caching"](../basics/document-caching.md)+- `fetchExchange`: Sends an operation to the API using `fetch` and adds results to the output stream+When we don't pass the `exchanges` option manually to our `Client` then these are the ones that will+be applied. As we can see, an exchange exters a lot of power over our operations and results. They+determine a lot of the logic of the `Client`, taking care of things like deduplication, caching, and+- [`errorExchange`](./api/core.md#errorexchange): Allows a global callback to be called when any error occurs+- [`multipartFetchExchange`](./advanced/persistence-and-uploads.md#file-uploads): Provides multipart file upload capability+- [`persistedFetchExchange`](./advanced/persistence-and-uploads.md#automatic-persisted-queries): Provides support for Automatic+- [`authExchange`](./advanced/authentication.md): Allows complex authentication flows to be implemented+- [`requestPolicyExchange`](../api/request-policy-exchange.md): Automatically upgrades `cache-only` and `cache-first` operations to `cache-and-network` after a given amount of time.+- `devtoolsExchange`: Provides the ability to use the [urql-devtools](https://github.com/FormidableLabs/urql-devtools)+We can even swap out our [document cache](./basics/document-caching.md), which is implemented by+In the previous sections we've learned a lot about how the `Client` works, but we've always learned+it in vague terms — for instance, we've learned that we get a "stream of results" or `urql` sees all+Generally we refer to _streams_ as abstractions that allow us to program with asynchronous events+and [Reactive Programming with Observables.](http://reactivex.io/documentation/observable.html)+These concepts may sound initimidating, but from a high-level view what we're talking about can be+thought of as a combination of promises and iterables (e.g. arrays). We're dealing with multiple+events but our callback is called over time. It's like calling `forEach` on an array but expecting+section](./basics/README.md), we may never see these streams in action or may never use them even,+directly](./basics/core.md#one-off-queries-and-mutations) or write exchanges then we'll see streams+`urql` utilises the [Wonka](https://github.com/kitten/wonka) library for its streams. It has a+In Wonka, like with Observables, streams are cancellable by calling the `unsubscribe` method that a+When we call methods on the `Client` like [`client.executeQuery`](./api/core.md#clientexecutequery)+or [`client.query`](./api/core.md#clientquery) then these will return a Wonka stream. Those are+We can use [`wonka`'s `subscribe`](https://wonka.kitten.sh/api/sinks#subscribe) function to start+this stream. We pass this function a callback and will receive results back from the `Client`, as it+starts our operation. When we unsubscribe then the `Client` will stop this operation by sending a
+4
-5
docs/basics/README.md
+4
-5
docs/basics/README.md
···- [**Core Package**](./core-package.md) defines why a shared package exists that contains the main-documentation](../concepts/README.md) as it explains the motivation and architecture that drives-- [**Document Caching**](../concepts/document-caching.md) explains the default cache mechanism of `urql`, as opposed to the opt-in
···- [**Core Package**](./core-package.md) defines why a shared package exists that contains the main+After reading the page for your bindings and the "Core" page you may want to the next two pages in+- [**Document Caching**](./document-caching.md) explains the default cache mechanism of `urql`, as opposed to the opt-in
+5
-5
docs/basics/core.md
+5
-5
docs/basics/core.md
······This concludes the introduction for using `@urql/core` without any framework bindings. This showedjust a couple of ways to use `gql` or the `Client`, however you may also want to learn more about-[how to use `urql`'s streams](../concepts/stream-patterns.md). Furthermore, apart from the frameworkbinding introductions, there are some other pages that provide more information on how to get fully- [Setting up other features, like authentication, uploads, or persisted queries.](../advanced/README.md)
······This concludes the introduction for using `@urql/core` without any framework bindings. This showedjust a couple of ways to use `gql` or the `Client`, however you may also want to learn more about+[how to use `urql`'s streams](../architecture.md#stream-patterns-in-urql). Furthermore, apart from the frameworkbinding introductions, there are some other pages that provide more information on how to get fully- [Setting up other features, like authentication, uploads, or persisted queries.](../advanced/README.md)
+7
-7
docs/basics/react-preact.md
+7
-7
docs/basics/react-preact.md
······The result object contains several properties. The `fetching` field indicates whether we're currentlyloading data, `data` contains the actual `data` from the API's result, and `error` is set when either···Request policies aren't specific to `urql`'s React API, but are a common feature in its core. [You······which is the same between all framework bindings. Hence, next we may want to learn more about one of- [Setting up other features, like authentication, uploads, or persisted queries.](../advanced/README.md)
······The result object contains several properties. The `fetching` field indicates whether we're currentlyloading data, `data` contains the actual `data` from the API's result, and `error` is set when either···Request policies aren't specific to `urql`'s React API, but are a common feature in its core. [You······which is the same between all framework bindings. Hence, next we may want to learn more about one of- [Setting up other features, like authentication, uploads, or persisted queries.](../advanced/README.md)
+6
-6
docs/basics/svelte.md
+6
-6
docs/basics/svelte.md
············which is the same between all framework bindings. Hence, next we may want to learn more about one of- [Setting up other features, like authentication, uploads, or persisted queries.](../advanced/README.md)
············which is the same between all framework bindings. Hence, next we may want to learn more about one of- [Setting up other features, like authentication, uploads, or persisted queries.](../advanced/README.md)
+6
-6
docs/basics/vue.md
+6
-6
docs/basics/vue.md
······The result object contains several properties. The `fetching` field indicates whether we're currentlyloading data, `data` contains the actual `data` from the API's result, and `error` is set when either······which is the same between all framework bindings. Hence, next we may want to learn more about one of- [Setting up other features, like authentication, uploads, or persisted queries.](../advanced/README.md)
······The result object contains several properties. The `fetching` field indicates whether we're currentlyloading data, `data` contains the actual `data` from the API's result, and `error` is set when either······which is the same between all framework bindings. Hence, next we may want to learn more about one of- [Setting up other features, like authentication, uploads, or persisted queries.](../advanced/README.md)
-27
docs/concepts/README.md
-27
docs/concepts/README.md
···-In this chapter we'll learn about the motivation behind `urql`, the architecture that drives it, the-inner workings of the `Client`, and how to write extensions and addons, also known as _Exchanges_.-- [**Document Caching**](./document-caching.md) explains the default cache mechanism of `urql`, as opposed to the opt-in-- [**Philosophy**](./philosophy.md) gives a quick overview of the different aspects of GraphQL clients and `urql` in-- [**Stream Pattern**](./stream-patterns.md) explains the inner working of `urql`, which is _stream-based_, also known as-- [**Exchanges**](./exchanges.md) finally introduces _Exchanges_ and how to write extensions or addons and use them-Caching"](../graphcache/normalized-caching.md). It's advisable to read this chapter before moving on
···
+2
-2
docs/concepts/document-caching.md
docs/basics/document-caching.md
+2
-2
docs/concepts/document-caching.md
docs/basics/document-caching.md
······The default _document caching_ logic is implemented in the default `cacheExchange`. We'll learn more
······The default _document caching_ logic is implemented in the default `cacheExchange`. We'll learn more
+1
-1
docs/concepts/errors.md
docs/basics/errors.md
+1
-1
docs/concepts/errors.md
docs/basics/errors.md
-111
docs/concepts/philosophy.md
-111
docs/concepts/philosophy.md
···-`urql` is a highly customizable and flexible GraphQL client, that happens to come with some default-configuration. `urql` is designed to be a client that grows with you. As you go from building your first-GraphQL app to a utilising the full functionality, the tools are available to extend and customize `urql` based on-In this guide, we will walk through how `urql` is set up internally and how all pieces of the puzzle-In `urql`, the client is the first step towards managing the complexity of GraphQL automatically.-You may have worked with a GraphQL API previously and noticed that using GraphQL in your app can be-In the following sections we'll talk about how `urql` solves these three problems, and how this is-This all happens in the background, allowing you to simply declare that you'd like to have data for a given-When we use GraphQL queries and mutations declaratively with `urql`, we expect them to interact-Furthermore, when we've already received the results from a query, we may not wish to send another request. To solve this, results can be cached in-memory and notifications can be sent to other parts of an app when the results change or-cache the results of queries automatically. In `urql` the `Client` can be extended with several-cache implementations; all of them allow you to prevent mixing your declarative query or mutation-[how you may store data in Redux.](https://redux.js.org/recipes/structuring-reducers/normalizing-state-shape/)-Using this approach the cache uses more type information to reference parts of the GraphQL only once-in the cache and structures it in a graph, which leads to more shared data, and hence more shared-With any kind of API there can be concerns outside of caching and state management. For example,-the global behavior or business logic of your application. For instance, you may want to add authentication, retry-logic for failed requests, or a global-`urql` introduces the concept of _Exchanges_ in order to abstract the details of how the `Client` interacts with-[middleware in Redux](https://redux.js.org/advanced/middleware) and have access to all operations-streams of operations and results allow us to implement complex behaviour in addition to allowing deep customisation over how the operations/results are handled. We'll learn more about this in the next section - [the Core Package](./core-package.md).
···
-120
docs/concepts/stream-patterns.md
-120
docs/concepts/stream-patterns.md
···-As we've learned in the previous section on [philosophy](./philosophy.md), `urql`'s main way of handling GraphQL requests-Internally the `Client` is an event hub. It defines a stream of operations as inputs, sends them-through a layer that will ultimately send GraphQL requests to an API, and then send the corresponding results-As a user working with framework code we never interact with these streams directly, but it's helpful to know that they describe-every interaction between the declarative queries we write and the way that `urql` fulfills them.-Generally we refer to _streams_ as abstractions that allow us to program with asynchronous streams of-and [Reactive Programming with Observables.](http://reactivex.io/documentation/observable.html)-These concepts can be quite intimidating, if you're new to them, but from a high-level view what-methods on arrays, so you're likely to see `map` and `filter` — amongst other utilities — in those-In Wonka, like with Observables, streams are cancellable by calling the `unsubscribe` method that a-convenience wrappers around `executeRequestOperation` that create an operation and return a stream.-There are also convenience wrappers around the "execute" methods that are useful when using `urql`-All methods on the `Client` internally emit an operation on an "operations stream" and the result
···
+3
-3
docs/graphcache/README.md
+3
-3
docs/graphcache/README.md
···-In `urql`, caching is fully configurable via [_Exchanges_](../concepts/exchanges.md) and the default-`cacheExchange` in `urql` offers a ["Document Cache"](../concepts/document-caching.md), which is···The following pages introduce different features in _Graphcache_ which together make it a compelling-alternative to the standard [document cache](../concepts/document-caching.md) that `urql` uses by- 🔁 [**Fully reactive, normalized caching.**](./normalized-caching.md) _Graphcache_ stores data in
······The following pages introduce different features in _Graphcache_ which together make it a compelling+alternative to the standard [document cache](../basics/document-caching.md) that `urql` uses by- 🔁 [**Fully reactive, normalized caching.**](./normalized-caching.md) _Graphcache_ stores data in
+1
-1
docs/graphcache/offline.md
+1
-1
docs/graphcache/offline.md
···offline error — the `offlineExchange` won't deliver the error for this query to avoid it from beingAwareness"](./schema-awareness.md) which will deliver as much of a partial query result as possible.-In combination with the [`cache-and-network` request policy](../concepts/document-caching.md#request-policies)
···offline error — the `offlineExchange` won't deliver the error for this query to avoid it from beingAwareness"](./schema-awareness.md) which will deliver as much of a partial query result as possible.+In combination with the [`cache-and-network` request policy](../basics/document-caching.md#request-policies)
+24
-4
packages/site/static.config.js
+24
-4
packages/site/static.config.js
······
······