@ic-reactor/react 3.0.0-beta.8 → 3.0.0

package/dist/hooks/useActorSuspenseInfiniteQuery.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useActorSuspenseInfiniteQuery.d.ts","sourceRoot":"","sources":["../../src/hooks/useActorSuspenseInfiniteQuery.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"useActorSuspenseInfiniteQuery.d.ts","sourceRoot":"","sources":["../../src/hooks/useActorSuspenseInfiniteQuery.ts"],"names":[],"mappings":"AACA,OAAO,EACL,QAAQ,EAER,8BAA8B,EAC9B,+BAA+B,EAC/B,YAAY,EACb,MAAM,uBAAuB,CAAA;AAC9B,OAAO,EACL,YAAY,EACZ,OAAO,EACP,YAAY,EACZ,WAAW,EACX,eAAe,EACf,gBAAgB,EACjB,MAAM,kBAAkB,CAAA;AACzB,OAAO,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAA;AAEhD;;;GAGG;AACH,MAAM,WAAW,uCAAuC,CACtD,CAAC,EACD,CAAC,SAAS,YAAY,CAAC,CAAC,CAAC,EACzB,CAAC,SAAS,YAAY,GAAG,QAAQ,EACjC,UAAU,GAAG,OAAO,EACpB,SAAS,GAAG,YAAY,CAAC,eAAe,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,UAAU,CAAC,CAC9D,SAAQ,IAAI,CACZ,+BAA+B,CAC7B,eAAe,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EACxB,gBAAgB,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EACzB,SAAS,EACT,QAAQ,EACR,UAAU,CACX,EACD,UAAU,GAAG,SAAS,GAAG,kBAAkB,GAAG,kBAAkB,CACjE;IACC,mDAAmD;IACnD,OAAO,EAAE,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC,CAAA;IACtB,8CAA8C;IAC9C,YAAY,EAAE,CAAC,CAAA;IACf,+CAA+C;IAC/C,OAAO,EAAE,CAAC,SAAS,EAAE,UAAU,KAAK,WAAW,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAA;IACxD,2DAA2D;IAC3D,UAAU,CAAC,EAAE,UAAU,CAAA;IACvB,wDAAwD;IACxD,QAAQ,CAAC,EAAE,QAAQ,CAAA;IACnB,6BAA6B;IAC7B,gBAAgB,EAAE,UAAU,CAAA;IAC5B,gDAAgD;IAChD,gBAAgB,EAAE,CAChB,QAAQ,EAAE,eAAe,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAClC,QAAQ,EAAE,eAAe,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,EACpC,aAAa,EAAE,UAAU,EACzB,aAAa,EAAE,UAAU,EAAE,KACxB,UAAU,GAAG,SAAS,GAAG,IAAI,CAAA;CACnC;AAED,MAAM,MAAM,mCAAmC,CAC7C,CAAC,EACD,CAAC,SAAS,YAAY,CAAC,CAAC,CAAC,EACzB,CAAC,SAAS,YAAY,GAAG,QAAQ,EACjC,UAAU,GAAG,OAAO,IAClB,IAAI,CACN,uCAAuC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,UAAU,CAAC,EAC5D,SAAS,CACV,CAAA;AAED,MAAM,MAAM,mCAAmC,CAC7C,CAAC,EACD,CAAC,SAAS,YAAY,CAAC,CAAC,CAAC,EACzB,CAAC,SAAS,YAAY,GAAG,QAAQ,EACjC,UAAU,GAAG,OAAO,IAClB,8BAA8B,CAChC,YAAY,CAAC,eAAe,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,UAAU,CAAC,EAClD,gBAAgB,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAC1B,CAAA;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,6BAA6B,GACxC,CAAC,EACD,CAAC,SAAS,YAAY,CAAC,CAAC,CAAC,EACzB,CAAC,SAAS,YAAY,GAAG,QAAQ,EACjC,UAAU,GAAG,OAAO,EACpB,sEAOC,uCAAuC,CACxC,CAAC,EACD,CAAC,EACD,CAAC,EACD,UAAU,CACX,KAAG,mCAAmC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,UAAU,CA4B1D,CAAA"}

