docs: complete NillionClient typedocs

packages/client-core/src/result.ts

@@ -2,6 +2,26 @@ import { Effect as E, pipe } from "effect";
 import { ZodError } from "zod";
 import { isTaggedError } from "./error";
 
+/**
+ * The outcome of a failable operation. This type represents either a successful result or an error.
+ *
+ * - If the operation was successful, `result.ok` contains the success value, and `result.err` is `null`.
+ * - If the operation failed, `result.err` contains the error value, and `result.ok` is `null`.
+ *
+ * @typeParam S - The type of the success value. This represents the data or result produced by the operation if it succeeds.
+ * @typeParam E - The type of the error value. This represents the error or exception encountered by the operation if it fails.
+ *
+ * @example
+ * ```ts
+ * declare result: Result<StoreId, Error>
+ * if(result.err) {
+ *    const err = result.err // err has type Error
+ *    console.log("the operation failed: ", result.err.message)
+ *    return
+ * }
+ * const id = result.ok // id has type StoreId
+ * ```
+ */
 export type Result<S, E> = { ok: S; err: null } | { ok: null; err: E };
 
 export const effectToResultAsync = <S, E extends Error>(

packages/client-vms/src/client.ts

@@ -64,8 +64,8 @@ export class NillionClient {
   /**
    * The constructor is private to enforces the use of the factory creator method.
    *
-   * @see NillionClient.create
    * @param _config - The configuration object for the NillionClient.
+   * @see NillionClient.create
    */
   private constructor(private _config: NillionClientConfig) {}
 
@@ -321,6 +321,14 @@ export class NillionClient {
     );
   }
 
+  /**
+   * Updates values at the given store id. Similar to {@link NillionClient.store}, this
+   * function takes care of converting from primitive values to Nada types automatically.
+   *
+   * @param args - An Object with the store id, values and time-to-live.
+   * @returns A promise resolving to the update's unique action id in the network.
+   * @see NillionClient.updateValue
+   */
   update(args: {
     id: StoreId | string;
     values: Record<NamedValue | string, NadaPrimitiveValue | StoreValueArgs>;
@@ -343,6 +351,14 @@ export class NillionClient {
     );
   }
 
+  /**
+   * Pay for the operation.
+   *
+   * Retrieves a quote from the leader, pays for it on nilchian and then returns a {@link PaymentReceipt}.
+   *
+   * @param args - An object containing the operation and its type.
+   * @returns An {@link E.Effect} that resolves to a {@link PaymentReceipt}.
+   */
   pay(args: {
     operation: IntoWasmQuotableOperation & { type: OperationType };
   }): E.Effect<PaymentReceipt, UnknownException> {
@@ -365,6 +381,12 @@ export class NillionClient {
     );
   }
 
+  /**
+   * Initiates execution of the specified program.
+   *
+   * @param args - An object containing program bindings, run-time values, and ids for values to retrieve.
+   * @returns A promise resolving to the {@link ComputeResultId}.
+   */
   runProgram(args: {
     bindings: ProgramBindings;
     values: NadaValues;
@@ -391,6 +413,13 @@ export class NillionClient {
     );
   }
 
+  /**
+   * Fetches the result from a program execution.
+   *
+   * @param args - An object containing the {@link ComputeResultId}.
+   * @returns A promise resolving to a Map of the programs output.
+   * @see NillionClient.runProgram
+   */
   fetchProgramOutput(args: {
     id: ComputeResultId | string;
   }): Promise<Result<Record<string, NadaPrimitiveValue>, UnknownException>> {
@@ -410,6 +439,12 @@ export class NillionClient {
     );
   }
 
+  /**
+   * Delete the {@link NadaValues} stored at {@link StoreId}.
+   *
+   * @param args - An object containing the {@link StoreId} to delete.
+   * @returns A promise resolving to the deleted {@link StoreId}.
+   */
   deleteValues(args: {
     id: StoreId | string;
   }): Promise<Result<StoreId, UnknownException>> {
@@ -424,16 +459,34 @@ export class NillionClient {
     );
   }
 
+  /**
+   * Fetch network details.
+   *
+   * @returns A promise resolving to the network's {@link ClusterDescriptor}.
+   */
   fetchClusterInfo(): Promise<Result<ClusterDescriptor, UnknownException>> {
     return pipe(this.vm.fetchClusterInfo(), effectToResultAsync);
   }
 
+  /**
+   * Asks the leader to quote the provided operation.
+   *
+   * @param args - An object containing the {@link Operation}.
+   * @returns A promise resolving to the {@link PriceQuote}.
+   * @see NillionClient.pay
+   */
   fetchOperationQuote(args: {
     operation: IntoWasmQuotableOperation & { type: OperationType };
   }): Promise<Result<PriceQuote, UnknownException>> {
     return pipe(this.vm.fetchOperationQuote(args), effectToResultAsync);
   }
 
+  /**
+   * Fetch the {@link NamedValue} at {@link StoreId}.
+   *
+   * @param args - An object containing the {@link StoreId}, {@link NamedValue} and {@link NadaValueType}.
+   * @returns A promise resolving to the {@link Result} containing a `Map` where the keys are {@link NamedValue} and the values are {@link NadaValue}.
+   */
   fetchValue(args: {
     id: StoreId;
     name: NamedValue;
@@ -465,6 +518,12 @@ export class NillionClient {
     );
   }
 
+  /**
+   * Store a program in the network.
+   *
+   * @param args - An object containing the {@link ProgramName} and the program as a {@link Uint8Array}.
+   * @returns A promise resolving to the {@link Result} containing the {@link ProgramId}.
+   */
   storeProgram(args: {
     name: ProgramName | string;
     program: Uint8Array;
@@ -486,6 +545,12 @@ export class NillionClient {
     );
   }
 
+  /**
+   * Stores {@link NadaValues} in the network.
+   *
+   * @param args - An object containing the values, time-to-live, and optional permissions.
+   * @returns A promise resolving to the {@link Result} containing the store id.
+   */
   storeValues(args: {
     values: NadaValues;
     ttl: Days;
@@ -512,6 +577,12 @@ export class NillionClient {
     );
   }
 
+  /**
+   * Updates the store id location with the provided values.
+   *
+   * @param args - An object containing the store id to update with updated values and time-to-live.
+   * @returns A promise resolving to the {@link Result} containing the {@link ActionId}.
+   */
   updateValue(args: {
     id: StoreId;
     values: NadaValues;
@@ -525,6 +596,12 @@ export class NillionClient {
     );
   }
 
+  /**
+   * Fetches a store id's permissions.
+   *
+   * @param args - An object containing the {@link StoreId}.
+   * @returns A promise resolving to the {@link Result} containing the {@link Permissions}.
+   */
   fetchPermissions(args: {
     id: StoreId | string;
   }): Promise<Result<Permissions, UnknownException>> {
@@ -545,6 +622,14 @@ export class NillionClient {
     );
   }
 
+  /**
+   * Sets the permissions for a stored value in the network.
+   *
+   * Existing permissions are overwritten.
+   *
+   * @param args - An object containing the {@link StoreId} and the new {@link Permisisons}.
+   * @returns A promise resolving to the {@link Result} containing the {@link ActionId}.
+   */
   setPermissions(args: {
     id: StoreId | string;
     permissions: Permissions;
@@ -564,5 +649,16 @@ export class NillionClient {
     );
   }
 
+  /**
+   * Creates a new instance of {@link NillionClient}.
+   *
+   * This factory method initializes a `NillionClient` instance using the provided configuration. Before invoking
+   * network calls, the async {@Link NillionClient.connect} method must be called.
+   *
+   * @param config - The configuration object providing settings for initializing the client, such as network settings, user seeds,
+   * and optional overrides.
+   * @returns A new instance of `NillionClient`.
+   * @see NillionClient.connect
+   */
   static create = (config: NillionClientConfig) => new NillionClient(config);
 }