@ic-reactor/react 3.0.3-beta.4 → 3.0.3

package/src/createMutation.ts

@@ -0,0 +1,173 @@
+/**
+ * Mutation Factory - Generic wrapper for mutating canister data
+ *
+ * Creates unified mutation hooks for any canister method.
+ * Works with any Reactor instance.
+ *
+ * @example
+ * const transferMutation = createMutation(reactor, {
+ *   functionName: "transfer",
+ *   onSuccess: () => console.log("Success!"),
+ * })
+ *
+ * // In component
+ * const { mutate, isPending } = transferMutation.useMutation()
+ */
+
+import { useMutation } from "@tanstack/react-query"
+import type {
+  Reactor,
+  FunctionName,
+  ReactorArgs,
+  TransformKey,
+  ReactorReturnOk,
+} from "@ic-reactor/core"
+import { isCanisterError } from "@ic-reactor/core"
+import type {
+  MutationConfig,
+  MutationResult,
+  MutationHookOptions,
+  NoInfer,
+} from "./types"
+
+// ============================================================================
+// Internal Implementation
+// ============================================================================
+
+const createMutationImpl = <
+  A,
+  M extends FunctionName<A> = FunctionName<A>,
+  T extends TransformKey = "candid",
+>(
+  reactor: Reactor<A, T>,
+  config: MutationConfig<A, M, T>
+): MutationResult<A, M, T> => {
+  const {
+    functionName,
+    callConfig,
+    invalidateQueries: factoryInvalidateQueries,
+    onSuccess: factoryOnSuccess,
+    onCanisterError: factoryOnCanisterError,
+    onError: factoryOnError,
+    ...factoryOptions
+  } = config
+
+  // Direct execution function
+  const execute = async (
+    args: ReactorArgs<A, M, T>
+  ): Promise<ReactorReturnOk<A, M, T>> => {
+    const result = await reactor.callMethod({
+      functionName,
+      args,
+      callConfig,
+    })
+
+    if (factoryInvalidateQueries) {
+      await Promise.all(
+        factoryInvalidateQueries.map((queryKey) => {
+          return reactor.queryClient.invalidateQueries({ queryKey })
+        })
+      )
+    }
+
+    return result
+  }
+
+  // Hook implementation
+  const useMutationHook = (options?: MutationHookOptions<A, M, T>) => {
+    const baseOptions = reactor.getQueryOptions({
+      functionName,
+    })
+    // Extract our custom options
+    const {
+      invalidateQueries: hookInvalidateQueries,
+      onCanisterError: hookOnCanisterError,
+      ...restOptions
+    } = options || {}
+
+    return useMutation(
+      {
+        mutationKey: baseOptions.queryKey,
+        ...factoryOptions,
+        ...restOptions,
+        mutationFn: execute,
+        onSuccess: async (...args) => {
+          // 1. Handle factory-level invalidateQueries
+          if (factoryInvalidateQueries) {
+            await Promise.all(
+              factoryInvalidateQueries.map((queryKey) => {
+                return reactor.queryClient.invalidateQueries({ queryKey })
+              })
+            )
+          }
+
+          // 2. Handle hook-level invalidateQueries
+          if (hookInvalidateQueries) {
+            await Promise.all(
+              hookInvalidateQueries.map((queryKey) => {
+                if (queryKey) {
+                  return reactor.queryClient.invalidateQueries({ queryKey })
+                }
+                return Promise.resolve()
+              })
+            )
+          }
+
+          // 3. Call factory onSuccess
+          if (factoryOnSuccess) {
+            await factoryOnSuccess(...args)
+          }
+
+          // 4. Call hook-local onSuccess
+          if (restOptions?.onSuccess) {
+            await restOptions.onSuccess(...args)
+          }
+        },
+        onError: (error, variables, context, mutation) => {
+          // Check if this is a CanisterError (from Result { Err: E })
+          if (isCanisterError(error)) {
+            // 1. Call factory-level onCanisterError
+            if (factoryOnCanisterError) {
+              factoryOnCanisterError(error, variables)
+            }
+            // 2. Call hook-level onCanisterError
+            if (hookOnCanisterError) {
+              hookOnCanisterError(error, variables)
+            }
+          }
+
+          // 3. Call factory-level onError (for all errors)
+          if (factoryOnError) {
+            factoryOnError(error, variables, context, mutation)
+          }
+
+          // 4. Call hook-level onError (for all errors)
+          if (restOptions?.onError) {
+            restOptions.onError(error, variables, context, mutation)
+          }
+        },
+      },
+      reactor.queryClient
+    )
+  }
+
+  return {
+    useMutation: useMutationHook,
+    execute,
+  }
+}
+
+// ============================================================================
+// Factory Function
+// ============================================================================
+
+export function createMutation<
+  A,
+  T extends TransformKey,
+  M extends FunctionName<A> = FunctionName<A>,
+>(
+  reactor: Reactor<A, T>,
+  config: MutationConfig<NoInfer<A>, M, T>
+): MutationResult<A, M, T> {
+  return createMutationImpl(reactor, config as MutationConfig<A, M, T>)
+}

package/src/createQuery.ts

