@t8/react-pending 1.1.1 → 1.2.0

package/README.md

@@ -12,14 +12,14 @@ Self-contained async action state management for React apps
 
   export let ItemList = () => {
     let [items, setItems] = useState([]);
-+   let { complete, error, track } = usePendingState("fetch-items");
++   let { initial, pending, error, track } = usePendingState("fetch-items");
 
     useEffect(() => {
 -     fetchItems().then(setItems);
 +     track(fetchItems()).then(setItems);
     }, [fetchItems, track]);
 
-+   if (!complete) return <p>Loading...</p>;
++   if (initial || pending) return <p>Loading...</p>;
 +   if (error) return <p>An error occurred</p>;
 
     return <ul>{items.map(/* ... */)}</ul>;
@@ -40,14 +40,14 @@ In our setup, there are two components rendering their content with regard to th
 
   export let ItemList = () => {
     let [items, setItems] = useState([]);
-+   let { complete, error, track } = usePendingState("fetch-items");
++   let { initial, pending, error, track } = usePendingState("fetch-items");
 
     useEffect(() => {
 -     fetchItems().then(setItems);
 +     track(fetchItems()).then(setItems);
     }, [fetchItems, track]);
 
-+   if (!complete) return <p>Loading...</p>;
++   if (initial || pending) return <p>Loading...</p>;
 +   if (error) return <p>An error occurred</p>;
 
     return <ul>{items.map(/* ... */)}</ul>;
@@ -58,10 +58,10 @@ In our setup, there are two components rendering their content with regard to th
 + import { usePendingState } from "@t8/react-pending";
 
   export let Status = () => {
-+   let { initialized, complete, error } = usePendingState("fetch-items");
++   let { initial, pending, error } = usePendingState("fetch-items");
 
-    if (!initialized) return null;
-    if (!complete) return <>Busy</>;
+    if (initial) return null;
+    if (pending) return <>Busy</>;
     if (error) return <>Error</>;
 
     return <>OK</>;
@@ -79,8 +79,8 @@ 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 { complete } = usePendingState("fetch-items"); // shared
-+ let { complete } = usePendingState(); // local
+- let { initial, pending, error } = usePendingState("fetch-items"); // shared
++ let { initial, pending, error } = usePendingState(); // local
 ```
 
 ## Silent tracking of background actions and optimistic updates
@@ -90,7 +90,7 @@ Omit the custom string key parameter of `usePendingState()` to scope the pending
 + track(fetchItems(), { silent: true })
 ```
 
-⬥ This option prevents `complete` from switching to `false` in the pending state.
+⬥ This option prevents the `pending` property from switching to `false` in the pending state.
 
 ## Delayed pending state
 
@@ -127,7 +127,7 @@ Omit the custom string key parameter of `usePendingState()` to scope the pending
 
 ```diff
 + let initialState = {
-+   "fetch-items": { initialized: true, complete: true },
++   "fetch-items": { initial: false, pending: true },
 + };
 
 - <PendingStateProvider>

package/dist/index.cjs

@@ -18,10 +18,10 @@ const PendingStateProvider = ({ value, children }) => {
   });
 };
 
-function createState(initialized = false, complete = false, error) {
+function createState(initial = true, pending = false, error) {
   return {
-    initialized,
-    complete,
+    initial,
+    pending,
     error,
     time: Date.now()
   };
@@ -29,15 +29,16 @@ function createState(initialized = false, complete = false, error) {
 /**
 * Returns an instance of an action's state and the functions to update it.
 *
-* @param store - A unique store key or a store. Providing a store
+* @param store - An optional unique string key or a store. Providing a
 * key or a shared store allows to share the state across multiple
-* components.
+* components. If omitted, the pending state stays locally scoped to the
+* component where the hook is used.
 *
-* @returns `{ initialized, complete, error, track, update }`, where
-* - `initialized`, `complete`, `error` reflect the current action's state;
+* @returns `{ initial, pending, error, track, update }`, where
+* - `initial`, `pending`, `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.
+* the current pending state directly with an another value.
 */
 function usePendingState(store) {
   let storeMap = (0, react.useContext)(PendingStateContext);
@@ -68,12 +69,12 @@ function usePendingState(store) {
         let delay = options?.delay;
         if (delay === void 0) setState((prevState) => ({
           ...prevState,
-          ...createState(true, false)
+          ...createState(false, true)
         }));
         else delayedPending = setTimeout(() => {
           setState((prevState) => ({
             ...prevState,
-            ...createState(true, false)
+            ...createState(false, true)
           }));
           delayedPending = null;
         }, delay);
@@ -82,21 +83,21 @@ function usePendingState(store) {
         if (delayedPending !== null) clearTimeout(delayedPending);
         setState((prevState) => ({
           ...prevState,
-          ...createState(true, true)
+          ...createState(false, false)
         }));
         return resolvedValue;
       }).catch((error) => {
         if (delayedPending !== null) clearTimeout(delayedPending);
         setState((prevState) => ({
           ...prevState,
-          ...createState(true, true, error)
+          ...createState(false, false, error)
         }));
         if (options?.throws) throw error;
       });
     }
     setState((prevState) => ({
       ...prevState,
-      ...createState(true, true)
+      ...createState(false, false)
     }));
     return value;
   }, [setState]);

package/dist/index.d.ts

@@ -4,10 +4,10 @@ import { SetStoreValue, Store } from "@t8/react-store";
 import * as react_jsx_runtime0 from "react/jsx-runtime";
 
 type PendingState = {
-  initialized?: boolean | undefined;
-  complete?: boolean | undefined;
-  time?: number | undefined;
+  initial?: boolean | undefined;
+  pending?: boolean | undefined;
   error?: unknown;
+  time?: number | undefined;
 };
 
 declare const PendingStateContext: react0.Context<Map<string, Store<PendingState>>>;
@@ -26,12 +26,12 @@ type TrackOptions = {
    * Whether to track the action state silently (e.g. with a background
    * action or an optimistic update).
    *
-   * When set to `true`, the state's `complete` property doesn't switch
-   * to `false` in the pending state.
+   * When set to `true`, the state's `pending` property doesn't switch
+   * to `true` in the pending state.
    */
   silent?: boolean;
   /**
-   * Delays switching the action state's `complete` property to `false`
+   * Delays switching the action state's `pending` property to `true`
    * in the pending state by the given number of milliseconds.
    *
    * Use case: to avoid flashing a process indicator if the action is
@@ -47,15 +47,16 @@ type TrackOptions = {
 /**
  * Returns an instance of an action's state and the functions to update it.
  *
- * @param store - A unique store key or a store. Providing a store
+ * @param store - An optional unique string key or a store. Providing a
  * key or a shared store allows to share the state across multiple
- * components.
+ * components. If omitted, the pending state stays locally scoped to the
+ * component where the hook is used.
  *
- * @returns `{ initialized, complete, error, track, update }`, where
- * - `initialized`, `complete`, `error` reflect the current action's state;
+ * @returns `{ initial, pending, error, track, update }`, where
+ * - `initial`, `pending`, `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.
+ * the current pending state directly with an another value.
  */
 declare function usePendingState(store?: string | Store<PendingState> | null): PendingState & {
   track: <T>(value: T) => T;

package/dist/index.mjs

@@ -18,10 +18,10 @@ const PendingStateProvider = ({ value, children }) => {
   });
 };
 
-function createState(initialized = false, complete = false, error) {
+function createState(initial = true, pending = false, error) {
   return {
-    initialized,
-    complete,
+    initial,
+    pending,
     error,
     time: Date.now()
   };
@@ -29,15 +29,16 @@ function createState(initialized = false, complete = false, error) {
 /**
 * Returns an instance of an action's state and the functions to update it.
 *
-* @param store - A unique store key or a store. Providing a store
+* @param store - An optional unique string key or a store. Providing a
 * key or a shared store allows to share the state across multiple
-* components.
+* components. If omitted, the pending state stays locally scoped to the
+* component where the hook is used.
 *
-* @returns `{ initialized, complete, error, track, update }`, where
-* - `initialized`, `complete`, `error` reflect the current action's state;
+* @returns `{ initial, pending, error, track, update }`, where
+* - `initial`, `pending`, `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.
+* the current pending state directly with an another value.
 */
 function usePendingState(store) {
   let storeMap = useContext(PendingStateContext);
@@ -68,12 +69,12 @@ function usePendingState(store) {
         let delay = options?.delay;
         if (delay === void 0) setState((prevState) => ({
           ...prevState,
-          ...createState(true, false)
+          ...createState(false, true)
         }));
         else delayedPending = setTimeout(() => {
           setState((prevState) => ({
             ...prevState,
-            ...createState(true, false)
+            ...createState(false, true)
           }));
           delayedPending = null;
         }, delay);
@@ -82,21 +83,21 @@ function usePendingState(store) {
         if (delayedPending !== null) clearTimeout(delayedPending);
         setState((prevState) => ({
           ...prevState,
-          ...createState(true, true)
+          ...createState(false, false)
         }));
         return resolvedValue;
       }).catch((error) => {
         if (delayedPending !== null) clearTimeout(delayedPending);
         setState((prevState) => ({
           ...prevState,
-          ...createState(true, true, error)
+          ...createState(false, false, error)
         }));
         if (options?.throws) throw error;
       });
     }
     setState((prevState) => ({
       ...prevState,
-      ...createState(true, true)
+      ...createState(false, false)
     }));
     return value;
   }, [setState]);

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@t8/react-pending",
-  "version": "1.1.1",
+  "version": "1.2.0",
   "description": "Self-contained async action state management for React apps",
   "main": "./dist/index.cjs",
   "module": "./dist/index.mjs",
   "types": "./dist/index.d.ts",
   "type": "module",
   "scripts": {
-    "demo": "npx @t8/serve tests/async_status --spa -b src/index.tsx",
+    "demo": "npx @t8/serve tests/async_state --spa -b src/index.tsx",
     "preversion": "npx npm-run-all shape test",
     "shape": "npx codeshape",
     "test": "npx playwright test --project=chromium"

package/src/PendingState.ts

@@ -1,6 +1,6 @@
 export type PendingState = {
-  initialized?: boolean | undefined;
-  complete?: boolean | undefined;
-  time?: number | undefined;
+  initial?: boolean | undefined;
+  pending?: boolean | undefined;
   error?: unknown;
+  time?: number | undefined;
 };

package/src/usePendingState.ts

@@ -4,13 +4,13 @@ import type { PendingState } from "./PendingState.ts";
 import { PendingStateContext } from "./PendingStateContext.ts";
 
 function createState(
-  initialized = false,
-  complete = false,
+  initial = true,
+  pending = false,
   error?: unknown,
 ): PendingState {
   return {
-    initialized,
-    complete,
+    initial,
+    pending,
     error,
     time: Date.now(),
   };
@@ -21,12 +21,12 @@ export type TrackOptions = {
    * Whether to track the action state silently (e.g. with a background
    * action or an optimistic update).
    *
-   * When set to `true`, the state's `complete` property doesn't switch
-   * to `false` in the pending state.
+   * When set to `true`, the state's `pending` property doesn't switch
+   * to `true` in the pending state.
    */
   silent?: boolean;
   /**
-   * Delays switching the action state's `complete` property to `false`
+   * Delays switching the action state's `pending` property to `true`
    * in the pending state by the given number of milliseconds.
    *
    * Use case: to avoid flashing a process indicator if the action is
@@ -43,15 +43,16 @@ export type TrackOptions = {
 /**
  * Returns an instance of an action's state and the functions to update it.
  *
- * @param store - A unique store key or a store. Providing a store
+ * @param store - An optional unique string key or a store. Providing a
  * key or a shared store allows to share the state across multiple
- * components.
+ * components. If omitted, the pending state stays locally scoped to the
+ * component where the hook is used.
  *
- * @returns `{ initialized, complete, error, track, update }`, where
- * - `initialized`, `complete`, `error` reflect the current action's state;
+ * @returns `{ initial, pending, error, track, update }`, where
+ * - `initial`, `pending`, `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.
+ * the current pending state directly with an another value.
  */
 export function usePendingState(
   store?: string | Store<PendingState> | null,
@@ -97,13 +98,13 @@ export function usePendingState(
           if (delay === undefined)
             setState((prevState) => ({
               ...prevState,
-              ...createState(true, false),
+              ...createState(false, true),
             }));
           else
             delayedPending = setTimeout(() => {
               setState((prevState) => ({
                 ...prevState,
-                ...createState(true, false),
+                ...createState(false, true),
               }));
 
               delayedPending = null;
@@ -116,7 +117,7 @@ export function usePendingState(
 
             setState((prevState) => ({
               ...prevState,
-              ...createState(true, true),
+              ...createState(false, false),
             }));
 
             return resolvedValue;
@@ -126,7 +127,7 @@ export function usePendingState(
 
             setState((prevState) => ({
               ...prevState,
-              ...createState(true, true, error),
+              ...createState(false, false, error),
             }));
 
             if (options?.throws) throw error;
@@ -135,7 +136,7 @@ export function usePendingState(
 
       setState((prevState) => ({
         ...prevState,
-        ...createState(true, true),
+        ...createState(false, false),
       }));
 
       return value;