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

package/src/createSuspenseQuery.ts

@@ -1,234 +0,0 @@
-/**
- * Suspense Query Factory - Generic wrapper for React Suspense-based canister data
- *
- * Creates unified fetch/hook/invalidate functions for any canister method.
- * Works with any Reactor instance.
- *
- * Uses `useSuspenseQuery` which:
- * - Requires wrapping in <Suspense> boundary
- * - Data is always defined (no undefined checks)
- * - Does NOT support `enabled` option
- *
- * @example
- * const userQuery = createSuspenseQuery(todoManager, {
- *   functionName: "get_user",
- *   select: (result) => result.user,
- * })
- *
- * // In component (wrap in Suspense)
- * const { data: user } = userQuery.useSuspenseQuery() // data is never undefined!
- */
-
-import type {
-  Reactor,
-  FunctionName,
-  ReactorArgs,
-  TransformKey,
-} from "@ic-reactor/core"
-import { useMemo } from "react"
-import { useSuspenseQuery } from "@tanstack/react-query"
-import type {
-  QueryFnData,
-  QueryError,
-  SuspenseQueryConfig,
-  UseSuspenseQueryWithSelect,
-  SuspenseQueryResult,
-  SuspenseQueryFactoryConfig,
-  NoInfer,
-} from "./types.js"
-import { buildChainedSelect, createBoundedCache } from "./utils.js"
-
-// ============================================================================
-// Internal Implementation
-// ============================================================================
-
-const createSuspenseQueryImpl = <
-  Service,
-  Method extends FunctionName<Service> = FunctionName<Service>,
-  Transform extends TransformKey = "candid",
-  Selected = QueryFnData<Service, Method, Transform>,
->(
-  reactor: Reactor<Service, Transform>,
-  config: SuspenseQueryConfig<Service, Method, Transform, Selected>
-): SuspenseQueryResult<
-  QueryFnData<Service, Method, Transform>,
-  Selected,
-  QueryError<Service, Method, Transform>
-> => {
-  type TData = QueryFnData<Service, Method, Transform>
-  type TError = QueryError<Service, Method, Transform>
-
-  const {
-    functionName,
-    args,
-    staleTime = 5 * 60 * 1000,
-    select,
-    queryKey: customQueryKey,
-    ...rest
-  } = config
-
-  const params = { functionName, args, queryKey: customQueryKey }
-
-  const getQueryKey = () => reactor.generateQueryKey(params)
-
-  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<Selected> => {
-    const result = await reactor.fetchQuery(params)
-    return applySelect(result)
-  }
-
-  /** Fire-and-forget prefetch — warms the cache without blocking. */
-  const prefetch = (): Promise<void> => {
-    const baseOptions = reactor.getQueryOptions(params)
-    return reactor.queryClient.prefetchQuery({
-      queryKey: baseOptions.queryKey,
-      queryFn: baseOptions.queryFn,
-      staleTime,
-    })
-  }
-
-  const useSuspenseQueryHook: UseSuspenseQueryWithSelect<
-    TData,
-    Selected,
-    TError
-  > = (options: any): any => {
-    const baseOptions = reactor.getQueryOptions(params)
-    // Memoized so the observer's select-result cache can hit; see
-    // buildChainedSelect. `select` comes from the factory config and is stable.
-    const chainedSelect = useMemo(
-      () => buildChainedSelect(select, options?.select),
-      [options?.select]
-    )
-    return useSuspenseQuery(
-      {
-        queryKey: baseOptions.queryKey,
-        staleTime,
-        ...rest,
-        ...options,
-        queryFn: baseOptions.queryFn,
-        select: chainedSelect,
-      },
-      reactor.queryClient
-    )
-  }
-
-  const invalidate = async (): Promise<void> => {
-    await reactor.queryClient.invalidateQueries({ queryKey: getQueryKey() })
-  }
-
-  const getCacheData: SuspenseQueryResult<
-    TData,
-    Selected,
-    TError
-  >["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, Selected, TError>["setData"] = (
-    updater
-  ) => {
-    return reactor.queryClient.setQueryData(getQueryKey(), updater as any) as
-      TData | undefined
-  }
-
-  return {
-    fetch,
-    prefetch,
-    useSuspenseQuery: useSuspenseQueryHook,
-    invalidate,
-    getQueryKey,
-    getCacheData,
-    setData,
-  }
-}
-
-// ============================================================================
-// Public Factory Function
-// ============================================================================
-
-export function createSuspenseQuery<
-  Service,
-  Transform extends TransformKey,
-  Method extends FunctionName<Service> = FunctionName<Service>,
-  Selected = QueryFnData<Service, Method, Transform>,
->(
-  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<Service, Method, Transform, Selected>
-  )
-}
-
-// ============================================================================
-// Convenience: Create suspense query with dynamic args
-// ============================================================================
-
-export function createSuspenseQueryFactory<
-  Service,
-  Transform extends TransformKey,
-  Method extends FunctionName<Service> = FunctionName<Service>,
-  Selected = QueryFnData<Service, Method, Transform>,
->(
-  reactor: Reactor<Service, Transform>,
-  config: SuspenseQueryFactoryConfig<
-    NoInfer<Service>,
-    Method,
-    Transform,
-    Selected
-  >
-): (
-  args: ReactorArgs<Service, Method, Transform>
-) => SuspenseQueryResult<
-  QueryFnData<Service, Method, Transform>,
-  Selected,
-  QueryError<Service, Method, Transform>
-> {
-  const cache =
-    createBoundedCache<
-      SuspenseQueryResult<
-        QueryFnData<Service, Method, Transform>,
-        Selected,
-        QueryError<Service, Method, Transform>
-      >
-    >()
-
-  return (args: ReactorArgs<Service, Method, Transform>) => {
-    const key = reactor.generateQueryKey({
-      functionName: config.functionName as Method,
-      args,
-    })
-    const cacheKey = JSON.stringify(key)
-
-    const existing = cache.get(cacheKey)
-    if (existing) return existing
-
-    const result = createSuspenseQueryImpl<
-      Service,
-      Method,
-      Transform,
-      Selected
-    >(reactor, {
-      ...(config as SuspenseQueryFactoryConfig<
-        Service,
-        Method,
-        Transform,
-        Selected
-      >),
-      args,
-    })
-    cache.set(cacheKey, result)
-    return result
-  }
-}

