npm

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 as callback 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} {format} {noformat} {nodebug} />

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
• {format} — Custom function for formatting, receives each error
• {nodebug} — Boolean; if present, print more details, otherwise format by default
• {noformat} — Boolean; if present, disable format completely when {nodebug} is missing

<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 at left: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 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 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 receives let:result
• failure — Replace the {:catch} block, default is <Failure />; it receives let:error

<In {id} {class} {modal} {visible} {autofocus} on:submit on:cancel />

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)

Before submitting HTML5 validation will run, if it's valid a submit event will be triggered. The cancel event is fired when you click outside the modal, or press the ESC key to close the modal.

Available props:

• {id} — Used id for the inner <form /> element
• {class} — Used class for the inner <form /> element
• {modal} — Its presence will render the inner <form /> in a modal-overlay
• {visible} — Its value is used to toggle the render of the entire custom-element
• {autofocus} &mdasg; Its presence enables focus() on the first input-element found

Add the nofocus or data-nofocus attribute to any element to skip autofocus on it, useful for close-icons, etc.

Public API

• setupClient(options[, key]) — Configure a FetchQL singleton with the given options, key is used for session loading
• useClient(options[, key]) — Returns a FetchQL instance with the given options, 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 from state by key, a shorthand for $state[key] values
• key(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.