@t8/react-pending 1.0.25 → 1.0.27

package/README.md

@@ -83,7 +83,7 @@ Omit the custom string key parameter of `usePendingState()` to scope the pending
 + let [state, withState] = usePendingState(); // local
 ```
 
-## Silent tracking of background and optimistic updates
+## Silent tracking of background actions and optimistic updates
 
 ```diff
 - withState(fetchItems())
@@ -96,7 +96,7 @@ Omit the custom string key parameter of `usePendingState()` to scope the pending
 
 ```diff
 - withState(fetchItems())
-+ withState(fetchItems(), { delay: 500 })
++ withState(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.
@@ -121,7 +121,7 @@ Omit the custom string key parameter of `usePendingState()` to scope the pending
 + </PendingStateProvider>
 ```
 
-🔹 `<PendingStateProvider>` creates an isolated instance of initial shared action state. Prime use cases: tests, SSR. It isn't required with client-side rendering, but it can be used to separate action states of larger self-contained portions of a web app.
+🔹 `<PendingStateProvider>` creates an isolated instance of initial shared action state. Prime use cases are SSR and tests. It isn't required with client-side rendering, but it can be used to separate action states of larger self-contained portions of a web app.
 
 ## Providing custom initial pending&nbsp;state
 

package/dist/index.d.ts

@@ -1,4 +1,58 @@
-export * from "./src/PendingState.ts";
-export * from "./src/PendingStateContext.ts";
-export * from "./src/PendingStateProvider.tsx";
-export * from "./src/usePendingState.ts";
+import type { SetStoreState, Store } from "@t8/react-store";
+import type { ReactNode } from "react";
+
+export type PendingState = {
+  initialized?: boolean | undefined;
+  complete?: boolean | undefined;
+  time?: number | undefined;
+  error?: unknown;
+};
+export declare const PendingStateContext: import("react").Context<Map<string, Store<PendingState>>>;
+export type PendingStateProviderProps = {
+  value?: Record<string, PendingState> | Map<string, Store<PendingState>> | null | undefined;
+  children?: ReactNode;
+};
+export declare const PendingStateProvider: ({ value, children, }: PendingStateProviderProps) => import("react/jsx-runtime").JSX.Element;
+export type WithStateOptions = {
+  /**
+   * 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.
+   */
+  silent?: boolean;
+  /**
+   * Delays switching the action state's `complete` property to `false`
+   * in the pending state by the given number of milliseconds.
+   *
+   * Use case: to avoid flashing a process indicator if the action is
+   * likely to complete by the end of a short delay.
+   */
+  delay?: number;
+  /**
+   * Allows the async action to reject explicitly, along with exposing
+   * the action state's `error` property that goes by default.
+   */
+  throws?: boolean;
+};
+/**
+ * Returns an instance of pending state and the functions to update it.
+ *
+ * @param store - A unique store key or a store. Providing a store
+ * 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 pending state;
+ * - `withState(action, options?)` reads and tracks the pending state
+ * of `action`;
+ * - `setState(update)` can update the pending state value directly.
+ */
+export declare function usePendingState(store?: string | Store<PendingState> | null): [
+  PendingState,
+  <T>(value: T) => T,
+  SetStoreState<PendingState>
+];
+
+export {};

package/package.json

@@ -1,20 +1,17 @@
 {
   "name": "@t8/react-pending",
-  "version": "1.0.25",
+  "version": "1.0.27",
   "description": "Concise async action state tracking for React apps",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "type": "module",
   "scripts": {
-    "build": "npx npm-run-all clean compile types",
     "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",
-    "prepublishOnly": "npm run build",
-    "preversion": "npx npm-run-all shape build test",
-    "shape": "npx codeshape --typecheck",
-    "test": "npx playwright test --project=chromium",
-    "types": "tsc -p tsconfig.build.json"
+    "preversion": "npx npm-run-all clean shape compile test",
+    "shape": "npx codeshape --typecheck --emit-types",
+    "test": "npx playwright test --project=chromium"
   },
   "author": "axtk",
   "license": "MIT",
@@ -34,13 +31,12 @@
   "devDependencies": {
     "@playwright/test": "^1.56.0",
     "@t8/serve": "^0.1.36",
-    "@types/node": "^24.10.1",
+    "@types/node": "^24.10.2",
     "@types/react": "^19.2.7",
-    "@types/react-dom": "^19.1.9",
-    "react-dom": "^19.2.1",
-    "typescript": "^5.9.3"
+    "@types/react-dom": "^19.2.3",
+    "react-dom": "^19.2.1"
   },
   "dependencies": {
-    "@t8/react-store": "^1.2.3"
+    "@t8/react-store": "^1.2.4"
   }
 }

package/src/usePendingState.ts

@@ -17,26 +17,43 @@ function createState(
 }
 
 export type WithStateOptions = {
+  /**
+   * 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.
+   */
   silent?: boolean;
-  throws?: boolean;
+  /**
+   * Delays switching the action state's `complete` property to `false`
+   * in the pending state by the given number of milliseconds.
+   *
+   * Use case: to avoid flashing a process indicator if the action is
+   * likely to complete by the end of a short delay.
+   */
   delay?: number;
+  /**
+   * Allows the async action to reject explicitly, along with exposing
+   * the action state's `error` property that goes by default.
+   */
+  throws?: boolean;
 };
 
 /**
- * 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.
+ * Returns an instance of pending state and the functions to update it.
+ *
+ * @param store - A unique store key or a store. Providing a store
+ * 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 pending state;
+ * - `withState(action, options?)` reads and tracks the pending state
+ * of `action`;
+ * - `setState(update)` can update the pending state value directly.
  */
 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);

package/dist/src/PendingState.d.ts

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

package/dist/src/PendingStateContext.d.ts

@@ -1,3 +0,0 @@
-import type { Store } from "@t8/react-store";
-import type { PendingState } from "./PendingState.ts";
-export declare const PendingStateContext: import("react").Context<Map<string, Store<PendingState>>>;

package/dist/src/PendingStateProvider.d.ts

@@ -1,8 +0,0 @@
-import { Store } from "@t8/react-store";
-import { type ReactNode } from "react";
-import type { PendingState } from "./PendingState.ts";
-export type PendingStateProviderProps = {
-    value?: Record<string, PendingState> | Map<string, Store<PendingState>> | null | undefined;
-    children?: ReactNode;
-};
-export declare const PendingStateProvider: ({ value, children, }: PendingStateProviderProps) => import("react/jsx-runtime").JSX.Element;

package/dist/src/usePendingState.d.ts

@@ -1,23 +0,0 @@
-import { type SetStoreState, Store } from "@t8/react-store";
-import type { PendingState } from "./PendingState.ts";
-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 declare 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>];

package/tsconfig.build.json

@@ -1,4 +0,0 @@
-{
-  "extends": "./tsconfig.json",
-  "include": ["./index.ts", "./src"]
-}