@spoosh/plugin-invalidation

Cache invalidation plugin for Spoosh - auto-invalidates related queries after mutations.

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

Installation

npm install @spoosh/plugin-invalidation

How It Works

Tags are automatically generated from the API path hierarchy:

// Query tags are generated from the path:
useRead((api) => api("users").GET());
// → tags: ["users"]

useRead((api) => api("users/:id").GET({ params: { id: 123 } }));
// → tags: ["users", "users/123"]

useRead((api) => api("users/:id/posts").GET({ params: { id: 123 } }));
// → tags: ["users", "users/123", "users/123/posts"]

When a mutation succeeds, related queries are automatically invalidated:

// Creating a post at users/123/posts invalidates:
const { trigger } = useWrite((api) => api("users/:id/posts").POST);
await trigger({ params: { id: 123 }, body: { title: "New Post" } });

// ✓ Invalidates: "users", "users/123", "users/123/posts"
// All queries matching these tags will refetch automatically

Usage

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

const client = new Spoosh<ApiSchema, Error>("/api").use([invalidationPlugin()]);

const { trigger } = useWrite((api) => api("posts").POST);
await trigger({ body: { title: "New Post" } });

Default Configuration

// Default: invalidate all related tags (full hierarchy)
invalidationPlugin(); // same as { defaultMode: "all" }

// Only invalidate the exact endpoint by default
invalidationPlugin({ defaultMode: "self" });

// Disable auto-invalidation by default (manual only)
invalidationPlugin({ defaultMode: "none" });

Per-Request Invalidation

// Mode only (string)
await trigger({
  body: { title: "New Post" },
  invalidate: "all", // Invalidate entire path hierarchy
});

await trigger({
  body: { title: "New Post" },
  invalidate: "self", // Only invalidate the exact endpoint
});

await trigger({
  body: { title: "New Post" },
  invalidate: "none", // No invalidation
});

// Tags only (array without mode keyword)
await trigger({
  body: { title: "New Post" },
  invalidate: ["posts", "users", "custom-tag"],
  // → Default mode: 'none' (only explicit tags are invalidated)
});

// Mode + Tags (array with mode keyword at any position)
await trigger({
  body: { title: "New Post" },
  invalidate: ["all", "dashboard", "stats"],
  // → 'all' mode + explicit tags
});

await trigger({
  body: { title: "New Post" },
  invalidate: ["posts", "self", "users"],
  // → 'self' mode + explicit tags
});

await trigger({
  body: { title: "New Post" },
  invalidate: ["dashboard", "stats", "all"],
  // → 'all' mode + explicit tags (mode can be anywhere)
});

Options

Plugin Config

| Option | Type | Default | Description | | ------------- | --------------------------- | ------- | --------------------------------------------------- | | defaultMode | "all" \| "self" \| "none" | "all" | Default invalidation mode when option not specified |

Per-Request Options

| Option | Type | Description | | ------------ | --------------------------------------- | ------------------------------------------------------------------------------------------------------- | | invalidate | "all" \| "self" \| "none" \| string[] | Mode only (string), tags only (array), or mode + tags (array with 'all'/'self' keyword at any position) |

Invalidation Modes

| Mode | Description | Example | | -------- | --------------------------------------- | ----------------------------------------------------------- | | "all" | Invalidate all tags from path hierarchy | users/123/posts → users, users/123, users/123/posts | | "self" | Only invalidate the exact endpoint tag | users/123/posts → users/123/posts | | "none" | Disable auto-invalidation (manual only) | No automatic invalidation |

Instance API

The plugin exposes invalidate for manually triggering cache invalidation outside of mutations:

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

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

// Invalidate with string array
invalidate(["users", "posts"]);

// Invalidate with single string
invalidate("users");

// Useful for external events like WebSocket messages
socket.on("data-changed", (tags) => {
  invalidate(tags);
});

| Method | Description | | ------------ | ----------------------------------------- | | invalidate | Manually invalidate cache entries by tags |