@@ -0,0 +1,197 @@
+/**
+ * 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.
+ *
+ * @example
+ * const userQuery = createQuery(todoManager, {
+ *   functionName: "get_user",
+ *   select: (result) => result.user,
+ * })
+ *
+ * // In component
+ * const { data: user } = userQuery.useQuery()
+ */
+
+import type {
+  Reactor,
+  FunctionName,
+  ReactorArgs,
+  TransformKey,
+} from "@ic-reactor/core"
+import { QueryKey, useQuery } from "@tanstack/react-query"
+import type {
+  QueryFnData,
+  QueryError,
+  QueryConfig,
+  UseQueryWithSelect,
+  QueryResult,
+  QueryFactoryConfig,
+  NoInfer,
+} from "./types"
+
+// ============================================================================
+// Internal Implementation
+// ============================================================================
+
+const createQueryImpl = <
+  A,
+  M extends FunctionName<A> = FunctionName<A>,
+  T extends TransformKey = "candid",
+  TSelected = QueryFnData<A, M, T>,
+>(
+  reactor: Reactor<A, T>,
+  config: QueryConfig<A, M, T, TSelected>
+): QueryResult<QueryFnData<A, M, T>, TSelected, QueryError<A, M, T>> => {
+  type TData = QueryFnData<A, M, T>
+  type TError = QueryError<A, M, T>
+
+  const {
+    functionName,
+    args,
+    staleTime = 5 * 60 * 1000,
+    select,
+    queryKey: customQueryKey,
+    ...rest
+  } = config
+
+  const params = {
+    functionName,
+    args,
+    queryKey: customQueryKey,
+  }
+
+  // Get query key from actor manager
+  const getQueryKey = (): QueryKey => {
+    return reactor.generateQueryKey(params)
+  }
+
+  // Fetch function for loaders (cache-first)
+  const fetch = async (): Promise<TSelected> => {
+    const result = await reactor.fetchQuery(params)
+    return select ? select(result) : (result as TSelected)
+  }
+
+  // Implementation
+  const useQueryHook: UseQueryWithSelect<TData, TSelected, TError> = (
+    options: any
+  ): any => {
+    const baseOptions = reactor.getQueryOptions(params)
+
+    // Chain the selects: raw -> config.select -> options.select
+    const chainedSelect = (rawData: TData) => {
+      const firstPass = config.select ? config.select(rawData) : rawData
+      if (options?.select) {
+        return options.select(firstPass)
+      }
+      return firstPass
+    }
+    return useQuery(
+      {
+        queryKey: baseOptions.queryKey,
+        staleTime,
+        ...rest,
+        ...options,
+        queryFn: baseOptions.queryFn,
+        select: chainedSelect,
+      },
+      reactor.queryClient
+    )
+  }
+
+  // Invalidate function
+  const invalidate = async (): Promise<void> => {
+    const queryKey = getQueryKey()
+    await reactor.queryClient.invalidateQueries({ queryKey })
+  }
+
+  // Get data from cache without fetching
+  const getCacheData: any = (selectFn?: (data: TData) => any) => {
+    const cachedRawData = reactor.getQueryData(params)
+
+    if (cachedRawData === undefined) {
+      return undefined
+    }
+
+    // Apply config.select to raw cache data
+    const selectedData = (
+      config.select ? config.select(cachedRawData) : cachedRawData
+    ) as TData
+
+    // Apply optional select parameter
+    if (selectFn) {
+      return selectFn(selectedData)
+    }
+
+    return selectedData
+  }
+
+  return {
+    fetch,
+    useQuery: useQueryHook,
+    invalidate,
+    getQueryKey,
+    getCacheData,
+  }
+}
+
+// ============================================================================
+// Factory Function
+// ============================================================================
+
+export function createQuery<
+  A,
+  T extends TransformKey,
+  M extends FunctionName<A> = FunctionName<A>,
+  TSelected = QueryFnData<A, M, T>,
+>(
+  reactor: Reactor<A, T>,
+  config: QueryConfig<NoInfer<A>, M, T, TSelected>
+): QueryResult<QueryFnData<A, M, T>, TSelected, QueryError<A, M, T>> {
+  return createQueryImpl(reactor, config as QueryConfig<A, M, T, TSelected>)
+}
+
+// ============================================================================
+// Convenience: Create query with dynamic args
+// ============================================================================
+
+export function createQueryFactory<
+  A,
+  T extends TransformKey,
+  M extends FunctionName<A> = FunctionName<A>,
+  TSelected = QueryFnData<A, M, T>,
+>(
+  reactor: Reactor<A, T>,
+  config: QueryFactoryConfig<NoInfer<A>, M, T, TSelected>
+): (
+  args: ReactorArgs<A, M, T>
+) => QueryResult<QueryFnData<A, M, T>, TSelected, QueryError<A, M, T>> {
+  const cache = new Map<
+    string,
+    QueryResult<QueryFnData<A, M, T>, TSelected, QueryError<A, M, T>>
+  >()
+
+  return (
+    args: ReactorArgs<A, M, T>
+  ): QueryResult<QueryFnData<A, M, T>, TSelected, QueryError<A, M, T>> => {
+    const key = reactor.generateQueryKey({
+      functionName: config.functionName as M,
+      args,
+    })
+    const cacheKey = JSON.stringify(key)
+
+    if (cache.has(cacheKey)) {
+      return cache.get(cacheKey)!
+    }
+
+    const result = createQueryImpl<A, M, T, TSelected>(reactor, {
+      ...config,
+      args,
+    })
+
+    cache.set(cacheKey, result)
+
+    return result
+  }
+}