The easiest way to consume GraphQL APIs in Svelte3
<script>
import { Out, query, setupClient } from 'svql';
setupClient({
url: 'https://graphql-pokemon.now.sh/graphql',
});
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>
How it works?
svql
use a fetchql singleton to talk with GraphQL, configure it through the setupClient()
method.
Both query
and mutation
helpers will take the GQL and returns 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}
and such,data
is optional the same ascallback
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 above, or by watching the returned promises, e.g.
<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, e.g.
<script>
// ...imports
export let name = '';
$: query(GET_POKEMON_INFO, { name });
</script>
So each time name
changes the query is executed again.
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 make more work, so you need to be sure and commit
once you're ready for the actual request, e.g.
<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.
Components
You can access svql
stores as conn
and state
respectively, however is better to use the following components to deal with.
<Failure {label} {error} />
This component is used to format captured errors from {:catch}
blocks.
Available props:
-
{label}
โ Title used for the failure message -
{error}
โ Error object or array of errors to display
<Status {from} {label} {pending} {otherwise} />
It takes a from={promise}
value and then render its progress, catch 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 atleft:0;bottom:0
by default -
{pending}
โ Message while the promise is being resolved... -
{otherwise}
โ Message while once promise has resolved successfully
With
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 receiveslet:result
-
exception
โ Replace the{:catch}
block, default is<Failure />
; it receiveslet: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}
โ Its presence disables the<Status />
render -
{loading}
โ Message while the promise is being resolved... -
{...}
โ Same props from<Status />
-
let:data
โ Unbounddata
inside
Available 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 receiveslet:result
-
failure
โ Replace the{:catch}
block, default is<Failure />
; it receiveslet:error
<In {id} {class|className} {modal} {autofocus} />
It is a <form />
wrapper that handle various effects:
- Subscribes to the GraphQL connection status and block its content while loading...
- When rendered as a modal-overlay it can be canceled with the
ESC
key or clicking outside - It can setup
autofocus
on the first input-element found inside the inner<form />
wrapper (js only)
Available props:
-
{id}
โ Usedid
for the inner<form />
element -
{class|className}
โ Usedclass
for the inner<form />
element -
{modal}
โ Its presence will render the inner<form />
in a modal-overlay -
{autofocus}
&mdasg; Its presence enablesfocus()
on the first input-element found
Public API
-
setupClient(options[, key])
โ Configure aFetchQL
singleton with the givenoptions
,key
is used for session loading -
useClient(options[, key])
โ Returns aFetchQL
instance with the givenoptions
,key
is used for session loading -
useToken(value[, key])
โ Update the session-token used for Bearer authentication,key
is used for session loading -
saveSession(data[, key])
โ Serializes any given value as the current session, it MUST be a plain object or null -
read(gql|key)
โ Retrieve current value fromstate
by key, a shorthand for$state[key]
values -
key(gql)
โ Returns a validkey
from GQL-strings, otherwise the same value is returned -
$state
โ Store with all resolved state by thefetchql
singleton -
$conn
โ Store with connection details duringfetchql
requests
sqvl
use Bearer authentication by default, so any token found in the session will be sent forth-and-back.