From b95783db54d8a5294c7f10e67ccb0f2c529aef75 Mon Sep 17 00:00:00 2001 From: ahsan-javaid Date: Thu, 26 May 2022 14:51:35 +0500 Subject: [PATCH] fix: add clarity typedoc annotations --- .../transactions/src/clarity/deserialize.ts | 22 +++++ .../transactions/src/clarity/serialize.ts | 19 +++++ .../src/clarity/types/booleanCV.ts | 33 ++++++++ .../src/clarity/types/bufferCV.ts | 42 ++++++++++ .../transactions/src/clarity/types/intCV.ts | 36 ++++++++ .../transactions/src/clarity/types/listCV.ts | 18 ++++ .../src/clarity/types/optionalCV.ts | 34 ++++++++ .../src/clarity/types/principalCV.ts | 83 +++++++++++++++++++ .../src/clarity/types/responseCV.ts | 38 +++++++++ .../src/clarity/types/stringCV.ts | 41 +++++++++ .../transactions/src/clarity/types/tupleCV.ts | 22 +++++ 11 files changed, 388 insertions(+) diff --git a/packages/transactions/src/clarity/deserialize.ts b/packages/transactions/src/clarity/deserialize.ts index f9da517e1..297db6903 100644 --- a/packages/transactions/src/clarity/deserialize.ts +++ b/packages/transactions/src/clarity/deserialize.ts @@ -21,6 +21,28 @@ import { deserializeAddress, deserializeLPString } from '../types'; import { DeserializationError } from '../errors'; import { stringAsciiCV, stringUtf8CV } from './types/stringCV'; +/** + * Deserializes clarity value to clarity type + * + * @param {value} Buffer | string value to be converted to clarity type + ** + * @returns {ClarityType} returns the clarity type instance + * + * @example + * ```typescript + * import { intCV, serializeCV, deserializeCV } from '@stacks/transactions'; + * + * const serialized = serializeCV(intCV(100)); // Similarly works for other clarity types as well like listCV, booleanCV ... + * + * // + * + * const deserialized = deserializeCV(serialized); + * // { type: 0, value: 100n } + * ``` + * + * @visit + * {@link https://github.com/hirosystems/stacks.js/blob/master/packages/transactions/tests/clarity.test.ts clarity test cases for more examples} + */ export default function deserializeCV( serializedClarityValue: BufferReader | Buffer | string ): T { diff --git a/packages/transactions/src/clarity/serialize.ts b/packages/transactions/src/clarity/serialize.ts index 5cfe96da1..98a78bd22 100644 --- a/packages/transactions/src/clarity/serialize.ts +++ b/packages/transactions/src/clarity/serialize.ts @@ -128,6 +128,25 @@ function serializeStringUtf8CV(cv: StringUtf8CV) { return serializeStringCV(cv, 'utf8'); } +/** + * Serializes clarity value to buffer + * + * @param {value} clarity value to be converted to buffer + ** + * @returns {Buffer} returns the buffer instance + * + * @example + * ```typescript + * import { intCV, serializeCV } from '@stacks/transactions'; + * + * const serialized = serializeCV(intCV(100)); // Similarly works for other clarity types as well like listCV, booleanCV ... + * + * // + * ``` + * + * @visit + * {@link https://github.com/hirosystems/stacks.js/blob/master/packages/transactions/tests/clarity.test.ts clarity test cases for more examples} + */ export function serializeCV(value: ClarityValue): Buffer { switch (value.type) { case ClarityType.BoolTrue: diff --git a/packages/transactions/src/clarity/types/booleanCV.ts b/packages/transactions/src/clarity/types/booleanCV.ts index d9765cd87..66aed4d7c 100644 --- a/packages/transactions/src/clarity/types/booleanCV.ts +++ b/packages/transactions/src/clarity/types/booleanCV.ts @@ -10,7 +10,40 @@ interface FalseCV { type: ClarityType.BoolFalse; } +/** + * Converts true to BooleanCV clarity type + * + * @returns {BooleanCV} returns instance of type BooleanCV + * + * @example + * ```typescript + * import { trueCV } from '@stacks/transactions'; + * + * const trueCV = trueCV(); + * // { type: 3 } + * ``` + * + * @visit + * {@link https://github.com/hirosystems/stacks.js/blob/master/packages/transactions/tests/clarity.test.ts clarity test cases for more examples} + */ const trueCV = (): BooleanCV => ({ type: ClarityType.BoolTrue }); + +/** + * Converts false to BooleanCV clarity type + * + * @returns {BooleanCV} returns instance of type BooleanCV + * + * @example + * ```typescript + * import { falseCV } from '@stacks/transactions'; + * + * const falseCV = falseCV(); + * // { type: 4 } + * ``` + * + * @visit + * {@link https://github.com/hirosystems/stacks.js/blob/master/packages/transactions/tests/clarity.test.ts clarity test cases for more examples} + */ const falseCV = (): BooleanCV => ({ type: ClarityType.BoolFalse }); export { BooleanCV, TrueCV, FalseCV, trueCV, falseCV }; diff --git a/packages/transactions/src/clarity/types/bufferCV.ts b/packages/transactions/src/clarity/types/bufferCV.ts index c349c7811..e047ba4b6 100644 --- a/packages/transactions/src/clarity/types/bufferCV.ts +++ b/packages/transactions/src/clarity/types/bufferCV.ts @@ -6,6 +6,27 @@ interface BufferCV { readonly buffer: Buffer; } +/** + * Converts a buffer to BufferCV clarity type + * + * @param {buffer} buffer value to be converted to clarity type + * + * @returns {BufferCV} returns instance of type BufferCV + * + * @example + * ```typescript + * import { bufferCV } from '@stacks/transactions'; + * + * const buffer = Buffer.from('this is a test'); + * const buf = bufferCV(buffer); + * // { type: 2, buffer: } + * const value = buf.buffer.toString(); + * // this is a test + * ``` + * + * @visit + * {@link https://github.com/hirosystems/stacks.js/blob/master/packages/transactions/tests/clarity.test.ts clarity test cases for more examples} + */ const bufferCV = (buffer: Buffer): BufferCV => { if (buffer.length > 1000000) { throw new Error('Cannot construct clarity buffer that is greater than 1MB'); @@ -14,6 +35,27 @@ const bufferCV = (buffer: Buffer): BufferCV => { return { type: ClarityType.Buffer, buffer }; }; +/** + * Converts a string to BufferCV clarity type + * + * @param {str} string input to be converted to bufferCV clarity type + * + * @returns {BufferCV} returns instance of type BufferCV + * + * @example + * ```typescript + * import { bufferCVFromString } from '@stacks/transactions'; + * + * const str = 'this is a test'; + * const buf = bufferCVFromString(str); + * // { type: 2, buffer: } + * const value = buf.buffer.toString(); + * // this is a test + *``` + * + * @visit + * {@link https://github.com/hirosystems/stacks.js/blob/master/packages/transactions/tests/clarity.test.ts clarity test cases for more examples} + */ const bufferCVFromString = (str: string): BufferCV => bufferCV(Buffer.from(str)); export { BufferCV, bufferCV, bufferCVFromString }; diff --git a/packages/transactions/src/clarity/types/intCV.ts b/packages/transactions/src/clarity/types/intCV.ts index 1cf064a41..5696f95f9 100644 --- a/packages/transactions/src/clarity/types/intCV.ts +++ b/packages/transactions/src/clarity/types/intCV.ts @@ -12,6 +12,24 @@ interface IntCV { readonly value: bigint; } +/** + * Converts IntegerType in to IntCV clarity type + * + * @param {value} integer value to be converted to IntCV clarity type + * + * @returns {IntCV} returns instance of type IntCV + * + * @example + * ```typescript + * import { intCV } from '@stacks/transactions'; + * + * const value = intCV('100'); // parameter any of type: number | string | bigint | Uint8Array | BN + * // { type: 0, value: 100n } + * ``` + * + * @visit + * {@link https://github.com/hirosystems/stacks.js/blob/master/packages/transactions/tests/clarity.test.ts clarity test cases for more examples} + */ const intCV = (value: IntegerType): IntCV => { const bigInt = intToBigInt(value, true); if (bigInt > MAX_I128) { @@ -31,6 +49,24 @@ interface UIntCV { readonly value: bigint; } +/** + * Converts IntegerType in to IntCV clarity type + * + * @param {value} integer value to be converted to UIntCV clarity type (Only unsigned integer is allowed otherwise throws exception) + * + * @returns {UIntCV} returns instance of type UIntCV + * + * @example + * ```typescript + * import { uintCV } from '@stacks/transactions'; + * + * const value = uintCV('100'); // parameter any of type: number | string | bigint | Uint8Array | BN + * // { type: 1, value: 100n } + * ``` + * + * @visit + * {@link https://github.com/hirosystems/stacks.js/blob/master/packages/transactions/tests/clarity.test.ts clarity test cases for more examples} + */ const uintCV = (value: IntegerType): UIntCV => { const bigInt = intToBigInt(value, false); if (bigInt < MIN_U128) { diff --git a/packages/transactions/src/clarity/types/listCV.ts b/packages/transactions/src/clarity/types/listCV.ts index ef4900c70..13fd1f4f2 100644 --- a/packages/transactions/src/clarity/types/listCV.ts +++ b/packages/transactions/src/clarity/types/listCV.ts @@ -6,6 +6,24 @@ interface ListCV { list: T[]; } +/** + * Create list of clarity types + * + * @param {ClarityValue>values: T[]} list of ClarityValues to be converted to ListCV clarity type + * + * @returns {ListCV} returns instance of type ListCV + * + * @example + * ```typescript + * import { listCV, intCV } from '@stacks/transactions'; + * + * const list = listCV([intCV(1), intCV(2), intCV(3), intCV(-4)]); + * // { type: 11, list: [ { type: 0, value: 1n }, { type: 0, value: 2n }, { type: 0, value: 3n }, { type: 0, value: -4n } ] } + * ``` + * + * @visit + * {@link https://github.com/hirosystems/stacks.js/blob/master/packages/transactions/tests/clarity.test.ts clarity test cases for more examples} + */ function listCV(values: T[]): ListCV { return { type: ClarityType.List, list: values }; } diff --git a/packages/transactions/src/clarity/types/optionalCV.ts b/packages/transactions/src/clarity/types/optionalCV.ts index 6979e1c4c..0c763c0ab 100644 --- a/packages/transactions/src/clarity/types/optionalCV.ts +++ b/packages/transactions/src/clarity/types/optionalCV.ts @@ -11,10 +11,44 @@ interface SomeCV { readonly value: T; } +/** + * Create a null clarity type + ** + * @returns {NoneCV} returns instance of type NoneCV + * + * @example + * ```typescript + * import { noneCV } from '@stacks/transactions'; + * + * const value = noneCV(); + * // { type: 9 } + * ``` + * + * @visit + * {@link https://github.com/hirosystems/stacks.js/blob/master/packages/transactions/tests/clarity.test.ts clarity test cases for more examples} + */ function noneCV(): NoneCV { return { type: ClarityType.OptionalNone }; } +/** + * Converts any ClarityValue in to OptionalCV clarity type + * + * @param {ClarityValue} value to be converted to OptionalCV clarity type + * + * @returns {OptionalCV} returns instance of type OptionalCV + * + * @example + * ```typescript + * import { someCV, trueCV } from '@stacks/transactions'; + * + * const value = someCV(trueCV()); + * // { type: 10, value: { type: 3 } } + * ``` + * + * @visit + * {@link https://github.com/hirosystems/stacks.js/blob/master/packages/transactions/tests/clarity.test.ts clarity test cases for more examples} + */ function someCV(value: T): OptionalCV { return { type: ClarityType.OptionalSome, value }; } diff --git a/packages/transactions/src/clarity/types/principalCV.ts b/packages/transactions/src/clarity/types/principalCV.ts index 45806aea2..f4fa3811c 100644 --- a/packages/transactions/src/clarity/types/principalCV.ts +++ b/packages/transactions/src/clarity/types/principalCV.ts @@ -36,21 +36,104 @@ function principalCV(principal: string): PrincipalCV { } } +/** + * Converts stx address in to StandardPrincipalCV clarity type + * + * @param {addressString} string value to be converted to StandardPrincipalCV clarity type + * + * @returns {StandardPrincipalCV} returns instance of type StandardPrincipalCV + * + * @example + * ```typescript + * import { standardPrincipalCV } from '@stacks/transactions'; + * + * const addr = standardPrincipalCV('SP2JXKMSH007NPYAQHKJPQMAQYAD90NQGTVJVQ02B'); + * // { type: 5, address: { type: 0, version: 22, hash160: 'a5d9d331000f5b79578ce56bd157f29a9056f0d6' } } + * ``` + * + * @visit + * {@link https://github.com/hirosystems/stacks.js/blob/master/packages/transactions/tests/clarity.test.ts clarity test cases for more examples} + */ function standardPrincipalCV(addressString: string): StandardPrincipalCV { const addr = createAddress(addressString); return { type: ClarityType.PrincipalStandard, address: addr }; } +/** + * Converts stx address in to StandardPrincipalCV clarity type + * + * @param {addressString} string value to be converted to StandardPrincipalCV clarity type + * + * @returns {StandardPrincipalCV} returns instance of type StandardPrincipalCV + * + * @example + * ```typescript + * import { standardPrincipalCVFromAddress, Address } from '@stacks/transactions'; + * + * const address: Address = { + * type: 0, + * version: 22, + * hash160: 'a5d9d331000f5b79578ce56bd157f29a9056f0d6' + * }; + * + * const principalCV = standardPrincipalCVFromAddress(address); + * // { type: 5, address: { type: 0, version: 22, hash160: 'a5d9d331000f5b79578ce56bd157f29a9056f0d6' } } + * ``` + * + * @visit + * {@link https://github.com/hirosystems/stacks.js/blob/master/packages/transactions/tests/clarity.test.ts clarity test cases for more examples} + */ function standardPrincipalCVFromAddress(address: Address): StandardPrincipalCV { return { type: ClarityType.PrincipalStandard, address }; } +/** + * Converts stx address in to ContractPrincipalCV clarity type + * + * @param {addressString} string value to be converted to ContractPrincipalCV clarity type + + * @param {contractName} string containing contract name + * + * @returns {ContractPrincipalCV} returns instance of type ContractPrincipalCV + * + * @example + * ```typescript + * import { contractPrincipalCV } from '@stacks/transactions'; + * + * const contractAddress = contractPrincipalCV('SP2JXKMSH007NPYAQHKJPQMAQYAD90NQGTVJVQ02B', 'test'); + * // { type: 6, address: { type: 0, version: 22, hash160: 'a5d9d331000f5b79578ce56bd157f29a9056f0d6' }, contractName: { type: 2, content: 'test', lengthPrefixBytes: 1, maxLengthBytes: 128 } } + * ``` + * + * @visit + * {@link https://github.com/hirosystems/stacks.js/blob/master/packages/transactions/tests/clarity.test.ts clarity test cases for more examples} + */ function contractPrincipalCV(addressString: string, contractName: string): ContractPrincipalCV { const addr = createAddress(addressString); const lengthPrefixedContractName = createLPString(contractName); return contractPrincipalCVFromAddress(addr, lengthPrefixedContractName); } +/** + * Create ContractPrincipalCV from Address type + * + * @param {address} address value to be converted to ContractPrincipalCV clarity type + * + * @param {contractName} contract name of type LengthPrefixedString + * + * @returns {ContractPrincipalCV} returns instance of type ContractPrincipalCV + * + * @example + * ```typescript + * import { contractPrincipalCVFromAddress, createLPString, createAddress } from '@stacks/transactions'; + * + * const contractAddressCV = contractPrincipalCVFromAddress(createAddress('SP2JXKMSH007NPYAQHKJPQMAQYAD90NQGTVJVQ02B'), createLPString('test')); + * + * // { type: 6, address: { type: 0, version: 22, hash160: 'a5d9d331000f5b79578ce56bd157f29a9056f0d6' }, contractName: { type: 2, content: 'test', lengthPrefixBytes: 1, maxLengthBytes: 128 } } + * ``` + * + * @visit + * {@link https://github.com/hirosystems/stacks.js/blob/master/packages/transactions/tests/clarity.test.ts clarity test cases for more examples} + */ function contractPrincipalCVFromAddress( address: Address, contractName: LengthPrefixedString diff --git a/packages/transactions/src/clarity/types/responseCV.ts b/packages/transactions/src/clarity/types/responseCV.ts index 6cf11a295..ed036f859 100644 --- a/packages/transactions/src/clarity/types/responseCV.ts +++ b/packages/transactions/src/clarity/types/responseCV.ts @@ -13,10 +13,48 @@ interface ResponseOkCV { readonly value: T; } +/** + * Converts ClarityValue to responseErrorCV + * + * @param {value} ClarityValue value to be converted to responseErrorCV clarity type + * + * @returns {responseErrorCV} returns instance of type responseErrorCV + * + * @example + * ```typescript + * import { responseErrorCV, intCV } from '@stacks/transactions'; + * + * const respErrorCV = responseErrorCV(intCV(1)); + * + * // { type: 8, value: { type: 0, value: 1n } } + * ``` + * + * @visit + * {@link https://github.com/hirosystems/stacks.js/blob/master/packages/transactions/tests/clarity.test.ts clarity test cases for more examples} + */ function responseErrorCV(value: T): ResponseErrorCV { return { type: ClarityType.ResponseErr, value }; } +/** + * Converts ClarityValue to ResponseOkCV + * + * @param {value} ClarityValue value to be converted to ResponseOkCV clarity type + * + * @returns {ResponseOkCV} returns instance of type ResponseOkCV + * + * @example + * ```typescript + * import { responseOkCV, intCV } from '@stacks/transactions'; + * + * const respOKCV = responseOkCV(intCV(1)); + * + * // { type: 7, value: { type: 0, value: 1n } } + * ``` + * + * @visit + * {@link https://github.com/hirosystems/stacks.js/blob/master/packages/transactions/tests/clarity.test.ts clarity test cases for more examples} + */ function responseOkCV(value: T): ResponseOkCV { return { type: ClarityType.ResponseOk, value }; } diff --git a/packages/transactions/src/clarity/types/stringCV.ts b/packages/transactions/src/clarity/types/stringCV.ts index 7ace9e38b..5f3725149 100644 --- a/packages/transactions/src/clarity/types/stringCV.ts +++ b/packages/transactions/src/clarity/types/stringCV.ts @@ -10,14 +10,55 @@ interface StringUtf8CV { readonly data: string; } +/** + * Converts ClarityValue to stringAsciiCV + * + * @param {data} ClarityValue value to be converted to stringAsciiCV clarity type + * + * @returns {StringAsciiCV} returns instance of type StringAsciiCV + * + * @example + * ```typescript + * import { stringAsciiCV } from '@stacks/transactions'; + * + * const stringAscii = stringAsciiCV('test'); + * + * // { type: 13, data: 'hello' } + * ``` + * + * @visit + * {@link https://github.com/hirosystems/stacks.js/blob/master/packages/transactions/tests/clarity.test.ts clarity test cases for more examples} + */ const stringAsciiCV = (data: string): StringAsciiCV => { return { type: ClarityType.StringASCII, data }; }; +/** + * Converts ClarityValue to stringUtf8CV + * + * @param {data} ClarityValue value to be converted to stringUtf8CV clarity type + * + * @returns {stringUtf8CV} returns instance of type stringUtf8CV + * + * @example + * ```typescript + * import { stringUtf8CV } from '@stacks/transactions'; + * + * const stringUTF8 = stringUtf8CV('test'); + * + * // { type: 13, data: 'hello' } + * ``` + * + * @visit + * {@link https://github.com/hirosystems/stacks.js/blob/master/packages/transactions/tests/clarity.test.ts clarity test cases for more examples} + */ const stringUtf8CV = (data: string): StringUtf8CV => { return { type: ClarityType.StringUTF8, data }; }; +/** + * @ignore + */ const stringCV = (data: string, encoding: 'ascii' | 'utf8'): StringAsciiCV | StringUtf8CV => { switch (encoding) { case 'ascii': diff --git a/packages/transactions/src/clarity/types/tupleCV.ts b/packages/transactions/src/clarity/types/tupleCV.ts index 147441ad6..8f3014617 100644 --- a/packages/transactions/src/clarity/types/tupleCV.ts +++ b/packages/transactions/src/clarity/types/tupleCV.ts @@ -9,6 +9,28 @@ interface TupleCV { data: T; } +/** + * Create tuple of clarity values + * + * @param {tupleData} tuple value to be converted to tuple of clarity types + * + * @returns {TupleCV} returns instance of type clarity tuple + * + * @example + * ```typescript + * import { tupleCV, trueCV, falseCV } from '@stacks/transactions'; + * + * const tuple = tupleCV({ + * c: trueCV(), + * b: falseCV(), + * a: trueCV(), + * }); + * // { type: 12, data: { c: { type: 3 }, b: { type: 4 }, a: { type: 3 } } } + * ``` + * + * @visit + * {@link https://github.com/hirosystems/stacks.js/blob/master/packages/transactions/tests/clarity.test.ts clarity test cases for more examples} + */ function tupleCV(data: TupleData): TupleCV> { for (const key in data) { if (!isClarityName(key)) {