villus

🆕 New Features

Added on demand subscription model (e5c9e85)

You can now manually subscribe and unsubscribe from a subscription using the subscribe and unsubscribe functions, and coupled with subscribeOnMount set to false you can now initiate the subscription only when needed rather than juggle paused and skip to achieve this.

const { subscribe, unsubscribe } = useSubscription({
   // ....
  subscribeOnMount: false
});

if (something) {
  subscribe();
}

Accept several options as RefOrGetter (5c9a789)

In multiple areas we were still accepting a Ref or a plain value, like with queries, contexts, etc...

Now you can pass getters as well, this makes villus utilize the MaybeGetterOrRef type from vue package and gives you more flexibility as you won't need to wrap those options with computed anymore.

🐛 Bug Fixes

• fix(types): subscription forwarded should receive a string always #210 (8b02c12)
• fix: watch the query if it is a getter in useQuery and useSubscription (b81eec6)

🪄 gql.tada support

This release brings full type support for gql.tada #206

import { graphql } from 'gql.tada';
import { useQuery } from 'villus';

const getBooksQuery = graphql(`
  query GetBooks {
    books {
      id
      title
    }
  }
`);

const { data, error } = useQuery({
  query: getBooksQuery
});

🆕 New Features

Added useQuery data mappers. Similar to subscriptions, you can now pass a second argument to useQuery to map the data and it will be fully typed.

const { data, error } = useQuery(
  {
    query: new TypedDocumentString<{ posts: Post[] }, never>(`
    query Posts {
      posts {
        id
        title
      }
    }
  `),
  },
  ({ data }) => {
    return data?.posts.map(p => p.id) || [];
  },
);

data.value;
//^ number[]

👕 TypeScript

• Exported mutation execution options type #203 thanks to @jbaubree

🆕 @villus/batch

You can now add an exclusion filter as config for the batch plugin to force specific queries to be executed in a non-batched request.

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

useClient({
  url: 'https://test.com/graphql',
  // Exclude all queries named "Posts"
  use: [batch({ exclude: ({ query }) => /query Posts/.test(query) })],
});
</script>

🆕 New features

