Core Concepts

The @spoosh/core package provides the foundation for the Spoosh type-safe API toolkit. This section covers the core concepts you need to understand.

Overview

Spoosh is built around a few key concepts:

Schema Definition - Define your API structure with TypeScript types
Client Creation - Create a client instance with the Spoosh class
Plugins - Extend functionality with caching, retry, invalidation, and more
Response Format - Consistent response structure across all requests

Architecture

┌─────────────────────────────────────────────────────────┐
│                      Your App                           │
├─────────────────────────────────────────────────────────┤
│  useRead / useWrite / useInfiniteRead (@spoosh/react)   │
├─────────────────────────────────────────────────────────┤
│     Plugins (cache, invalidation, retry, etc.)          │
├─────────────────────────────────────────────────────────┤
│                Spoosh (@spoosh/core)                    │
├─────────────────────────────────────────────────────────┤
│                      fetch API                          │
└─────────────────────────────────────────────────────────┘

Creating a Client

Use the Spoosh class to create your API client with plugins:

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

const spoosh = new Spoosh<ApiSchema, Error>("/api").use([
  cachePlugin({ staleTime: 5000 }),
  deduplicationPlugin(), // Prevent duplicate requests during invalidation
  invalidationPlugin(),
]);

Note: There's also createClient for simple use cases without plugins, but the Spoosh class is recommended for most applications.

Overview

Architecture

Creating a Client

Next Steps

Schema Definition

Client API

Response Format

Plugins

On this page