@t8/react-pending 1.0.32 → 1.1.0

package/README.md

@@ -1,10 +1,10 @@
 # T8 React Pending
 
-A concise async action state management lib for React apps
+Self-contained async action state management for React apps
 
-[![npm](https://img.shields.io/npm/v/@t8/react-pending?labelColor=345&color=46e)](https://www.npmjs.com/package/@t8/react-pending) ![Lightweight](https://img.shields.io/bundlephobia/minzip/@t8/react-pending?label=minzip&labelColor=345&color=46e) ![CSR ✓](https://img.shields.io/badge/CSR-✓-345?labelColor=345) ![SSR ✓](https://img.shields.io/badge/SSR-✓-345?labelColor=345)
+[![npm](https://img.shields.io/npm/v/@t8/react-pending?labelColor=345&color=46e)](https://www.npmjs.com/package/@t8/react-pending) ![Lightweight](https://img.shields.io/bundlephobia/minzip/@t8/react-pending?label=minzip&labelColor=345&color=46e)
 
-**Why?** To manage the async action state, whether local or shared, without tightly coupling it with the app state. Decoupled pending state as described here acts like a lightweight scaffolding on top of the action's and component's successful scenario. It's easy to set up from scratch without rewriting the async actions and affecting the app state, and easy to manage further on since it's barely intertwined with other app's internals.
+**Features:** Decoupled from app state management and async actions' internals · Local or shared async action state · CSR/SSR-compatible
 
 <!-- docsgen-show-start --
 ```diff
@@ -12,15 +12,15 @@ A concise async action state management lib for React apps
 
   export let ItemList = () => {
     let [items, setItems] = useState([]);
-+   let [state, withState] = usePendingState("fetch-items");
++   let { complete, error, track } = usePendingState("fetch-items");
 
     useEffect(() => {
 -     fetchItems().then(setItems);
-+     withState(fetchItems()).then(setItems);
-    }, [fetchItems, withState]);
++     track(fetchItems()).then(setItems);
+    }, [fetchItems, track]);
 
-+   if (!state.complete) return <p>Loading...</p>;
-+   if (state.error) return <p>An error occurred</p>;
++   if (!complete) return <p>Loading...</p>;
++   if (error) return <p>An error occurred</p>;
 
     return <ul>{items.map(/* ... */)}</ul>;
   };
@@ -40,15 +40,15 @@ In our setup, there are two components rendering their content with regard to th
 
   export let ItemList = () => {
     let [items, setItems] = useState([]);
-+   let [state, withState] = usePendingState("fetch-items");
++   let { complete, error, track } = usePendingState("fetch-items");
 
     useEffect(() => {
 -     fetchItems().then(setItems);
-+     withState(fetchItems()).then(setItems);
-    }, [fetchItems, withState]);
++     track(fetchItems()).then(setItems);
+    }, [fetchItems, track]);
 
-+   if (!state.complete) return <p>Loading...</p>;
-+   if (state.error) return <p>An error occurred</p>;
++   if (!complete) return <p>Loading...</p>;
++   if (error) return <p>An error occurred</p>;
 
     return <ul>{items.map(/* ... */)}</ul>;
   };
@@ -58,11 +58,11 @@ In our setup, there are two components rendering their content with regard to th
 + import { usePendingState } from "@t8/react-pending";
 
   export let Status = () => {
-+   let [state] = usePendingState("fetch-items");
++   let { initialized, complete, error } = usePendingState("fetch-items");
 
-    if (!state.initialized) return null;
-    if (!state.complete) return <>Busy</>;
-    if (state.error) return <>Error</>;
+    if (!initialized) return null;
+    if (!complete) return <>Busy</>;
+    if (error) return <>Error</>;
 
     return <>OK</>;
   };
@@ -79,24 +79,24 @@ In our setup, there are two components rendering their content with regard to th
 Omit the custom string key parameter of `usePendingState()` to scope the pending state locally within a single component:
 
 ```diff
-- let [state, withState] = usePendingState("fetch-items"); // shared
-+ let [state, withState] = usePendingState(); // local
+- let { complete } = usePendingState("fetch-items"); // shared
++ let { complete } = usePendingState(); // local
 ```
 
 ## Silent tracking of background actions and optimistic updates
 
 ```diff
-- withState(fetchItems())
-+ withState(fetchItems(), { silent: true })
+- track(fetchItems())
++ track(fetchItems(), { silent: true })
 ```
 
-⬥ This option prevents `state.complete` from switching to `false` in the pending state.
+⬥ This option prevents `complete` from switching to `false` in the pending state.
 
 ## Delayed pending state
 
 ```diff
-- withState(fetchItems())
-+ withState(fetchItems(), { delay: 500 }) // in milliseconds
+- track(fetchItems())
++ track(fetchItems(), { delay: 500 }) // in milliseconds
 ```
 
 ⬥ Use case: avoiding flashing a process indicator when the action is likely to complete by the end of a short delay.
@@ -104,11 +104,11 @@ Omit the custom string key parameter of `usePendingState()` to scope the pending
 ## Custom rejection handler
 
 ```diff
-- withState(fetchItems())
-+ withState(fetchItems(), { throws: true }).catch(handleError)
+- track(fetchItems())
++ track(fetchItems(), { throws: true }).catch(handleError)
 ```
 
-⬥ This option allows the async action to reject explicitly, along with exposing `state.error` that goes by default.
+⬥ This option allows the async action to reject explicitly, along with exposing `error` returned from `usePendingState()` that goes by default.
 
 ## Providing blank initial pending&nbsp;state
 

package/dist/index.cjs

@@ -33,12 +33,11 @@ function createState(initialized = false, complete = false, error) {
 * key or a shared store allows to share the state across multiple
 * components.
 *
-* @returns `[state, withState, setState]`, where
-* - `state` is the current value of the action's state;
-* - `withState(action, options?)` reads and tracks the `actions`'s state
-* which is exposed as `state` listed above;
-* - `setState(update)` can be used to replace the current `state` value
-* directly with an another state value.
+* @returns `{ initialized, complete, error, track, update }`, where
+* - `initialized`, `complete`, `error` reflect the current action's state;
+* - `track(action, options?)` tracks the `actions`'s state;
+* - `update(nextState | ((state) => nextState))` can be used to replace
+* the current `state` value directly with an another state value.
 */
 function usePendingState(store) {
   let storeMap = (0, react.useContext)(PendingStateContext);
@@ -62,49 +61,50 @@ function usePendingState(store) {
     storeMap,
     storeItemInited
   ]));
-  return [
-    state,
-    (0, react.useCallback)((value, options) => {
-      if (value instanceof Promise) {
-        let delayedPending = null;
-        if (!options?.silent) {
-          let delay = options?.delay;
-          if (delay === void 0) setState((prevState) => ({
-            ...prevState,
-            ...createState(true, false)
-          }));
-          else delayedPending = setTimeout(() => {
-            setState((prevState) => ({
-              ...prevState,
-              ...createState(true, false)
-            }));
-            delayedPending = null;
-          }, delay);
-        }
-        return value.then((resolvedValue) => {
-          if (delayedPending !== null) clearTimeout(delayedPending);
-          setState((prevState) => ({
-            ...prevState,
-            ...createState(true, true)
-          }));
-          return resolvedValue;
-        }).catch((error) => {
-          if (delayedPending !== null) clearTimeout(delayedPending);
+  let track = (0, react.useCallback)((value, options) => {
+    if (value instanceof Promise) {
+      let delayedPending = null;
+      if (!options?.silent) {
+        let delay = options?.delay;
+        if (delay === void 0) setState((prevState) => ({
+          ...prevState,
+          ...createState(true, false)
+        }));
+        else delayedPending = setTimeout(() => {
           setState((prevState) => ({
             ...prevState,
-            ...createState(true, true, error)
+            ...createState(true, false)
           }));
-          if (options?.throws) throw error;
-        });
+          delayedPending = null;
+        }, delay);
       }
-      setState((prevState) => ({
-        ...prevState,
-        ...createState(true, true)
-      }));
-      return value;
-    }, [setState]),
-    setState
-  ];
+      return value.then((resolvedValue) => {
+        if (delayedPending !== null) clearTimeout(delayedPending);
+        setState((prevState) => ({
+          ...prevState,
+          ...createState(true, true)
+        }));
+        return resolvedValue;
+      }).catch((error) => {
+        if (delayedPending !== null) clearTimeout(delayedPending);
+        setState((prevState) => ({
+          ...prevState,
+          ...createState(true, true, error)
+        }));
+        if (options?.throws) throw error;
+      });
+    }
+    setState((prevState) => ({
+      ...prevState,
+      ...createState(true, true)
+    }));
+    return value;
+  }, [setState]);
+  return {
+    ...state,
+    track,
+    update: setState
+  };
 }
 
 exports.PendingStateContext = PendingStateContext;

package/dist/index.d.ts

@@ -21,7 +21,7 @@ declare const PendingStateProvider: ({
   children
 }: PendingStateProviderProps) => react_jsx_runtime0.JSX.Element;
 
-type WithStateOptions = {
+type TrackOptions = {
   /**
    * Whether to track the action state silently (e.g. with a background
    * action or an optimistic update).
@@ -51,13 +51,15 @@ type WithStateOptions = {
  * key or a shared store allows to share the state across multiple
  * components.
  *
- * @returns `[state, withState, setState]`, where
- * - `state` is the current value of the action's state;
- * - `withState(action, options?)` reads and tracks the `actions`'s state
- * which is exposed as `state` listed above;
- * - `setState(update)` can be used to replace the current `state` value
- * directly with an another state value.
+ * @returns `{ initialized, complete, error, track, update }`, where
+ * - `initialized`, `complete`, `error` reflect the current action's state;
+ * - `track(action, options?)` tracks the `actions`'s state;
+ * - `update(nextState | ((state) => nextState))` can be used to replace
+ * the current `state` value directly with an another state value.
  */
-declare function usePendingState(store?: string | Store<PendingState> | null): [PendingState, <T>(value: T) => T, SetStoreValue<PendingState>];
+declare function usePendingState(store?: string | Store<PendingState> | null): PendingState & {
+  track: <T>(value: T) => T;
+  update: SetStoreValue<PendingState>;
+};
 
-export { PendingState, PendingStateContext, PendingStateProvider, PendingStateProviderProps, WithStateOptions, usePendingState };
+export { PendingState, PendingStateContext, PendingStateProvider, PendingStateProviderProps, TrackOptions, usePendingState };

package/dist/index.mjs

@@ -33,12 +33,11 @@ function createState(initialized = false, complete = false, error) {
 * key or a shared store allows to share the state across multiple
 * components.
 *
-* @returns `[state, withState, setState]`, where
-* - `state` is the current value of the action's state;
-* - `withState(action, options?)` reads and tracks the `actions`'s state
-* which is exposed as `state` listed above;
-* - `setState(update)` can be used to replace the current `state` value
-* directly with an another state value.
+* @returns `{ initialized, complete, error, track, update }`, where
+* - `initialized`, `complete`, `error` reflect the current action's state;
+* - `track(action, options?)` tracks the `actions`'s state;
+* - `update(nextState | ((state) => nextState))` can be used to replace
+* the current `state` value directly with an another state value.
 */
 function usePendingState(store) {
   let storeMap = useContext(PendingStateContext);
@@ -62,49 +61,50 @@ function usePendingState(store) {
     storeMap,
     storeItemInited
   ]));
-  return [
-    state,
-    useCallback((value, options) => {
-      if (value instanceof Promise) {
-        let delayedPending = null;
-        if (!options?.silent) {
-          let delay = options?.delay;
-          if (delay === void 0) setState((prevState) => ({
-            ...prevState,
-            ...createState(true, false)
-          }));
-          else delayedPending = setTimeout(() => {
-            setState((prevState) => ({
-              ...prevState,
-              ...createState(true, false)
-            }));
-            delayedPending = null;
-          }, delay);
-        }
-        return value.then((resolvedValue) => {
-          if (delayedPending !== null) clearTimeout(delayedPending);
-          setState((prevState) => ({
-            ...prevState,
-            ...createState(true, true)
-          }));
-          return resolvedValue;
-        }).catch((error) => {
-          if (delayedPending !== null) clearTimeout(delayedPending);
+  let track = useCallback((value, options) => {
+    if (value instanceof Promise) {
+      let delayedPending = null;
+      if (!options?.silent) {
+        let delay = options?.delay;
+        if (delay === void 0) setState((prevState) => ({
+          ...prevState,
+          ...createState(true, false)
+        }));
+        else delayedPending = setTimeout(() => {
           setState((prevState) => ({
             ...prevState,
-            ...createState(true, true, error)
+            ...createState(true, false)
           }));
-          if (options?.throws) throw error;
-        });
+          delayedPending = null;
+        }, delay);
       }
-      setState((prevState) => ({
-        ...prevState,
-        ...createState(true, true)
-      }));
-      return value;
-    }, [setState]),
-    setState
-  ];
+      return value.then((resolvedValue) => {
+        if (delayedPending !== null) clearTimeout(delayedPending);
+        setState((prevState) => ({
+          ...prevState,
+          ...createState(true, true)
+        }));
+        return resolvedValue;
+      }).catch((error) => {
+        if (delayedPending !== null) clearTimeout(delayedPending);
+        setState((prevState) => ({
+          ...prevState,
+          ...createState(true, true, error)
+        }));
+        if (options?.throws) throw error;
+      });
+    }
+    setState((prevState) => ({
+      ...prevState,
+      ...createState(true, true)
+    }));
+    return value;
+  }, [setState]);
+  return {
+    ...state,
+    track,
+    update: setState
+  };
 }
 
 export { PendingStateContext, PendingStateProvider, usePendingState };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@t8/react-pending",
-  "version": "1.0.32",
-  "description": "A concise async action state management lib for React apps",
+  "version": "1.1.0",
+  "description": "Self-contained async action state management for React apps",
   "main": "./dist/index.cjs",
   "module": "./dist/index.mjs",
   "types": "./dist/index.d.ts",
@@ -22,6 +22,7 @@
   "keywords": [
     "async actions",
     "pending state",
+    "async state",
     "react"
   ],
   "peerDependencies": {
@@ -36,6 +37,6 @@
     "react-dom": "^19.2.3"
   },
   "dependencies": {
-    "@t8/react-store": "^1.2.7"
+    "@t8/react-store": "^1.2.8"
   }
 }

package/src/usePendingState.ts

@@ -16,7 +16,7 @@ function createState(
   };
 }
 
-export type WithStateOptions = {
+export type TrackOptions = {
   /**
    * Whether to track the action state silently (e.g. with a background
    * action or an optimistic update).
@@ -47,16 +47,18 @@ export type WithStateOptions = {
  * key or a shared store allows to share the state across multiple
  * components.
  *
- * @returns `[state, withState, setState]`, where
- * - `state` is the current value of the action's state;
- * - `withState(action, options?)` reads and tracks the `actions`'s state
- * which is exposed as `state` listed above;
- * - `setState(update)` can be used to replace the current `state` value
- * directly with an another state value.
+ * @returns `{ initialized, complete, error, track, update }`, where
+ * - `initialized`, `complete`, `error` reflect the current action's state;
+ * - `track(action, options?)` tracks the `actions`'s state;
+ * - `update(nextState | ((state) => nextState))` can be used to replace
+ * the current `state` value directly with an another state value.
  */
 export function usePendingState(
   store?: string | Store<PendingState> | null,
-): [PendingState, <T>(value: T) => T, SetStoreValue<PendingState>] {
+): PendingState & {
+  track: <T>(value: T) => T;
+  update: SetStoreValue<PendingState>;
+} {
   let storeMap = useContext(PendingStateContext);
   let storeRef = useRef<Store<PendingState> | null>(null);
   let [storeItemInited, setStoreItemInited] = useState(false);
@@ -84,8 +86,8 @@ export function usePendingState(
 
   let [state, setState] = useStore(resolvedStore);
 
-  let withState = useCallback(
-    <T>(value: T, options?: WithStateOptions): T => {
+  let track = useCallback(
+    <T>(value: T, options?: TrackOptions): T => {
       if (value instanceof Promise) {
         let delayedPending: ReturnType<typeof setTimeout> | null = null;
 
@@ -141,5 +143,9 @@ export function usePendingState(
     [setState],
   );
 
-  return [state, withState, setState];
+  return {
+    ...state,
+    track,
+    update: setState,
+  };
 }