mobx-tanstack-query

MobX wrapper for Tanstack Query Core package

What package supports

Queries -> MobxQuery

Class wrapper for @tanstack-query/core queries with MobX reactivity

Usage

Create an instance of MobxQuery with queryKey and queryFn parameters

1const query = new MobxQuery({
2  queryClient,
3  abortSignal, // Helps you to automatically clean up query  
4  queryKey: ['pets'],
5  queryFn: async ({ signal, queryKey }) => {
6    const response = await petsApi.fetchPets({ signal });
7    return response.data;
8  },
9});  

Features

enableOnDemand option

Query will be disabled until you request result for this query
Example:

1const query = new MobxQuery({
2  //...
3  enableOnDemand: true
4});
5// happens nothing
6query.result.data; // from this code line query starts fetching data

dynamic options

Options which can be dynamically updated for this query

1const query = new MobxQuery({
2  // ...
3  options: () => ({
4    enabled: this.myObservableValue > 10,
5    queryKey: ['foo', 'bar', this.myObservableValue] as const,
6  }),
7  queryFn: ({ queryKey }) => {
8    const myObservableValue = queryKey[2];
9  }
10});

dynamic queryKey

Works the same as dynamic options option but only for queryKey

1const query = new MobxQuery({
2  // ...
3  queryKey: () => ['foo', 'bar', this.myObservableValue] as const,
4  queryFn: ({ queryKey }) => {
5    const myObservableValue = queryKey[2];
6  }
7});

P.S. you can combine it with dynamic (out of box) enabled property

1const query = new MobxQuery({
2  // ...
3  queryKey: () => ['foo', 'bar', this.myObservableValue] as const,
4  enabled: ({ queryKey }) => queryKey[2] > 10,
5  queryFn: ({ queryKey }) => {
6    const myObservableValue = queryKey[2];
7  }
8});

method update()

Update options for query (Uses QueryObserver.setOptions)

hook onDone()

Subscribe when query has been successfully fetched data

hook onError()

Subscribe when query has been failed fetched data

method invalidate()

Invalidate current query (Uses queryClient.invalidateQueries)

method reset()

Reset current query (Uses queryClient.resetQueries)

method setData()

Set data for current query (Uses queryClient.setQueryData)

property isResultRequsted

Any time when you trying to get access to result property this field sets as true
This field is needed for enableOnDemand option
This property if observable

property result

Observable query result (The same as returns the useQuery hook)

About enabled

All queries are enabled (docs can be found here) by default, but you can set enabled as false or use dynamic value like ({ queryKey }) => !!queryKey[1]
You can use update method to update value for this property or use dynamic options construction (options: () => ({ enabled: !!this.observableValue }))

About refetchOnWindowFocus and refetchOnReconnect

They will not work if you will not call mount() method manually of your QueryClient instance which you send for your queries, all other cases dependents on query stale time and enabled properties.
Example:

1import { hashKey, QueryClient } from '@tanstack/query-core';
2
3const MAX_FAILURE_COUNT = 3;
4
5export const queryClient = new QueryClient({
6  defaultOptions: {
7    queries: {
8      throwOnError: true,
9      queryKeyHashFn: hashKey,
10      refetchOnWindowFocus: 'always',
11      refetchOnReconnect: 'always',
12      staleTime: 5 * 60 * 1000,
13      retry: (failureCount, error) => {
14        if ('status' in error && Number(error.status) >= 500) {
15          return MAX_FAILURE_COUNT - failureCount > 0;
16        }
17        return false;
18      },
19    },
20    mutations: {
21      throwOnError: true,
22    },
23  },
24});
25
26queryClient.mount(); // enable all subscriptions for online\offline and window focus/blur

Mutations -> MobxMutation

Class wrapper for @tanstack-query/core mutations with MobX reactivity

Usage

Create an instance of MobxMutation with mutationFn parameter

1const mutation = new MobxMutation({
2  queryClient,
3  abortSignal, // Helps you to automatically clean up mutation  
4  mutationFn: async ({ signal, queryKey }) => {
5    const response = await petsApi.createPet({ name: 'Fluffy' }, { signal });
6    return response.data;
7  },
8});  

Features

method mutate(variables, options?)

Runs the mutation. (Works the as mutate function in useMutation hook)

hook onDone()

Subscribe when mutation has been successfully finished

hook onError()

Subscribe when mutation has been finished with failure

method reset()

Reset current mutation

property result

Observable mutation result (The same as returns the useMutation hook)

InfiniteQueries -> MobxInfiniteQuery

See docs for MobxQuery

