docs: add typedoc documentation to client-react-hooks

client-react-hooks/src/cache-key.ts

@@ -1,15 +1,19 @@
 import { ComputeOutputId, StoreId } from "@nillion/client-core";
 
+/** `REACT_QUERY_STATE_KEY_PREFIX` is a string that is used to prefix the cache keys */
 export const REACT_QUERY_STATE_KEY_PREFIX = "__NILLION";
 
+/** `createStoreCacheKey` is a function that takes a `StoreId` or `string` and returns a cache key */
 export const createStoreCacheKey = (
   id: StoreId | string,
 ): readonly unknown[] => [REACT_QUERY_STATE_KEY_PREFIX, "STORE", id];
 
+/** `createPermissionsCacheKey` is a function that takes a `StoreId` or `string` or `null` and returns a cache key */
 export const createPermissionsCacheKey = (
   id: StoreId | string | null,
 ): readonly unknown[] => [REACT_QUERY_STATE_KEY_PREFIX, "PERMISSIONS", id];
 
+/** `createComputeResultCacheKey` is a function that takes a `ComputeOutputId` or `string` and returns a cache key */
 export const createComputeResultCacheKey = (
   id: ComputeOutputId | string,
 ): readonly unknown[] => [REACT_QUERY_STATE_KEY_PREFIX, "COMPUTE", id];

client-react-hooks/src/logging.ts

@@ -1,3 +1,7 @@
 import debug from "debug";
 
+/**
+ * `Log` is a debug logger that can be used to log messages to the console.
+ * @param message - string
+ */
 export const Log = debug("nillion:react-hooks");

client-react-hooks/src/nil-hook-base.ts

@@ -1,5 +1,12 @@
 import { UseMutationResult } from "@tanstack/react-query";
 
+/**
+ * `NilHookState` is a set of states that a NilHook can be in:
+ * - Idle: Waiting to receive a request
+ * - Loading: Waiting for the request to complete
+ * - Success: The request was successful
+ * - Error: The request had an error
+ */
 export const NilHookState = {
   Idle: {
     status: "idle",
@@ -31,6 +38,9 @@ export const NilHookState = {
   },
 } as const;
 
+/**
+ * `UseNilHook` is a hook that allows you to execute a NilHook operation, and check its status.
+ */
 export type UseNilHook<ExecuteArgs, ExecuteResult> = NilHookBaseResult<
   ExecuteArgs,
   ExecuteResult
@@ -42,11 +52,24 @@ export type UseNilHook<ExecuteArgs, ExecuteResult> = NilHookBaseResult<
     | NilHookErrorResult
   );
 
+/**
+ * NilHookBaseResult is a set of functions that a NilHook can use.
+ * execute - A function that executes the NilHook.
+ * executeAsync - A function that executes the NilHook asynchronously.
+ */
 export interface NilHookBaseResult<ExecuteArgs, ExecuteResult> {
   execute: (args: ExecuteArgs) => void;
   executeAsync: (args: ExecuteArgs) => Promise<ExecuteResult>;
 }
 
