# createActorHooks

`createActorHooks` is a factory function that creates a set of type-safe React hooks bound to a specific canister. It's the primary way to integrate IC Reactor with React.

## Import

```typescript
import { createActorHooks } from "@ic-reactor/react"
```

## Usage

### Basic Usage

```typescript
import { createActorHooks } from "@ic-reactor/react"
import { backend } from "./reactor"

const {
  useActorQuery,
  useActorSuspenseQuery,
  useActorInfiniteQuery,
  useActorSuspenseInfiniteQuery,
  useActorMutation,
  useActorMethod,
} = createActorHooks(backend)
```

**Tip:** It is recommended to rename the hooks to reflect the canister name, especially when working with multiple canisters:

```typescript
const { useActorQuery: useBackendQuery } = createActorHooks(backend)
```

### With Reactor Parameters

Using a `Reactor` instance is the only supported way to create actor hooks:

```typescript
import { Reactor, createActorHooks } from "@ic-reactor/react"
import { clientManager } from "./reactor"
import { idlFactory, type _SERVICE } from "../declarations/backend"

const backend = new Reactor<_SERVICE>({
  clientManager,
  idlFactory,
  name: "backend",
  canisterId: import.meta.env.VITE_BACKEND_CANISTER_ID,
})

const { useActorQuery, useActorMutation } = createActorHooks(backend)
```

### With DisplayReactor (Auto Transformations)

To enable automatic display transformations (BigInt → string, Principal → text, etc.), use `DisplayReactor`:

```typescript
import { DisplayReactor, createActorHooks } from "@ic-reactor/react"
import { clientManager } from "./reactor"
import { idlFactory, type _SERVICE } from "../declarations/backend"

const backend = new DisplayReactor<_SERVICE>({
  clientManager,
  idlFactory,
  name: "backend",
  canisterId: "...",
})

// Hooks will use display types (string instead of bigint, etc.)
const { useActorQuery, useActorMutation } = createActorHooks(backend)
```

## Parameters

```typescript
createActorHooks(reactor: Reactor<A, T>)
```

| Parameter | Type            | Description                                      |
| --------- | --------------- | ------------------------------------------------ |
| `reactor` | `Reactor<A, T>` | A pre-created Reactor or DisplayReactor instance |

## Return Value

`createActorHooks` returns an object containing:

