@urql/svelte 1.0

[kitten]

We've just made the step of resolving #1007. This means that we've reimplemented our @urql/svelte bindings and have released them as v1.0.0. This is a big step for us in providing stable bindings for Svelte.

While previous releases have tried varying different approaches and API designs. This time around we've taken all these learnings, resolved the bugs we've had before, and built an API that steers you towards the idiomatic and correct usage of the API.

So, what's new and how does it work?

All results and inputs to an urql Operation are now abstracted by the operationStore. This is simply a reactive primitive that will hold all values for the query and for the query's result. This may look very similar to a derived API, but it instead allows us to instruct Svelte to run all execution logic separately.

You may create an operationStore like so:

const todos = operationStore(`
  query {
    todos {
      id
      title
    }
  }
`);

This is the shortest way to instantiate an operationStore. You can reactively update this store. It's just a Svelte writeable!

$todos.variables = { /* ... */ };

However, not all logic will always live in components, so you can also directly update it:

// Note the missing dollar sign:
todos.variables = { /* ... */ };

The actual query may be started separately using the query call, which must be synchronous and will automatically attach an unsubscribe cleanup callback to onDestroy in the Svelte component.

The query may then update todos.data, todos.error, todos.fetching and all the other fields automatically.

How do I get started?

We've written extensive new docs to signal how to use this new API:

• Getting Started
• Queries
• Mutations
• Subscriptions
• API Docs

Hope y'all Svelters enjoy this release! And please do let us know how you get on with this API! 🙏

[ispyinternet]

I have a question! The mutation api, allows you to pass the operationStore or the query string - in the latter it will create the operationStore for you. What's stopping the query api from working in the same way?

<script>
  import gql from 'graphql-tag';
  import {  query } from '@urql/svelte';

 // returns the operation store and runs the query in 1 hit
  const todos = query(gql`
    query ($first: Int!, $skip: Int) {
      todos(first: $first, skip: $skip) {
        id
      }
    }
  `, { first: 10 }); 

[kitten]

It's not that simple; a more direct API would destroy the data whenever you change the inputs. The store being separate allows us to preserve data across updates and input changes.
Mutation is not any different, except that often mutation data is used as a one off; so we can create the store internally optionally.

Now why do the other APIs not do this? Because if we create the store internally it'd be very tempting to do query($todosQuery, $variables) and the likes. That means that we have to derive the output state which is asynchronous, but when these variables change query gets called again and destroys the previous state, which means that flags like stale and previous data accesses become impossible, which is bad for pagination and other cases.

So long story short, if you check out our previous implementations you can see how this can quickly go wrong. In your implementation from the other thread how you've basically worked around this is by binding inputs separately, which is actually extremely similar to what we're doing now, and instead only sets the "boundary" between store state and reactive updates in a different place.

[ispyinternet]

I feel like I still don't know the answer 😂

In your implementation from the other thread how you've basically worked around this is by binding inputs separately, which is actually extremely similar to what we're doing now, and instead only sets the "boundary" between store state and reactive updates in a different place.

Does that mean it can be or can't or shouldn't be done!?

Anyway, not to labour this any longer, I'm pretty happy so long as it works (optimally) - api isn't that painful 😁

[kitten]

So it can be done, and arguably it could be fine, but mostly it leads to confusion as far as I've seen 😅

[frederikhors]

@ispyinternet You can also use this oneliner:

const user = query(operationStore(USER_QUERY));

[Manborough]

Awesome work on the new api (and fast too). I'm starting to change over my app to use it.

I've got a couple of problems that I'm not sure how to solve.

One is pausing the query, which is supported in the React examples for this reason.

In some cases we may want useQuery to execute a query when a pre-condition has been met, 
and not execute the query otherwise. For instance, we may be building a form and want a 
validation query to only take place when a field has been filled out.

I'm not currently looking to do anything like this, but I figure it could come up at some point.

