@ic-reactor/react 3.12.5 → 4.0.0-beta.1

package/src/hooks/useActorMethod.ts

@@ -1,507 +0,0 @@
-import { useCallback, useEffect, useMemo, useRef } from "react"
-import {
-  useQuery,
-  useMutation,
-  type UseQueryResult,
-  type UseMutationResult,
-  type QueryKey,
-  type QueryObserverOptions,
-} from "@tanstack/react-query"
-import {
-  Reactor,
-  BaseActor,
-  FunctionName,
-  TransformKey,
-  ReactorArgs,
-  ReactorReturnOk,
-  ReactorQueryData,
-  ReactorReturnErr,
-  FunctionType,
-} from "@ic-reactor/core"
-import { CallConfig } from "@icp-sdk/core/agent"
-import { normalizeQueryData } from "../utils.js"
-
-/**
- * Configuration for useActorMethod hook.
- * Extends react-query's QueryObserverOptions with custom reactor params.
- *
- * This is a unified hook that handles both query and mutation methods.
- * Query-specific options (like refetchInterval) only apply to query methods.
- * Mutation-specific options (like invalidateQueries) only apply to mutation methods.
- */
-export interface UseActorMethodParameters<
-  Service = BaseActor,
-  Method extends FunctionName<Service> = FunctionName<Service>,
-  Transform extends TransformKey = "candid",
-> extends Omit<
-  QueryObserverOptions<
-    ReactorQueryData<ReactorReturnOk<Service, Method, Transform>>,
-    ReactorReturnErr<Service, Method, Transform>,
-    ReactorQueryData<ReactorReturnOk<Service, Method, Transform>>,
-    ReactorQueryData<ReactorReturnOk<Service, Method, Transform>>,
-    QueryKey
-  >,
-  "queryKey" | "queryFn"
-> {
-  /** The reactor instance to use for method calls */
-  reactor: Reactor<Service, Transform>
-
-  /** The method name to call on the canister */
-  functionName: Method
-
-  /** Arguments to pass to the method (optional for parameterless methods) */
-  args?: ReactorArgs<Service, Method, Transform>
-
-  /** Agent call configuration (effectiveCanisterId, etc.) */
-  callConfig?: CallConfig
-
-  /** Custom query key (auto-generated if not provided) */
-  queryKey?: QueryKey
-
-  /**
-   * Callback when the method call succeeds.
-   * Works for both query and mutation methods.
-   *
-   * A method's `undefined` result arrives as `null`, as in `useActorQuery`,
-   * for query and update methods alike.
-   */
-  onSuccess?: (
-    data: ReactorQueryData<ReactorReturnOk<Service, Method, Transform>>
-  ) => void
-
-  /**
-   * Callback when the method call fails.
-   * Works for both query and mutation methods.
-   */
-  onError?: (error: ReactorReturnErr<Service, Method, Transform>) => void
-
-  /**
-   * Query keys to invalidate after a successful mutation.
-   * Only applies to mutation methods (updates).
-   */
-  invalidateQueries?: QueryKey[]
-}
-
-/**
- * Configuration type for bound useActorMethod hook (reactor omitted).
- * For use with createActorHooks.
- */
-export type UseActorMethodConfig<
-  Service = BaseActor,
-  Method extends FunctionName<Service> = FunctionName<Service>,
-  Transform extends TransformKey = "candid",
-> = Omit<UseActorMethodParameters<Service, Method, Transform>, "reactor">
-
-/**
- * Result type for useActorMethod hook.
- * Provides a unified interface for both query and mutation methods.
- */
-export interface UseActorMethodResult<
-  Service = BaseActor,
-  Method extends FunctionName<Service> = FunctionName<Service>,
-  Transform extends TransformKey = "candid",
-> {
-  /**
-   * The returned data from the method call. A method's `undefined` result is
-   * `null` here, as in `useActorQuery`, so `undefined` only means no call has
-   * settled yet.
-   */
-  data:
-    ReactorQueryData<ReactorReturnOk<Service, Method, Transform>> | undefined
-
-  /** Whether the method is currently executing */
-  isLoading: boolean
-
-  /** Alias for isLoading - whether a mutation is pending */
-  isPending: boolean
-
-  /** Whether there was an error */
-  isError: boolean
-
-  /** Whether the method has successfully completed at least once */
-  isSuccess: boolean
-
-  /** The error if one occurred */
-  error: ReactorReturnErr<Service, Method, Transform> | null
-
-  /** Whether this is a query method (true) or mutation method (false) */
-  isQuery: boolean
-
-  /** The function type (query, update, composite_query) */
-  functionType: FunctionType
-
-  /**
-   * Call the method with optional arguments.
-   * For queries: triggers a refetch
-   * For mutations: executes the mutation with the provided args
-   */
-  call: (
-    args?: ReactorArgs<Service, Method, Transform>
-  ) => Promise<
-    ReactorQueryData<ReactorReturnOk<Service, Method, Transform>> | undefined
-  >
-
-  /**
-   * Reset the state (data and error).
-   * For queries: resets this hook's own cache entry to its initial state, so
-   * `data` goes back to `initialData` when one was given and is cleared
-   * otherwise. An enabled hook then refetches. Other args of the same method
-   * are left alone.
-   * For mutations: resets the mutation state
-   */
-  reset: () => void
-
-  /**
-   * For queries only: Refetch the query
-   */
-  refetch: () => Promise<
-    ReactorQueryData<ReactorReturnOk<Service, Method, Transform>> | undefined
-  >
-
-  // Expose underlying results for advanced use cases
-  /** The raw query result (only available for query methods) */
-  queryResult?: UseQueryResult<
-    ReactorQueryData<ReactorReturnOk<Service, Method, Transform>>,
-    ReactorReturnErr<Service, Method, Transform>
-  >
-
-  /** The raw mutation result (only available for mutation methods) */
-  mutationResult?: UseMutationResult<
-    ReactorQueryData<ReactorReturnOk<Service, Method, Transform>>,
-    ReactorReturnErr<Service, Method, Transform>,
-    ReactorArgs<Service, Method, Transform>
-  >
-}
-
-/**
- * A unified hook for calling canister methods that automatically handles
- * both query and mutation methods based on the Candid interface.
- */
-export function useActorMethod<
-  Service = BaseActor,
-  Method extends FunctionName<Service> = FunctionName<Service>,
-  Transform extends TransformKey = "candid",
->({
-  reactor,
-  functionName,
-  args,
-  callConfig,
-  queryKey: customQueryKey,
-  enabled = true,
-  onSuccess,
-  onError,
-  invalidateQueries,
-  ...queryOptions
-}: UseActorMethodParameters<Service, Method, Transform>): UseActorMethodResult<
-  Service,
-  Method,
-  Transform
-> {
-  type TData = ReactorReturnOk<Service, Method, Transform>
-  type TQueryData = ReactorQueryData<TData>
-
-  // Determine if this is a query method by checking the IDL
-  const isQuery = useMemo(() => {
-    if (!reactor) throw new Error("Reactor instance is required")
-    return reactor.isQueryMethod(functionName)
-  }, [reactor, functionName])
-
-  const functionType: FunctionType = isQuery ? "query" : "update"
-
-  // Latest callbacks, read at dispatch time: this keeps a rerendered closure
-  // from being ignored, and keeps callback identity out of the effect deps.
-  const onSuccessRef = useRef(onSuccess)
-  const onErrorRef = useRef(onError)
-  onSuccessRef.current = onSuccess
-  onErrorRef.current = onError
-
-  // Build the key for a given set of call arguments.
-  //
-  // A custom `queryKey` is appended to the canister/function prefix rather than
-  // replacing it, matching `useActorQuery`. Used verbatim it would carry no
-  // canister id, so the entry would be invisible to the canister-scoped
-  // invalidation `ClientManager.updateAgent` runs on identity change and would
-  // keep serving the previous principal's data after sign-in or sign-out.
-  const buildQueryKey = useCallback(
-    (keyArgs: ReactorArgs<Service, Method, Transform> | undefined): QueryKey =>
-      reactor.generateQueryKey(
-        { functionName, args: keyArgs, queryKey: customQueryKey },
-        callConfig
-      ),
-    // `canisterId` is mutable reactor state that `setCanisterId` can change,
-    // while `reactor` itself stays the same object — so it has to be a
-    // dependency in its own right or the key stays pinned to the old canister.
-    [
-      reactor,
-      reactor.canisterId?.toString(),
-      functionName,
-      callConfig,
-      customQueryKey,
-    ]
-  )
-
-  const queryKey = useMemo(() => buildQueryKey(args), [buildQueryKey, args])
-
-  // ============================================================================
-  // Query Implementation
-  // ============================================================================
-
-  const queryResult = useQuery<
-    TQueryData,
-    ReactorReturnErr<Service, Method, Transform>
-  >(
-    {
-      queryKey,
-      // Callbacks deliberately do NOT live here: a queryFn runs once per fetch
-      // attempt, so `onError` fired on every retry (four times with the default
-      // QueryClient) and `onSuccess` never fired when data came from the cache
-      // or a deduped sibling. They are dispatched from the settled observer
-      // result below instead.
-      //
-      // TanStack Query fails a query whose queryFn resolves `undefined`, with
-      // "data is undefined", and a successful call can resolve it. A
-      // DisplayReactor decodes an `opt` None to `undefined`, and a `()` query
-      // returns nothing. Every other query path normalizes the value to `null`.
-      queryFn: async () =>
-        normalizeQueryData<TData>(
-          (await reactor.callMethod({
-            functionName,
-            args,
-            callConfig,
-          })) as TData
-        ),
-      enabled: isQuery && enabled,
-      ...queryOptions,
-    },
-    reactor.queryClient
-  )
-
-  // Dispatch the query callbacks from the settled observer result, once per
-  // distinct outcome. TanStack v5 removed `onSuccess`/`onError` from useQuery
-  // for exactly this reason, so the settle timestamps are what identify a new
-  // result: they also advance for a cache hit on a fresh mount, which is the
-  // case that previously never notified at all.
-  const notifiedSuccessAt = useRef<number | undefined>(undefined)
-  const notifiedErrorAt = useRef<number | undefined>(undefined)
-
-  const { status, data, error, dataUpdatedAt, errorUpdatedAt } = queryResult
-
-  useEffect(() => {
-    if (!isQuery) return
-    if (status === "success" && dataUpdatedAt !== notifiedSuccessAt.current) {
-      notifiedSuccessAt.current = dataUpdatedAt
-      onSuccessRef.current?.(data)
-    }
-  }, [isQuery, status, data, dataUpdatedAt])
-
-  useEffect(() => {
-    if (!isQuery) return
-    if (status === "error" && errorUpdatedAt !== notifiedErrorAt.current) {
-      notifiedErrorAt.current = errorUpdatedAt
-      onErrorRef.current?.(
-        error as ReactorReturnErr<Service, Method, Transform>
-      )
-    }
-  }, [isQuery, status, error, errorUpdatedAt])
-
-  // ============================================================================
-  // Mutation Implementation
-  // ============================================================================
-
-  const mutationResult = useMutation<
-    TQueryData,
-    ReactorReturnErr<Service, Method, Transform>,
-    ReactorArgs<Service, Method, Transform>
-  >(
-    {
-      mutationKey: queryKey,
-      // Normalized like the query branch, so `data`, `call()` and `onSuccess`
-      // mean the same thing for both kinds of method. The hook cannot type the
-      // two branches apart: a Candid service type does not say which methods
-      // are queries.
-      mutationFn: async (mutationArgs) =>
-        normalizeQueryData<TData>(
-          (await reactor.callMethod({
-            functionName,
-            args: mutationArgs ?? args,
-            callConfig,
-          })) as TData
-        ),
-      onSuccess: (data) => {
-        onSuccessRef.current?.(data)
-        // Invalidate specified queries after successful mutation
-        if (invalidateQueries && invalidateQueries.length > 0) {
-          invalidateQueries.forEach((key) => {
-            void reactor.queryClient.invalidateQueries({ queryKey: key })
-          })
-        }
-      },
-      onError: (error) => {
-        onErrorRef.current?.(error)
-      },
-    },
-    reactor.queryClient
-  )
-
-  // ============================================================================
-  // Unified Call Function
-  // ============================================================================
-
-  const call = useCallback(
-    async (
-      callArgs?: ReactorArgs<Service, Method, Transform>
-    ): Promise<TQueryData | undefined> => {
-      if (isQuery) {
-        // For queries, refetch with new args if provided
-        if (callArgs !== undefined) {
-          // Key on the args actually being called. Reusing the hook's
-          // mount-time key would store this result under the previous args'
-          // entry — poisoning it for every other reader — and let fetchQuery
-          // dedupe onto an in-flight request for the old args, returning that
-          // response as though it answered this one.
-          try {
-            const result = await reactor.queryClient.fetchQuery<TQueryData>({
-              queryKey: buildQueryKey(callArgs),
-              // Normalize for the same reason as the observer's queryFn.
-              queryFn: async () =>
-                normalizeQueryData<TData>(
-                  (await reactor.callMethod({
-                    functionName,
-                    args: callArgs,
-                    callConfig,
-                  })) as TData
-                ),
-              staleTime: 0,
-            })
-            // Dispatched here rather than by the observer effect: this result
-            // lands under the called args' key, which the mounted observer (bound
-            // to the hook's own args) does not watch. That separation is also why
-            // this can no longer double-fire the way it did when both wrote to
-            // the same key.
-            onSuccessRef.current?.(result)
-            return result
-          } catch (error) {
-            onErrorRef.current?.(
-              error as ReactorReturnErr<Service, Method, Transform>
-            )
-            return undefined
-          }
-        }
-        // Otherwise just refetch
-        const { data } = await queryResult.refetch()
-        return data
-      } else {
-        // For mutations, execute with provided args
-        return mutationResult
-          .mutateAsync(callArgs as ReactorArgs<Service, Method, Transform>)
-          .catch(() => undefined)
-      }
-    },
-    [
-      isQuery,
-      reactor,
-      functionName,
-      callConfig,
-      buildQueryKey,
-      queryResult,
-      mutationResult,
-    ]
-  )
-
-  // ============================================================================
-  // Reset Function
-  // ============================================================================
-
-  const reset = useCallback(() => {
-    if (isQuery) {
-      // Reset, not remove. `removeQueries` drops the entry without notifying
-      // its observers, so this hook kept rendering the old data while bound to
-      // a query that was no longer in the cache. No later invalidation reached
-      // it, including the one an identity switch runs. `resetQueries` notifies
-      // the observer and refetches the entry when the hook is enabled. It is
-      // `exact` because only this hook's entry should reset. A prefix match on
-      // a no-args key would also reset every args variant other hooks render.
-      void reactor.queryClient.resetQueries({ queryKey, exact: true })
-    } else {
-      mutationResult.reset()
-    }
-  }, [isQuery, reactor, queryKey, mutationResult])
-
-  // ============================================================================
-  // Refetch Function
-  // ============================================================================
-
-  const refetch = useCallback(async () => {
-    if (isQuery) {
-      const result = await queryResult.refetch()
-      return result.data
-    }
-    return undefined
-  }, [isQuery, queryResult])
-
-  // ============================================================================
-  // Return Unified Result
-  // ============================================================================
-
-  if (isQuery) {
-    return {
-      data: queryResult.data,
-      isLoading: queryResult.isLoading,
-      isPending: queryResult.isLoading,
-      isError: queryResult.isError,
-      isSuccess: queryResult.isSuccess,
-      error: queryResult.error,
-      isQuery: true,
-      functionType,
-      call,
-      reset,
-      refetch,
-      queryResult,
-    } as UseActorMethodResult<Service, Method, Transform>
-  } else {
-    return {
-      data: mutationResult.data,
-      isLoading: mutationResult.isPending,
-      isPending: mutationResult.isPending,
-      isError: mutationResult.isError,
-      isSuccess: mutationResult.isSuccess,
-      error: mutationResult.error,
-      isQuery: false,
-      functionType,
-      call,
-      reset,
-      refetch,
-      mutationResult,
-    } as UseActorMethodResult<Service, Method, Transform>
-  }
-}
-
-/**
- * Creates a bound useMethod hook for a specific reactor instance.
- *
- * @example
- * ```tsx
- * const { useMethod } = createActorMethodHooks(reactor)
- * ```
- */
-export function createActorMethodHooks<
-  Service = BaseActor,
-  Transform extends TransformKey = "candid",
->(reactor: Reactor<Service, Transform>) {
-  return {
-    /**
-     * Hook for calling methods on the bound reactor.
-     */
-    useMethod: <Method extends FunctionName<Service>>(
-      config: Omit<
-        UseActorMethodParameters<Service, Method, Transform>,
-        "reactor"
-      >
-    ) =>
-      useActorMethod({ ...config, reactor } as UseActorMethodParameters<
-        Service,
-        Method,
-        Transform
-      >),
-  }
-}

