Reference

HTTP client

Two layers: the directives, which cover most cases without a line of JavaScript, and the full client in V.http. The guide on fetching data teaches you to use it; this page lists everything.

Directive triggers

Each verb fires on the element's natural trigger:

v-trigger replaces the default:

<div v-get="/api/status" v-trigger="load">...</div>
<div v-get="/api/banner" v-trigger="visible">...</div>
<input v-get="/api/search" v-trigger="keyup" v-debounce="300">
<div v-get="/api/feed" v-trigger="visible.repeat">...</div>
<button v-get="/api/x" v-trigger="click.once">Only once</button>

Special triggers: load and ready fire on mount; visible and revealed fire when the element gets close to the screen. The modifiers accepted in the text are once and repeat.

v-target and v-swap

The inserted HTML is walked by Voodoo, so it can bring new directives with it.

Handling the response

Inside the template you have item (the whole object), index and every key of the object as a variable of its own.

v-search

v-resource

The syntax is name: url. With no name, the resource is called resource. It accepts v-method, v-params, v-cache, v-retry, v-timeout, v-json-path, v-poll and v-manual, which does not fetch on mount and waits for reload().

Loading, notifications and callbacks

During the request the element also gets aria-busy="true".

Network

Events

<div v-get="/api/x"
     @voodoo:before-request="console.log('going')"
     @voodoo:success="console.log($detail.data)"
     @voodoo:error="console.log($detail.message)"
     @voodoo:complete="console.log('done')">
</div>

The V.http client

const users   = await V.http.get('/api/users');
const created = await V.http.post('/api/users', { name: 'Ann' });
await V.http.put('/api/users/1', { name: 'Bea' });
await V.http.patch('/api/users/1', { active: false });
await V.http.delete('/api/users/1');
await V.http.head('/api/users');

The shortcuts return the data only. For the full response, use request:

const response = await V.http.request({ url: '/api/users', method: 'GET' });
response.data;
response.status;
response.headers.get('x-total');
response.ok;
response.raw;     // the original Response

Options

Body

Objects become JSON with the right header. FormData, Blob, URLSearchParams, ArrayBuffer and text pass through as they are.

Errors

try {
  await V.http.get('/api/x');
} catch (err) {
  if (err instanceof V.HttpError) {
    err.status;            // 0 when there was no response
    err.response?.data;    // the body of the error
    err.isNetworkError;    // true on network failure, timeout or cancellation
    err.config;            // the configuration used
  }
}

4xx errors are not retried. 5xx errors and network failures respect retry.

Interceptors

const off = V.http.interceptors.request.use((config) => {
  config.headers = { ...config.headers, 'X-Tenant': currentTenant() };
  return config;
});

V.http.interceptors.response.use((response) => response);

V.http.interceptors.error.use((error) => {
  if (error.status === 401) location.assign('/login');
});

off();  // removes the request interceptor

Interceptors can be asynchronous. The request one has to return the configuration, and the response one has to return the response.

Authentication and default headers

V.http.setBaseURL('https://api.example.com');
V.http.setToken('my-jwt');                   // Authorization: Bearer my-jwt
V.http.setToken('key', 'Token');             // Authorization: Token key
V.http.setToken(null);                       // removes it
V.http.setHeader('Accept-Language', 'en');
V.http.setHeader('Accept-Language', null);   // removes it

Every request already carries X-Requested-With: XMLHttpRequest. On methods that write, the CSRF token is read from <meta name="csrf-token"> and sent in X-CSRF-TOKEN. The names are configurable in V.http.defaults.csrfMeta and V.http.defaults.csrfHeader.

Upload with progress

const data = new FormData();
data.append('file', input.files[0]);

await V.http.upload('/api/files', data, {
  onProgress: (percent, sent, total) => {
    bar.style.width = percent + '%';
  }
});

It uses XMLHttpRequest underneath, because that is the only thing that reports real upload progress.

Server-Sent Events and streaming

const source = V.http.sse('/api/events', {
  message: (data) => console.log(data),
  error: (e) => console.warn('connection dropped', e)
});
source.close();

await V.http.stream('/api/logs', (line) => console.log(JSON.parse(line)));

In SSE, JSON is parsed automatically when possible. stream delivers line by line, which works well for NDJSON and long responses.

Cache

await V.http.get('/api/config', { cache: 300000 });
V.http.clearCache();                // clears everything
V.http.clearCache('/api/products'); // clears whatever contains the text
V.http.clearCache(/^GET \/api\//);  // clears by pattern

Offline queue

await V.http.post('/api/orders', order, { offlineQueue: true });
await V.http.flushOfflineQueue();   // forces the resend

Requests with offlineQueue: true fired while the browser is offline are stored in localStorage and sent again when the connection comes back. The immediate response is synthetic, with status: 0 and statusText: 'offline-queued', handle that case in the interface, or the user will think the operation is already finished.