and the other is checking auth when routing between pages. I have an async function to check auth which awaits on a promise to return before redirecting. Not sure how to do that with the operationStore and Query. Any suggestions?

[kitten]

ohhhhhh yes, I forgot to add pausing 😅

[randyridge]

Upgrading from 0.4.0 to 1 it looks like typing has changed. It feels weird to me that data, error, etc are typed with a | void. Often I pass a graphql codegen type around and rather than having data? I get data? | void so I'm potentially passing void around which seems non-sensical to me...? It's not typed like this in, for instance, the react lib. Am I missing something?

[kitten]

It is actually typed like this in React https://github.com/FormidableLabs/urql/blob/2527996491103e5ce17328071e67583f5b498c70/packages/react-urql/src/hooks/useQuery.ts#L28
Except that we mark these fields as data?: T for instance, which means that we're basically loosening this guarantee in other bindings even more in that the field may not be set at all (which it always is, but it changes how TS treats it)
In Svelte we explicitly say | void to say that the field will always at least be set, since we rely on that in the implementation of the operationStore. However, this is just a minor detail.

[randyridge]

I still feel like I'm missing something (or dumb).

// HomeScreenQuery generated by graphql codegen urql
const homeScreenQuery = operationStore<HomeScreenQuery>(HomeScreenDocument);
query(homeScreenQuery);

{#if $homeScreenQuery.fetching}
	<SpinnerScreen />
{:else if $homeScreenQuery.error}
         // truthy error
	<ErrorScreen error={$homeScreenQuery.error} /> // Now in ErrorScreen I have to type prop error as void | CombinedError
{:else if $homeScreenQuery.data}
         // truthy data
	<HomeScreen data={$homeScreenQuery.data} /> // Now in HomeScreen data has to be typed void | HomeScreenQuery
{/if}

In either case in ErrorScreen or HomeScreen the prop will never be void, but I have to type it as though it were possible...

[kitten]

It can actually be null | void. It may be null when an error erases all possible results from the API, and it may be void when a network error occurs, or it may also become null when the cache has no match but the requestPolicy is set to cache-only. So while you know that it shouldn't happen, they're still possible states.

[robhicks]

I'm newish to svelte and urql.

I'm struggling with the svelte api for subscriptions. I have followed the documentation on configuring the client using @urql/svelte for subscriptions. I can see the web socket connection to the server and the only subscription I have added:

{
  "id": "f635e52b-0d56-4513-8067-563ab2f3903e",
  "type": "subscribe",
  "payload": {
    "key": "1h05np4",
    "query": "subscription {\n  postAdded {\n    author {\n      avatar\n      name\n      username\n    }\n    channel {\n      _id\n    }\n    content\n    updated\n  }\n}\n",
    "variables": {
      "channelId": "6048ae93d145dde8a7ed7463"
    },
    "context": {
      "url": "http://localhost:3001/graphql",
      "fetchOptions": {
        "headers": {
          "Authorization": "Bearer {token}"
        }
      },
      "preferGetMethod": false,
      "suspense": false,
      "requestPolicy": "cache-first",
      "meta": {
        "cacheOutcome": "miss"
      },
      "authAttempt": false
    }
  }
}

I have added 2 operationStore(s), one as a query and one as a subscription. The docs are a little confusing on this point. Should I add one for the query and one for the subscription? Without the query, I get nothing returned from the server. Additionally, with or without the query, the subscription handler never gets called.

const postAdded = operationStore(
  `subscription{
    postAdded{
      author {
        avatar
        name
        username
      }
      channel {
        _id
      }
      content
      updated
    }
  }`,
  { channelId: params.id }
);

subscription(postAdded, (previous = [], data) => {
  console.log(`subscription::previous`, previous);
  console.log(`subscription::data`, data);
});

Is there a full example of how to do a subscription, displaying not only changed data but existing data?

Thanks!

[michaljanocko]

Hi, I'm a big fan of Svelte and Urql. Now that SvelteKit is the new big thing, I have to ask. How is the support of server-side rendering with urql?