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

package/src/hooks/createAuthHooks.ts

@@ -1,189 +0,0 @@
-import { useSyncExternalStore, useEffect, useRef, useMemo } from "react"
-import type { AuthenticationManager } from "../auth/authentication-manager.js"
-import type { AuthState, AuthenticationSignInOptions } from "../auth/types.js"
-import type { AgentState } from "@ic-reactor/core"
-import type { Principal } from "@icp-sdk/core/principal"
-import type { Identity } from "@icp-sdk/core/agent"
-
-export interface UseAuthReturn {
-  authenticate: () => Promise<Identity | undefined>
-  login: (options?: AuthenticationSignInOptions) => Promise<void>
-  logout: (options?: { returnTo?: string }) => Promise<void>
-  isAuthenticated: boolean
-  isAuthenticating: boolean
-  /**
-   * The signed-in user's principal, or `null` while signed out. A signed-out
-   * session still holds an anonymous `identity`, and its principal is not
-   * returned here.
-   */
-  principal: Principal | null
-  identity: Identity | null
-  error: Error | undefined
-}
-
-export interface CreateAuthHooksReturn {
-  useAgentState: () => AgentState
-  useUserPrincipal: () => Principal | null
-  useAuth: () => UseAuthReturn
-}
-
-/**
- * The principal both hooks return.
- *
- * `authenticate()` and `logout()` leave the client's anonymous identity in
- * `authState.identity` with `isAuthenticated: false`, so deriving the principal
- * from the identity alone reported `2vxsx-fae` for a signed-out user, and
- * `principal ? <SignedIn /> : <SignedOut />` rendered the signed-in branch.
- * Memoized on the identity, because `getPrincipal()` may build a new object on
- * each call and the result is often a hook dependency.
- */
-function usePrincipal(
-  isAuthenticated: boolean,
-  identity: Identity | null
-): Principal | null {
-  return useMemo(
-    () => (isAuthenticated && identity ? identity.getPrincipal() : null),
-    [isAuthenticated, identity]
-  )
-}
-
-/**
- * Create authentication hooks for managing user sessions with Internet Identity.
- *
- * @example
- * const { useAuth, useUserPrincipal, useAgentState } = createAuthHooks(authentication)
- *
- * function App() {
- *   const { login, logout, principal, isAuthenticated } = useAuth()
- *
- *   return isAuthenticated
- *     ? <button onClick={() => logout()}>Logout {principal?.toText()}</button>
- *     : <button onClick={() => login()}>Login with II</button>
- * }
- */
-export const createAuthHooks = (
-  authentication: AuthenticationManager
-): CreateAuthHooksReturn => {
-  // Passing a ClientManager here is the natural mistake — it is what
-  // `AuthenticationManager` is built from, and the two are adjacent in every
-  // setup snippet. TypeScript rejects it, but a JS caller got no error until
-  // render, where it surfaced as "Cannot destructure property 'isAuthenticated'
-  // of 'useAuthState(...)' as it is undefined" — which names neither the cause
-  // nor this function.
-  if (
-    !authentication ||
-    typeof authentication.subscribeAuthState !== "function"
-  ) {
-    throw new TypeError(
-      "[ic-reactor] createAuthHooks() expects an AuthenticationManager, not a " +
-        "ClientManager. Build one first: " +
-        "`new AuthenticationManager({ clientManager })`, or take it from " +
-        "`defineReactor(...).authentication`."
-    )
-  }
-
-  const { clientManager } = authentication
-  /**
-   * Subscribe to agent state changes.
-   * Returns the current agent state (agent, isInitialized, etc.)
-   */
-  const useAgentState = (): AgentState =>
-    useSyncExternalStore(
-      (callback) => clientManager.subscribeAgentState(callback),
-      () => clientManager.agentState,
-      // Server snapshot - provide initial state for SSR
-      () => clientManager.agentState
-    )
-
-  /**
-   * Subscribe to authentication state changes.
-   * Returns auth state (isAuthenticated, isAuthenticating, identity, error)
-   */
-  const useAuthState = (): AuthState =>
-    useSyncExternalStore(
-      (callback) => authentication.subscribeAuthState(callback),
-      () => authentication.authState,
-      // Server snapshot - provide initial state for SSR
-      () => authentication.authState
-    )
-
-  /**
-   * Main authentication hook that provides login/logout methods and auth state.
-   * Automatically initializes the session on first use, restoring any previous session.
-   *
-   * @example
-   * function AuthButton() {
-   *   const { login, logout, isAuthenticated, isAuthenticating } = useAuth()
-   *
-   *   if (isAuthenticated) {
-   *     return <button onClick={() => logout()}>Logout</button>
-   *   }
-   *   return (
-   *     <button onClick={() => login()} disabled={isAuthenticating}>
-   *       {isAuthenticating ? "Connecting..." : "Login"}
-   *     </button>
-   *   )
-   * }
-   */
-  const useAuth = (): UseAuthReturn => {
-    const { login, logout, authenticate } = authentication
-    const { isAuthenticated, isAuthenticating, identity, error } =
-      useAuthState()
-
-    // Track if we've already initialized to avoid duplicate calls
-    const initializedRef = useRef(false)
-
-    // Auto-initialize on first mount to restore previous session.
-    // `prepareClient` also warms up the AuthClient so a later `login()` can
-    // open the identity provider window inside the click handler.
-    useEffect(() => {
-      if (!initializedRef.current) {
-        initializedRef.current = true
-        authentication
-          .prepareClient()
-          .catch(() => undefined)
-          .then(() => clientManager.initialize())
-          .then(() => authentication.authenticate())
-          // Failures are already reflected in authState/agentState; without
-          // this the rejection escapes as an unhandled promise rejection.
-          .catch(() => undefined)
-      }
-    }, [])
-
-    const principal = usePrincipal(isAuthenticated, identity)
-
-    return {
-      authenticate,
-      login,
-      logout,
-      isAuthenticated,
-      isAuthenticating,
-      principal,
-      identity,
-      error,
-    }
-  }
-
-  /**
-   * Get the current user's Principal.
-   * Returns null if not authenticated, including while the signed-out session
-   * holds the anonymous identity.
-   *
-   * @example
-   * function UserInfo() {
-   *   const principal = useUserPrincipal()
-   *   if (!principal) return null
-   *   return <span>Logged in as: {principal.toText()}</span>
-   * }
-   */
-  const useUserPrincipal = (): Principal | null => {
-    const { isAuthenticated, identity } = useAuthState()
-    return usePrincipal(isAuthenticated, identity)
-  }
-
-  return {
-    useAuth,
-    useAgentState,
-    useUserPrincipal,
-  }
-}

