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

package/src/types.ts

@@ -1,499 +0,0 @@
-/**
- * Shared type definitions for query factories (createActorQuery, createActorSuspenseQuery, etc.)
- */
-
-import type {
-  FunctionName,
-  ReactorReturnOk,
-  ReactorQueryData,
-  ReactorReturnErr,
-  ReactorArgs,
-  BaseActor,
-  TransformKey,
-  TransformReturnRegistry,
-  ErrResult,
-  ActorMethodReturnType,
-} from "@ic-reactor/core"
-import { CanisterError } from "@ic-reactor/core"
-import { CallConfig } from "@icp-sdk/core/agent"
-import {
-  QueryKey,
-  QueryObserverOptions,
-  UseQueryOptions,
-  UseQueryResult,
-  UseSuspenseQueryOptions,
-  UseSuspenseQueryResult,
-  UseMutationOptions,
-  UseMutationResult,
-} from "@tanstack/react-query"
-
-// ============================================================================
-// Utility Types
-// ============================================================================
-
-// NoInfer prevents TypeScript from inferring a type parameter from a particular position
-// This is available in TypeScript 5.4+ natively, but we define it for compatibility
-export type NoInfer<T> = [T][T extends any ? 0 : never]
-// ============================================================================
-// Base Query Data Types
-// ============================================================================
-
-/** The raw data type returned by the query function (before select) */
-export type QueryFnData<
-  Service = BaseActor,
-  Method extends FunctionName<Service> = FunctionName<Service>,
-  Transform extends TransformKey = "candid",
-> = ReactorQueryData<ReactorReturnOk<Service, Method, Transform>>
-
-/** The error type for queries */
-export type QueryError<
-  Service = BaseActor,
-  Method extends FunctionName<Service> = FunctionName<Service>,
-  Transform extends TransformKey = "candid",
-> = ReactorReturnErr<Service, Method, Transform>
-
-// ============================================================================
-// Base Query Configuration
-// ============================================================================
-
-/**
- * Base configuration for query wrappers (shared between regular and suspense).
- *
- * @template Service - The actor interface type
- * @template Method - The method name on the actor
- * @template Transform - The transformation key (identity, display, etc.)
- * @template Selected - The type returned after select transformation
- */
-export interface BaseQueryConfig<
-  Service = BaseActor,
-  Method extends FunctionName<Service> = FunctionName<Service>,
-  Transform extends TransformKey = "candid",
-  Selected = QueryFnData<Service, Method, Transform>,
-> extends Omit<
-  QueryObserverOptions<
-    QueryFnData<Service, Method, Transform>,
-    ReactorReturnErr<Service, Method, Transform>,
-    Selected,
-    QueryFnData<Service, Method, Transform>,
-    QueryKey
-  >,
-  "queryFn" | "queryKey"
-> {
-  /** The method to call on the canister */
-  functionName: Method
-  /** Arguments to pass to the method (if any) */
-  args?: ReactorArgs<Service, Method, Transform>
-  /** The query key to use for this query */
-  queryKey?: QueryKey
-  /** How long data stays fresh before refetching (default: 5 min) */
-  staleTime?: number
-  /** Transform the raw result before returning */
-  select?: (data: QueryFnData<Service, Method, Transform>) => Selected
-}
-
-/**
- * Configuration for createQuery (regular useQuery).
- * Alias for BaseQueryConfig for clarity.
- */
-export type QueryConfig<
-  Service = BaseActor,
-  Method extends FunctionName<Service> = FunctionName<Service>,
-  Transform extends TransformKey = "candid",
-  Selected = QueryFnData<Service, Method, Transform>,
-> = BaseQueryConfig<Service, Method, Transform, Selected>
-
-/**
- * Configuration for createSuspenseQuery (useSuspenseQuery).
- * Alias for BaseQueryConfig for clarity.
- */
-export type SuspenseQueryConfig<
-  Service = BaseActor,
-  Method extends FunctionName<Service> = FunctionName<Service>,
-  Transform extends TransformKey = "candid",
-  Selected = QueryFnData<Service, Method, Transform>,
-> = BaseQueryConfig<Service, Method, Transform, Selected>
-
-// ============================================================================
-// Factory Configuration (without args)
-// ============================================================================
-
-/**
- * Configuration for createQueryFactory (args are provided at call time).
- */
-export type QueryFactoryConfig<
-  Service = BaseActor,
-  Method extends FunctionName<Service> = FunctionName<Service>,
-  Transform extends TransformKey = "candid",
-  Selected = QueryFnData<Service, Method, Transform>,
-> = Omit<QueryConfig<Service, Method, Transform, Selected>, "args">
-
-/**
- * Configuration for createSuspenseQueryFactory (args are provided at call time).
- */
-export type SuspenseQueryFactoryConfig<
-  Service = BaseActor,
-  Method extends FunctionName<Service> = FunctionName<Service>,
-  Transform extends TransformKey = "candid",
-  Selected = QueryFnData<Service, Method, Transform>,
-> = Omit<SuspenseQueryConfig<Service, Method, Transform, Selected>, "args">
-
-// ============================================================================
-// Hook Interfaces with Chained Select Support
-// ============================================================================
-
-/**
- * useQuery hook with chained select support.
- * - Without select: returns TSelected (from config.select)
- * - With select: chains on top and returns TFinal
- *
- * Accepts all useQuery options from React Query documentation.
- * Select is special: it chains on top of config.select.
- */
-export interface UseQueryWithSelect<
-  TQueryFnData,
-  TSelected = TQueryFnData,
-  TError = Error,
-> {
-  // Overload 1: Without select - returns TSelected
-  // Note: select is included as optional (never type) to enable autocomplete suggestions
-  (
-    options?: Omit<
-      UseQueryOptions<TQueryFnData, TError, TSelected>,
-      "queryKey" | "queryFn"
-    > & {
-      select?: undefined
-    }
-  ): UseQueryResult<TSelected, TError>
-
-  // Overload 2: With select - chains on top of config.select and returns TFinal
-  <TFinal = TSelected>(
-    options: Omit<
-      UseQueryOptions<TQueryFnData, TError, TFinal>,
-      "queryKey" | "queryFn" | "select"
-    > & {
-      select: (data: TSelected) => TFinal
-    }
-  ): UseQueryResult<TFinal, TError>
-}
-
-/**
- * useSuspenseQuery hook with chained select support.
- * - Without select: returns TSelected (from config.select)
- * - With select: chains on top and returns TFinal
- *
- * Accepts all useSuspenseQuery options from React Query documentation.
- * Select is special: it chains on top of config.select.
- * Data is always defined (never undefined).
- * Does NOT support `enabled` option.
- */
-export interface UseSuspenseQueryWithSelect<
-  TQueryFnData,
-  TSelected = TQueryFnData,
-  TError = Error,
-> {
-  // Overload 1: Without select - returns TSelected
-  // Note: select is included as optional (never type) to enable autocomplete suggestions
-  (
-    options?: Omit<
-      UseSuspenseQueryOptions<TQueryFnData, TError, TSelected>,
-      "queryKey" | "queryFn"
-    > & {
-      select?: undefined
-    }
-  ): UseSuspenseQueryResult<TSelected, TError>
-
-  // Overload 2: With select - chains on top of config.select and returns TFinal
-  <TFinal = TSelected>(
-    options: Omit<
-      UseSuspenseQueryOptions<TQueryFnData, TError, TFinal>,
-      "queryKey" | "queryFn" | "select"
-    > & {
-      select: (data: TSelected) => TFinal
-    }
-  ): UseSuspenseQueryResult<TFinal, TError>
-}
-
-// ============================================================================
-// Result Interfaces
-// ============================================================================
-
-/**
- * Base result interface shared between createQuery and createSuspenseQuery.
- *
- * @template TQueryFnData - The raw data type
- * @template TSelected - The type after select transformation
- * @template TError - The error type
- */
-export interface BaseQueryResult<
-  TQueryFnData,
-  TSelected = TQueryFnData,
-  _TError = Error,
-> {
-  /** Fetch data in loader (uses ensureQueryData for cache-first) */
-  fetch: () => Promise<TSelected>
-
-  /**
-   * Eagerly prefetch data into the cache without blocking.
-   * Useful for preloading data before navigating to a route.
-   *
-   * Unlike `fetch()`, this returns a void promise so it can be fire-and-forget.
-   *
-   * @example
-   * // In a route hover handler
-   * button.addEventListener("mouseenter", () => userQuery.prefetch())
-   */
-  prefetch: () => Promise<void>
-
-  /** Invalidate the cache (refetches if query is active) */
-  invalidate: () => Promise<void>
-
-  /** Get query key (for advanced React Query usage) */
-  getQueryKey: () => QueryKey
-
-  /**
-   * Read data directly from cache without fetching.
-   * Returns undefined if data is not in cache.
-   *
-   * @template TFinal - Type returned after optional select transformation
-   * @param select - Optional select function to transform cached data further
-   * @returns Cached data with select applied, or undefined if not in cache
-   *
-   * @example
-   * // Just get the cached data
-   * const user = userQuery.getCacheData()
-   *
-   * // With additional select transformation
-   * const name = userQuery.getCacheData((user) => user.name)
-   */
-  getCacheData: {
-    (): TSelected | undefined
-    <TFinal>(select: (data: TSelected) => TFinal): TFinal | undefined
-  }
-
-  /**
-   * Write raw data directly into the cache (useful for optimistic updates).
-   * Accepts a new value or an updater function that receives the current cached raw data.
-   *
-   * Note: The value is stored as raw (pre-select) data.  Any active `select`
-   * transformations are automatically re-applied by React Query on the next render.
-   *
-   * @example
-   * // Optimistic update before a mutation
-   * userQuery.setData({ id: "1", name: "Alice" })
-   *
-   * // Functional update
-   * counterQuery.setData((prev) => (prev ?? 0) + 1)
-   */
-  setData: (
-    updater:
-      | TQueryFnData
-      | ((old: TQueryFnData | undefined) => TQueryFnData | undefined)
-  ) => TQueryFnData | undefined
-}
-
-/**
- * Result from createQuery
- *
- * Includes useQuery hook that:
- * - Supports `enabled` option for conditional fetching
- * - Data may be `undefined` during loading
- * - Uses regular `useQuery` with manual loading state handling
- *
- * @template TQueryFnData - The raw data type
- * @template TSelected - The type after select transformation
- * @template TError - The error type
- */
-export interface QueryResult<
-  TQueryFnData,
-  TSelected = TQueryFnData,
-  TError = Error,
-> extends BaseQueryResult<TQueryFnData, TSelected, TError> {
-  /** React hook for components - supports chained select and enabled option */
-  useQuery: UseQueryWithSelect<TQueryFnData, TSelected, TError>
-}
-
-/**
- * Result from createSuspenseQuery
- *
- * Includes useSuspenseQuery hook that:
- * - Requires wrapping in <Suspense> boundary
- * - Data is always defined (no undefined checks)
- * - Does NOT support `enabled` option
- *
- * @template TQueryFnData - The raw data type
- * @template TSelected - The type after select transformation
- * @template TError - The error type
- */
-export interface SuspenseQueryResult<
-  TQueryFnData,
-  TSelected = TQueryFnData,
-  TError = Error,
-> extends BaseQueryResult<TQueryFnData, TSelected, TError> {
-  /** React hook for components - data is always defined (wrap in Suspense) */
-  useSuspenseQuery: UseSuspenseQueryWithSelect<TQueryFnData, TSelected, TError>
-}
-
-// ============================================================================
-// Actor Mutation Types
-// ============================================================================
-
-/**
- * Configuration for createMutation and useActorMutation.
- *
- * @template TOnMutateResult - The value `onMutate` returns, which `onSuccess`,
- * `onError` and `onSettled` receive. TypeScript infers it from `onMutate`.
- */
-export interface MutationConfig<
-  Service = BaseActor,
-  Method extends FunctionName<Service> = FunctionName<Service>,
-  Transform extends TransformKey = "candid",
-  TOnMutateResult = unknown,
-> extends Omit<
-  UseMutationOptions<
-    ReactorReturnOk<Service, Method, Transform>,
-    ReactorReturnErr<Service, Method, Transform>,
-    ReactorArgs<Service, Method, Transform>,
-    TOnMutateResult
-  >,
-  "mutationFn"
-> {
-  /** The method to call on the canister */
-  functionName: Method
-  /** Call configuration for the actor method */
-  callConfig?: CallConfig
-  /**
-   * Queries to invalidate upon successful mutation.
-   *
-   * `undefined` entries are skipped, so the common
-   * `[maybeQuery?.getQueryKey()]` idiom is safe when the optional query object
-   * is absent.
-   */
-  invalidateQueries?: (QueryKey | undefined)[]
-  /**
-   * Callback for canister-level business logic errors.
-   * Called when the canister returns a Result { Err: E } variant.
-   *
-   * This is separate from `onError` which handles all errors including
-   * network failures, agent errors, etc.
-   *
-   * @param error - The CanisterError containing the typed error value
-   * @param variables - The arguments passed to the mutation
-   *
-   * @example
-   * ```typescript
-   * createMutation(reactor, {
-   *   functionName: "transfer",
-   *   onCanisterError: (error, variables) => {
-   *     // error.err contains the typed Err value
-   *     // error.code contains the variant key (e.g., "InsufficientFunds")
-   *     console.error(`Transfer failed: ${error.code}`, error.err)
-   *   },
-   * })
-   * ```
-   */
-  onCanisterError?: (
-    error: CanisterError<
-      TransformReturnRegistry<
-        ErrResult<ActorMethodReturnType<Service[Method]>>,
-        Service
-      >[Transform]
-    >,
-    variables: ReactorArgs<Service, Method, Transform>
-  ) => void
-}
-
-/**
- * Configuration for createMutationFactory.
- */
-export type MutationFactoryConfig<
-  Service = BaseActor,
-  Method extends FunctionName<Service> = FunctionName<Service>,
-  Transform extends TransformKey = "candid",
-  TOnMutateResult = unknown,
-> = Omit<
-  MutationConfig<Service, Method, Transform, TOnMutateResult>,
-  "onSuccess"
->
-
-/**
- * Options for useMutation hook.
- * Extends React Query's UseMutationOptions with invalidateQueries support.
- *
- * @template TOnMutateResult - The value `onMutate` returns, which `onSuccess`,
- * `onError` and `onSettled` receive. TypeScript infers it from `onMutate`.
- */
-export interface MutationHookOptions<
-  Service = BaseActor,
-  Method extends FunctionName<Service> = FunctionName<Service>,
-  Transform extends TransformKey = "candid",
-  TOnMutateResult = unknown,
-> extends Omit<
-  UseMutationOptions<
-    ReactorReturnOk<Service, Method, Transform>,
-    ReactorReturnErr<Service, Method, Transform>,
-    ReactorArgs<Service, Method, Transform>,
-    TOnMutateResult
-  >,
-  "mutationFn"
-> {
-  /**
-   * Query keys to invalidate upon successful mutation.
-   * Use query.getQueryKey() to get the key from a query result.
-   *
-   * @example
-   * const balanceQuery = getIcpBalance(account)
-   * useMutation({
-   *   invalidateQueries: [balanceQuery.getQueryKey()],
-   * })
-   */
-  invalidateQueries?: (QueryKey | undefined)[]
-  /**
-   * Callback for canister-level business logic errors.
-   * Called when the canister returns a Result { Err: E } variant.
-   *
-   * @param error - The CanisterError containing the typed error value
-   * @param variables - The arguments passed to the mutation
-   */
-  onCanisterError?: (
-    error: CanisterError<
-      TransformReturnRegistry<
-        ErrResult<ActorMethodReturnType<Service[Method]>>,
-        Service
-      >[Transform]
-    >,
-    variables: ReactorArgs<Service, Method, Transform>
-  ) => void
-}
-
-/**
- * Result from createMutation.
- */
-export interface MutationResult<
-  Service = BaseActor,
-  Method extends FunctionName<Service> = FunctionName<Service>,
-  Transform extends TransformKey = "candid",
-> {
-  /**
-   * React hook for the mutation.
-   * Accepts options to override/extend the factory config.
-   *
-   * @example
-   * // With invalidateQueries to auto-update balance after transfer
-   * const { mutate } = icpTransferMutation.useMutation({
-   *   invalidateQueries: [userBalanceQuery], // Auto-invalidate after success!
-   * })
-   */
-  useMutation: <TOnMutateResult = unknown>(
-    options?: MutationHookOptions<Service, Method, Transform, TOnMutateResult>
-  ) => UseMutationResult<
-    ReactorReturnOk<Service, Method, Transform>,
-    ReactorReturnErr<Service, Method, Transform>,
-    ReactorArgs<Service, Method, Transform>,
-    TOnMutateResult
-  >
-
-  /** Execute the update call directly (outside of React) */
-  execute: (
-    args: ReactorArgs<Service, Method, Transform>
-  ) => Promise<ReactorReturnOk<Service, Method, Transform>>
-}

