@aptos-labs/ts-sdk 1.29.0 → 1.30.0

package/src/transactions/typeTag/index.ts

@@ -10,9 +10,30 @@ import { AccountAddress } from "../../core";
 import { Identifier } from "../instances/identifier";
 import { TypeTagVariants } from "../../types";
 
+/**
+ * Represents a type tag in the serialization framework, serving as a base class for various specific type tags.
+ * This class provides methods for serialization and deserialization of type tags, as well as type checking methods
+ * to determine the specific type of the tag at runtime.
+ *
+ * @extends Serializable
+ */
 export abstract class TypeTag extends Serializable {
   abstract serialize(serializer: Serializer): void;
 
+  /**
+   * Deserializes a StructTag from the provided deserializer.
+   * This function allows you to reconstruct a StructTag object from its serialized form.
+   *
+   * @param deserializer - The deserializer instance used to read the serialized data.
+   */
+  deserialize(deserializer: Deserializer): StructTag {
+    const address = AccountAddress.deserialize(deserializer);
+    const moduleName = Identifier.deserialize(deserializer);
+    const name = Identifier.deserialize(deserializer);
+    const typeArgs = deserializer.deserializeVector(TypeTag);
+    return new StructTag(address, moduleName, name, typeArgs);
+  }
+
   static deserialize(deserializer: Deserializer): TypeTag {
     const index = deserializer.deserializeUleb128AsU32();
     switch (index) {
@@ -48,69 +69,175 @@ export abstract class TypeTag extends Serializable {
 
   abstract toString(): string;
 
+  /**
+   * Determines if the current instance is of type TypeTagBool.
+   *
+   * @returns {boolean} True if the instance is a TypeTagBool, otherwise false.
+   */
   isBool(): this is TypeTagBool {
     return this instanceof TypeTagBool;
   }
 
+  /**
+   * Determines if the current instance is of type TypeTagAddress.
+   *
+   * @returns {boolean} True if the instance is a TypeTagAddress, otherwise false.
+   */
   isAddress(): this is TypeTagAddress {
     return this instanceof TypeTagAddress;
   }
 
+  /**
+   * Determines if the current instance is of type TypeTagGeneric.
+   *
+   * @returns {boolean} Returns true if the instance is a TypeTagGeneric, otherwise false.
+   */
   isGeneric(): this is TypeTagGeneric {
     return this instanceof TypeTagGeneric;
   }
 
+  /**
+   * Determine if the current instance is a TypeTagSigner.
+   *
+   * @returns {boolean} Returns true if the instance is a TypeTagSigner, otherwise false.
+   */
   isSigner(): this is TypeTagSigner {
     return this instanceof TypeTagSigner;
   }
 
+  /**
+   * Checks if the current instance is a vector type.
+   * This can help determine the specific type of data structure being used.
+   *
+   * @returns {boolean} True if the instance is of type TypeTagVector, otherwise false.
+   */
   isVector(): this is TypeTagVector {
     return this instanceof TypeTagVector;
   }
 
+  /**
+   * Determines if the current instance is a structure type.
+   *
+   * @returns {boolean} True if the instance is of type TypeTagStruct, otherwise false.
+   */
   isStruct(): this is TypeTagStruct {
     return this instanceof TypeTagStruct;
   }
 
+  /**
+   * Determines if the current instance is of type `TypeTagU8`.
+   *
+   * @returns {boolean} Returns true if the instance is of type `TypeTagU8`, otherwise false.
+   */
   isU8(): this is TypeTagU8 {
     return this instanceof TypeTagU8;
   }
 
+  /**
+   * Checks if the current instance is of type TypeTagU16.
+   *
+   * @returns {boolean} True if the instance is TypeTagU16, otherwise false.
+   */
   isU16(): this is TypeTagU16 {
     return this instanceof TypeTagU16;
   }
 
+  /**
+   * Checks if the current instance is of type TypeTagU32.
+   *
+   * @returns {boolean} Returns true if the instance is TypeTagU32, otherwise false.
+   */
   isU32(): this is TypeTagU32 {
     return this instanceof TypeTagU32;
   }
 
+  /**
+   * Checks if the current instance is of type TypeTagU64.
+   *
+   * @returns {boolean} True if the instance is a TypeTagU64, otherwise false.
+   */
   isU64(): this is TypeTagU64 {
     return this instanceof TypeTagU64;
   }
 
+  /**
+   * Determines if the current instance is of the TypeTagU128 type.
+   *
+   * @returns {boolean} True if the instance is of TypeTagU128, otherwise false.
+   */
   isU128(): this is TypeTagU128 {
     return this instanceof TypeTagU128;
   }
 
+  /**
+   * Checks if the current instance is of type TypeTagU256.
+   *
+   * @returns {boolean} Returns true if the instance is of type TypeTagU256, otherwise false.
+   */
   isU256(): this is TypeTagU256 {
     return this instanceof TypeTagU256;
   }
+
+  isPrimitive(): boolean {
+    return (
+      this instanceof TypeTagSigner ||
+      this instanceof TypeTagAddress ||
+      this instanceof TypeTagBool ||
+      this instanceof TypeTagU8 ||
+      this instanceof TypeTagU16 ||
+      this instanceof TypeTagU32 ||
+      this instanceof TypeTagU64 ||
+      this instanceof TypeTagU128 ||
+      this instanceof TypeTagU256
+    );
+  }
 }
 
+/**
+ * Represents a boolean type tag in the type system.
+ * This class extends the base TypeTag class and provides
+ * methods for serialization and deserialization of the boolean
+ * type tag.
+ *
+ * @extends TypeTag
+ */
 export class TypeTagBool extends TypeTag {
+  /**
+   * Returns the string representation of the object.
+   *
+   * @returns {string} The string representation of the object.
+   */
   toString(): string {
     return "bool";
   }
 
+  /**
+   * Serializes the current instance's properties into a provided serializer.
+   * This function ensures that the address, module name, name, and type arguments are properly serialized.
+   *
+   * @param serializer - The serializer instance used to serialize the properties.
+   */
   serialize(serializer: Serializer): void {
     serializer.serializeU32AsUleb128(TypeTagVariants.Bool);
   }
 
+  /**
+   * Deserializes a StructTag and returns a new TypeTagStruct instance.
+   *
+   * @param _deserializer - The deserializer used to read the StructTag data.
+   */
   static load(_deserializer: Deserializer): TypeTagBool {
     return new TypeTagBool();
   }
 }
 
+/**
+ * Represents a type tag for an 8-bit unsigned integer (u8).
+ * This class extends the base TypeTag class and provides methods
+ * for serialization and deserialization specific to the u8 type.
+ *
+ * @extends TypeTag
+ */
 export class TypeTagU8 extends TypeTag {
   toString(): string {
     return "u8";
@@ -125,6 +252,12 @@ export class TypeTagU8 extends TypeTag {
   }
 }
 
+/**
+ * Represents a type tag for unsigned 16-bit integers (u16).
+ * This class extends the base TypeTag class and provides methods for serialization and deserialization.
+ *
+ * @extends TypeTag
+ */
 export class TypeTagU16 extends TypeTag {
   toString(): string {
     return "u16";
@@ -139,6 +272,13 @@ export class TypeTagU16 extends TypeTag {
   }
 }
 
+/**
+ * Represents a type tag for a 32-bit unsigned integer (u32).
+ * This class extends the base TypeTag class and provides methods for serialization
+ * and deserialization specific to the u32 type.
+ *
+ * @extends TypeTag
+ */
 export class TypeTagU32 extends TypeTag {
   toString(): string {
     return "u32";
@@ -153,6 +293,12 @@ export class TypeTagU32 extends TypeTag {
   }
 }
 
+/**
+ * Represents a type tag for 64-bit unsigned integers (u64).
+ * This class extends the base TypeTag class and provides methods for serialization and deserialization.
+ *
+ * @extends TypeTag
+ */
 export class TypeTagU64 extends TypeTag {
   toString(): string {
     return "u64";
@@ -167,6 +313,12 @@ export class TypeTagU64 extends TypeTag {
   }
 }
 
+/**
+ * Represents a type tag for the u128 data type.
+ * This class extends the base TypeTag class and provides methods for serialization and deserialization.
+ *
+ * @extends TypeTag
+ */
 export class TypeTagU128 extends TypeTag {
   toString(): string {
     return "u128";
@@ -181,6 +333,12 @@ export class TypeTagU128 extends TypeTag {
   }
 }
 
+/**
+ * Represents a type tag for the U256 data type.
+ * This class extends the base TypeTag class and provides methods for serialization and deserialization.
+ *
+ * @extends TypeTag
+ */
 export class TypeTagU256 extends TypeTag {
   toString(): string {
     return "u256";
@@ -195,6 +353,13 @@ export class TypeTagU256 extends TypeTag {
   }
 }
 
+/**
+ * Represents a type tag for an address in the system.
+ * This class extends the TypeTag class and provides functionality
+ * to serialize the address type and load it from a deserializer.
+ *
+ * @extends TypeTag
+ */
 export class TypeTagAddress extends TypeTag {
   toString(): string {
     return "address";
@@ -209,6 +374,13 @@ export class TypeTagAddress extends TypeTag {
   }
 }
 
+/**
+ * Represents a type tag for a signer in the system.
+ * This class extends the base TypeTag and provides specific functionality
+ * related to the signer type.
+ *
+ * @extends TypeTag
+ */
 export class TypeTagSigner extends TypeTag {
   toString(): string {
     return "signer";
@@ -223,11 +395,23 @@ export class TypeTagSigner extends TypeTag {
   }
 }
 
+/**
+ * Represents a reference to a type tag in the type system.
+ * This class extends the TypeTag class and provides functionality
+ * to serialize and deserialize type tag references.
+ *
+ * @extends TypeTag
+ */
 export class TypeTagReference extends TypeTag {
   toString(): `&${string}` {
     return `&${this.value.toString()}`;
   }
 
+  /**
+   * Initializes a new instance of the class with the specified parameters.
+   *
+   * @param value - The TypeTag to reference.
+   */
   constructor(public readonly value: TypeTag) {
     super();
   }
@@ -243,9 +427,10 @@ export class TypeTagReference extends TypeTag {
 }
 
 /**
- * Generics are used for type parameters in entry functions.  However,
- * they are not actually serialized into a real type, so they cannot be
- * used as a type directly.
+ * Represents a generic type tag used for type parameters in entry functions.
+ * Generics are not serialized into a real type, so they cannot be used as a type directly.
+ *
+ * @extends TypeTag
  */
 export class TypeTagGeneric extends TypeTag {
   toString(): `T${number}` {
@@ -268,6 +453,13 @@ export class TypeTagGeneric extends TypeTag {
   }
 }
 
+/**
+ * Represents a vector type tag, which encapsulates a single type tag value.
+ * This class extends the base TypeTag class and provides methods for serialization,
+ * deserialization, and string representation of the vector type tag.
+ *
+ * @extends TypeTag
+ */
 export class TypeTagVector extends TypeTag {
   toString(): `vector<${string}>` {
     return `vector<${this.value.toString()}>`;
@@ -277,6 +469,11 @@ export class TypeTagVector extends TypeTag {
     super();
   }
 
+  /**
+   * Creates a new TypeTagVector instance with a TypeTagU8 type.
+   *
+   * @returns {TypeTagVector} A new TypeTagVector initialized with TypeTagU8.
+   */
   static u8(): TypeTagVector {
     return new TypeTagVector(new TypeTagU8());
   }
@@ -292,6 +489,13 @@ export class TypeTagVector extends TypeTag {
   }
 }
 
+/**
+ * Represents a structured type tag in the system, extending the base TypeTag class.
+ * This class encapsulates information about a specific structure, including its address,
+ * module name, and type arguments, and provides methods for serialization and type checking.
+ *
+ * @param value - The StructTag instance containing the details of the structured type.
+ */
 export class TypeTagStruct extends TypeTag {
   toString(): `0x${string}::${string}::${string}` {
     // Collect type args and add it if there are any
@@ -319,6 +523,14 @@ export class TypeTagStruct extends TypeTag {
     return new TypeTagStruct(value);
   }
 
+  /**
+   * Determines if the provided address, module name, and struct name match the current type tag.
+   *
+   * @param address - The account address to compare against the type tag.
+   * @param moduleName - The name of the module to compare against the type tag.
+   * @param structName - The name of the struct to compare against the type tag.
+   * @returns True if the address, module name, and struct name match the type tag; otherwise, false.
+   */
   isTypeTag(address: AccountAddress, moduleName: string, structName: string): boolean {
     return (
       this.value.moduleName.identifier === moduleName &&
@@ -327,19 +539,46 @@ export class TypeTagStruct extends TypeTag {
     );
   }
 
+  /**
+   * Checks if the provided value is of type string.
+   * This function can help ensure that the data being processed is in the correct format before further operations.
+   *
+   * @returns {boolean} Returns true if the value is a string, otherwise false.
+   */
   isString(): boolean {
     return this.isTypeTag(AccountAddress.ONE, "string", "String");
   }
 
+  /**
+   * Checks if the specified account address is of type "option".
+   *
+   * @returns {boolean} Returns true if the account address is an option type, otherwise false.
+   */
   isOption(): boolean {
     return this.isTypeTag(AccountAddress.ONE, "option", "Option");
   }
 
+  /**
+   * Checks if the provided value is of type 'object'.
+   * This function helps determine if a value can be treated as an object type in the context of the SDK.
+   *
+   * @returns {boolean} Returns true if the value is an object, otherwise false.
+   */
   isObject(): boolean {
     return this.isTypeTag(AccountAddress.ONE, "object", "Object");
   }
 }
 
+/**
+ * Represents a structured tag that includes an address, module name,
+ * name, and type arguments. This class is used to define and manage
+ * structured data types within the SDK.
+ *
+ * @property {AccountAddress} address - The address associated with the struct tag.
+ * @property {Identifier} moduleName - The name of the module that contains the struct.
+ * @property {Identifier} name - The name of the struct.
+ * @property {Array<TypeTag>} typeArgs - An array of type arguments associated with the struct.
+ */
 export class StructTag extends Serializable {
   public readonly address: AccountAddress;
 
@@ -373,18 +612,40 @@ export class StructTag extends Serializable {
   }
 }
 
+/**
+ * Retrieves the StructTag for the AptosCoin, which represents the Aptos Coin in the Aptos blockchain.
+ *
+ * @returns {StructTag} The StructTag for the AptosCoin.
+ */
 export function aptosCoinStructTag(): StructTag {
   return new StructTag(AccountAddress.ONE, new Identifier("aptos_coin"), new Identifier("AptosCoin"), []);
 }
 
+/**
+ * Returns a new StructTag representing a string type.
+ *
+ * @returns {StructTag} A StructTag for the string type.
+ */
 export function stringStructTag(): StructTag {
   return new StructTag(AccountAddress.ONE, new Identifier("string"), new Identifier("String"), []);
 }
 
+/**
+ * Creates a new StructTag for the Option type with the specified type argument.
+ * This can help in defining a specific instance of an Option type in your application.
+ *
+ * @param typeArg - The type tag that specifies the type of the value contained in the Option.
+ */
 export function optionStructTag(typeArg: TypeTag): StructTag {
   return new StructTag(AccountAddress.ONE, new Identifier("option"), new Identifier("Option"), [typeArg]);
 }
 
+/**
+ * Creates a new StructTag for the Object type with the specified type argument.
+ * This function helps in defining a structured representation of an Object with a specific type.
+ *
+ * @param typeArg - The type tag that specifies the type of the Object.
+ */
 export function objectStructTag(typeArg: TypeTag): StructTag {
   return new StructTag(AccountAddress.ONE, new Identifier("object"), new Identifier("Object"), [typeArg]);
 }

package/src/transactions/typeTag/parser.ts

@@ -22,40 +22,41 @@ import { AccountAddress } from "../../core";
 import { Identifier } from "../instances/identifier";
 
 /**
- * Tells if the string is a valid Move identifier.  It can only be alphanumeric and `_`
- * @param str
+ * Determines if the provided string is a valid Move identifier, which can only contain alphanumeric characters and underscores.
+ * @param str - The string to validate as a Move identifier.
  */
 function isValidIdentifier(str: string) {
   return !!str.match(/^[_a-zA-Z0-9]+$/);
 }
 
 /**
- * Tells if the character is a whitespace character.  Does not work for multiple characters
- * @param char
+ * Determines if the provided character is a whitespace character. This function only works for single characters.
+ * @param char - The character to check for whitespace.
  */
 function isValidWhitespaceCharacter(char: string) {
   return !!char.match(/\s/);
 }
 
 /**
- * Tells if a type is a generic type from the ABI, this will be of the form T0, T1, ...
- * @param str
+ * Determines if a given string represents a generic type from the ABI, specifically in the format T0, T1, etc.
+ * @param str - The string to evaluate for generic type format.
  */
 function isGeneric(str: string) {
   return !!str.match(/^T[0-9]+$/);
 }
 
 /**
- * Tells if a type is a reference type (starts with &)
- * @param str
+ * Determines if the provided string is a reference type, which is indicated by starting with an ampersand (&).
+ * @param str - The string to evaluate for reference type.
  */
 function isRef(str: string) {
   return !!str.match(/^&.+$/);
 }
 
 /**
- * Tells if a type is a primitive type
- * @param str
+ * Determines if the provided string represents a primitive type.
+ * @param str - The string to evaluate as a potential primitive type.
+ * @returns A boolean indicating whether the string is a primitive type.
  */
 function isPrimitive(str: string) {
   switch (str) {
@@ -75,9 +76,11 @@ function isPrimitive(str: string) {
 }
 
 /**
- * Consumes all whitespace in a string, similar to trim
- * @param tagStr
- * @param pos
+ * Consumes all whitespace characters in a string starting from a specified position.
+ *
+ * @param tagStr - The string from which to consume whitespace.
+ * @param pos - The position in the string to start consuming whitespace from.
+ * @returns The new position in the string after consuming whitespace.
  */
 function consumeWhitespace(tagStr: string, pos: number) {
   let i = pos;
@@ -93,7 +96,7 @@ function consumeWhitespace(tagStr: string, pos: number) {
 }
 
 /**
- * State for TypeTag parsing.  This is pushed onto a stack to keep track of what is the current state
+ * State for TypeTag parsing, maintained on a stack to track the current parsing state.
  */
 type TypeTagState = {
   savedExpectedTypes: number;
@@ -101,6 +104,9 @@ type TypeTagState = {
   savedTypes: Array<TypeTag>;
 };
 
+/**
+ * Error types related to parsing type tags, indicating various issues encountered during the parsing process.
+ */
 export enum TypeTagParserErrorType {
   InvalidTypeTag = "unknown type",
   UnexpectedGenericType = "unexpected generic type",
@@ -118,23 +124,49 @@ export enum TypeTagParserErrorType {
   InvalidAddress = "struct address must be valid",
 }
 
+/**
+ * Represents an error that occurs during the parsing of a type tag.
+ * This error extends the built-in Error class and provides additional context
+ * regarding the specific type tag that failed to parse and the reason for the failure.
+ *
+ * @param typeTagStr - The type tag string that failed to be parsed.
+ * @param invalidReason - The reason why the type tag string is considered invalid.
+ */
 export class TypeTagParserError extends Error {
+  /**
+   * Constructs an error indicating a failure to parse a type tag.
+   * This error provides details about the specific type tag that could not be parsed and the reason for the failure.
+   *
+   * @param typeTagStr - The string representation of the type tag that failed to parse.
+   * @param invalidReason - The reason why the type tag is considered invalid.
+   */
   constructor(typeTagStr: string, invalidReason: TypeTagParserErrorType) {
     super(`Failed to parse typeTag '${typeTagStr}', ${invalidReason}`);
   }
 }
 
 /**
+ * Parses a type string into a structured representation of type tags, accommodating various formats including generics and
+ * nested types.
+ *
+ * This function can help you accurately interpret type strings, which can include simple types, standalone structs, and complex
+ * nested generics.
+ * It supports multiple generics, spacing within generics, and nested generics of varying depths.
  * All types are made of a few parts they're either:
  * 1. A simple type e.g. u8
  * 2. A standalone struct e.g. 0x1::account::Account
  * 3. A nested struct e.g. 0x1::coin::Coin<0x1234::coin::MyCoin>
  *
  * There are a few more special cases that need to be handled, however.
- * 1. Multiple generics e.g 0x1::pair::Pair<u8, u16>
+ * 1. Multiple generics e.g. 0x1::pair::Pair<u8, u16>
  * 2. Spacing in the generics e.g. 0x1::pair::Pair< u8 , u16>
  * 3. Nested generics of different depths e.g. 0x1::pair::Pair<0x1::coin::Coin<0x1234::coin::MyCoin>, u8>
- * 4. Generics for types in ABIs are filled in with placeholders e.g T1, T2, T3
+ * 4. Generics for types in ABIs are filled in with placeholders e.g. T1, T2, T3
+ * @param typeStr - The string representation of the type to be parsed.
+ * @param options - Optional settings for parsing behavior.
+ * @param options.allowGenerics - A flag indicating whether to allow generics in the parsing process.
+ * @returns The parsed type tag representation.
+ * @throws TypeTagParserError if the type string is malformed or does not conform to expected formats.
  */
 export function parseTypeTag(typeStr: string, options?: { allowGenerics?: boolean }) {
   const allowGenerics = options?.allowGenerics ?? false;
@@ -263,10 +295,12 @@ export function parseTypeTag(typeStr: string, options?: { allowGenerics?: boolea
 }
 
 /**
- * Parses a type tag with internal types associated
- * @param str
- * @param types
- * @param allowGenerics allow generic in parsing of the type tag
+ * Parses a type tag with internal types associated, allowing for the inclusion of generics if specified. This function helps in
+ * constructing the appropriate type tags based on the provided string representation and associated types.
+ *
+ * @param str - The string representation of the type tag to parse.
+ * @param types - An array of TypeTag instances that represent internal types associated with the type tag.
+ * @param allowGenerics - A boolean indicating whether generics are allowed in the parsing of the type tag.
  */
 function parseTypeTagInner(str: string, types: Array<TypeTag>, allowGenerics: boolean): TypeTag {
   const trimmedStr = str.trim();