react

@spoosh/react

React hooks for Spoosh - useRead, useWrite, usePages, and useSSE.

Documentation · Requirements: TypeScript >= 5.0, React >= 18.0

Installation

npm install @spoosh/core @spoosh/react

Usage

Setup

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

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

export const { useRead, useWrite, usePages } = create(spoosh);

useRead

Fetch data with automatic caching and refetching.

function UserList() {
  const { data, loading, error, trigger } = useRead(
    (api) => api("users").GET()
  );

  if (loading) return <div>Loading...</div>;
  if (error) return <div>Error: {error.message}</div>;

  return (
    <ul>
      {data?.map((user) => <li key={user.id}>{user.name}</li>)}
    </ul>
  );
}

// With options
const { data } = useRead(
  (api) => api("users").GET({ query: { page: 1 } }),
  {
    staleTime: 10000,
    enabled: isReady,
  }
);

// With path parameters
const { data: user } = useRead(
  (api) => api("users/:id").GET({ params: { id: userId } }),
  { enabled: !!userId }
);

useWrite

Trigger mutations with loading and error states.

function CreateUser() {
  const { trigger, loading, error } = useWrite(
    (api) => api("users").POST()
  );

  const handleSubmit = async (data: CreateUserBody) => {
    const result = await trigger({ body: data });
    if (result.data) {
      // Success
    }
  };

  return (
    <form onSubmit={handleSubmit}>
      {/* form fields */}
      <button disabled={loading}>
        {loading ? "Creating..." : "Create User"}
      </button>
    </form>
  );
}

// With path parameters
const updateUser = useWrite((api) => api("users/:id").PUT());

await updateUser.trigger({
  params: { id: userId },
  body: { name: "Updated Name" },
});

usePages

Bidirectional paginated data fetching with infinite scroll support.

function PostList() {
  const {
    data,
    pages,
    loading,
    canFetchNext,
    canFetchPrev,
    fetchNext,
    fetchPrev,
    fetchingNext,
    fetchingPrev,
  } = usePages(
    (api) => api("posts").GET({ query: { page: 1 } }),
    {
      // Required: Check if next page exists
      canFetchNext: ({ lastPage }) => lastPage?.data?.meta.hasMore ?? false,

      // Required: Build request for next page
      nextPageRequest: ({ lastPage }) => ({
        query: { page: (lastPage?.data?.meta.page ?? 0) + 1 },
      }),

      // Required: Merge all pages into items
      merger: (pages) => pages.flatMap((p) => p.data?.items ?? []),

      // Optional: Check if previous page exists
      canFetchPrev: ({ firstPage }) => (firstPage?.data?.meta.page ?? 1) > 1,

      // Optional: Build request for previous page
      prevPageRequest: ({ firstPage }) => ({
        query: { page: (firstPage?.data?.meta.page ?? 2) - 1 },
      }),
    }
  );

  return (
    <div>
      {canFetchPrev && (
        <button onClick={fetchPrev} disabled={fetchingPrev}>
          {fetchingPrev ? "Loading..." : "Load Previous"}
        </button>
      )}

      {data?.map((post) => <PostCard key={post.id} post={post} />)}

      {canFetchNext && (
        <button onClick={fetchNext} disabled={fetchingNext}>
          {fetchingNext ? "Loading..." : "Load More"}
        </button>
      )}
    </div>
  );
}

useSSE

Subscribe to real-time data streams using Server-Sent Events (SSE).

import { sse } from "@spoosh/transport-sse";

// Setup with SSE transport
const spoosh = new Spoosh<ApiSchema, Error>("/api").withTransports([sse()]);
export const { useSSE } = create(spoosh);

// Basic subscription
function Notifications() {
  const { data, isConnected, loading } = useSSE(
    (api) => api("notifications").GET({ query: { userId: "user-123" } })
  );

  if (loading) return <div>Connecting...</div>;

  return (
    <div>
      <span>{isConnected ? "Connected" : "Disconnected"}</span>
      {data?.message && <p>{data.message.text}</p>}
    </div>
  );
}