package/src/hooks/index.ts

@@ -1,103 +0,0 @@
-// ============================================================================
-// Hooks
-//
-// These are the RAW hooks: they take the reactor as a property. They are
-// therefore exported as `useReactor*` only — the `useActor*` names belong to
-// the bound hooks `createActorHooks` returns, which take no reactor. Aliasing
-// the raw implementations under the bound names would hand a caller following
-// the documented `useActorQuery({ functionName })` shape an undefined reactor.
-// ============================================================================
-
-// useActorQuery / useReactorQuery
-export { useActorQuery as useReactorQuery } from "./useActorQuery.js"
-
-// useActorMutation / useReactorMutation
-export { useActorMutation as useReactorMutation } from "./useActorMutation.js"
-
-// useActorSuspenseQuery / useReactorSuspenseQuery
-export { useActorSuspenseQuery as useReactorSuspenseQuery } from "./useActorSuspenseQuery.js"
-
-// useActorInfiniteQuery / useReactorInfiniteQuery
-export { useActorInfiniteQuery as useReactorInfiniteQuery } from "./useActorInfiniteQuery.js"
-
-// useActorSuspenseInfiniteQuery / useReactorSuspenseInfiniteQuery
-export { useActorSuspenseInfiniteQuery as useReactorSuspenseInfiniteQuery } from "./useActorSuspenseInfiniteQuery.js"
-
-// useActorMethod / useReactorMethod
-export {
-  useActorMethod,
-  useActorMethod as useReactorMethod,
-  createActorMethodHooks,
-} from "./useActorMethod.js"
-
-// createAuthHooks
-export { createAuthHooks } from "./createAuthHooks.js"
-export type { CreateAuthHooksReturn, UseAuthReturn } from "./createAuthHooks.js"
-
-// ============================================================================
-// Types - UseReactor* (with reactor parameter)
-// ============================================================================
-
-export type {
-  UseActorQueryParameters as UseReactorQueryParameters,
-  UseActorQueryResult as UseReactorQueryResult,
-} from "./useActorQuery.js"
-
-export type {
-  UseActorMutationParameters as UseReactorMutationParameters,
-  UseActorMutationResult as UseReactorMutationResult,
-} from "./useActorMutation.js"
-
-export type {
-  UseActorSuspenseQueryParameters as UseReactorSuspenseQueryParameters,
-  UseActorSuspenseQueryResult as UseReactorSuspenseQueryResult,
-} from "./useActorSuspenseQuery.js"
-
-export type {
-  UseActorInfiniteQueryParameters as UseReactorInfiniteQueryParameters,
-  UseActorInfiniteQueryResult as UseReactorInfiniteQueryResult,
-} from "./useActorInfiniteQuery.js"
-
-export type {
-  UseActorSuspenseInfiniteQueryParameters as UseReactorSuspenseInfiniteQueryParameters,
-  UseActorSuspenseInfiniteQueryResult as UseReactorSuspenseInfiniteQueryResult,
-} from "./useActorSuspenseInfiniteQuery.js"
-
-export type {
-  UseActorMethodParameters as UseReactorMethodParameters,
-  UseActorMethodResult as UseReactorMethodResult,
-} from "./useActorMethod.js"
-
-// ============================================================================
-// Types - UseActor* (without reactor parameter, for use with createActorHooks)
-// ============================================================================
-
-export type {
-  UseActorQueryConfig as UseActorQueryParameters,
-  UseActorQueryResult,
-} from "./useActorQuery.js"
-
-export type {
-  UseActorMutationConfig as UseActorMutationParameters,
-  UseActorMutationResult,
-} from "./useActorMutation.js"
-
-export type {
-  UseActorSuspenseQueryConfig as UseActorSuspenseQueryParameters,
-  UseActorSuspenseQueryResult,
-} from "./useActorSuspenseQuery.js"
-
-export type {
-  UseActorInfiniteQueryConfig as UseActorInfiniteQueryParameters,
-  UseActorInfiniteQueryResult,
-} from "./useActorInfiniteQuery.js"
-
-export type {
-  UseActorSuspenseInfiniteQueryConfig as UseActorSuspenseInfiniteQueryParameters,
-  UseActorSuspenseInfiniteQueryResult,
-} from "./useActorSuspenseInfiniteQuery.js"
-
-export type {
-  UseActorMethodConfig as UseActorMethodParameters,
-  UseActorMethodResult,
-} from "./useActorMethod.js"

