fix: interface fix and docs update

src/utils/calldata/cairo.ts

@@ -3,6 +3,7 @@ import { isBigInt, isHex, isStringWholeNumber } from '../num';
 import { encodeShortString, isShortString, isText } from '../shortString';
 import { UINT_128_MAX, isUint256 } from '../uint256';
 
+// Intended for internal usage, maybe should be exported somewhere else and not exported to utils
 export const isLen = (name: string) => /_len$/.test(name);
 export const isTypeFelt = (type: string) => type === 'felt' || type === 'core::felt252';
 export const isTypeArray = (type: string) =>
@@ -24,7 +25,6 @@ export const isTypeContractAddress = (type: string) =>
 export const isTypeEthAddress = (type: string) =>
   type === 'core::starknet::eth_address::EthAddress';
 export const isCairo1Type = (type: string) => type.includes('core::');
-
 export const getArrayType = (type: string) => {
   if (isCairo1Type(type)) {
     return type.substring(type.indexOf('<') + 1, type.lastIndexOf('>'));
@@ -33,10 +33,9 @@ export const getArrayType = (type: string) => {
 };
 
 /**
- * tells if an ABI comes from a Cairo 1 contract
- *
- * @param abi representing the interface of a Cairo contract
- * @returns TRUE if it is an ABI from a Cairo1 contract
+ * Test if an ABI comes from a Cairo 1 contract
+ * @param abi Abi - representing the interface of a Cairo contract
+ * @returns boolean - TRUE if it is an ABI from a Cairo1 contract
  * @example
  * ```typescript
  * const isCairo1: boolean = isCairo1Abi(myAbi: Abi);
@@ -61,13 +60,19 @@ export function isCairo1Abi(abi: Abi): boolean {
 }
 
 /**
- * named tuple are described as js object {}
- * struct types are described as js object {}
- * array types are described as js array []
+ * named tuple cairo type are described as js object {}
+ * struct cairo type are described as js object {}
+ * array cairo type are described as js array []
  */
 
 /**
- * Uint256 cairo type (helper for common struct type)
+ * Create Uint256 Cairo type (helper for common struct type)
+ * @param it BigNumberish
+ * @returns Uint256
+ * @example
+ * ```typescript
+ * uint256('892349863487563453485768723498');
+ * ```
  */
 export const uint256 = (it: BigNumberish): Uint256 => {
   const bn = BigInt(it);
@@ -83,12 +88,23 @@ export const uint256 = (it: BigNumberish): Uint256 => {
 /**
  * unnamed tuple cairo type (helper same as common struct type)
  */
+/**
+ * Create unnamed tuple Cairo type (helper same as common struct type)
+ * @param args BigNumberish[] | object[] | boolean[]
+ * @returns Record
+ * @example
+ * ```typescript
+ * tuple(1,'0x101',16);
+ * ```
+ */
 export const tuple = (
   ...args: (BigNumberish | object | boolean)[]
 ): Record<number, BigNumberish | object | boolean> => ({ ...args });
 
 /**
- * felt cairo type
+ * Create felt Cairo type (cairo type helper)
+ * @param it BigNumberish
+ * @returns felt-string
  */
 export function felt(it: BigNumberish): string {
   // BN or number

src/utils/encode.ts

@@ -3,39 +3,85 @@ export const IS_BROWSER = typeof window !== 'undefined';
 
 const STRING_ZERO = '0';
 
+/**
+ * Some function imported from https://github.com/pedrouid/enc-utils/blob/master/src/index.ts
+ * enc-utils is no dependency to avoid using `Buffer` which just works in node and no browsers
+ */
+
+/**
+ * Convert array buffer to string
+ * internal usage
+ * @param array ArrayBuffer
+ * @returns string
+ */
 export function arrayBufferToString(array: ArrayBuffer): string {
   return new Uint8Array(array).reduce((data, byte) => data + String.fromCharCode(byte), '');
 }
 
+/**
+ * Convert string to array buffer
+ * internal usage
+ * @param s string
+ * @returns Uint8Array
+ */
 export function stringToArrayBuffer(s: string): Uint8Array {
   return Uint8Array.from(s, (c) => c.charCodeAt(0));
 }
 
+/**
+ * Convert string to array buffer (browser and node compatible)
+ * @param a string
+ * @returns Uint8Array
+ */
 export function atobUniversal(a: string): Uint8Array {
   return IS_BROWSER ? stringToArrayBuffer(atob(a)) : Buffer.from(a, 'base64');
 }
 
+/**
+ * Convert array buffer to string (browser and node compatible)
+ * @param b ArrayBuffer
+ * @returns string
+ */
 export function btoaUniversal(b: ArrayBuffer): string {
   return IS_BROWSER ? btoa(arrayBufferToString(b)) : Buffer.from(b).toString('base64');
 }
 
+/**
+ * Convert array buffer to hex-string
+ * @param buffer Uint8Array
+ * @returns hex-string
+ */
 export function buf2hex(buffer: Uint8Array) {
   return [...buffer].map((x) => x.toString(16).padStart(2, '0')).join('');
 }
 
 /**
- * Some function imported from https://github.com/pedrouid/enc-utils/blob/master/src/index.ts
- * enc-utils is no dependency to avoid using `Buffer` which just works in node and no browsers
+ * Remove hex prefix '0x' from hex-string
+ * @param hex hex-string
+ * @returns base16-string
  */
-
 export function removeHexPrefix(hex: string): string {
   return hex.replace(/^0x/i, '');
 }
 
+/**
+ * Add hex prefix '0x' to base16-string
+ * @param hex base16-string
+ * @returns hex-string
+ */
 export function addHexPrefix(hex: string): string {
   return `0x${removeHexPrefix(hex)}`;
 }
 
+/**
+ * Prepend or append to string
+ * internal usage
+ * @param str string
+ * @param length number
+ * @param left boolean
+ * @param padding STRING_ZERO
+ * @returns string
+ */
 function padString(str: string, length: number, left: boolean, padding = STRING_ZERO): string {
   const diff = length - str.length;
   let result = str;
@@ -46,19 +92,48 @@ function padString(str: string, length: number, left: boolean, padding = STRING_
   return result;
 }
 
+/**
+ * Prepend string (default with '0')
+ * @param str string
+ * @param length number
+ * @param padding STRING_ZERO
+ * @returns string
+ */
 export function padLeft(str: string, length: number, padding = STRING_ZERO): string {
   return padString(str, length, true, padding);
 }
 
-export function calcByteLength(length: number, byteSize = 8): number {
+/**
+ * Calculate byte length of string
+ * no-internal usage
+ * @param str string
+ * @param byteSize =8
+ * @returns number
+ */
+export function calcByteLength(str: string, byteSize = 8): number {
+  const { length } = str;
   const remainder = length % byteSize;
   return remainder ? ((length - remainder) / byteSize) * byteSize + byteSize : length;
 }
 
+/**
+ * Prepend '0' to string bytes
+ * no-internal usage
+ * @param str string
+ * @param byteSize =8
+ * @param padding STRING_ZERO
+ * @returns string
+ */
 export function sanitizeBytes(str: string, byteSize = 8, padding = STRING_ZERO): string {
-  return padLeft(str, calcByteLength(str.length, byteSize), padding);
+  return padLeft(str, calcByteLength(str, byteSize), padding);
 }
 
+/**
+ * Prepend '0' to hex-string bytes
+ * no-internal usage
+ * @param hex hex-string
+ * @returns hex-string
+ */
 export function sanitizeHex(hex: string): string {
   hex = removeHexPrefix(hex);
   hex = sanitizeBytes(hex, 2);
@@ -68,7 +143,12 @@ export function sanitizeHex(hex: string): string {
   return hex;
 }
 
-// implemented using TextEncoder to make it isomorphic
+/**
+ * Convert utf8-string to Uint8Array
+ * implemented using TextEncoder to make it isomorphic
+ * @param str utf8-string
+ * @returns Uint8Array
+ */
 export function utf8ToArray(str: string): Uint8Array {
   return new TextEncoder().encode(str);
 }