Skip to content

Commit cb35e34

Browse files
ikrcatovivpavici
ikrcatov
and
ivpavici
authored
docs: adding missing jsdocs on methods (#1036)
* docs: adding missing jsdocs on methods * removed override, and non exported method comments * Modified comment param * removed invalid comment * Update src/utils/address.ts * Update src/utils/address.ts * Update src/utils/calldata/cairo.ts * Update src/utils/calldata/cairo.ts --------- Co-authored-by: Ivan Pavičić <ivan.pavicic@live.com>
1 parent 23c5fd6 commit cb35e34

File tree

15 files changed

+327
-5
lines changed

15 files changed

+327
-5
lines changed

‎src/contract/interface.ts‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -162,5 +162,11 @@ export abstract class ContractInterface {
162162
*/
163163
public abstract getVersion(): Promise<ContractVersion>;
164164

165+
/**
166+
* Returns a typed instance of ContractV2 based on the supplied ABI.
167+
*
168+
* @param {TAbi} tAbi - The ABI (Abstract Binary Interface) of the ContractV2.
169+
* @return {TypedContractV2<TAbi>} - A typed instance of ContractV2.
170+
*/
165171
public abstract typedv2<TAbi extends AbiKanabi>(tAbi: TAbi): TypedContractV2<TAbi>;
166172
}

‎src/utils/address.ts‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -33,7 +33,14 @@ export function validateAndParseAddress(address: BigNumberish): string {
3333
return result;
3434
}
3535

36-
// from https://github.com/ethers-io/ethers.js/blob/fc1e006575d59792fa97b4efb9ea2f8cca1944cf/packages/address/src.ts/index.ts#L12
36+
/**
37+
* Computes the checksum address for the given Starknet address.
38+
*
39+
* From https://github.com/ethers-io/ethers.js/blob/fc1e006575d59792fa97b4efb9ea2f8cca1944cf/packages/address/src.ts/index.ts#L12
40+
* @param {BigNumberish} address - The address to compute the checksum for.
41+
*
42+
* @returns {string} The checksum address.
43+
*/
3744
export function getChecksumAddress(address: BigNumberish): string {
3845
const chars = removeHexPrefix(validateAndParseAddress(address)).toLowerCase().split('');
3946
const hex = removeHexPrefix(keccakBn(address));

‎src/utils/assert.ts‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,9 @@
1+
/**
2+
* Asserts that the given condition is true, otherwise throws an error with an optional message.
3+
* @param {any} condition - The condition to check.
4+
* @param {string} [message] - The optional message to include in the error.
5+
* @throws {Error} Throws an error if the condition is false.
6+
*/
17
export default function assert(condition: any, message?: string): asserts condition {
28
if (!condition) {
39
throw new Error(message || 'Assertion failure');

‎src/utils/calldata/cairo.ts‎

Lines changed: 109 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,32 +14,141 @@ import { CairoUint256 } from '../cairoDataTypes/uint256';
1414
import { CairoUint512 } from '../cairoDataTypes/uint512';
1515

1616
// Intended for internal usage, maybe should be exported somewhere else and not exported to utils
17+
/**
18+
* Checks if the given name ends with "_len".
19+
*
20+
* @param {string} name - The name to be checked.
21+
* @returns - True if the name ends with "_len", false otherwise.
22+
*/
1723
export const isLen = (name: string) => /_len$/.test(name);
24+
/**
25+
* Checks if a given type is felt.
26+
*
27+
* @param {string} type - The type to check.
28+
* @returns - True if the type is felt, false otherwise.
29+
*/
1830
export const isTypeFelt = (type: string) => type === 'felt' || type === 'core::felt252';
31+
/**
32+
* Checks if the given type is an array type.
33+
*
34+
* @param {string} type - The type to check.
35+
* @returns - `true` if the type is an array type, `false` otherwise.
36+
*/
1937
export const isTypeArray = (type: string) =>
2038
/\*/.test(type) ||
2139
type.startsWith('core::array::Array::') ||
2240
type.startsWith('core::array::Span::');
41+
/**
42+
* Checks if the given type is a tuple type.
43+
*
44+
* @param {string} type - The type to be checked.
45+
* @returns - `true` if the type is a tuple type, otherwise `false`.
46+
*/
2347
export const isTypeTuple = (type: string) => /^\(.*\)$/i.test(type);
48+
/**
49+
* Checks whether a given type is a named tuple.
50+
*
51+
* @param {string} type - The type to be checked.
52+
* @returns - True if the type is a named tuple, false otherwise.
53+
*/
2454
export const isTypeNamedTuple = (type: string) => /\(.*\)/i.test(type) && type.includes(':');
55+
/**
56+
* Checks if a given type is a struct.
57+
*
58+
* @param {string} type - The type to check for existence.
59+
* @param {AbiStructs} structs - The collection of structs to search in.
60+
* @returns - True if the type exists in the structs, false otherwise.
61+
*/
2562
export const isTypeStruct = (type: string, structs: AbiStructs) => type in structs;
63+
/**
64+
* Checks if a given type is an enum.
65+
*
66+
* @param {string} type - The type to check.
67+
* @param {AbiEnums} enums - The enumeration to search in.
68+
* @returns - True if the type exists in the enumeration, otherwise false.
69+
*/
2670
export const isTypeEnum = (type: string, enums: AbiEnums) => type in enums;
71+
/**
72+
* Determines if the given type is an Option type.
73+
*
74+
* @param {string} type - The type to check.
75+
* @returns - True if the type is an Option type, false otherwise.
76+
*/
2777
export const isTypeOption = (type: string) => type.startsWith('core::option::Option::');
78+
/**
79+
* Checks whether a given type starts with 'core::result::Result::'.
80+
*
81+
* @param {string} type - The type to check.
82+
* @returns - True if the type starts with 'core::result::Result::', false otherwise.
83+
*/
2884
export const isTypeResult = (type: string) => type.startsWith('core::result::Result::');
85+
/**
86+
* Checks if the given value is a valid Uint type.
87+
*
88+
* @param {string} type - The value to check.
89+
* @returns - Returns true if the value is a valid Uint type, otherwise false.
90+
*/
2991
export const isTypeUint = (type: string) => Object.values(Uint).includes(type as Uint);
3092
// Legacy Export
93+
/**
94+
* Checks if the given type is `uint256`.
95+
*
96+
* @param {string} type - The type to be checked.
97+
* @returns - Returns true if the type is `uint256`, otherwise false.
98+
*/
3199
export const isTypeUint256 = (type: string) => CairoUint256.isAbiType(type);
100+
/**
101+
* Checks if the given type is a literal type.
102+
*
103+
* @param {string} type - The type to check.
104+
* @returns - True if the type is a literal type, false otherwise.
105+
*/
32106
export const isTypeLiteral = (type: string) => Object.values(Literal).includes(type as Literal);
107+
/**
108+
* Checks if the given type is a boolean type.
109+
*
110+
* @param {string} type - The type to be checked.
111+
* @returns - Returns true if the type is a boolean type, otherwise false.
112+
*/
33113
export const isTypeBool = (type: string) => type === 'core::bool';
114+
/**
115+
* Checks if the provided type is equal to 'core::starknet::contract_address::ContractAddress'.
116+
* @param {string} type - The type to be checked.
117+
* @returns - true if the type matches 'core::starknet::contract_address::ContractAddress', false otherwise.
118+
*/
34119
export const isTypeContractAddress = (type: string) =>
35120
type === 'core::starknet::contract_address::ContractAddress';
121+
/**
122+
* Determines if the given type is an Ethereum address type.
123+
*
124+
* @param {string} type - The type to check.
125+
* @returns - Returns true if the given type is 'core::starknet::eth_address::EthAddress', otherwise false.
126+
*/
36127
export const isTypeEthAddress = (type: string) =>
37128
type === 'core::starknet::eth_address::EthAddress';
129+
/**
130+
* Checks if the given type is 'core::bytes_31::bytes31'.
131+
*
132+
* @param {string} type - The type to check.
133+
* @returns - True if the type is 'core::bytes_31::bytes31', false otherwise.
134+
*/
38135
export const isTypeBytes31 = (type: string) => type === 'core::bytes_31::bytes31';
136+
/**
137+
* Checks if the given type is equal to the 'core::byte_array::ByteArray'.
138+
*
139+
* @param {string} type - The type to check.
140+
* @returns - True if the given type is equal to 'core::byte_array::ByteArray', false otherwise.
141+
*/
39142
export const isTypeByteArray = (type: string) => type === 'core::byte_array::ByteArray';
40143
export const isTypeSecp256k1Point = (type: string) =>
41144
type === 'core::starknet::secp256k1::Secp256k1Point';
42145
export const isCairo1Type = (type: string) => type.includes('::');
146+
/**
147+
* Retrieves the array type from the given type string.
148+
*
149+
* @param {string} type - The type string.
150+
* @returns - The array type.
151+
*/
43152
export const getArrayType = (type: string) => {
44153
if (isCairo1Type(type)) {
45154
return type.substring(type.indexOf('<') + 1, type.lastIndexOf('>'));

‎src/utils/calldata/formatter.ts‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,14 @@ const guard = {
1515
},
1616
};
1717

18+
/**
19+
* Formats the given data based on the provided type definition.
20+
*
21+
* @param {any} data - The data to be formatted.
22+
* @param {any} type - The type definition for the data.
23+
* @param {any} [sameType] - The same type definition to be used (optional).
24+
* @returns - The formatted data.
25+
*/
1826
export default function formatter(data: any, type: any, sameType?: any) {
1927
// match data element with type element
2028
return Object.entries(data).reduce((acc, [key, value]: [any, any]) => {

‎src/utils/calldata/responseParser.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -84,6 +84,7 @@ function parseBaseTypes(type: string, it: Iterator<string>) {
8484
* @param responseIterator - iterator of the response
8585
* @param element - element of the field {name: string, type: string}
8686
* @param structs - structs from abi
87+
* @param enums
8788
* @return {any} - parsed arguments in format that contract is expecting
8889
*/
8990
function parseResponseValue(

‎src/utils/contract.ts‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,13 +13,28 @@ import { decompressProgram } from './stark';
1313

1414
import { isString } from './shortString';
1515

16+
/**
17+
* Checks if a given contract is in Sierra (Safe Intermediate Representation) format.
18+
*
19+
* @param {CairoContract | string} contract - The contract to check. Can be either a CairoContract object or a string representation of the contract.
20+
* @return {boolean} - Returns true if the contract is a Sierra contract, otherwise false.
21+
*/
1622
export function isSierra(
1723
contract: CairoContract | string
1824
): contract is SierraContractClass | CompiledSierra {
1925
const compiledContract = isString(contract) ? parse(contract) : contract;
2026
return 'sierra_program' in compiledContract;
2127
}
2228

29+
/**
30+
* Extracts contract hashes from `DeclareContractPayload`.
31+
*
32+
* @param {DeclareContractPayload} payload - The payload containing contract information.
33+
*
34+
* @return {CompleteDeclareContractPayload} - The `CompleteDeclareContractPayload` with extracted contract hashes.
35+
*
36+
* @throws {Error} - If extraction of compiledClassHash or classHash fails.
37+
*/
2338
export function extractContractHashes(
2439
payload: DeclareContractPayload
2540
): CompleteDeclareContractPayload {

‎src/utils/events/index.ts‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,12 @@ import responseParser from '../calldata/responseParser';
1414
import { starkCurve } from '../ec';
1515
import { addHexPrefix, utf8ToArray } from '../encode';
1616

17+
/**
18+
* Retrieves the events from the given ABI.
19+
*
20+
* @param {Abi} abi - The ABI to extract events from.
21+
* @return {AbiEvents} - An object containing the extracted events.
22+
*/
1723
export function getAbiEvents(abi: Abi): AbiEvents {
1824
return abi
1925
.filter((abiEntry) => abiEntry.type === 'event' && (abiEntry.size || abiEntry.kind !== 'enum'))
@@ -33,6 +39,7 @@ export function getAbiEvents(abi: Abi): AbiEvents {
3339
* @param providerReceivedEvents ProviderEvent[] - Array of raw events
3440
* @param abiEvents AbiEvents - Events defined in the abi
3541
* @param abiStructs AbiStructs - Structs defined in the abi
42+
* @param abiEnums
3643
* @return ParsedEvents - parsed events corresponding to the abi
3744
*/
3845
export function parseEvents(

‎src/utils/provider.ts‎

Lines changed: 14 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -119,7 +119,7 @@ export class Block {
119119

120120
tag: BlockIdentifier = null;
121121

122-
private setIdentifier(__identifier: BlockIdentifier) {
122+
private setIdentifier(__identifier: BlockIdentifier): void {
123123
if (isString(__identifier)) {
124124
if (isDecimalString(__identifier)) {
125125
this.number = parseInt(__identifier, 10);
@@ -182,11 +182,24 @@ export class Block {
182182
toString = () => this.hash;
183183
}
184184

185+
/**
186+
* Check if the given transaction details is a V3 transaction.
187+
*
188+
* @param {InvocationsDetailsWithNonce} details - The transaction details to be checked.
189+
* @return {boolean} - Returns true if the transaction is a V3 transaction, otherwise false.
190+
*/
185191
export function isV3Tx(details: InvocationsDetailsWithNonce): details is V3TransactionDetails {
186192
const version = details.version ? toHex(details.version) : ETransactionVersion.V3;
187193
return version === ETransactionVersion.V3 || version === ETransactionVersion.F3;
188194
}
189195

196+
/**
197+
* Determines if the given response matches the specified version.
198+
*
199+
* @param {('0.5' | '0.6' | '0.7')} version - The version to compare against the response.
200+
* @param {string} response - The response to check against the version.
201+
* @returns {boolean} - True if the response matches the version, false otherwise.
202+
*/
190203
export function isVersion(version: '0.5' | '0.6' | '0.7', response: string) {
191204
const [majorS, minorS] = version.split('.');
192205
const [majorR, minorR] = response.split('.');

‎src/utils/stark.ts‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -104,6 +104,21 @@ export function estimatedFeeToMaxFee(
104104
return addPercent(estimatedFee, overhead);
105105
}
106106

107+
/**
108+
* Calculates the maximum resource bounds for fee estimation.
109+
*
110+
* @param {FeeEstimate|0n} estimate - The estimate for the fee. If a BigInt is provided,
111+
* the returned bounds will be set to '0x0'.
112+
* @param {number} [amountOverhead=feeMarginPercentage.L1_BOUND_MAX_AMOUNT] - The percentage
113+
* overhead added to
114+
* the gas consumed or
115+
* overall fee amount.
116+
* @param {number} [priceOverhead=feeMarginPercentage.L1_BOUND_MAX_PRICE_PER_UNIT] - The percentage
117+
* overhead added to
118+
* the gas price per unit.
119+
* @throws {Error} If the estimate object is undefined or does not have the required properties.
120+
* @returns {ResourceBounds} The maximum resource bounds for fee estimation.
121+
*/
107122
export function estimateFeeToBounds(
108123
estimate: FeeEstimate | 0n,
109124
amountOverhead: number = feeMarginPercentage.L1_BOUND_MAX_AMOUNT,
@@ -131,6 +146,13 @@ export function estimateFeeToBounds(
131146
};
132147
}
133148

149+
/**
150+
* Converts the data availability mode from EDataAvailabilityMode to EDAMode.
151+
*
152+
* @param {EDataAvailabilityMode} dam - The data availability mode to be converted.
153+
* @return {EDAMode} The converted data availability mode.
154+
* @throws {Error} If the data availability mode is not a valid value.
155+
*/
134156
export function intDAM(dam: EDataAvailabilityMode) {
135157
if (dam === EDataAvailabilityMode.L1) return EDAMode.L1;
136158
if (dam === EDataAvailabilityMode.L2) return EDAMode.L2;

0 commit comments

Comments
 (0)