• Exported normalizeQuery helper that converts a query (string, or a document object) to a string.
• New onData and onError for the useMutation composable if you prefer to use callback style for handling, thanks to @jbaubree (#197)

🆕 New features

• Added support for TypedDocumentString introduced with GraphQL codegenrator ecosystem

💣 Breaking Changes

This release contains minor breaking changes, mainly subscriptions reducer arguments order being flipped and onSuccess hook being renamed.

You can read how to migrate by checking this guide.

🆕 New features

• Added isFetching to useSubscription until the first data event is received.
• Added initialData to useSubscription options to provide an initial data.
• Subscription forwarder can now be asynchronous.
• Added onData and onError hooks on the return type of useQuery, so you can register multiple hooks anytime. Read more here.

🐛 Bug Fixes

• Fixed a few issues with re-subscribing due to variable changes (b88190b8528d6d9dfd7aad7514647cce6f2b4bff)

🆕 Enhancements

• Added skip to useSubscription to unsubscribe or wait until some conditions are met before subscribing (b88190b8528d6d9dfd7aad7514647cce6f2b4bff)
• Allow the subscription forwarder to be async

🆕 New features

Thanks to @jbaubree for suggesting implementing event hooks, which is a little nicer than using a watcher for detecting when a query concludes or fails.

onSuccess

This is called whenever a new result is available.

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

const { data } = useQuery({
  query: GetPostById,
  variables,
  onSuccess: (data) => {
    console.log(data)
  },
});
</script>

onError

It is triggered when an error occurs.

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

const { data } = useQuery({
  query: GetPostById,
  variables,
  onError: (err) => {
    console.log(err)
  },
});
</script>

🐛 Bugs Fixed

• Subscription forwarder not receiving a nomralized query string (7a502495c17b8b34dc6edd6ecc5fc5620bb279c0) #188

👕 TypeScript

• Changed the internal ObserverLike interface to require next and error and complete functions. This makes it more compatible with graphql-ws sink type which is the recommended WebSocket implementation (0c91f11d44da84195636327f908a265769d72cb6) #154 #186

A couple of nice features to help with the caching and fetching logic of mutations and queries. As always, feedback is welcome and make sure to report any bugs you encounter.

🆕 New Features

Added the ability to tag queries using the tags option when calling useQuery. This marks a query with the specified tags for a couple of features.

Clearing tagged queries cache after mutation

const { data } = useQuery(GetPosts, {
  tags: ['all_posts'],
});

// This will clear the previous query cache whenever `execute` concludes successfully.
const { execute } = useMutation(CreatePost, {
  clearCacheTags: ['all_posts'],
});

Refetching tagged queries cache after mutation

const { data } = useQuery(GetPosts, {
  tags: ['all_posts'],
});

// This will auto-fetch the previous query whenever `execute` concludes successfully.
const { execute } = useMutation(CreatePost, {
  refetchTags: ['all_posts'],
});

This refetching bypasses the cache so it will also clear the affected queries cache as well, so there is some overlap between clearing and autofetching.

👕 TypeScript

• Fixed a couple of typing issues with useMutation and its execute() where the data and error values returned were not nullable #182 (#183)

⚙️ Misc

• Exposed several network utilities to make creating fetch plugins easier, the exposed functions are mergeFetchOptions, makeFetchOptions and parseResponse #163 (47348e197b6b8edd3511f3a95b0960160f4a6ffc)

A new major release of villus with Vue 2.7 support and API improvements.

Vue 2.7 Support 🎉

Villus now supports Vue 2.7+ releases, so go ahead and try it out in your Vue 2.7 projects!

💀 Breaking Changes

Dropping higher-order components

Villus is now strictly a composition API library, the higher-order components were dropped in favor of a lighter footprint and compatibility with Vue 2.7 due to differences in VDOM API.

The Higher-order components API was mostly around for compatibility purposes and wasn't documented properly to encourage using the composition API.

Pausing Queries/Subscriptions

The API for stopping auto-refetch behaviors was changed. Instead of having explicit resume and pause functions you could pass a boolean, function that returns a boolean or a boolean ref.

Here are a few examples of how that works now:

const { data } = useQuery({
  query: GetPostById,
  variables,
  // Don't re-fetch automatically unless the id is present
  paused: ({ id }) => !id,
})

const { data, execute } = useQuery({
  query: GetPostById,
  variables,
  // This query is now "lazy" and you have to trigger executions manually with `execute`.
  paused: true,
});

The docs offer more examples and use cases for this API.

Aside from that, it also offers a clear distinction from the recently introduced skipped queries.

🐛 Bug Fixes

• Fixed an issue with batch plugin dropping some fetch options set by previous plugins #166 (#167) thanks to @DaLukasTI

👕 TypeScript

• Exposed GraphQLResponse and ParsedResponse types.

🆕 New Features

• Added maxOperationCount option to the batch plugin to allow fine control over how many queries can be executed in a batch. Docs

🐛 Bug Fixes

• Fixed calling query.unwatchVariables() can error out if variables are not watched by default (#164) thanks to @callumacrae

🐛 Bug Fixes

• Fixed not being able to resolve global fetch when in worker context #160 (#161) thanks to @bravik

🐛 Bug Fixes

• Fixed isFetching not being set to false if the query was skipped via skip option.

🆕 New Features

• Added skip option to useQuery which prevents executing queries if it is evaluated to true.

const route = useRoute();

// skip fetching if route param `id` does not exist
const shouldSkip = computed(() => {
  return !route.params.id
});

const { data, isFetching } = useQuery({
  // pass as ref ...
  skip: shouldSkip,
});


// pass as a function, which rescives the current variables as an argument
const { data, isFetching } = useQuery({
  // ...,
  skip: (variables) => {
    return !variables.id;
  },
});

• useQuery variables option can now be a function that returns a variables object. This is mainly a DX improvement to avoid having to create computed properties to pass to useQuery.

const route = useRoute();

const { data, isFetching } = useQuery({
  variables: () => {
    return { id: route.params.id };
  },
});

👕 TypeScript

• fix: add export types for villus.d.ts by @GavinXue in https://github.com/logaretm/villus/pull/155

🆕 New Features

• feat: enable useQuery etc function outside of setup and outside component by @GavinXue in https://github.com/logaretm/villus/pull/156

This change will allow you to use useQuery and friends in a limited fashion outside the setup function. This should reduce the occurrences where a client instance cannot be found due to the inject/provide API caveats.