+/**
+ * NilHookIdleResult is a set of states that a NilHook can be in when it is idle.
+ * status - The status of the NilHook.
+ * isLoading - Whether the NilHook is loading.
+ * isSuccess - Whether the NilHook is successful.
+ * isError - Whether the NilHook has an error.
+ * isIdle - Whether the NilHook is idle.
+ */
 export interface NilHookIdleResult {
   status: "idle";
   isLoading: false;
@@ -55,6 +78,14 @@ export interface NilHookIdleResult {
   isIdle: true;
 }
 
+/**
+ * NilHookLoadingResult is a set of states that a NilHook can be in when it is loading.
+ * status - The status of the NilHook, namely "loading".
+ * isLoading - Whether the NilHook is loading.
+ * isSuccess - Whether the NilHook is successful.
+ * isError - Whether the NilHook has an error.
+ * isIdle - Whether the NilHook is idle.
+ */
 export interface NilHookLoadingResult {
   status: "loading";
   isLoading: true;
@@ -63,6 +94,15 @@ export interface NilHookLoadingResult {
   isIdle: false;
 }
 
+/**
+ * NilHookSuccessResult is a set of states that a NilHook can be in when it is successful.
+ * status - The status of the NilHook namely "success".
+ * data  - The data of the NilHook.
+ * isLoading - Whether the NilHook is loading.
+ * isSuccess - Whether the NilHook is successful.
+ * isError - Whether the NilHook has an error.
+ * isIdle - Whether the NilHook is idle.
+ */
 export interface NilHookSuccessResult<R> {
   status: "success";
   data: R;
@@ -72,6 +112,15 @@ export interface NilHookSuccessResult<R> {
   isIdle: false;
 }
 
+/**
+ * NilHookErrorResult is a set of states that a NilHook can be in when it has an error.
+ * status - The status of the NilHook namely "error".
+ * error - The error of the NilHook.
+ * isLoading - Whether the NilHook is loading.
+ * isSuccess - Whether the NilHook is successful.
+ * isError - Whether the NilHook has an error.
+ * isIdle - Whether the NilHook is idle.
+ */
 export interface NilHookErrorResult {
   status: "error";
   error: Error;
@@ -81,6 +130,11 @@ export interface NilHookErrorResult {
   isIdle: false;
 }
 
+/**
+ * nilHookBaseResult is a function that returns the state of a NilHook.
+ * @param mutate - The result of a mutation.
+ * @returns The state of the NilHook, which can be idle, loading, success, or error.
+ */
 export const nilHookBaseResult = <T, E, R>(
   mutate: UseMutationResult<T, E, R>,
 ) => {

client-react-hooks/src/nillion-provider.tsx

@@ -24,39 +24,76 @@ import { NetworkConfig, NillionClient } from "@nillion/client-vms";
 
 import { Log } from "./logging";
 
+/**
+ * `WithConfigProps`
+ * `config` is a ProviderNetworkConfig
+ * `network` is a NamedNetwork
+ * `client` is not allowed
+ **/
 interface WithConfigProps {
   config?: ProviderNetworkConfig;
   network?: NamedNetwork;
   client?: never;
 }
 
+/**
+ * `ProviderNetworkConfig`
+ * `bootnodes` is an array of Multiaddr or string
+ * `clusterId` is a ClusterId or string
+ * `nilChainId` is a ChainId or string
+ * `nilChainEndpoint` is a Url or string
+ */
 interface ProviderNetworkConfig {
   bootnodes?: (Multiaddr | string)[];
   clusterId?: ClusterId | string;
   nilChainId?: ChainId | string;
   nilChainEndpoint?: Url | string;
 }
 
+/**
+ * `WithClientProps`
+ * `client` is a `NillionClient`
+ * `config` is not allowed
+ * `network` is not allowed
+ */
 interface WithClientProps {
   client: NillionClient;
   config?: never;
   network?: never;
 }
 
+/**
+ * `NillionProviderProps`
+ * Alias for either WithConfigProps or WithClientProps
+ */
 export type NillionProviderProps = WithConfigProps | WithClientProps;
 
+/**
+ * `NillionContext`
+ * `client` is a NillionClient
+ * `logout` is a function that returns a Promise<void>
+ */
 export interface NillionContext {
   client: NillionClient;
   logout: () => Promise<void>;
 }
 
+/**
+ * `NillionContext`
+ * It provides a `NillionClient` context
+ */
 export const NillionContext = createContext<NillionContext | undefined>(
   undefined,
 );
 
 // Moving this into the hook means the client doesn't persist when strict mode is enabled
 const client = NillionClient.create();
 
+/**
+ * NillionProvider
+ * @param NillionProviderProps - expects provider props or a `ReactNode`
+ * @returns ReactNode
+ */
 export const NillionProvider: React.FC<
   NillionProviderProps & { children: ReactNode }
 > = (props): ReactNode => {

client-react-hooks/src/use-nil-compute-output.ts

@@ -5,14 +5,27 @@ import { ComputeOutputId, NadaPrimitiveValue } from "@nillion/client-core";
 import { nilHookBaseResult, UseNilHook } from "./nil-hook-base";
 import { useNillion } from "./use-nillion";
 
+/**
+ * `ExecuteArgs` is an interface that can be passed to the `execute` function.
+ * @param id - `ComputeOutputId` or `string`
+ */
 interface ExecuteArgs {
   id: ComputeOutputId | string;
 }
 
 type ExecuteResult = Record<string, NadaPrimitiveValue>;
 
+/**
+ * `UseNilComputeOutput` is a hook that allows you to execute a compute output.
+ * execute - It executes the NilHook synchronously, allowing the user to check for its status via {@link isSuccess} and {@link isError}.
+ * executeAsync -  It executes the NilHook asynchronously, allowing the usage of `async/await` or `.then()`.
+ */
 type UseNilComputeOutput = UseNilHook<ExecuteArgs, ExecuteResult>;
 
+/**
+ * `useNilComputeOutput` is a hook that allows you to execute a compute output.
+ * @returns {@link UseNilComputeOutput}
+ */
 export const useNilComputeOutput = (): UseNilComputeOutput => {
   const { client: nilClient } = useNillion();
 
@@ -27,9 +40,11 @@ export const useNilComputeOutput = (): UseNilComputeOutput => {
   });
 
   return {
+    /** execute function that takes an ExecuteArgs object and executes the compute output */
     execute: (args: ExecuteArgs) => {
       mutate.mutate(args);
     },
+    /** executeAsync function that takes an ExecuteArgs object and executes the compute output asynchronously */
     executeAsync: async (args: ExecuteArgs) => mutate.mutateAsync(args),
     ...nilHookBaseResult(mutate),
   };

client-react-hooks/src/use-nil-compute.ts

@@ -10,15 +10,29 @@ import {
 import { nilHookBaseResult, UseNilHook } from "./nil-hook-base";
 import { useNillion } from "./use-nillion";
 
+/** ExecuteArgs is an interface that can be passed to the `execute` function.
+ * @param bindings - `ProgramBindings`
+ * @param values - `NadaValues`
+ * @param storeIds - array of `StoreId`s or strings
+ */
 interface ExecuteArgs {
   bindings: ProgramBindings;
   values?: NadaValues;
   storeIds?: (StoreId | string)[];
 }
 type ExecuteResult = ComputeOutputId;
 
+/**
+ * `UseNilCompute` is a hook that allows you to execute a compute operation on Nillion.
+ * execute - It executes the NilHook synchronously, allowing the user to check for its status via {@link isSuccess} and {@link isError}.
+ * executeAsync -  It executes the NilHook asynchronously, allowing the usage of `async/await` or `.then()`.
+ */
 type UseNilCompute = UseNilHook<ExecuteArgs, ExecuteResult>;
 
+/**
+ * `useNilCompute` is a hook that allows you to execute a compute.
+ * @returns {@link UseNilCompute}
+ */
 export const useNilCompute = (): UseNilCompute => {
   const { client: nilClient } = useNillion();
 
@@ -38,9 +52,11 @@ export const useNilCompute = (): UseNilCompute => {
   });
 
   return {
+    /** `execute` function that takes an `ExecuteArgs` object and executes the compute */
     execute: (args: ExecuteArgs) => {
       mutate.mutate(args);
     },
+    /** `executeAsync` function that takes an `ExecuteArgs` object and executes the compute asynchronously */
     executeAsync: async (args: ExecuteArgs) => mutate.mutateAsync(args),
     ...nilHookBaseResult(mutate),
   };

client-react-hooks/src/use-nil-delete-value.ts

@@ -7,14 +7,27 @@ import { nilHookBaseResult } from "./nil-hook-base";
 import { UseNilHook } from "./nil-hook-base";
 import { useNillion } from "./use-nillion";
 
+/**
+ * `ExecuteArgs` is an interface that can be passed to the `execute` function
+ * @param id - `StoreId` or `string`
+ */
 interface ExecuteArgs {
   id: StoreId | string;
 }
 
 type ExecuteResult = StoreId;
 
+/**
+ * `UseNilDeleteValue` is a hook that allows you to delete a value from a store.
+ * execute - It executes the NilHook synchronously, allowing the user to check for its status via {@link isSuccess} and {@link isError}.
+ * executeAsync -  It executes the NilHook asynchronously, allowing the usage of `async/await` or `.then()`.
+ */
 type UseNilDeleteValue = UseNilHook<ExecuteArgs, ExecuteResult>;
 
+/**
+ * `useNilDeleteValue` is a hook that allows you to delete a value from a store.
+ * @returns {@link UseNilDeleteValue}
+ */
 export const useNilDeleteValue = (): UseNilDeleteValue => {
   const { client: nilClient } = useNillion();
   const queryClient = useQueryClient();
@@ -39,9 +52,11 @@ export const useNilDeleteValue = (): UseNilDeleteValue => {
   });
 
   return {
+    /** execute function that takes an `ExecuteArgs` object and executes the delete value */
     execute: (args: ExecuteArgs) => {
       mutate.mutate(args);
     },
+    /** executeAsync function that takes an `ExecuteArgs` object and executes the delete value asynchronously */
     executeAsync: async (args: ExecuteArgs) => mutate.mutateAsync(args),
     ...nilHookBaseResult(mutate),
   };

client-react-hooks/src/use-nil-fetch-store-acl.ts

@@ -5,13 +5,26 @@ import { StoreAcl, StoreId } from "@nillion/client-core";
 import { nilHookBaseResult, UseNilHook } from "./nil-hook-base";
 import { useNillion } from "./use-nillion";
 
+/**
+ * `ExecuteArgs` is an interface that can be passed to the `execute` function.
+ * @param id - `StoreId` or `string`
+ */
 interface ExecuteArgs {
   id: StoreId | string;
 }
 type ExecuteResult = StoreAcl;
 
+/**
+ * `UseNilFetchStoreAcl` is a hook that allows you to fetch a store acl.
+ * execute - executes the NilHook synchronously, allowing the user to check for its status via {@link isSuccess} and {@link isError}.
+ * executeAsync - executes the NilHook asynchronously, allowing the usage of `async/await` or `.then()`.
+ */
 type UseNilFetchStoreAcl = UseNilHook<ExecuteArgs, ExecuteResult>;
 
+/**
+ * `useNilFetchStoreAcl` is a hook that allows you to fetch a store acl.
+ * @returns {@link UseNilFetchStoreAcl}
+ */
 export const useNilFetchStoreAcl = (): UseNilFetchStoreAcl => {
   const { client } = useNillion();
 
@@ -26,9 +39,11 @@ export const useNilFetchStoreAcl = (): UseNilFetchStoreAcl => {
   });
 
   return {
+    /* execute function that takes an `ExecuteArgs` object and executes the fetch store acl */
     execute: (args: ExecuteArgs) => {
       mutate.mutate(args);
     },
+    /* executeAsync function that takes an `ExecuteArgs` object and executes the fetch store acl asynchronously */
     executeAsync: async (args: ExecuteArgs) => mutate.mutateAsync(args),
     ...nilHookBaseResult(mutate),
   };