Pinia-cached-store NPM

Cached Pinia Stores

This module defines a factory function that creates read-only Pinia stores which automatically copy their state to local storage and can load it from there, omitting the need for subsequent refetches. The pattern enables a lightweight dataloading system with a global cache, somewhat similar to what React Query, Apollo or other libraries provide. Another use case is to cache expensive calculations in a store. These can then be re-instantiated quickly when the page gets refreshed without needing to recompute.

As an example of the second aforementioned use case, the following store calculates Pi to a given precision and stores the value:

import { defineCachedStore } from 'pinia-cached-store';

const usePiStore = defineCachedStore({
  id: 'pi',

  state: () => ({
    value: 3.14,
  }),

  async refresh({ iterations }) {
    // This is a simple (and pretty inefficient) Monte Carlo algorithm that
    // estimates Pi. A fixed number of points is randomly distributed inside the
    // square from the origin to [1,1]. We check how many of these points fall
    // into the corresponding quarter-circle and use that to calculate pi.
    let hits = 0;
    for (let i = 0; i < iterations; i++) {
      const x = Math.random();
      const y = Math.random();
      if (x * x + y * y <= 1) {
        hits += 1;
      }
    }
    // For the quarter-circle's area A:
    //   A = pi (since r=1)
    //   A / 4 = hits / iterations
    this.value = (4 * hits) / iterations;
  },
});

Later in our app, the store can be used like this:

const pi = usePiStore();
// Make sure you are in an async function. Also, feel free to play around with
// this paramter and get different values:
await pi.$load({ iterations: 99999 });

// Somewhere else:
const doublePi = pi.value * 2;
// Or in templates:
// <span>Pi: {{ pi.value }}</span>

Note that since a cached store is read-only, it is no longer possible to define actions. That means the store's sole purpose is to merely reflect data on a backend or store the output of some computation – the source of truth will never be the store itself. Using getters (computed properties) is fine, though.

Installation

Install the package as follows:

npm install --save-dev pinia-cached-store
# or
yarn add --dev pinia-cached-store

Both Vue and Pinia 2 should also be installed as dependencies in your project.

Usage

For this guide, we will look at the following example store. It takes the name of a Pizza dish as an input and stores all the required ingredients for making it. A cached store is defined much like a regular Pinia store, and any options can be here as well, except for actions, since caching makes a store read-only. For completeness' sake, we will directly define it in Typescript. Here is the code for the complete store definition:

import { defineCachedStore } from 'pinia-cached-store';
import pizzaApi from 'awesome-pizza-place';

// Users of the store will pass these options when initializing it. We can use
// them to pass around information relevant to what data we want to fetch.
// As another example, a store containing customer data would take something
// like the customer's ID in this options object.
interface PizzaRefreshOptions {
  name: string;
  extraCheese?: boolean;
}

export const usePizzaStore = defineCachedStore({
  id: 'pizza',

  state: () => ({
    toppings: [] as string[],
    sauce: null as string | null,
    cheese: false as boolean | 'extra',
  }),

  async refresh({ name, extraCheese }: PizzaRefreshOptions) {
    this.$state = await pizzaApi.getPizzaByName(name);
    if (this.cheese && extraCheese) {
      this.cheese = 'extra';
    }
  },
});

The refresh callback

A cached store must define an asynchronous function named refresh in the top level. Although it looks and feels like an action, it is explicitly not placed inside the actions object, and you won't be able to call it directly later, either. The purpose of this function is to populate the state with the correct data when a user requests it. You must define exactly one argument to this function, which are the options that you will receive from the user (see the using section below). This will only be called when the cache doesn't already contain an entry for the requested options, so you don't need to do any cache checking here.

Using this works exactly the same way as it would inside an action. That means that you can use methods like \$patch to overwrite (parts of) the state, as well as setting this.$state directly. Setting individual keys in the state also works as expected.

Using the store

Once the store is created, you can use it just like any other Pinia store. By default, cache-enabled stores are created from the state() function in their definition. You can then use the $load action to populate the state with data, depending on what you currently need. This method takes the exact same parameter object you defined for refresh and will update the state accordingly:

// Inside setup() of a component:
const pizza = usePizzaStore();

onMounted(async () => {
  await pizza.$load({ pizzaName: 'hawaii' });
});

Multiple $load() calls (either consecutively or after a page refresh) will prioritize cached content. Cache entries are considered applicable if they were created from the same options object as the current call:

// This will call refresh() with our objects object:
await pizza.$load({ pizzaName: 'hawaii' });
// Here, refresh() is called again, since we have a new options object:
await pizza.$load({ pizzaName: 'hawaii', extraCheese: true });
// Again, this will call refresh():
await pizza.$load({ pizzaName: 'hawaii' });
// Since this object was passed before, this is loaded from cache:
await pizza.$load({ extraCheese: true, pizzaName: 'hawaii' });

