The easiest way to consume GraphQL APIs in Svelte3
<script>
import { Out, query, setupClient } from 'svql';
setupClient({
url: 'https://graphql-pokemon2.vercel.app/',
});
const GET_POKEMON_INFO = `
query($name: String!) {
pokemon(name: $name) {
id name image number
}
}
`;
query(GET_POKEMON_INFO, { name: 'Pikachu' });
</script>
<Out nostatus from={GET_POKEMON_INFO} let:data>
<h3>{data.pokemon.number}. {data.pokemon.name}</h3>
<img alt={data.pokemon.name} src={data.pokemon.image} />
</Out>
svql
uses a fetchql singleton to talk to GraphQL. You can configure it through the setupClient()
method.
Both query
and mutation
helpers will take the GQL and return a promise (or function that returns a promise, respectively).
query(gql[, data[, callback]]): Promise
Queries are indexed so you can refer to them as
from={MY_GQL_QUERY}
.data
is optional, as is thecallback
function. Any truthy value returned by this callback will be used in-place of the regular response.
Accessing those values can be done through <Out />
components as shown above, or by watching the returned promises:
<script>
// ...imports
let promise = query(GET_POKEMON_INFO, { name: 'Bulbasaur' });
</script>
<!-- we can use {#await promise}...{/await} -->
Refetching of queries can be done through reactive statements:
<script>
// ...imports
export let name = '';
$: query(GET_POKEMON_INFO, { name });
</script>
Each time name
changes, the query re-executes.
mutation(gql[, callback]): Function
The callback will receive a
commit
function that accepts variables-input as first argument, and optionally a second function to handle the response. Values returned by this function are also promises.
Mutations are functions that could result in more work, so you need to be sure and commit
once you're ready for the actual request:
<script>
// ...imports
export let email = '';
let password;
let promise;
const doLogin = mutation(LOGIN_REQUEST, commit => function login() {
promise = commit({ email, password }, data => {
saveSession(data.login);
location.href = '/';
});
});
</script>
<p>Email: <input type="email" bind:value={email} /></p>
<p>Password: <input type="password" bind:value={password} /></p>
<button on:click={doLogin}>Log in</button>
Since mutation()
returns a function, there's no need to setup reactive statements to refetch it. Just calling the generated function is enough.
You can access svql
stores as conn
and state
respectively. However, it is better to use the following components to handle state. :sunglasses:
<Failure ... />
No longer shipped, use a separate Failure
component from smoo.
<Status {from} {label} {pending} {otherwise} />
This takes a from={promise}
value, then renders its progress, catches the failure, etc.
Available props:
{from}
— Promise-like value to handle status changes{label}
— Label used for {:catch error}
handling with <Failure />
{fixed}
— Setup <Status />
container as fixed, positioned at left:0;bottom:0
by default{pending}
— Message while the promise is being resolved...{otherwise}
— Message while once promise has resolved successfullyWith
fixed
you can provide offsets, e.g.<Status fixed="{{ top: '10vh' }}" />
Available slots:
pending
— Replace the {:await}
block, default is an <h3 />
otherwise
— Replace the {:then}
block, default is an <h3 />
; it receives let:result
exception
— Replace the {:catch}
block, default is <Failure />
; it receives let:error
<Out {nostatus} {loading} {...} let:data />
Use this component to access data from={promise}
inside, or from={GQL}
to extract it from resolved state.
Available props:
{nostatus}
— Boolean; its presence disables the <Status />
render{loading}
— Message while the promise is being resolved...{...}
— Same props from <Status />
let:data
— Unbound data
insideAvailable slots:
status
— Replaces the <Status />
render with custom markup; it receives the same props as <Status />
loading
— Replace the {:then}
block, default is an <h3 />
; it receives let:result
failure
— Replace the {:catch}
block, default is <Failure />
; it receives let:error
<In ... />
No longer shipped, use a separate Fence
component from smoo.
Loading states should be bound as
<Fence loading={$conn.loading}>...</Fence>
to properly block the UI.
setupClient(options[, key])
— Configure a FetchQL
singleton with the given options
, key
is used for session loadinguseClient(options[, key])
— Returns a FetchQL
instance with the given options
, key
is used for session loadinguseToken(value[, key])
— Update the session-token used for Bearer authentication, key
is used for session loadingsaveSession(data[, key])
— Serializes any given value as the current session, it MUST be a plain object or nullread(gql|key)
— Retrieve current value from state
by key, a shorthand for $state[key]
valueskey(gql)
— Returns a valid key
from GQL-strings, otherwise the same value is returned$state
— Store with all resolved state by the fetchql
singleton$conn
— Store with connection details during fetchql
requests
sqvl
use Bearer authentication by default, so any token found in the session will be sent forth-and-back.
If you want to change your client's authorization token, you may call client.setToken()
— or useToken()
globally.