@ic-reactor/react 3.0.0-beta.8 → 3.0.0

package/src/hooks/useActorMutation.ts

@@ -0,0 +1,124 @@
+import { useMemo, useCallback } from "react"
+import {
+  useMutation,
+  UseMutationOptions,
+  UseMutationResult,
+  QueryKey,
+} from "@tanstack/react-query"
+import {
+  Reactor,
+  ReactorArgs,
+  ReactorReturnOk,
+  FunctionName,
+  TransformKey,
+  ReactorReturnErr,
+} from "@ic-reactor/core"
+import { CallConfig } from "@icp-sdk/core/agent"
+
+export interface UseActorMutationParameters<
+  A,
+  M extends FunctionName<A>,
+  T extends TransformKey = "candid",
+> extends Omit<
+  UseMutationOptions<
+    ReactorReturnOk<A, M, T>,
+    ReactorReturnErr<A, M, T>,
+    ReactorArgs<A, M, T>
+  >,
+  "mutationFn"
+> {
+  reactor: Reactor<A, T>
+  functionName: M
+  callConfig?: CallConfig
+  invalidateQueries?: QueryKey[]
+}
+
+export type UseActorMutationConfig<
+  A,
+  M extends FunctionName<A>,
+  T extends TransformKey = "candid",
+> = Omit<UseActorMutationParameters<A, M, T>, "reactor">
+
+export type UseActorMutationResult<
+  A,
+  M extends FunctionName<A>,
+  T extends TransformKey = "candid",
+> = UseMutationResult<
+  ReactorReturnOk<A, M, T>,
+  ReactorReturnErr<A, M, T>,
+  ReactorArgs<A, M, T>
+>
+
+/**
+ * Hook for executing mutation calls on a canister.
+ *
+ * @example
+ * const { mutate, isPending } = useActorMutation({
+ *   reactor,
+ *   functionName: "transfer",
+ *   onSuccess: () => console.log("Success!"),
+ * })
+ */
+export const useActorMutation = <
+  A,
+  M extends FunctionName<A>,
+  T extends TransformKey = "candid",
+>({
+  reactor,
+  functionName,
+  invalidateQueries,
+  onSuccess,
+  callConfig,
+  ...options
+}: UseActorMutationParameters<A, M, T>): UseActorMutationResult<A, M, T> => {
+  // Memoize mutationFn to avoid creating new function on every render
+  const mutationFn = useCallback(
+    async (args: ReactorArgs<A, M, T>) => {
+      return reactor.callMethod({
+        functionName,
+        callConfig,
+        args,
+      })
+    },
+    [reactor, functionName, callConfig]
+  )
+
+  // Memoize onSuccess handler
+  const handleSuccess = useCallback(
+    async (
+      ...params: Parameters<
+        NonNullable<
+          UseMutationOptions<
+            ReactorReturnOk<A, M, T>,
+            ReactorReturnErr<A, M, T>,
+            ReactorArgs<A, M, T>
+          >["onSuccess"]
+        >
+      >
+    ) => {
+      if (invalidateQueries) {
+        await Promise.all(
+          invalidateQueries.map((queryKey) =>
+            reactor.queryClient.invalidateQueries({ queryKey })
+          )
+        )
+      }
+      if (onSuccess) {
+        await onSuccess(...params)
+      }
+    },
+    [reactor, invalidateQueries, onSuccess]
+  )
+
+  // Memoize mutation options
+  const mutationOptions = useMemo(
+    () => ({
+      ...options,
+      mutationFn,
+      onSuccess: handleSuccess,
+    }),
+    [options, mutationFn, handleSuccess]
+  )
+
+  return useMutation(mutationOptions, reactor.queryClient)
+}

package/src/hooks/useActorQuery.test.tsx

