Cache

The cache plugin stores API responses and serves them instantly on subsequent requests, reducing network usage and improving perceived performance.

Installation

npm install @spoosh/plugin-cache

Usage

import { Spoosh } from "@spoosh/core";
import { cachePlugin } from "@spoosh/plugin-cache";

const client = new Spoosh<ApiSchema, Error>("/api").use([
  cachePlugin({ staleTime: 5000 }),
]);

Data is considered "fresh" for the duration of staleTime. During this period, subsequent requests return cached data without making a network request.

Per-Request Override

// Use longer cache time for static data
useRead((api) => api("settings").GET(), { staleTime: 60000 });

// Disable caching for real-time data
useRead((api) => api("live").GET(), { staleTime: 0 });

Options

Plugin Config

Option	Type	Default	Description
`staleTime`	`number`	`0`	Default stale time in milliseconds

Per-Request Options

Option	Type	Description
`staleTime`	`number`	Override stale time for this request

How It Works

First request fetches from network and stores in cache
Subsequent requests within staleTime return cached data instantly
After staleTime expires, next request fetches fresh data
Cache is automatically invalidated when using invalidationPlugin

Combining with Invalidation

For automatic cache updates after mutations, combine with invalidationPlugin:

import { Spoosh } from "@spoosh/core";
import { cachePlugin } from "@spoosh/plugin-cache";
import { invalidationPlugin } from "@spoosh/plugin-invalidation";

const client = new Spoosh<ApiSchema, Error>("/api").use([
  cachePlugin({ staleTime: 5000 }),
  invalidationPlugin(),
]);

When a mutation succeeds, related cached queries are automatically refreshed.

Clearing Cache on Mutations

You can clear all cached data after a mutation completes successfully using the clearCache write option:

const { trigger } = useWrite((api) => api("auth/logout").POST);

// Clear cache after logout
await trigger({ clearCache: true });

// Clear cache + trigger all queries to refetch (combine with invalidation plugin)
await trigger({ clearCache: true, invalidate: "*" });

This is useful for scenarios like user logout or switching organizations where you want to ensure no stale data persists.

Write Options

Option	Type	Description
`clearCache`	`boolean`	Clear all cached data after mutation succeeds

Manual Cache Clearing

The plugin also exposes a clearCache function for manually clearing all cached data outside of mutations:

import { createReactSpoosh } from "@spoosh/react";

const { useRead, clearCache } = createReactSpoosh(client);

function LogoutButton() {
  const handleLogout = () => {
    // Clear cache only (no automatic refetch)
    clearCache();
    // ... rest of logout logic
  };

  return <button onClick={handleLogout}>Logout</button>;
}

function SwitchAccountButton() {
  const handleSwitch = () => {
    // Clear cache and trigger all queries to refetch
    clearCache({ refetchAll: true });
  };

  return <button onClick={handleSwitch}>Switch Account</button>;
}

Instance API

Method	Description
`clearCache()`	Clears all cached data without triggering refetch
`clearCache({ refetchAll: true })`	Clears cache and triggers all queries to refetch

Behavior Matrix

Call	Cache Cleared	Refetch All
`clearCache()`	✅	❌
`clearCache({ refetchAll: true })`	✅	✅
`trigger({ clearCache: true })`	✅	❌
`trigger({ invalidate: "*" })`	❌	✅
`trigger({ clearCache: true, invalidate: "*" })`	✅	✅

On this page