# useActorMethod

`useActorMethod` is a unified hook for calling canister methods that automatically handles both query and mutation methods based on the Candid interface. It is the bound version of `useReactorMethod` and is generated per-canister using `createActorHooks`.

## Features

- **Automatic Detection**: Determines query vs mutation based on Candid annotations (`query`, `composite_query`).
- **Unified Interface**: Same hook structure regardless of method type.
- **TypeScript Support**: Full type safety for arguments and return types.
- **Cache Invalidation**: Built-in support for invalidating queries after successful mutations.

## Import

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

const { useActorMethod } = createActorHooks(backend)
```

## Usage

### Query Method (Auto-fetches)

For query methods, the hook behaves like `useActorQuery` and fetches data on mount.

```tsx
function Balance({ owner }: { owner: string }) {
  const { data, isLoading, error } = useActorMethod({
    functionName: "icrc1_balance_of",
    args: [{ owner }],
  })

  if (isLoading) return <div>Loading...</div>
  return <div>Balance: {data?.toString()}</div>
}
```

### Mutation Method (Manual Call)

For update methods, the hook behaves like `useActorMutation`. Data is only fetched when you call the `call` function.

```tsx
function Transfer() {
  const { call, isPending, data } = useActorMethod({
    functionName: "transfer",
    invalidateQueries: [["icrc1_balance_of"]], // Optional: invalidate queries after success
  })

  const handleTransfer = async () => {
    await call([{ to: "recipient", amount: 100n }])
    alert("Transfer successful!")
  }

  return (
    <button onClick={handleTransfer} disabled={isPending}>
      {isPending ? "Transferring..." : "Transfer"}
    </button>
  )
}
```

## Options

`UseActorMethodParameters` extends react-query's `QueryObserverOptions`, giving you access to all standard react-query options plus our custom actor options.

### Custom Options

| Option              | Type                   | Description                                             |
| :------------------ | :--------------------- | :------------------------------------------------------ |
| `functionName`      | `M`                    | **Required**. The method name to call on the canister.  |
| `args`              | `ReactorArgs<A, M, T>` | Arguments to pass to the method.                        |
| `callConfig`        | `CallConfig`           | Agent call configuration (e.g., `effectiveCanisterId`). |
| `queryKey`          | `QueryKey`             | Custom query key for queries.                           |
| `onSuccess`         | `(data) => void`       | Callback when the method call succeeds.                 |
| `onError`           | `(error) => void`      | Callback when the method call fails.                    |
| `invalidateQueries` | `QueryKey[]`           | For mutations: keys to invalidate after success.        |

### Inherited from React Query

All react-query options are available:

| Option                 | Type                 | Default     | Description                                              |
| :--------------------- | :------------------- | :---------- | :------------------------------------------------------- |
| `enabled`              | `boolean`            | `true`      | For queries: whether to auto-fetch.                      |
| `staleTime`            | `number`             | `0`         | How long data stays fresh (ms).                          |
| `gcTime`               | `number`             | `300000`    | Time before unused data is garbage collected (ms).       |
| `refetchInterval`      | `number \| false`    | `false`     | Polling interval in ms.                                  |
| `refetchOnWindowFocus` | `boolean`            | `true`      | Refetch when window regains focus.                       |
| `refetchOnMount`       | `boolean`            | `true`      | Refetch when component mounts.                           |
| `refetchOnReconnect`   | `boolean`            | `true`      | Refetch when network reconnects.                         |
| `retry`                | `number \| boolean`  | `3`         | Number of retry attempts.                                |
| `retryDelay`           | `number \| function` | exponential | Delay between retries.                                   |
| `networkMode`          | `string`             | `"online"`  | Network mode (`"online"`, `"always"`, `"offlineFirst"`). |
| `placeholderData`      | `TData \| function`  | -           | Placeholder data while loading.                          |

## Return Value

| Property         | Type                                                      | Description                                                                                                                                |
| :--------------- | :-------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------- |
| `data`           | `ReactorQueryData<ReactorReturnOk<A, M, T>> \| undefined` | The returned data. A method's `undefined` result is `null`, as in `useActorQuery`, so `undefined` only means no call has settled yet.      |
| `call`           | `(args?) => Promise<data>`                                | Function to trigger the method call manually.                                                                                              |
| `isLoading`      | `boolean`                                                 | Whether the method is currently executing (alias for `isPending`).                                                                         |
| `isPending`      | `boolean`                                                 | Whether the method is currently executing.                                                                                                 |
| `isError`        | `boolean`                                                 | Whether the last call resulted in an error.                                                                                                |
| `isSuccess`      | `boolean`                                                 | Whether the method has completed successfully.                                                                                             |
| `error`          | `ReactorReturnErr<A, M, T> \| null`                       | The error object if one occurred.                                                                                                          |
| `isQuery`        | `boolean`                                                 | `true` if it's a query method, `false` otherwise.                                                                                          |
| `functionType`   | `FunctionType`                                            | `"query"` or `"update"`. Candid `composite_query` methods report `"query"`.                                                                |
| `reset`          | `() => void`                                              | Resets the state. For a query, `data` goes back to `initialData` if one was given and is cleared otherwise, and an enabled hook refetches. |
| `refetch`        | `() => Promise`                                           | For queries: manually refetches the data.                                                                                                  |
| `queryResult`    | `UseQueryResult`                                          | The raw result if it's a query.                                                                                                            |
| `mutationResult` | `UseMutationResult`                                       | The raw result if it's a mutation.                                                                                                         |

## See Also

- [useReactorMethod](https://ic-reactor.b3pay.net/v3/reference/reactorhooks/usereactormethod) — Raw version
- [useActorQuery](https://ic-reactor.b3pay.net/v3/reference/createactorhooks/useactorquery)
- [useActorMutation](https://ic-reactor.b3pay.net/v3/reference/createactorhooks/useactormutation)