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

package/dist/index.d.ts

@@ -1,17 +1,261 @@
-export * from "@ic-reactor/core";
-export * from "./hooks/index.js";
-export * from "./validation.js";
-export * from "./createActorHooks.js";
-export * from "./defineReactor.js";
-export * from "./defineDisplayReactor.js";
-export * from "./createReactorProvider.js";
-export * from "./createQuery.js";
-export * from "./createSuspenseQuery.js";
-export * from "./createInfiniteQuery.js";
-export * from "./createSuspenseInfiniteQuery.js";
-export * from "./createMutation.js";
-export * from "./auth/index.js";
-export * from "./types.js";
-export { skipToken } from "@tanstack/react-query";
-export type { SkipToken } from "@tanstack/react-query";
+/**
+ * `@ic-reactor/react` 4: the `'use client'` bindings over `@ic-reactor/core`.
+ *
+ * A provider that gives a tree one client ({@link ReactorProvider}), a hook
+ * that reads it ({@link useClient}), and one that follows who is signed in
+ * ({@link useAuth}). Nothing here wraps `useQuery` or `useMutation`: an app
+ * calls TanStack Query's own hooks with the options the client builds. The
+ * package never re-exports `@ic-reactor/core`, so every name has one import
+ * path.
+ *
+ * The directive above makes this module a client boundary, so a framework
+ * that renders on a server (Next.js's App Router, for one) loads it as client
+ * code. A Server Component still cannot pass `ReactorProvider` its `client`
+ * prop, a function, across that boundary: render the provider from a client
+ * module of the app, which a Server Component then renders around its page.
+ *
+ * @packageDocumentation
+ */
+import type { AuthState, Client } from "@ic-reactor/core";
+import { type ReactElement, type ReactNode } from "react";
+/** Props of {@link ReactorProvider}. */
+export interface ReactorProviderProps {
+    /**
+     * Returns the client of this tree. Either it creates one, such as
+     * `() => createClient({ network: "ic", auth: () => new AuthClient() })`, and
+     * the provider owns that client and disposes it when it unmounts; or it
+     * returns a client the app created before, at module scope, as
+     * `() => client`, and the provider borrows it and never disposes it.
+     *
+     * A factory, not a client, so that the provider decides when it runs: once
+     * per mounted provider, never per render. Give it no work beyond creating or
+     * returning the client (`createClient` does none until the client is used):
+     * React may call it twice in development and keep one result.
+     *
+     * Only the factory of the first render is used. A different function on a
+     * later render does not rebuild the client; to replace it, remount the
+     * provider by giving it another `key`.
+     */
+    readonly client: () => Client;
+    /** The tree that reads the client with {@link useClient} and {@link useAuth}. */
+    readonly children: ReactNode;
+}
+/**
+ * Gives a tree one client: it gets it from `client` once, on the first
+ * render, makes it available to {@link useClient} and {@link useAuth}, renders
+ * TanStack Query's `QueryClientProvider` around the children with the
+ * client's `QueryClient`, and, if its factory created the client, disposes it
+ * when it unmounts.
+ *
+ * Put it at the root of the part of the app that calls canisters, in a
+ * client module (the examples below). On a server it renders inside the
+ * request, so a factory that creates the client runs once per request and no
+ * cache or caller is shared between two users, which a client at module scope
+ * would be.
+ *
+ * Who disposes the client depends on when it was created, not on where the
+ * factory is written. A client the factory call creates belongs to the
+ * provider. A client created before the call, such as one at module scope that
+ * code outside React uses too, is borrowed: the provider never disposes it,
+ * however many times it mounts and unmounts, and the app ends it with
+ * `client.dispose()` if it ever needs to. A factory that creates the shared
+ * client lazily on its first call (`() => (client ??= createClient(...))`)
+ * hands that first provider ownership, and the provider disposes it on
+ * unmount. It can also lose the client before any unmount: when React throws
+ * away the render that created it (see below), the client stays registered
+ * for disposal at collection until the next render gets it back from the
+ * factory, so a garbage collection while the fallback shows disposes the
+ * client the retry then mounts. Create a shared client eagerly instead. In
+ * development, a provider whose factory hands back a client that an earlier
+ * factory call created and no provider has committed yet, as a lazily shared
+ * factory does, logs a warning (under `StrictMode`, on its first render), and
+ * a provider that is given a borrowed client which is already disposed logs an
+ * error.
+ *
+ * Disposal is safe in React's development double-mount (`StrictMode` mounts,
+ * unmounts and mounts every component again at once): the cleanup only
+ * schedules the disposal for the next macrotask, and the second mount cancels
+ * it, so a client in use is never disposed. An unmount that is not followed
+ * by a mount disposes an owned client exactly once.
+ *
+ * React runs no cleanup for a render it throws away before committing it: the
+ * first render of a provider below a Suspense boundary that suspends, or the
+ * `useState` initializer call that `StrictMode` drops in development. An owned
+ * client built for such a render, whose auth a child's {@link useAuth} may
+ * already have built, is disposed once that render's state is garbage
+ * collected, through a `FinalizationRegistry`. That is later than an unmount
+ * would dispose it, at a moment no code chooses, but it is disposed, auth and
+ * listeners with it. A client that the factory returns again, or that a
+ * provider commits, is taken off the registry, whoever owns it. A runtime
+ * without `FinalizationRegistry` never disposes such a client, and a server
+ * never registers one: it builds no auth there, and the rest of the request
+ * still uses it.
+ *
+ * React also runs the effects of a subtree again when it shows a hidden
+ * `Activity` once more, and that can be long after they were cleaned up. If an
+ * owned client was disposed meanwhile, the provider builds another from the
+ * same factory, because a disposed client cannot call, sign in or cache any
+ * more. The cost is that hiding a provider inside an `Activity` drops its
+ * cache: disposing clears the `QueryClient`, and the client built on the next
+ * show starts empty. React cannot tell a hidden subtree from an unmounted one
+ * in the cleanup, so there is no way to keep it. To keep a cache across
+ * hiding, render the provider above the `Activity`, not inside it, or give it
+ * a borrowed client, which is never disposed.
+ *
+ * @example
+ * A client per provider, owned and disposed by it (on a server, one per
+ * request):
+ * ```tsx
+ * "use client"
+ *
+ * import { createClient } from "@ic-reactor/core"
+ * import { ReactorProvider } from "@ic-reactor/react"
+ * import { AuthClient } from "@icp-sdk/auth/client"
+ * import type { ReactNode } from "react"
+ *
+ * export function Providers({ children }: { children: ReactNode }) {
+ *   return (
+ *     <ReactorProvider
+ *       client={() =>
+ *         createClient({ network: "ic", auth: () => new AuthClient() })
+ *       }
+ *     >
+ *       {children}
+ *     </ReactorProvider>
+ *   )
+ * }
+ * ```
+ *
+ * @example
+ * One client per tab, created at module scope and used outside React too.
+ * The provider borrows it and never disposes it (browser-only: on a server a
+ * module-scope client is shared by every request):
+ * ```tsx
+ * "use client"
+ *
+ * import { createClient } from "@ic-reactor/core"
+ * import { ReactorProvider } from "@ic-reactor/react"
+ * import { AuthClient } from "@icp-sdk/auth/client"
+ * import type { ReactNode } from "react"
+ *
+ * export const client = createClient({
+ *   network: "ic",
+ *   auth: () => new AuthClient(),
+ * })
+ *
+ * export function Providers({ children }: { children: ReactNode }) {
+ *   return <ReactorProvider client={() => client}>{children}</ReactorProvider>
+ * }
+ * ```
+ */
+export declare function ReactorProvider({ client: build, children, }: ReactorProviderProps): ReactElement;
+/**
+ * The client of the nearest {@link ReactorProvider}: the one object that
+ * builds canister handles and query options, and that signs users in and out.
+ *
+ * Call it in the body of each component that builds keys or options, on
+ * every render, and build them from what it returns there, never from a
+ * client held at module scope: they are built for the caller this render
+ * shows. Do not keep what it returns past the render: while a page hydrates
+ * it is a view for the anonymous caller, and a view never moves on. An effect
+ * or a callback that uses it closes over its render's value and lists it in
+ * its dependencies (`react-hooks/exhaustive-deps`), so that it runs again with
+ * the client after hydrating. Kept from the hydrating render anywhere else
+ * (`useState(client)`, `useRef(client)`, a `useMemo` or `useCallback` with
+ * `[]`, a module variable), it stays that view: the component shows the
+ * anonymous caller's data, a read it starts while the user is signed in is
+ * cancelled, and a write through it still signs as the live caller. Nothing
+ * warns about it. A nested {@link ReactorProvider} given it
+ * (`client={() => client}`) holds the client the view was made over.
+ * It follows the client's caller with `useSyncExternalStore`, so a
+ * component that calls it renders again when the caller changes (a sign-in, a
+ * switch of account, a sign-out) and never otherwise: a change of status that
+ * leaves the caller as it is (a session that expired, or one signed in
+ * elsewhere, both call as the anonymous principal) renders nothing. In the
+ * steady state it returns the provider's client object itself.
+ *
+ * On a server, and while a page hydrates, the caller is the anonymous one, as
+ * for {@link useAuth}. In a browser that holds a session, the hydrating render
+ * gets a view of the client for the anonymous caller: its `queryKey`,
+ * `queryOptions`, `caller()` and `authState()` are the anonymous caller's, so
+ * the page finds what the server prefetched and dehydrated and matches its
+ * HTML; everything else (canisters, `mutationOptions`, `signIn`, `signOut`,
+ * the `QueryClient`) is the client's own, and a write signs as the caller
+ * current when it runs. Right after hydrating, React renders the component
+ * again with the client itself, for the user: a read with none of the user's
+ * data yet shows its loading state, and a `useSuspenseQuery` read its
+ * boundary's fallback, until that data arrives. A client built with
+ * `identity` keeps its caller for good and is always returned as it is.
+ *
+ * Three consequences of that move on a signed-in reload:
+ *
+ * - A Suspense boundary that is still dehydrated below a component that
+ *   renders with the caller (this hook or {@link useAuth}), because its lazy
+ *   code is still loading or its streamed HTML has not arrived, is rendered
+ *   on the client when that component moves on: it shows its fallback
+ *   instead of the server's HTML, and React 18 reports a recoverable error.
+ *   Its data is still the user's. A `useAuth()` component also moves on in a
+ *   tab whose session expired or is signed in elsewhere. Render such a boundary where no component
+ *   that renders with the caller sits above it, or pass it in as `children`,
+ *   which a component's own update does not render again.
+ * - A read the hydrating render built may still run once (TanStack Query
+ *   refetches stale data on mount, and an effect may fetch with the view's
+ *   options). It is cancelled before anything is sent. A key that holds data
+ *   keeps it as it was, and a fetch of it resolves with that data. A key with
+ *   none fails (`kind` `"cancelled"`, `code` `"caller_changed"`) until the
+ *   anonymous caller is current again: the hydrating render's own reads never
+ *   show that, but a listener of
+ *   `client.queryClient.getQueryCache().subscribe()` (the client takes no
+ *   `QueryCache` of yours), an effect that awaits the fetch and, for a
+ *   `useSuspenseQuery` read the server rendered without dehydrating its
+ *   data, React's `onRecoverableError` (as the reported error's `cause` on
+ *   React 19) see it, so ignore `kind` `"cancelled"` there.
+ * - Put a Suspense boundary above every component that reads with
+ *   `useSuspenseQuery`, on React 18 and 19 alike. The move is a synchronous
+ *   update, which such a read suspends until the user's data arrives. With a
+ *   boundary above, the boundary shows its fallback, then the user's data,
+ *   and the rest of the page responds meanwhile. With none, React 18 refuses
+ *   the update ("A component suspended while responding to synchronous
+ *   input") and unmounts the root, so a signed-in reload renders nothing.
+ *   React 19 keeps the server's HTML on screen, but until the user's data
+ *   arrives, however long the read and its retries take, a click or any other
+ *   update outside a transition commits nothing, and neither does a
+ *   transition that renders the reading component again.
+ *
+ * @throws Error outside a `ReactorProvider`, naming it.
+ */
+export declare function useClient(): Client;
+/**
+ * Who calls, and how to change it: the client's {@link AuthState} (`status`
+ * and `principal`) with `signIn` and `signOut` forwarded to the client.
+ *
+ * It follows the client with `useSyncExternalStore`, so a component renders
+ * again once per change of status or principal and never otherwise (a renewed
+ * delegation, or a parent that renders, does not). The object it returns is
+ * the same until the state changes, so it is safe in a dependency array or
+ * as a prop of a memoized child.
+ *
+ * On a server, and while a page hydrates, the state is `anonymous`: the
+ * server has no session, and rendering the browser's would not match the
+ * server's HTML. A browser whose state is another one (signed in, or a session
+ * that expired or is signed in elsewhere) renders the component again with its
+ * own state right after hydration; an anonymous one does not, and keeps the
+ * object. A component that reads `status` before then should show the same
+ * thing signed out and while the session is read. Whenever it moves on after
+ * hydrating (a signed-in reload, or a session that expired or is signed in
+ * elsewhere), it renders a Suspense boundary still dehydrated below it on the
+ * client, as for {@link useClient}.
+ *
+ * `signIn` and `signOut` reject like {@link Client.signIn} and
+ * {@link Client.signOut}: on a client built with `identity`, which has no
+ * sign-in, and on a server.
+ *
+ * @throws Error outside a {@link ReactorProvider}.
+ */
+export declare function useAuth(): AuthState & {
+    /** Signs in through the client's auth, passing `options` on. */
+    signIn(options?: unknown): Promise<void>;
+    /** Signs out through the client's auth. */
+    signOut(options?: unknown): Promise<void>;
+};
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,cAAc,kBAAkB,CAAA;AAGhC,cAAc,kBAAkB,CAAA;AAGhC,cAAc,iBAAiB,CAAA;AAG/B,cAAc,uBAAuB,CAAA;AACrC,cAAc,oBAAoB,CAAA;AAClC,cAAc,2BAA2B,CAAA;AACzC,cAAc,4BAA4B,CAAA;AAE1C,cAAc,kBAAkB,CAAA;AAChC,cAAc,0BAA0B,CAAA;AACxC,cAAc,0BAA0B,CAAA;AACxC,cAAc,kCAAkC,CAAA;AAChD,cAAc,qBAAqB,CAAA;AAEnC,cAAc,iBAAiB,CAAA;AAE/B,cAAc,YAAY,CAAA;AAK1B,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAA;AACjD,YAAY,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.tsx"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAA;AAEzD,OAAO,EAQL,KAAK,YAAY,EACjB,KAAK,SAAS,EACf,MAAM,OAAO,CAAA;AAwNd,wCAAwC;AACxC,MAAM,WAAW,oBAAoB;IACnC;;;;;;;;;;;;;;;OAeG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,MAAM,CAAA;IAC7B,iFAAiF;IACjF,QAAQ,CAAC,QAAQ,EAAE,SAAS,CAAA;CAC7B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2GG;AACH,wBAAgB,eAAe,CAAC,EAC9B,MAAM,EAAE,KAAK,EACb,QAAQ,GACT,EAAE,oBAAoB,GAAG,YAAY,CAmDrC;AAmBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0EG;AACH,wBAAgB,SAAS,IAAI,MAAM,CAclC;AAgBD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,OAAO,IAAI,SAAS,GAAG;IACrC,gEAAgE;IAChE,MAAM,CAAC,OAAO,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACxC,2CAA2C;IAC3C,OAAO,CAAC,OAAO,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CAC1C,CAsBA"}