// Subscribe to specific events only
const { data } = useSSE(
  (api) => api("notifications").GET({
    query: { userId: "user-123" },
  }),
  { events: ["alert"] }  // Only alert events
);

// AI streaming with accumulation
const { data, trigger } = useSSE(
  (api) => api("chat").POST(),
  {
    events: ["chunk", "done"],
    parse: "json-done",
    accumulate: {
      chunk: (prev, curr) => ({
        ...curr,
        chunk: (prev?.chunk || "") + curr.chunk,
      }),
    },
    enabled: false,
  }
);

// Start streaming on demand
await trigger({ body: { message: "Hello" } });

API Reference

useRead(readFn, options?)

Option	Type	Default	Description
enabled	boolean	true	Whether to fetch automatically
staleTime	number	-	Cache stale time (from plugin-cache)
retries	number	-	Retry attempts (from plugin-retry)
+ plugin options	-	-	Options from installed plugins

Returns:

Property	Type	Description
data	TData | undefined	Response data
error	TError | undefined	Error if request failed
loading	boolean	True during initial load
fetching	boolean	True during any fetch
trigger	() => Promise	Manually trigger fetch
abort	() => void	Abort current request

useWrite(writeFn)

Returns:

Property	Type	Description
trigger	(options) => Promise	Execute the mutation
data	TData | undefined	Response data
error	TError | undefined	Error if request failed
loading	boolean	True while mutation is in progress
abort	() => void	Abort current request

usePages(readFn, options)

Option	Type	Required	Description
merger	(pages) => TItem[]	Yes	Merge all pages into items
canFetchNext	(ctx) => boolean	No	Check if next page exists. Default: () => false
nextPageRequest	(ctx) => Partial<TRequest>	No	Build request for next page
canFetchPrev	(ctx) => boolean	No	Check if previous page exists
prevPageRequest	(ctx) => Partial<TRequest>	No	Build request for previous page
enabled	boolean	No	Whether to fetch automatically

Context object passed to callbacks:

// For canFetchNext and nextPageRequest
type NextContext<TData, TRequest> = {
  lastPage: InfinitePage<TData> | undefined;
  pages: InfinitePage<TData>[];
  request: TRequest;
};

// For canFetchPrev and prevPageRequest
type PrevContext<TData, TRequest> = {
  firstPage: InfinitePage<TData> | undefined;
  pages: InfinitePage<TData>[];
  request: TRequest;
};

// Each page in the pages array
type InfinitePage<TData> = {
  status: "pending" | "loading" | "success" | "error" | "stale";
  data?: TData;
  error?: TError;
  meta?: TMeta;
  input?: { query?; params?; body? };
};

Returns:

Property	Type	Description
data	TItem[] | undefined	Merged items from all pages
pages	InfinitePage<TData>[]	Array of all pages with status, data, and meta
loading	boolean	True during initial load
fetching	boolean	True during any fetch
fetchingNext	boolean	True while fetching next page
fetchingPrev	boolean	True while fetching previous
canFetchNext	boolean	Whether next page exists
canFetchPrev	boolean	Whether previous page exists
fetchNext	() => Promise<void>	Fetch the next page
fetchPrev	() => Promise<void>	Fetch the previous page
trigger	(options?) => Promise<void>	Trigger fetch with optional new request options
abort	() => void	Abort current request
error	TError | undefined	Error if request failed

useSSE(subFn, options?)

Option	Type	Default	Description
enabled	boolean	true	Whether to connect automatically
events	string[]	all events	Subscribe to specific events only
parse	ParseConfig	"auto"	How to parse raw event data
accumulate	AccumulateConfig	"replace"	How to combine events over time

Returns:

Property	Type	Description
data	TEvents | undefined	Accumulated event data
error	TError | undefined	Error if connection failed
loading	boolean	True during initial connection
isConnected	boolean	True when connected to stream
trigger	(options?) => Promise	Reconnect with new options
disconnect	() => void	Disconnect from stream
reset	() => void	Reset accumulated data

Connection Options:

Option	Type	Description
headers	HeadersInit	Request headers
credentials	RequestCredentials	Credentials mode
maxRetries	number	Max retry attempts (default: 3)
retryDelay	number	Delay between retries in ms (default: 1000)