package/src/hooks/useActorMutation.ts

@@ -1,205 +0,0 @@
-import { useCallback } from "react"
-import {
-  useMutation,
-  UseMutationOptions,
-  UseMutationResult,
-  QueryKey,
-} from "@tanstack/react-query"
-import {
-  Reactor,
-  ReactorArgs,
-  ReactorReturnOk,
-  FunctionName,
-  TransformKey,
-  ReactorReturnErr,
-  isCanisterError,
-  CanisterError,
-  ErrResult,
-  ActorMethodReturnType,
-  TransformReturnRegistry,
-} from "@ic-reactor/core"
-import { CallConfig } from "@icp-sdk/core/agent"
-
-export interface UseActorMutationParameters<
-  Service,
-  Method extends FunctionName<Service>,
-  Transform extends TransformKey = "candid",
-  TOnMutateResult = unknown,
-> extends Omit<
-  UseMutationOptions<
-    ReactorReturnOk<Service, Method, Transform>,
-    ReactorReturnErr<Service, Method, Transform>,
-    ReactorArgs<Service, Method, Transform>,
-    TOnMutateResult
-  >,
-  "mutationFn"
-> {
-  reactor: Reactor<Service, Transform>
-  functionName: Method
-  callConfig?: CallConfig
-  /**
-   * Queries to invalidate upon successful mutation.
-   *
-   * `undefined` entries are skipped, so the common
-   * `[maybeQuery?.getQueryKey()]` idiom is safe when the optional query object
-   * is absent.
-   */
-  invalidateQueries?: (QueryKey | undefined)[]
-  /**
-   * Callback for canister-level business logic errors.
-   * Called when the canister returns a Result { Err: E } variant.
-   * Separate from `onError`, which fires for all errors including network failures.
-   */
-  onCanisterError?: (
-    error: CanisterError<
-      TransformReturnRegistry<
-        ErrResult<ActorMethodReturnType<Service[Method]>>,
-        Service
-      >[Transform]
-    >,
-    variables: ReactorArgs<Service, Method, Transform>
-  ) => void
-}
-
-export type UseActorMutationConfig<
-  Service,
-  Method extends FunctionName<Service>,
-  Transform extends TransformKey = "candid",
-  TOnMutateResult = unknown,
-> = Omit<
-  UseActorMutationParameters<Service, Method, Transform, TOnMutateResult>,
-  "reactor"
->
-
-export type UseActorMutationResult<
-  Service,
-  Method extends FunctionName<Service>,
-  Transform extends TransformKey = "candid",
-  TOnMutateResult = unknown,
-> = UseMutationResult<
-  ReactorReturnOk<Service, Method, Transform>,
-  ReactorReturnErr<Service, Method, Transform>,
-  ReactorArgs<Service, Method, Transform>,
-  TOnMutateResult
->
-
-/**
- * Hook for executing mutation calls on a canister.
- * Use this for component-level mutation flows.
- * For non-React usage, prefer `createMutation(...).execute(args)`.
- *
- * @example
- * const { mutate, isPending } = useActorMutation({
- *   reactor,
- *   functionName: "transfer",
- *   onSuccess: () => console.log("Success!"),
- *   onCanisterError: (err) => console.error("Canister Err:", err.code),
- * })
- *
- * @example
- * const transferMutation = createMutation(reactor, {
- *   functionName: "transfer",
- *   onCanisterError: (err) => console.error(err.code),
- * })
- *
- * // Non-React execution path
- * await transferMutation.execute([{ to: "aaaaa-aa", amount: "100" }])
- */
-export const useActorMutation = <
-  Service,
-  Method extends FunctionName<Service>,
-  Transform extends TransformKey = "candid",
-  TOnMutateResult = unknown,
->({
-  reactor,
-  functionName,
-  invalidateQueries,
-  onSuccess,
-  onError,
-  onCanisterError,
-  callConfig,
-  ...options
-}: UseActorMutationParameters<
-  Service,
-  Method,
-  Transform,
-  TOnMutateResult
->): UseActorMutationResult<Service, Method, Transform, TOnMutateResult> => {
-  const mutationFn = useCallback(
-    async (args: ReactorArgs<Service, Method, Transform>) =>
-      reactor.callMethod({ functionName, callConfig, args }),
-    [reactor, functionName, callConfig]
-  )
-
-  const handleSuccess = useCallback(
-    async (
-      ...params: Parameters<
-        NonNullable<
-          UseMutationOptions<
-            ReactorReturnOk<Service, Method, Transform>,
-            ReactorReturnErr<Service, Method, Transform>,
-            ReactorArgs<Service, Method, Transform>,
-            TOnMutateResult
-          >["onSuccess"]
-        >
-      >
-    ) => {
-      if (invalidateQueries) {
-        // Skip undefined entries. React Query reads `{ queryKey: undefined }`
-        // as "match everything", so a single undefined — which the natural
-        // `invalidateQueries: [maybeQuery?.getQueryKey()]` idiom produces
-        // whenever the optional query object is absent — would invalidate every
-        // query in the client, including an app's unrelated non-canister ones.
-        // `createMutation.invalidateAll` already filters the same way.
-        await Promise.all(
-          invalidateQueries
-            .filter((queryKey) => queryKey !== undefined)
-            .map((queryKey) =>
-              reactor.queryClient.invalidateQueries({ queryKey })
-            )
-        )
-      }
-      await onSuccess?.(...params)
-    },
-    [reactor, invalidateQueries, onSuccess]
-  )
-
-  const handleError = useCallback(
-    async (
-      error: ReactorReturnErr<Service, Method, Transform>,
-      variables: ReactorArgs<Service, Method, Transform>,
-      context: unknown,
-      mutation: unknown
-    ) => {
-      if (isCanisterError(error)) {
-        onCanisterError?.(error as any, variables)
-      }
-      // Awaited like `onSuccess` above. TanStack Query waits for the promise
-      // `onError` returns before it runs `onSettled` and settles the mutation,
-      // and it can only wait for a promise this wrapper passes back.
-      await onError?.(error, variables, context as any, mutation as any)
-    },
-    [onCanisterError, onError]
-  )
-
-  // Not memoized. The deps could only ever list the values destructured above,
-  // never the `options` rest bucket, so everything passed straight through —
-  // `onMutate`, `onSettled`, `retry`, `meta`, `gcTime` — was frozen at the first
-  // render: `useMutation` calls `observer.setOptions` from an effect keyed on
-  // the options identity, so a later render's closures never reached it. A
-  // component passing only `onSettled` would report the recipient selected at
-  // mount rather than at submit.
-  //
-  // `createMutation`'s own hook builds its options inline for the same reason.
-  // A fresh object per render costs nothing here: `setOptions` diffs the values
-  // rather than the reference.
-  return useMutation(
-    {
-      ...options,
-      mutationFn,
-      onSuccess: handleSuccess,
-      onError: handleError,
-    },
-    reactor.queryClient
-  )
-}