@t8/react-pending 1.0.24 → 1.0.26

package/README.md

@@ -4,22 +4,36 @@
 
 [![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)
 
-Shared or local pending state tracking with a concise API without rewrites in the app's shared state or async actions' internals.
+**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.
 
+<!-- docsgen-show-start --
 ```diff
-+ let [state, withState] = usePendingState("fetch-items");
++ import { usePendingState } from "@t8/react-pending";
 
-- fetchItems().then(setItems);
-+ withState(fetchItems()).then(setItems);
+  export let ItemList = () => {
+    let [items, setItems] = useState([]);
++   let [state, withState] = usePendingState("fetch-items");
 
-+ if (!state.complete) return <p>Loading...</p>;
+    useEffect(() => {
+-     fetchItems().then(setItems);
++     withState(fetchItems()).then(setItems);
+    }, [fetchItems, withState]);
+
++   if (!state.complete) return <p>Loading...</p>;
++   if (state.error) return <p>An error occurred</p>;
+
+    return <ul>{items.map(/* ... */)}</ul>;
+  };
 ```
+-- docsgen-show-end -->
 
 Installation: `npm i @t8/react-pending`
 
 ## Shared pending state
 
-Objective: Track the pending state of the asynchronous action `fetchItems()` to tell the user whether the UI is busy or encountered an error (preferably without rewriting the action and the app's state management). In our setup, there are two components rendering their content with regard to the current state of `fetchItems()`.
+Objective: Track the pending state of the asynchronous action `fetchItems()` to tell the user whether the UI is busy handling the async action or encountered an error, without rewriting the action and the app's state management.
+
+In our setup, there are two components rendering their content with regard to the current state of `fetchItems()`, so the pending state is shared between these components:
 
 ```diff
 + import { usePendingState } from "@t8/react-pending";

package/dist/index.d.ts

@@ -1,4 +1,42 @@
-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 = {
+  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>
+];
+
+export {};

package/dist/index.js

@@ -9,6 +9,11 @@ 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/isPersistentStore.ts
+function isPersistentStore(x) {
+  return isStore(x) && "sync" in x;
+}
+
 // node_modules/@t8/store/src/Store.ts
 var Store = class {
   state;
@@ -38,12 +43,14 @@ var Store = class {
 // 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");
+  if (!isStore(store))
+    throw new Error("'store' is not an instance of Store");
   let [, setRevision] = useState(-1);
   let state = store.getState();
   let setState = useMemo(() => store.setState.bind(store), [store]);
   let initialStoreRevision = useRef(store.revision);
   useEffect(() => {
+    if (isPersistentStore(store)) store.syncOnce();
     if (!shouldUpdate) return;
     let unsubscribe = store.onUpdate((nextState, prevState) => {
       if (typeof shouldUpdate !== "function" || shouldUpdate(nextState, prevState))

package/package.json

@@ -1,47 +1,42 @@
-{
-  "name": "@t8/react-pending",
-  "version": "1.0.24",
-  "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 typecheck shape build test",
-    "shape": "npx codeshape",
-    "test": "npx playwright test --project=chromium",
-    "typecheck": "tsc --noEmit",
-    "types": "tsc -p tsconfig.build.json"
-  },
-  "author": "axtk",
-  "license": "MIT",
-  "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.56.0",
-    "@t8/serve": "^0.1.35",
-    "@types/node": "^24.5.2",
-    "@types/react": "^19.1.10",
-    "@types/react-dom": "^19.1.9",
-    "react-dom": "^19.1.1",
-    "typescript": "^5.9.3"
-  },
-  "dependencies": {
-    "@t8/react-store": "^1.0.35"
-  }
-}
+{
+  "name": "@t8/react-pending",
+  "version": "1.0.26",
+  "description": "Concise async action state tracking for React apps",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "type": "module",
+  "scripts": {
+    "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",
+    "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",
+  "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.56.0",
+    "@t8/serve": "^0.1.36",
+    "@types/node": "^24.10.2",
+    "@types/react": "^19.2.7",
+    "@types/react-dom": "^19.2.3",
+    "react-dom": "^19.2.1"
+  },
+  "dependencies": {
+    "@t8/react-store": "^1.2.4"
+  }
+}

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"]
-}