QueryClient -> MobxQueryClient

This is the same entity as QueryClient from @tanstack-query/core package, but has a bit improvenments like hooks and configurations for Mobx* like entities

InferQuery, InferMutation, InferInfiniteQuery types

This types are needed to infer some other types from mutations\configs.

1type MyData = InferMutation<typeof myMutation, 'data'>
2type MyVariables = InferMutation<typeof myMutation, 'variables'>
3type MyConfig = InferMutation<typeof myMutation, 'config'>

MobxQueryConfigFromFn, MobxMutationConfigFromFn, MobxInfiniteQueryConfigFromFn

This types are needed to create configuration types from your functions of your http client

1const myApi = {
2  createApple: (name: string): Promise<AppleDC> => ... 
3}
4
5type Config = MobxMutationConfigFromFn<typeof myApi.createApple>

Usage

1. Install dependencies

1pnpm add @tanstack/query-core mobx-tanstack-query

2. Create QueryClient instance

1// @/shared/lib/tanstack-query/query-client.ts
2import { hashKey, QueryClient } from '@tanstack/query-core';
3
4const MAX_FAILURE_COUNT = 3;
5
6export const queryClient = new QueryClient({
7  defaultOptions: {
8    queries: {
9      throwOnError: true,
10      queryKeyHashFn: hashKey,
11      refetchOnWindowFocus: 'always',
12      refetchOnReconnect: 'always',
13      staleTime: 5 * 60 * 1000,
14      retry: (failureCount, error) => {
15        if ('status' in error && Number(error.status) >= 500) {
16          return MAX_FAILURE_COUNT - failureCount > 0;
17        }
18        return false;
19      },
20    },
21    mutations: {
22      throwOnError: true,
23    },
24  },
25});
26
27queryClient.mount(); // enable all subscriptions for online\offline and window focus/blur

3. Use it

1const petsListQuery = new MobxQuery({
2  queryClient,
3  queryKey: ['pets'],
4  queryFn: async ({ signal, queryKey }) => {
5    const response = await petsApi.fetchPets({ signal });
6    return response.data;
7  },
8});
9
10const addPetsMutation = new MobxMutation({
11  queryClient,
12  mutationFn: async (payload: { petName: string }) => {
13    const response = await petsApi.createPet(payload);
14    return response.data;
15  },
16
17  onSuccess: (data) => {
18    rootStore.notifications.push({
19      type: 'success',
20      title: `Pet created successfully with name ${data.name}`,
21    });
22    petsListQuery.invalidate();
23  },
24  onError: (error) => {
25    rootStore.notifications.push({
26      type: 'danger',
27      title: 'Failed to create pet',
28    });
29  }
30});
31
32addPetsMutation.mutate({ petName: 'fluffy' });

Another usage or mobx-tanstack-query/preset

This sub folder is contains already configured instance of QueryClient with this configuration and needed to reduce your boilerplate with more compact way.
Every parameter in configuration you can override using this construction

1import { queryClient } from "mobx-tanstack-query/preset";
2
3const defaultOptions = queryClient.getDefaultOptions();
4defaultOptions.queries!.refetchOnMount = true;
5queryClient.setDefaultOptions({ ...defaultOptions })

P.S. Overriding default options should be written before start whole application

createQuery(queryFn, otherOptionsWithoutFn?)

This is alternative for new MobxQuery(). Example:

1import { createQuery } from "mobx-tanstack-query/preset";
2
3const query = createQuery(async ({ signal, queryKey }) => {
4  const response = await petsApi.fetchPets({ signal });
5  return response.data;
6}, {
7  queryKey: ['pets'],
8})

createMutation(mutationFn, otherOptionsWithoutFn?)

This is alternative for new MobxMutation(). Example:

1import { createMutation } from "mobx-tanstack-query/preset";
2
3const mutation = createMutation(async (payload: { petName: string }) => {
4  const response = await petsApi.createPet(payload);
5  return response.data;
6})

createInfiniteQuery(queryFn, otherOptionsWithoutFn?)

This is alternative for new MobxInfiniteQuery(). Example:

1import { createInfiniteQuery } from "mobx-tanstack-query/preset";
2
3const query = createInfiniteQuery(async ({ signal, queryKey }) => {
4  const response = await petsApi.fetchPets({ signal });
5  return response.data;
6})

Project examples

• HTTP Status Codes
  Simple usage MobX Tanstack queries to fetch JSON data from GitHub
  Links:
  • Source: https://github.com/js2me/http-status-codes
  • GitHub Pages: https://js2me.github.io/http-status-codes/#/