From 14591a2feee11c084d74bd8206b758b1a24680ff Mon Sep 17 00:00:00 2001 From: april Date: Wed, 25 Sep 2024 12:40:56 +0100 Subject: [PATCH] docs: add documentation to `client-vms` --- packages/client-vms/src/logger.ts | 4 ++++ packages/client-vms/src/nada.ts | 13 ++++++++++++ packages/client-vms/src/nilvm/client.ts | 28 +++++++++++++++++++++++++ packages/client-vms/src/types.ts | 17 +++++++++++++++ 4 files changed, 62 insertions(+) diff --git a/packages/client-vms/src/logger.ts b/packages/client-vms/src/logger.ts index fca3347..4bdf50a 100644 --- a/packages/client-vms/src/logger.ts +++ b/packages/client-vms/src/logger.ts @@ -1,4 +1,8 @@ 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:vms"); Log.log = console.log.bind(console); diff --git a/packages/client-vms/src/nada.ts b/packages/client-vms/src/nada.ts index 8ffef82..48080eb 100644 --- a/packages/client-vms/src/nada.ts +++ b/packages/client-vms/src/nada.ts @@ -10,6 +10,19 @@ import { import { StoreValueArgs } from "./types"; +/** + * `toNadaValues` is a function that takes a `NamedValue` or `string` and a `NadaPrimitiveValue` or `StoreValueArgs` and returns a `NadaValues` object. + * @param args: {@link toNadaValuesArgs} + * @returns {@link NadaValues} + * @throws + * @example + * ```ts + * const nadaValues = toNadaValues({ + * name: "myValue", + * value: "myValueData", + * }); + * ``` + */ export const toNadaValues = (args: { name: NamedValue | string; value: NadaPrimitiveValue | StoreValueArgs; diff --git a/packages/client-vms/src/nilvm/client.ts b/packages/client-vms/src/nilvm/client.ts index 8ec0122..455146f 100644 --- a/packages/client-vms/src/nilvm/client.ts +++ b/packages/client-vms/src/nilvm/client.ts @@ -34,6 +34,11 @@ import * as Wasm from "@nillion/client-wasm"; import { Log } from "../logger"; +/* `NilVmClientConfig` is an object that contains the configuration for the NilVmClient + * @param bootnodes: `Multiaddr[]` + * @param clusterId: `ClusterId` + * @param userSeed: `string` + */ export const NilVmClientConfig = z.object({ bootnodes: z.array(Multiaddr), clusterId: ClusterId, @@ -43,6 +48,10 @@ export const NilVmClientConfig = z.object({ export type NilVmClientConfig = z.infer; +/** + * `NilVmClient` is a class that allows you to interact with Nillion. + * @class + */ export class NilVmClient { // The wasm bundle is loaded asynchronously which can be problematic because most environments don't // support top-level awaits. To manage this complexity `this._client` is lazily initialized and guarded @@ -54,29 +63,35 @@ export class NilVmClient { private constructor(private _config: NilVmClientConfig) {} + /* `ready` is a boolean that indicates whether the client is ready to be used */ get ready(): boolean { return this._ready; } + /* `partyId` is a `PartyId` object that represents the party ID of the client */ get partyId(): PartyId { this.isReadyGuard(); return PartyId.parse(this._client.party_id); } + /* `userId` is a `UserId` object that represents the user ID of the client */ get userId(): UserId { this.isReadyGuard(); return UserId.parse(this._client.user_id); } + /* `clusterId` is a `ClusterId` object that represents the cluster ID of the client */ get clusterId(): ClusterId { return this._config.clusterId; } + /* `client` is a `Wasm.NillionClient` object that represents the client */ get client(): Wasm.NillionClient { this.isReadyGuard(); return this._client; } + /* `connect` is an async function that connects the client to the cluster */ async connect(): Promise { if (!globalThis.__NILLION?.initialized) { await init(); @@ -95,6 +110,7 @@ export class NilVmClient { return this._ready; } + /* `isReadyGuard` is a function that checks if the client is ready */ private isReadyGuard(): void | never { if (!this._ready) { const message = "NilVmClient not ready. Call `await client.connect()`."; @@ -103,6 +119,7 @@ export class NilVmClient { } } + /* `fetchClusterInfo` is an effect that fetches the cluster information */ fetchClusterInfo(): E.Effect { return E.tryPromise(async () => { const response = await this.client.cluster_information(this.clusterId); @@ -112,6 +129,7 @@ export class NilVmClient { }); } + /* `fetchComputeOutput` is an effect that fetches the compute */ fetchComputeOutput(args: { id: ComputeOutputId; }): E.Effect, UnknownException> { @@ -126,6 +144,7 @@ export class NilVmClient { }); } + /* `fetchOperationQuote` is an effect that fetches the operation quote */ fetchOperationQuote(args: { operation: IntoWasmQuotableOperation & { type: OperationType }; }): E.Effect { @@ -141,6 +160,7 @@ export class NilVmClient { }); } + /* `fetchValue` is an effect that fetches the value */ fetchValue(args: { receipt: PaymentReceipt; operation: FetchValue; @@ -165,6 +185,7 @@ export class NilVmClient { }); } + /* `fetchStoreAcl` is an effect that fetches the store acl */ fetchStoreAcl(args: { receipt: PaymentReceipt; operation: FetchStoreAcl; @@ -188,6 +209,7 @@ export class NilVmClient { }); } + /* `setStoreAcl` is an effect that sets the store acl */ setStoreAcl(args: { receipt: PaymentReceipt; operation: SetStoreAcl; @@ -214,6 +236,7 @@ export class NilVmClient { }); } + /* `compute` is an effect that computes the operation */ compute(args: { receipt: PaymentReceipt; operation: Compute; @@ -241,6 +264,7 @@ export class NilVmClient { }); } + /* `storeProgram` is an effect that stores the program */ storeProgram(args: { receipt: PaymentReceipt; operation: StoreProgram; @@ -265,6 +289,7 @@ export class NilVmClient { }); } + /* `deleteProgram` is an effect that deletes the program */ deleteValues(args: { id: StoreId }): E.Effect { return E.tryPromise(async () => { const { id } = args; @@ -274,6 +299,7 @@ export class NilVmClient { }); } + /* `deleteProgram` is an effect that deletes the program */ updateValues(args: { receipt: PaymentReceipt; operation: UpdateValue; @@ -299,6 +325,7 @@ export class NilVmClient { }); } + /* `storeValues` is an effect that stores the values */ storeValues(args: { receipt: PaymentReceipt; operation: StoreValue; @@ -326,5 +353,6 @@ export class NilVmClient { }); } + /* `create` is a static function that creates a new NilVmClient */ static create = (args: NilVmClientConfig) => new NilVmClient(args); } diff --git a/packages/client-vms/src/types.ts b/packages/client-vms/src/types.ts index 316406a..2004aae 100644 --- a/packages/client-vms/src/types.ts +++ b/packages/client-vms/src/types.ts @@ -11,11 +11,22 @@ import { UserSeed, } from "@nillion/client-core"; +/** `StoreValueArgs` is an interface that can be passed to the `store` function + * @param data: `NadaPrimitiveValue + * @param secret: `boolean` + */ export interface StoreValueArgs { data: NadaPrimitiveValue; secret: boolean; } +/** `NetworkConfig` is an interface that can be passed to the `toNadaValues` function + * @param bootnotes: `Multiaddr[]` + * @param clusterId: `ClusterId` + * @param nilChainId: `ChainId` + * @param nilChainEndpoint: `Url` + * @type + */ export const NetworkConfig = z.object({ bootnodes: z.array(Multiaddr), clusterId: ClusterId, @@ -24,6 +35,12 @@ export const NetworkConfig = z.object({ }); export type NetworkConfig = z.infer; +/** `UserCredentials` is an interface that can be passed to the `toNadaValues` function + * @param nodeSeed: `NodeSeed` + * @param signer: `OfflineSigner` + * @param userSeed: `UserSeed` + * @type + */ export const UserCredentials = z.object({ userSeed: UserSeed, nodeSeed: NodeSeed.default(() => window.crypto.randomUUID()),