@ic-reactor/react 3.6.0 → 3.7.0

package/src/createSuspenseQuery.ts

@@ -42,20 +42,20 @@ import { buildChainedSelect } from "./utils"
 // ============================================================================
 
 const createSuspenseQueryImpl = <
-  A,
-  M extends FunctionName<A> = FunctionName<A>,
-  T extends TransformKey = "candid",
-  TSelected = QueryFnData<A, M, T>,
+  Service,
+  Method extends FunctionName<Service> = FunctionName<Service>,
+  Transform extends TransformKey = "candid",
+  Selected = QueryFnData<Service, Method, Transform>,
 >(
-  reactor: Reactor<A, T>,
-  config: SuspenseQueryConfig<A, M, T, TSelected>
+  reactor: Reactor<Service, Transform>,
+  config: SuspenseQueryConfig<Service, Method, Transform, Selected>
 ): SuspenseQueryResult<
-  QueryFnData<A, M, T>,
-  TSelected,
-  QueryError<A, M, T>
+  QueryFnData<Service, Method, Transform>,
+  Selected,
+  QueryError<Service, Method, Transform>
 > => {
-  type TData = QueryFnData<A, M, T>
-  type TError = QueryError<A, M, T>
+  type TData = QueryFnData<Service, Method, Transform>
+  type TError = QueryError<Service, Method, Transform>
 
   const {
     functionName,
@@ -70,11 +70,11 @@ const createSuspenseQueryImpl = <
 
   const getQueryKey = () => reactor.generateQueryKey(params)
 
-  const applySelect = (raw: TData): TSelected =>
-    select ? select(raw) : (raw as unknown as TSelected)
+  const applySelect = (raw: TData): Selected =>
+    select ? select(raw) : (raw as unknown as Selected)
 
   /** Cache-first fetch for use in loaders / route preloading. */
-  const fetch = async (): Promise<TSelected> => {
+  const fetch = async (): Promise<Selected> => {
     const result = await reactor.fetchQuery(params)
     return applySelect(result)
   }
@@ -91,7 +91,7 @@ const createSuspenseQueryImpl = <
 
   const useSuspenseQueryHook: UseSuspenseQueryWithSelect<
     TData,
-    TSelected,
+    Selected,
     TError
   > = (options: any): any => {
     const baseOptions = reactor.getQueryOptions(params)
@@ -114,21 +114,20 @@ const createSuspenseQueryImpl = <
 
   const getCacheData: SuspenseQueryResult<
     TData,
-    TSelected,
+    Selected,
     TError
-  >["getCacheData"] = (selectFn?: (data: TSelected) => unknown): any => {
+  >["getCacheData"] = (selectFn?: (data: Selected) => unknown): any => {
     const raw = reactor.getQueryData(params)
     if (raw === undefined) return undefined
     const selected = applySelect(raw)
     return selectFn ? selectFn(selected) : selected
   }
 
-  const setData: SuspenseQueryResult<TData, TSelected, TError>["setData"] = (
+  const setData: SuspenseQueryResult<TData, Selected, TError>["setData"] = (
     updater
   ) => {
     return reactor.queryClient.setQueryData(getQueryKey(), updater as any) as
-      | TData
-      | undefined
+      TData | undefined
   }
 
   return {
@@ -147,17 +146,21 @@ const createSuspenseQueryImpl = <
 // ============================================================================
 
 export function createSuspenseQuery<
-  A,
-  T extends TransformKey,
-  M extends FunctionName<A> = FunctionName<A>,
-  TSelected = QueryFnData<A, M, T>,
+  Service,
+  Transform extends TransformKey,
+  Method extends FunctionName<Service> = FunctionName<Service>,
+  Selected = QueryFnData<Service, Method, Transform>,
 >(
-  reactor: Reactor<A, T>,
-  config: SuspenseQueryConfig<NoInfer<A>, M, T, TSelected>
-): SuspenseQueryResult<QueryFnData<A, M, T>, TSelected, QueryError<A, M, T>> {
+  reactor: Reactor<Service, Transform>,
+  config: SuspenseQueryConfig<NoInfer<Service>, Method, Transform, Selected>
+): SuspenseQueryResult<
+  QueryFnData<Service, Method, Transform>,
+  Selected,
+  QueryError<Service, Method, Transform>
+> {
   return createSuspenseQueryImpl(
     reactor,
-    config as SuspenseQueryConfig<A, M, T, TSelected>
+    config as SuspenseQueryConfig<Service, Method, Transform, Selected>
   )
 }
 
@@ -166,24 +169,37 @@ export function createSuspenseQuery<
 // ============================================================================
 
 export function createSuspenseQueryFactory<
-  A,
-  T extends TransformKey,
-  M extends FunctionName<A> = FunctionName<A>,
-  TSelected = QueryFnData<A, M, T>,
+  Service,
+  Transform extends TransformKey,
+  Method extends FunctionName<Service> = FunctionName<Service>,
+  Selected = QueryFnData<Service, Method, Transform>,
 >(
-  reactor: Reactor<A, T>,
-  config: SuspenseQueryFactoryConfig<NoInfer<A>, M, T, TSelected>
+  reactor: Reactor<Service, Transform>,
+  config: SuspenseQueryFactoryConfig<
+    NoInfer<Service>,
+    Method,
+    Transform,
+    Selected
+  >
 ): (
-  args: ReactorArgs<A, M, T>
-) => SuspenseQueryResult<QueryFnData<A, M, T>, TSelected, QueryError<A, M, T>> {
+  args: ReactorArgs<Service, Method, Transform>
+) => SuspenseQueryResult<
+  QueryFnData<Service, Method, Transform>,
+  Selected,
+  QueryError<Service, Method, Transform>
+> {
   const cache = new Map<
     string,
-    SuspenseQueryResult<QueryFnData<A, M, T>, TSelected, QueryError<A, M, T>>
+    SuspenseQueryResult<
+      QueryFnData<Service, Method, Transform>,
+      Selected,
+      QueryError<Service, Method, Transform>
+    >
   >()
 
-  return (args: ReactorArgs<A, M, T>) => {
+  return (args: ReactorArgs<Service, Method, Transform>) => {
     const key = reactor.generateQueryKey({
-      functionName: config.functionName as M,
+      functionName: config.functionName as Method,
       args,
     })
     const cacheKey = JSON.stringify(key)
@@ -191,8 +207,18 @@ export function createSuspenseQueryFactory<
     const existing = cache.get(cacheKey)
     if (existing) return existing
 
-    const result = createSuspenseQueryImpl<A, M, T, TSelected>(reactor, {
-      ...(config as SuspenseQueryFactoryConfig<A, M, T, TSelected>),
+    const result = createSuspenseQueryImpl<
+      Service,
+      Method,
+      Transform,
+      Selected
+    >(reactor, {
+      ...(config as SuspenseQueryFactoryConfig<
+        Service,
+        Method,
+        Transform,
+        Selected
+      >),
       args,
     })
     cache.set(cacheKey, result)

package/src/defineReactor.test.ts

@@ -0,0 +1,70 @@
+import { describe, it, expect } from "vitest"
+import { ClientManager, Reactor, DisplayReactor } from "@ic-reactor/core"
+import { QueryClient } from "@tanstack/react-query"
+import { defineReactor } from "./defineReactor"
+import { ActorMethod } from "@icp-sdk/core/agent"
+
+const idlFactory = ({ IDL }: any) =>
+  IDL.Service({
+    greet: IDL.Func([IDL.Text], [IDL.Text], ["query"]),
+  })
+
+interface TestActor {
+  greet: ActorMethod<[string], string>
+}
+
+const baseConfig = {
+  name: "test",
+  idlFactory,
+  canisterId: "rrkah-fqaaa-aaaaa-aaaaq-cai",
+}
+
+describe("defineReactor", () => {
+  it("bootstraps a standard Reactor with hooks and infrastructure", () => {
+    const result = defineReactor<TestActor>(baseConfig)
+
+    expect(result.reactor).toBeInstanceOf(Reactor)
+    expect(result.reactor).not.toBeInstanceOf(DisplayReactor)
+    expect(result.clientManager).toBeInstanceOf(ClientManager)
+    expect(result.queryClient).toBeInstanceOf(QueryClient)
+    expect(typeof result.useActorQuery).toBe("function")
+    expect(typeof result.useActorMutation).toBe("function")
+  })
+
+  it("creates a DisplayReactor when display is true", () => {
+    const result = defineReactor<TestActor>({ ...baseConfig, display: true })
+
+    expect(result.reactor).toBeInstanceOf(DisplayReactor)
+  })
+
+  it("wires the reactor to the created ClientManager and QueryClient", () => {
+    const { reactor, clientManager, queryClient } =
+      defineReactor<TestActor>(baseConfig)
+
+    expect(reactor.clientManager).toBe(clientManager)
+    expect(clientManager.queryClient).toBe(queryClient)
+  })
+
+  it("reuses an existing ClientManager and its QueryClient", () => {
+    const queryClient = new QueryClient()
+    const clientManager = new ClientManager({ queryClient })
+
+    const result = defineReactor<TestActor>({ ...baseConfig, clientManager })
+
+    expect(result.clientManager).toBe(clientManager)
+    expect(result.queryClient).toBe(queryClient)
+    expect(result.reactor.clientManager).toBe(clientManager)
+  })
+
+  it("lets multiple reactors share one ClientManager", () => {
+    const ledger = defineReactor<TestActor>({ ...baseConfig, name: "ledger" })
+    const index = defineReactor<TestActor>({
+      ...baseConfig,
+      name: "index",
+      clientManager: ledger.clientManager,
+    })
+
+    expect(index.clientManager).toBe(ledger.clientManager)
+    expect(index.reactor).not.toBe(ledger.reactor)
+  })
+})

package/src/defineReactor.ts

@@ -0,0 +1,150 @@
+/**
+ * defineReactor - One-call bootstrap for a canister reactor + its React hooks.
+ *
+ * Collapses the four manual steps (QueryClient → ClientManager → Reactor →
+ * createActorHooks) into a single call, and turns the Reactor / DisplayReactor
+ * choice into a `display` flag.
+ * Use this when one-call bootstrap is enough. If you need reusable
+ * method-specific operations outside React, compose with query/mutation
+ * factories after setup.
+ *
+ * @example
+ * ```typescript
+ * import { defineReactor } from "@ic-reactor/react"
+ * import { idlFactory, type _SERVICE } from "./declarations/backend"
+ *
+ * const { reactor, useActorQuery, useActorMutation } = defineReactor<_SERVICE>({
+ *   name: "backend",
+ *   idlFactory,
+ *   canisterId: "rrkah-fqaaa-aaaaa-aaaaq-cai",
+ *   display: true, // ⇒ DisplayReactor (string principals/bigints)
+ * })
+ *
+ * function Profile() {
+ *   const { data } = useActorQuery({ functionName: "get_profile" })
+ *   return <div>{data?.name}</div>
+ * }
+ * ```
+ *
+ * @example Reuse an existing ClientManager (multiple canisters share one agent)
+ * ```typescript
+ * const ledger = defineReactor<_LEDGER>({ name: "ledger", idlFactory: ledgerIdl })
+ * const index = defineReactor<_INDEX>({
+ *   name: "index",
+ *   idlFactory: indexIdl,
+ *   clientManager: ledger.clientManager,
+ * })
+ * ```
+ */
+import { ClientManager, Reactor, DisplayReactor } from "@ic-reactor/core"
+import type {
+  BaseActor,
+  TransformKey,
+  ReactorParameters,
+  ClientManagerParameters,
+  DisplayReactorParameters,
+} from "@ic-reactor/core"
+import { QueryClient } from "@tanstack/react-query"
+import { createActorHooks, ActorHooks } from "./createActorHooks"
+
+/** Options shared by both the standard and display variants of defineReactor. */
+export interface DefineReactorSharedParameters
+  extends
+    Omit<ReactorParameters, "clientManager">,
+    Omit<ClientManagerParameters, "queryClient"> {
+  /**
+   * Reuse an existing ClientManager (e.g. to share one agent across canisters).
+   * When omitted, a ClientManager is created from the agent options below.
+   */
+  clientManager?: ClientManager
+  /**
+   * Reuse an existing QueryClient. When omitted, the provided ClientManager's
+   * QueryClient is reused, or a new one is created.
+   */
+  queryClient?: QueryClient
+}
+
+/** Parameters for a standard (raw Candid types) reactor. */
+export interface DefineReactorParameters extends DefineReactorSharedParameters {
+  display?: false
+}
+
+/** Parameters for a DisplayReactor (UI-friendly string principals/bigints). */
+export interface DefineDisplayReactorParameters<
+  Service,
+> extends DefineReactorSharedParameters {
+  display: true
+  /** Optional initial argument validators (receive display types). */
+  validators?: DisplayReactorParameters<Service>["validators"]
+}
+
+/** The reactor instance plus its bound hooks and shared infrastructure. */
+export type DefineReactorResult<
+  Service,
+  Transform extends TransformKey,
+  R extends Reactor<Service, Transform>,
+> = ActorHooks<Service, Transform> & {
+  reactor: R
+  clientManager: ClientManager
+  queryClient: QueryClient
+}
+
+export function defineReactor<Service = BaseActor>(
+  params: DefineDisplayReactorParameters<Service>
+): DefineReactorResult<Service, "display", DisplayReactor<Service>>
+
+export function defineReactor<Service = BaseActor>(
+  params: DefineReactorParameters
+): DefineReactorResult<Service, "candid", Reactor<Service, "candid">>
+
+export function defineReactor<Service = BaseActor>(
+  params: DefineReactorParameters | DefineDisplayReactorParameters<Service>
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+): DefineReactorResult<Service, any, any> {
+  const {
+    clientManager: providedClientManager,
+    queryClient: providedQueryClient,
+    display,
+    agentOptions,
+    name,
+    idlFactory,
+    canisterId,
+    pollingOptions,
+  } = params as DefineDisplayReactorParameters<Service>
+
+  const queryClient =
+    providedQueryClient ??
+    providedClientManager?.queryClient ??
+    new QueryClient()
+
+  const clientManager =
+    providedClientManager ??
+    new ClientManager({
+      queryClient,
+      agentOptions,
+    })
+
+  const reactorConfig = {
+    clientManager,
+    name,
+    idlFactory,
+    canisterId,
+    pollingOptions,
+  }
+
+  // The Reactor / DisplayReactor union cannot be expressed through the shared
+  // implementation signature, so the body is intentionally untyped here; the
+  // public overloads above carry the precise types for callers.
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const reactor: any = display
+    ? new DisplayReactor<Service>({
+        ...reactorConfig,
+        validators: (params as DefineDisplayReactorParameters<Service>)
+          .validators,
+      })
+    : new Reactor<Service>(reactorConfig)
+
+  const hooks = createActorHooks(reactor)
+
+  return { ...hooks, reactor, clientManager, queryClient }
+}

package/src/{createAuthHooks.ts → hooks/createAuthHooks.ts}

@@ -1,26 +1,13 @@
-import {
-  useSyncExternalStore,
-  useEffect,
-  useRef,
-  useMemo,
-  useState,
-  useCallback,
-} from "react"
-import {
-  ClientManager,
-  AgentState,
-  AuthState,
-  ClientManagerSignInOptions,
-  IdentityAttributeResult,
-  RequestIdentityAttributesParameters,
-  RequestOpenIdIdentityAttributesParameters,
-} from "@ic-reactor/core"
+import { useSyncExternalStore, useEffect, useRef, useMemo } from "react"
+import type { AuthenticationManager } from "../auth/authentication-manager"
+import type { AuthState, AuthenticationSignInOptions } from "../auth/types"
+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?: ClientManagerSignInOptions) => Promise<void>
+  login: (options?: AuthenticationSignInOptions) => Promise<void>
   logout: (options?: { returnTo?: string }) => Promise<void>
   isAuthenticated: boolean
   isAuthenticating: boolean
@@ -33,27 +20,13 @@ export interface CreateAuthHooksReturn {
   useAgentState: () => AgentState
   useUserPrincipal: () => Principal | null
   useAuth: () => UseAuthReturn
-  useIdentityAttributes: () => UseIdentityAttributesReturn
-}
-
-export interface UseIdentityAttributesReturn {
-  requestAttributes: (
-    params: RequestIdentityAttributesParameters
-  ) => Promise<IdentityAttributeResult>
-  requestOpenIdAttributes: (
-    params: RequestOpenIdIdentityAttributesParameters
-  ) => Promise<IdentityAttributeResult>
-  attributes: IdentityAttributeResult | null
-  isRequestingAttributes: boolean
-  attributeError: Error | null
-  clearAttributes: () => void
 }
 
 /**
  * Create authentication hooks for managing user sessions with Internet Identity.
  *
  * @example
- * const { useAuth, useUserPrincipal, useAgentState } = createAuthHooks(clientManager)
+ * const { useAuth, useUserPrincipal, useAgentState } = createAuthHooks(authentication)
  *
  * function App() {
  *   const { login, logout, principal, isAuthenticated } = useAuth()
@@ -64,8 +37,9 @@ export interface UseIdentityAttributesReturn {
  * }
  */
 export const createAuthHooks = (
-  clientManager: ClientManager
+  authentication: AuthenticationManager
 ): CreateAuthHooksReturn => {
+  const { clientManager } = authentication
   /**
    * Subscribe to agent state changes.
    * Returns the current agent state (agent, isInitialized, etc.)
@@ -84,10 +58,10 @@ export const createAuthHooks = (
    */
   const useAuthState = (): AuthState =>
     useSyncExternalStore(
-      (callback) => clientManager.subscribeAuthState(callback),
-      () => clientManager.authState,
+      (callback) => authentication.subscribeAuthState(callback),
+      () => authentication.authState,
       // Server snapshot - provide initial state for SSR
-      () => clientManager.authState
+      () => authentication.authState
     )
 
   /**
@@ -109,7 +83,7 @@ export const createAuthHooks = (
    * }
    */
   const useAuth = (): UseAuthReturn => {
-    const { login, logout, authenticate } = clientManager
+    const { login, logout, authenticate } = authentication
     const { isAuthenticated, isAuthenticating, identity, error } =
       useAuthState()
 
@@ -120,7 +94,11 @@ export const createAuthHooks = (
     useEffect(() => {
       if (!initializedRef.current) {
         initializedRef.current = true
-        clientManager.initialize()
+        authentication
+          .prepareClient()
+          .catch(() => undefined)
+          .then(() => clientManager.initialize())
+          .then(() => authentication.authenticate())
       }
     }, [])
 
@@ -157,68 +135,9 @@ export const createAuthHooks = (
     return identity ? identity.getPrincipal() : null
   }
 
-  const useIdentityAttributes = (): UseIdentityAttributesReturn => {
-    const [attributes, setAttributes] =
-      useState<IdentityAttributeResult | null>(null)
-    const [isRequestingAttributes, setIsRequestingAttributes] = useState(false)
-    const [attributeError, setAttributeError] = useState<Error | null>(null)
-
-    const requestAttributes = useCallback(
-      async (params: RequestIdentityAttributesParameters) => {
-        setIsRequestingAttributes(true)
-        setAttributeError(null)
-        try {
-          const result = await clientManager.requestIdentityAttributes(params)
-          setAttributes(result)
-          return result
-        } catch (error) {
-          setAttributeError(error as Error)
-          throw error
-        } finally {
-          setIsRequestingAttributes(false)
-        }
-      },
-      []
-    )
-
-    const requestOpenIdAttributes = useCallback(
-      async (params: RequestOpenIdIdentityAttributesParameters) => {
-        setIsRequestingAttributes(true)
-        setAttributeError(null)
-        try {
-          const result =
-            await clientManager.requestOpenIdIdentityAttributes(params)
-          setAttributes(result)
-          return result
-        } catch (error) {
-          setAttributeError(error as Error)
-          throw error
-        } finally {
-          setIsRequestingAttributes(false)
-        }
-      },
-      []
-    )
-
-    const clearAttributes = useCallback(() => {
-      setAttributes(null)
-      setAttributeError(null)
-    }, [])
-
-    return {
-      requestAttributes,
-      requestOpenIdAttributes,
-      attributes,
-      isRequestingAttributes,
-      attributeError,
-      clearAttributes,
-    }
-  }
-
   return {
     useAuth,
     useAgentState,
     useUserPrincipal,
-    useIdentityAttributes,
   }
 }

package/src/hooks/index.ts

@@ -24,6 +24,10 @@ export {
   createActorMethodHooks,
 } from "./useActorMethod.js"
 
+// createAuthHooks
+export { createAuthHooks } from "./createAuthHooks.js"
+export type { CreateAuthHooksReturn, UseAuthReturn } from "./createAuthHooks.js"
+
 // ============================================================================
 // Types - UseReactor* (with reactor parameter)
 // ============================================================================