@spoosh/react 0.5.1 → 0.6.0

package/README.md

@@ -1,6 +1,6 @@
 # @spoosh/react
 
-React hooks for Spoosh - `useRead`, `useWrite`, and `useInfiniteRead`.
+React hooks for Spoosh - `useRead`, `useLazyRead`, `useWrite`, and `useInfiniteRead`.
 
 **[Documentation](https://spoosh.dev/docs/integrations/react)** · **Requirements:** TypeScript >= 5.0, React >= 18.0
 
@@ -23,7 +23,8 @@ const spoosh = new Spoosh<ApiSchema, Error>("/api").use([
   cachePlugin({ staleTime: 5000 }),
 ]);
 
-export const { useRead, useWrite, useInfiniteRead } = createReactSpoosh(spoosh);
+export const { useRead, useLazyRead, useWrite, useInfiniteRead } =
+  createReactSpoosh(spoosh);
 ```
 
 ### useRead
@@ -32,7 +33,7 @@ Fetch data with automatic caching and refetching.
 
 ```typescript
 function UserList() {
-  const { data, loading, error, refetch } = useRead(
+  const { data, loading, error, trigger } = useRead(
     (api) => api("users").GET()
   );
 
@@ -62,6 +63,27 @@ const { data: user } = useRead(
 );
 ```
 
+### useLazyRead
+
+Lazy data fetching for print/download/export scenarios. Does not auto-fetch on mount.
+
+```typescript
+function PrintOrder() {
+  const { trigger, loading } = useLazyRead((api) => api("orders/:id").GET);
+
+  const handlePrint = async (orderId: string) => {
+    const { data } = await trigger({ params: { id: orderId } });
+    if (data) printReceipt(data);
+  };
+
+  return (
+    <button onClick={() => handlePrint("123")} disabled={loading}>
+      {loading ? "Loading..." : "Print"}
+    </button>
+  );
+}
+```
+
 ### useWrite
 
 Trigger mutations with loading and error states.
@@ -177,7 +199,7 @@ function PostList() {
 | `error`    | `TError \| undefined` | Error if request failed  |
 | `loading`  | `boolean`             | True during initial load |
 | `fetching` | `boolean`             | True during any fetch    |
-| `refetch`  | `() => Promise`       | Manually trigger refetch |
+| `trigger`  | `() => Promise`       | Manually trigger fetch   |
 | `abort`    | `() => void`          | Abort current request    |
 
 ### useWrite(writeFn)
@@ -190,7 +212,6 @@ function PostList() {
 | `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)

package/dist/index.d.mts

@@ -41,8 +41,8 @@ type BaseReadResult<TData, TError, TMeta = Record<string, unknown>> = {
     meta: TMeta;
     /** Abort the current fetch operation */
     abort: () => void;
-    /** Manually trigger a refetch */
-    refetch: () => Promise<SpooshResponse<TData, TError>>;
+    /** Manually trigger a fetch */
+    trigger: () => Promise<SpooshResponse<TData, TError>>;
 };
 /**
  * Result returned by `useWrite` hook.
@@ -63,11 +63,28 @@ type BaseWriteResult<TData, TError, TOptions, TMeta = Record<string, unknown>> =
     error: TError | undefined;
     /** Plugin-provided metadata */
     meta: TMeta;
-    /** Reset the state to initial values */
-    reset: () => void;
     /** Abort the current mutation */
     abort: () => void;
 };
+/**
+ * Result returned by `useLazyRead` hook.
+ *
+ * @template TData - The response data type
+ * @template TError - The error type
+ * @template TOptions - The trigger options type
+ */
+type BaseLazyReadResult<TData, TError, TOptions> = {
+    /** Execute the fetch with optional options */
+    trigger: (options?: TOptions) => Promise<SpooshResponse<TData, TError>>;
+    /** True while the fetch is in progress */
+    loading: boolean;
+    /** Response data from the API */
+    data: TData | undefined;
+    /** Error from the last failed request */
+    error: TError | undefined;
+    /** Abort the current fetch */
+    abort: () => void;
+};
 type OptionalQueryField<TQuery> = [TQuery] extends [never] ? object : undefined extends TQuery ? {
     query?: Exclude<TQuery, undefined>;
 } : {
@@ -106,6 +123,7 @@ type ExtractMethodError<T> = T extends (...args: never[]) => infer R ? ErrorResp
     error: infer E;
 } ? E : unknown : unknown;
 type ExtractMethodOptions<T> = T extends (...args: infer A) => unknown ? A[0] : never;
+type ExtractCoreMethodOptions<T> = T extends (...args: infer A) => unknown ? A[0] extends object ? Pick<A[0], Extract<keyof A[0], "query" | "params" | "body">> : object : object;
 type ExtractMethodQuery<T> = ExtractMethodOptions<T> extends {
     query: infer Q;
 } ? Q : never;
@@ -237,8 +255,8 @@ type BaseInfiniteReadResult<TData, TError, TItem, TPluginResult = Record<string,
     fetchNext: () => Promise<void>;
     /** Fetch the previous page */
     fetchPrev: () => Promise<void>;
-    /** Refetch all pages from the beginning */
-    refetch: () => Promise<void>;
+    /** Trigger refetch of all pages from the beginning */
+    trigger: () => Promise<void>;
     /** Abort the current fetch operation */
     abort: () => void;
     /** Error from the last failed request */
@@ -263,6 +281,9 @@ type UseReadFn<TDefaultError, TSchema, TPlugins extends PluginArray> = {
 type UseWriteFn<TDefaultError, TSchema, TPlugins extends PluginArray> = {
     <TMethod extends (...args: never) => Promise<SpooshResponse<unknown, unknown>>>(writeFn: (api: WriteApiClient<TSchema, TDefaultError>) => TMethod): BaseWriteResult<ExtractMethodData<TMethod>, InferError<ExtractMethodError<TMethod>, TDefaultError>, Parameters<TMethod>[0] & ResolvedWriteOptions<TSchema, TPlugins, TMethod, TDefaultError>, MergePluginResults<TPlugins>["write"]> & WriteResponseInputFields<ExtractMethodQuery<TMethod>, ExtractMethodBody<TMethod>, ExtractResponseParamNames<TMethod>>;
 };
+type UseLazyReadFn<TDefaultError, TSchema> = {
+    <TMethod extends (...args: never) => Promise<SpooshResponse<unknown, unknown>>>(readFn: (api: ReadApiClient<TSchema, TDefaultError>) => TMethod): BaseLazyReadResult<ExtractMethodData<TMethod>, InferError<ExtractMethodError<TMethod>, TDefaultError>, ExtractCoreMethodOptions<TMethod>> & WriteResponseInputFields<ExtractResponseQuery<TMethod>, ExtractResponseBody<TMethod>, ExtractResponseParamNames<TMethod>>;
+};
 type InfiniteReadResolverContext<TSchema, TData, TError, TRequest> = ResolverContext<TSchema, TData, TError, TRequest extends {
     query: infer Q;
 } ? Q : never, TRequest extends {
@@ -285,7 +306,7 @@ type SpooshReactHooks<TDefaultError, TSchema, TPlugins extends PluginArray> = {
      *
      * @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`
+     * @returns Object containing `data`, `error`, `loading`, `fetching`, `trigger`, and `abort`
      *
      * @example
      * ```tsx
@@ -302,7 +323,7 @@ type SpooshReactHooks<TDefaultError, TSchema, TPlugins extends PluginArray> = {
      * 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`
+     * @returns Object containing `trigger`, `data`, `error`, `loading`, and `abort`
      *
      * @example
      * ```tsx
@@ -315,6 +336,23 @@ type SpooshReactHooks<TDefaultError, TSchema, TPlugins extends PluginArray> = {
      * ```
      */
     useWrite: UseWriteFn<TDefaultError, TSchema, TPlugins>;
+    /**
+     * React hook for lazy GET requests with manual triggering (does not auto-fetch on mount).
+     *
+     * @param readFn - Function that selects the API endpoint (e.g., `(api) => api("posts").GET`)
+     * @returns Object containing `trigger`, `data`, `error`, `loading`, and `abort`
+     *
+     * @example
+     * ```tsx
+     * const { trigger, loading, data } = useLazyRead((api) => api("posts/:id").GET);
+     *
+     * const handleClick = async (id) => {
+     *   const { data, error } = await trigger({ params: { id } });
+     *   if (data) console.log('Fetched:', data);
+     * };
+     * ```
+     */
+    useLazyRead: UseLazyReadFn<TDefaultError, TSchema>;
     /**
      * React hook for infinite/paginated data fetching with automatic pagination control.
      *
@@ -411,6 +449,8 @@ declare function createUseRead<TSchema, TDefaultError, TPlugins extends readonly
     }> ? E : unknown, MergePluginResults<TPlugins>["read"]> & ResponseInputFields<ExtractResponseQuery<TReadFn>, ExtractResponseBody<TReadFn>, ExtractResponseParamNames<TReadFn>>;
 };
 
+declare function createUseLazyRead<TSchema, TDefaultError, TPlugins extends readonly SpooshPlugin<PluginTypeConfig>[]>(options: Omit<SpooshInstanceShape<unknown, TSchema, TDefaultError, TPlugins>, "_types">): <TMethod extends (...args: never[]) => Promise<SpooshResponse<unknown, unknown>>>(readFn: (api: ReadApiClient<TSchema, TDefaultError>) => TMethod) => BaseLazyReadResult<ExtractMethodData<TMethod>, [ExtractMethodError<TMethod>] extends [unknown] ? TDefaultError : ExtractMethodError<TMethod>, ExtractCoreMethodOptions<TMethod>> & WriteResponseInputFields<ExtractResponseQuery<TMethod>, ExtractResponseBody<TMethod>, ExtractResponseParamNames<TMethod>>;
+
 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> & 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 {
@@ -427,4 +467,4 @@ declare function createUseInfiniteRead<TSchema, TDefaultError, TPlugins 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>;
 
-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 };
+export { type BaseInfiniteReadOptions, type BaseInfiniteReadResult, type BaseLazyReadResult, type BaseReadOptions, type BaseReadResult, type BaseWriteResult, type PluginHooksConfig, type SpooshReactHooks, type UseInfiniteReadResult, type UseReadResult, type UseWriteResult, createReactSpoosh, createUseInfiniteRead, createUseLazyRead, createUseRead, createUseWrite };

package/dist/index.d.ts

@@ -41,8 +41,8 @@ type BaseReadResult<TData, TError, TMeta = Record<string, unknown>> = {
     meta: TMeta;
     /** Abort the current fetch operation */
     abort: () => void;
-    /** Manually trigger a refetch */
-    refetch: () => Promise<SpooshResponse<TData, TError>>;
+    /** Manually trigger a fetch */
+    trigger: () => Promise<SpooshResponse<TData, TError>>;
 };
 /**
  * Result returned by `useWrite` hook.
@@ -63,11 +63,28 @@ type BaseWriteResult<TData, TError, TOptions, TMeta = Record<string, unknown>> =
     error: TError | undefined;
     /** Plugin-provided metadata */
     meta: TMeta;
-    /** Reset the state to initial values */
-    reset: () => void;
     /** Abort the current mutation */
     abort: () => void;
 };
+/**
+ * Result returned by `useLazyRead` hook.
+ *
+ * @template TData - The response data type
+ * @template TError - The error type
+ * @template TOptions - The trigger options type
+ */
+type BaseLazyReadResult<TData, TError, TOptions> = {
+    /** Execute the fetch with optional options */
+    trigger: (options?: TOptions) => Promise<SpooshResponse<TData, TError>>;
+    /** True while the fetch is in progress */
+    loading: boolean;
+    /** Response data from the API */
+    data: TData | undefined;
+    /** Error from the last failed request */
+    error: TError | undefined;
+    /** Abort the current fetch */
+    abort: () => void;
+};
 type OptionalQueryField<TQuery> = [TQuery] extends [never] ? object : undefined extends TQuery ? {
     query?: Exclude<TQuery, undefined>;
 } : {
@@ -106,6 +123,7 @@ type ExtractMethodError<T> = T extends (...args: never[]) => infer R ? ErrorResp
     error: infer E;
 } ? E : unknown : unknown;
 type ExtractMethodOptions<T> = T extends (...args: infer A) => unknown ? A[0] : never;
+type ExtractCoreMethodOptions<T> = T extends (...args: infer A) => unknown ? A[0] extends object ? Pick<A[0], Extract<keyof A[0], "query" | "params" | "body">> : object : object;
 type ExtractMethodQuery<T> = ExtractMethodOptions<T> extends {
     query: infer Q;
 } ? Q : never;
@@ -237,8 +255,8 @@ type BaseInfiniteReadResult<TData, TError, TItem, TPluginResult = Record<string,
     fetchNext: () => Promise<void>;
     /** Fetch the previous page */
     fetchPrev: () => Promise<void>;
-    /** Refetch all pages from the beginning */
-    refetch: () => Promise<void>;
+    /** Trigger refetch of all pages from the beginning */
+    trigger: () => Promise<void>;
     /** Abort the current fetch operation */
     abort: () => void;
     /** Error from the last failed request */
@@ -263,6 +281,9 @@ type UseReadFn<TDefaultError, TSchema, TPlugins extends PluginArray> = {
 type UseWriteFn<TDefaultError, TSchema, TPlugins extends PluginArray> = {
     <TMethod extends (...args: never) => Promise<SpooshResponse<unknown, unknown>>>(writeFn: (api: WriteApiClient<TSchema, TDefaultError>) => TMethod): BaseWriteResult<ExtractMethodData<TMethod>, InferError<ExtractMethodError<TMethod>, TDefaultError>, Parameters<TMethod>[0] & ResolvedWriteOptions<TSchema, TPlugins, TMethod, TDefaultError>, MergePluginResults<TPlugins>["write"]> & WriteResponseInputFields<ExtractMethodQuery<TMethod>, ExtractMethodBody<TMethod>, ExtractResponseParamNames<TMethod>>;
 };
+type UseLazyReadFn<TDefaultError, TSchema> = {
+    <TMethod extends (...args: never) => Promise<SpooshResponse<unknown, unknown>>>(readFn: (api: ReadApiClient<TSchema, TDefaultError>) => TMethod): BaseLazyReadResult<ExtractMethodData<TMethod>, InferError<ExtractMethodError<TMethod>, TDefaultError>, ExtractCoreMethodOptions<TMethod>> & WriteResponseInputFields<ExtractResponseQuery<TMethod>, ExtractResponseBody<TMethod>, ExtractResponseParamNames<TMethod>>;
+};
 type InfiniteReadResolverContext<TSchema, TData, TError, TRequest> = ResolverContext<TSchema, TData, TError, TRequest extends {
     query: infer Q;
 } ? Q : never, TRequest extends {
@@ -285,7 +306,7 @@ type SpooshReactHooks<TDefaultError, TSchema, TPlugins extends PluginArray> = {
      *
      * @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`
+     * @returns Object containing `data`, `error`, `loading`, `fetching`, `trigger`, and `abort`
      *
      * @example
      * ```tsx
@@ -302,7 +323,7 @@ type SpooshReactHooks<TDefaultError, TSchema, TPlugins extends PluginArray> = {
      * 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`
+     * @returns Object containing `trigger`, `data`, `error`, `loading`, and `abort`
      *
      * @example
      * ```tsx
@@ -315,6 +336,23 @@ type SpooshReactHooks<TDefaultError, TSchema, TPlugins extends PluginArray> = {
      * ```
      */
     useWrite: UseWriteFn<TDefaultError, TSchema, TPlugins>;
+    /**
+     * React hook for lazy GET requests with manual triggering (does not auto-fetch on mount).
+     *
+     * @param readFn - Function that selects the API endpoint (e.g., `(api) => api("posts").GET`)
+     * @returns Object containing `trigger`, `data`, `error`, `loading`, and `abort`
+     *
+     * @example
+     * ```tsx
+     * const { trigger, loading, data } = useLazyRead((api) => api("posts/:id").GET);
+     *
+     * const handleClick = async (id) => {
+     *   const { data, error } = await trigger({ params: { id } });
+     *   if (data) console.log('Fetched:', data);
+     * };
+     * ```
+     */
+    useLazyRead: UseLazyReadFn<TDefaultError, TSchema>;
     /**
      * React hook for infinite/paginated data fetching with automatic pagination control.
      *
@@ -411,6 +449,8 @@ declare function createUseRead<TSchema, TDefaultError, TPlugins extends readonly
     }> ? E : unknown, MergePluginResults<TPlugins>["read"]> & ResponseInputFields<ExtractResponseQuery<TReadFn>, ExtractResponseBody<TReadFn>, ExtractResponseParamNames<TReadFn>>;
 };
 
+declare function createUseLazyRead<TSchema, TDefaultError, TPlugins extends readonly SpooshPlugin<PluginTypeConfig>[]>(options: Omit<SpooshInstanceShape<unknown, TSchema, TDefaultError, TPlugins>, "_types">): <TMethod extends (...args: never[]) => Promise<SpooshResponse<unknown, unknown>>>(readFn: (api: ReadApiClient<TSchema, TDefaultError>) => TMethod) => BaseLazyReadResult<ExtractMethodData<TMethod>, [ExtractMethodError<TMethod>] extends [unknown] ? TDefaultError : ExtractMethodError<TMethod>, ExtractCoreMethodOptions<TMethod>> & WriteResponseInputFields<ExtractResponseQuery<TMethod>, ExtractResponseBody<TMethod>, ExtractResponseParamNames<TMethod>>;
+
 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> & 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 {
@@ -427,4 +467,4 @@ declare function createUseInfiniteRead<TSchema, TDefaultError, TPlugins 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>;
 
-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 };
+export { type BaseInfiniteReadOptions, type BaseInfiniteReadResult, type BaseLazyReadResult, type BaseReadOptions, type BaseReadResult, type BaseWriteResult, type PluginHooksConfig, type SpooshReactHooks, type UseInfiniteReadResult, type UseReadResult, type UseWriteResult, createReactSpoosh, createUseInfiniteRead, createUseLazyRead, createUseRead, createUseWrite };

package/dist/index.js

@@ -24,6 +24,7 @@ var src_exports = {};
 __export(src_exports, {
   createReactSpoosh: () => createReactSpoosh,
   createUseInfiniteRead: () => createUseInfiniteRead,
+  createUseLazyRead: () => createUseLazyRead,
   createUseRead: () => createUseRead,
   createUseWrite: () => createUseWrite
 });
@@ -171,7 +172,7 @@ function createUseRead(options) {
     const abort = (0, import_react.useCallback)(() => {
       abortRef.current();
     }, []);
-    const refetch = (0, import_react.useCallback)(() => {
+    const trigger = (0, import_react.useCallback)(() => {
       return executeWithTracking(true);
     }, [executeWithTracking]);
     const entry = stateManager.getCache(queryKey);
@@ -200,7 +201,7 @@ function createUseRead(options) {
       loading,
       fetching,
       abort,
-      refetch
+      trigger
     };
   }
   return useRead;
@@ -262,10 +263,6 @@ function createUseWrite(options) {
     );
     const [lastTriggerOptions, setLastTriggerOptions] = (0, import_react2.useState)(void 0);
     const [requestState, setRequestState] = (0, import_react2.useState)({ isPending: false, error: void 0 });
-    const reset = (0, import_react2.useCallback)(() => {
-      stateManager.deleteCache(queryKey);
-      setRequestState({ isPending: false, error: void 0 });
-    }, [queryKey]);
     const abort = (0, import_react2.useCallback)(() => {
       controller.abort();
     }, []);
@@ -317,7 +314,6 @@ function createUseWrite(options) {
       data: state.data,
       error: requestState.error ?? state.error,
       loading,
-      reset,
       abort
       // eslint-disable-next-line @typescript-eslint/no-explicit-any
     };
@@ -325,9 +321,141 @@ function createUseWrite(options) {
   return useWrite;
 }
 
-// src/useInfiniteRead/index.ts
+// src/useLazyRead/index.ts
 var import_react3 = require("react");
 var import_core3 = require("@spoosh/core");
+function createUseLazyRead(options) {
+  const { api, stateManager, pluginExecutor, eventEmitter } = options;
+  function useLazyRead(readFn) {
+    const hookId = (0, import_react3.useId)();
+    const selectorResultRef = (0, import_react3.useRef)({
+      call: null,
+      selector: null
+    });
+    const selectorProxy = (0, import_core3.createSelectorProxy)((result) => {
+      selectorResultRef.current = result;
+    });
+    readFn(selectorProxy);
+    const selectedEndpoint = selectorResultRef.current.selector;
+    if (!selectedEndpoint) {
+      throw new Error(
+        'useLazyRead requires selecting an HTTP method (GET). Example: useLazyRead((api) => api("posts").GET)'
+      );
+    }
+    if (selectedEndpoint.method !== "GET") {
+      throw new Error(
+        "useLazyRead only supports GET method. Use useWrite for POST, PUT, PATCH, DELETE methods."
+      );
+    }
+    const pathSegments = selectedEndpoint.path.split("/").filter(Boolean);
+    const controllerRef = (0, import_react3.useRef)(null);
+    const emptyStateRef = (0, import_react3.useRef)({ data: void 0, error: void 0 });
+    const [currentQueryKey, setCurrentQueryKey] = (0, import_react3.useState)(null);
+    const [, forceUpdate] = (0, import_react3.useState)(0);
+    const getOrCreateController = (0, import_react3.useCallback)(
+      (triggerOptions) => {
+        const queryKey = stateManager.createQueryKey({
+          path: pathSegments,
+          method: selectedEndpoint.method,
+          options: triggerOptions
+        });
+        if (controllerRef.current?.queryKey === queryKey) {
+          return { controller: controllerRef.current.controller, queryKey };
+        }
+        const controller2 = (0, import_core3.createOperationController)({
+          operationType: "read",
+          path: pathSegments,
+          method: "GET",
+          tags: [],
+          stateManager,
+          eventEmitter,
+          pluginExecutor,
+          hookId,
+          requestOptions: triggerOptions,
+          fetchFn: async (fetchOpts) => {
+            const pathMethods = api(selectedEndpoint.path);
+            const method = pathMethods[selectedEndpoint.method];
+            return method(fetchOpts);
+          }
+        });
+        controllerRef.current = { controller: controller2, queryKey };
+        setCurrentQueryKey(queryKey);
+        forceUpdate((n) => n + 1);
+        return { controller: controller2, queryKey };
+      },
+      [pathSegments, selectedEndpoint.method, selectedEndpoint.path, hookId]
+    );
+    const controller = controllerRef.current?.controller;
+    const subscribe = (0, import_react3.useCallback)(
+      (callback) => {
+        if (!controller) return () => {
+        };
+        return controller.subscribe(callback);
+      },
+      [controller]
+    );
+    const getSnapshot = (0, import_react3.useCallback)(() => {
+      if (!controller) return emptyStateRef.current;
+      return controller.getState();
+    }, [controller]);
+    const state = (0, import_react3.useSyncExternalStore)(subscribe, getSnapshot, getSnapshot);
+    const [lastTriggerOptions, setLastTriggerOptions] = (0, import_react3.useState)(void 0);
+    const [requestState, setRequestState] = (0, import_react3.useState)({ isPending: false, error: void 0 });
+    const abort = (0, import_react3.useCallback)(() => {
+      controllerRef.current?.controller.abort();
+    }, []);
+    const trigger = (0, import_react3.useCallback)(
+      async (triggerOptions) => {
+        setLastTriggerOptions(triggerOptions);
+        setRequestState((prev) => ({ ...prev, isPending: true }));
+        const params = triggerOptions?.params;
+        (0, import_core3.resolvePath)(pathSegments, params);
+        const { controller: ctrl } = getOrCreateController(triggerOptions);
+        ctrl.setPluginOptions(triggerOptions);
+        try {
+          const response = await ctrl.execute(triggerOptions);
+          if (response.error) {
+            setRequestState({ isPending: false, error: response.error });
+          } else {
+            setRequestState({ isPending: false, error: void 0 });
+          }
+          return response;
+        } catch (err) {
+          setRequestState({ isPending: false, error: err });
+          throw err;
+        }
+      },
+      [pathSegments, getOrCreateController]
+    );
+    const opts = lastTriggerOptions;
+    const inputInner = {};
+    if (opts?.query !== void 0) {
+      inputInner.query = opts.query;
+    }
+    if (opts?.body !== void 0) {
+      inputInner.body = opts.body;
+    }
+    if (opts?.params !== void 0) {
+      inputInner.params = opts.params;
+    }
+    const inputField = Object.keys(inputInner).length > 0 ? { input: inputInner } : {};
+    const loading = requestState.isPending;
+    return {
+      trigger,
+      ...inputField,
+      data: state.data,
+      error: requestState.error ?? state.error,
+      loading,
+      abort
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    };
+  }
+  return useLazyRead;
+}
+
+// src/useInfiniteRead/index.ts
+var import_react4 = require("react");
+var import_core4 = require("@spoosh/core");
 function createUseInfiniteRead(options) {
   const { api, stateManager, eventEmitter, pluginExecutor } = options;
   return function useInfiniteRead(readFn, readOptions) {
@@ -341,12 +469,12 @@ function createUseInfiniteRead(options) {
       prevPageRequest,
       ...pluginOpts
     } = readOptions;
-    const hookId = (0, import_react3.useId)();
-    const selectorResultRef = (0, import_react3.useRef)({
+    const hookId = (0, import_react4.useId)();
+    const selectorResultRef = (0, import_react4.useRef)({
       call: null,
       selector: null
     });
-    const selectorProxy = (0, import_core3.createSelectorProxy)((result2) => {
+    const selectorProxy = (0, import_core4.createSelectorProxy)((result2) => {
       selectorResultRef.current = result2;
     });
     readFn(selectorProxy);
@@ -369,13 +497,13 @@ function createUseInfiniteRead(options) {
       params: void 0,
       body: void 0
     };
-    const resolvedPath = (0, import_core3.resolvePath)(pathSegments, requestOptions?.params);
-    const resolvedTags = (0, import_core3.resolveTags)({ tags }, resolvedPath);
-    const canFetchNextRef = (0, import_react3.useRef)(canFetchNext);
-    const canFetchPrevRef = (0, import_react3.useRef)(canFetchPrev);
-    const nextPageRequestRef = (0, import_react3.useRef)(nextPageRequest);
-    const prevPageRequestRef = (0, import_react3.useRef)(prevPageRequest);
-    const mergerRef = (0, import_react3.useRef)(merger);
+    const resolvedPath = (0, import_core4.resolvePath)(pathSegments, requestOptions?.params);
+    const resolvedTags = (0, import_core4.resolveTags)({ tags }, resolvedPath);
+    const canFetchNextRef = (0, import_react4.useRef)(canFetchNext);
+    const canFetchPrevRef = (0, import_react4.useRef)(canFetchPrev);
+    const nextPageRequestRef = (0, import_react4.useRef)(nextPageRequest);
+    const prevPageRequestRef = (0, import_react4.useRef)(prevPageRequest);
+    const mergerRef = (0, import_react4.useRef)(merger);
     canFetchNextRef.current = canFetchNext;
     canFetchPrevRef.current = canFetchPrev;
     nextPageRequestRef.current = nextPageRequest;
@@ -386,10 +514,10 @@ function createUseInfiniteRead(options) {
       method: capturedCall.method,
       options: baseOptionsForKey
     });
-    const controllerRef = (0, import_react3.useRef)(null);
+    const controllerRef = (0, import_react4.useRef)(null);
     if (!controllerRef.current || controllerRef.current.queryKey !== queryKey) {
       controllerRef.current = {
-        controller: (0, import_core3.createInfiniteReadController)({
+        controller: (0, import_core4.createInfiniteReadController)({
           path: pathSegments,
           method: capturedCall.method,
           tags: resolvedTags,
@@ -422,12 +550,12 @@ function createUseInfiniteRead(options) {
     }
     const controller = controllerRef.current.controller;
     controller.setPluginOptions(pluginOpts);
-    const state = (0, import_react3.useSyncExternalStore)(
+    const state = (0, import_react4.useSyncExternalStore)(
       controller.subscribe,
       controller.getState,
       controller.getState
     );
-    const [isPending, setIsPending] = (0, import_react3.useState)(() => {
+    const [isPending, setIsPending] = (0, import_react4.useState)(() => {
       return enabled && state.data === void 0;
     });
     const fetchingDirection = controller.getFetchingDirection();
@@ -436,18 +564,18 @@ function createUseInfiniteRead(options) {
     const fetchingPrev = fetchingDirection === "prev";
     const hasData = state.data !== void 0;
     const loading = (isPending || fetching) && !hasData;
-    const lifecycleRef = (0, import_react3.useRef)({
+    const lifecycleRef = (0, import_react4.useRef)({
       initialized: false,
       prevContext: null
     });
     const tagsKey = JSON.stringify(tags);
-    (0, import_react3.useEffect)(() => {
+    (0, import_react4.useEffect)(() => {
       return () => {
         controllerRef.current?.controller.unmount();
         lifecycleRef.current.initialized = false;
       };
     }, []);
-    (0, import_react3.useEffect)(() => {
+    (0, import_react4.useEffect)(() => {
       controller.mount();
       lifecycleRef.current.initialized = true;
       const unsubInvalidate = eventEmitter.on(
@@ -466,7 +594,7 @@ function createUseInfiniteRead(options) {
         unsubInvalidate();
       };
     }, [tagsKey]);
-    (0, import_react3.useEffect)(() => {
+    (0, import_react4.useEffect)(() => {
       if (!lifecycleRef.current.initialized) return;
       if (enabled) {
         const currentState = controller.getState();
@@ -477,7 +605,7 @@ function createUseInfiniteRead(options) {
         }
       }
     }, [enabled]);
-    (0, import_react3.useEffect)(() => {
+    (0, import_react4.useEffect)(() => {
       if (!enabled || !lifecycleRef.current.initialized) return;
       const prevContext = controller.getContext();
       controller.update(prevContext);
@@ -496,7 +624,7 @@ function createUseInfiniteRead(options) {
       canFetchPrev: state.canFetchPrev,
       fetchNext: controller.fetchNext,
       fetchPrev: controller.fetchPrev,
-      refetch: controller.refetch,
+      trigger: controller.refetch,
       abort: controller.abort,
       error: state.error
     };
@@ -519,6 +647,12 @@ function createReactSpoosh(instance) {
     eventEmitter,
     pluginExecutor
   });
+  const useLazyRead = createUseLazyRead({
+    api,
+    stateManager,
+    eventEmitter,
+    pluginExecutor
+  });
   const useInfiniteRead = createUseInfiniteRead({
     api,
     stateManager,
@@ -544,6 +678,7 @@ function createReactSpoosh(instance) {
   return {
     useRead,
     useWrite,
+    useLazyRead,
     useInfiniteRead,
     ...instanceApis
   };

package/dist/index.mjs

@@ -155,7 +155,7 @@ function createUseRead(options) {
     const abort = useCallback(() => {
       abortRef.current();
     }, []);
-    const refetch = useCallback(() => {
+    const trigger = useCallback(() => {
       return executeWithTracking(true);
     }, [executeWithTracking]);
     const entry = stateManager.getCache(queryKey);
@@ -184,7 +184,7 @@ function createUseRead(options) {
       loading,
       fetching,
       abort,
-      refetch
+      trigger
     };
   }
   return useRead;
@@ -257,10 +257,6 @@ function createUseWrite(options) {
     );
     const [lastTriggerOptions, setLastTriggerOptions] = useState2(void 0);
     const [requestState, setRequestState] = useState2({ isPending: false, error: void 0 });
-    const reset = useCallback2(() => {
-      stateManager.deleteCache(queryKey);
-      setRequestState({ isPending: false, error: void 0 });
-    }, [queryKey]);
     const abort = useCallback2(() => {
       controller.abort();
     }, []);
@@ -312,7 +308,6 @@ function createUseWrite(options) {
       data: state.data,
       error: requestState.error ?? state.error,
       loading,
-      reset,
       abort
       // eslint-disable-next-line @typescript-eslint/no-explicit-any
     };
@@ -320,18 +315,160 @@ function createUseWrite(options) {
   return useWrite;
 }
 
-// src/useInfiniteRead/index.ts
+// src/useLazyRead/index.ts
 import {
+  useSyncExternalStore as useSyncExternalStore3,
   useRef as useRef3,
+  useCallback as useCallback3,
+  useState as useState3,
+  useId as useId3
+} from "react";
+import {
+  createOperationController as createOperationController3,
+  createSelectorProxy as createSelectorProxy3,
+  resolvePath as resolvePath3
+} from "@spoosh/core";
+function createUseLazyRead(options) {
+  const { api, stateManager, pluginExecutor, eventEmitter } = options;
+  function useLazyRead(readFn) {
+    const hookId = useId3();
+    const selectorResultRef = useRef3({
+      call: null,
+      selector: null
+    });
+    const selectorProxy = createSelectorProxy3((result) => {
+      selectorResultRef.current = result;
+    });
+    readFn(selectorProxy);
+    const selectedEndpoint = selectorResultRef.current.selector;
+    if (!selectedEndpoint) {
+      throw new Error(
+        'useLazyRead requires selecting an HTTP method (GET). Example: useLazyRead((api) => api("posts").GET)'
+      );
+    }
+    if (selectedEndpoint.method !== "GET") {
+      throw new Error(
+        "useLazyRead only supports GET method. Use useWrite for POST, PUT, PATCH, DELETE methods."
+      );
+    }
+    const pathSegments = selectedEndpoint.path.split("/").filter(Boolean);
+    const controllerRef = useRef3(null);
+    const emptyStateRef = useRef3({ data: void 0, error: void 0 });
+    const [currentQueryKey, setCurrentQueryKey] = useState3(null);
+    const [, forceUpdate] = useState3(0);
+    const getOrCreateController = useCallback3(
+      (triggerOptions) => {
+        const queryKey = stateManager.createQueryKey({
+          path: pathSegments,
+          method: selectedEndpoint.method,
+          options: triggerOptions
+        });
+        if (controllerRef.current?.queryKey === queryKey) {
+          return { controller: controllerRef.current.controller, queryKey };
+        }
+        const controller2 = createOperationController3({
+          operationType: "read",
+          path: pathSegments,
+          method: "GET",
+          tags: [],
+          stateManager,
+          eventEmitter,
+          pluginExecutor,
+          hookId,
+          requestOptions: triggerOptions,
+          fetchFn: async (fetchOpts) => {
+            const pathMethods = api(selectedEndpoint.path);
+            const method = pathMethods[selectedEndpoint.method];
+            return method(fetchOpts);
+          }
+        });
+        controllerRef.current = { controller: controller2, queryKey };
+        setCurrentQueryKey(queryKey);
+        forceUpdate((n) => n + 1);
+        return { controller: controller2, queryKey };
+      },
+      [pathSegments, selectedEndpoint.method, selectedEndpoint.path, hookId]
+    );
+    const controller = controllerRef.current?.controller;
+    const subscribe = useCallback3(
+      (callback) => {
+        if (!controller) return () => {
+        };
+        return controller.subscribe(callback);
+      },
+      [controller]
+    );
+    const getSnapshot = useCallback3(() => {
+      if (!controller) return emptyStateRef.current;
+      return controller.getState();
+    }, [controller]);
+    const state = useSyncExternalStore3(subscribe, getSnapshot, getSnapshot);
+    const [lastTriggerOptions, setLastTriggerOptions] = useState3(void 0);
+    const [requestState, setRequestState] = useState3({ isPending: false, error: void 0 });
+    const abort = useCallback3(() => {
+      controllerRef.current?.controller.abort();
+    }, []);
+    const trigger = useCallback3(
+      async (triggerOptions) => {
+        setLastTriggerOptions(triggerOptions);
+        setRequestState((prev) => ({ ...prev, isPending: true }));
+        const params = triggerOptions?.params;
+        resolvePath3(pathSegments, params);
+        const { controller: ctrl } = getOrCreateController(triggerOptions);
+        ctrl.setPluginOptions(triggerOptions);
+        try {
+          const response = await ctrl.execute(triggerOptions);
+          if (response.error) {
+            setRequestState({ isPending: false, error: response.error });
+          } else {
+            setRequestState({ isPending: false, error: void 0 });
+          }
+          return response;
+        } catch (err) {
+          setRequestState({ isPending: false, error: err });
+          throw err;
+        }
+      },
+      [pathSegments, getOrCreateController]
+    );
+    const opts = lastTriggerOptions;
+    const inputInner = {};
+    if (opts?.query !== void 0) {
+      inputInner.query = opts.query;
+    }
+    if (opts?.body !== void 0) {
+      inputInner.body = opts.body;
+    }
+    if (opts?.params !== void 0) {
+      inputInner.params = opts.params;
+    }
+    const inputField = Object.keys(inputInner).length > 0 ? { input: inputInner } : {};
+    const loading = requestState.isPending;
+    return {
+      trigger,
+      ...inputField,
+      data: state.data,
+      error: requestState.error ?? state.error,
+      loading,
+      abort
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    };
+  }
+  return useLazyRead;
+}
+
+// src/useInfiniteRead/index.ts
+import {
+  useRef as useRef4,
   useEffect as useEffect2,
-  useSyncExternalStore as useSyncExternalStore3,
-  useId as useId3,
-  useState as useState3
+  useSyncExternalStore as useSyncExternalStore4,
+  useId as useId4,
+  useState as useState4
 } from "react";
 import {
   createInfiniteReadController,
-  createSelectorProxy as createSelectorProxy3,
-  resolvePath as resolvePath3,
+  createSelectorProxy as createSelectorProxy4,
+  resolvePath as resolvePath4,
   resolveTags as resolveTags3
 } from "@spoosh/core";
 function createUseInfiniteRead(options) {
@@ -347,12 +484,12 @@ function createUseInfiniteRead(options) {
       prevPageRequest,
       ...pluginOpts
     } = readOptions;
-    const hookId = useId3();
-    const selectorResultRef = useRef3({
+    const hookId = useId4();
+    const selectorResultRef = useRef4({
       call: null,
       selector: null
     });
-    const selectorProxy = createSelectorProxy3((result2) => {
+    const selectorProxy = createSelectorProxy4((result2) => {
       selectorResultRef.current = result2;
     });
     readFn(selectorProxy);
@@ -375,13 +512,13 @@ function createUseInfiniteRead(options) {
       params: void 0,
       body: void 0
     };
-    const resolvedPath = resolvePath3(pathSegments, requestOptions?.params);
+    const resolvedPath = resolvePath4(pathSegments, requestOptions?.params);
     const resolvedTags = resolveTags3({ tags }, resolvedPath);
-    const canFetchNextRef = useRef3(canFetchNext);
-    const canFetchPrevRef = useRef3(canFetchPrev);
-    const nextPageRequestRef = useRef3(nextPageRequest);
-    const prevPageRequestRef = useRef3(prevPageRequest);
-    const mergerRef = useRef3(merger);
+    const canFetchNextRef = useRef4(canFetchNext);
+    const canFetchPrevRef = useRef4(canFetchPrev);
+    const nextPageRequestRef = useRef4(nextPageRequest);
+    const prevPageRequestRef = useRef4(prevPageRequest);
+    const mergerRef = useRef4(merger);
     canFetchNextRef.current = canFetchNext;
     canFetchPrevRef.current = canFetchPrev;
     nextPageRequestRef.current = nextPageRequest;
@@ -392,7 +529,7 @@ function createUseInfiniteRead(options) {
       method: capturedCall.method,
       options: baseOptionsForKey
     });
-    const controllerRef = useRef3(null);
+    const controllerRef = useRef4(null);
     if (!controllerRef.current || controllerRef.current.queryKey !== queryKey) {
       controllerRef.current = {
         controller: createInfiniteReadController({
@@ -428,12 +565,12 @@ function createUseInfiniteRead(options) {
     }
     const controller = controllerRef.current.controller;
     controller.setPluginOptions(pluginOpts);
-    const state = useSyncExternalStore3(
+    const state = useSyncExternalStore4(
       controller.subscribe,
       controller.getState,
       controller.getState
     );
-    const [isPending, setIsPending] = useState3(() => {
+    const [isPending, setIsPending] = useState4(() => {
       return enabled && state.data === void 0;
     });
     const fetchingDirection = controller.getFetchingDirection();
@@ -442,7 +579,7 @@ function createUseInfiniteRead(options) {
     const fetchingPrev = fetchingDirection === "prev";
     const hasData = state.data !== void 0;
     const loading = (isPending || fetching) && !hasData;
-    const lifecycleRef = useRef3({
+    const lifecycleRef = useRef4({
       initialized: false,
       prevContext: null
     });
@@ -502,7 +639,7 @@ function createUseInfiniteRead(options) {
       canFetchPrev: state.canFetchPrev,
       fetchNext: controller.fetchNext,
       fetchPrev: controller.fetchPrev,
-      refetch: controller.refetch,
+      trigger: controller.refetch,
       abort: controller.abort,
       error: state.error
     };
@@ -525,6 +662,12 @@ function createReactSpoosh(instance) {
     eventEmitter,
     pluginExecutor
   });
+  const useLazyRead = createUseLazyRead({
+    api,
+    stateManager,
+    eventEmitter,
+    pluginExecutor
+  });
   const useInfiniteRead = createUseInfiniteRead({
     api,
     stateManager,
@@ -550,6 +693,7 @@ function createReactSpoosh(instance) {
   return {
     useRead,
     useWrite,
+    useLazyRead,
     useInfiniteRead,
     ...instanceApis
   };
@@ -557,6 +701,7 @@ function createReactSpoosh(instance) {
 export {
   createReactSpoosh,
   createUseInfiniteRead,
+  createUseLazyRead,
   createUseRead,
   createUseWrite
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spoosh/react",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "license": "MIT",
   "description": "React hooks for Spoosh API client",
   "keywords": [
@@ -38,7 +38,7 @@
     "react": "^18 || ^19"
   },
   "devDependencies": {
-    "@spoosh/core": "0.7.0"
+    "@spoosh/core": "0.9.0"
   },
   "scripts": {
     "dev": "tsup --watch",