Important: This documentation covers Yarn 1 (Classic).
For Yarn 2+ docs and migration guide, see yarnpkg.com.

Package detail

@villus/batch

logaretm2.6kMIT3.5.2TypeScript support: included

Batch queries plugin for villus graphql client

VueJS, Vue, batch, graphql, api

readme

villus

Villus is a finger-like structures in the small intestine. They help to absorb digested food.

A small and fast GraphQL client for **Vue.js**


You can also help this this project and my other projects by donating one time or by sponsoring.

Features

  • 📦 Minimal: Its all you need to query GQL APIs
  • 🦐 Tiny: Very small footprint
  • 🗄 Caching: Simple and convenient query caching by default
  • 👕 TypeScript: Written in Typescript and Supports GraphQL TS tooling
  • 🖇 Composable: Built for the Composition API
  • ⚡️ Suspense: Supports the <Suspense> API
  • 🔌 Plugins: Use existing plugins and create custom ones

Why use this

GraphQL is just a simple HTTP request. This library is meant to be a tiny client without all the bells and whistles attached to Apollo and its ecosystem which subsequently means it is faster across the board due to it's smaller bundle size and reduced overhead. villus offers simple strategies to cache and batch, dedup your GraphQL requests.

villus also supports file uploads and subscriptions without compromising bundle size through plugins.

If you are looking for a more full-featured client use vue-apollo, it has everything you need.

You can read more about it in the announcement post.

Documentation

You can find the documentation here

Quick Start

First install villus:

yarn add villus graphql

# or npm

npm install villus graphql --save

Or because villus is so simple, you can use it via CDN:

<!-- Import Vue 3 -->
<script src="https://unpkg.com/vue@3.0.2/dist/vue.global.js"></script>
<!-- Villus -->
<script src="https://unpkg.com/villus@latest/dist/villus.min.js"></script>

Usage

Configure the GraphQL client for your root component:

<script setup>
import { useClient } from 'villus';

useClient({
  url: 'http://localhost:3002/graphql',
});
</script>

Then you can use useQuery in any child component:

<template>
  <div>
    <div v-if="data">
      <pre>{{ data }}</pre>
    </div>
  </div>
</template>

<script setup>
import { useQuery } from 'villus';

const AllPosts = `
  query AllPosts {
    posts {
      title
    }
  }
`;

const { data } = useQuery({
  query: AllPosts,
});
</script>

villus makes frequent tasks such as re-fetching, caching, deduplication, mutations, and subscriptions a breeze. It has even built-in Suspense support with Vue 3! Consult the documentation for more use-cases and examples.

Compatibility

This library relies on the fetch web API to run queries, you can use unfetch (client-side) or node-fetch (server-side) to use as a polyfill.

This library is compatible with Vue 3.0+ or 2.7+

Examples

Live examples can be found here

License

MIT

changelog

Change Log

3.5.2

Patch Changes

  • 0851c7d: fix: useSubscription return types

3.5.1

Patch Changes

  • 056ffbd: fix: added unsubscribeOnUnmount option

3.5.0

Minor Changes

  • e5c9e85: feat: added on demand subscription model

Patch Changes

  • 8b02c12: fix(types): subscription forwarded should receive a string always
  • 5c9a789: feat: accept several options as RefOrGetter
  • b81eec6: fix: watch the query if it is a getter

3.4.0

Minor Changes

  • 56d1e18: feat: add support for gql.tada

3.3.0

Minor Changes

  • 877cb15: feat: add query data mapper

3.2.0

Minor Changes

  • 559556d: feat: expose normalize query and add batching exclusion filter

All notable changes to this project will be documented in this file. See Conventional Commits for commit guidelines.

3.1.0 (2023-04-04)

Features

  • support typed document strings (62e5c56)

3.0.0 (2023-03-20)

Features

  • added data and error hooks (8ba12ae)
  • added subscription initial data and isFetching (7edd698)
  • breaking: change the reducer signature in subscriptions (f7b3893)
  • expose hook handler types (3e16cdc)

2.2.1 (2023-03-09)

Bug Fixes

  • subscriptions enhancements (b88190b)

2.2.0 (2023-03-03)

Features

  • add onSuccess and onError hooks in useQuery function (151b928)
  • useQuery: add tests (2e3152a)

2.1.1 (2023-02-08)