Cache clearing

To remove all entries from local storage corresponding a store, call the $clearCache action. Since this will reset the store to the initial state (the one returned by the state function in the store's definition), you probably want to load some data again afterwards:

pizza.$clearCache();
await pizza.$load({ pizzaName: 'margherita' });

Note that this will only clear that specific store's cache — those of other stores are left untouched.

Manual cache writes and SSR

Every cached store has a $flushCache method which you can call if you would like to force the cache to be written to storage. You don't need to do this when calling $load, but there might be other circumstances.

For example, in an SSR environment like Nuxt you might want to calculate the store's content on the server and store it in the client's local storage while hydrating. You can use this snippet to start:

const useComplicatedStore = defineCachedStore({
  id: 'magic',

  caching: {
    // Don't write to a cache while performing SSR. You'll need to check your
    // SSR framework's docs to find out how to check if SSR is currently
    // running.
    storage: import.meta.env.SSR ? null : window.localStorage,
  },

  state: () => ({ value: 1 }),

  async refresh() {
    this.value = calculateValue();
  },

  // Don't just copy this, read the note below.
  hydrate(storeState, initialState) {
    this.$flushCache();
  },
});

Note that you might not even need hydrate. If the store is pre-filled from rendering server-side, there isn't really a need to blindly copy that data to the user's local storage. An exception to this suggestion would be if you $load() different values into the store during the lifecycle of you app. In that case it might be beneficial to cache the server-rendered dataset on the client as well.

You might also want to check out Vue's hydration guide, the corresponding Pinia guide, and the docs on Pinia's hydrate option.

Secondary payloads

The $load method accepts a second argument which will be passed verbatim to your refresh method. You can use this to provide data when refreshing that is not factored in when calculating a key for caching. Since caches are stored under a key that depends on what you pass as the first argument, you need to use the second payload if you have data that isn't part of the state key. This payload is also passed to checkValidity, if provided.

As an example, we could rewrite the pi store from above to use this argument for the number of iterations. That way we only get one local storage entry if we call it multiple times (this time with TypeScript):

import { defineCachedStore } from 'pinia-cached-store';

const usePiStore = defineCachedStore({
  id: 'pi',

  state: () => ({
    value: 3.14,
    iterations: 0,
  }),

  async refresh(options: {}, iterations: number) {
    this.value = thePiAlgorithmFromAbove(iterations);
    this.iterations = iterations;
  },

  caching: {
    checkValidity(data: { iterations: number }, requestedIterations: number) {
      // Only recalculate when more iterations are requested:
      return iterations >= requestedIterations;
    },
  },
});

When calling the store now, a recalculation will only be performed if the number of iterations requested is higher than that from the last calculation. Further, local storage will only contain one entry for this store.

Caching options

The object passed to the store factory function may also contain a set of options to control the caching behaviour:

export const store = defineCachedStore({
  // ...

  caching: {
    keyPrefix: 'myStore',
  },
});

Following options are supported (all are optional):

keyPrefix — By default, cache entries are stored into local storage entries named store followed by the store ID and a base64 representation of the provided options. This option can be used to change that prefix to something else.
refreshSpecificKey — Set this to false to use one cache key for the entire store. By default (true), different cache entries are created depending on the options which $load is called with (as described in the guide above). Note that disabling this behaviour will effectively invalidate options you give to $load in a second call because then the cache will be used instead (which may have been populated with other arguments).
maxAge — This is the maximum age a cache entry may have before it is considered stale and needs to be refetched. Provide this as a number, in milliseconds (the default is 86400000, or a day).
checkValidity — In addition to maxAge, this option can be used to modify how existing cache entries get loaded. It is set to a function that receives the (old) data and returns either true or false, depending on whether it should be loaded or discarded and refetched.
loadingKey — Set this to the name of a boolean property defined in state and it will automatically be set to true when loading starts. After loading is finished (with or without errors), it will be set back to false. The property will not be created, it needs to exist in the state already.
storage — Use this option to use a different Storage object to save the cache. By default, the browser's local storage is used. Make sure to handle SSR somehow if you set this option. If you set this to null, no storage is used and the cache is effectively bypassed.

You can get final caching key that is actually used from the stores' computedCacheKey property. It is set after calling $load.

Error handling

For error logging / handling, you can use Pinia's subscription mechanism. Using a subscription, you can perform additional actions before and after the load process runs:

let isLoading = false;

store.$onAction(({ name, after, onError }) => {
  if (name !== '$load') return;

  isLoading = true;

  after(() => (isLoading = false));
  onError((error) => {
    isLoading = false;
    console.warn(`Error while loading store: ${error}`);
  });
});

See the aforementioned documentation for more details. In particular, note that the subscription lives as long as the component it was created in. Further, $onAction returns a function that can be used to manually terminate the subscription if necessary.