@ic-reactor/react 3.13.0 → 4.0.0-beta.2

package/src/createMutation.ts

@@ -1,324 +0,0 @@
-/**
- * Mutation Factory - Generic wrapper for mutating canister data
- *
- * Creates unified mutation hooks for any canister method.
- * Works with any Reactor instance.
- * Use this when one mutation should support both React hooks and imperative
- * execution outside React.
- *
- * @example
- * const transferMutation = createMutation(reactor, {
- *   functionName: "transfer",
- *   // Refetched before onSuccess runs: a query factory covers every args
- *   // instance, a `{ functionName }` every query of that method
- *   invalidateQueries: [getBalance, { functionName: "get_history" }],
- *   onSuccess: () => console.log("Success!"),
- * })
- *
- * // In component
- * const { mutate, isPending } = transferMutation.useMutation()
- *
- * @example
- * const transferMutation = createMutation(reactor, {
- *   functionName: "transfer",
- *   onCanisterError: (err) => console.error(err.code),
- * })
- *
- * // Outside React (loader/service/script)
- * await transferMutation.execute([{ to: "aaaaa-aa", amount: "1000" }])
- */
-
-import {
-  useMutation,
-  type MutationFunctionContext,
-  type UseMutationOptions,
-} from "@tanstack/react-query"
-import type {
-  Reactor,
-  FunctionName,
-  ReactorArgs,
-  TransformKey,
-  ReactorReturnOk,
-  ReactorReturnErr,
-} from "@ic-reactor/core"
-import { isCanisterError } from "@ic-reactor/core"
-import type {
-  MutationConfig,
-  MutationResult,
-  MutationHookOptions,
-  NoInfer,
-} from "./types.js"
-import { invalidateTargets, useMountQueryClient } from "./utils.js"
-
-// ============================================================================
-// Internal Implementation
-// ============================================================================
-
-const createMutationImpl = <
-  Service,
-  Method extends FunctionName<Service> = FunctionName<Service>,
-  Transform extends TransformKey = "candid",
-  TOnMutateResult = unknown,
->(
-  reactor: Reactor<Service, Transform>,
-  config: MutationConfig<
-    Service,
-    Method,
-    Transform,
-    TOnMutateResult | undefined
-  >
-): MutationResult<Service, Method, Transform> => {
-  type TData = ReactorReturnOk<Service, Method, Transform>
-  type TError = ReactorReturnErr<Service, Method, Transform>
-  type TVariables = ReactorArgs<Service, Method, Transform>
-
-  const {
-    functionName,
-    callConfig,
-    invalidateQueries: factoryInvalidateQueries,
-    onSuccess: factoryOnSuccess,
-    onCanisterError: factoryOnCanisterError,
-    onError: factoryOnError,
-    onMutate: factoryOnMutate,
-    onSettled: factoryOnSettled,
-    ...factoryOptions
-  } = config
-
-  /**
-   * Raw call without any invalidation logic.
-   * Used as mutationFn so that onSuccess handles all post-mutation work
-   * and there is no double-invalidation.
-   */
-  const callFn = (args: TVariables): Promise<TData> =>
-    reactor.callMethod({ functionName, args, callConfig })
-
-  /**
-   * The factory's own `onMutate` result for each call.
-   *
-   * TanStack Query stores one `onMutate` result per mutation and hands it to
-   * every callback. That slot holds the hook's result, which the mutation also
-   * exposes as `context`, so this map holds the factory's. Each key is the
-   * context object TanStack Query creates for a call and passes to every
-   * callback of that call.
-   */
-  const factoryOnMutateResults = new WeakMap<
-    MutationFunctionContext,
-    TOnMutateResult | undefined
-  >()
-
-  /**
-   * The `onMutate` result a factory callback receives. A factory without its
-   * own `onMutate` gets the hook's, as it always has.
-   */
-  const factoryOnMutateResult = (
-    onMutateResult: unknown,
-    context: MutationFunctionContext | undefined
-  ) =>
-    (factoryOnMutate && context
-      ? factoryOnMutateResults.get(context)
-      : onMutateResult) as TOnMutateResult | undefined
-
-  /**
-   * The options a mutation of this factory runs with, on both call paths: the
-   * factory's config, the hook's options on top when there is a hook, and the
-   * callbacks of both levels chained, factory first. `useMutation()` hands
-   * them to TanStack Query's `useMutation`, and `execute()` builds a mutation
-   * from them in the QueryClient's MutationCache.
-   */
-  const mutationOptions = <THookOnMutateResult = unknown>(
-    options?: MutationHookOptions<
-      Service,
-      Method,
-      Transform,
-      THookOnMutateResult
-    >
-  ): UseMutationOptions<TData, TError, TVariables, THookOnMutateResult> => {
-    const {
-      invalidateQueries: hookInvalidateQueries,
-      onCanisterError: hookOnCanisterError,
-      ...restOptions
-    } = options ?? {}
-
-    return {
-      mutationKey: reactor.getQueryOptions({ functionName }).queryKey,
-      ...factoryOptions,
-      ...restOptions,
-      // Use callFn (not execute) to avoid double-invalidation:
-      // factoryInvalidateQueries are handled in onSuccess below.
-      mutationFn: callFn,
-      onSuccess: async (data, variables, onMutateResult, context) => {
-        // 1. Factory-level invalidation
-        await invalidateTargets(reactor, factoryInvalidateQueries, callConfig)
-        // 2. Hook-level invalidation
-        await invalidateTargets(reactor, hookInvalidateQueries, callConfig)
-        // 3. Factory onSuccess
-        await factoryOnSuccess?.(
-          data,
-          variables,
-          factoryOnMutateResult(onMutateResult, context),
-          context
-        )
-        // 4. Hook onSuccess
-        await restOptions.onSuccess?.(data, variables, onMutateResult, context)
-      },
-      onError: async (error, variables, onMutateResult, context) => {
-        if (isCanisterError(error)) {
-          factoryOnCanisterError?.(error, variables)
-          hookOnCanisterError?.(error, variables)
-        }
-        // Awaited in order, like `onSuccess`. TanStack Query holds
-        // `onSettled` and the settled state until this promise resolves, so
-        // an async `onError` must be part of it.
-        await factoryOnError?.(
-          error,
-          variables,
-          factoryOnMutateResult(onMutateResult, context),
-          context
-        )
-        await restOptions.onError?.(error, variables, onMutateResult, context)
-      },
-      // `onMutate` and `onSettled` are composed like `onSuccess`/`onError`
-      // above. They used to arrive through the `...restOptions` spread, so a
-      // hook-level one silently replaced the factory's — factory teardown,
-      // telemetry or logging simply vanished the moment any call site passed
-      // its own, with no warning and no type error. Chaining is what a
-      // reader who has seen `onSuccess` chain already expects.
-      onMutate: async (variables, context) => {
-        if (factoryOnMutate) {
-          const result = await factoryOnMutate(variables, context)
-          if (context) factoryOnMutateResults.set(context, result)
-        }
-        // Without a hook-level `onMutate` this is `undefined`, and
-        // THookOnMutateResult is then `unknown`.
-        return (await restOptions.onMutate?.(
-          variables,
-          context
-        )) as THookOnMutateResult
-      },
-      onSettled: async (data, error, variables, onMutateResult, context) => {
-        await factoryOnSettled?.(
-          data,
-          error,
-          variables,
-          factoryOnMutateResult(onMutateResult, context),
-          context
-        )
-        await restOptions.onSettled?.(
-          data,
-          error,
-          variables,
-          onMutateResult,
-          context
-        )
-      },
-    }
-  }
-
-  /**
-   * Imperative execution for non-React usage.
-   *
-   * Builds the mutation in the QueryClient's MutationCache and runs it, as
-   * TanStack Query's `useMutation` does, with the options the hook path uses
-   * minus the hook's own. It used to call the canister and the factory's
-   * callbacks itself, so the MutationCache never saw it: its global
-   * `onError`, `onSuccess` and `onSettled` did not run, `useIsMutating` did
-   * not count it, and neither the factory's `retry` or `networkMode` nor the
-   * same options in the QueryClient's mutation defaults applied to the call.
-   * The factory's `onMutate` and `onSettled` did not run either.
-   *
-   * Now the factory's chain runs as it does through `useMutation()`:
-   * `onMutate`, then the factory's invalidation and `onSuccess`, or
-   * `onCanisterError` and `onError` on failure, then `onSettled`. Each factory
-   * callback gets the result of the factory's `onMutate` for this call. Only
-   * hook-level callbacks are absent, because there is no hook here to supply
-   * them.
-   *
-   * The QueryClient's mutation defaults apply as well, so a `mutations.retry`
-   * there re-sends a failed call here too. Each retry of an update method is
-   * a new call the canister runs; set `retry` on the factory (`false`, or
-   * `reactorUpdateRetry` to retry only a SysTransient rejection) to decide it
-   * per method.
-   *
-   * It resolves with the method's result. On failure it rejects with the
-   * call's error once the callbacks have run, so `await execute(...)` still
-   * rejects for the caller.
-   *
-   * Use this in route loaders, scripts, or server-side code.
-   */
-  const execute = async (args: TVariables): Promise<TData> => {
-    const { queryClient } = reactor
-    const options = mutationOptions()
-    const { onError } = options
-    // What the factory's `onError` or `onCanisterError` throws, if either
-    // does. execute() has always rejected with it, and a TanStack Query
-    // mutation at the 5.90.2 peer floor does too. Later releases reject with
-    // the call's error and report the thrown one as an unhandled rejection,
-    // which ends a Node script, so it is caught here and rethrown below.
-    let thrownByOnError: { error: unknown } | undefined
-    const mutation = queryClient
-      .getMutationCache()
-      .build<TData, TError, TVariables, unknown>(queryClient, {
-        ...options,
-        onError: async (error, variables, onMutateResult, context) => {
-          try {
-            await onError?.(error, variables, onMutateResult, context)
-          } catch (thrown) {
-            thrownByOnError = { error: thrown }
-          }
-        },
-      })
-    try {
-      return await mutation.execute(args)
-    } catch (error) {
-      throw thrownByOnError ? thrownByOnError.error : error
-    }
-  }
-
-  // Hook implementation
-  const useMutationHook = <THookOnMutateResult = unknown>(
-    options?: MutationHookOptions<
-      Service,
-      Method,
-      Transform,
-      THookOnMutateResult
-    >
-  ) => {
-    useMountQueryClient(reactor.queryClient)
-    return useMutation(mutationOptions(options), reactor.queryClient)
-  }
-
-  return { useMutation: useMutationHook, execute }
-}
-
-// ============================================================================
-// Public Factory Function
-// ============================================================================
-
-export function createMutation<
-  Service,
-  Transform extends TransformKey,
-  Method extends FunctionName<Service> = FunctionName<Service>,
-  TOnMutateResult = unknown,
->(
-  reactor: Reactor<Service, Transform>,
-  // A factory `onError` or `onSettled` gets no `onMutate` result when
-  // `onMutate` throws, so the result can also be `undefined`. `onSuccess`
-  // shares the type argument. It kept the `undefined` from when `execute()`
-  // ran no `onMutate`, although it now always gets a result.
-  config: MutationConfig<
-    NoInfer<Service>,
-    Method,
-    Transform,
-    TOnMutateResult | undefined
-  >
-): MutationResult<Service, Method, Transform> {
-  return createMutationImpl(
-    reactor,
-    config as MutationConfig<
-      Service,
-      Method,
-      Transform,
-      TOnMutateResult | undefined
-    >
-  )
-}