package/dist/hooks/useActorSuspenseInfiniteQuery.js.map

@@ -1 +1 @@
-{"version":3,"file":"useActorSuspenseInfiniteQuery.js","sourceRoot":"","sources":["../../src/hooks/useActorSuspenseInfiniteQuery.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,OAAO,CAAA;AAC5C,OAAO,EAEL,wBAAwB,GAGzB,MAAM,uBAAuB,CAAA;AAkE9B;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,6BAA6B,GAAG,CAK3C,EACA,OAAO,EACP,YAAY,EACZ,OAAO,EACP,UAAU,EACV,QAAQ,EACR,GAAG,OAAO,EAMX,EAA4D,EAAE;IAC7D,0DAA0D;IAC1D,MAAM,YAAY,GAAG,OAAO,CAC1B,GAAG,EAAE,CAAC,QAAQ,IAAI,OAAO,CAAC,gBAAgB,CAAC,EAAE,YAAY,EAAE,CAAC,EAC5D,CAAC,QAAQ,EAAE,OAAO,EAAE,YAAY,CAAC,CAClC,CAAA;IAED,wDAAwD;IACxD,MAAM,OAAO,GAAG,WAAW,CACzB,KAAK,EAAE,EAAE,SAAS,EAA6B,EAAE,EAAE;QACjD,MAAM,IAAI,GAAG,OAAO,CAAC,SAAS,CAAC,CAAA;QAC/B,OAAO,OAAO,CAAC,UAAU,CAAC;YACxB,YAAY;YACZ,IAAI;YACJ,UAAU;SACX,CAAC,CAAA;IACJ,CAAC,EACD,CAAC,OAAO,EAAE,YAAY,EAAE,OAAO,EAAE,UAAU,CAAC,CAC7C,CAAA;IAED,OAAO,wBAAwB,CAC7B;QACE,QAAQ,EAAE,YAAY;QACtB,OAAO;QACP,GAAG,OAAO;KACJ,EACR,OAAO,CAAC,WAAW,CACwC,CAAA;AAC/D,CAAC,CAAA"}
+{"version":3,"file":"useActorSuspenseInfiniteQuery.js","sourceRoot":"","sources":["../../src/hooks/useActorSuspenseInfiniteQuery.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,OAAO,CAAA;AAC5C,OAAO,EAEL,wBAAwB,GAIzB,MAAM,uBAAuB,CAAA;AAwE9B;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,6BAA6B,GAAG,CAK3C,EACA,OAAO,EACP,YAAY,EACZ,OAAO,EACP,UAAU,EACV,QAAQ,EACR,GAAG,OAAO,EAMX,EAA4D,EAAE;IAC7D,0DAA0D;IAC1D,MAAM,YAAY,GAAG,OAAO,CAC1B,GAAG,EAAE,CAAC,QAAQ,IAAI,OAAO,CAAC,gBAAgB,CAAC,EAAE,YAAY,EAAE,CAAC,EAC5D,CAAC,QAAQ,EAAE,OAAO,EAAE,YAAY,CAAC,CAClC,CAAA;IAED,wDAAwD;IACxD,MAAM,OAAO,GAAG,WAAW,CACzB,KAAK,EAAE,EAAE,SAAS,EAA6B,EAAE,EAAE;QACjD,MAAM,IAAI,GAAG,OAAO,CAAC,SAAS,CAAC,CAAA;QAC/B,OAAO,OAAO,CAAC,UAAU,CAAC;YACxB,YAAY;YACZ,IAAI;YACJ,UAAU;SACX,CAAC,CAAA;IACJ,CAAC,EACD,CAAC,OAAO,EAAE,YAAY,EAAE,OAAO,EAAE,UAAU,CAAC,CAC7C,CAAA;IAED,OAAO,wBAAwB,CAC7B;QACE,QAAQ,EAAE,YAAY;QACtB,OAAO;QACP,GAAG,OAAO;KACJ,EACR,OAAO,CAAC,WAAW,CACwC,CAAA;AAC/D,CAAC,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ic-reactor/react",
-  "version": "3.0.0-beta.8",
+  "version": "3.0.0",
   "description": "IC Reactor React Library",
   "main": "dist/index.js",
   "module": "dist/index.js",
@@ -16,6 +16,7 @@
   },
   "files": [
     "dist",
+    "src",
     "README.md"
   ],
   "repository": {
@@ -41,7 +42,7 @@
   "author": "Behrad Deylami",
   "license": "MIT",
   "dependencies": {
-    "@ic-reactor/core": "^3.0.0-beta.8"
+    "@ic-reactor/core": "^3.0.0"
   },
   "peerDependencies": {
     "react": ">=18.0.0",
@@ -55,15 +56,15 @@
     "@tanstack/react-query": "^5.90",
     "@testing-library/dom": "^10.4.1",
     "@testing-library/jest-dom": "^6.9.1",
-    "@testing-library/react": "^16.3.1",
-    "@types/react": "^19.2.7",
+    "@testing-library/react": "^16.3.2",
+    "@types/react": "^19.2.10",
     "@types/react-dom": "^19.2.3",
     "fake-indexeddb": "^6.2.5",
-    "jsdom": "^27.4.0",
+    "jsdom": "^28.0.0",
     "react": "^19.2.3",
     "react-dom": "^19.2.3",
     "size-limit": "^12.0.0",
-    "vitest": "^4.0.16"
+    "vitest": "^4.0.17"
   },
   "size-limit": [
     {

package/src/createActorHooks.ts

@@ -0,0 +1,146 @@
+/**
+ * Actor Hooks Factory - Creates a full set of React hooks for a reactor instance.
+ *
+ * This is the primary entry point for using the library in React applications.
+ * It generates type-safe hooks for:
+ * - Queries (useActorQuery)
+ * - Suspense Queries (useActorSuspenseQuery)
+ * - Infinite Queries (useActorInfiniteQuery)
+ * - Suspense Infinite Queries (useActorSuspenseInfiniteQuery)
+ * - Mutations (useActorMutation)
+ *
+ * @example
+ * const { useActorQuery, useActorMutation } = createActorHooks(reactor)
+ *
+ * // In component
+ * const { data } = useActorQuery({ functionName: 'get_user' })
+ * const { mutate } = useActorMutation({ functionName: 'update_user' })
+ */
+import {
+  Reactor,
+  DisplayReactor,
+  ReactorReturnErr,
+  ReactorReturnOk,
+  BaseActor,
+  FunctionName,
+  TransformKey,
+} from "@ic-reactor/core"
+import {
+  UseQueryResult,
+  UseSuspenseQueryResult,
+  UseInfiniteQueryResult,
+  UseSuspenseInfiniteQueryResult,
+  UseMutationResult,
+  InfiniteData,
+} from "@tanstack/react-query"
+import { createQuery } from "./createQuery"
+import { createSuspenseQuery } from "./createSuspenseQuery"
+import { createInfiniteQuery, InfiniteQueryConfig } from "./createInfiniteQuery"
+import {
+  createSuspenseInfiniteQuery,
+  SuspenseInfiniteQueryConfig,
+} from "./createSuspenseInfiniteQuery"
+import { createMutation } from "./createMutation"
+import {
+  useActorMethod,
+  UseActorMethodParameters,
+} from "./hooks/useActorMethod"
+import { QueryConfig, SuspenseQueryConfig, MutationConfig } from "./types"
+
+export type ActorHooks<A, T extends TransformKey> = {
+  useActorQuery: {
+    <M extends FunctionName<A>>(
+      config: QueryConfig<A, M, T, ReactorReturnOk<A, M, T>>
+    ): UseQueryResult<ReactorReturnOk<A, M, T>, ReactorReturnErr<A, M, T>>
+    <M extends FunctionName<A>, TData>(
+      config: QueryConfig<A, M, T, TData>
+    ): UseQueryResult<TData, ReactorReturnErr<A, M, T>>
+  }
+
+  useActorSuspenseQuery: {
+    <M extends FunctionName<A>>(
+      config: SuspenseQueryConfig<A, M, T, ReactorReturnOk<A, M, T>>
+    ): UseSuspenseQueryResult<
+      ReactorReturnOk<A, M, T>,
+      ReactorReturnErr<A, M, T>
+    >
+    <M extends FunctionName<A>, TData>(
+      config: SuspenseQueryConfig<A, M, T, TData>
+    ): UseSuspenseQueryResult<TData, ReactorReturnErr<A, M, T>>
+  }
+
+  useActorInfiniteQuery: <M extends FunctionName<A>, TPageParam = unknown>(
+    config: InfiniteQueryConfig<A, M, T, TPageParam>
+  ) => UseInfiniteQueryResult<
+    InfiniteData<ReactorReturnOk<A, M, T>, TPageParam>,
+    ReactorReturnErr<A, M, T>
+  >
+
+  useActorSuspenseInfiniteQuery: <
+    M extends FunctionName<A>,
+    TPageParam = unknown,
+  >(
+    config: SuspenseInfiniteQueryConfig<A, M, T, TPageParam>
+  ) => UseSuspenseInfiniteQueryResult<
+    InfiniteData<ReactorReturnOk<A, M, T>, TPageParam>,
+    ReactorReturnErr<A, M, T>
+  >
+
+  useActorMutation: <M extends FunctionName<A>>(
+    config: MutationConfig<A, M, T>
+  ) => UseMutationResult<ReactorReturnOk<A, M, T>, ReactorReturnErr<A, M, T>>
+
+  useActorMethod: <M extends FunctionName<A>>(
+    config: Omit<UseActorMethodParameters<A, M, T>, "reactor">
+  ) => ReturnType<typeof useActorMethod<A, M, T>>
+}
+
+export function createActorHooks<A>(
+  reactor: DisplayReactor<A>
+): ActorHooks<A, "display">
+
+export function createActorHooks<
+  A = BaseActor,
+  T extends TransformKey = "candid",
+>(reactor: Reactor<A, T>): ActorHooks<A, T>
+
+export function createActorHooks<A, T extends TransformKey>(
+  reactor: Reactor<A, T>
+): ActorHooks<A, T> {
+  return {
+    useActorQuery: ((config: any) => {
+      const { select, ...options } = config
+      return createQuery(reactor, config).useQuery(options)
+    }) as ActorHooks<A, T>["useActorQuery"],
+
+    useActorSuspenseQuery: ((config: any) => {
+      const { select, ...options } = config
+      return createSuspenseQuery(reactor, config).useSuspenseQuery(options)
+    }) as ActorHooks<A, T>["useActorSuspenseQuery"],
+
+    useActorInfiniteQuery: ((config) => {
+      const { select, ...options } = config
+      return createInfiniteQuery(reactor, config).useInfiniteQuery(options)
+    }) as ActorHooks<A, T>["useActorInfiniteQuery"],
+
+    useActorSuspenseInfiniteQuery: ((config) => {
+      const { select, ...options } = config
+      return createSuspenseInfiniteQuery(
+        reactor,
+        config
+      ).useSuspenseInfiniteQuery(options)
+    }) as ActorHooks<A, T>["useActorSuspenseInfiniteQuery"],
+
+    useActorMutation: ((config) => {
+      const { onSuccess, invalidateQueries, ...options } = config
+      return createMutation(reactor, config).useMutation(options)
+    }) as ActorHooks<A, T>["useActorMutation"],
+
+    useActorMethod: (config) =>
+      useActorMethod({ ...config, reactor } as UseActorMethodParameters<
+        A,
+        any,
+        T
+      >),
+  }
+}

package/src/createAuthHooks.ts

@@ -0,0 +1,137 @@
+import { useSyncExternalStore, useEffect, useRef, useMemo } from "react"
+import { ClientManager, AgentState, AuthState } from "@ic-reactor/core"
+import { Principal } from "@icp-sdk/core/principal"
+import { Identity } from "@icp-sdk/core/agent"
+import { AuthClientLoginOptions } from "@icp-sdk/auth/client"
+
+export interface UseAuthReturn {
+  authenticate: () => Promise<Identity | undefined>
+  login: (options?: AuthClientLoginOptions) => Promise<void>
+  logout: (options?: { returnTo?: string }) => Promise<void>
+  isAuthenticated: boolean
+  isAuthenticating: boolean
+  principal: Principal | null
+  identity: Identity | null
+  error: Error | undefined
+}
+
+export interface CreateAuthHooksReturn {
+  useAgentState: () => AgentState
+  useUserPrincipal: () => Principal | null
+  useAuth: () => UseAuthReturn
+}
+
+/**
+ * Create authentication hooks for managing user sessions with Internet Identity.
+ *
+ * @example
+ * const { useAuth, useUserPrincipal, useAgentState } = createAuthHooks(clientManager)
+ *
+ * function App() {
+ *   const { login, logout, principal, isAuthenticated } = useAuth()
+ *
+ *   return isAuthenticated
+ *     ? <button onClick={logout}>Logout {principal?.toText()}</button>
+ *     : <button onClick={login}>Login with II</button>
+ * }
+ */
+export const createAuthHooks = (
+  clientManager: ClientManager
+): CreateAuthHooksReturn => {
+  /**
+   * Subscribe to agent state changes.
+   * Returns the current agent state (agent, isInitialized, etc.)
+   */
+  const useAgentState = (): AgentState =>
+    useSyncExternalStore(
+      (callback) => clientManager.subscribeAgentState(callback),
+      () => clientManager.agentState,
+      // Server snapshot - provide initial state for SSR
+      () => clientManager.agentState
+    )
+
+  /**
+   * Subscribe to authentication state changes.
+   * Returns auth state (isAuthenticated, isAuthenticating, identity, error)
+   */
+  const useAuthState = (): AuthState =>
+    useSyncExternalStore(
+      (callback) => clientManager.subscribeAuthState(callback),
+      () => clientManager.authState,
+      // Server snapshot - provide initial state for SSR
+      () => clientManager.authState
+    )
+
+  /**
+   * Main authentication hook that provides login/logout methods and auth state.
+   * Automatically initializes the session on first use, restoring any previous session.
+   *
+   * @example
+   * function AuthButton() {
+   *   const { login, logout, isAuthenticated, isAuthenticating } = useAuth()
+   *
+   *   if (isAuthenticated) {
+   *     return <button onClick={logout}>Logout</button>
+   *   }
+   *   return (
+   *     <button onClick={login} disabled={isAuthenticating}>
+   *       {isAuthenticating ? "Connecting..." : "Login"}
+   *     </button>
+   *   )
+   * }
+   */
+  const useAuth = (): UseAuthReturn => {
+    const { login, logout, authenticate } = clientManager
+    const { isAuthenticated, isAuthenticating, identity, error } =
+      useAuthState()
+
+    // Track if we've already initialized to avoid duplicate calls
+    const initializedRef = useRef(false)
+
+    // Auto-initialize on first mount to restore previous session
+    useEffect(() => {
+      if (!initializedRef.current) {
+        initializedRef.current = true
+        clientManager.initialize()
+      }
+    }, [])
+
+    const principal = useMemo(
+      () => (identity ? identity.getPrincipal() : null),
+      [identity]
+    )
+
+    return {
+      authenticate,
+      login,
+      logout,
+      isAuthenticated,
+      isAuthenticating,
+      principal,
+      identity,
+      error,
+    }
+  }
+
+  /**
+   * Get the current user's Principal.
+   * Returns null if not authenticated.
+   *
+   * @example
+   * function UserInfo() {
+   *   const principal = useUserPrincipal()
+   *   if (!principal) return null
+   *   return <span>Logged in as: {principal.toText()}</span>
+   * }
+   */
+  const useUserPrincipal = (): Principal | null => {
+    const { identity } = useAuthState()
+    return identity ? identity.getPrincipal() : null
+  }
+
+  return {
+    useAuth,
+    useAgentState,
+    useUserPrincipal,
+  }
+}