From 7a4f1ce1f85e7cabf202272fd40b0cb68ff05625 Mon Sep 17 00:00:00 2001 From: Ho3einWave Date: Wed, 30 Oct 2024 16:23:31 +0330 Subject: [PATCH] refactor: Improve code readability and documentation in assets.service.ts, router.service.ts, swap.service.ts, tonapi.service.ts, and convert.ts --- src/services/assets/assets.service.ts | 30 +++++++++++++++--- src/services/router/router.service.ts | 14 ++++++++- src/services/swap/swap.service.ts | 7 ++++- src/services/tonapi/tonapi.service.ts | 45 ++++++++++++++++++++++++--- src/utils/convert.ts | 15 +++++++++ 5 files changed, 100 insertions(+), 11 deletions(-) diff --git a/src/services/assets/assets.service.ts b/src/services/assets/assets.service.ts index 12f1be9..11cd3a2 100644 --- a/src/services/assets/assets.service.ts +++ b/src/services/assets/assets.service.ts @@ -2,12 +2,18 @@ import { Services } from '../../core/services'; import { Asset, PaginatedAssets } from '../../types/assets'; export class Assets extends Services { - public async getExactAsset(asset: string): Promise { + /** + * Retrieves an exact asset from the server. + * + * @param {string} asset - The token address you want. + * @returns {Promise} A promise that resolves to the token if found, or null if not found. + */ + public async getExactAsset(token_address: string): Promise { const assets = await this.client.request.send({ url: '/swap-process/data/assets/find/exactSearch', method: 'POST', data: { - assets: [asset], + assets: [token_address], }, }); if (assets.length > 0) { @@ -18,7 +24,10 @@ export class Assets extends Services { } /** - * getAssets + * Retrieves a list of assets from the server based on the provided asset addresses. + * + * @param {string[]} assetsAddress - An array of asset addresses to fetch. + * @returns {Promise} A promise that resolves to an array of assets. */ public async getAssets(assetsAddress: string[]) { const listOfAssets = await this.client.request.send<{ list: Asset[] }>({ @@ -32,7 +41,12 @@ export class Assets extends Services { } /** - * getPaginatedAssets + * Retrieves a paginated list of assets from the server. + * + * @param {number} [page=1] page - The page number to retrieve. Defaults to 1. + * @param {boolean} [warning=false] warning - A boolean indicating whether to include warnings. Defaults to false. + * @param {string} [phrase=''] phrase - An optional search phrase to filter the assets. + * @returns {Promise} A promise that resolves to a paginated list of assets. */ public async getPaginatedAssets(page = 1, warning = false, phrase?: string) { const listOfAssets = await this.client.request.send({ @@ -45,7 +59,13 @@ export class Assets extends Services { } /** - * getPairs + * Retrieves a paginated list of asset pairs from the server. + * + * @param {string} assetAddress - The address of the asset to fetch pairs for. + * @param {number} [page=1] - The page number to retrieve. Defaults to 1. + * @param {boolean} [warning=false] - A boolean indicating whether to include warnings. Defaults to false. + * @param {string} [searchPhrase=''] - An optional search phrase to filter the asset pairs. + * @returns {Promise} A promise that resolves to a paginated list of asset pairs. */ public async getPairs( assetAddress: string, diff --git a/src/services/router/router.service.ts b/src/services/router/router.service.ts index a79fba9..5c058ee 100644 --- a/src/services/router/router.service.ts +++ b/src/services/router/router.service.ts @@ -2,6 +2,19 @@ import { Services } from '../../core/services'; import { BestRoute, Dex } from '../../types/router'; export class Router extends Services { + /** + * Finds the best route for a given input and output asset address, pay amount, and optional slippage and DEX. + * + * @param {string} inputAssetAddress - The address of the input asset. + * @param {string} outputAssetAddress - The address of the output asset. + * @param {bigint} payAmount - The amount to be paid. + * @param {number} [slippage] - Optional slippage percentage. + * @param {Dex} [forceDex] - Optional DEX to force the route through. + * @returns {Promise} A promise that resolves to the best route. + * + * @todo Add validation for address and slippage. + * @todo If the user doesn't input an address, get the address by asset service. + */ public async findBestRoute( inputAssetAddress: string, outputAssetAddress: string, @@ -9,7 +22,6 @@ export class Router extends Services { slippage?: number, forceDex?: Dex, ) { - // TODO Validation on address, slippage // TODO if User doesn't input address get address by asset service const body = { diff --git a/src/services/swap/swap.service.ts b/src/services/swap/swap.service.ts index ef8db68..f85007b 100644 --- a/src/services/swap/swap.service.ts +++ b/src/services/swap/swap.service.ts @@ -4,7 +4,12 @@ import { SwapResponse } from '../../types/swap'; export class Swap extends Services { /** - * swap + * Creates a swap request using the provided user wallet address and best route. + * + * @param {string} userWalletAddress - The address of the user's wallet. + * @param {BestRoute} bestRoute - The best route from router. + * @param {string} [app_id] - Optional application ID to include in the request headers. + * @returns {Promise} A promise that resolves to the swap response. */ public async createSwap(userWalletAddress: string, bestRoute: BestRoute, app_id?: string) { return await this.client.request.send({ diff --git a/src/services/tonapi/tonapi.service.ts b/src/services/tonapi/tonapi.service.ts index dc0b75b..fe6e3e5 100644 --- a/src/services/tonapi/tonapi.service.ts +++ b/src/services/tonapi/tonapi.service.ts @@ -11,6 +11,13 @@ import { import { TransactionEvent } from '../../types/transaction-event'; export class TonApi extends Services { + /** + * Fetches the jetton data for a given wallet address and jetton address. + * + * @param {string} walletAddr - The wallet address to fetch the jetton data for. + * @param {string} jettonAddress - The jetton address to fetch the data from. + * @returns {Promise} A promise that resolves to the balance data. + */ public async getJettonData(walletAddr: string, jettonAddress: string) { const data = await this.client.request.send({ baseURL: 'https://tonapi.io/v2', @@ -21,6 +28,13 @@ export class TonApi extends Services { return data; } + /** + * Retrieves a custom payload for a specific wallet and jetton address. + * + * @param {string} walletAddr - The address of the wallet. + * @param {string} jettonAddress - The address of the jetton. + * @returns {Promise} A promise that resolves to the custom payload. + */ public async getCustomPayload(walletAddr: string, jettonAddress: string) { const data = await this.client.request.send({ baseURL: 'https://tonapi.io/v2', @@ -32,7 +46,12 @@ export class TonApi extends Services { } /** - * getWalletAssets + * Retrieves wallet assets for a given wallet address, including balances and rates for jettons. + * + * @param {string} walletAddress - The address of the wallet to retrieve assets for. + * @param {string[]} [currencies=['usd']] - An array of currency codes to retrieve rates for. + * @param {boolean} [custom_payload=true] - Whether to include custom payload in the request. + * @returns {Promise>} A promise that resolves to a map of balances keyed by jetton addresses. */ public async getWalletAssets( walletAddress: string, @@ -87,7 +106,10 @@ export class TonApi extends Services { } /** - * getAssetsRates + * Fetches the rates of specified assets from the TON API. + * + * @param {string[]} assetsAddresses - An array of asset addresses to fetch rates for. + * @returns {Promise>} A promise that resolves to a map where the keys are user-friendly asset addresses and the values are their corresponding prices. */ public async getAssetsRates(assetsAddresses: string[]) { const addresses = assetsAddresses.join(','); @@ -110,6 +132,15 @@ export class TonApi extends Services { /** * waitForTransactionResult */ + /** + * Waits for a transaction result by periodically checking the transaction status. + * + * @param {string} hash - The hash of the transaction to wait for. + * @param {number} [period_ms=3000] - The period in milliseconds to wait between checks. + * @param {number} [maxRetry=30] - The maximum number of retries before giving up. + * @returns {Promise} - A promise that resolves with the transaction result when complete. + * @throws {Error} - Throws an error if the maximum number of retries is reached. + */ public async waitForTransactionResult( hash: string, period_ms: number = 3000, @@ -140,8 +171,10 @@ export class TonApi extends Services { } /** - * getTransactionEvent + * Fetches a transaction event from the TON API using the provided hash. * + * @param {string} hash - The hash of the transaction event to retrieve. + * @returns {Promise} A promise that resolves to the transaction event. */ public async getTransactionEvent(hash: string) { const event = await this.client.request.send({ @@ -152,7 +185,11 @@ export class TonApi extends Services { } /** - * allTransactionComplete + * Checks if all transactions in the given event are complete. + * + * @param {TransactionEvent} event - The transaction event to check. + * @returns {boolean} - Returns `true` if all transactions are complete and successful, otherwise `false`. + * @throws {Error} - Throws an error if any transaction action has a status other than 'ok'. */ public allTransactionComplete(event: TransactionEvent) { if (event.in_progress) return false; diff --git a/src/utils/convert.ts b/src/utils/convert.ts index 2d94529..06cbd8f 100644 --- a/src/utils/convert.ts +++ b/src/utils/convert.ts @@ -1,3 +1,11 @@ +/** + * Converts a given number, string, or bigint to a bigint with the specified number of decimals. + * + * @param {number | string | bigint} src - The source value to convert. It can be a number, string, or bigint. + * @param {number} [decimals=9] - The number of decimal places to consider for the conversion. Defaults to 9. + * @returns {bigint} - The converted value as a bigint. + * @throws {Error} - Throws an error if the input number is not finite, if the input string is invalid, or if the input number does not have enough precision. + */ export function toNano(src: number | string | bigint, decimals: number = 9): bigint { if (typeof src === 'bigint') { return src * 10n ** BigInt(decimals); @@ -59,6 +67,13 @@ export function toNano(src: number | string | bigint, decimals: number = 9): big } } +/** + * Converts a value from nano units to a string representation with the specified number of decimals. + * + * @param {bigint | number | string} src - The source value in nano units. It can be a bigint, number, or string. + * @param {number} [decimals=9] - The number of decimal places to include in the output string. Defaults to 9. + * @returns {string} The converted value as a string with the specified number of decimals. + */ export function fromNano(src: bigint | number | string, decimals: number = 9) { let v = BigInt(src); let neg = false;