@rabbitio/ui-kit 1.0.0-beta.11 → 1.0.0-beta.111

package/src/index.js

@@ -1,23 +1,99 @@
 // UI-KIT components
-export { Button } from "./components/atoms/buttons/Button/Button.jsx";
-export { LoadingDots } from "./components/atoms/LoadingDots/LoadingDots.jsx";
-export { SupportChat } from "./components/atoms/SupportChat/SupportChat.jsx";
-export { AssetIcon } from "./components/atoms/AssetIcon/AssetIcon.jsx";
+export { Button } from "./ui-kit/components/atoms/buttons/Button/Button.jsx";
+export { LoadingDots } from "./ui-kit/components/atoms/LoadingDots/LoadingDots.jsx";
+export { SupportChat } from "./ui-kit/components/atoms/SupportChat/SupportChat.jsx";
+export { AssetIcon } from "./ui-kit/components/atoms/AssetIcon/AssetIcon.jsx";
+export { LinkButton, ICON_ROTATE_OPTIONS } from "./ui-kit/components/atoms/buttons/LinkButton/LinkButton.jsx";
+export { DialogButtons } from "./ui-kit/components/organisms/Dialog/DialogButtons/DialogButtons.jsx";
+export { BackgroundTitle } from "./ui-kit/components/atoms/BackgroundTitle/BackgroundTitle.jsx";
+export { Close, CLOSE_COLORS } from "./ui-kit/components/atoms/buttons/Close/Close.jsx";
+export { Validation } from "./ui-kit/components/atoms/Validation/Validation.jsx";
+export { Dialog, DIALOG_SIZES, DIALOG_TRANSITION_STEP_DURATION } from "./ui-kit/components/organisms/Dialog/Dialog.jsx";
+export { DialogStep, DIALOG_STEP_CLASS } from "./ui-kit/components/organisms/Dialog/DialogStep/DialogStep.jsx";
+export { AssetSelection } from "./ui-kit/components/atoms/AssetSelection/AssetSelection.jsx";
+export { Tooltip, TOOLTIP_POSITIONS } from "./ui-kit/components/atoms/Tooltip/Tooltip.jsx";
+export { NoticeIcon } from "./ui-kit/components/atoms/NoticeIcon/NoticeIcon.jsx";
+export { TitleBox } from "./ui-kit/components/atoms/TitleBox/TitleBox.jsx";
+export { AmountInput } from "./ui-kit/components/molecules/AmountInput/AmountInput.jsx";
+export { SwapForm } from "./ui-kit/components/organisms/SwapForm/SwapForm.jsx";
+export { Textarea } from "./ui-kit/components/atoms/Textarea/Textarea.jsx";
+export { QrCode } from "./ui-kit/components/atoms/QrCode/QrCode.jsx";
+export { LinesOfText } from "./ui-kit/components/atoms/TwoLinesOfText/LinesOfText.jsx";
+export { LineWithIconLink } from "./ui-kit/components/molecules/LineWithIconLink/LineWithIconLink.jsx";
+export { DeterminedErrorDialogStep } from "./ui-kit/components/templates/DeterminedErrorDialogStep/DeterminedErrorDialogStep.jsx";
+export { TitledLineWithIconLink } from "./ui-kit/components/molecules/TitledLineWithIconLink/TitledLineWithIconLink.jsx";
+export { RadioButtonWithText } from "./ui-kit/components/atoms/buttons/RadioButtonWithText/RadioButtonWithText.jsx";
+export { InformationMessage } from "./ui-kit/components/atoms/InformationMessage/InformationMessage.jsx";
+export { Input } from "./ui-kit/components/atoms/Input/Input.jsx";
+export { COIN_PICKER_MODES, CoinPicker } from "./ui-kit/components/molecules/CoinPicker/CoinPicker.jsx";
+export { CoinPickerDialogStep } from "./ui-kit/components/organisms/CoinPickerDialogStep/CoinPickerDialogStep.jsx";
+export { SearchableCoinsList } from "./ui-kit/components/molecules/SearchableCoinsList/SearchableCoinsList.jsx";
+export { ColoredNotice, COLORED_NOTICE_COLORS } from "./ui-kit/components/molecules/ColoredNotice/ColoredNotice.jsx";
+export { WaitlistSubscription } from "./ui-kit/components/organisms/WaitlistSubscription/WaitlistSubscription.jsx";
+export { LogoCarousel } from "./ui-kit/components/molecules/LogoCarousel/LogoCarousel.jsx";
+
+// UI-KIT constants
+export { FALLBACK_ASSET_ICON_URL, DEFAULT_CRYPTO_DECIMAL_COUNT } from "./common-apis/globalConstants.jsx";
+
+export { useCallHandlingErrors } from "./ui-kit/hooks/useCallHandlingErrors.js";
+export { useReferredState } from "./ui-kit/hooks/useReferredState.js";
+export { handleClickOutside } from "./ui-kit/utils/uiUtils.js";
+export { InputValuesProviders } from "./ui-kit/utils/inputValueProviders.js";
+export { copyBrowserTextToClipboard } from "./ui-kit/utils/textUtils.js";
+export { useIsHydrated } from "./ui-kit/hooks/useIsHydrated.js";
+
+export { saveQueryParameterAndValues } from "./ui-kit/utils/urlQueryUtils.js";
+export { removeQueryParameterAndValues } from "./ui-kit/utils/urlQueryUtils.js";
+export { getQueryParameterSingleValue } from "./ui-kit/utils/urlQueryUtils.js";
+export { getQueryParameterValues } from "./ui-kit/utils/urlQueryUtils.js";
 
 // Common code lib (to be extracted later to dedicated lib)
