docs: add documentation to client-react-hooks

package.json

@@ -42,14 +42,15 @@
     "lint-staged": "^15.2.9",
     "node-fetch": "^3.3.2",
     "prettier": "^3.3.3",
-    "serve": "^14.2.3",
+    "serve": "^6.5.8",
     "ts-jest": "^29.2.4",
     "ts-loader": "^9.5.1",
     "ts-node": "^10.9.2",
     "tsconfig-paths-webpack-plugin": "^4.1.0",
     "typedoc": "^0.26.6",
     "typedoc-plugin-markdown": "^4.2.6",
     "typedoc-plugin-mermaid": "^1.12.0",
+    "typedoc-plugin-not-exported": "^0.1.6",
     "typedoc-plugin-zod": "^1.2.1",
     "typescript": "^5.5.4",
     "typescript-eslint": "^8.2.0",

packages/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];

packages/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");

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

@@ -1,7 +1,11 @@
 import { UseMutationResult } from "@tanstack/react-query";
 
 /**
- * NilHookState is a set of states that a NilHook can be in.
+ * 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
  @enum
  */
 export const NilHookState = {
@@ -35,6 +39,10 @@ export const NilHookState = {
   },
 } as const;
 
+/**
+ * `UseNilHook` is a hook that allows you to execute a NilHook operation, and check its status.
+ * @type
+ */
 export type UseNilHook<ExecuteArgs, ExecuteResult> = NilHookBaseResult<
   ExecuteArgs,
   ExecuteResult
@@ -50,7 +58,6 @@ export type UseNilHook<ExecuteArgs, ExecuteResult> = NilHookBaseResult<
  * NilHookBaseResult is a set of functions that a NilHook can use.
  * @property execute - A function that executes the NilHook.
  * @property executeAsync - A function that executes the NilHook asynchronously.
- * @interface
  */
 export interface NilHookBaseResult<ExecuteArgs, ExecuteResult> {
   execute: (args: ExecuteArgs) => void;
@@ -63,7 +70,7 @@ export interface NilHookBaseResult<ExecuteArgs, ExecuteResult> {
  * @property isLoading - Whether the NilHook is loading.
  * @property isSuccess - Whether the NilHook is successful.
  * @property isError - Whether the NilHook has an error.
- * @interface
+ * @property isIdle - Whether the NilHook is idle.
  */
 export interface NilHookIdleResult {
   status: "idle";
@@ -79,7 +86,7 @@ export interface NilHookIdleResult {
  * @property isLoading - Whether the NilHook is loading.
  * @property isSuccess - Whether the NilHook is successful.
  * @property isError - Whether the NilHook has an error.
- * @interface
+ * @property isIdle - Whether the NilHook is idle.
  */
 export interface NilHookLoadingResult {
   status: "loading";
@@ -96,7 +103,7 @@ export interface NilHookLoadingResult {
  * @property isLoading - Whether the NilHook is loading.
  * @property isSuccess - Whether the NilHook is successful.
  * @property isError - Whether the NilHook has an error.
- * @interface
+ * @property isIdle - Whether the NilHook is idle.
  */
 export interface NilHookSuccessResult<R> {
   status: "success";
@@ -114,7 +121,7 @@ export interface NilHookSuccessResult<R> {
  * @property isLoading - Whether the NilHook is loading.
  * @property isSuccess - Whether the NilHook is successful.
  * @property isError - Whether the NilHook has an error.
- * @interface
+ * @property isIdle - Whether the NilHook is idle.
  */
 export interface NilHookErrorResult {
   status: "error";
@@ -128,7 +135,7 @@ export interface NilHookErrorResult {
 /**
  * nilHookBaseResult is a function that returns the state of a NilHook.
  * @param mutate - The result of a mutation.
- * @returns The state of the NilHook.
+ * @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>,

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

@@ -29,22 +29,21 @@ import { Log } from "./logging";
  * @property config is a ProviderNetworkConfig
  * @property network is a NamedNetwork
  * @property client is not allowed
- * @interface
  **/
-interface WithConfigProps {
+export interface WithConfigProps {
   config?: ProviderNetworkConfig;
   network?: NamedNetwork;
   client?: never;
 }
 
-/** ProviderNetworkConfig
+/**
+ * ProviderNetworkConfig
  * @property bootnodes is an array of Multiaddr or string
  * @property clusterId is a ClusterId or string
  * @property nilChainId is a ChainId or string
  * @property nilChainEndpoint is a Url or string
- * @interface
  */
-interface ProviderNetworkConfig {
+export interface ProviderNetworkConfig {
   bootnodes?: (Multiaddr | string)[];
   clusterId?: ClusterId | string;
   nilChainId?: ChainId | string;
@@ -53,28 +52,24 @@ interface ProviderNetworkConfig {
 
 /**
  * WithClientProps
- *
  * @property client is a NillionClient
  * @property config is not allowed
  * @property network is not allowed
- * @interface
  */
-interface WithClientProps {
+export interface WithClientProps {
   client: NillionClient;
   config?: never;
   network?: never;
 }
 
 /**
  * NillionProviderProps
- *
  * @type Alias for either WithConfigProps or WithClientProps
  */
 export type NillionProviderProps = WithConfigProps | WithClientProps;
 
 /**
  * NillionContext
- *
  * @property client is a NillionClient
  * @property logout is a function that returns a Promise<void>
  * @interface
@@ -84,6 +79,10 @@ export interface NillionContext {
   logout: () => Promise<void>;
 }
 
+/**
+ * NillionContext
+ * @type React.Context<NillionContext | undefined>
+ */
 export const NillionContext = createContext<NillionContext | undefined>(
   undefined,
 );
@@ -93,8 +92,7 @@ const client = NillionClient.create();
 
 /**
  * NillionProvider
- *
- * @param NillionProviderProps
+ * @param NillionProviderProps & { children: ReactNode }
  * @returns ReactNode
  */
 export const NillionProvider: React.FC<

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

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

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

@@ -10,15 +10,31 @@ import {
 import { nilHookBaseResult, UseNilHook } from "./nil-hook-base";
 import { useNillion } from "./use-nillion";
 
-interface ExecuteArgs {
+/** 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
+ */
+export interface ExecuteArgs {
   bindings: ProgramBindings;
   values?: NadaValues;
   storeIds?: (StoreId | string)[];
 }
 type ExecuteResult = ComputeOutputId;
 
-type UseNilCompute = UseNilHook<ExecuteArgs, ExecuteResult>;
+/**
+ * `UseNilCompute` is a hook that allows you to execute a compute operation on Nillion.
+ * @property execute - It executes the NilHook synchronously, allowing the user to check for its status via {@link isSuccess} and {@link isError}.
+ * @property executeAsync -  It executes the NilHook asynchronously, allowing the usage of `async/await` or `.then()`.
+ * @type
+ */
+export type UseNilCompute = UseNilHook<ExecuteArgs, ExecuteResult>;
 
+/**
+ * `useNilCompute` is a hook that allows you to execute a compute.
+ * @returns {@link UseNilCompute}
+ * @interface
+ */
 export const useNilCompute = (): UseNilCompute => {
   const { client: nilClient } = useNillion();
 
@@ -38,9 +54,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),
   };

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

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

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

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