@@ -0,0 +1,287 @@
+import { describe, it, expect, vi, beforeEach } from "vitest"
+import { renderHook, waitFor } from "@testing-library/react"
+import React from "react"
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query"
+import { useActorQuery } from "./useActorQuery"
+import { ActorMethod } from "@icp-sdk/core/agent"
+import { Reactor } from "@ic-reactor/core"
+
+// Define a test actor type
+type TestActor = {
+  greet: ActorMethod<[], string>
+  greetWithName: ActorMethod<[string], string>
+  getCount: ActorMethod<[], bigint>
+}
+
+// Mock Reactor
+const createMockReactor = (queryClient: QueryClient): Reactor<TestActor> =>
+  ({
+    queryClient,
+    getQueryOptions: vi.fn().mockImplementation(({ functionName, args }) => ({
+      queryKey: ["test-canister", functionName, ...(args || [])],
+      queryFn: vi.fn().mockImplementation(async () => {
+        if (functionName === "greet") return "Hello, World!"
+        if (functionName === "greetWithName")
+          return `Hello, ${args?.[0] || "Guest"}!`
+        if (functionName === "getCount") return BigInt(42)
+        return null
+      }),
+    })),
+  }) as unknown as Reactor<TestActor>
+
+describe("useActorQuery", () => {
+  let queryClient: QueryClient
+  let mockReactor: Reactor<TestActor>
+
+  beforeEach(() => {
+    queryClient = new QueryClient({
+      defaultOptions: {
+        queries: {
+          retry: false,
+        },
+      },
+    })
+    mockReactor = createMockReactor(queryClient)
+  })
+
+  const wrapper = ({ children }: { children: React.ReactNode }) => (
+    <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
+  )
+
+  describe("basic functionality", () => {
+    it("should fetch data without select", async () => {
+      const { result } = renderHook(
+        () =>
+          useActorQuery<TestActor, "greet">({
+            reactor: mockReactor,
+            functionName: "greet",
+          }),
+        { wrapper }
+      )
+
+      await waitFor(() => {
+        expect(result.current.isSuccess).toBe(true)
+      })
+
+      expect(result.current.data).toBe("Hello, World!")
+    })
+
+    it("should pass args to the query", async () => {
+      const { result } = renderHook(
+        () =>
+          useActorQuery<TestActor, "greetWithName">({
+            reactor: mockReactor,
+            functionName: "greetWithName",
+            args: ["Alice"],
+          }),
+        { wrapper }
+      )
+
+      await waitFor(() => {
+        expect(result.current.isSuccess).toBe(true)
+      })
+
+      expect(result.current.data).toBe("Hello, Alice!")
+      expect(mockReactor.getQueryOptions).toHaveBeenCalledWith({
+        callConfig: undefined,
+        functionName: "greetWithName",
+        args: ["Alice"],
+      })
+    })
+
+    it("should handle bigint return types", async () => {
+      const { result } = renderHook(
+        () =>
+          useActorQuery<TestActor, "getCount">({
+            reactor: mockReactor,
+            functionName: "getCount",
+          }),
+        { wrapper }
+      )
+
+      await waitFor(() => {
+        expect(result.current.isSuccess).toBe(true)
+      })
+
+      expect(result.current.data).toBe(BigInt(42))
+    })
+  })
+
+  describe("select function", () => {
+    it("should transform data with select function", async () => {
+      const { result } = renderHook(
+        () =>
+          useActorQuery<TestActor, "greet", "candid", number>({
+            reactor: mockReactor,
+            functionName: "greet",
+            select: (data: string) => data.length,
+          }),
+        { wrapper }
+      )
+
+      await waitFor(() => {
+        expect(result.current.isSuccess).toBe(true)
+      })
+
+      // "Hello, World!" has 13 characters
+      expect(result.current.data).toBe(13)
+    })
+
+    it("should transform data to different type with select", async () => {
+      const { result } = renderHook(
+        () =>
+          useActorQuery<TestActor, "greet", "candid", { message: string }>({
+            reactor: mockReactor,
+            functionName: "greet",
+            select: (data: string) => ({ message: data }),
+          }),
+        { wrapper }
+      )
+
+      await waitFor(() => {
+        expect(result.current.isSuccess).toBe(true)
+      })
+
+      expect(result.current.data).toEqual({ message: "Hello, World!" })
+    })
+
+    it("should transform bigint to number with select", async () => {
+      const { result } = renderHook(
+        () =>
+          useActorQuery<TestActor, "getCount", "candid", number>({
+            reactor: mockReactor,
+            functionName: "getCount",
+            select: (data: bigint) => Number(data),
+          }),
+        { wrapper }
+      )
+
+      await waitFor(() => {
+        expect(result.current.isSuccess).toBe(true)
+      })
+
+      expect(result.current.data).toBe(42)
+      expect(typeof result.current.data).toBe("number")
+    })
+
+    it("should work with array transformation in select", async () => {
+      const { result } = renderHook(
+        () =>
+          useActorQuery<TestActor, "greet", "candid", string[]>({
+            reactor: mockReactor,
+            functionName: "greet",
+            select: (data: string) => data.split(", "),
+          }),
+        { wrapper }
+      )
+
+      await waitFor(() => {
+        expect(result.current.isSuccess).toBe(true)
+      })
+
+      expect(result.current.data).toEqual(["Hello", "World!"])
+    })
+  })
+
+  describe("query options", () => {
+    it("should respect enabled: false option", async () => {
+      const { result } = renderHook(
+        () =>
+          useActorQuery<TestActor, "greet">({
+            reactor: mockReactor,
+            functionName: "greet",
+            enabled: false,
+          }),
+        { wrapper }
+      )
+
+      // Should stay in pending state
+      expect(result.current.isPending).toBe(true)
+      expect(result.current.fetchStatus).toBe("idle")
+      expect(result.current.data).toBeUndefined()
+    })
+
+    it("should use custom staleTime", async () => {
+      const { result } = renderHook(
+        () =>
+          useActorQuery<TestActor, "greet">({
+            reactor: mockReactor,
+            functionName: "greet",
+            staleTime: 1000 * 60 * 10, // 10 minutes
+          }),
+        { wrapper }
+      )
+
+      await waitFor(() => {
+        expect(result.current.isSuccess).toBe(true)
+      })
+
+      expect(result.current.isStale).toBe(false)
+    })
+  })
+
+  describe("type inference", () => {
+    it("should infer string type for greet method without select", async () => {
+      const { result } = renderHook(
+        () =>
+          useActorQuery<TestActor, "greet">({
+            reactor: mockReactor,
+            functionName: "greet",
+          }),
+        { wrapper }
+      )
+
+      await waitFor(() => {
+        expect(result.current.isSuccess).toBe(true)
+      })
+
+      // TypeScript should infer data as string
+      const data: string | undefined = result.current.data
+      expect(typeof data).toBe("string")
+    })
+
+    it("should infer number type when select returns number", async () => {
+      const { result } = renderHook(
+        () =>
+          useActorQuery({
+            reactor: mockReactor,
+            functionName: "greet",
+            select: (data: any) => data.length,
+          }),
+        { wrapper }
+      )
+
+      await waitFor(() => {
+        expect(result.current.isSuccess).toBe(true)
+      })
+
+      // TypeScript should infer data as number
+      const data: number | undefined = result.current.data
+      expect(typeof data).toBe("number")
+    })
+  })
+
+  describe("refetching", () => {
+    it("should support manual refetch", async () => {
+      const { result } = renderHook(
+        () =>
+          useActorQuery<TestActor, "greet">({
+            reactor: mockReactor,
+            functionName: "greet",
+          }),
+        { wrapper }
+      )
+
+      await waitFor(() => {
+        expect(result.current.isSuccess).toBe(true)
+      })
+
+      // Refetch should be available
+      expect(typeof result.current.refetch).toBe("function")
+
+      await result.current.refetch()
+
+      expect(result.current.isSuccess).toBe(true)
+    })
+  })
+})

