@tuwaio/pulsar-react 0.4.9 → 0.6.0

package/README.md

@@ -1,156 +1,63 @@
-# Pulsar React
+# @tuwaio/pulsar-react
 
 [![NPM Version](https://img.shields.io/npm/v/@tuwaio/pulsar-react.svg)](https://www.npmjs.com/package/@tuwaio/pulsar-react)
-[![License](https://img.shields.io/npm/l/@tuwaio/pulsar-react.svg)](./LICENSE)
-[![Build Status](https://img.shields.io/github/actions/workflow/status/TuwaIO/pulsar-core/release.yml?branch=main)](https://github.com/TuwaIO/pulsar-core/actions)
+[![License](https://img.shields.io/npm/l/@tuwaio/pulsar-react.svg)](https://github.com/TuwaIO/pulsar-core/blob/main/packages/pulsar-react/LICENSE)
 
-Layer 4 (L4) of the TUWA Ecosystem. Global React context bindings, hooks, and transaction pool initializers for orchestrating framework-agnostic Pulsar stores.
+`@tuwaio/pulsar-react` is the React Layer 4 (L4) package of **Pulsar**, the transaction tracking project of TUWA Stage 2 ("State & Connection", next to Satellite Connect). Built on **`react`** only, it ships one hook, `useInitializeTransactionsPool`, that restarts the trackers of pending transactions when your app mounts. It has no UI components and no dependency on the other Pulsar packages: to read the store in components, use `createBoundedUseStore` from [`@tuwaio/pulsar-core`](https://pulsar.docs.tuwa.io/packages/pulsar-core).
 
 ---
 
-## 🏛️ What is `@tuwaio/pulsar-react`?
+## 🏛️ Core Capabilities
 
-This package serves as the integration layer between the framework-agnostic `@tuwaio/pulsar-core` headless state machine and React. It provides global bindings, hooks, and transaction pool initializers to orchestrate Pulsar stores within the React component lifecycle.
-
-Its primary role is to execute `useInitializeTransactionsPool` to resume pending transaction tracking automatically across client-side refreshes.
+- **Resume after reload:** `useInitializeTransactionsPool` calls the store's `initializeTransactionsPool` in an effect, on the client and after the store has restored its pool from `localStorage`, so transactions that were pending before a reload are tracked again.
+- **Runs once:** the effect depends only on `initializeTransactionsPool`, and the latest `onError` is read without re-running it, so an inline `onError` does not start new trackers on every render.
+- **Errors:** a rejected initialization goes to `onError`, or to `console.error` by default; nothing is reported after unmount.
 
 ---
 
 ## 💾 Installation
 
-To use this package, you need the complete Pulsar stack, including `@wagmi/core` for EVM interactions.
-
 ```bash
-# Using pnpm (recommended), but you can use npm, yarn or bun as well
 pnpm add @tuwaio/pulsar-react react
 ```
 
----
-
-## 🚀 Getting Started
-
-The recommended way to integrate Pulsar with React is to create a vanilla store instance, create a bounded hook for it, and then use `useInitializeTransactionsPool` in your main layout component.
-
-Here is a complete step-by-step example:
-
-### Step 1: Create the Pulsar Store and Hook
-
-First, create your vanilla Pulsar store and a reusable, bounded hook to access it. This pattern is recommended by Zustand for type safety and ease of use.
-
-```ts
-// src/hooks/txTrackingHooks.ts
-import { createBoundedUseStore, createPulsarStore, Transaction } from '@tuwaio/pulsar-core';
-import { pulsarEvmAdapter } from '@tuwaio/pulsar-evm';
-
-import { appChains, config } from '@/configs/wagmiConfig';
-
-const storageName = 'transactions-tracking-storage';
-
-export enum TxType {
-  example = 'example',
-}
-
-type ExampleTx = Transaction & {
-  type: TxType.example;
-  payload: {
-    value: number;
-  };
-};
-
-export type TransactionUnion = ExampleTx;
-
-export const usePulsarStore = createBoundedUseStore(
-  createPulsarStore<TransactionUnion>({
-    name: storageName,
-    adapter: pulsarEvmAdapter(config, appChains),
-    beforeTxProcess: async () => {
-      // Optional global preflight. Throw here to block before wallet interaction.
-      await assertUserCanSubmitTransactions();
-    },
-  }),
-);
-```
+> [!IMPORTANT]
+> `react` (>=19.2.3) is a peer dependency and must be installed alongside `@tuwaio/pulsar-react`. The hook is used with a store from [`@tuwaio/pulsar-core`](https://pulsar.docs.tuwa.io/packages/pulsar-core).
 
-The preflight and metadata validation lives in `@tuwaio/pulsar-core`, not in React. Before wallet interaction or persistence, Pulsar validates that each `title` string is 100 characters or less, each `description` string is 300 characters or less, and the serialized `payload` is 10KB or less. Invalid pending transactions restored by `useInitializeTransactionsPool` are removed from persisted storage during initialization.
+---
 
-### Step 2: Initialize the Store in Your App
+## 🚀 Usage
 
-Create a small, client-side component that uses the `useInitializeTransactionsPool` hook. This component's job is to re-activate trackers for pending transactions when the app loads.
+Render the initializer once, in a component that stays mounted, such as your root providers:
 
 ```tsx
-// src/components/PulsarInitializer.tsx
 'use client';
 
+import { createPulsarStore, type Transaction, type TxAdapter } from '@tuwaio/pulsar-core';
 import { useInitializeTransactionsPool } from '@tuwaio/pulsar-react';
-import { usePulsarStore } from '../hooks/txTrackingHooks';
-
-export const PulsarInitializer = () => {
-  // Get the initialization function from the store via our custom hook
-  const initializeTransactionsPool = usePulsarStore((state) => state.initializeTransactionsPool);
 
-  // Pass the function to the hook from this package
-  useInitializeTransactionsPool({ initializeTransactionsPool });
-
-  return null; // This component renders nothing to the DOM
-};
-```
+declare const adapter: TxAdapter<Transaction>; // pulsarEvmAdapter(...) or pulsarSolanaAdapter(...)
 
-### Step 3: Add the Initializer to Your Root Layout
+export const pulsarStore = createPulsarStore<Transaction>({ name: 'pulsar-transactions', adapter });
 
-Finally, place the `PulsarInitializer` component at a high level in your application tree (e.g., in your root layout or providers component) so it runs on every page load.
+export function PulsarInitializer() {
+  useInitializeTransactionsPool({
+    initializeTransactionsPool: pulsarStore.getState().initializeTransactionsPool,
+    onError: (error) => console.warn('Could not resume transaction tracking:', error),
+  });
 
-```tsx
-// src/app/layout.tsx (Next.js example)
-import { WagmiProvider } from 'wagmi';
-import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
-import { wagmiConfig } from '../configs/wagmi';
-import { PulsarInitializer } from '../components/PulsarInitializer';
-
-const queryClient = new QueryClient();
-
-export default function RootLayout({ children }) {
-  return (
-    <html lang="en">
-      <body>
-        <WagmiProvider config={wagmiConfig}>
-          <QueryClientProvider client={queryClient}>
-            <PulsarInitializer />
-            {children}
-          </QueryClientProvider>
-        </WagmiProvider>
-      </body>
-    </html>
-  );
+  return null;
 }
 ```
 
-With this setup, your application is now fully configured to track transactions and resume tracking across page reloads.
+Every call of `initializeTransactionsPool` starts new trackers, so do not render the initializer more than once. In development, React Strict Mode runs effects twice. The complete setup is on the **[Getting Started](https://pulsar.docs.tuwa.io/gettingStarted)** page.
 
 ---
 
-## 📖 API Reference
-
-### `useInitializeTransactionsPool(params)`
-
-This is the primary hook exported by this package. Its sole purpose is to re-initialize the transaction store on component mount.
-
-#### **Parameters**
-
-The hook accepts a single object with the following properties:
-
-- `initializeTransactionsPool: () => Promise<void>`: **(Required)** The initialization function obtained from your Pulsar store.
-- `onError?: (error: Error) => void`: **(Optional)** A callback function to handle any errors that occur during initialization. If not provided, errors will be logged to the console.
-
----
-
-## 🤝 Contributing & Support
-
-Contributions are welcome! Please read our main **[Contribution Guidelines](https://github.com/TuwaIO/workflows/blob/main/CONTRIBUTING.md)**.
-
-If you find this library useful, please consider supporting its development. Every contribution helps!
+## 📚 API Reference
 
-[**➡️ View Support Options**](https://github.com/TuwaIO/workflows/blob/main/Donation.md)
+Every export, with signatures and types generated from the source, is documented at **[pulsar.docs.tuwa.io/packages/pulsar-react](https://pulsar.docs.tuwa.io/packages/pulsar-react)**.
 
 ## 📄 License
 
-This project is licensed under the **Apache-2.0 License** - see the [LICENSE](./LICENSE) file for details.
+Licensed under the **Apache-2.0 License**. See the [LICENSE](https://github.com/TuwaIO/pulsar-core/blob/main/packages/pulsar-react/LICENSE) file for details.

package/dist/index.d.mts

@@ -1,45 +1,51 @@
 /**
- * @file React hook for bootstrapping the Pulsar transaction lifecycle on app start.
- * It rehydrates pending transaction trackers and can optionally perform an initial
- * remote history fetch right after tracker initialization.
+ * @file React hook that restarts the trackers of pending Pulsar transactions when the app mounts.
  */
 /**
- * Configuration for {@link useInitializeTransactionsPool}.
+ * The parameters of {@link useInitializeTransactionsPool}.
  */
 type UseInitializeTransactionsPoolParams = {
     /**
-     * Re-initializes background trackers for all pending transactions stored in the Pulsar store.
+     * The store's `initializeTransactionsPool` action (`createPulsarStore` from `@tuwaio/pulsar-core`). Pass a stable
+     * reference: the hook runs it again whenever it changes.
      */
     initializeTransactionsPool: () => Promise<void>;
     /**
-     * Optional error handler called when initialization or the optional initial fetch fails.
+     * Called when `initializeTransactionsPool` rejects. The latest function is used, so an inline callback does not run
+     * the initialization again.
      *
-     * @defaultValue `console.error`
+     * @defaultValue Logs the error with `console.error`.
+     * @param error - The rejection reason of `initializeTransactionsPool`.
      */
     onError?: (error: Error) => void;
 };
 /**
- * Re-initializes pending transaction trackers when the component mounts.
+ * Calls `initializeTransactionsPool` in an effect after the component mounts, so the trackers of transactions that
+ * were pending before a page reload start again. It runs on the client only, after the store has restored its state
+ * from `localStorage`.
  *
- * Use this hook once in your application's root layout or top-level provider.
- * It restores tracker activity after reloads and can optionally fetch the initial
- * remote transaction history right after restoration.
+ * Use it once, in a component that stays mounted (a root layout or provider): every run starts new trackers. The
+ * effect runs again only when `initializeTransactionsPool` changes. In development, React Strict Mode runs effects
+ * twice, so pending transactions get two trackers there.
  *
- * @param params Hook configuration.
- * @param params.initializeTransactionsPool Function that restores trackers for pending transactions.
- * @param params.onError Optional custom error handler.
+ * @param params - The hook parameters.
+ * @param params.initializeTransactionsPool - The store's `initializeTransactionsPool` action.
+ * @param params.onError - Called when the initialization rejects; defaults to `console.error`. Not called after
+ * unmount.
  *
  * @example
  * ```tsx
  * import { useInitializeTransactionsPool } from '@tuwaio/pulsar-react';
  *
- * function AppLayout() {
+ * import { pulsarStore } from './pulsarStore';
+ *
+ * export function PulsarInitializer() {
  *   useInitializeTransactionsPool({
- *     initializeTransactionsPool: store.getState().initializeTransactionsPool,
+ *     initializeTransactionsPool: pulsarStore.getState().initializeTransactionsPool,
  *     onError: (error) => console.warn('Failed to restore transactions:', error),
  *   });
  *
- *   return <div>...</div>;
+ *   return null;
  * }
  * ```
  */

package/dist/index.d.ts

@@ -1,45 +1,51 @@
 /**
- * @file React hook for bootstrapping the Pulsar transaction lifecycle on app start.
- * It rehydrates pending transaction trackers and can optionally perform an initial
- * remote history fetch right after tracker initialization.
+ * @file React hook that restarts the trackers of pending Pulsar transactions when the app mounts.
  */
 /**
- * Configuration for {@link useInitializeTransactionsPool}.
+ * The parameters of {@link useInitializeTransactionsPool}.
  */
 type UseInitializeTransactionsPoolParams = {
     /**
-     * Re-initializes background trackers for all pending transactions stored in the Pulsar store.
+     * The store's `initializeTransactionsPool` action (`createPulsarStore` from `@tuwaio/pulsar-core`). Pass a stable
+     * reference: the hook runs it again whenever it changes.
      */
     initializeTransactionsPool: () => Promise<void>;
     /**
-     * Optional error handler called when initialization or the optional initial fetch fails.
+     * Called when `initializeTransactionsPool` rejects. The latest function is used, so an inline callback does not run
+     * the initialization again.
      *
-     * @defaultValue `console.error`
+     * @defaultValue Logs the error with `console.error`.
+     * @param error - The rejection reason of `initializeTransactionsPool`.
      */
     onError?: (error: Error) => void;
 };
 /**
- * Re-initializes pending transaction trackers when the component mounts.
+ * Calls `initializeTransactionsPool` in an effect after the component mounts, so the trackers of transactions that
+ * were pending before a page reload start again. It runs on the client only, after the store has restored its state
+ * from `localStorage`.
  *
- * Use this hook once in your application's root layout or top-level provider.
- * It restores tracker activity after reloads and can optionally fetch the initial
- * remote transaction history right after restoration.
+ * Use it once, in a component that stays mounted (a root layout or provider): every run starts new trackers. The
+ * effect runs again only when `initializeTransactionsPool` changes. In development, React Strict Mode runs effects
+ * twice, so pending transactions get two trackers there.
  *
- * @param params Hook configuration.
- * @param params.initializeTransactionsPool Function that restores trackers for pending transactions.
- * @param params.onError Optional custom error handler.
+ * @param params - The hook parameters.
+ * @param params.initializeTransactionsPool - The store's `initializeTransactionsPool` action.
+ * @param params.onError - Called when the initialization rejects; defaults to `console.error`. Not called after
+ * unmount.
  *
  * @example
  * ```tsx
  * import { useInitializeTransactionsPool } from '@tuwaio/pulsar-react';
  *
- * function AppLayout() {
+ * import { pulsarStore } from './pulsarStore';
+ *
+ * export function PulsarInitializer() {
  *   useInitializeTransactionsPool({
- *     initializeTransactionsPool: store.getState().initializeTransactionsPool,
+ *     initializeTransactionsPool: pulsarStore.getState().initializeTransactionsPool,
  *     onError: (error) => console.warn('Failed to restore transactions:', error),
  *   });
  *
- *   return <div>...</div>;
+ *   return null;
  * }
  * ```
  */

package/dist/index.js

@@ -1 +1 @@
-'use strict';var react=require('react');var c=({initializeTransactionsPool:r,onError:o})=>{react.useEffect(()=>{let i=true;return (async()=>{try{if(await r(),!i)return}catch(a){(o??(t=>{console.error("[Pulsar] Failed to initialize transactions pool:",t);}))(a);}})(),()=>{i=false;}},[r,o]);};exports.useInitializeTransactionsPool=c;
+'use strict';var react=require('react');var c=({initializeTransactionsPool:a,onError:i})=>{let t=react.useEffectEvent(r=>{(i??(o=>{console.error("[Pulsar] Failed to initialize transactions pool:",o);}))(r);});react.useEffect(()=>{let r=true;return (async()=>{try{await a();}catch(o){if(!r)return;t(o);}})(),()=>{r=false;}},[a]);};exports.useInitializeTransactionsPool=c;

package/dist/index.mjs

@@ -1 +1 @@
-import {useEffect}from'react';var c=({initializeTransactionsPool:r,onError:o})=>{useEffect(()=>{let i=true;return (async()=>{try{if(await r(),!i)return}catch(a){(o??(t=>{console.error("[Pulsar] Failed to initialize transactions pool:",t);}))(a);}})(),()=>{i=false;}},[r,o]);};export{c as useInitializeTransactionsPool};
+import {useEffectEvent,useEffect}from'react';var c=({initializeTransactionsPool:a,onError:i})=>{let t=useEffectEvent(r=>{(i??(o=>{console.error("[Pulsar] Failed to initialize transactions pool:",o);}))(r);});useEffect(()=>{let r=true;return (async()=>{try{await a();}catch(o){if(!r)return;t(o);}})(),()=>{r=false;}},[a]);};export{c as useInitializeTransactionsPool};

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@tuwaio/pulsar-react",
-  "version": "0.4.9",
+  "version": "0.6.0",
   "private": false,
   "author": "Oleksandr Tkach",
   "license": "Apache-2.0",
-  "description": "Layer 4 (L4) of the TUWA Ecosystem. Global React context bindings, hooks, and transaction pool initializers for orchestrating framework-agnostic Pulsar stores.",
+  "description": "L4 React package of Pulsar (TUWA): useInitializeTransactionsPool hook that resumes tracking of pending transactions after a page reload.",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
   "types": "./dist/index.d.ts",
@@ -16,12 +16,13 @@
     "socket.json"
   ],
   "keywords": [
+    "tuwa",
+    "pulsar",
+    "transaction-tracking",
+    "web3",
     "react",
     "hooks",
-    "web3",
-    "transaction",
-    "tracking",
-    "pulsar"
+    "typescript"
   ],
   "repository": {
     "type": "git",
@@ -42,13 +43,14 @@
     "react": ">=19.2.3"
   },
   "devDependencies": {
-    "@types/react": "^19.2.18",
-    "react": "^19.2.8",
+    "@types/react": "^19.3.0",
+    "react": "^19.3.0",
     "tsup": "^8.5.1",
-    "typescript": "^6.0.3"
+    "typescript": "6.0.3"
   },
   "scripts": {
     "start": "tsup src/index.ts --watch",
-    "build": "tsup"
+    "build": "tsup",
+    "test": "vitest run"
   }
 }