Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/pateketrueke/svql
FetchQL wrapper for Svelte 3
https://github.com/pateketrueke/svql
Last synced: about 2 months ago
JSON representation
FetchQL wrapper for Svelte 3
- Host: GitHub
- URL: https://github.com/pateketrueke/svql
- Owner: pateketrueke
- Created: 2019-06-04T04:34:47.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2023-03-04T03:53:48.000Z (almost 2 years ago)
- Last Synced: 2024-10-24T20:15:49.839Z (2 months ago)
- Language: JavaScript
- Homepage: https://svelte.dev/repl/57ede36346454489b0f1c57248ee4eb9?version=3.4.4
- Size: 1.57 MB
- Stars: 61
- Watchers: 5
- Forks: 0
- Open Issues: 6
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
> The _easiest_ way to consume GraphQL APIs in Svelte3
>
> 
> [](http://badge.fury.io/js/svql)
> [](https://snyk.io/test/npm/svql)
```html
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' });
{data.pokemon.number}. {data.pokemon.name}
```
## How it works.
`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 the `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 `` components as shown above, or by watching the returned promises:
```html
// ...imports
let promise = query(GET_POKEMON_INFO, { name: 'Bulbasaur' });
```
Refetching of queries can be done through reactive statements:
```html
// ...imports
export let name = '';
$: query(GET_POKEMON_INFO, { name });
```
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:
```html
// ...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 = '/';
});
});
Email:
Password:
Log in
```
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, it is better to use the following components to handle state. :sunglasses:
### ``
No longer shipped, use a separate `Failure` component from [smoo](https://github.com/pateketrueke/smoo).
### ``
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 ``
- `{fixed}` — Setup `` 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. ``
Available slots:
- `pending` — Replace the `{:await}` block, default is an `
`
- `otherwise` — Replace the `{:then}` block, default is an ``; it receives `let:result`
- `exception` — Replace the `{:catch}` block, default is ``; it receives `let:error`
### ``
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 `` render
- `{loading}` — Message while the promise is being resolved...
- `{...}` — Same props from ``
- `let:data` — Unbound `data` inside
Available slots:
- `status` — Replaces the `` render with custom markup; it receives the same props as ``
- `loading` — Replace the `{:then}` block, default is an `
`; it receives `let:result`
- `failure` — Replace the `{:catch}` block, default is ``; it receives `let:error`
### ``
No longer shipped, use a separate `Fence` component from [smoo](https://github.com/pateketrueke/smoo).
> Loading states should be bound as `...` to properly block the UI.
## 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.
If you want to change your client's authorization token, you may call `client.setToken()` — or `useToken()` globally.