package/src/createQuery.ts

@@ -1,369 +0,0 @@
-/**
- * Query Factory - Generic wrapper for React Query-based canister data
- *
- * Creates unified fetch/hook/invalidate functions for any canister method.
- * Works with any Reactor instance.
- * Use this when the same read operation must work both inside React components
- * and outside React (loaders, actions, services, tests).
- *
- * @example
- * const userQuery = createQuery(todoManager, {
- *   functionName: "get_user",
- *   select: (result) => result.user,
- * })
- *
- * // In component
- * const { data: user } = userQuery.useQuery()
- *
- * @example
- * const userQuery = createQuery(todoManager, { functionName: "get_user", args: ["alice"] })
- *
- * // Outside React (loader/service/script)
- * await userQuery.fetch()
- * const cached = userQuery.getCacheData()
- * await userQuery.invalidate()
- */
-
-import type {
-  Reactor,
-  FunctionName,
-  ReactorArgs,
-  TransformKey,
-} from "@ic-reactor/core"
-import { useMemo } from "react"
-import {
-  QueryKey,
-  useQuery,
-  skipToken,
-  type SkipToken,
-  type UseQueryOptions,
-  type Updater,
-} from "@tanstack/react-query"
-import type {
-  QueryFnData,
-  QueryError,
-  QueryConfig,
-  SkippableQueryConfig,
-  UseQueryWithSelect,
-  QueryResult,
-  QueryFactoryConfig,
-  SkippableQueryFactoryFn,
-  SkippedQuery,
-  NoInfer,
-} from "./types.js"
-import {
-  buildChainedSelect,
-  createBoundedCache,
-  pickFetchOptions,
-  queryCacheControls,
-  retryOption,
-  skippedQueryKey,
-  useMountQueryClient,
-  withQueryFactoryMethods,
-} from "./utils.js"
-
-// ============================================================================
-// Internal Implementation
-// ============================================================================
-
-const createQueryImpl = <
-  Service,
-  Method extends FunctionName<Service> = FunctionName<Service>,
-  Transform extends TransformKey = "candid",
-  Selected = QueryFnData<Service, Method, Transform>,
->(
-  reactor: Reactor<Service, Transform>,
-  // `args` is `skipToken` only for a factory's skipped query, which exposes
-  // nothing but `useQuery`; see createQueryFactory.
-  config: SkippableQueryConfig<Service, Method, Transform, Selected>
-): QueryResult<
-  QueryFnData<Service, Method, Transform>,
-  Selected,
-  QueryError<Service, Method, Transform>
-> => {
-  type TData = QueryFnData<Service, Method, Transform>
-  type TError = QueryError<Service, Method, Transform>
-
-  const {
-    functionName,
-    args,
-    callConfig,
-    staleTime = 5 * 60 * 1000,
-    select,
-    queryKey: customQueryKey,
-    ...rest
-  } = config
-
-  const skipped = args === skipToken
-
-  // `callConfig` goes wherever the hooks send it: to the call and into the
-  // key, so a query of another canister or agent has an entry of its own.
-  const params = {
-    functionName,
-    args: skipped ? undefined : args,
-    queryKey: customQueryKey,
-    callConfig,
-  }
-
-  // What the hook observes: the call, or for a query still waiting for its
-  // args, an entry of its own under the method's key, with nothing to run;
-  // see skippedQueryKey.
-  const queryOptions = () =>
-    skipped
-      ? {
-          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(params)
-
-  const getQueryKey = (): QueryKey =>
-    reactor.generateQueryKey(params, callConfig)
-
-  // Apply config.select to raw data (shared by fetch, getCacheData, and the hook)
-  const applySelect = (raw: TData): Selected =>
-    select ? select(raw) : (raw as unknown as Selected)
-
-  // How the query function runs, shared with the hook; see pickFetchOptions.
-  const fetchOptions = pickFetchOptions(rest)
-
-  /** Cache-first fetch for use in loaders / route preloading. */
-  const fetch = async (): Promise<Selected> => {
-    // Through the reactor rather than straight to the QueryClient: overriding
-    // `fetchQuery` in a Reactor subclass is a documented way to add logic to
-    // every factory fetch.
-    const result = await reactor.fetchQuery(params, fetchOptions)
-    return applySelect(result)
-  }
-
-  /** Fire-and-forget prefetch — warms the cache without blocking. */
-  const prefetch = (): Promise<void> => {
-    const baseOptions = reactor.getQueryOptions(params)
-    // A sign-in or sign-out cancels a prefetch in flight, and TanStack
-    // resolves it all the same: an entry nothing observes was left empty, and
-    // one a mounted query shows still held the previous principal's data
-    // until that query's refetch landed. It now runs again for the principal
-    // signed in, as `fetch()` does. Like `prefetchQuery` it never rejects, so
-    // the CallError for a principal that keeps switching is dropped too.
-    return reactor.clientManager
-      .fetchAcrossIdentitySwitch(() =>
-        reactor.queryClient.prefetchQuery({
-          ...fetchOptions,
-          // An update method's default `retry`; see `Reactor.getQueryRetry`.
-          ...retryOption(fetchOptions.retry, baseOptions.retry),
-          queryKey: baseOptions.queryKey,
-          queryFn: baseOptions.queryFn,
-          staleTime,
-        })
-      )
-      .catch(() => undefined)
-  }
-
-  // The hook publicly exposes the overloaded UseQueryWithSelect signature.
-  // Internally it takes a single broad options object, so we type the
-  // implementation explicitly and cast once to the public overloaded type.
-  type UseQueryHookOptions = Omit<
-    UseQueryOptions<TData, TError, unknown>,
-    "queryKey" | "queryFn"
-  > & { select?: (data: Selected) => unknown }
-
-  const useQueryHook = ((options?: UseQueryHookOptions) => {
-    useMountQueryClient(reactor.queryClient)
-    const baseOptions = queryOptions()
-    // 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 useQuery(
-      {
-        queryKey: baseOptions.queryKey,
-        staleTime,
-        ...rest,
-        ...options,
-        queryFn: baseOptions.queryFn,
-        select: chainedSelect,
-        // The hook's `retry`, else the config's, else an update method's
-        // default; see `Reactor.getQueryRetry`.
-        ...retryOption(options?.retry ?? rest.retry, baseOptions.retry),
-      },
-      reactor.queryClient
-    )
-  }) as UseQueryWithSelect<TData, Selected, TError>
-
-  const invalidate = async (): Promise<void> => {
-    await reactor.queryClient.invalidateQueries({ queryKey: getQueryKey() })
-  }
-
-  const getCacheData = ((
-    selectFn?: (data: Selected) => unknown
-  ): Selected | unknown => {
-    const raw = reactor.getQueryData(params, callConfig)
-    if (raw === undefined) return undefined
-    const selected = applySelect(raw)
-    return selectFn ? selectFn(selected) : selected
-  }) as QueryResult<TData, Selected, TError>["getCacheData"]
-
-  const setData: QueryResult<TData, Selected, TError>["setData"] = (
-    updater
-  ) => {
-    return reactor.queryClient.setQueryData(
-      getQueryKey(),
-      updater as Updater<TData | undefined, TData | undefined>
-    ) as TData | undefined
-  }
-
-  return {
-    fetch,
-    prefetch,
-    useQuery: useQueryHook,
-    invalidate,
-    getQueryKey,
-    getCacheData,
-    setData,
-    ...queryCacheControls<TData>(reactor, getQueryKey),
-  }
-}
-
-// ============================================================================
-// Public Factory Function
-// ============================================================================
-
-export function createQuery<
-  Service,
-  Transform extends TransformKey,
-  Method extends FunctionName<Service> = FunctionName<Service>,
-  Selected = QueryFnData<Service, Method, Transform>,
->(
-  reactor: Reactor<Service, Transform>,
-  config: QueryConfig<NoInfer<Service>, Method, Transform, Selected>
-): QueryResult<
-  QueryFnData<Service, Method, Transform>,
-  Selected,
-  QueryError<Service, Method, Transform>
-> {
-  return createQueryImpl(
-    reactor,
-    config as QueryConfig<Service, Method, Transform, Selected>
-  )
-}
-
-// ============================================================================
-// Convenience: Create query with dynamic args
-// ============================================================================
-
-/**
- * Create a query factory: a function that takes the method's args and returns
- * the query object for them, the same object for the same args.
- *
- * The function also has `getQueryKey()`, the key prefix every query it
- * returns shares, and `invalidate()`, which invalidates all of them whatever
- * their args. Pass the function itself to a mutation's `invalidateQueries` to
- * refresh every instance after the mutation.
- *
- * It also takes TanStack Query's `skipToken` in place of args, for a
- * component whose args are not known yet, and returns a query with only
- * `useQuery()`, which waits without fetching; see
- * {@link SkippableQueryFactoryFn}.
- *
- * @example
- * const getBalance = createQueryFactory(ledger, {
- *   functionName: "icrc1_balance_of",
- * })
- *
- * // In a component
- * const { data } = getBalance([{ owner, subaccount: [] }]).useQuery()
- *
- * // In a component whose owner may not be known yet
- * const { data: maybe } = getBalance(
- *   owner ? [{ owner, subaccount: [] }] : skipToken
- * ).useQuery()
- *
- * // Refetch every account's balance after a transfer
- * const transfer = createMutation(ledger, {
- *   functionName: "icrc1_transfer",
- *   invalidateQueries: [getBalance],
- * })
- */
-export function createQueryFactory<
-  Service,
-  Transform extends TransformKey,
-  Method extends FunctionName<Service> = FunctionName<Service>,
-  Selected = QueryFnData<Service, Method, Transform>,
->(
-  reactor: Reactor<Service, Transform>,
-  config: QueryFactoryConfig<NoInfer<Service>, Method, Transform, Selected>
-): SkippableQueryFactoryFn<
-  ReactorArgs<Service, Method, Transform>,
-  QueryResult<
-    QueryFnData<Service, Method, Transform>,
-    Selected,
-    QueryError<Service, Method, Transform>
-  >
-> {
-  type Query = QueryResult<
-    QueryFnData<Service, Method, Transform>,
-    Selected,
-    QueryError<Service, Method, Transform>
-  >
-
-  const cache = createBoundedCache<Query>()
-
-  // One skipped query per factory, built on first use. Only its hook is
-  // handed out: until the args are known there is no call to make and no
-  // entry of their own to read or write.
-  let skippedQuery: SkippedQuery<Query> | undefined
-
-  function factory(args: ReactorArgs<Service, Method, Transform>): Query
-  function factory(args: SkipToken): SkippedQuery<Query>
-  function factory(
-    args: ReactorArgs<Service, Method, Transform> | SkipToken
-  ): Query | SkippedQuery<Query>
-  function factory(
-    args: ReactorArgs<Service, Method, Transform> | SkipToken
-  ): Query | SkippedQuery<Query> {
-    if (args === skipToken) {
-      skippedQuery ??= {
-        useQuery: createQueryImpl<Service, Method, Transform, Selected>(
-          reactor,
-          { ...config, args: skipToken }
-        ).useQuery,
-      }
-      return skippedQuery
-    }
-
-    const key = reactor.generateQueryKey(
-      { functionName: config.functionName as Method, args },
-      config.callConfig
-    )
-    const cacheKey = JSON.stringify(key)
-
-    const existing = cache.get(cacheKey)
-    if (existing) return existing
-
-    const result = createQueryImpl<Service, Method, Transform, Selected>(
-      reactor,
-      {
-        ...config,
-        args,
-      }
-    )
-    cache.set(cacheKey, result)
-    return result
-  }
-
-  // The method's own prefix, at the canister and agent the config's
-  // `callConfig` names. A config `queryKey` follows the args segment in every
-  // instance's key, so it cannot narrow the prefix.
-  return withQueryFactoryMethods(factory, reactor, () =>
-    reactor.generateQueryKey(
-      { functionName: config.functionName as Method },
-      config.callConfig
-    )
-  )
-}