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

package/src/hooks/useActorMutation.ts

@@ -1,205 +0,0 @@
-import { useCallback } from "react"
-import {
-  useMutation,
-  UseMutationOptions,
-  UseMutationResult,
-} 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"
-import { invalidateTargets, useMountQueryClient } from "../utils.js"
-import type { InvalidationTarget } from "../types.js"
-
-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, awaited before
-   * `onSuccess` runs.
-   *
-   * Each entry is a query key, a query object or query factory, or a
-   * `{ functionName, args? }` method of `reactor`; see
-   * {@link InvalidationTarget}. `undefined` entries are skipped, so
-   * `[maybeQuery]` is safe when the optional query object is absent.
-   */
-  invalidateQueries?: InvalidationTarget<Service, Transform>[]
-  /**
-   * 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 } = useReactorMutation({
- *   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> => {
-  useMountQueryClient(reactor.queryClient)
-
-  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"]
-        >
-      >
-    ) => {
-      // Undefined entries are skipped: React Query reads
-      // `{ queryKey: undefined }` as "match everything", and the natural
-      // `[maybeQuery]` idiom produces one whenever the query is absent.
-      await invalidateTargets(reactor, invalidateQueries, callConfig)
-      await onSuccess?.(...params)
-    },
-    [reactor, invalidateQueries, onSuccess, callConfig]
-  )
-
-  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(
-    {
-      // Keyed like `createMutation`'s hook and `useActorMethod`'s mutations,
-      // so `useIsMutating({ mutationKey })`, `useMutationState` and defaults
-      // registered with `setMutationDefaults` can find this one too. An
-      // explicit `mutationKey` in the options still wins.
-      mutationKey: reactor.getQueryOptions({ functionName, callConfig })
-        .queryKey,
-      ...options,
-      mutationFn,
-      onSuccess: handleSuccess,
-      onError: handleError,
-    },
-    reactor.queryClient
-  )
-}

package/src/hooks/useActorQuery.ts

@@ -1,157 +0,0 @@
-import { useMemo } from "react"
-import {
-  QueryKey,
-  useQuery,
-  skipToken,
-  QueryObserverOptions,
-  UseQueryResult,
-  type SkipToken,
-} from "@tanstack/react-query"
-import {
-  FunctionName,
-  Reactor,
-  TransformKey,
-  ReactorArgs,
-  ReactorReturnOk,
-  ReactorQueryData,
-  ReactorReturnErr,
-} from "@ic-reactor/core"
-import { CallConfig } from "@icp-sdk/core/agent"
-import { retryOption, skippedQueryKey, useMountQueryClient } from "../utils.js"
-
-export interface UseActorQueryParameters<
-  Service,
-  Method extends FunctionName<Service>,
-  Transform extends TransformKey = "candid",
-  Selected = ReactorQueryData<ReactorReturnOk<Service, Method, Transform>>,
-> extends Omit<
-  QueryObserverOptions<
-    ReactorQueryData<ReactorReturnOk<Service, Method, Transform>>,
-    ReactorReturnErr<Service, Method, Transform>,
-    Selected,
-    ReactorQueryData<ReactorReturnOk<Service, Method, Transform>>,
-    QueryKey
-  >,
-  "queryKey" | "queryFn"
-> {
-  reactor: Reactor<Service, Transform>
-  functionName: Method
-  /**
-   * The method's arguments, or TanStack Query's `skipToken` while they are
-   * not known: the query then waits without fetching, in an entry of its own
-   * under its method's key, which no call's key shares, so it shows no data
-   * until the arguments arrive.
-   */
-  args?: ReactorArgs<Service, Method, Transform> | SkipToken
-  callConfig?: CallConfig
-  queryKey?: QueryKey
-}
-
-export type UseActorQueryConfig<
-  Service,
-  Method extends FunctionName<Service>,
-  Transform extends TransformKey = "candid",
-  Selected = ReactorQueryData<ReactorReturnOk<Service, Method, Transform>>,
-> = Omit<
-  UseActorQueryParameters<Service, Method, Transform, Selected>,
-  "reactor"
->
-
-export type UseActorQueryResult<
-  Service,
-  Method extends FunctionName<Service>,
-  Transform extends TransformKey = "candid",
-  Selected = ReactorQueryData<ReactorReturnOk<Service, Method, Transform>>,
-> = UseQueryResult<Selected, ReactorReturnErr<Service, Method, Transform>>
-
-/**
- * Hook for executing query calls on a canister.
- *
- * @example
- * const { data, isLoading } = useReactorQuery({
- *   reactor,
- *   functionName: "getUser",
- *   args: ["user-123"],
- * })
- *
- * // With select transformation
- * const { data } = useReactorQuery({
- *   reactor,
- *   functionName: "getUser",
- *   args: ["user-123"],
- *   select: (user) => user.name,
- * })
- *
- * // Wait for the args: no fetch until userId is known
- * const { data } = useReactorQuery({
- *   reactor,
- *   functionName: "getUser",
- *   args: userId ? [userId] : skipToken,
- * })
- */
-export const useActorQuery = <
-  Service,
-  Method extends FunctionName<Service>,
-  Transform extends TransformKey = "candid",
-  Selected = ReactorQueryData<ReactorReturnOk<Service, Method, Transform>>,
->({
-  reactor,
-  functionName,
-  args,
-  callConfig,
-  queryKey: defaultQueryKey,
-  ...options
-}: UseActorQueryParameters<
-  Service,
-  Method,
-  Transform,
-  Selected
->): UseActorQueryResult<Service, Method, Transform, Selected> => {
-  useMountQueryClient(reactor.queryClient)
-
-  // Memoize query options to prevent unnecessary re-computations
-  // For an update method, the options also carry its default `retry`; see
-  // `Reactor.getQueryRetry`.
-  const { queryKey, queryFn, retry } = useMemo(
-    () =>
-      args === skipToken
-        ? // Waiting for its args: an entry of its own under the method's key,
-          // with nothing to run until then; see skippedQueryKey.
-          {
-            queryKey: skippedQueryKey(
-              reactor.generateQueryKey({ functionName }, callConfig),
-              "query"
-            ),
-            // Kept as the unique symbol, which an object literal widens.
-            queryFn: skipToken as SkipToken,
-            retry: undefined,
-          }
-        : reactor.getQueryOptions<Method>({
-            callConfig,
-            functionName,
-            args,
-            queryKey: defaultQueryKey,
-          }),
-    // `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(),
-      callConfig,
-      functionName,
-      args,
-      defaultQueryKey,
-    ]
-  )
-
-  return useQuery(
-    {
-      queryFn,
-      ...options,
-      queryKey,
-      ...retryOption(options.retry, retry),
-    },
-    reactor.queryClient
-  )
-}

