@spoosh/react 0.10.1 → 0.12.0

package/dist/index.js

@@ -404,12 +404,12 @@ function createUseWrite(options) {
   return useWrite;
 }
 
-// src/useInfiniteRead/index.ts
+// src/usePages/index.ts
 var import_react3 = require("react");
 var import_core3 = require("@spoosh/core");
-function createUseInfiniteRead(options) {
+function createUsePages(options) {
   const { api, stateManager, eventEmitter, pluginExecutor } = options;
-  return function useInfiniteRead(readFn, readOptions) {
+  return function usePages(readFn, readOptions) {
     const {
       enabled = true,
       tags,
@@ -432,7 +432,7 @@ function createUseInfiniteRead(options) {
     const capturedCall = selectorResultRef.current.call;
     if (!capturedCall) {
       throw new Error(
-        'useInfiniteRead requires calling an HTTP method (GET). Example: useInfiniteRead((api) => api("posts").GET())'
+        'usePages requires calling an HTTP method (GET). Example: usePages((api) => api("posts").GET())'
       );
     }
     const requestOptions = capturedCall.options;
@@ -442,12 +442,6 @@ function createUseInfiniteRead(options) {
       params: requestOptions?.params,
       body: requestOptions?.body
     };
-    const baseOptionsForKey = {
-      ...capturedCall.options,
-      query: void 0,
-      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);
@@ -463,22 +457,31 @@ function createUseInfiniteRead(options) {
     const queryKey = stateManager.createQueryKey({
       path: capturedCall.path,
       method: capturedCall.method,
-      options: baseOptionsForKey
+      options: capturedCall.options
+    });
+    const lifecycleRef = (0, import_react3.useRef)({
+      initialized: false,
+      prevContext: null,
+      lastQueryKey: null
     });
     const controllerRef = (0, import_react3.useRef)(null);
-    if (!controllerRef.current || controllerRef.current.queryKey !== queryKey) {
+    const queryKeyChanged = controllerRef.current !== null && controllerRef.current.queryKey !== queryKey;
+    if (queryKeyChanged) {
+      lifecycleRef.current.prevContext = controllerRef.current.controller.getContext();
+      lifecycleRef.current.initialized = false;
+    }
+    if (!controllerRef.current || queryKeyChanged) {
       controllerRef.current = {
         controller: (0, import_core3.createInfiniteReadController)({
           path: capturedCall.path,
           method: capturedCall.method,
           tags: resolvedTags,
           initialRequest,
-          baseOptionsForKey,
-          canFetchNext: (ctx) => canFetchNextRef.current(ctx),
+          canFetchNext: canFetchNext ? (ctx) => canFetchNextRef.current?.(ctx) ?? false : void 0,
           canFetchPrev: canFetchPrev ? (ctx) => canFetchPrevRef.current?.(ctx) ?? false : void 0,
-          nextPageRequest: (ctx) => nextPageRequestRef.current(ctx),
+          nextPageRequest: nextPageRequest ? (ctx) => nextPageRequestRef.current?.(ctx) ?? {} : void 0,
           prevPageRequest: prevPageRequest ? (ctx) => prevPageRequestRef.current?.(ctx) ?? {} : void 0,
-          merger: (responses) => mergerRef.current(responses),
+          merger: (pages) => mergerRef.current(pages),
           stateManager,
           eventEmitter,
           pluginExecutor,
@@ -488,9 +491,7 @@ function createUseInfiniteRead(options) {
             const method = pathMethods[capturedCall.method];
             const fetchOptions = {
               ...capturedCall.options,
-              query: opts.query,
-              params: opts.params,
-              body: opts.body,
+              ...opts,
               signal
             };
             return method(fetchOptions);
@@ -501,11 +502,12 @@ function createUseInfiniteRead(options) {
     }
     const controller = controllerRef.current.controller;
     controller.setPluginOptions(pluginOpts);
-    const state = (0, import_react3.useSyncExternalStore)(
-      controller.subscribe,
-      controller.getState,
-      controller.getState
+    const subscribe = (0, import_react3.useCallback)(
+      (callback) => controller.subscribe(callback),
+      [controller]
     );
+    const getSnapshot = (0, import_react3.useCallback)(() => controller.getState(), [controller]);
+    const state = (0, import_react3.useSyncExternalStore)(subscribe, getSnapshot, getSnapshot);
     const [isPending, setIsPending] = (0, import_react3.useState)(() => {
       return enabled && state.data === void 0;
     });
@@ -515,10 +517,6 @@ function createUseInfiniteRead(options) {
     const fetchingPrev = fetchingDirection === "prev";
     const hasData = state.data !== void 0;
     const loading = (isPending || fetching) && !hasData;
-    const lifecycleRef = (0, import_react3.useRef)({
-      initialized: false,
-      prevContext: null
-    });
     const tagsKey = JSON.stringify(tags);
     (0, import_react3.useEffect)(() => {
       return () => {
@@ -527,8 +525,27 @@ function createUseInfiniteRead(options) {
       };
     }, []);
     (0, import_react3.useEffect)(() => {
-      controller.mount();
-      lifecycleRef.current.initialized = true;
+      if (!enabled) return;
+      const { initialized, prevContext, lastQueryKey } = lifecycleRef.current;
+      const isQueryKeyChange = lastQueryKey !== null && lastQueryKey !== queryKey;
+      if (!initialized) {
+        controller.mount();
+        lifecycleRef.current.initialized = true;
+        if (prevContext) {
+          controller.update(prevContext);
+          lifecycleRef.current.prevContext = null;
+        }
+      }
+      lifecycleRef.current.lastQueryKey = queryKey;
+      const currentState = controller.getState();
+      const isFetching = controller.getFetchingDirection() !== null;
+      if (isQueryKeyChange) {
+        setIsPending(true);
+        controller.trigger({ force: false }).finally(() => setIsPending(false));
+      } else if (currentState.data === void 0 && !isFetching) {
+        setIsPending(true);
+        controller.fetchNext().finally(() => setIsPending(false));
+      }
       const unsubInvalidate = eventEmitter.on(
         "invalidate",
         (invalidatedTags) => {
@@ -537,41 +554,32 @@ function createUseInfiniteRead(options) {
           );
           if (hasMatch) {
             setIsPending(true);
-            controller.refetch().finally(() => setIsPending(false));
+            controller.trigger().finally(() => setIsPending(false));
           }
         }
       );
       const unsubRefetchAll = eventEmitter.on("refetchAll", () => {
         setIsPending(true);
-        controller.refetch().finally(() => setIsPending(false));
+        controller.trigger().finally(() => setIsPending(false));
       });
       return () => {
+        controller.unmount();
         unsubInvalidate();
         unsubRefetchAll();
       };
-    }, [tagsKey]);
-    (0, import_react3.useEffect)(() => {
-      if (!lifecycleRef.current.initialized) return;
-      if (enabled) {
-        const currentState = controller.getState();
-        const isFetching = controller.getFetchingDirection() !== null;
-        if (currentState.data === void 0 && !isFetching) {
-          setIsPending(true);
-          controller.fetchNext().finally(() => setIsPending(false));
-        }
-      }
-    }, [enabled]);
+    }, [queryKey, enabled, tagsKey]);
+    const pluginOptsKey = JSON.stringify(pluginOpts);
     (0, import_react3.useEffect)(() => {
       if (!enabled || !lifecycleRef.current.initialized) return;
       const prevContext = controller.getContext();
       controller.update(prevContext);
-    }, [JSON.stringify(pluginOpts)]);
-    const entry = stateManager.getCache(queryKey);
-    const pluginResultData = entry?.meta ? Object.fromEntries(entry.meta) : {};
+    }, [pluginOptsKey]);
+    const trigger = async (options2) => {
+      await controller.trigger(options2);
+    };
     const result = {
-      meta: pluginResultData,
       data: state.data,
-      allResponses: state.allResponses,
+      pages: state.pages,
       loading,
       fetching,
       fetchingNext,
@@ -580,7 +588,7 @@ function createUseInfiniteRead(options) {
       canFetchPrev: state.canFetchPrev,
       fetchNext: controller.fetchNext,
       fetchPrev: controller.fetchPrev,
-      trigger: controller.refetch,
+      trigger,
       abort: controller.abort,
       error: state.error
     };
@@ -588,6 +596,72 @@ function createUseInfiniteRead(options) {
   };
 }
 
+// src/useQueue/index.ts
+var import_react4 = require("react");
+var import_core4 = require("@spoosh/core");
+function createUseQueue(options) {
+  const { api, stateManager, pluginExecutor, eventEmitter } = options;
+  function useQueue(queueFn, queueOptions) {
+    (0, import_react4.useId)();
+    const selectorResultRef = (0, import_react4.useRef)({
+      call: null,
+      selector: null
+    });
+    const selectorProxy = (0, import_core4.createSelectorProxy)((result) => {
+      selectorResultRef.current = result;
+    });
+    queueFn(selectorProxy);
+    const capturedCall = selectorResultRef.current.call;
+    const capturedSelector = selectorResultRef.current.selector;
+    const captured = capturedCall ?? capturedSelector;
+    if (!captured) {
+      throw new Error(
+        'useQueue requires selecting an HTTP method. Example: useQueue((api) => api("uploads").POST())'
+      );
+    }
+    const { concurrency, ...hookOptions } = queueOptions ?? {};
+    const controllerRef = (0, import_react4.useRef)(null);
+    if (!controllerRef.current) {
+      const config = {
+        path: captured.path,
+        method: captured.method,
+        concurrency,
+        operationType: "queue",
+        hookOptions
+      };
+      controllerRef.current = (0, import_core4.createQueueController)(config, {
+        api,
+        stateManager,
+        eventEmitter,
+        pluginExecutor
+      });
+    }
+    const controller = controllerRef.current;
+    (0, import_react4.useEffect)(() => {
+      if (concurrency !== void 0) {
+        controller.setConcurrency(concurrency);
+      }
+    }, [concurrency, controller]);
+    const tasks = (0, import_react4.useSyncExternalStore)(
+      controller.subscribe,
+      controller.getQueue,
+      controller.getQueue
+    );
+    return {
+      trigger: (input) => controller.trigger(input ?? {}),
+      tasks,
+      stats: controller.getStats(),
+      abort: controller.abort,
+      retry: controller.retry,
+      remove: controller.remove,
+      removeSettled: controller.removeSettled,
+      clear: controller.clear
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    };
+  }
+  return useQueue;
+}
+
 // src/create/index.ts
 function create(instance) {
   const { api, stateManager, eventEmitter, pluginExecutor } = instance;
@@ -603,7 +677,13 @@ function create(instance) {
     eventEmitter,
     pluginExecutor
   });
-  const useInfiniteRead = createUseInfiniteRead({
+  const usePages = createUsePages({
+    api,
+    stateManager,
+    eventEmitter,
+    pluginExecutor
+  });
+  const useQueue = createUseQueue({
     api,
     stateManager,
     eventEmitter,
@@ -636,7 +716,8 @@ function create(instance) {
   return {
     useRead,
     useWrite,
-    useInfiniteRead,
+    usePages,
+    useQueue,
     ...instanceApis
   };
 }

package/dist/index.mjs

@@ -402,13 +402,14 @@ function createUseWrite(options) {
   return useWrite;
 }
 
-// src/useInfiniteRead/index.ts
+// src/usePages/index.ts
 import {
   useRef as useRef3,
   useEffect as useEffect2,
   useSyncExternalStore as useSyncExternalStore3,
   useId as useId3,
-  useState as useState3
+  useState as useState3,
+  useCallback as useCallback3
 } from "react";
 import {
   createInfiniteReadController,
@@ -416,9 +417,9 @@ import {
   resolvePath as resolvePath3,
   resolveTags as resolveTags3
 } from "@spoosh/core";
-function createUseInfiniteRead(options) {
+function createUsePages(options) {
   const { api, stateManager, eventEmitter, pluginExecutor } = options;
-  return function useInfiniteRead(readFn, readOptions) {
+  return function usePages(readFn, readOptions) {
     const {
       enabled = true,
       tags,
@@ -441,7 +442,7 @@ function createUseInfiniteRead(options) {
     const capturedCall = selectorResultRef.current.call;
     if (!capturedCall) {
       throw new Error(
-        'useInfiniteRead requires calling an HTTP method (GET). Example: useInfiniteRead((api) => api("posts").GET())'
+        'usePages requires calling an HTTP method (GET). Example: usePages((api) => api("posts").GET())'
       );
     }
     const requestOptions = capturedCall.options;
@@ -451,12 +452,6 @@ function createUseInfiniteRead(options) {
       params: requestOptions?.params,
       body: requestOptions?.body
     };
-    const baseOptionsForKey = {
-      ...capturedCall.options,
-      query: void 0,
-      params: void 0,
-      body: void 0
-    };
     const resolvedPath = resolvePath3(pathSegments, requestOptions?.params);
     const resolvedTags = resolveTags3({ tags }, resolvedPath);
     const canFetchNextRef = useRef3(canFetchNext);
@@ -472,22 +467,31 @@ function createUseInfiniteRead(options) {
     const queryKey = stateManager.createQueryKey({
       path: capturedCall.path,
       method: capturedCall.method,
-      options: baseOptionsForKey
+      options: capturedCall.options
+    });
+    const lifecycleRef = useRef3({
+      initialized: false,
+      prevContext: null,
+      lastQueryKey: null
     });
     const controllerRef = useRef3(null);
-    if (!controllerRef.current || controllerRef.current.queryKey !== queryKey) {
+    const queryKeyChanged = controllerRef.current !== null && controllerRef.current.queryKey !== queryKey;
+    if (queryKeyChanged) {
+      lifecycleRef.current.prevContext = controllerRef.current.controller.getContext();
+      lifecycleRef.current.initialized = false;
+    }
+    if (!controllerRef.current || queryKeyChanged) {
       controllerRef.current = {
         controller: createInfiniteReadController({
           path: capturedCall.path,
           method: capturedCall.method,
           tags: resolvedTags,
           initialRequest,
-          baseOptionsForKey,
-          canFetchNext: (ctx) => canFetchNextRef.current(ctx),
+          canFetchNext: canFetchNext ? (ctx) => canFetchNextRef.current?.(ctx) ?? false : void 0,
           canFetchPrev: canFetchPrev ? (ctx) => canFetchPrevRef.current?.(ctx) ?? false : void 0,
-          nextPageRequest: (ctx) => nextPageRequestRef.current(ctx),
+          nextPageRequest: nextPageRequest ? (ctx) => nextPageRequestRef.current?.(ctx) ?? {} : void 0,
           prevPageRequest: prevPageRequest ? (ctx) => prevPageRequestRef.current?.(ctx) ?? {} : void 0,
-          merger: (responses) => mergerRef.current(responses),
+          merger: (pages) => mergerRef.current(pages),
           stateManager,
           eventEmitter,
           pluginExecutor,
@@ -497,9 +501,7 @@ function createUseInfiniteRead(options) {
             const method = pathMethods[capturedCall.method];
             const fetchOptions = {
               ...capturedCall.options,
-              query: opts.query,
-              params: opts.params,
-              body: opts.body,
+              ...opts,
               signal
             };
             return method(fetchOptions);
@@ -510,11 +512,12 @@ function createUseInfiniteRead(options) {
     }
     const controller = controllerRef.current.controller;
     controller.setPluginOptions(pluginOpts);
-    const state = useSyncExternalStore3(
-      controller.subscribe,
-      controller.getState,
-      controller.getState
+    const subscribe = useCallback3(
+      (callback) => controller.subscribe(callback),
+      [controller]
     );
+    const getSnapshot = useCallback3(() => controller.getState(), [controller]);
+    const state = useSyncExternalStore3(subscribe, getSnapshot, getSnapshot);
     const [isPending, setIsPending] = useState3(() => {
       return enabled && state.data === void 0;
     });
@@ -524,10 +527,6 @@ function createUseInfiniteRead(options) {
     const fetchingPrev = fetchingDirection === "prev";
     const hasData = state.data !== void 0;
     const loading = (isPending || fetching) && !hasData;
-    const lifecycleRef = useRef3({
-      initialized: false,
-      prevContext: null
-    });
     const tagsKey = JSON.stringify(tags);
     useEffect2(() => {
       return () => {
@@ -536,8 +535,27 @@ function createUseInfiniteRead(options) {
       };
     }, []);
     useEffect2(() => {
-      controller.mount();
-      lifecycleRef.current.initialized = true;
+      if (!enabled) return;
+      const { initialized, prevContext, lastQueryKey } = lifecycleRef.current;
+      const isQueryKeyChange = lastQueryKey !== null && lastQueryKey !== queryKey;
+      if (!initialized) {
+        controller.mount();
+        lifecycleRef.current.initialized = true;
+        if (prevContext) {
+          controller.update(prevContext);
+          lifecycleRef.current.prevContext = null;
+        }
+      }
+      lifecycleRef.current.lastQueryKey = queryKey;
+      const currentState = controller.getState();
+      const isFetching = controller.getFetchingDirection() !== null;
+      if (isQueryKeyChange) {
+        setIsPending(true);
+        controller.trigger({ force: false }).finally(() => setIsPending(false));
+      } else if (currentState.data === void 0 && !isFetching) {
+        setIsPending(true);
+        controller.fetchNext().finally(() => setIsPending(false));
+      }
       const unsubInvalidate = eventEmitter.on(
         "invalidate",
         (invalidatedTags) => {
@@ -546,41 +564,32 @@ function createUseInfiniteRead(options) {
           );
           if (hasMatch) {
             setIsPending(true);
-            controller.refetch().finally(() => setIsPending(false));
+            controller.trigger().finally(() => setIsPending(false));
           }
         }
       );
       const unsubRefetchAll = eventEmitter.on("refetchAll", () => {
         setIsPending(true);
-        controller.refetch().finally(() => setIsPending(false));
+        controller.trigger().finally(() => setIsPending(false));
       });
       return () => {
+        controller.unmount();
         unsubInvalidate();
         unsubRefetchAll();
       };
-    }, [tagsKey]);
-    useEffect2(() => {
-      if (!lifecycleRef.current.initialized) return;
-      if (enabled) {
-        const currentState = controller.getState();
-        const isFetching = controller.getFetchingDirection() !== null;
-        if (currentState.data === void 0 && !isFetching) {
-          setIsPending(true);
-          controller.fetchNext().finally(() => setIsPending(false));
-        }
-      }
-    }, [enabled]);
+    }, [queryKey, enabled, tagsKey]);
+    const pluginOptsKey = JSON.stringify(pluginOpts);
     useEffect2(() => {
       if (!enabled || !lifecycleRef.current.initialized) return;
       const prevContext = controller.getContext();
       controller.update(prevContext);
-    }, [JSON.stringify(pluginOpts)]);
-    const entry = stateManager.getCache(queryKey);
-    const pluginResultData = entry?.meta ? Object.fromEntries(entry.meta) : {};
+    }, [pluginOptsKey]);
+    const trigger = async (options2) => {
+      await controller.trigger(options2);
+    };
     const result = {
-      meta: pluginResultData,
       data: state.data,
-      allResponses: state.allResponses,
+      pages: state.pages,
       loading,
       fetching,
       fetchingNext,
@@ -589,7 +598,7 @@ function createUseInfiniteRead(options) {
       canFetchPrev: state.canFetchPrev,
       fetchNext: controller.fetchNext,
       fetchPrev: controller.fetchPrev,
-      trigger: controller.refetch,
+      trigger,
       abort: controller.abort,
       error: state.error
     };
@@ -597,6 +606,75 @@ function createUseInfiniteRead(options) {
   };
 }
 
+// src/useQueue/index.ts
+import { useSyncExternalStore as useSyncExternalStore4, useRef as useRef4, useId as useId4, useEffect as useEffect3 } from "react";
+import {
+  createSelectorProxy as createSelectorProxy4,
+  createQueueController
+} from "@spoosh/core";
+function createUseQueue(options) {
+  const { api, stateManager, pluginExecutor, eventEmitter } = options;
+  function useQueue(queueFn, queueOptions) {
+    useId4();
+    const selectorResultRef = useRef4({
+      call: null,
+      selector: null
+    });
+    const selectorProxy = createSelectorProxy4((result) => {
+      selectorResultRef.current = result;
+    });
+    queueFn(selectorProxy);
+    const capturedCall = selectorResultRef.current.call;
+    const capturedSelector = selectorResultRef.current.selector;
+    const captured = capturedCall ?? capturedSelector;
+    if (!captured) {
+      throw new Error(
+        'useQueue requires selecting an HTTP method. Example: useQueue((api) => api("uploads").POST())'
+      );
+    }
+    const { concurrency, ...hookOptions } = queueOptions ?? {};
+    const controllerRef = useRef4(null);
+    if (!controllerRef.current) {
+      const config = {
+        path: captured.path,
+        method: captured.method,
+        concurrency,
+        operationType: "queue",
+        hookOptions
+      };
+      controllerRef.current = createQueueController(config, {
+        api,
+        stateManager,
+        eventEmitter,
+        pluginExecutor
+      });
+    }
+    const controller = controllerRef.current;
+    useEffect3(() => {
+      if (concurrency !== void 0) {
+        controller.setConcurrency(concurrency);
+      }
+    }, [concurrency, controller]);
+    const tasks = useSyncExternalStore4(
+      controller.subscribe,
+      controller.getQueue,
+      controller.getQueue
+    );
+    return {
+      trigger: (input) => controller.trigger(input ?? {}),
+      tasks,
+      stats: controller.getStats(),
+      abort: controller.abort,
+      retry: controller.retry,
+      remove: controller.remove,
+      removeSettled: controller.removeSettled,
+      clear: controller.clear
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    };
+  }
+  return useQueue;
+}
+
 // src/create/index.ts
 function create(instance) {
   const { api, stateManager, eventEmitter, pluginExecutor } = instance;
@@ -612,7 +690,13 @@ function create(instance) {
     eventEmitter,
     pluginExecutor
   });
-  const useInfiniteRead = createUseInfiniteRead({
+  const usePages = createUsePages({
+    api,
+    stateManager,
+    eventEmitter,
+    pluginExecutor
+  });
+  const useQueue = createUseQueue({
     api,
     stateManager,
     eventEmitter,
@@ -645,7 +729,8 @@ function create(instance) {
   return {
     useRead,
     useWrite,
-    useInfiniteRead,
+    usePages,
+    useQueue,
     ...instanceApis
   };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spoosh/react",
-  "version": "0.10.1",
+  "version": "0.12.0",
   "license": "MIT",
   "description": "React hooks for Spoosh API toolkit",
   "keywords": [
@@ -34,14 +34,14 @@
     }
   },
   "peerDependencies": {
-    "@spoosh/core": ">=0.13.2",
+    "@spoosh/core": ">=0.15.0",
     "react": "^18 || ^19"
   },
   "devDependencies": {
     "@testing-library/react": "^16.0.0",
     "jsdom": "^26.0.0",
-    "@spoosh/core": "0.13.2",
-    "@spoosh/test-utils": "0.2.0"
+    "@spoosh/core": "0.15.0",
+    "@spoosh/test-utils": "0.3.0"
   },
   "scripts": {
     "dev": "tsup --watch",