-export { improveAndRethrow } from "./common/errorUtils.js";
-export { FiatCurrenciesService } from "./common/fiatCurrenciesService.js";
-export { AmountUtils } from "./common/amountUtils.js";
+export { improveAndRethrow } from "./common-apis/utils/errorUtils.js";
+export { logErrorOrOutputToConsole } from "./common-apis/utils/errorUtils.js";
+export { FiatCurrenciesService } from "./common-apis/services/fiatCurrenciesService.js";
+export { AmountUtils } from "./common-apis/utils/amountUtils.js";
+export { toRabbitTicker } from "./common-apis/utils/rabbitTicker.js";
+export { searchCoins } from "./ui-kit/utils/searchCoins.js";
+
+export { Blockchain } from "./common-apis/models/blockchain.js";
+export { Protocol } from "./common-apis/models/protocol.js";
+export { Coin } from "./common-apis/models/coin.js";
+
+export { Cache } from "./common-apis/utils/cache.js";
+export { safeStringify } from "./common-apis/utils/safeStringify.js";
+export { LogsStorage } from "./common-apis/utils/logging/logsStorage.js";
+export { Logger } from "./common-apis/utils/logging/logger.js";
+export { postponeExecution } from "./common-apis/utils/postponeExecution.js";
+export { AxiosAdapter } from "./common-apis/adapters/axiosAdapter.js";
+
+export { EmailsApi } from "./common-apis/external-apis/emailAPI.js";
+export { IpAddressProvider } from "./common-apis/external-apis/ipAddressProviders.js";
+
+export { GoogleAnalyticsAdapter } from "./common-apis/adapters/analyticsAdapters/googleAnalyticsAdapter.js";
+export { MixpanelAdapter } from "./common-apis/adapters/analyticsAdapters/mixpanelAdapter.js";
+export { MetrikaAdapter } from "./common-apis/adapters/analyticsAdapters/metrikaAdapter.js";
 
-export { Blockchain } from "./common/models/blockchain.js";
-export { Protocol } from "./common/models/protocol.js";
-export { Coin } from "./common/models/coin.js";
+// Robust data retriever service and related APIs (to be extracted later to dedicated lib)
+export { CacheAndConcurrentRequestsResolver } from "./robust-api-caller/cacheAndConcurrentRequestsResolver.js";
+export { CachedRobustExternalApiCallerService } from "./robust-api-caller/cachedRobustExternalApiCallerService.js";
+export { CancelProcessing } from "./robust-api-caller/cancelProcessing.js";
+export { ExternalApiProvider } from "./robust-api-caller/externalApiProvider.js";
+export { RobustExternalAPICallerService } from "./robust-api-caller/robustExternalAPICallerService.js";
+export { ConcurrentCalculationsMetadataHolder } from "./robust-api-caller/concurrentCalculationsMetadataHolder.js";
 