package/src/utils.ts

@@ -1,121 +0,0 @@
-/**
- * Shared internal utilities for query and mutation factories.
- */
-
-import type { QueryKey } from "@tanstack/react-query"
-import type { ReactorQueryData } from "@ic-reactor/core"
-import { generateKey } from "@ic-reactor/core"
-
-/**
- * Internal query-key segment used to distinguish per-call factory args
- * from the base query key. Not part of the public API.
- */
-export const FACTORY_KEY_ARGS_QUERY_KEY = "__ic_reactor_factory_key_args"
-
-/** Convert a direct reactor result into a value TanStack Query can cache. */
-export const normalizeQueryData = <T>(value: T): ReactorQueryData<T> =>
-  (value === undefined ? null : value) as ReactorQueryData<T>
-
-/**
- * Merge a base query key, optional per-call query key, and optional key-args
- * into a single query key array.
- *
- * Used by createInfiniteQueryFactory and createSuspenseInfiniteQueryFactory to
- * ensure each unique set of factory args produces a distinct cache entry.
- */
-export function mergeFactoryQueryKey(
-  baseQueryKey?: QueryKey,
-  callQueryKey?: QueryKey,
-  keyArgs?: unknown
-): QueryKey | undefined {
-  const merged: unknown[] = []
-
-  if (baseQueryKey) merged.push(...baseQueryKey)
-  if (callQueryKey) merged.push(...callQueryKey)
-  if (keyArgs !== undefined) {
-    // Serialize keyArgs through generateKey so BigInt values (and other
-    // non-JSON-serializable Candid types such as Principal) are safely
-    // converted to strings before React Query hashes the key.
-    const safeKeyArgs = generateKey(
-      Array.isArray(keyArgs) ? keyArgs : [keyArgs]
-    )
-    merged.push({ [FACTORY_KEY_ARGS_QUERY_KEY]: safeKeyArgs })
-  }
-
-  return merged.length > 0 ? merged : undefined
-}
-
-/**
- * Build a chained select that applies the config-level select (if any) and then
- * the hook-level select (if any).
- *
- * Returns the caller's own function untouched when only one of the two is
- * present, and `undefined` when neither is — allocating a wrapper only for the
- * genuinely chained case. Identity matters here: `QueryObserver` memoizes a
- * select result on `options.select === previousSelectFn`, so a wrapper rebuilt
- * on every render defeats that check. The select then re-runs each render, and
- * for a select returning a non-plain value (a `Map`, a `Date`, a `Principal`)
- * `replaceEqualDeep` cannot structurally share the result either, so `data`
- * gets a fresh reference every render and a `useEffect([data])` that sets state
- * becomes an unbounded loop.
- *
- * Callers should still memoize the result, since the chained case allocates.
- */
-export function buildChainedSelect<TData, TSelected, TFinal = TSelected>(
-  configSelect: ((data: TData) => TSelected) | undefined,
-  hookSelect: ((data: TSelected) => TFinal) | undefined
-): ((rawData: TData) => TSelected | TFinal) | undefined {
-  if (!configSelect) {
-    // `hookSelect` receives the raw data when there is no config-level select,
-    // matching the previous behaviour.
-    return hookSelect as unknown as
-      ((rawData: TData) => TSelected | TFinal) | undefined
-  }
-  if (!hookSelect) return configSelect
-  return (rawData: TData) => hookSelect(configSelect(rawData))
-}
-
-/**
- * How many memoized query objects an args-late factory keeps.
- *
- * The memo exists so `getBalance(sameArgs)` returns the same object twice; it
- * was unbounded, so an open-ended argument space — a per-principal balance in a
- * long-lived SPA, a search-as-you-type filter, a cursor-keyed list — grew it
- * forever (measured at ~2.9 kB per entry, 55.8 MB for 20k). A few hundred
- * covers any realistic working set while capping the worst case.
- */
-const FACTORY_CACHE_LIMIT = 256
-
-/**
- * Smallest useful LRU: a `Map` already iterates in insertion order, so
- * re-inserting on read is enough to track recency.
- *
- * Eviction is safe — it costs memoization, never correctness. A query object is
- * a closure over the reactor and config, so one rebuilt after eviction behaves
- * identically; only its reference identity differs.
- */
-export function createBoundedCache<V>(limit: number = FACTORY_CACHE_LIMIT) {
-  const entries = new Map<string, V>()
-
-  return {
-    get(key: string): V | undefined {
-      const value = entries.get(key)
-      if (value === undefined) return undefined
-      // Touch: move to the most-recent end.
-      entries.delete(key)
-      entries.set(key, value)
-      return value
-    },
-    set(key: string, value: V): void {
-      if (entries.has(key)) entries.delete(key)
-      else if (entries.size >= limit) {
-        const oldest = entries.keys().next().value
-        if (oldest !== undefined) entries.delete(oldest)
-      }
-      entries.set(key, value)
-    },
-    get size(): number {
-      return entries.size
-    },
-  }
-}