Core Concepts

The @spoosh/core package provides the foundation for building type-safe API clients. 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 createSpoosh
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.)          │
├─────────────────────────────────────────────────────────┤
│                createSpoosh (@spoosh/core)              │
├─────────────────────────────────────────────────────────┤
│                      fetch API                          │
└─────────────────────────────────────────────────────────┘

Creating a Client

Use createSpoosh to create your API client with plugins:

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

const spoosh = createSpoosh<ApiSchema>({
  baseUrl: "/api",
  plugins: [
    cachePlugin({ staleTime: 5000 }),
    deduplicationPlugin(), // Prevent duplicate requests during invalidation
    invalidationPlugin(),
  ],
});

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

Overview

Architecture

Creating a Client

Next Steps

Schema Definition

Client API

Response Format

Plugins

On this page