package/src/hooks/useActorQuery.ts

@@ -0,0 +1,110 @@
+import { useMemo } from "react"
+import {
+  QueryKey,
+  useQuery,
+  QueryObserverOptions,
+  UseQueryResult,
+} from "@tanstack/react-query"
+import {
+  FunctionName,
+  Reactor,
+  TransformKey,
+  ReactorArgs,
+  ReactorReturnOk,
+  ReactorReturnErr,
+} from "@ic-reactor/core"
+import { CallConfig } from "@icp-sdk/core/agent"
+
+export interface UseActorQueryParameters<
+  A,
+  M extends FunctionName<A>,
+  T extends TransformKey = "candid",
+  TSelected = ReactorReturnOk<A, M, T>,
+> extends Omit<
+  QueryObserverOptions<
+    ReactorReturnOk<A, M, T>,
+    ReactorReturnErr<A, M, T>,
+    TSelected,
+    ReactorReturnOk<A, M, T>,
+    QueryKey
+  >,
+  "queryKey" | "queryFn"
+> {
+  reactor: Reactor<A, T>
+  functionName: M
+  args?: ReactorArgs<A, M, T>
+  callConfig?: CallConfig
+  queryKey?: QueryKey
+}
+
+export type UseActorQueryConfig<
+  A,
+  M extends FunctionName<A>,
+  T extends TransformKey = "candid",
+  TSelected = ReactorReturnOk<A, M, T>,
+> = Omit<UseActorQueryParameters<A, M, T, TSelected>, "reactor">
+
+export type UseActorQueryResult<
+  A,
+  M extends FunctionName<A>,
+  T extends TransformKey = "candid",
+  TSelected = ReactorReturnOk<A, M, T>,
+> = UseQueryResult<TSelected, ReactorReturnErr<A, M, T>>
+
+/**
+ * Hook for executing query calls on a canister.
+ *
+ * @example
+ * const { data, isLoading } = useActorQuery({
+ *   reactor,
+ *   functionName: "getUser",
+ *   args: ["user-123"],
+ * })
+ *
+ * // With select transformation
+ * const { data } = useActorQuery({
+ *   reactor,
+ *   functionName: "getUser",
+ *   args: ["user-123"],
+ *   select: (user) => user.name,
+ * })
+ */
+export const useActorQuery = <
+  A,
+  M extends FunctionName<A>,
+  T extends TransformKey = "candid",
+  TSelected = ReactorReturnOk<A, M, T>,
+>({
+  reactor,
+  functionName,
+  args,
+  callConfig,
+  queryKey: defaultQueryKey,
+  ...options
+}: UseActorQueryParameters<A, M, T, TSelected>): UseActorQueryResult<
+  A,
+  M,
+  T,
+  TSelected
+> => {
+  // Memoize query options to prevent unnecessary re-computations
+  const { queryKey, queryFn } = useMemo(
+    () =>
+      reactor.getQueryOptions<M>({
+        callConfig,
+        functionName,
+        args,
+        queryKey: defaultQueryKey,
+      }),
+    [reactor, callConfig, functionName, args, defaultQueryKey]
+  )
+
+  return useQuery(
+    {
+      queryFn,
+      ...options,
+      queryKey,
+    },
+    reactor.queryClient
+  )
+}