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

package/src/hooks/useActorSuspenseQuery.test.tsx

@@ -0,0 +1,254 @@
+import { describe, it, expect, vi, beforeEach } from "vitest"
+import { renderHook, waitFor } from "@testing-library/react"
+import React, { Suspense } from "react"
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query"
+import { useActorSuspenseQuery } from "./useActorSuspenseQuery"
+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("useActorSuspenseQuery", () => {
+  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}>
+      <Suspense fallback={<div>Loading...</div>}>{children}</Suspense>
+    </QueryClientProvider>
+  )
+
+  describe("basic functionality", () => {
+    it("should fetch data with suspense", async () => {
+      const { result } = renderHook(
+        () =>
+          useActorSuspenseQuery<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(
+        () =>
+          useActorSuspenseQuery<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(
+        () =>
+          useActorSuspenseQuery<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(
+        () =>
+          useActorSuspenseQuery<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(
+        () =>
+          useActorSuspenseQuery<
+            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(
+        () =>
+          useActorSuspenseQuery<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")
+    })
+  })
+
+  describe("query options", () => {
+    it("should use custom staleTime", async () => {
+      const { result } = renderHook(
+        () =>
+          useActorSuspenseQuery<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("suspense behavior", () => {
+    it("should always return data (no undefined) when successful", async () => {
+      const { result } = renderHook(
+        () =>
+          useActorSuspenseQuery<TestActor, "greet">({
+            reactor: mockReactor,
+            functionName: "greet",
+          }),
+        { wrapper }
+      )
+
+      await waitFor(() => {
+        expect(result.current.isSuccess).toBe(true)
+      })
+
+      // Suspense queries always have data when rendered
+      expect(result.current.data).toBeDefined()
+      expect(result.current.data).toBe("Hello, World!")
+    })
+
+    it("should have status 'success' when data is available", async () => {
+      const { result } = renderHook(
+        () =>
+          useActorSuspenseQuery<TestActor, "greet">({
+            reactor: mockReactor,
+            functionName: "greet",
+          }),
+        { wrapper }
+      )
+
+      await waitFor(() => {
+        expect(result.current.status).toBe("success")
+      })
+    })
+  })
+
+  describe("refetching", () => {
+    it("should support manual refetch", async () => {
+      const { result } = renderHook(
+        () =>
+          useActorSuspenseQuery<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/useActorSuspenseQuery.ts

@@ -0,0 +1,112 @@
+import { useMemo } from "react"
+import {
+  QueryKey,
+  useSuspenseQuery,
+  QueryObserverOptions,
+  UseSuspenseQueryResult,
+  QueryFunction,
+} from "@tanstack/react-query"
+import {
+  FunctionName,
+  Reactor,
+  TransformKey,
+  ReactorArgs,
+  ReactorReturnOk,
+  ReactorReturnErr,
+} from "@ic-reactor/core"
+import { CallConfig } from "@icp-sdk/core/agent"
+
+export interface UseActorSuspenseQueryParameters<
+  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 UseActorSuspenseQueryConfig<
+  A,
+  M extends FunctionName<A>,
+  T extends TransformKey = "candid",
+  TSelected = ReactorReturnOk<A, M, T>,
+> = Omit<UseActorSuspenseQueryParameters<A, M, T, TSelected>, "reactor">
+
+export type UseActorSuspenseQueryResult<
+  A,
+  M extends FunctionName<A>,
+  T extends TransformKey = "candid",
+  TSelected = ReactorReturnOk<A, M, T>,
+> = UseSuspenseQueryResult<TSelected, ReactorReturnErr<A, M, T>>
+
+/**
+ * Hook for executing suspense-enabled query calls on a canister.
+ *
+ * @example
+ * const { data } = useActorSuspenseQuery({
+ *   reactor,
+ *   functionName: "getUser",
+ *   args: ["user-123"],
+ * })
+ *
+ * // With select transformation
+ * const { data } = useActorSuspenseQuery({
+ *   reactor,
+ *   functionName: "getUser",
+ *   args: ["user-123"],
+ *   select: (user) => user.name,
+ * })
+ */
+export const useActorSuspenseQuery = <
+  A,
+  M extends FunctionName<A>,
+  T extends TransformKey = "candid",
+  TSelected = ReactorReturnOk<A, M, T>,
+>({
+  reactor,
+  functionName,
+  args,
+  callConfig,
+  queryKey: defaultQueryKey,
+  ...options
+}: UseActorSuspenseQueryParameters<
+  A,
+  M,
+  T,
+  TSelected
+>): UseActorSuspenseQueryResult<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 useSuspenseQuery(
+    {
+      // Suspense queries don't support skipToken, so cast the queryFn
+      queryFn: queryFn as QueryFunction<ReactorReturnOk<A, M, T>, QueryKey>,
+      ...options,
+      queryKey,
+    },
+    reactor.queryClient
+  )
+}

package/src/index.ts

@@ -0,0 +1,21 @@
+// Re-export core (following TanStack Query's pattern)
+// Users can import everything from @ic-reactor/react without needing @ic-reactor/core
+export * from "@ic-reactor/core"
+
+// Re-export hooks
+export * from "./hooks"
+
+// Validation utilities for React
+export * from "./validation"
+
+// React-specific exports
+export * from "./createAuthHooks"
+export * from "./createActorHooks"
+
+export * from "./createQuery"
+export * from "./createSuspenseQuery"
+export * from "./createInfiniteQuery"
+export * from "./createSuspenseInfiniteQuery"
+export * from "./createMutation"
+
+export * from "./types"