@spoosh/react 0.1.0-beta.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Spoosh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,222 @@
+# @spoosh/react
+
+React hooks for Spoosh - `useRead`, `useWrite`, and `useInfiniteRead`.
+
+**[Documentation](https://spoosh.dev/docs/integrations/react)** · **Requirements:** TypeScript >= 5.0, React >= 18.0
+
+## Installation
+
+```bash
+npm install @spoosh/core @spoosh/react
+```
+
+## Usage
+
+### Setup
+
+```typescript
+import { createSpoosh } from "@spoosh/core";
+import { createReactSpoosh } from "@spoosh/react";
+import { cachePlugin } from "@spoosh/plugin-cache";
+
+const plugins = [cachePlugin({ staleTime: 5000 })];
+
+const client = createSpoosh<ApiSchema, Error, typeof plugins>({
+  baseUrl: "/api",
+  plugins,
+});
+
+export const { useRead, useWrite, useInfiniteRead } = createReactSpoosh(client);
+```
+
+### useRead
+
+Fetch data with automatic caching and refetching.
+
+```typescript
+function UserList() {
+  const { data, loading, error, refetch } = 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,
+  }
+);
+```
+
+### useWrite
+
+Trigger mutations with loading and error states.
+
+```typescript
+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>
+  );
+}
+```
+
+### useInfiniteRead
+
+Bidirectional paginated data fetching with infinite scroll support.
+
+```typescript
+function PostList() {
+  const {
+    data,
+    allResponses,
+    loading,
+    canFetchNext,
+    canFetchPrev,
+    fetchNext,
+    fetchPrev,
+    fetchingNext,
+    fetchingPrev,
+  } = useInfiniteRead(
+    (api) => api.posts.$get({ query: { page: 1 } }),
+    {
+      // Required: Check if next page exists
+      canFetchNext: ({ response }) => response?.meta.hasMore ?? false,
+
+      // Required: Build request for next page
+      nextPageRequest: ({ response, request }) => ({
+        query: { ...request.query, page: (response?.meta.page ?? 0) + 1 },
+      }),
+
+      // Required: Merge all responses into items
+      merger: (allResponses) => allResponses.flatMap((r) => r.items),
+
+      // Optional: Check if previous page exists
+      canFetchPrev: ({ response }) => (response?.meta.page ?? 1) > 1,
+
+      // Optional: Build request for previous page
+      prevPageRequest: ({ response, request }) => ({
+        query: { ...request.query, page: (response?.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>
+  );
+}
+```
+
+## 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    |
+| `refetch`  | `() => Promise`       | Manually trigger refetch |
+| `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 |
+| `reset`   | `() => void`           | Reset state                        |
+| `abort`   | `() => void`           | Abort current request              |
+
+### useInfiniteRead(readFn, options)
+
+| Option            | Type                         | Required | Description                     |
+| ----------------- | ---------------------------- | -------- | ------------------------------- |
+| `canFetchNext`    | `(ctx) => boolean`           | Yes      | Check if next page exists       |
+| `nextPageRequest` | `(ctx) => Partial<TRequest>` | Yes      | Build request for next page     |
+| `merger`          | `(allResponses) => TItem[]`  | Yes      | Merge all responses into items  |
+| `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:**
+
+```typescript
+type Context<TData, TRequest> = {
+  response: TData | undefined; // Latest response
+  allResponses: TData[]; // All fetched responses
+  request: TRequest; // Current request options
+};
+```
+
+**Returns:**
+
+| Property       | Type                   | Description                     |
+| -------------- | ---------------------- | ------------------------------- |
+| `data`         | `TItem[] \| undefined` | Merged items from all responses |
+| `allResponses` | `TData[] \| undefined` | Array of all raw responses      |
+| `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         |
+| `refetch`      | `() => Promise<void>`  | Refetch all pages               |
+| `abort`        | `() => void`           | Abort current request           |
+| `error`        | `TError \| undefined`  | Error if request failed         |

package/dist/index.d.mts

@@ -0,0 +1,411 @@
+import * as _spoosh_core from '@spoosh/core';
+import { QueryOnlyClient, MethodOptionsMap, CoreRequestOptionsBase, TagOptions, SpooshResponse, MutationOnlyClient, SpooshPlugin, PluginTypeConfig, SpooshOptions, MergePluginResults, StateManager, EventEmitter, PluginExecutor, PluginArray, MergePluginOptions, ResolverContext, ResolveResultTypes, MergePluginInstanceApi } from '@spoosh/core';
+
+type QueryRequestOptions = CoreRequestOptionsBase;
+type MutationRequestOptions = CoreRequestOptionsBase;
+type ReactOptionsMap = MethodOptionsMap<QueryRequestOptions, MutationRequestOptions>;
+type PluginHooksConfig<TPlugins extends readonly SpooshPlugin<PluginTypeConfig>[]> = {
+    baseUrl: string;
+    defaultOptions?: SpooshOptions;
+    plugins: TPlugins;
+};
+/**
+ * Base options for `useRead` hook.
+ */
+type BaseReadOptions = TagOptions & {
+    /** Whether to fetch automatically on mount. Default: true */
+    enabled?: boolean;
+};
+
+/**
+ * Result returned by `useRead` hook.
+ *
+ * @template TData - The response data type
+ * @template TError - The error type
+ */
+type BaseReadResult<TData, TError> = {
+    /** True during the initial load (no data yet) */
+    loading: boolean;
+    /** True during any fetch operation */
+    fetching: boolean;
+    /** Response data from the API */
+    data: TData | undefined;
+    /** Error from the last failed request */
+    error: TError | undefined;
+    /** Abort the current fetch operation */
+    abort: () => void;
+    /** Manually trigger a refetch */
+    refetch: () => Promise<SpooshResponse<TData, TError>>;
+};
+/**
+ * Result returned by `useWrite` hook.
+ *
+ * @template TData - The response data type
+ * @template TError - The error type
+ * @template TOptions - The trigger options type
+ */
+type BaseWriteResult<TData, TError, TOptions> = {
+    /** Execute the mutation with optional options */
+    trigger: (options?: TOptions) => Promise<SpooshResponse<TData, TError>>;
+    /** True while the mutation is in progress */
+    loading: boolean;
+    /** Response data from the API */
+    data: TData | undefined;
+    /** Error from the last failed request */
+    error: TError | undefined;
+    /** Reset the state to initial values */
+    reset: () => void;
+    /** Abort the current mutation */
+    abort: () => void;
+};
+type OptionalQueryField<TQuery> = [TQuery] extends [never] ? object : {
+    query: TQuery;
+};
+type OptionalBodyField<TBody> = [TBody] extends [never] ? object : {
+    body: TBody;
+};
+type OptionalFormDataField<TFormData> = [TFormData] extends [never] ? object : {
+    formData: TFormData;
+};
+type OptionalParamsField<TParamNames extends string> = [TParamNames] extends [
+    never
+] ? object : {
+    params: Record<TParamNames, string | number>;
+};
+type InputFields<TQuery, TBody, TFormData, TParamNames extends string> = OptionalQueryField<TQuery> & OptionalBodyField<TBody> & OptionalFormDataField<TFormData> & OptionalParamsField<TParamNames>;
+type WriteResponseInputFields<TQuery, TBody, TFormData, TParamNames extends string> = [TQuery, TBody, TFormData, TParamNames] extends [never, never, never, never] ? object : {
+    input: InputFields<TQuery, TBody, TFormData, TParamNames> | undefined;
+};
+type UseReadResult<TData, TError, TPlugins extends readonly SpooshPlugin<PluginTypeConfig>[]> = BaseReadResult<TData, TError> & MergePluginResults<TPlugins>["read"];
+type UseWriteResult<TData, TError, TOptions, TPlugins extends readonly SpooshPlugin<PluginTypeConfig>[]> = BaseWriteResult<TData, TError, TOptions> & MergePluginResults<TPlugins>["write"];
+type ReadApiClient<TSchema, TDefaultError> = QueryOnlyClient<TSchema, TDefaultError, ReactOptionsMap>;
+type WriteApiClient<TSchema, TDefaultError> = MutationOnlyClient<TSchema, TDefaultError, ReactOptionsMap>;
+type SuccessResponse<T> = Extract<T, {
+    data: unknown;
+    error?: undefined;
+}>;
+type ErrorResponse<T> = Extract<T, {
+    error: unknown;
+    data?: undefined;
+}>;
+type ExtractMethodData<T> = T extends (...args: never[]) => infer R ? SuccessResponse<Awaited<R>> extends {
+    data: infer D;
+} ? D : unknown : unknown;
+type ExtractMethodError<T> = T extends (...args: never[]) => infer R ? ErrorResponse<Awaited<R>> extends {
+    error: infer E;
+} ? E : unknown : unknown;
+type ExtractMethodOptions<T> = T extends (...args: infer A) => unknown ? A[0] : never;
+type ExtractMethodQuery<T> = ExtractMethodOptions<T> extends {
+    query: infer Q;
+} ? Q : never;
+type ExtractMethodBody<T> = ExtractMethodOptions<T> extends {
+    body: infer B;
+} ? B : never;
+type ExtractMethodFormData<T> = ExtractMethodOptions<T> extends {
+    formData: infer F;
+} ? F : never;
+type ExtractMethodUrlEncoded<T> = ExtractMethodOptions<T> extends {
+    urlEncoded: infer U;
+} ? U : never;
+type AwaitedReturnType<T> = T extends (...args: never[]) => infer R ? Awaited<R> : never;
+type SuccessReturnType<T> = SuccessResponse<AwaitedReturnType<T>>;
+type ExtractResponseQuery<T> = SuccessReturnType<T> extends {
+    input: {
+        query: infer Q;
+    };
+} ? Q : never;
+type ExtractResponseBody<T> = SuccessReturnType<T> extends {
+    input: {
+        body: infer B;
+    };
+} ? B : never;
+type ExtractResponseFormData<T> = SuccessReturnType<T> extends {
+    input: {
+        formData: infer F;
+    };
+} ? F : never;
+type ExtractResponseParamNames<T> = SuccessReturnType<T> extends {
+    input: {
+        params: Record<infer K, unknown>;
+    };
+} ? K extends string ? K : never : never;
+type QueryField<TQuery> = [TQuery] extends [never] ? object : {
+    query: TQuery;
+};
+type BodyField<TBody> = [TBody] extends [never] ? object : {
+    body: TBody;
+};
+type FormDataField<TFormData> = [TFormData] extends [never] ? object : {
+    formData: TFormData;
+};
+type ParamsField<TParamNames extends string> = [TParamNames] extends [never] ? object : {
+    params: Record<TParamNames, string | number>;
+};
+type ReadInputFields<TQuery, TBody, TFormData, TParamNames extends string> = QueryField<TQuery> & BodyField<TBody> & FormDataField<TFormData> & ParamsField<TParamNames>;
+type ResponseInputFields<TQuery, TBody, TFormData, TParamNames extends string> = [TQuery, TBody, TFormData, TParamNames] extends [never, never, never, never] ? object : {
+    input: ReadInputFields<TQuery, TBody, TFormData, TParamNames>;
+};
+type AnyInfiniteRequestOptions = {
+    query?: Record<string, unknown>;
+    params?: Record<string, string | number>;
+    body?: unknown;
+};
+/**
+ * Context passed to `canFetchNext` and `nextPageRequest` callbacks.
+ */
+type InfiniteNextContext<TData, TRequest> = {
+    /** The latest fetched response data */
+    response: TData | undefined;
+    /** All responses fetched so far */
+    allResponses: TData[];
+    /** The current request options (query, params, body) */
+    request: TRequest;
+};
+/**
+ * Context passed to `canFetchPrev` and `prevPageRequest` callbacks.
+ */
+type InfinitePrevContext<TData, TRequest> = {
+    /** The latest fetched response data */
+    response: TData | undefined;
+    /** All responses fetched so far */
+    allResponses: TData[];
+    /** The current request options (query, params, body) */
+    request: TRequest;
+};
+/**
+ * Options for `useInfiniteRead` hook.
+ *
+ * @template TData - The response data type for each page
+ * @template TItem - The item type after merging all responses
+ * @template TRequest - The request options type (query, params, body)
+ */
+type BaseInfiniteReadOptions<TData, TItem, TRequest = AnyInfiniteRequestOptions> = TagOptions & {
+    /** Whether to fetch automatically on mount. Default: true */
+    enabled?: boolean;
+    /** Callback to determine if there's a next page to fetch */
+    canFetchNext: (ctx: InfiniteNextContext<TData, TRequest>) => boolean;
+    /** Callback to build the request options for the next page */
+    nextPageRequest: (ctx: InfiniteNextContext<TData, TRequest>) => Partial<TRequest>;
+    /** Callback to merge all responses into a single array of items */
+    merger: (allResponses: TData[]) => TItem[];
+    /** Callback to determine if there's a previous page to fetch */
+    canFetchPrev?: (ctx: InfinitePrevContext<TData, TRequest>) => boolean;
+    /** Callback to build the request options for the previous page */
+    prevPageRequest?: (ctx: InfinitePrevContext<TData, TRequest>) => Partial<TRequest>;
+};
+/**
+ * Result returned by `useInfiniteRead` hook.
+ *
+ * @template TData - The response data type for each page
+ * @template TError - The error type
+ * @template TItem - The item type after merging all responses
+ */
+type BaseInfiniteReadResult<TData, TError, TItem> = {
+    /** Merged items from all fetched responses */
+    data: TItem[] | undefined;
+    /** Array of all raw response data */
+    allResponses: TData[] | undefined;
+    /** True during the initial load (no data yet) */
+    loading: boolean;
+    /** True during any fetch operation */
+    fetching: boolean;
+    /** True while fetching the next page */
+    fetchingNext: boolean;
+    /** True while fetching the previous page */
+    fetchingPrev: boolean;
+    /** Whether there's a next page available to fetch */
+    canFetchNext: boolean;
+    /** Whether there's a previous page available to fetch */
+    canFetchPrev: boolean;
+    /** Fetch the next page */
+    fetchNext: () => Promise<void>;
+    /** Fetch the previous page */
+    fetchPrev: () => Promise<void>;
+    /** Refetch all pages from the beginning */
+    refetch: () => Promise<void>;
+    /** Abort the current fetch operation */
+    abort: () => void;
+    /** Error from the last failed request */
+    error: TError | undefined;
+};
+type UseInfiniteReadResult<TData, TError, TItem, TPlugins extends readonly SpooshPlugin<PluginTypeConfig>[]> = BaseInfiniteReadResult<TData, TError, TItem> & MergePluginResults<TPlugins>["read"];
+type InfiniteReadApiClient<TSchema, TDefaultError> = QueryOnlyClient<TSchema, TDefaultError, ReactOptionsMap>;
+
+type InferError<T, TDefaultError> = [T] extends [unknown] ? TDefaultError : T;
+type ExtractParamsRecord<T> = ExtractResponseParamNames<T> extends never ? never : Record<ExtractResponseParamNames<T>, string | number>;
+type ReadResolverContext<TSchema, TReadFn, TDefaultError> = ResolverContext<TSchema, ExtractMethodData<TReadFn>, InferError<ExtractMethodError<TReadFn>, TDefaultError>, ExtractResponseQuery<TReadFn>, ExtractResponseBody<TReadFn>, ExtractParamsRecord<TReadFn>, ExtractResponseFormData<TReadFn>>;
+type ResolvedReadOptions<TSchema, TPlugins extends PluginArray, TReadFn, TDefaultError> = _spoosh_core.ResolveTypes<MergePluginOptions<TPlugins>["read"], ReadResolverContext<TSchema, TReadFn, TDefaultError>>;
+type WriteResolverContext<TSchema, TMethod, TDefaultError> = ResolverContext<TSchema, ExtractMethodData<TMethod>, InferError<ExtractMethodError<TMethod>, TDefaultError>, ExtractMethodQuery<TMethod>, ExtractMethodBody<TMethod>, ExtractResponseParamNames<TMethod> extends never ? never : Record<ExtractResponseParamNames<TMethod>, string | number>, ExtractMethodFormData<TMethod>, ExtractMethodUrlEncoded<TMethod>>;
+type ResolvedWriteOptions<TSchema, TPlugins extends PluginArray, TMethod, TDefaultError> = _spoosh_core.ResolveTypes<MergePluginOptions<TPlugins>["write"], WriteResolverContext<TSchema, TMethod, TDefaultError>>;
+type UseReadFn<TDefaultError, TSchema, TPlugins extends PluginArray> = <TReadFn extends (api: ReadApiClient<TSchema, TDefaultError>) => Promise<{
+    data?: unknown;
+    error?: unknown;
+}>, TReadOpts extends BaseReadOptions & ResolvedReadOptions<TSchema, TPlugins, TReadFn, TDefaultError> = BaseReadOptions & ResolvedReadOptions<TSchema, TPlugins, TReadFn, TDefaultError>>(readFn: TReadFn, readOptions?: TReadOpts) => BaseReadResult<ExtractMethodData<TReadFn>, InferError<ExtractMethodError<TReadFn>, TDefaultError>> & ResponseInputFields<ExtractResponseQuery<TReadFn>, ExtractResponseBody<TReadFn>, ExtractResponseFormData<TReadFn>, ExtractResponseParamNames<TReadFn>> & ResolveResultTypes<MergePluginResults<TPlugins>["read"], TReadOpts>;
+type UseWriteFn<TDefaultError, TSchema, TPlugins extends PluginArray> = <TMethod extends (...args: never[]) => Promise<SpooshResponse<unknown, unknown>>, TWriteOpts extends (TMethod extends (options: infer O) => unknown ? O : object) & ResolvedWriteOptions<TSchema, TPlugins, TMethod, TDefaultError> = (TMethod extends (options: infer O) => unknown ? O : object) & ResolvedWriteOptions<TSchema, TPlugins, TMethod, TDefaultError>>(writeFn: (api: WriteApiClient<TSchema, TDefaultError>) => TMethod) => BaseWriteResult<ExtractMethodData<TMethod>, InferError<ExtractMethodError<TMethod>, TDefaultError>, TWriteOpts> & WriteResponseInputFields<ExtractResponseQuery<TMethod>, ExtractResponseBody<TMethod>, ExtractResponseFormData<TMethod>, ExtractResponseParamNames<TMethod>> & ResolveResultTypes<MergePluginResults<TPlugins>["write"], TWriteOpts>;
+type InfiniteReadResolverContext<TSchema, TData, TError, TRequest> = ResolverContext<TSchema, TData, TError, TRequest extends {
+    query: infer Q;
+} ? Q : never, TRequest extends {
+    body: infer B;
+} ? B : never, TRequest extends {
+    params: infer P;
+} ? P : never, never>;
+type ResolvedInfiniteReadOptions<TSchema, TPlugins extends PluginArray, TData, TError, TRequest> = _spoosh_core.ResolveTypes<MergePluginOptions<TPlugins>["infiniteRead"], InfiniteReadResolverContext<TSchema, TData, TError, TRequest>>;
+type UseInfiniteReadFn<TDefaultError, TSchema, TPlugins extends PluginArray> = <TData, TItem, TError = TDefaultError, TRequest extends AnyInfiniteRequestOptions = AnyInfiniteRequestOptions>(readFn: (api: InfiniteReadApiClient<TSchema, TDefaultError>) => Promise<SpooshResponse<TData, TError>>, readOptions: BaseInfiniteReadOptions<TData, TItem, TRequest> & ResolvedInfiniteReadOptions<TSchema, TPlugins, TData, TError, TRequest>) => BaseInfiniteReadResult<TData, TError, TItem> & MergePluginResults<TPlugins>["read"];
+/**
+ * Spoosh React hooks interface containing useRead, useWrite, and useInfiniteRead.
+ *
+ * @template TDefaultError - The default error type
+ * @template TSchema - The API schema type
+ * @template TPlugins - The plugins array type
+ */
+type SpooshReactHooks<TDefaultError, TSchema, TPlugins extends PluginArray> = {
+    /**
+     * React hook for fetching data from an API endpoint with automatic caching and revalidation.
+     *
+     * @param readFn - Function that selects the API endpoint to call (e.g., `(api) => api.posts.$get()`)
+     * @param readOptions - Optional configuration including `enabled`, `tags`, and plugin-specific options
+     * @returns Object containing `data`, `error`, `loading`, `fetching`, `refetch`, and `abort`
+     *
+     * @example
+     * ```tsx
+     * const { data, loading, error } = useRead((api) => api.posts.$get());
+     *
+     * const { data: post } = useRead(
+     *   (api) => api.posts[postId].$get(),
+     *   { enabled: !!postId }
+     * );
+     * ```
+     */
+    useRead: UseReadFn<TDefaultError, TSchema, TPlugins>;
+    /**
+     * React hook for mutations (POST, PUT, PATCH, DELETE) with manual triggering.
+     *
+     * @param writeFn - Function that selects the API endpoint (e.g., `(api) => api.posts.$post`)
+     * @returns Object containing `trigger`, `data`, `error`, `loading`, `reset`, and `abort`
+     *
+     * @example
+     * ```tsx
+     * const { trigger, loading, data } = useWrite((api) => api.posts.$post);
+     *
+     * const handleSubmit = async (formData) => {
+     *   const { data, error } = await trigger({ body: formData });
+     *   if (data) console.log('Created:', data);
+     * };
+     * ```
+     */
+    useWrite: UseWriteFn<TDefaultError, TSchema, TPlugins>;
+    /**
+     * React hook for infinite/paginated data fetching with automatic pagination control.
+     *
+     * @param readFn - Function that selects the API endpoint to call
+     * @param readOptions - Configuration including `canFetchNext`, `nextPageRequest`, `merger`, and optional `canFetchPrev`/`prevPageRequest`
+     * @returns Object containing `data`, `allResponses`, `fetchNext`, `fetchPrev`, `canFetchNext`, `canFetchPrev`, `loading`, `fetching`, and pagination states
+     *
+     * @example
+     * ```tsx
+     * const { data, fetchNext, canFetchNext, loading } = useInfiniteRead(
+     *   (api) => api.posts.$get(),
+     *   {
+     *     canFetchNext: ({ response }) => !!response?.nextCursor,
+     *     nextPageRequest: ({ response }) => ({ query: { cursor: response?.nextCursor } }),
+     *     merger: (responses) => responses.flatMap(r => r.items)
+     *   }
+     * );
+     * ```
+     */
+    useInfiniteRead: UseInfiniteReadFn<TDefaultError, TSchema, TPlugins>;
+} & MergePluginInstanceApi<TPlugins, TSchema>;
+/**
+ * Shape of a Spoosh instance required for creating React hooks.
+ */
+type SpooshInstanceShape<TApi, TSchema, TDefaultError, TPlugins> = {
+    /** The API client instance */
+    api: TApi;
+    /** State manager for caching and state */
+    stateManager: StateManager;
+    /** Event emitter for refetch and invalidation events */
+    eventEmitter: EventEmitter;
+    /** Plugin executor for running plugins */
+    pluginExecutor: PluginExecutor;
+    /** Type information (not used at runtime) */
+    _types: {
+        schema: TSchema;
+        defaultError: TDefaultError;
+        plugins: TPlugins;
+    };
+};
+
+/**
+ * Creates React hooks (useRead, useWrite, useInfiniteRead) from a Spoosh instance.
+ *
+ * @template TSchema - The API schema type
+ * @template TDefaultError - The default error type
+ * @template TPlugins - The plugins array type
+ * @template TApi - The API client type
+ * @param instance - The Spoosh instance containing api, stateManager, eventEmitter, and pluginExecutor
+ * @returns An object containing useRead, useWrite, useInfiniteRead hooks and plugin instance APIs
+ *
+ * @example
+ * ```ts
+ * const { useRead, useWrite, useInfiniteRead } = createReactSpoosh(spooshInstance);
+ *
+ * function MyComponent() {
+ *   const { data, loading } = useRead((api) => api.posts.$get());
+ *   return <div>{loading ? 'Loading...' : data?.title}</div>;
+ * }
+ * ```
+ */
+declare function createReactSpoosh<TSchema, TDefaultError, TPlugins extends PluginArray, TApi>(instance: SpooshInstanceShape<TApi, TSchema, TDefaultError, TPlugins>): SpooshReactHooks<TDefaultError, TSchema, TPlugins>;
+
+declare function createUseRead<TSchema, TDefaultError, TPlugins extends readonly SpooshPlugin<PluginTypeConfig>[]>(options: Omit<SpooshInstanceShape<unknown, TSchema, TDefaultError, TPlugins>, "_types">): <TReadFn extends (api: ReadApiClient<TSchema, TDefaultError>) => Promise<{
+    data?: unknown;
+    error?: unknown;
+}>, TReadOpts extends BaseReadOptions & (((TPlugins[number] extends infer T_3 ? T_3 extends TPlugins[number] ? T_3 extends SpooshPlugin<infer Types_1 extends PluginTypeConfig> ? Types_1 extends {
+    readOptions: infer R_1;
+} ? R_1 : object : object : never : never) extends infer T_4 ? T_4 extends (TPlugins[number] extends infer T_5 ? T_5 extends TPlugins[number] ? T_5 extends SpooshPlugin<infer Types_1 extends PluginTypeConfig> ? Types_1 extends {
+    readOptions: infer R_1;
+} ? R_1 : object : object : never : never) ? T_4 extends unknown ? (x: T_4) => void : never : never : never) extends (x: infer I) => void ? I : never) = BaseReadOptions & (((TPlugins[number] extends infer T_6 ? T_6 extends TPlugins[number] ? T_6 extends SpooshPlugin<infer Types_1 extends PluginTypeConfig> ? Types_1 extends {
+    readOptions: infer R_1;
+} ? R_1 : object : object : never : never) extends infer T_7 ? T_7 extends (TPlugins[number] extends infer T_8 ? T_8 extends TPlugins[number] ? T_8 extends SpooshPlugin<infer Types_1 extends PluginTypeConfig> ? Types_1 extends {
+    readOptions: infer R_1;
+} ? R_1 : object : object : never : never) ? T_7 extends unknown ? (x: T_7) => void : never : never : never) extends (x: infer I) => void ? I : never)>(readFn: TReadFn, readOptions?: TReadOpts) => BaseReadResult<TReadFn extends (...args: unknown[]) => Promise<{
+    data: infer D;
+}> ? D : unknown, [TReadFn extends (...args: unknown[]) => Promise<{
+    error: infer E;
+}> ? E : unknown] extends [unknown] ? TDefaultError : TReadFn extends (...args: unknown[]) => Promise<{
+    error: infer E;
+}> ? E : unknown> & ResponseInputFields<ExtractResponseQuery<TReadFn>, ExtractResponseBody<TReadFn>, ExtractResponseFormData<TReadFn>, ExtractResponseParamNames<TReadFn>> & ResolveResultTypes<((TPlugins[number] extends infer T ? T extends TPlugins[number] ? T extends SpooshPlugin<infer Types extends PluginTypeConfig> ? Types extends {
+    readResult: infer R;
+} ? R : object : object : never : never) extends infer T_1 ? T_1 extends (TPlugins[number] extends infer T_2 ? T_2 extends TPlugins[number] ? T_2 extends SpooshPlugin<infer Types extends PluginTypeConfig> ? Types extends {
+    readResult: infer R;
+} ? R : object : object : never : never) ? T_1 extends unknown ? (x: T_1) => void : never : never : never) extends (x: infer I) => void ? I : never, TReadOpts>;
+
+declare function createUseWrite<TSchema, TDefaultError, TPlugins extends readonly SpooshPlugin<PluginTypeConfig>[]>(options: Omit<SpooshInstanceShape<unknown, TSchema, TDefaultError, TPlugins>, "_types">): <TMethod extends (...args: never[]) => Promise<SpooshResponse<unknown, unknown>>>(writeFn: (api: WriteApiClient<TSchema, TDefaultError>) => TMethod) => BaseWriteResult<ExtractMethodData<TMethod>, [ExtractMethodError<TMethod>] extends [unknown] ? TDefaultError : ExtractMethodError<TMethod>, ExtractMethodOptions<TMethod> & _spoosh_core.ResolveTypes<((TPlugins[number] extends infer T ? T extends TPlugins[number] ? T extends SpooshPlugin<infer Types extends PluginTypeConfig> ? Types extends {
+    writeOptions: infer W;
+} ? W : object : object : never : never) extends infer T_1 ? T_1 extends (TPlugins[number] extends infer T_2 ? T_2 extends TPlugins[number] ? T_2 extends SpooshPlugin<infer Types extends PluginTypeConfig> ? Types extends {
+    writeOptions: infer W;
+} ? W : object : object : never : never) ? T_1 extends unknown ? (x: T_1) => void : never : never : never) extends (x: infer I) => void ? I : never, ResolverContext<TSchema, ExtractMethodData<TMethod>, [ExtractMethodError<TMethod>] extends [unknown] ? TDefaultError : ExtractMethodError<TMethod>, ExtractMethodQuery<TMethod>, ExtractMethodBody<TMethod>, ExtractResponseParamNames<TMethod> extends never ? never : Record<ExtractResponseParamNames<TMethod>, string | number>, ExtractMethodFormData<TMethod>, ExtractMethodUrlEncoded<TMethod>>>> & WriteResponseInputFields<ExtractResponseQuery<TMethod>, ExtractResponseBody<TMethod>, ExtractResponseFormData<TMethod>, ExtractResponseParamNames<TMethod>> & ResolveResultTypes<((TPlugins[number] extends infer T_3 ? T_3 extends TPlugins[number] ? T_3 extends SpooshPlugin<infer Types_1 extends PluginTypeConfig> ? Types_1 extends {
+    writeResult: infer W_1;
+} ? W_1 : object : object : never : never) extends infer T_4 ? T_4 extends (TPlugins[number] extends infer T_5 ? T_5 extends TPlugins[number] ? T_5 extends SpooshPlugin<infer Types_1 extends PluginTypeConfig> ? Types_1 extends {
+    writeResult: infer W_1;
+} ? W_1 : object : object : never : never) ? T_4 extends unknown ? (x: T_4) => void : never : never : never) extends (x: infer I) => void ? I : never, ExtractMethodOptions<TMethod> & _spoosh_core.ResolveTypes<((TPlugins[number] extends infer T_6 ? T_6 extends TPlugins[number] ? T_6 extends SpooshPlugin<infer Types extends PluginTypeConfig> ? Types extends {
+    writeOptions: infer W;
+} ? W : object : object : never : never) extends infer T_7 ? T_7 extends (TPlugins[number] extends infer T_8 ? T_8 extends TPlugins[number] ? T_8 extends SpooshPlugin<infer Types extends PluginTypeConfig> ? Types extends {
+    writeOptions: infer W;
+} ? W : object : object : never : never) ? T_7 extends unknown ? (x: T_7) => void : never : never : never) extends (x: infer I) => void ? I : never, ResolverContext<TSchema, ExtractMethodData<TMethod>, [ExtractMethodError<TMethod>] extends [unknown] ? TDefaultError : ExtractMethodError<TMethod>, ExtractMethodQuery<TMethod>, ExtractMethodBody<TMethod>, ExtractResponseParamNames<TMethod> extends never ? never : Record<ExtractResponseParamNames<TMethod>, string | number>, ExtractMethodFormData<TMethod>, ExtractMethodUrlEncoded<TMethod>>>>;
+
+declare function createUseInfiniteRead<TSchema, TDefaultError, TPlugins extends readonly SpooshPlugin<PluginTypeConfig>[]>(options: Omit<SpooshInstanceShape<unknown, TSchema, TDefaultError, TPlugins>, "_types">): <TData, TItem, TError = TDefaultError, TRequest extends AnyInfiniteRequestOptions = AnyInfiniteRequestOptions, TReadOpts extends BaseInfiniteReadOptions<TData, TItem, TRequest> & (((TPlugins[number] extends infer T_3 ? T_3 extends TPlugins[number] ? T_3 extends SpooshPlugin<infer Types_1 extends PluginTypeConfig> ? Types_1 extends {
+    infiniteReadOptions: infer I_1;
+} ? I_1 : object : object : never : never) extends infer T_4 ? T_4 extends (TPlugins[number] extends infer T_5 ? T_5 extends TPlugins[number] ? T_5 extends SpooshPlugin<infer Types_1 extends PluginTypeConfig> ? Types_1 extends {
+    infiniteReadOptions: infer I_1;
+} ? I_1 : object : object : never : never) ? T_4 extends unknown ? (x: T_4) => void : never : never : never) extends (x: infer I) => void ? I : never) = BaseInfiniteReadOptions<TData, TItem, TRequest> & (((TPlugins[number] extends infer T_6 ? T_6 extends TPlugins[number] ? T_6 extends SpooshPlugin<infer Types_1 extends PluginTypeConfig> ? Types_1 extends {
+    infiniteReadOptions: infer I_1;
+} ? I_1 : object : object : never : never) extends infer T_7 ? T_7 extends (TPlugins[number] extends infer T_8 ? T_8 extends TPlugins[number] ? T_8 extends SpooshPlugin<infer Types_1 extends PluginTypeConfig> ? Types_1 extends {
+    infiniteReadOptions: infer I_1;
+} ? I_1 : object : object : never : never) ? T_7 extends unknown ? (x: T_7) => void : never : never : never) extends (x: infer I) => void ? I : never)>(readFn: (api: InfiniteReadApiClient<TSchema, TDefaultError>) => Promise<SpooshResponse<TData, TError>>, readOptions: TReadOpts) => BaseInfiniteReadResult<TData, TError, TItem> & ResolveResultTypes<((TPlugins[number] extends infer T ? T extends TPlugins[number] ? T extends SpooshPlugin<infer Types extends PluginTypeConfig> ? Types extends {
+    readResult: infer R;
+} ? R : object : object : never : never) extends infer T_1 ? T_1 extends (TPlugins[number] extends infer T_2 ? T_2 extends TPlugins[number] ? T_2 extends SpooshPlugin<infer Types extends PluginTypeConfig> ? Types extends {
+    readResult: infer R;
+} ? R : object : object : never : never) ? T_1 extends unknown ? (x: T_1) => void : never : never : never) extends (x: infer I) => void ? I : never, TReadOpts>;
+
+export { type BaseInfiniteReadOptions, type BaseInfiniteReadResult, type BaseReadOptions, type BaseReadResult, type BaseWriteResult, type PluginHooksConfig, type SpooshReactHooks, type UseInfiniteReadResult, type UseReadResult, type UseWriteResult, createReactSpoosh, createUseInfiniteRead, createUseRead, createUseWrite };