@ic-reactor/react 3.12.5 → 3.13.0

package/src/hooks/useActorQuery.ts

@@ -2,8 +2,10 @@ import { useMemo } from "react"
 import {
   QueryKey,
   useQuery,
+  skipToken,
   QueryObserverOptions,
   UseQueryResult,
+  type SkipToken,
 } from "@tanstack/react-query"
 import {
   FunctionName,
@@ -15,6 +17,7 @@ import {
   ReactorReturnErr,
 } from "@ic-reactor/core"
 import { CallConfig } from "@icp-sdk/core/agent"
+import { retryOption, skippedQueryKey, useMountQueryClient } from "../utils.js"
 
 export interface UseActorQueryParameters<
   Service,
@@ -33,7 +36,13 @@ export interface UseActorQueryParameters<
 > {
   reactor: Reactor<Service, Transform>
   functionName: Method
-  args?: ReactorArgs<Service, Method, Transform>
+  /**
+   * 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
 }
@@ -59,19 +68,26 @@ export type UseActorQueryResult<
  * Hook for executing query calls on a canister.
  *
  * @example
- * const { data, isLoading } = useActorQuery({
+ * const { data, isLoading } = useReactorQuery({
  *   reactor,
  *   functionName: "getUser",
  *   args: ["user-123"],
  * })
  *
  * // With select transformation
- * const { data } = useActorQuery({
+ * 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,
@@ -91,15 +107,31 @@ export const useActorQuery = <
   Transform,
   Selected
 >): UseActorQueryResult<Service, Method, Transform, Selected> => {
+  useMountQueryClient(reactor.queryClient)
+
   // Memoize query options to prevent unnecessary re-computations
-  const { queryKey, queryFn } = useMemo(
+  // For an update method, the options also carry its default `retry`; see
+  // `Reactor.getQueryRetry`.
+  const { queryKey, queryFn, retry } = useMemo(
     () =>
-      reactor.getQueryOptions<Method>({
-        callConfig,
-        functionName,
-        args,
-        queryKey: defaultQueryKey,
-      }),
+      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.
@@ -118,6 +150,7 @@ export const useActorQuery = <
       queryFn,
       ...options,
       queryKey,
+      ...retryOption(options.retry, retry),
     },
     reactor.queryClient
   )

package/src/hooks/useActorSuspenseInfiniteQuery.ts

@@ -16,7 +16,14 @@ import {
   ReactorReturnErr,
 } from "@ic-reactor/core"
 import { CallConfig } from "@icp-sdk/core/agent"
-import { mergeFactoryQueryKey, normalizeQueryData } from "../utils.js"
+import {
+  callConfigForKey,
+  mergeFactoryQueryKey,
+  mountWhileSuspended,
+  normalizeQueryData,
+  retryOption,
+  useMountQueryClient,
+} from "../utils.js"
 
 /**
  * Parameters for useActorSuspenseInfiniteQuery hook.
@@ -47,6 +54,18 @@ export interface UseActorSuspenseInfiniteQueryParameters<
   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) */
@@ -100,10 +119,10 @@ export type UseActorSuspenseInfiniteQueryResult<
  * Hook for executing suspense-enabled infinite/paginated query calls on a canister.
  *
  * @example
- * const { data, fetchNextPage, hasNextPage } = useActorSuspenseInfiniteQuery({
+ * const { data, fetchNextPage, hasNextPage } = useReactorSuspenseInfiniteQuery({
  *   reactor,
  *   functionName: "getItems",
- *   getArgs: (pageParam) => [{ offset: pageParam, limit: 10 }],
+ *   getArgs: (pageParam) => [{ offset: pageParam, limit: 10 }] as const,
  *   initialPageParam: 0,
  *   getNextPageParam: (lastPage) => lastPage.nextOffset,
  * })
@@ -121,6 +140,7 @@ export const useActorSuspenseInfiniteQuery = <
   reactor,
   functionName,
   getArgs,
+  getKeyArgs,
   callConfig,
   queryKey,
   ...options
@@ -137,49 +157,59 @@ export const useActorSuspenseInfiniteQuery = <
   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(
-    () =>
-      reactor.generateQueryKey(
-        {
-          functionName,
-          // 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.
-          queryKey: mergeFactoryQueryKey(
-            queryKey,
-            undefined,
-            getArgs(options.initialPageParam)
-          ),
-        },
-        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,
-      options.initialPageParam,
-    ]
-  )
+  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 }: { pageParam: TPageParam }) => {
+    async ({
+      pageParam,
+      queryKey: fetchedKey,
+    }: {
+      pageParam: TPageParam
+      queryKey: QueryKey
+    }) => {
       const args = getArgs(pageParam)
       const result = await reactor.callMethod({
         functionName,
         args,
-        callConfig,
+        callConfig: callConfigForKey(fetchedKey, callConfig),
       })
       return normalizeQueryData<ReactorReturnOk<Service, Method, Transform>>(
         result as ReactorReturnOk<Service, Method, Transform>
@@ -188,18 +218,31 @@ export const useActorSuspenseInfiniteQuery = <
     [reactor, functionName, getArgs, callConfig]
   )
 
-  return useSuspenseInfiniteQuery(
-    {
-      queryKey: baseQueryKey,
-      queryFn,
-      ...options,
-    } as any,
-    reactor.queryClient
-  ) as UseActorSuspenseInfiniteQueryResult<
-    Service,
-    Method,
-    Transform,
-    TPageParam,
-    Selected
-  >
+  // 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
+  }
 }

package/src/hooks/useActorSuspenseQuery.ts

@@ -16,6 +16,11 @@ import {
   ReactorReturnErr,
 } from "@ic-reactor/core"
 import { CallConfig } from "@icp-sdk/core/agent"
+import {
+  mountWhileSuspended,
+  retryOption,
+  useMountQueryClient,
+} from "../utils.js"
 
 export interface UseActorSuspenseQueryParameters<
   Service,
@@ -63,14 +68,14 @@ export type UseActorSuspenseQueryResult<
  * Hook for executing suspense-enabled query calls on a canister.
  *
  * @example
- * const { data } = useActorSuspenseQuery({
+ * const { data } = useReactorSuspenseQuery({
  *   reactor,
  *   functionName: "getUser",
  *   args: ["user-123"],
  * })
  *
  * // With select transformation
- * const { data } = useActorSuspenseQuery({
+ * const { data } = useReactorSuspenseQuery({
  *   reactor,
  *   functionName: "getUser",
  *   args: ["user-123"],
@@ -95,8 +100,12 @@ export const useActorSuspenseQuery = <
   Transform,
   Selected
 >): UseActorSuspenseQueryResult<Service, Method, Transform, Selected> => {
+  useMountQueryClient(reactor.queryClient)
+
   // Memoize query options to prevent unnecessary re-computations
-  const { queryKey, queryFn } = useMemo(
+  // For an update method, the options also carry its default `retry`; see
+  // `Reactor.getQueryRetry`.
+  const { queryKey, queryFn, retry } = useMemo(
     () =>
       reactor.getQueryOptions<Method>({
         callConfig,
@@ -117,16 +126,22 @@ export const useActorSuspenseQuery = <
     ]
   )
 
-  return useSuspenseQuery(
-    {
-      // Suspense queries don't support skipToken, so cast the queryFn
-      queryFn: queryFn as QueryFunction<
-        ReactorQueryData<ReactorReturnOk<Service, Method, Transform>>,
-        QueryKey
-      >,
-      ...options,
-      queryKey,
-    },
-    reactor.queryClient
-  )
+  try {
+    return useSuspenseQuery(
+      {
+        // Suspense queries don't support skipToken, so cast the queryFn
+        queryFn: queryFn as QueryFunction<
+          ReactorQueryData<ReactorReturnOk<Service, Method, Transform>>,
+          QueryKey
+        >,
+        ...options,
+        queryKey,
+        ...retryOption(options.retry, retry),
+      },
+      reactor.queryClient
+    )
+  } catch (thrown) {
+    mountWhileSuspended(reactor.queryClient, thrown)
+    throw thrown
+  }
 }

package/src/index.ts

@@ -11,6 +11,8 @@ export * from "./validation.js"
 // React-specific exports
 export * from "./createActorHooks.js"
 export * from "./defineReactor.js"
+export * from "./defineDisplayReactor.js"
+export * from "./createReactorProvider.js"
 
 export * from "./createQuery.js"
 export * from "./createSuspenseQuery.js"
@@ -21,3 +23,9 @@ export * from "./createMutation.js"
 export * from "./auth/index.js"
 
 export * from "./types.js"
+
+// TanStack Query's marker for a query whose args are not known yet, which the
+// non-suspense query hooks and createQueryFactory take in place of args. It is
+// the same symbol as @tanstack/react-query's, so either import works.
+export { skipToken } from "@tanstack/react-query"
+export type { SkipToken } from "@tanstack/react-query"

package/src/ownedAuthentication.ts

@@ -0,0 +1,81 @@
+/**
+ * Which `AuthenticationManager`s a `createReactorProvider` value owns, for the
+ * provider to dispose when its tree unmounts. Not part of the public API.
+ *
+ * A value owns the managers built for it: those constructed while its factory
+ * ran, and those a `defineReactor` or `defineDisplayReactor` result in it
+ * builds later, on first use. A manager built elsewhere and handed in, such as
+ * an app-wide one every provider shares, belongs to whoever built it, and
+ * disposing it on each remount would stop its client following the session.
+ *
+ * A result's `authentication` is a getter that builds the manager on first
+ * read, and building one loads the optional `@icp-sdk/auth` peer in a browser.
+ * A provider that read it to release the manager would build one only to
+ * dispose it, for every reactor whose tree never signed in. Each result
+ * registers a reader here instead, which answers without building anything.
+ *
+ * Kept apart from `defineReactorShared.ts` so that the provider does not pull
+ * that module's reactor setup into an app that builds its reactors by hand.
+ */
+import type { AuthenticationManager } from "./auth/authentication-manager.js"
+
+const readers = new WeakMap<object, () => AuthenticationManager | undefined>()
+
+/** The managers constructed during a running {@link collectAuthentication}. */
+let collecting: Set<AuthenticationManager> | undefined
+
+/**
+ * Records how to read the manager `owner` built, once it has built one.
+ *
+ * @internal
+ */
+export function registerAuthentication(
+  owner: object,
+  read: () => AuthenticationManager | undefined
+): void {
+  readers.set(owner, read)
+}
+
+/**
+ * The manager a registered result built, or `undefined` for one that has not
+ * built one yet, for one that was handed a manager, and for anything that was
+ * never registered.
+ *
+ * @internal
+ */
+export function authenticationOf(
+  owner: object
+): AuthenticationManager | undefined {
+  return readers.get(owner)?.()
+}
+
+/**
+ * Called by each `AuthenticationManager` as it is constructed.
+ *
+ * @internal
+ */
+export function recordAuthentication(manager: AuthenticationManager): void {
+  collecting?.add(manager)
+}
+
+/**
+ * Runs `build` and returns what it returned, with every manager constructed
+ * while it ran. `build` runs synchronously, so a server rendering several
+ * requests at once cannot interleave another request's managers.
+ *
+ * @internal
+ */
+export function collectAuthentication<T>(build: () => T): {
+  value: T
+  built: AuthenticationManager[]
+} {
+  const outer = collecting
+  const built = new Set<AuthenticationManager>()
+  collecting = built
+  try {
+    const value = build()
+    return { value, built: [...built] }
+  } finally {
+    collecting = outer
+  }
+}

package/src/server.ts

@@ -0,0 +1,23 @@
+/**
+ * The `react-server` entry of `@ic-reactor/react`.
+ *
+ * React Server Components are bundled with the `react-server` export
+ * condition, and `package.json` routes that condition here instead of to
+ * `index.ts`. The main entry also loads every hook, and a bundler rejects a
+ * hook import anywhere in the server graph, so a server component that
+ * imported only `Reactor` from it failed to build.
+ *
+ * This entry carries the core runtime (`Reactor`, `DisplayReactor`,
+ * `ClientManager`, the error classes and utilities) and the framework-free
+ * validation helpers, and nothing that imports React. A hook or a hook factory
+ * imported in a server component is therefore a missing export at build time,
+ * which is the error to get: those only run in a `"use client"` module.
+ *
+ * TypeScript does not read the `react-server` condition, so types still come
+ * from the main entry.
+ */
+export * from "@ic-reactor/core"
+
+// Plain functions over `ValidationError`, useful in a server action that maps
+// a rejected call onto form field errors.
+export * from "./validation.js"

package/src/testing.ts

@@ -0,0 +1,18 @@
+/**
+ * `@ic-reactor/react/testing`: the testing utilities of
+ * `@ic-reactor/core/testing`, re-exported for an app that depends on
+ * `@ic-reactor/react` alone. The main entry re-exports `@ic-reactor/core` the
+ * same way, but a package manager that installs strictly does not let such an
+ * app import `@ic-reactor/core/testing` itself.
+ *
+ * Nothing here imports React, and neither the main entry nor the
+ * `react-server` entry imports this one, so none of it reaches an app bundle.
+ *
+ * @example
+ * ```typescript
+ * import { createTestCanister, installFakeReplica } from "@ic-reactor/react/testing"
+ * ```
+ *
+ * @packageDocumentation
+ */
+export * from "@ic-reactor/core/testing"