kitten.sh
+4
-5
docs/README.md
+4
-5
docs/README.md
···As you're adopting GraphQL, `urql` becomes your primary data layer and can handle content-heavy-pages through ["Document Caching"](./concepts/document-caching.md) as well as dynamic and data-heavy+pages through ["Document Caching"](./basics/document-caching.md) as well as dynamic and data-heavy···of `urql` with most of its logic. As we progress with implementing `urql` into our application,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+- **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.+- [**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`+[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)+`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](../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.+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
+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 usingframework bindings, you'll likely want to import from your framework bindings package directly.······| `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)+[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.](../concepts/document-caching.md). It's of type `Exchange`.+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+After reading the page for your bindings and the "Core" page you may want to the next two pages in-- [**Document Caching**](../concepts/document-caching.md) explains the default cache mechanism of `urql`, as opposed to the opt-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 framework+[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
+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 eitherthe request to the API has failed or when our API result contained some `GraphQLError`s, which···Request policies aren't specific to `urql`'s React API, but are a common feature in its core. [Youcan learn more about how the cache behaves given the four different policies on the "Document······which is the same between all framework bindings. Hence, next we may want to learn more about one of
+6
-6
docs/basics/svelte.md
+6
-6
docs/basics/svelte.md
······This "Getting Started" guide covers how to install and set up `urql` and provide a `Client` for···If you're checking for errors, you should use `operationStore.error` instead, which will be set···which is the same between all framework bindings. Hence, next we may want to learn more about one of
+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 eitherthe request to the API has failed or when our API result contained some `GraphQLError`s, which······which is the same between all framework bindings. Hence, next we may want to learn more about one of
-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
+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 issufficient for sites that heavily rely and render static content. However as an app grows morecomplex it's likely that the data and state that `urql` manages, will also grow more complex and···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+alternative to the standard [document cache](../basics/document-caching.md) that `urql` uses by
+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)+In combination with the [`cache-and-network` request policy](../basics/document-caching.md#request-policies)we can now ensure that we display as much data as possible when the user is offline while still
+24
-4
packages/site/static.config.js
+24
-4
packages/site/static.config.js
······