docs: add typedoc documentation to client-react-hooks and client-vms packages

package.json

@@ -16,43 +16,51 @@
  "examples/nextjs"
  ],
  "devDependencies": {
- "@commitlint/cli": "^19.5.0",
- "@commitlint/config-conventional": "^19.5.0",
- "@eslint/compat": "^1.2.0",
- "@eslint/js": "^9.12.0",
+ "@commitlint/cli": "^19.4.0",
+ "@commitlint/config-conventional": "^19.2.2",
+ "@eslint/compat": "^1.1.1",
+ "@eslint/js": "^9.9.0",
  "@types/debug": "^4.1.12",
  "@types/jasmine": "^5.1.4",
- "@types/jest": "^29.5.13",
- "browserslist": "^4.24.0",
- "concurrently": "^9.0.1",
+ "@types/jest": "^29.5.12",
+ "browserslist": "^4.23.3",
+ "concurrently": "^8.2.2",
  "copy-webpack-plugin": "^12.0.2",
- "esbuild": "^0.24.0",
- "esbuild-plugin-browserslist": "^0.15.0",
- "eslint": "^9.12.0",
+ "esbuild": "^0.23.1",
+ "esbuild-plugin-browserslist": "^0.14.0",
+ "eslint": "^9.9.0",
  "eslint-plugin-simple-import-sort": "^12.1.1",
  "eslint-plugin-tsdoc": "^0.3.0",
  "express-http-proxy": "^2.1.1",
  "glob": "^11.0.0",
- "globals": "^15.10.0",
- "husky": "^9.1.6",
+ "globals": "^15.9.0",
+ "husky": "^9.1.5",
  "jasmine-browser-runner": "^2.5.0",
- "jasmine-core": "^5.3.0",
+ "jasmine-core": "^5.2.0",
  "jest": "^29.7.0",
  "jest-environment-jsdom": "^29.7.0",
- "lint-staged": "^15.2.10",
+ "lint-staged": "^15.2.9",
  "node-fetch": "^3.3.2",
  "prettier": "^3.3.3",
- "ts-jest": "^29.2.5",
+ "serve": "^14.2.3",
+ "ts-jest": "^29.2.4",
  "ts-loader": "^9.5.1",
  "ts-node": "^10.9.2",
  "tsconfig-paths-webpack-plugin": "^4.1.0",
- "typescript": "^5.6.2",
- "typescript-eslint": "^8.8.0",
- "webpack": "^5.95.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",
+ "webpack": "^5.93.0",
  "webpack-cli": "^5.1.4"
  },
  "scripts": {
- "prepare": "husky"
+ "prepare": "husky",
+ "builddocs": "npx typedoc --tsconfig ./tsconfig.typedoc.json",
+ "servedocs": "npx serve docs"
  },
  "lint-staged": {
  "*.{js,jsx,ts,tsx}": "eslint -c eslint.config.mjs"

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,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>,
 ) => {

packages/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 => {

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

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