@t8/react-pending 1.0.12 → 1.0.14

package/README.md

@@ -13,43 +13,43 @@ Installation: `npm i @t8/react-pending`
 Objective: Track the pending state of the async `fetchItems()` action to tell the user whether the UI is busy or encountered an error (preferably without rewriting the action and the app's state management).
 
 ```diff
-+ import {usePendingState} from '@t8/react-pending';
++ import { usePendingState } from "@t8/react-pending";
 
   const ItemList = () => {
-      const [items, setItems] = useState([]);
-      // the custom string key parameter tags the action's state so
-      // that another component can access this state by the same tag
-+     const [state, withState] = usePendingState('fetch-items');
+    const [items, setItems] = useState([]);
+    // the custom string key parameter tags the action's state so
+    // that another component can access this state by the same tag
++   const [state, withState] = usePendingState("fetch-items");
 
-      useEffect(() => {
-          // wrapping fetchItems() to track the async action's state
--         fetchItems().then(setItems);
-+         withState(fetchItems()).then(setItems);
-      }, [fetchItems, withState]);
+    useEffect(() => {
+      // wrapping fetchItems() to track the async action's state
+-     fetchItems().then(setItems);
++     withState(fetchItems()).then(setItems);
+    }, [fetchItems, withState]);
 
-+     if (!state.complete)
-+         return <p>Loading...</p>;
++   if (!state.complete)
++     return <p>Loading...</p>;
 
-+     if (state.error)
-+         return <p>An error occurred</p>;
++   if (state.error)
++     return <p>An error occurred</p>;
 
-      return <ul>{items.map(/* ... */)}</ul>;
+    return <ul>{items.map(/* ... */)}</ul>;
   };
 
   const Status = () => {
-      // reading the 'fetch-items' state updated in ItemList
-+     const [state] = usePendingState('fetch-items');
+    // reading the "fetch-items" state updated in ItemList
++   const [state] = usePendingState("fetch-items");
 
-      if (!state.initialized)
-          return 'Initial';
+    if (!state.initialized)
+      return "Initial";
 
-      if (!state.complete)
-          return 'Busy';
+    if (!state.complete)
+      return "Busy";
 
-      if (state.error)
-          return 'Error';
+    if (state.error)
+      return "Error";
 
-      return 'OK';
+    return "OK";
   };
 ```
 
@@ -58,7 +58,7 @@ Objective: Track the pending state of the async `fetchItems()` action to tell th
 🔹 If the action's state is only used within a single component, it can be used locally by omitting the custom string key parameter of the `usePendingState()` hook.
 
 ```diff
-- const [state, withState] = usePendingState('fetch-items');
+- const [state, withState] = usePendingState("fetch-items");
 + const [state, withState] = usePendingState();
 ```
 
@@ -68,27 +68,27 @@ Objective: Track the pending state of the async `fetchItems()` action to tell th
 
 ```diff
 - withState(fetchItems())
-+ withState(fetchItems(), {silent: true})
++ withState(fetchItems(), { silent: true })
 ```
 
 🔹 Revealing the action's pending state after a delay (e.g. to avoid flashing a process indicator when the action is likely to complete by the end of the delay):
 
 ```diff
 - withState(fetchItems())
-+ withState(fetchItems(), {delay: 500})
++ withState(fetchItems(), { delay: 500 })
 ```
 
 🔹 Allowing the action's Promise value to reject explicitly (e.g. in order to provide the action with a custom rejection handler) along with exposing `state.error` that goes by default:
 
 ```diff
 - withState(fetchItems())
-+ withState(fetchItems(), {throws: true}).catch(handleError)
++ withState(fetchItems(), { throws: true }).catch(handleError)
 ```
 
 🔹 Providing an isolated instance of initial shared action state, e.g. for tests or SSR (it can be unnecessary for client-side rendering where the default context value is sufficient, but it can also be used to separate action states of larger self-contained portions of a web app):
 
 ```diff
-+ import {PendingStateProvider} from '@t8/react-pending';
++ import { PendingStateProvider } from "@t8/react-pending";
 
 - <App/>
 + <PendingStateProvider>
@@ -100,7 +100,7 @@ Objective: Track the pending state of the async `fetchItems()` action to tell th
 
 ```diff
 + const initialState = {
-+   'fetch-items': { initialized: true, complete: true },
++   "fetch-items": { initialized: true, complete: true },
 + };
 
 - <PendingStateProvider>
@@ -109,4 +109,4 @@ Objective: Track the pending state of the async `fetchItems()` action to tell th
   </PendingStateProvider>
 ```
 
-With an explicit value or without, the `<PendingStateProvider>`'s nested components will only respond to updates in the particular action states they subscribed to by means of `usePendingState('action-key')`.
+With an explicit value or without, the `<PendingStateProvider>`'s nested components will only respond to updates in the particular action states they subscribed to by means of `usePendingState("action-key")`.

package/dist/index.js

@@ -78,10 +78,7 @@ var PendingStateProvider = ({
     if (value instanceof Map) return value;
     if (typeof value === "object" && value !== null)
       return new Map(
-        Object.entries(value).map(([key, state]) => [
-          key,
-          new Store(state)
-        ])
+        Object.entries(value).map(([key, state]) => [key, new Store(state)])
       );
     if (defaultValueRef.current === null)
       defaultValueRef.current = /* @__PURE__ */ new Map();
@@ -140,16 +137,14 @@ function usePendingState(store) {
             }, delay);
         }
         return value.then((resolvedValue) => {
-          if (delayedPending !== null)
-            clearTimeout(delayedPending);
+          if (delayedPending !== null) clearTimeout(delayedPending);
           setState((prevState) => ({
             ...prevState,
             ...createState(true, true)
           }));
           return resolvedValue;
         }).catch((error) => {
-          if (delayedPending !== null)
-            clearTimeout(delayedPending);
+          if (delayedPending !== null) clearTimeout(delayedPending);
           setState((prevState) => ({
             ...prevState,
             ...createState(true, true, error)

package/index.ts

@@ -1,4 +1,4 @@
-export * from './src/PendingState';
-export * from './src/PendingStateContext';
-export * from './src/PendingStateProvider';
-export * from './src/usePendingState';
+export * from "./src/PendingState";
+export * from "./src/PendingStateContext";
+export * from "./src/PendingStateProvider";
+export * from "./src/usePendingState";

package/package.json

@@ -1,39 +1,46 @@
-{
-  "name": "@t8/react-pending",
-  "version": "1.0.12",
-  "description": "Concise async action state tracking for React apps",
-  "main": "dist/index.js",
-  "type": "module",
-  "scripts": {
-    "build": "npx npm-run-all clean compile",
-    "clean": "node -e \"require('node:fs').rmSync('dist', {force: true, recursive: true});\"",
-    "compile": "npx esbuild index.ts --bundle --outdir=dist --platform=neutral --external:react",
-    "gh-pages": "npx ghstage --theme=t8 --ymid=103784239 --nav=https://raw.githubusercontent.com/t8js/t8js.github.io/refs/heads/main/assets/nav.html",
-    "prepublishOnly": "npx npm-run-all build gh-pages",
-    "preversion": "npx npm-run-all typecheck shape build",
-    "shape": "npx codeshape",
-    "typecheck": "tsc --noEmit"
-  },
-  "author": "axtk",
-  "license": "ISC",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/t8js/react-pending.git"
-  },
-  "homepage": "https://t8.js.org/react-pending",
-  "keywords": [
-    "async actions",
-    "pending state",
-    "react"
-  ],
-  "peerDependencies": {
-    "react": ">=16.8"
-  },
-  "devDependencies": {
-    "@types/react": "^19.1.10",
-    "typescript": "^5.9.2"
-  },
-  "dependencies": {
-    "@t8/react-store": "^1.0.12"
-  }
-}
+{
+  "name": "@t8/react-pending",
+  "version": "1.0.14",
+  "description": "Concise async action state tracking for React apps",
+  "main": "dist/index.js",
+  "type": "module",
+  "scripts": {
+    "build": "npx npm-run-all clean compile",
+    "clean": "node -e \"require('node:fs').rmSync('dist', {force: true, recursive: true});\"",
+    "compile": "npx esbuild index.ts --bundle --outdir=dist --platform=neutral --external:react",
+    "demo": "npx @t8/serve 3000 * tests/async_status -b src/index.tsx",
+    "gh-pages": "npx ghstage --theme=t8 --ymid=103784239 --nav=https://raw.githubusercontent.com/t8js/t8js.github.io/refs/heads/main/assets/nav.html",
+    "prepublishOnly": "npx npm-run-all build gh-pages",
+    "preversion": "npx npm-run-all typecheck shape build test",
+    "shape": "npx codeshape",
+    "test": "npx playwright test --project=chromium",
+    "typecheck": "tsc --noEmit"
+  },
+  "author": "axtk",
+  "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/t8js/react-pending.git"
+  },
+  "homepage": "https://t8.js.org/react-pending",
+  "keywords": [
+    "async actions",
+    "pending state",
+    "react"
+  ],
+  "peerDependencies": {
+    "react": ">=16.8"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.55.1",
+    "@t8/serve": "^0.1.19",
+    "@types/node": "^24.5.2",
+    "@types/react": "^19.1.10",
+    "@types/react-dom": "^19.1.9",
+    "react-dom": "^19.1.1",
+    "typescript": "^5.9.2"
+  },
+  "dependencies": {
+    "@t8/react-store": "^1.0.15"
+  }
+}

package/src/PendingState.ts

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

package/src/PendingStateContext.ts

@@ -1,7 +1,7 @@
-import type {Store} from '@t8/react-store';
-import {createContext} from 'react';
-import type {PendingState} from './PendingState';
+import type { Store } from "@t8/react-store";
+import { createContext } from "react";
+import type { PendingState } from "./PendingState";
 
 export const PendingStateContext = createContext(
-    new Map<string, Store<PendingState>>(),
+  new Map<string, Store<PendingState>>(),
 );

package/src/PendingStateProvider.tsx

@@ -1,43 +1,40 @@
-import {Store} from '@t8/react-store';
-import {type ReactNode, useMemo, useRef} from 'react';
-import type {PendingState} from './PendingState';
-import {PendingStateContext} from './PendingStateContext';
+import { Store } from "@t8/react-store";
+import { type ReactNode, useMemo, useRef } from "react";
+import type { PendingState } from "./PendingState";
+import { PendingStateContext } from "./PendingStateContext";
 
 export type PendingStateProviderProps = {
-    value?:
-        | Record<string, PendingState>
-        | Map<string, Store<PendingState>>
-        | null
-        | undefined;
-    children?: ReactNode;
+  value?:
+    | Record<string, PendingState>
+    | Map<string, Store<PendingState>>
+    | null
+    | undefined;
+  children?: ReactNode;
 };
 
 export const PendingStateProvider = ({
-    value,
-    children,
+  value,
+  children,
 }: PendingStateProviderProps) => {
-    let defaultValueRef = useRef<Map<string, Store<PendingState>> | null>(null);
+  let defaultValueRef = useRef<Map<string, Store<PendingState>> | null>(null);
 
-    let resolvedValue = useMemo(() => {
-        if (value instanceof Map) return value;
+  let resolvedValue = useMemo(() => {
+    if (value instanceof Map) return value;
 
-        if (typeof value === 'object' && value !== null)
-            return new Map(
-                Object.entries(value).map(([key, state]) => [
-                    key,
-                    new Store(state),
-                ]),
-            );
+    if (typeof value === "object" && value !== null)
+      return new Map(
+        Object.entries(value).map(([key, state]) => [key, new Store(state)]),
+      );
 
-        if (defaultValueRef.current === null)
-            defaultValueRef.current = new Map<string, Store<PendingState>>();
+    if (defaultValueRef.current === null)
+      defaultValueRef.current = new Map<string, Store<PendingState>>();
 
-        return defaultValueRef.current;
-    }, [value]);
+    return defaultValueRef.current;
+  }, [value]);
 
-    return (
-        <PendingStateContext.Provider value={resolvedValue}>
-            {children}
-        </PendingStateContext.Provider>
-    );
+  return (
+    <PendingStateContext.Provider value={resolvedValue}>
+      {children}
+    </PendingStateContext.Provider>
+  );
 };

package/src/usePendingState.ts

@@ -1,25 +1,25 @@
-import {isStore, type SetStoreState, Store, useStore} from '@t8/react-store';
-import {useCallback, useContext, useMemo, useRef, useState} from 'react';
-import type {PendingState} from './PendingState';
-import {PendingStateContext} from './PendingStateContext';
+import { isStore, type SetStoreState, Store, useStore } from "@t8/react-store";
+import { useCallback, useContext, useMemo, useRef, useState } from "react";
+import type { PendingState } from "./PendingState";
+import { PendingStateContext } from "./PendingStateContext";
 
 function createState(
-    initialized = false,
-    complete = false,
-    error?: unknown,
+  initialized = false,
+  complete = false,
+  error?: unknown,
 ): PendingState {
-    return {
-        initialized,
-        complete,
-        error,
-        time: Date.now(),
-    };
+  return {
+    initialized,
+    complete,
+    error,
+    time: Date.now(),
+  };
 }
 
 export type WithStateOptions = {
-    silent?: boolean;
-    throws?: boolean;
-    delay?: number;
+  silent?: boolean;
+  throws?: boolean;
+  delay?: number;
 };
 
 /**
@@ -32,98 +32,96 @@ export type WithStateOptions = {
  * - `setState()` to directly update the state.
  */
 export function usePendingState(
-    /**
-     * A unique store key or a store. Providing a store key or a
-     * shared store allows to share the state across multiple
-     * components.
-     */
-    store?: string | Store<PendingState> | null,
+  /**
+   * A unique store key or a store. Providing a store key or a
+   * shared store allows to share the state across multiple
+   * components.
+   */
+  store?: string | Store<PendingState> | null,
 ): [PendingState, <T>(value: T) => T, SetStoreState<PendingState>] {
-    let storeMap = useContext(PendingStateContext);
-    let storeRef = useRef<Store<PendingState> | null>(null);
-    let [storeItemInited, setStoreItemInited] = useState(false);
+  let storeMap = useContext(PendingStateContext);
+  let storeRef = useRef<Store<PendingState> | null>(null);
+  let [storeItemInited, setStoreItemInited] = useState(false);
 
-    let resolvedStore = useMemo(() => {
-        if (isStore<PendingState>(store)) return store;
+  let resolvedStore = useMemo(() => {
+    if (isStore<PendingState>(store)) return store;
 
-        if (typeof store === 'string') {
-            let storeItem = storeMap.get(store);
+    if (typeof store === "string") {
+      let storeItem = storeMap.get(store);
 
-            if (!storeItem) {
-                storeItem = new Store(createState());
-                storeMap.set(store, storeItem);
+      if (!storeItem) {
+        storeItem = new Store(createState());
+        storeMap.set(store, storeItem);
 
-                if (!storeItemInited) setStoreItemInited(true);
-            }
+        if (!storeItemInited) setStoreItemInited(true);
+      }
 
-            return storeItem;
-        }
+      return storeItem;
+    }
+
+    if (!storeRef.current) storeRef.current = new Store(createState());
+
+    return storeRef.current;
+  }, [store, storeMap, storeItemInited]);
+
+  let [state, setState] = useStore(resolvedStore);
 
-        if (!storeRef.current) storeRef.current = new Store(createState());
-
-        return storeRef.current;
-    }, [store, storeMap, storeItemInited]);
-
-    let [state, setState] = useStore(resolvedStore);
-
-    let withState = useCallback(
-        <T>(value: T, options?: WithStateOptions): T => {
-            if (value instanceof Promise) {
-                let delayedPending: ReturnType<typeof setTimeout> | null = null;
-
-                if (!options?.silent) {
-                    let delay = options?.delay;
-
-                    if (delay === undefined)
-                        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);
-
-                        setState(prevState => ({
-                            ...prevState,
-                            ...createState(true, true, error),
-                        }));
-
-                        if (options?.throws) throw error;
-                    }) as T;
-            }
-
-            setState(prevState => ({
+  let withState = useCallback(
+    <T>(value: T, options?: WithStateOptions): T => {
+      if (value instanceof Promise) {
+        let delayedPending: ReturnType<typeof setTimeout> | null = null;
+
+        if (!options?.silent) {
+          let delay = options?.delay;
+
+          if (delay === undefined)
+            setState((prevState) => ({
+              ...prevState,
+              ...createState(true, false),
+            }));
+          else
+            delayedPending = setTimeout(() => {
+              setState((prevState) => ({
                 ...prevState,
-                ...createState(true, true),
+                ...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);
+
+            setState((prevState) => ({
+              ...prevState,
+              ...createState(true, true, error),
             }));
 
-            return value;
-        },
-        [setState],
-    );
+            if (options?.throws) throw error;
+          }) as T;
+      }
+
+      setState((prevState) => ({
+        ...prevState,
+        ...createState(true, true),
+      }));
+
+      return value;
+    },
+    [setState],
+  );
 
-    return [state, withState, setState];
+  return [state, withState, setState];
 }

package/tsconfig.json

@@ -1,13 +1,13 @@
-{
-    "include": ["index.ts"],
-    "compilerOptions": {
-        "lib": ["ESNext", "DOM"],
-        "target": "ESNext",
-        "outDir": "dist",
-        "moduleResolution": "node",
-        "jsx": "react-jsx",
-        "strict": true,
-        "noUnusedLocals": true,
-        "noUnusedParameters": true
-    }
-}
+{
+  "include": ["index.ts", "playwright.config.ts", "src", "tests"],
+  "compilerOptions": {
+    "lib": ["ESNext", "DOM"],
+    "target": "ESNext",
+    "outDir": "dist",
+    "moduleResolution": "node",
+    "jsx": "react-jsx",
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true
+  }
+}