-export { Cache } from "./common/utils/cache.js";
-export { safeStringify } from "./common/utils/safeStringify.js";
-export { LogsStorage } from "./common/utils/logging/logsStorage.js";
-export { Logger } from "./common/utils/logging/logger.js";
+export { ApiGroups } from "./common-apis/external-apis/apiGroups.js";
+export { ApiGroup } from "./common-apis/external-apis/apiGroups.js";
 
 // Swaps lib (to be extracted later to dedicated lib)
 export { ExistingSwap } from "./swaps-lib/models/existingSwap.js";
+export { ExistingSwapWithFiatData } from "./swaps-lib/models/existingSwapWithFiatData.js";
+export { BaseSwapCreationInfo } from "./swaps-lib/models/baseSwapCreationInfo.js";
+export { SwapProviderCoinInfo } from "./swaps-lib/models/swapProviderCoinInfo.js";
 export { SwapProvider } from "./swaps-lib/external-apis/swapProvider.js";
+export { SwapspaceSwapProvider } from "./swaps-lib/external-apis/swapspaceSwapProvider.js";
+export { LetsExchangeSwapProvider } from "./swaps-lib/external-apis/letsExchangeSwapProvider.js";
+export { ExolixSwapProvider } from "./swaps-lib/external-apis/exolixSwapProvider.js";
+export { GoexmeSwapProvider } from "./swaps-lib/external-apis/goexmeSwapProvider.js";
+export { SwapUtils } from "./swaps-lib/utils/swapUtils.js";
+export { PublicSwapService } from "./swaps-lib/services/publicSwapService.js";
+export { Partner, KYC_LEVELS } from "./swaps-lib/models/partner.js";

package/src/robust-api-caller/cacheAndConcurrentRequestsResolver.js

