@spoosh/core

Core client and plugin system for Spoosh - a type-safe API toolkit.

Documentation · Requirements: TypeScript >= 5.0

Installation

``bash
npm install @spoosh/core
`

Usage

$3

`typescript
type User = { id: number; name: string; email: string };

type ApiSchema = {
users: {
GET: { data: User[] };
POST: { data: User; body: { name: string; email: string } };
};
"users/:id": {
GET: { data: User };
PUT: { data: User; body: Partial };
DELETE: { data: void };
};
search: {
GET: { data: User[]; query: { q: string; page?: number } };
};
upload: {
POST: { data: { url: string }; body: { file: File } };
};
payments: {
POST: {
data: { id: string };
body: { amount: number; currency: string };
};
};
};
`

$3

`typescript
import { createClient } from "@spoosh/core";

const api = createClient("/api");

// With custom options
const apiWithAuth = createClient("/api", {
headers: { Authorization: "Bearer token" },
});

// Import body wrappers for explicit serialization
import { json, form, urlencoded } from "@spoosh/core";
`

$3

`typescript
// GET /api/users
const { data, error, status } = await api("users").GET();

// GET /api/search?q=john&page=1
const { data } = await api("search").GET({ query: { q: "john", page: 1 } });

// POST /api/users with JSON body
const { data: newUser } = await api("users").POST({
body: { name: "John", email: "john@example.com" },
});

// GET /api/users/123 (with params)
const { data: user } = await api("users/:id").GET({ params: { id: 123 } });

// PUT /api/users/123
const userId = 123;
const { data: updated } = await api("users/:id").PUT({
params: { id: userId },
body: { name: "John Updated" },
});

// DELETE /api/users/123
await api("users/:id").DELETE({ params: { id: 123 } });

// POST with file upload (using form() wrapper for multipart/form-data)
const { data: uploaded } = await api("upload").POST({
body: form({ file: myFile }),
});

// POST with form data (using urlencoded() wrapper)
const { data: payment } = await api("payments").POST({
body: urlencoded({ amount: 1000, currency: "usd" }),
});
`

$3

All API calls return a SpooshResponse:

`typescript
type SpooshResponse = {
status: number; // HTTP status code
data: TData | undefined; // Response data (if successful)
error: TError | undefined; // Error data (if failed)
headers?: Headers; // Response headers
aborted?: boolean; // True if request was aborted
};
`

$3

When using createClient, Next.js cache tags are automatically generated from the API path:

`typescript
// Server component
import { createClient } from "@spoosh/core";

const api = createClient(process.env.API_URL!);

// Auto-generates next: { tags: ['posts'] }
const { data: posts } = await api("posts").GET();

// Auto-generates next: { tags: ['users', 'users/123', 'users/123/posts'] }
const { data: userPosts } = await api("users/:id/posts").GET({
params: { id: 123 },
});
`

This enables automatic cache invalidation with revalidateTag() in Next.js.

Schema Types

| Field | Description | Example |
| ------- | --------------------- | ------------------------------------------------ |
| data | Response data type | GET: { data: User[] } |
| body | Request body type | POST: { data: User; body: CreateUserBody } |
| query | Query parameters type | GET: { data: User[]; query: { page: number } } |
| error | Typed error type | GET: { data: User; error: ApiError } |

Path parameters are defined using :param syntax in the path key (e.g., "users/:id").

API Reference

$3

Creates a lightweight type-safe API instance.

Parameters:

| Parameter | Type | Description |
| ---------------- | ------------- | ------------------------------------------------------------- |
| baseUrl | string | Base URL for all API requests |
| defaultOptions | RequestInit | (Optional) Default fetch options (headers, credentials, etc.) |

$3

Creates a full-featured client with plugin system using a clean class-based API. Use this with @spoosh/react or @spoosh/angular.

`typescript
import { Spoosh } from "@spoosh/core";
import { cachePlugin } from "@spoosh/plugin-cache";
import { retryPlugin } from "@spoosh/plugin-retry";

const spoosh = new Spoosh("/api", {
headers: { Authorization: "Bearer token" },
}).use([cachePlugin({ staleTime: 5000 }), retryPlugin({ retries: 3 })]);

const { api } = client;
const { data } = await api("users").GET();
`

Constructor Parameters:

| Parameter | Type | Description |
| ---------------- | ------------- | -------------------------------- |
| baseUrl | string | Base URL for all API requests |
| defaultOptions | RequestInit | (Optional) Default fetch options |

Methods:

| Method | Description |
| --------------- | --------------------------------------------------------------------- |
| .use(plugins) | Add plugins to the client. Returns a new instance with updated types. |

Properties:

| Property | Description |
| ----------------- | ------------------------------------------- |
| .api | Type-safe API interface for making requests |
| .stateManager | Cache and state management |
| .eventEmitter | Event system for refetch/invalidation |
| .pluginExecutor | Plugin lifecycle management |

Creating Plugins

`typescript
import type { SpooshPlugin } from "@spoosh/core";

interface MyPluginOptions {
myOption?: string;
}

export function myPlugin(): SpooshPlugin<{
readOptions: MyPluginOptions;
}> {
return {
name: "my:plugin",
operations: ["read"],

middleware: async (context, next) => {
// Before request
const response = await next();
// After request
return response;
},

onResponse: async (context) => {
// Handle response
// This always run after response
},

lifecycle: {
onMount(context) {},
onUpdate(context, prev) {},
onUnmount(context) {},
},
};
}
``