Bug Fixes

2.1.0 (2022-12-30)

Features

  • added a mechanism to clear all cache closes #84 (c78dfd2)
  • added refetching tagged queries (18e04b9)
  • implement tag based eviction closes #147 (9139f7e)
  • write docs on clearing cache (4e8e156)

2.0.2 (2022-12-28)

Bug Fixes

  • types: ensure mutation data and error are nullable closes #182 (#183) (25b6e5c)

2.0.1 (2022-10-23)

Note: Version bump only for package villus

2.0.0 (2022-08-07)

Bug Fixes

  • handle internal injections for vue 2.7 (163242e)

Features

  • add waitFor (e1a5aee)
  • deprecate variable watching API in useQuery (cbeef72)
  • normalize the skip and pause behaviors (3ba3576)

1.2.5 (2022-07-31)

Note: Version bump only for package villus

1.2.4 (2022-07-11)

Features

  • export GQL response types (e1d75f5)

1.2.3 (2022-07-03)

Note: Version bump only for package villus

1.2.2 (2022-06-13)

Note: Version bump only for package villus

1.2.1 (2022-06-03)

Bug Fixes

  • ensure isFetching is false after a query was skipped (659820a)

1.2.0 (2022-05-30)

Bug Fixes

  • query variables import path (6a05aee)

Features

  • added query skip argument (9b0ba85)
  • allow lazy variables to be passed in to queries (980673b)

1.1.0 (2022-04-23)

Bug Fixes