| Property                                                                                        | Type | Description                          |
| ----------------------------------------------------------------------------------------------- | ---- | ------------------------------------ |
| [`useActorQuery`](https://ic-reactor.b3pay.net/v3/reference/createactorhooks/useactorquery)                                 | Hook | Query hook for fetching data         |
| [`useActorSuspenseQuery`](https://ic-reactor.b3pay.net/v3/reference/createactorhooks/useactorsuspensequery)                 | Hook | Suspense-enabled query hook          |
| [`useActorMutation`](https://ic-reactor.b3pay.net/v3/reference/createactorhooks/useactormutation)                           | Hook | Mutation hook for updates            |
| [`useActorMethod`](https://ic-reactor.b3pay.net/v3/reference/createactorhooks/useactormethod)                               | Hook | Unified hook for queries & updates   |
| [`useActorInfiniteQuery`](https://ic-reactor.b3pay.net/v3/reference/createactorhooks/useactorinfinitequery)                 | Hook | Infinite query hook for pagination   |
| [`useActorSuspenseInfiniteQuery`](https://ic-reactor.b3pay.net/v3/reference/createactorhooks/useactorsuspenseinfinitequery) | Hook | Suspense-enabled infinite query hook |

## Examples

### Complete Setup Example

```typescript
// src/reactor/index.ts
import { ClientManager, Reactor } from "@ic-reactor/react"
import { QueryClient } from "@tanstack/react-query"
import { idlFactory, type _SERVICE } from "../declarations/backend"

export const queryClient = new QueryClient()

export const clientManager = new ClientManager({
  queryClient,
})

export const backend = new Reactor<_SERVICE>({
  clientManager,
  idlFactory,
  canisterId: import.meta.env.VITE_BACKEND_CANISTER_ID,
  name: "backend",
})
```

```typescript
// src/reactor/hooks.ts
import {
  AuthenticationManager,
  createActorHooks,
  createAuthHooks,
} from "@ic-reactor/react"
import { backend, clientManager } from "./index"

// Create hooks for the backend canister
export const {
  useActorQuery,
  useActorMutation,
  useActorSuspenseQuery,
  useActorInfiniteQuery,
  useActorSuspenseInfiniteQuery,
  useActorMethod,
} = createActorHooks(backend)

// Create auth hooks
const authentication = new AuthenticationManager({ clientManager })

export const { useAuth, useUserPrincipal, useAgentState } =
  createAuthHooks(authentication)
```

### Multiple Canisters

```typescript
// src/reactor/hooks.ts
import { createActorHooks } from "@ic-reactor/react"
import { backend, ledger } from "./index"

// Backend canister hooks
export const backendHooks = createActorHooks(backend)

// Ledger canister hooks
export const ledgerHooks = createActorHooks(ledger)

// Export individual hooks for convenience
export const {
  useActorQuery: useBackendQuery,
  useActorMutation: useBackendMutation,
} = backendHooks

export const {
  useActorQuery: useLedgerQuery,
  useActorMutation: useLedgerMutation,
} = ledgerHooks
```

### Inline Definition

You can define everything in one place:

```typescript
// src/reactor/hooks.ts
import {
  AuthenticationManager,
  ClientManager,
  Reactor,
  createActorHooks,
  createAuthHooks,
} from "@ic-reactor/react"
import { QueryClient } from "@tanstack/react-query"
import { idlFactory, type _SERVICE } from "../declarations/backend"

const queryClient = new QueryClient()

const clientManager = new ClientManager({
  queryClient,
})

const backend = new Reactor<_SERVICE>({
  clientManager,
  idlFactory,
  name: "backend",
  canisterId: import.meta.env.VITE_BACKEND_CANISTER_ID,
})

const authentication = new AuthenticationManager({ clientManager })

// Returns hooks
export const { useActorQuery, useActorMutation } = createActorHooks(backend)

export const { useAuth, useUserPrincipal } = createAuthHooks(authentication)

// Export for use elsewhere
export { queryClient, clientManager, backend }
```

## Type Safety

`createActorHooks` preserves full type safety:

```typescript
import { createActorHooks } from "@ic-reactor/react"
import { backend } from "./reactor"

const { useActorQuery, useActorMutation } = createActorHooks(backend)

// TypeScript knows all available methods
const { data } = useActorQuery({
  functionName: "getUser", // ✅ Autocomplete shows valid methods
  args: ["user-123"], // ✅ Type-checked arguments
})

const { mutate } = useActorMutation({
  functionName: "createUser", // ✅ Autocomplete
})

mutate([{ name: "Alice", email: "alice@example.com" }]) // ✅ Type-safe args
```

## Type Exports

The package exports types for all hooks with two naming conventions:

### `UseActor*` Types (for bound hooks)

For hooks created by `createActorHooks` where the reactor is already bound:

```typescript
import type {
  UseActorQueryParameters,
  UseActorQueryResult,
  UseActorMutationParameters,
  UseActorMutationResult,
  UseActorSuspenseQueryParameters,
  UseActorSuspenseQueryResult,
  UseActorInfiniteQueryParameters,
  UseActorInfiniteQueryResult,
  UseActorSuspenseInfiniteQueryParameters,
  UseActorSuspenseInfiniteQueryResult,
} from "@ic-reactor/react"
```

### `UseReactor*` Types (for direct hooks)

For direct hook usage where you pass the reactor explicitly:

```typescript
import type {
  UseReactorQueryParameters,
  UseReactorQueryResult,
  UseReactorMutationParameters,
  UseReactorMutationResult,
  UseReactorMethodParameters,
  UseReactorMethodResult,
  // ... and more
} from "@ic-reactor/react"
```

**Note:** All parameter types extend react-query's base types (`QueryObserverOptions`,
  `UseMutationOptions`, `UseInfiniteQueryOptions`). This means you get access to
  all standard react-query options like `gcTime`, `retry`,
  `refetchOnWindowFocus`, `networkMode`, `placeholderData`, etc.

## See Also

- [useActorQuery](https://ic-reactor.b3pay.net/v3/reference/createactorhooks/useactorquery) — Query hook reference
- [useActorMutation](https://ic-reactor.b3pay.net/v3/reference/createactorhooks/useactormutation) — Mutation hook reference
- [useActorSuspenseQuery](https://ic-reactor.b3pay.net/v3/reference/createactorhooks/useactorsuspensequery) — Suspense query reference
- [useActorInfiniteQuery](https://ic-reactor.b3pay.net/v3/reference/createactorhooks/useactorinfinitequery) — Infinite query reference
- [createAuthHooks](https://ic-reactor.b3pay.net/v3/reference/createauthhooks/overview) — Auth hooks factory