React Location Simple Cache

A simple cache created for React Location Route loaders.

• Fetch Policies
• Stale-While-Revalidate
• Custom Keys
• Manual Invalidation

Installation

1 yarn add @tanstack/react-location-simple-cache
2 # or
3 npm i @tanstack/react-location-simple-cache

Getting Started

1 import { ReactLocation, Router } from '@tanstack/react-location'
2 import { ReactLocationSimpleCache } from '@tanstack/react-location-simple-cache'
3 
4 //
5 
6 const routeCache = new ReactLocationSimpleCache()
7 const location = new ReactLocation()
8 
9 function App() {
10   return (
11     <Router
12       location={location}
13       routes={[
14         {
15           path: '/',
16           element: <Posts />,
17           loader: routeCache.createLoader(async () => ({
18             posts: await fetchPosts(),
19           })),
20         },
21       ]}
22     />
23   )
24 }

Docs

ReactLocationSimpleCache

Use the ReactLocationSimpleCache class to create a new cache instance.

 const simpleCache = new ReactLocationSimpleCache()

SimpleCacheRecord

This is the underlying shape of each record that is stored in the cache:

1 import { LoaderData, RouteMatch } from '@tanstack/react-location'
2 
3 export type SimpleCacheRecord<
4   TData extends LoaderData = Record<string, unknown>,
5 > = {
6   key: string
7   updatedAt: number
8   ready: boolean
9   promise?: Promise<TData>
10   data?: any
11   invalid?: boolean
12   match: RouteMatch
13 }

Fetch Policies

The caching functionality of the simple cache allows for a few different fetch policies to be used when determining if and when your loader function gets called again.

 type FetchPolicy = 'cache-and-network' | 'cache-first' | 'network-only'

• cache-and-network
  • If the record is empty:
    • navigation suspends while the data is fetch and cached
  • If data is cached:
    • Navigation is immediate
    • If a maxAge was not supplied:
      • The data is always refetched in the background after navigation
    • If a maxAge was supplied OR the record has been manually invalidated:
      • If the record has expired, the data is refetched in the background after navigation
• cache-first
  • If the record is empty:
    • navigation suspends while the data is fetch and cached
  • If data is cached:
    • Navigation is immediate
    • If the record has been manually marked as invalid, it will be refetch in the background
    • Otherwise, the data is never refetched
• network-only
  • navigation always suspends while the data is fetched and cached

cache.createLoader

This cache method creates a loader function for a React Location route.

1 createLoader: (
2   loader: Loader,
3   opts?: {
4     key?: (match: RouteMatch) => string
5     maxAge?: number
6     policy?: FetchPolicy
7   },
8 ) => Loader

1 const routes = [
2   {
3     path: ':postId',
4     element: <Post />,
5     loader: routeCache.createLoader(
6       async ({ params: { postId } }) => ({
7         post: await fetchPostById(postId),
8       }),
9       {
10         key: (match) => `posts_${match.params.postId}`,
11       },
12     ),
13   },
14 ]

cache.clearAll

Resets the cache to its original state with no records and no data

1 type cache = {
2   removeAll(): void
3 }

cache.clear

Removes records from the cache by predicate function

1 type cache = {
2   remove<TLoaderData>(
3     predicateFn: (record: SimpleCacheRecord) => boolean | any,
4   ): void
5 }

cache.filter

Returns records by predicate function

1 type cache = {
2   filter<TLoaderData>(
3     predicateFn: (record: SimpleCacheRecord) => boolean | any,
4   ): SimpleCacheRecord<TLoaderData>
5 }

cache.find

Returns the first record found by predicate

1 type cache = {
2   find<TLoaderData>(
3     predicateFn: (record: SimpleCacheRecord) => boolean | any,
4   ): SimpleCacheRecord<TLoaderData>
5 }

cache.invalidate

Invalidates records by predicate function

1 type cache = {
2   invalidate<TLoaderData>(
3     predicateFn: (record: SimpleCacheRecord) => boolean | any,
4   ): void
5 }