@t8/react-pending 0.1.0

package/dist/index.js

@@ -0,0 +1,170 @@
+// src/PendingStateContext.ts
+import { createContext } from "react";
+var PendingStateContext = createContext(
+  /* @__PURE__ */ new Map()
+);
+
+// node_modules/@t8/store/src/isStore.ts
+function isStore(x) {
+  return x !== null && typeof x === "object" && "onUpdate" in x && typeof x.onUpdate === "function" && "getState" in x && typeof x.getState === "function" && "setState" in x && typeof x.setState === "function";
+}
+
+// node_modules/@t8/store/src/Store.ts
+var Store = class {
+  state;
+  callbacks;
+  constructor(data) {
+    this.state = data;
+    this.callbacks = [];
+  }
+  onUpdate(callback) {
+    this.callbacks.push(callback);
+    return () => {
+      for (let i = this.callbacks.length - 1; i >= 0; i--) {
+        if (this.callbacks[i] === callback) this.callbacks.splice(i, 1);
+      }
+    };
+  }
+  getState() {
+    return this.state;
+  }
+  setState(update) {
+    let prevState = this.state;
+    let nextState = update instanceof Function ? update(this.state) : update;
+    this.state = nextState;
+    for (let callback of this.callbacks) callback(nextState, prevState);
+  }
+};
+
+// node_modules/@t8/react-store/src/useStore.ts
+import { useEffect, useMemo, useRef, useState } from "react";
+function useStore(store, shouldUpdate = true) {
+  if (!isStore(store)) throw new Error("'store' is not an instance of Store");
+  let [, setRevision] = useState(-1);
+  let initedRef = useRef(false);
+  let state = store.getState();
+  let setState = useMemo(() => store.setState.bind(store), [store]);
+  useEffect(() => {
+    if (!shouldUpdate) return;
+    let unsubscribe = store.onUpdate((nextState, prevState) => {
+      if (typeof shouldUpdate !== "function" || shouldUpdate(nextState, prevState))
+        setRevision(Math.random());
+    });
+    if (!initedRef.current) {
+      initedRef.current = true;
+      setRevision(Math.random());
+    }
+    return () => {
+      unsubscribe();
+      initedRef.current = false;
+    };
+  }, [store, shouldUpdate]);
+  return [state, setState];
+}
+
+// src/PendingStateProvider.tsx
+import { useMemo as useMemo2, useRef as useRef2 } from "react";
+import { jsx } from "react/jsx-runtime";
+var PendingStateProvider = ({
+  value,
+  children
+}) => {
+  let defaultValueRef = useRef2(null);
+  let resolvedValue = useMemo2(() => {
+    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 (defaultValueRef.current === null)
+      defaultValueRef.current = /* @__PURE__ */ new Map();
+    return defaultValueRef.current;
+  }, [value]);
+  return /* @__PURE__ */ jsx(PendingStateContext.Provider, { value: resolvedValue, children });
+};
+
+// src/usePendingState.ts
+import { useCallback, useContext, useMemo as useMemo3, useRef as useRef3, useState as useState2 } from "react";
+function createState(initialized = false, complete = false, error) {
+  return {
+    initialized,
+    complete,
+    error,
+    time: Date.now()
+  };
+}
+function usePendingState(store) {
+  let storeMap = useContext(PendingStateContext);
+  let storeRef = useRef3(null);
+  let [storeItemInited, setStoreItemInited] = useState2(false);
+  let resolvedStore = useMemo3(() => {
+    if (isStore(store)) return store;
+    if (typeof store === "string") {
+      let storeItem = storeMap.get(store);
+      if (!storeItem) {
+        storeItem = new Store(createState());
+        storeMap.set(store, storeItem);
+        if (!storeItemInited) setStoreItemInited(true);
+      }
+      return storeItem;
+    }
+    if (!storeRef.current) storeRef.current = new Store(createState());
+    return storeRef.current;
+  }, [store, storeMap, storeItemInited]);
+  let [state, setState] = useStore(resolvedStore);
+  let withState = 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);
+          setState((prevState) => ({
+            ...prevState,
+            ...createState(true, true, error)
+          }));
+          if (options?.throws) throw error;
+        });
+      }
+      setState((prevState) => ({
+        ...prevState,
+        ...createState(true, true)
+      }));
+      return value;
+    },
+    [setState]
+  );
+  return [state, withState, setState];
+}
+export {
+  PendingStateContext,
+  PendingStateProvider,
+  usePendingState
+};

package/index.ts

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

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@t8/react-pending",
+  "version": "0.1.0",
+  "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",
+    "prepublishOnly": "npm run build",
+    "preversion": "npx npm-run-all shape build",
+    "shape": "npx codeshape"
+  },
+  "author": "axtk",
+  "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/t8dev/react-pending.git"
+  },
+  "keywords": [
+    "async actions",
+    "pending state",
+    "react"
+  ],
+  "peerDependencies": {
+    "@t8/react-store": "^1.0.0",
+    "react": ">=16.8"
+  },
+  "devDependencies": {
+    "@types/react": "^19.1.10"
+  }
+}

package/src/PendingState.ts

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

package/src/PendingStateContext.ts

@@ -0,0 +1,7 @@
+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>>(),
+);

package/src/PendingStateProvider.tsx

@@ -0,0 +1,43 @@
+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;
+};
+
+export const PendingStateProvider = ({
+    value,
+    children,
+}: PendingStateProviderProps) => {
+    let defaultValueRef = useRef<Map<string, Store<PendingState>> | null>(null);
+
+    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 (defaultValueRef.current === null)
+            defaultValueRef.current = new Map<string, Store<PendingState>>();
+
+        return defaultValueRef.current;
+    }, [value]);
+
+    return (
+        <PendingStateContext.Provider value={resolvedValue}>
+            {children}
+        </PendingStateContext.Provider>
+    );
+};

package/src/usePendingState.ts

@@ -0,0 +1,129 @@
+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,
+): PendingState {
+    return {
+        initialized,
+        complete,
+        error,
+        time: Date.now(),
+    };
+}
+
+export type WithStateOptions = {
+    silent?: boolean;
+    throws?: boolean;
+    delay?: number;
+};
+
+/**
+ * Returns an array containing `[state, withState, setState]`:
+ * - `state` reflects the state of a value passed to `withState()`;
+ * - `withState(value, [options])` enables the tracking of the state
+ * of `value`; setting the options to `{silent: true}` prevents
+ * `withState()` from updating the state while `value` is pending
+ * (e.g. for background or optimistic updates);
+ * - `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,
+): [PendingState, <T>(value: T) => T, SetStoreState<PendingState>] {
+    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;
+
+        if (typeof store === 'string') {
+            let storeItem = storeMap.get(store);
+
+            if (!storeItem) {
+                storeItem = new Store(createState());
+                storeMap.set(store, storeItem);
+
+                if (!storeItemInited) setStoreItemInited(true);
+            }
+
+            return storeItem;
+        }
+
+        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 => ({
+                ...prevState,
+                ...createState(true, true),
+            }));
+
+            return value;
+        },
+        [setState],
+    );
+
+    return [state, withState, setState];
+}

package/tsconfig.json

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