@spoosh/plugin-cache

Response caching plugin for Spoosh with configurable stale time.

Documentation · Requirements: TypeScript >= 5.0 · Peer Dependencies: @spoosh/core

Installation

npm install @spoosh/plugin-cache

Usage

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

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

// Per-query override
useRead((api) => api("posts").GET(), { staleTime: 10000 });

How It Works

The cache plugin runs with priority -10, meaning it executes early in the middleware chain to check the cache before other plugins (like retry, debug) run. This ensures maximum efficiency by short-circuiting requests when cached data is available.

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 |

Write Options

Clear cache after a mutation completes successfully:

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

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

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

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

Instance API

The plugin exposes a clearCache function for manually clearing all cached data:

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

const { useRead, clearCache } = create(spoosh);

// Clear all cached data only (no refetch)
function handleLogout() {
  clearCache();
}

// Clear cache and trigger all queries to refetch
function handleUserSwitch() {
  clearCache({ refetchAll: true });
}

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