Features

  • enable useQuery etc function outside of setup and outside component (#156) (14335b3)

1.0.1 (2021-11-06)

Note: Version bump only for package villus

1.0.0 (2021-10-18)

Features

1.0.0-rc.21 (2021-08-26)

Note: Version bump only for package villus

1.0.0-rc.20 (2021-08-07)

Note: Version bump only for package villus

1.0.0-rc.19 (2021-07-25)

Features

  • update the reactive result for cache-and-network policy closes #76 (23cd60b)

1.0.0-rc.18 (2021-06-29)

Bug Fixes

  • added TData to client execute variants closes #128 (80426e2)

1.0.0-rc.17 (2021-05-12)

Note: Version bump only for package villus

1.0.0-rc.16 (2021-04-15)

Note: Version bump only for package villus

1.0.0-rc.15 (2021-03-06)

Bug Fixes

1.0.0-rc.14 (2021-03-04)

Bug Fixes

  • handle multiple executions state integrity (43d936b)

1.0.0-rc.13 (2021-02-27)

Bug Fixes

  • ensure fetch recongizes partial error responses (6c0a6fa)

1.0.0-rc.12 (2021-02-16)

Bug Fixes

  • effect conditions for Query and Subscription components (20f6803)
  • ensure executeopts arg is optional (f3f4bca)
  • expose villus client symbol for testing (141bf97)
  • fetchonMounted typo (09c3de4)
  • handle non 200 error responses closes #49 (0950fa8)
  • only resubscribe if the query/vars change closes #94 (739b75e)
  • prevent running the query onMounted when suspended closes #56 (27385b6)
  • remove invalid import (3bfdaf7)
  • safe access to the provides property (73efd25)
  • type import path (9c7c12c)
  • type the patched useResult (31fe56b)
  • typing of operation in fetch plugin (2dc8173)
  • use QueryVariables as default type for subscription forwarder #93 (3791251)
  • use standard execution result for subscription forwarder closes #93 (9ced480)

Features

  • add install method to client (#83) (397bbdb)
  • added context per query basis closes #96 (8248b06)
  • added dedup test (8b12141)
  • allow adding other hash items to the query key helper (5d18e8a)
  • avoid deduping mutations and subscriptions (3bb9642)
  • changed the signature of provider and useClient (b4fa6d9)
  • enhance suspense query suspense API and allow override query vars (c38e574)
  • export plugins types (598a65f)
  • expose getQueryKey helper (26548d5)
  • expose new definePlugin type helper (6f79a97)
  • implement dedup plugin (eb0f0a3)
  • implement response context closes #62 (04cae29)
  • initial isFetching (#74) (ea043da)
  • re-execute subscriptions closes #79 (0ec4680)
  • re-implement subscriptions as a plugin (e5e790a)
  • remove initialIsFetching and sync it with fetchOnMount (a1e75c4)
  • rename lazy to fetchOnMount (68b937e)
  • rename pause and resume for queries to be more explicit (ca9cf1e)
  • rename pause prop to paused and watch its effect (fca32d4)
  • rename suspend prop to suspended for consistency (06eaecd)
  • support typed document node (9c166f6)
  • updated graphql dep closes #65 (ef4be0a)
  • upgrade Vue and provide a workaround for #72 (6127f37)
  • breaking: signature updates (#70) (47937e8)
  • updated query component prop names (d0fc40d)
  • use defineComponent helper with subscription (ef7c16a)
  • use the defineComponent helper with Mutation component (eb72067)
  • use the defineComponent helper with Query component and omit redudencies (d00e25b)

1.0.0-rc.11 (2021-01-20)

Bug Fixes

  • only resubscribe if the query/vars change closes #94 (739b75e)
  • use QueryVariables as default type for subscription forwarder #93 (3791251)
  • use standard execution result for subscription forwarder closes #93 (9ced480)

1.0.0-rc.10 (2021-01-17)

Bug Fixes

  • ensure executeopts arg is optional (f3f4bca)

1.0.0-rc.9 (2021-01-15)

Features

  • enhance suspense query suspense API and allow override query vars (c38e574)

1.0.0-rc.8 (2021-01-05)

Bug Fixes

  • expose villus client symbol for testing (141bf97)

1.0.0-rc.7 (2021-01-02)

Features

  • remove initialIsFetching and sync it with fetchOnMount (a1e75c4)

1.0.0-rc.6 (2020-11-26)

Features

1.0.0-rc.5 (2020-11-25)

Bug Fixes

Features

  • allow adding other hash items to the query key helper (5d18e8a)
  • expose getQueryKey helper (26548d5)
  • re-execute subscriptions closes #79 (0ec4680)

1.0.0-rc.4 (2020-11-01)

Features

  • expose new definePlugin type helper (6f79a97)

1.0.0-rc.3 (2020-10-28)

Features

1.0.0-rc.2 (2020-10-27)

Bug Fixes

  • safe access to the provides property (73efd25)

1.0.0-rc.1 (2020-10-26)

Features

  • upgrade Vue and provide a workaround for #72 (6127f37)

1.0.0-rc.0 (2020-10-22)

Features

1.0.0-beta.8 (2020-10-21)

Bug Fixes

Features

1.0.0-beta.7 (2020-10-19)

Bug Fixes

  • typing of operation in fetch plugin (2dc8173)

Features

  • support typed document node (9c166f6)

1.0.0-beta.6 (2020-10-09)

Bug Fixes

  • prevent running the query onMounted when suspended closes #56 (27385b6)

1.0.0-beta.5 (2020-10-09)

Bug Fixes

1.0.0-beta.4 (2020-10-07)

Bug Fixes

  • effect conditions for Query and Subscription components (20f6803)

Features

  • re-implement subscriptions as a plugin (e5e790a)
  • rename lazy to fetchOnMount (68b937e)
  • rename pause and resume for queries to be more explicit (ca9cf1e)
  • rename pause prop to paused and watch its effect (fca32d4)
  • rename suspend prop to suspended for consistency (06eaecd)
  • updated query component prop names (d0fc40d)
  • use defineComponent helper with subscription (ef7c16a)
  • use the defineComponent helper with Mutation component (eb72067)
  • use the defineComponent helper with Query component and omit redudencies (d00e25b)

1.0.0-beta.3 (2020-10-05)

Note: Version bump only for package villus

1.0.0-beta.2 (2020-10-02)

Note: Version bump only for package villus

1.0.0-beta.1 (2020-09-30)

Breaking Changes

  • deprecate the context and fetch options in favor of custom plugins API
  • deprecate the exported batch fetcher in favor of @villus/batch plugin
  • changed the signature of provider and useClient (b4fa6d9) due to conflicts with TypeScript typings

Bug Fixes

  • handle non 200 error responses closes #49 (0950fa8)

Features

Plugins API

A large chunk of villus code has been re-written from scratch to use a pipeline-like operation transformers (plugins) similair to what apollo client and urql are doing with much less jargon and complexity, they are just a simple middleware performing operations on GraphQL queries as they go out or after execution.

Check the documentation here

multipart plugin

The multipart plugin will enable support for graphql file upload, check the documentation and examples here