package/src/hooks/useActorSuspenseInfiniteQuery.ts

@@ -1,248 +0,0 @@
-import { useMemo, useCallback } from "react"
-import {
-  QueryKey,
-  useSuspenseInfiniteQuery,
-  UseSuspenseInfiniteQueryResult,
-  UseSuspenseInfiniteQueryOptions,
-  InfiniteData,
-} from "@tanstack/react-query"
-import {
-  FunctionName,
-  Reactor,
-  TransformKey,
-  ReactorArgs,
-  ReactorReturnOk,
-  ReactorQueryData,
-  ReactorReturnErr,
-} from "@ic-reactor/core"
-import { CallConfig } from "@icp-sdk/core/agent"
-import {
-  callConfigForKey,
-  mergeFactoryQueryKey,
-  mountWhileSuspended,
-  normalizeQueryData,
-  retryOption,
-  useMountQueryClient,
-} from "../utils.js"
-
-/**
- * Parameters for useActorSuspenseInfiniteQuery hook.
- * Extends react-query's UseSuspenseInfiniteQueryOptions with custom reactor params.
- */
-export interface UseActorSuspenseInfiniteQueryParameters<
-  Service,
-  Method extends FunctionName<Service>,
-  Transform extends TransformKey = "candid",
-  TPageParam = unknown,
-  Selected = InfiniteData<
-    ReactorQueryData<ReactorReturnOk<Service, Method, Transform>>,
-    TPageParam
-  >,
-> extends Omit<
-  UseSuspenseInfiniteQueryOptions<
-    ReactorQueryData<ReactorReturnOk<Service, Method, Transform>>,
-    ReactorReturnErr<Service, Method, Transform>,
-    Selected,
-    QueryKey,
-    TPageParam
-  >,
-  "queryKey" | "queryFn" | "getNextPageParam" | "initialPageParam"
-> {
-  /** The reactor instance to use for method calls */
-  reactor: Reactor<Service, Transform>
-  /** The method name to call on the canister */
-  functionName: Method
-  /** Function to get args from page parameter */
-  getArgs: (pageParam: TPageParam) => ReactorArgs<Service, Method, Transform>
-  /**
-   * Narrows what the cache key derives from the call arguments.
-   *
-   * By default the key is scoped by `getArgs(initialPageParam)`, so two
-   * infinite queries on the same method with different arguments stay in
-   * separate cache entries. Supply this when those args embed the cursor and
-   * only part of them identifies the query — return the stable, serializable
-   * portion (typically everything except the pagination field). It is required
-   * when `initialPageParam` changes between renders, as `Date.now()` does:
-   * without it every render keys a new query.
-   */
-  getKeyArgs?: (args: ReactorArgs<Service, Method, Transform>) => unknown
-  /** Agent call configuration (effectiveCanisterId, etc.) */
-  callConfig?: CallConfig
-  /** Custom query key (auto-generated if not provided) */
-  queryKey?: QueryKey
-  /** Initial page parameter */
-  initialPageParam: TPageParam
-  /** Function to determine next page parameter */
-  getNextPageParam: (
-    lastPage: ReactorQueryData<ReactorReturnOk<Service, Method, Transform>>,
-    allPages: ReactorQueryData<ReactorReturnOk<Service, Method, Transform>>[],
-    lastPageParam: TPageParam,
-    allPageParams: TPageParam[]
-  ) => TPageParam | undefined | null
-}
-
-export type UseActorSuspenseInfiniteQueryConfig<
-  Service,
-  Method extends FunctionName<Service>,
-  Transform extends TransformKey = "candid",
-  TPageParam = unknown,
-  Selected = InfiniteData<
-    ReactorQueryData<ReactorReturnOk<Service, Method, Transform>>,
-    TPageParam
-  >,
-> = Omit<
-  UseActorSuspenseInfiniteQueryParameters<
-    Service,
-    Method,
-    Transform,
-    TPageParam,
-    Selected
-  >,
-  "reactor"
->
-
-export type UseActorSuspenseInfiniteQueryResult<
-  Service,
-  Method extends FunctionName<Service>,
-  Transform extends TransformKey = "candid",
-  TPageParam = unknown,
-  Selected = InfiniteData<
-    ReactorQueryData<ReactorReturnOk<Service, Method, Transform>>,
-    TPageParam
-  >,
-> = UseSuspenseInfiniteQueryResult<
-  Selected,
-  ReactorReturnErr<Service, Method, Transform>
->
-
-/**
- * Hook for executing suspense-enabled infinite/paginated query calls on a canister.
- *
- * @example
- * const { data, fetchNextPage, hasNextPage } = useReactorSuspenseInfiniteQuery({
- *   reactor,
- *   functionName: "getItems",
- *   getArgs: (pageParam) => [{ offset: pageParam, limit: 10 }] as const,
- *   initialPageParam: 0,
- *   getNextPageParam: (lastPage) => lastPage.nextOffset,
- * })
- */
-export const useActorSuspenseInfiniteQuery = <
-  Service,
-  Method extends FunctionName<Service>,
-  Transform extends TransformKey = "candid",
-  TPageParam = unknown,
-  Selected = InfiniteData<
-    ReactorQueryData<ReactorReturnOk<Service, Method, Transform>>,
-    TPageParam
-  >,
->({
-  reactor,
-  functionName,
-  getArgs,
-  getKeyArgs,
-  callConfig,
-  queryKey,
-  ...options
-}: UseActorSuspenseInfiniteQueryParameters<
-  Service,
-  Method,
-  Transform,
-  TPageParam,
-  Selected
->): UseActorSuspenseInfiniteQueryResult<
-  Service,
-  Method,
-  Transform,
-  TPageParam,
-  Selected
-> => {
-  useMountQueryClient(reactor.queryClient)
-
-  // Always pass queryKey through generateQueryKey so it is merged with the
-  // reactor/function identity. Using the custom key verbatim would cause cache
-  // collisions if two different actors or methods share the same key string.
-  const baseQueryKey = useMemo(() => {
-    // Fold the call arguments into the key. They live in the `getArgs`
-    // closure rather than in the config, so without this two hooks on the
-    // same method with different arguments share one cache entry and serve
-    // each other's pages. `getKeyArgs` narrows them exactly as it does for the
-    // factories, which the bound hook's config type always accepted: it used
-    // to be ignored here, so the cursor stayed in the key, and an
-    // `initialPageParam` that changes every render (`Date.now()`) keyed a new
-    // query on every render — an endless loop of first-page fetches.
-    const initialArgs = getArgs(options.initialPageParam)
-    const keyArgs = getKeyArgs?.(initialArgs) ?? initialArgs
-
-    return reactor.generateQueryKey(
-      {
-        functionName,
-        queryKey: mergeFactoryQueryKey(queryKey, undefined, keyArgs),
-      },
-      callConfig
-    )
-  }, [
-    queryKey,
-    reactor,
-    // `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
-    // while the queryFn already calls the new one.
-    reactor.canisterId?.toString(),
-    functionName,
-    callConfig,
-    getArgs,
-    getKeyArgs,
-    options.initialPageParam,
-  ])
-
-  // Memoize queryFn to prevent recreation on every render
-  const queryFn = useCallback(
-    async ({
-      pageParam,
-      queryKey: fetchedKey,
-    }: {
-      pageParam: TPageParam
-      queryKey: QueryKey
-    }) => {
-      const args = getArgs(pageParam)
-      const result = await reactor.callMethod({
-        functionName,
-        args,
-        callConfig: callConfigForKey(fetchedKey, callConfig),
-      })
-      return normalizeQueryData<ReactorReturnOk<Service, Method, Transform>>(
-        result as ReactorReturnOk<Service, Method, Transform>
-      )
-    },
-    [reactor, functionName, getArgs, callConfig]
-  )
-
-  // The method's default `retry`: for an update method, only failures that
-  // prove the canister never ran the call; see `Reactor.getQueryRetry`.
-  const defaultRetry = useMemo(
-    () => reactor.getQueryRetry(functionName, baseQueryKey),
-    [reactor, functionName, baseQueryKey]
-  )
-
-  try {
-    return useSuspenseInfiniteQuery(
-      {
-        queryKey: baseQueryKey,
-        queryFn,
-        ...options,
-        ...retryOption(options.retry, defaultRetry),
-      } as any,
-      reactor.queryClient
-    ) as UseActorSuspenseInfiniteQueryResult<
-      Service,
-      Method,
-      Transform,
-      TPageParam,
-      Selected
-    >
-  } catch (thrown) {
-    mountWhileSuspended(reactor.queryClient, thrown)
-    throw thrown
-  }
-}