@ic-reactor/react 3.0.0-beta.1 → 3.0.0-beta.2

package/README.md

@@ -1,147 +1,317 @@
 # @ic-reactor/react
 
-**The Ultimate React Hooks for the Internet Computer.**  
-Connect your React application to the Internet Computer Blockchain in seconds. using the power of [TanStack Query](https://tanstack.com/query).
+<div align="center">
+  <strong>The Ultimate React Hooks for the Internet Computer.</strong>
+  <br><br>
+  
+  [![npm version](https://img.shields.io/npm/v/@ic-reactor/react.svg)](https://www.npmjs.com/package/@ic-reactor/react)
+  [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+  [![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)
+</div>
+
+---
+
+Connect your React application to the Internet Computer Blockchain with full [TanStack Query](https://tanstack.com/query) integration for caching, suspense, and infinite queries.
 
 ## Features
 
-- ⚛️ **React Query Integration**: Full power of TanStack Query (Caching, Refetching, Suspense).
-- 🔄 ** Type-Safe**: Full TypeScript support with automatic type inference from your Candid files.
-- 🔐 **Authentication**: Easy-to-use authentication hooks with Internet Identity and other providers.
-- 🚀 **Performance**: Efficient caching and state management tailored for IC.
+- ⚛️ **TanStack Query Integration** — Full power of React Query (caching, refetching, suspense, infinite queries)
+- � **End-to-End Type Safety** — Automatic type inference from your Candid files
+- � **Auto Transformations** — `DisplayReactor` converts BigInt to string, Principal to text, and more
+- 📦 **Result Unwrapping** — Automatic `Ok`/`Err` handling from Candid Result types
+- 🔐 **Authentication** — Easy-to-use hooks with Internet Identity integration
+- 🏗️ **Multi-Actor Support** — Manage multiple canisters with shared authentication
 
 ## Installation
 
 ```bash
-npm install @ic-reactor/react @ic-reactor/core @tanstack/react-query @icp-sdk/core @icp-sdk/auth
+# With npm
+npm install @ic-reactor/react @tanstack/react-query @icp-sdk/core
+
+# With pnpm
+pnpm add @ic-reactor/react @tanstack/react-query @icp-sdk/core
+
+# Optional: For Internet Identity authentication
+npm install @icp-sdk/auth
 ```
 
 ## Quick Start
 
-### 1. Initialize the Actor
-
-Create your actor hooks using `createActorHooks`. This is the "One Stop Shop" for interacting with your canister.
+### 1. Setup ClientManager and Reactor
 
 ```typescript
-// src/hooks/actor.ts
-import { createActorHooks } from "@ic-reactor/react"
-import { canisterId, idlFactory } from "../declarations/my_canister"
-
-export const { useActorQuery, useActorMutation, useAuth, reactor } =
-  createActorHooks({
-    canisterId,
-    idlFactory,
-  })
+// src/reactor.ts
+import { ClientManager, Reactor } from "@ic-reactor/react"
+import { QueryClient } from "@tanstack/react-query"
+import { idlFactory, type _SERVICE } from "./declarations/my_canister"
+
+// Create query client for caching
+export const queryClient = new QueryClient()
+
+// Create client manager (handles identity and agent)
+export const clientManager = new ClientManager({
+  queryClient,
+  withProcessEnv: true, // Reads DFX_NETWORK from environment
+})
+
+// Create reactor for your canister
+export const backend = new Reactor<_SERVICE>({
+  clientManager,
+  idlFactory,
+  canisterId: "rrkah-fqaaa-aaaaa-aaaaq-cai",
+})
 ```
 
-### 2. Authentication (Auto-Initializes Session)
+### 2. Create Hooks
 
-The `useAuth` hook automatically initializes the agent and restores any previous session on first use.
+```typescript
+// src/hooks.ts
+import { createActorHooks, createAuthHooks } from "@ic-reactor/react"
+import { backend, clientManager } from "./reactor"
+
+// Create actor hooks for queries and mutations
+export const { useActorQuery, useActorMutation, useActorSuspenseQuery } =
+  createActorHooks(backend)
+
+// Create auth hooks for login/logout
+export const { useAuth, useUserPrincipal } = createAuthHooks(clientManager)
+```
+
+### 3. Setup Provider (not required) and Use in Components
 
 ```tsx
 // src/App.tsx
-import { useAuth } from "./hooks/actor"
+import { QueryClientProvider } from "@tanstack/react-query"
+import { queryClient } from "./reactor"
+import { useAuth, useActorQuery, useActorMutation } from "./hooks"
 
 function App() {
-  // useAuth() auto-initializes - no separate setup needed!
-  const { isAuthenticated, login, logout } = useAuth()
-
   return (
-    <div>
-      {isAuthenticated ? (
-        <button onClick={logout}>Logout</button>
-      ) : (
-        <button onClick={login}>Login with II</button>
-      )}
-      <Dashboard />
-    </div>
+    <QueryClientProvider client={queryClient}>
+      <AuthButton />
+      <Greeting />
+    </QueryClientProvider>
   )
 }
-```
-
-### 3. Use in Components
 
-Now you can use your hooks directly in your components!
+function AuthButton() {
+  const { login, logout, isAuthenticated, principal } = useAuth()
 
-```tsx
-// src/Dashboard.tsx
-import { useActorQuery, useActorMutation } from "./hooks/actor"
+  return isAuthenticated ? (
+    <button onClick={() => logout()}>
+      Logout {principal?.toText().slice(0, 8)}...
+    </button>
+  ) : (
+    <button onClick={() => login()}>Login with Internet Identity</button>
+  )
+}
 
-function Dashboard() {
+function Greeting() {
   // Query: Fetch data (auto-cached!)
-  const { data: balance } = useActorQuery({
-    functionName: "icrc1_balance_of",
-    args: [{ owner: Principal.fromText("...") }],
+  const { data, isPending, error } = useActorQuery({
+    functionName: "greet",
+    args: ["World"],
   })
 
-  // Update: Execute state changes
-  const { mutate: transfer, isPending } = useActorMutation({
-    functionName: "icrc1_transfer",
-    onSuccess: () => {
-      console.log("Transfer successful!")
-    }
-  })
+  if (isPending) return <div>Loading...</div>
+  if (error) return <div>Error: {error.message}</div>
 
-  return (
-    <div>
-      <h1>Balance: {balance?.toString()}</h1>
-      <button onClick={() => transfer(...)} disabled={isPending}>
-        Transfer
-      </button>
-    </div>
-  )
+  return <h1>{data}</h1>
 }
 ```
 
-### Form Friendly (CandidAdapter)
+## Core Concepts
 
-If you want your hooks to automatically handle type transformations (e.g., converting `bigint` to `string` for simple form binding), set `autoCodecs: true`.
+### Reactor vs DisplayReactor
+
+| Feature       | `Reactor`        | `DisplayReactor`            |
+| ------------- | ---------------- | --------------------------- |
+| Types         | Raw Candid types | Display-friendly types      |
+| BigInt        | `bigint`         | `string`                    |
+| Principal     | `Principal`      | `string`                    |
+| Vec nat8      | `Uint8Array`     | <= 96 bytes: `string` (hex) |
+| Result        | Unwrapped        | Unwrapped                   |
+| Form-friendly | No               | Yes                         |
 
 ```typescript
-export const { useActorQuery } = createActorHooks({
-  canisterId,
+import { DisplayReactor } from "@ic-reactor/react"
+
+// DisplayReactor for form-friendly UI work
+const backend = new DisplayReactor<_SERVICE>({
+  clientManager,
   idlFactory,
-  autoCodecs: true, // Returns stringified values for bigint, principal, small blobs
+  canisterId: "rrkah-fqaaa-aaaaa-aaaaq-cai",
 })
+
+// Now hooks return strings instead of bigint/Principal
+const { data } = useActorQuery({
+  functionName: "icrc1_balance_of",
+  args: [{ owner: "aaaaa-aa", subaccount: [] }], // strings!
+})
+// data is "100000000" instead of 100000000n
 ```
 
-### Authentication
+## Hooks Reference
 
-The `createActorHooks` function returns authentication hooks directly.
+### Actor Hooks (from `createActorHooks`)
 
-```typescript
-import { useAuth } from "./hooks/actor"
+| Hook                            | Description                                    |
+| ------------------------------- | ---------------------------------------------- |
+| `useActorQuery`                 | Standard queries with loading states           |
+| `useActorSuspenseQuery`         | Suspense-enabled queries (data always defined) |
+| `useActorInfiniteQuery`         | Paginated/infinite scroll queries              |
+| `useActorSuspenseInfiniteQuery` | Suspense infinite queries                      |
+| `useActorMutation`              | State-changing operations                      |
 
-function LoginButton() {
-  const { login, logout, identity, isAuthenticated } = useAuth()
+### Auth Hooks (from `createAuthHooks`)
 
-  return (
-    <div>
-      {isAuthenticated ? (
-        <button onClick={logout}>Logout</button>
-      ) : (
-        <button onClick={login}>Login</button>
-      )}
-    </div>
-  )
+| Hook               | Description                         |
+| ------------------ | ----------------------------------- |
+| `useAuth`          | Login, logout, authentication state |
+| `useAgentState`    | Agent initialization state          |
+| `useUserPrincipal` | Current user's Principal            |
+
+## Query Examples
+
+### Standard Query
+
+```tsx
+const { data, isPending, error } = useActorQuery({
+  functionName: "get_user",
+  args: ["user-123"],
+  staleTime: 5 * 60 * 1000, // 5 minutes
+})
+```
+
+### Suspense Query
+
+```tsx
+// Parent must have <Suspense> boundary
+function UserProfile() {
+  // data is never undefined with suspense!
+  const { data } = useActorSuspenseQuery({
+    functionName: "get_user",
+    args: ["user-123"],
+  })
+
+  return <div>{data.name}</div>
 }
 ```
 
-### Dynamic Queries
+### Infinite Query
+
+```tsx
+const { data, fetchNextPage, hasNextPage } = useActorInfiniteQuery({
+  functionName: "get_posts",
+  initialPageParam: 0,
+  getNextPageParam: (lastPage, pages) => pages.length * 10,
+  args: (pageParam) => [{ offset: pageParam, limit: 10 }],
+})
+```
+
+## Mutation Examples
+
+### Basic Mutation
+
+```tsx
+const { mutate, isPending, error } = useActorMutation({
+  functionName: "update_profile",
+  onSuccess: (result) => {
+    console.log("Profile updated!", result)
+  },
+})
+
+// Call the mutation
+mutate([{ name: "Alice", bio: "Hello IC!" }])
+```
+
+## Query Factories
+
+Create reusable query configurations with factory functions:
+
+```typescript
+import {
+  createQuery,
+  createSuspenseQuery,
+  createMutation,
+} from "@ic-reactor/react"
+
+// Static query (no args at call time)
+export const tokenNameQuery = createSuspenseQuery(backend, {
+  functionName: "icrc1_name",
+})
+
+// In component:
+const { data } = tokenNameQuery.useSuspenseQuery()
+```
 
-Need to create queries on the fly? Use `createQuery`.
+### Factory with Dynamic Args
 
 ```typescript
-import { createQuery } from "@ic-reactor/react"
+import { createSuspenseQueryFactory } from "@ic-reactor/react"
 
-const balanceQuery = createQuery(reactor, {
+// Factory for balance queries
+export const getBalance = createSuspenseQueryFactory(backend, {
   functionName: "icrc1_balance_of",
-  select: (balance) => balance.toString() + " ICP",
+  select: (balance) => `${balance} tokens`,
 })
 
-const { data } = balanceQuery.useQuery()
+// In component - pass args at call time
+const { data } = getBalance.useSuspenseQuery({
+  args: [{ owner: userPrincipal, subaccount: [] }],
+})
+```
+
+## Advanced: Direct Reactor Usage
+
+Access reactor methods directly for manual cache management:
+
+```typescript
+// Fetch and cache
+await backend.fetchQuery({
+  functionName: "get_user",
+  args: ["user-123"],
+})
+
+// Get cached data (no fetch)
+const cached = backend.getQueryData({
+  functionName: "get_user",
+  args: ["user-123"],
+})
+
+// Invalidate cache to trigger refetch
+backend.invalidateQueries({
+  functionName: "get_user",
+})
+
+// Direct call without caching
+const result = await backend.callMethod({
+  functionName: "update_user",
+  args: [{ name: "Alice" }],
+})
+```
+
+## Re-exports
+
+`@ic-reactor/react` re-exports everything from `@ic-reactor/core`, so you typically only need one import:
+
+```typescript
+// Everything from one package
+import {
+  ClientManager,
+  Reactor,
+  DisplayReactor,
+  createActorHooks,
+  createAuthHooks,
+  createQuery,
+  CanisterError,
+} from "@ic-reactor/react"
 ```
 
+## Documentation
+
+For comprehensive guides and API reference, visit the [documentation site](https://b3pay.github.io/ic-reactor/v3).
+
 ## License
 
-MIT
+MIT © [Behrad Deylami](https://github.com/b3hr4d)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ic-reactor/react",
-  "version": "3.0.0-beta.1",
+  "version": "3.0.0-beta.2",
   "description": "IC Reactor React Library",
   "main": "dist/index.js",
   "module": "dist/index.js",