@@ -0,0 +1,525 @@
+import { v4 } from "uuid";
+
+import { improveAndRethrow } from "../common-apis/utils/errorUtils.js";
+import { Logger } from "../common-apis/utils/logging/logger.js";
+
+/**
+ * This util helps to avoid duplicated calls to a shared resource.
+ * It tracks is there currently active calculation for the specific cache id and make all other requests
+ * with the same cache id waiting for this active calculation to be finished. When the calculation ends
+ * the resolver allows all the waiting requesters to get the data from cache and start their own calculations.
+ *
+ * This class should be instantiated inside some other service where you need to request some resource concurrently.
+ * Rules:
+ * 1. When you need to make a request inside your main service call 'getCachedOrWaitForCachedOrAcquireLock'
+ *    on the instance of this class and await for the result. If the flag allowing to start calculation is true
+ *    then you can request data inside your main service. Otherwise you should use the cached data as an another
+ *    requester just finished the most resent requesting and there is actual data in the cache that
+ *    is returned to you here.
+ * 1.1 Also you can acquire a lock directly if you don't want to get cached data. Use the corresponding method 'acquireLock'.
+ *
+ * 2. If you start requesting (when you successfully acquired the lock) then after receiving the result of your
+ *    requesting you should call the 'saveCachedData' so the retrieved data will appear in the cache.
+ *
+ * 3. If you successfully acquired the lock then you should after calling the 'saveCachedData' call
+ *    the 'releaseLock' - this is mandatory to release the lock and allow other requesters to perform their requests.
+ *    WARNING: If for any reason you forget to call this method then this class instance will wait perpetually for
+ *    the lock releasing and all your attempts to request the data will constantly fail. So usually call it
+ *    inside the 'finally' block.
+ *
+ * TODO: [tests, critical++] add unit tests - massively used logic and can produce sophisticated concurrency bugs
+ */
+export class CacheAndConcurrentRequestsResolver {
+    /**
+     * @param bio {string} unique identifier for the exact service
+     * @param cache {Cache} cache
+     * @param cacheTtl {number|null} time to live for cache ms. 0 or null means the cache cannot expire
+     * @param [maxCallAttemptsToWaitForAlreadyRunningRequest=100] {number} number of request allowed to do waiting for
+     *        result before we fail the original request. Use custom value only if you need to make the attempts count
+     *        and polling interval changes.
+     * @param [timeoutBetweenAttemptsToCheckWhetherAlreadyRunningRequestFinished=1000] {number}
+     *        timeout ms for polling for a result. if you change maxCallAttemptsToWaitForAlreadyRunningRequest
+     *        then this parameter maybe also require the custom value.
+     * @param [removeExpiredCacheAutomatically=true] {boolean}
+     */
+    constructor(
+        bio,
+        cache,
+        cacheTtl,
+        removeExpiredCacheAutomatically = true,
+        maxCallAttemptsToWaitForAlreadyRunningRequest = 100,
+        timeoutBetweenAttemptsToCheckWhetherAlreadyRunningRequestFinished = 1000
+    ) {
+        if (cacheTtl != null && cacheTtl < timeoutBetweenAttemptsToCheckWhetherAlreadyRunningRequestFinished * 2) {
+            /*
+             * During the lifetime of this service e.g. if the data is being retrieved slowly we can get
+             * RACE CONDITION when we constantly retrieve data and during retrieval it is expired, so we are trying
+             * to retrieve it again and again.
+             * We have a protection mechanism that we will wait no more than
+             * maxCallAttemptsToWaitForAlreadyRunningRequest * timeoutBetweenAttemptsToCheckWhetherAlreadyRunningRequestFinished
+             * but this additional check is aimed to reduce potential loading time for some requests.
+             */
+            throw new Error(
+                `DEV: Wrong parameters passed to construct ${bio} - TTL ${cacheTtl} should be 2 times greater than ${timeoutBetweenAttemptsToCheckWhetherAlreadyRunningRequestFinished}`
+            );
+        }
+        this._bio = bio;
+        this._cache = cache;
+        this._cacheTtlMs = cacheTtl != null ? cacheTtl : null;
+        this._maxExecutionTimeMs =
+            maxCallAttemptsToWaitForAlreadyRunningRequest *
+            timeoutBetweenAttemptsToCheckWhetherAlreadyRunningRequestFinished;
+        this._removeExpiredCacheAutomatically = removeExpiredCacheAutomatically;
+        this._requestsManager = new ManagerOfRequestsToTheSameResource(
+            bio,
+            maxCallAttemptsToWaitForAlreadyRunningRequest,
+            timeoutBetweenAttemptsToCheckWhetherAlreadyRunningRequestFinished
+        );
+    }
+
+    /**
+     * Method to easily wrap external requests into cached ones. Uses the existing
+     * cache logic under the hood, but simplifies its implementation. The response
+     * will either be the previously cached result, if a request with the same key
+     * was executed, otherwise an external request will be executed and returned.
+     *
+     * @param requestFunction {function} The loading function the result of which should be cached
+     * @param cacheKey {string} Cache key for the method, which has to be unique for each variation of the request
+     * @return {Promise<Object>}
+     */
+    async callFunctionWithCacheAndConcurrentRequestsResolver(requestFunction, cacheKey) {
+        let cacheResolvingResult;
+        let response;
+
+        try {
+            cacheResolvingResult = await this.getCachedOrWaitForCachedOrAcquireLock(cacheKey);
+            if (!cacheResolvingResult?.canStartDataRetrieval) {
+                response = cacheResolvingResult?.cachedData;
+            } else {
+                response = await requestFunction();
+                this.saveCachedData(cacheKey, cacheResolvingResult?.lockId, response);
+            }
+            return response;
+        } catch (e) {
+            improveAndRethrow(e, "cachedRequestWrapper");
+        } finally {
+            this.releaseLock(cacheKey, cacheResolvingResult?.lockId);
+        }
+    }
+
+    /**
+     * When using this service this is the major method you should call to get data by cache id.
+     * This method checks is there cached data and ether
+     * - returns you flag that you can start requesting data from the shared resource
+     * - or if there is already started calculation waits until it is finished (removed from this service)
+     *   and returns you the retrieved data
+     * - or just returns you the cached data
+     *
+     * 'canStartDataRetrieval' equal true means that the lock was acquired, and you should manually call 'saveCachedData'
+     * if needed and then 'releaseLock' to mark this calculation as finished so other
+     * requesters can take their share of the resource.
+     *
+     * @param cacheId {string}
+     * @return {Promise<({
+     *             canStartDataRetrieval: true,
+     *             cachedData: any,
+     *             lockId: string
+     *         }|{
+     *             canStartDataRetrieval: false,
+     *             cachedData: any
+     *         })>}
+     */
+    async getCachedOrWaitForCachedOrAcquireLock(cacheId) {
+        try {
+            const startedAtTimestamp = Date.now();
+            let cached = this._cache.get(cacheId);
+            let cachedDataBackupIsPresentButExpired = null;
+            if (cached != null && !this._removeExpiredCacheAutomatically) {
+                const lastUpdateTimestamp = this._cache.getLastUpdateTimestamp(cacheId);
+                if ((lastUpdateTimestamp ?? 0) + this._cacheTtlMs < Date.now()) {
+                    /*
+                     * Here we are manually clearing 'cached' value retrieved from cache to force the data loading.
+                     * But we save its value first to the backup variable to be able to return this value if ongoing
+                     * requesting fails.
+                     */
+                    cachedDataBackupIsPresentButExpired = cached;
+                    cached = null;
+                }
+            }
+            let calculationId = null;
+            let isRetrievedCacheExpired = true;
+            let isWaitingForActiveCalculationSucceeded;
+            let weStillHaveSomeTimeToProceedExecution = true;
+            while (
+                calculationId == null &&
+                cached == null &&
+                isRetrievedCacheExpired &&
+                weStillHaveSomeTimeToProceedExecution
+            ) {
+                const result = await this._requestsManager.startCalculationOrWaitForActiveToFinish(cacheId);
+                calculationId = typeof result === "string" ? result : null;
+                isWaitingForActiveCalculationSucceeded = typeof result === "boolean" ? result : null;
+                cached = this._cache.get(cacheId);
+                isRetrievedCacheExpired = isWaitingForActiveCalculationSucceeded && cached == null;
+                weStillHaveSomeTimeToProceedExecution = Date.now() - startedAtTimestamp < this._maxExecutionTimeMs;
+            }
+            if (calculationId) {
+                return {
+                    canStartDataRetrieval: true,
+                    cachedData: cached ?? cachedDataBackupIsPresentButExpired,
+                    lockId: calculationId,
+                };
+            }
+
+            return {
+                canStartDataRetrieval: false,
+                cachedData: cached ?? cachedDataBackupIsPresentButExpired,
+            };
+        } catch (e) {
+            improveAndRethrow(e, `${this._bio}.getCachedOrWaitForCachedOrAcquireLock`);
+        }
+    }
+
+    /**
+     * Returns just the current cache value for the given id.
+     * Doesn't wait for the active calculation, doesn't acquire lock, just retrieves the current cache as it is.
+     *
+     * @param cacheId {string}
+     * @return {any}
+     */
+    getCached(cacheId) {
+        try {
+            return this._cache.get(cacheId);
+        } catch (e) {
+            improveAndRethrow(e, "getCached");
+        }
+    }
+
+    _getTtl() {
+        return this._removeExpiredCacheAutomatically ? this._cacheTtlMs : null;
+    }
+
+    /**
+     * Directly acquires the lock despite on cached data availability.
+     * So if this method returns result === true you can start the data retrieval.
+     *
+     * @param cacheId {string}
+     * @return {Promise<{ result: true, lockId: string }|{ result: false }>}
+     */
+    async acquireLock(cacheId) {
+        try {
+            return await this._requestsManager.acquireLock(cacheId);
+        } catch (e) {
+            improveAndRethrow(e, "acquireLock");
+        }
+    }
+
+    /**
+     * This method should be called only if you acquired a lock successfully.
+     *
+     * If the current lock id is not equal to the passed one the passed data will be ignored.
+     * Or you can do the synchronous data merging on your side and pass the
+     * wasDataMergedSynchronouslyWithMostRecentCacheState=true so your data will be stored
+     * despite on the lockId.
+     * WARNING: you should do this only if you are sure you perform the synchronous update.
+     *
+     * @param cacheId {string}
+     * @param lockId {string}
+     * @param data {any}
+     * @param [sessionDependentData=true] {boolean}
+     * @param [wasDataMergedSynchronouslyWithMostRecentCacheState=false]
+     */
+    saveCachedData(
+        cacheId,
+        lockId,
+        data,
+        sessionDependentData = true,
+        wasDataMergedSynchronouslyWithMostRecentCacheState = false
+    ) {
+        try {
+            if (
+                wasDataMergedSynchronouslyWithMostRecentCacheState ||
+                this._requestsManager.isTheLockActiveOne(cacheId, lockId)
+            ) {
+                /* We save passed data only if the <caller> has the currently acquired lockId.
+                 * If the passed lockId is not the active one it means that other code cleared/stopped the lock
+                 * acquired by the <caller> recently due to some urgent/more prior changes.
+                 *
+                 * But we allow user to pass the 'wasDataMergedSynchronouslyWithMostRecentCacheState' flag
+                 * that tells us that the user had taken the most recent cache value and merged his new data
+                 * with that cached value (AFTER possibly performing async data retrieval). This means that we
+                 * can ignore the fact that his lockId is no more relevant and save the passed data
+                 * as it is synchronously merged with the most recent cached data. (Synchronously merged means that
+                 * the lost update cannot occur during the merge time as JS execute the synchronous functions\
+                 * till the end).
+                 */
+                if (sessionDependentData) {
+                    this._cache.putSessionDependentData(cacheId, data, this._getTtl());
+                } else {
+                    this._cache.put(cacheId, data, this._getTtl());
+                }
+            }
+        } catch (e) {
+            improveAndRethrow(e, `${this._bio}.saveCachedData`);
+        }
+    }
+
+    /**
+     * Should be called then and only then if you successfully acquired a lock with the lock id.
+     *
+     * @param cacheId {string}
+     * @param lockId {string}
+     */
+    releaseLock(cacheId, lockId) {
+        try {
+            if (this._requestsManager.isTheLockActiveOne(cacheId, lockId)) {
+                this._requestsManager.finishActiveCalculation(cacheId);
+            }
+        } catch (e) {
+            improveAndRethrow(e, `${this._bio}.releaseLock`);
+        }
+    }
+
+    /**
+     * Actualized currently present cached data by key. Applies the provided function to the cached data.
+     *
+     * @param cacheId {string} id of cache entry
+     * @param synchronousCurrentCacheProcessor (function|null} synchronous function accepting cache entry. Should return
+     *        an object in following format:
+     *        {
+     *            isModified: boolean,
+     *            data: any
+     *        }
+     *        the flag signals whether data was changed during the processing or not
+     * @param [sessionDependent=true] {boolean} whether to mark the cache entry as session-dependent
+     */
+    actualizeCachedData(cacheId, synchronousCurrentCacheProcessor, sessionDependent = true) {
+        try {
+            const cached = this._cache.get(cacheId);
+            const result = synchronousCurrentCacheProcessor(cached);
+            if (result?.isModified && result?.data != null) {
+                if (sessionDependent) {
+                    this._cache.putSessionDependentData(cacheId, result?.data, this._getTtl());
+                } else {
+                    this._cache.put(cacheId, result?.data, this._getTtl());
+                }
+
+                /* Here we call the lock releasing to ensure the currently active calculation will be ignored.
+                 * This is needed to ensure no 'lost update'.
+                 * Lost update can occur if we change data in this method and after that some calculation finishes
+                 * having the earlier data as its base to calculate its data set result. And the earlier data
+                 * has no changes applied inside this method, so we will lose them.
+                 *
+                 * This is not so good solution: ideally, we should acquire lock before performing any data updating.
+                 * But the goal of this method is to provide an instant ability to update the cached data.
+                 * And if we start acquiring the lock here the data update can be postponed significantly.
+                 * And this kills the desired nature of this method.
+                 * So we better lose some data retrieval (means abusing the resource a bit) than lose
+                 * the instant update expected after this method execution.
+                 */
+                this._requestsManager.finishActiveCalculation(cacheId);
+            }
+        } catch (e) {
+            improveAndRethrow(e, `${this._bio}.actualizeCachedData`);
+        }
+    }
+
+    invalidate(key) {
+        this._cache.invalidate(key);
+        this._requestsManager.finishActiveCalculation(key);
+    }
+
+    invalidateContaining(keyPart) {
+        this._cache.invalidateContaining(keyPart);
+        this._requestsManager.finishAllActiveCalculations(keyPart);
+    }
+
+    markAsExpiredButDontRemove(key) {
+        if (this._removeExpiredCacheAutomatically) {
+            this._cache.markCacheItemAsExpiredButDontRemove(key, this._cacheTtlMs);
+        } else {
+            this._cache.setLastUpdateTimestamp(key, Date.now() - this._cacheTtlMs - 1);
+        }
+        this._requestsManager.finishAllActiveCalculations(key);
+    }
+}
+
+/**
+ * Util class to control access to a resource when it can be called in parallel for the same result.
+ * (E.g. getting today coins-fiat rates from some API).
+ */
+class ManagerOfRequestsToTheSameResource {
+    /**
+     * @param bio {string} resource-related identifier for logging
+     * @param [maxPollsCount=100] {number} max number of attempts to wait when waiting for a lock acquisition
+     * @param [timeoutDuration=1000] {number} timeout between the polls for a lock acquisition
+     */
+    constructor(bio, maxPollsCount = 100, timeoutDuration = 1000) {
+        this.bio = bio;
+        this.maxPollsCount = maxPollsCount;
+        this.timeoutDuration = timeoutDuration;
+        this._activeCalculationsIds = new Map();
+        this._nextCalculationIds = new Map();
+    }
+
+    /**
+     * If there is no active calculation just creates uuid and returns it.
+     * If there is active calculation waits until it removed from the active calculation uuid variable.
+     *
+     * @param requestHash {string}
+     * @return {Promise<string|boolean>} returns uuid of new active calculation or true if waiting for active
+     *         calculation succeed or false if max attempts count exceeded
+     */
+    async startCalculationOrWaitForActiveToFinish(requestHash) {
+        try {
+            const activeCalculationIdForHash = this._activeCalculationsIds.get(requestHash);
+            if (activeCalculationIdForHash == null) {
+                const id = v4();
+                this._activeCalculationsIds.set(requestHash, id);
+                return id;
+            }
+
+            return await this._waitForCalculationIdToFinish(requestHash, activeCalculationIdForHash, 0);
+        } catch (e) {
+            Logger.logError(e, `startCalculationOrWaitForActiveToFinish_${this.bio}`);
+        }
+
+        return null;
+    }
+
+    /**
+     * Acquires lock to the resource by the provided hash.
+     *
+     * @param requestHash {string}
+     * @return {Promise<{ result: true, lockId: string }|{ result: false }>} result is true if the lock is successfully
+     *         acquired, false if the max allowed time to wait for acquisition expired or any unexpected error occurs
+     *         during the waiting.
+     */
+    async acquireLock(requestHash) {
+        try {
+            const activeId = this._activeCalculationsIds.get(requestHash);
+            const nextId = v4();
+            if (activeId == null) {
+                this._activeCalculationsIds.set(requestHash, nextId);
+                return { result: true, lockId: nextId };
+            }
+
+            const currentNext = this._nextCalculationIds.get(requestHash) ?? [];
+            currentNext.push(nextId);
+            this._nextCalculationIds.set(requestHash, currentNext);
+
+            const waitingResult = await this._waitForCalculationIdToFinish(requestHash, activeId, 0, nextId);
+            return {
+                result: waitingResult,
+                lockId: waitingResult ? nextId : undefined,
+            };
+        } catch (e) {
+            improveAndRethrow(e, "acquireLock");
+        }
+    }
+
+    /**
+     * Clears active calculation id.
+     * WARNING: if you forget to call this method the start* one will perform maxPollsCount attempts before finishing
+     * @param requestHash {string} hash of request. Helps to distinct the request for the same resource but
+     *        having different request parameters and hold a dedicated calculation id per this hash
+     */
+    finishActiveCalculation(requestHash = "default") {
+        try {
+            this._activeCalculationsIds.delete(requestHash);
+            const next = this._nextCalculationIds.get(requestHash) ?? [];
+            if (next.length) {
+                this._activeCalculationsIds.set(requestHash, next[0]);
+                this._nextCalculationIds.set(requestHash, next.slice(1));
+            }
+        } catch (e) {
+            improveAndRethrow(e, "finishActiveCalculation");
+        }
+    }
+
+    finishAllActiveCalculations(keyPart = "") {
+        try {
+            Array.from(this._activeCalculationsIds.keys()).forEach(hash => {
+                if (typeof hash === "string" && new RegExp(keyPart).test(hash)) {
+                    this.finishActiveCalculation(hash);
+                }
+            });
+        } catch (e) {
+            improveAndRethrow(e, "finishAllActiveCalculations");
+        }
+    }
+
+    /**
+     * @param requestHash {string}
+     * @param lockId {string}
+     * @return {boolean}
+     */
+    isTheLockActiveOne(requestHash, lockId) {
+        try {
+            return this._activeCalculationsIds.get(requestHash) === lockId;
+        } catch (e) {
+            improveAndRethrow(e, "isTheLockActiveOne");
+        }
+    }
+
+    /**
+     * @param requestHash {string}
+     * @param activeCalculationId {string|null}
+     * @param [attemptIndex=0] {number}
+     * @param waitForCalculationId {string|null} if you want to wait for an exact id to appear as active then pass this parameter
+     * @return {Promise<boolean>} true
+     *                            - if the given calculation id is no more an active one
+     *                            - or it is equal to waitForCalculationId
+     *                            false
+     *                            - if waiting period exceeds the max allowed waiting time or unexpected error occurs
+     * @private
+     */
+    async _waitForCalculationIdToFinish(
+        requestHash,
+        activeCalculationId,
+        attemptIndex = 0,
+        waitForCalculationId = null
+    ) {
+        try {
+            if (attemptIndex + 1 > this.maxPollsCount) {
+                // Max number of polls for active calculation id change is achieved. So we return false.
+                return false;
+            }
+
+            const currentId = this._activeCalculationsIds.get(requestHash);
+            if (waitForCalculationId == null ? currentId !== activeCalculationId : currentId === waitForCalculationId) {
+                /* We return true depending on the usage of this function:
+                 * 1. if there is calculation id that we should wait for to become an active then we return true only
+                 *    if this id becomes the active one.
+                 *
+                 *    Theoretically we can fail to wait for the desired calculation id. This can be caused by wrong use of
+                 *    this service or by any other mistakes/errors. But this waiting function will return false anyway if
+                 *    the number of polls done exceeds the max allowed.
+                 *
+                 * 2. if we just wait for the currently active calculation id to be finished then we return true
+                 *    when we notice that the current active id differs from the original passed into this function.
+                 */
+                return true;
+            } else {
+                /* The original calculation id is still the active one, so we are scheduling a new attempt to check
+                 * whether the active calculation id changed or not in timeoutDuration milliseconds.
+                 */
+                const it = this;
+                return new Promise((resolve, reject) => {
+                    setTimeout(function () {
+                        try {
+                            resolve(
+                                it._waitForCalculationIdToFinish(requestHash, activeCalculationId, attemptIndex + 1)
+                            );
+                        } catch (e) {
+                            reject(e);
+                        }
+                    }, this.timeoutDuration);
+                });
+            }
+        } catch (e) {
+            Logger.logError(e, "_waitForCalculationIdToFinish", "Failed to wait for active calculation id change.");
+            return false;
+        }
+    }
+}