package/src/hooks/useActorInfiniteQuery.ts

@@ -1,205 +0,0 @@
-import { useMemo, useCallback } from "react"
-import {
-  QueryKey,
-  useInfiniteQuery,
-  UseInfiniteQueryResult,
-  UseInfiniteQueryOptions,
-  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 { mergeFactoryQueryKey, normalizeQueryData } from "../utils.js"
-
-/**
- * Parameters for useActorInfiniteQuery hook.
- * Extends react-query's UseInfiniteQueryOptions with custom reactor params.
- */
-export interface UseActorInfiniteQueryParameters<
-  Service,
-  Method extends FunctionName<Service>,
-  Transform extends TransformKey = "candid",
-  TPageParam = unknown,
-  Selected = InfiniteData<
-    ReactorQueryData<ReactorReturnOk<Service, Method, Transform>>,
-    TPageParam
-  >,
-> extends Omit<
-  UseInfiniteQueryOptions<
-    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>
-  /** 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 UseActorInfiniteQueryConfig<
-  Service,
-  Method extends FunctionName<Service>,
-  Transform extends TransformKey = "candid",
-  TPageParam = unknown,
-  Selected = InfiniteData<
-    ReactorQueryData<ReactorReturnOk<Service, Method, Transform>>,
-    TPageParam
-  >,
-> = Omit<
-  UseActorInfiniteQueryParameters<
-    Service,
-    Method,
-    Transform,
-    TPageParam,
-    Selected
-  >,
-  "reactor"
->
-
-export type UseActorInfiniteQueryResult<
-  Service,
-  Method extends FunctionName<Service>,
-  Transform extends TransformKey = "candid",
-  TPageParam = unknown,
-  Selected = InfiniteData<
-    ReactorQueryData<ReactorReturnOk<Service, Method, Transform>>,
-    TPageParam
-  >,
-> = UseInfiniteQueryResult<
-  Selected,
-  ReactorReturnErr<Service, Method, Transform>
->
-
-/**
- * Hook for executing infinite/paginated query calls on a canister.
- *
- * @example
- * const { data, fetchNextPage, hasNextPage } = useActorInfiniteQuery({
- *   reactor,
- *   functionName: "getItems",
- *   getArgs: (pageParam) => [{ offset: pageParam, limit: 10 }],
- *   initialPageParam: 0,
- *   getNextPageParam: (lastPage) => lastPage.nextOffset,
- * })
- */
-export const useActorInfiniteQuery = <
-  Service,
-  Method extends FunctionName<Service>,
-  Transform extends TransformKey = "candid",
-  TPageParam = unknown,
-  Selected = InfiniteData<
-    ReactorQueryData<ReactorReturnOk<Service, Method, Transform>>,
-    TPageParam
-  >,
->({
-  reactor,
-  functionName,
-  getArgs,
-  callConfig,
-  queryKey,
-  ...options
-}: UseActorInfiniteQueryParameters<
-  Service,
-  Method,
-  Transform,
-  TPageParam,
-  Selected
->): UseActorInfiniteQueryResult<
-  Service,
-  Method,
-  Transform,
-  TPageParam,
-  Selected
-> => {
-  // 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,
-    ]
-  )
-
-  // Memoize queryFn to prevent recreation on every render
-  const queryFn = useCallback(
-    async ({ pageParam }: { pageParam: TPageParam }) => {
-      const args = getArgs(pageParam)
-      const result = await reactor.callMethod({
-        functionName,
-        args,
-        callConfig,
-      })
-      return normalizeQueryData<ReactorReturnOk<Service, Method, Transform>>(
-        result as ReactorReturnOk<Service, Method, Transform>
-      )
-    },
-    [reactor, functionName, getArgs, callConfig]
-  )
-
-  return useInfiniteQuery(
-    {
-      queryKey: baseQueryKey,
-      queryFn,
-      ...options,
-    } as any,
-    reactor.queryClient
-  ) as UseActorInfiniteQueryResult<
-    Service,
-    Method,
-    Transform,
-    TPageParam,
-    Selected
-  >
-}