package/src/defineReactor.ts

@@ -1,324 +0,0 @@
-/**
- * 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,
- *   authentication: ledger.authentication, // one Internet Identity session
- * })
- * ```
- *
- * @example Internet Identity is wired up out of the box
- * ```typescript
- * const { useAuth, useIdentityAttributes } = defineReactor<_SERVICE>({
- *   name: "backend",
- *   idlFactory,
- *   // Needed when the app is served from more than one origin.
- *   auth: { derivationOrigin: "https://app.example.com" },
- * })
- *
- * function LoginButton() {
- *   const { login, logout, isAuthenticated, principal } = useAuth()
- *   return isAuthenticated
- *     ? <button onClick={() => logout()}>{principal?.toText()}</button>
- *     : <button onClick={() => login()}>Sign in</button>
- * }
- * ```
- */
-import {
-  ClientManager,
-  Reactor,
-  DisplayReactor,
-  reactorRetry,
-} 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.js"
-import { AuthenticationManager } from "./auth/authentication-manager.js"
-import { IdentityAttributesManager } from "./auth/identity-attributes-manager.js"
-import { createIdentityAttributeHooks } from "./auth/createIdentityAttributeHooks.js"
-import type { UseIdentityAttributesReturn } from "./auth/createIdentityAttributeHooks.js"
-import { createAuthHooks } from "./hooks/createAuthHooks.js"
-import type { CreateAuthHooksReturn } from "./hooks/createAuthHooks.js"
-import type { AuthenticationManagerParameters } from "./auth/authentication-manager.js"
-
-/** 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.
-   *
-   * A supplied or adopted manager brings its own agent and QueryClient, so
-   * `agentOptions`, `queryClient` and `allowEnvConfig` apply only when this
-   * call creates one.
-   */
-  clientManager?: ClientManager
-  /**
-   * QueryClient for a ClientManager created by this call.
-   *
-   * Ignored when `clientManager` or `authentication` is supplied — queries run
-   * against that manager's own QueryClient, which is what is returned.
-   */
-  queryClient?: QueryClient
-  /**
-   * Reuse an existing AuthenticationManager, so several reactors share one
-   * Internet Identity session. When omitted, one is created for this reactor.
-   *
-   * Its `clientManager` is adopted for this reactor, so sign-in updates the
-   * same agent the reactor calls through. Supplying a different `clientManager`
-   * alongside it is rejected.
-   */
-  authentication?: AuthenticationManager
-  /**
-   * Internet Identity options forwarded to the AuthenticationManager
-   * (`identityProvider`, `derivationOrigin`, `idleOptions`, `storage`, …).
-   *
-   * Mutually exclusive with `authentication`: a manager built elsewhere is
-   * already configured, so these could not be applied to it.
-   */
-  auth?: Omit<AuthenticationManagerParameters, "clientManager">
-}
-
-/** 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> &
-  CreateAuthHooksReturn & {
-    reactor: R
-    clientManager: ClientManager
-    queryClient: QueryClient
-    /** Internet Identity session manager backing `useAuth`. */
-    authentication: AuthenticationManager
-    /** Signed identity attribute requests backing `useIdentityAttributes`. */
-    identityAttributes: IdentityAttributesManager
-    useIdentityAttributes: () => UseIdentityAttributesReturn
-  }
-
-/**
- * The QueryClient this module creates when the caller does not supply one.
- *
- * React Query retries every failure three times by default, which for canister
- * calls means four attempts and several seconds of backoff on outcomes that
- * cannot change — a canister `Err`, a validation failure, a Candid encode
- * error that never reached the network. `reactorRetry` keeps the same three
- * attempts for transport failures and stops immediately on the rest.
- *
- * A caller-supplied `queryClient` is left exactly as given; opt in there with
- * `defaultOptions: { queries: { retry: reactorRetry } }`.
- */
-const createDefaultQueryClient = () =>
-  new QueryClient({
-    defaultOptions: { queries: { retry: reactorRetry } },
-  })
-
-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>
-): DefineReactorResult<Service, any, any> {
-  const {
-    clientManager: providedClientManager,
-    queryClient: providedQueryClient,
-    authentication: providedAuthentication,
-    auth,
-    display,
-    agentOptions,
-    allowEnvConfig,
-    allowEnvRootKey,
-    name,
-    idlFactory,
-    canisterId,
-    pollingOptions,
-  } = params as DefineDisplayReactorParameters<Service>
-
-  // A shared AuthenticationManager updates the identity on its own
-  // ClientManager. Giving this reactor a different one would leave its calls
-  // anonymous after sign-in, so adopt the manager's rather than building a new
-  // one, and refuse an explicit mismatch instead of splitting them silently.
-  if (
-    providedClientManager &&
-    providedAuthentication &&
-    providedAuthentication.clientManager !== providedClientManager
-  ) {
-    throw new Error(
-      `[ic-reactor] defineReactor("${name}") received an \`authentication\` manager bound to a different \`clientManager\`. ` +
-        `Sign-in would update the authentication manager's agent while this reactor calls through another one, ` +
-        `leaving its calls anonymous. Pass \`clientManager: authentication.clientManager\`, or omit \`clientManager\` to adopt it.`
-    )
-  }
-
-  // `auth` configures a manager this call would build; an existing one is
-  // already constructed, so these options could only be dropped on the floor.
-  if (providedAuthentication && auth) {
-    throw new Error(
-      `[ic-reactor] defineReactor("${name}") received both \`authentication\` and \`auth\`. ` +
-        `The supplied manager is already configured, so \`auth\` (${Object.keys(auth).join(", ")}) would be ignored. ` +
-        `Pass those options where that AuthenticationManager is created, or drop \`authentication\` to build one here.`
-    )
-  }
-
-  // Same reasoning as `auth`, and it matters more here: an ignored
-  // `allowEnvConfig: false` reads as "I locked the cookie out" while the
-  // supplied manager carries whatever decision it was built with.
-  if (
-    (providedClientManager || providedAuthentication) &&
-    (allowEnvConfig !== undefined || allowEnvRootKey !== undefined)
-  ) {
-    const passed = [
-      allowEnvConfig !== undefined && "allowEnvConfig",
-      allowEnvRootKey !== undefined && "allowEnvRootKey",
-    ]
-      .filter(Boolean)
-      .join(", ")
-    throw new Error(
-      `[ic-reactor] defineReactor("${name}") received both a ClientManager and \`${passed}\`. ` +
-        `That option is resolved when a ClientManager is constructed, so the supplied one already carries its own ` +
-        `decision and this would be ignored — silently changing nothing about whether the ic_env cookie is trusted. ` +
-        `Pass it where that ClientManager is created, or drop \`clientManager\` to build one here.`
-    )
-  }
-
-  const clientManager =
-    providedClientManager ??
-    providedAuthentication?.clientManager ??
-    new ClientManager({
-      queryClient: providedQueryClient ?? createDefaultQueryClient(),
-      agentOptions,
-      // Forwarded, not dropped: the type has always accepted these (it extends
-      // ClientManagerParameters) while the call ignored them, so the one
-      // documented setup path silently discarded the ic_env opt-in it advertised.
-      allowEnvConfig,
-      allowEnvRootKey,
-    })
-
-  // Always report the QueryClient actually in use: when a ClientManager is
-  // supplied or adopted, its own QueryClient is the one queries run against.
-  const queryClient = clientManager.queryClient
-
-  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.
-
-  const reactor: any = display
-    ? new DisplayReactor<Service>({
-        ...reactorConfig,
-        validators: (params as DefineDisplayReactorParameters<Service>)
-          .validators,
-      })
-    : new Reactor<Service>(reactorConfig)
-
-  // `reactor` is `any` above, which would let the overloads infer `Service`
-  // as `unknown` and type every hook's arguments as `never`.
-  const hooks = createActorHooks<Service, any>(reactor)
-
-  // Auth is built on first use. `AuthenticationManager` dynamically imports the
-  // optional `@icp-sdk/auth` peer as soon as it is constructed, and reactors
-  // that never touch authentication should not pay for that.
-  let authenticationInstance: AuthenticationManager | undefined
-  const getAuthentication = () =>
-    (authenticationInstance ??=
-      providedAuthentication ??
-      new AuthenticationManager({ ...auth, clientManager }))
-
-  let identityAttributesInstance: IdentityAttributesManager | undefined
-  const getIdentityAttributes = () =>
-    (identityAttributesInstance ??= new IdentityAttributesManager(
-      getAuthentication()
-    ))
-
-  let authHooks: CreateAuthHooksReturn | undefined
-  const getAuthHooks = () =>
-    (authHooks ??= createAuthHooks(getAuthentication()))
-
-  let attributeHooks:
-    ReturnType<typeof createIdentityAttributeHooks> | undefined
-  const getAttributeHooks = () =>
-    (attributeHooks ??= createIdentityAttributeHooks(getIdentityAttributes()))
-
-  return {
-    ...hooks,
-    reactor,
-    clientManager,
-    queryClient,
-    // Stable wrappers: the hook call order inside them never changes, so the
-    // rules of hooks still hold.
-    useAuth: () => getAuthHooks().useAuth(),
-    useAgentState: () => getAuthHooks().useAgentState(),
-    useUserPrincipal: () => getAuthHooks().useUserPrincipal(),
-    useIdentityAttributes: () => getAttributeHooks().useIdentityAttributes(),
-    get authentication() {
-      return getAuthentication()
-    },
-    get identityAttributes() {
-      return getIdentityAttributes()
-    },
-  }
-}