Nano Stores Query

Mutator stores track the lifecycle of a mutation call.

Key behaviors:

• mutate() always resets data and error before starting.
• When throttleCalls is true (default), calling mutate() while already loading is a no-op.
• When the store loses all subscribers, it resets to the initial state. Any in-flight mutation results are discarded.

To use Nano Stores Query, you must first initialize the factory using nanoqueryFactory. This function accepts a PlatformCompat object which provides platform-specific hooks for visibility changes and network reconnection. The factory returns a nanoquery function used to configure global settings and create stores.

import { nanoqueryFactory } from './lib/factory';

// PlatformCompat provides isAppVisible, visibilityChangeSubscribe, and reconnectChangeSubscribe
const nanoquery = nanoqueryFactory(platformCompatInstance);

// Initialize with global settings
const query = nanoquery({
  cacheLifetime: 60000,
  revalidateOnFocus: true,
  fetcher: myGlobalFetcher
});

If a store depends on an external factor (like a userId or refreshToken) that is not part of the store's own key, you must manually invalidate the cache when that factor changes to prevent stale data from the previous user/session.

Wipe all keys

Use invalidateKeys with a predicate that returns true to clear the entire cache:

onSet($refreshToken, () => invalidateKeys(() => true))

Target specific store invalidation

If a specific store depends on an outside factor, call its invalidate method directly:

onSet($someOutsideFactor, $specificStore.invalidate)

Nano Query is fully supported in React Native.

Revalidation on Reconnect

To enable revalidateOnReconnect functionality, you must install the @react-native-community/netinfo package. If not installed, reconnection events will simply not trigger revalidation.

Importing the library

If your environment does not support package exports, import from the specific React Native entry point:

import { nanoquery } from "@nanostores/query/react-native";

While module-scoped stores are common, you can create store instances limited to a single component's lifecycle. This allows you to fetch data based on component props or state while still leveraging Nano Query's cache and refetching features.

To do this, wrap your createFetcherStore call in a factory function that is invoked within a component's state initialization.

const createStore = (id: string) => () =>
  createFetcherStore<{ avatarUrl: string }>(`/api/user/${id}`);

const UserAvatar: FC<{ id: string }> = ({ id }) => {
  // Initialize the store instance within component state
  const [$user] = useState(createStore(id));

  const { data } = useStore($user);
  if (!data) return null;

  return <img src={data.avatarUrl} />;
};

To use Nano Stores Query, install both nanostores and @nanostores/query using npm:

npm install nanostores @nanostores/query

Before creating stores, use nanoquery() to define a context. This allows you to share a default fetcher implementation and general settings across all fetcher and mutator stores. This context also facilitates easy mocking for tests and stories.

import { nanoquery } from '@nanostores/query';

export const [createFetcherStore, createMutatorStore] = nanoquery({
  fetcher: (...keys) => fetch(keys.join('')).then((r) => r.json()),
});

Fetcher stores provide three specific properties to manage the currently active key (the key currently being used for fetching/mutating):

1. fetcherStore.invalidate: Invalidates the current key.
2. fetcherStore.revalidate: Revalidates the current key.
3. fetcherStore.mutate: A function that accepts a new value to mutate the current key for the fetcher.
4. fetcherStore.key: Holds the current key in its serialized string form.

A fetcher store is a reactive Nano Store (an atom) that automatically fetches data whenever its keys change. You can pass strings, numbers, or other Nano Stores as keys. If any key part is a NoKey (null, undefined, void, or false), the fetcher will not execute (conditional fetching).

import { atom } from 'nanostores';
import { createFetcherStore } from './fetcher';

export const $currentPostId = atom('');
// The store will re-fetch whenever $currentPostId updates
export const $currentPost = createFetcherStore<Post>(['/api/post/', $currentPostId]);