@sabaaa1/common 0.0.1

package/src/data-structures/TokenDBs/EventsPublicTokensDB.ts

@@ -0,0 +1,216 @@
+import { ethers } from 'ethers';
+import { get, update } from 'idb-keyval';
+import { API } from '../../API/API';
+import { networkRegistry } from '../../constants/chains.constants';
+import { Logger } from '../../error-handling/logger';
+import { lowerCaseIncludes } from '../../functions/utils/caseInsensitive.utils';
+import { StorageKeys } from '../../types/cache.types';
+import { ERC20Token } from '../../types/token.types';
+import { getStateKey } from '../../functions/utils/string.utils';
+import { zeroAddress } from '../../constants/protocol.constants';
+import { Mutex } from 'async-mutex';
+import { IPublicTokensDB } from './IPublicTokensDB';
+import { isNFTToken } from '../../functions/utils/erc20tokenFunctions';
+import { tokenVisibilityStorage } from './token-visibility-db';
+import { createTorRpcProvider } from '../../functions';
+import { EVENTS_INITIAL_BLOCKS } from '../../constants';
+
+export class EventsPublicTokensDB implements IPublicTokensDB {
+  private fetchedTokens: Record<string, ERC20Token[]> = {};
+
+  private updateMutexes: Record<string, Mutex> = {};
+
+  private readonly transferEventTopic = ethers.utils.id('Transfer(address,address,uint256)');
+
+  private getMutex(stateKey: string): Mutex {
+    if (!this.updateMutexes[stateKey]) {
+      this.updateMutexes[stateKey] = new Mutex();
+    }
+    return this.updateMutexes[stateKey];
+  }
+
+  public async getPublicTokens(chainId: number, walletAddress: string): Promise<ERC20Token[]> {
+    const key = getStateKey(walletAddress, chainId);
+    const publicTokens = await get<Record<string, ERC20Token[]>>(StorageKeys.EVENTS_PUBLIC_TOKENS);
+    return publicTokens?.[key] || [];
+  }
+
+  public getFetchedTokens(chainId: number, walletAddress: string): ERC20Token[] {
+    const key = getStateKey(walletAddress, chainId);
+    return this.fetchedTokens[key] || [];
+  }
+
+  public async fetchAndUpdatePublicTokens(walletAddress: string, chainId: number) {
+    const stateKey = getStateKey(walletAddress, chainId);
+    const mutex = this.getMutex(stateKey);
+
+    await mutex.runExclusive(async () => {
+      try {
+        const publicTokens = await this.getPublicTokens(chainId, walletAddress);
+        const publicTokensAddresses = publicTokens.map((token) => token.erc20TokenAddress);
+
+        const { toEvents, fromEvents, latestBlock } = await this.getEvents(walletAddress, chainId);
+
+        const allEvents = [...toEvents, ...fromEvents];
+
+        const { erc20Tokens } = await this.fetchPublicTokens(allEvents, chainId, publicTokensAddresses);
+
+        const hiddenTokenAddresses = await tokenVisibilityStorage.hideSpamsAndFetchHiddenTokensAddresses(
+          chainId,
+          erc20Tokens,
+        );
+        const nonHiddenErc20Tokens = erc20Tokens.filter(
+          (token) => !lowerCaseIncludes(hiddenTokenAddresses, token.erc20TokenAddress), // filter out hidden tokens
+        );
+
+        await update(StorageKeys.EVENTS_PUBLIC_TOKENS, (pubTokens: Record<string, ERC20Token[]> = {}) => {
+          const currentTokens = pubTokens[stateKey] || [];
+          const currentTokensAddresses = currentTokens.map((t) => t.erc20TokenAddress);
+          const newTokens = nonHiddenErc20Tokens.filter(
+            (token) => !lowerCaseIncludes(currentTokensAddresses, token.erc20TokenAddress),
+          );
+          currentTokens.push(...newTokens);
+
+          const updatedTokensWithIds = this.updateTokenIds(fromEvents, toEvents, currentTokens);
+
+          const newPublicTokens = {
+            ...pubTokens,
+            [stateKey]: updatedTokensWithIds,
+          };
+          this.fetchedTokens = newPublicTokens;
+          return newPublicTokens;
+        });
+
+        // Only update the last processed block if we successfully fetched events
+        if (latestBlock) {
+          await this.updateLastProcessedBlock(chainId, walletAddress, latestBlock);
+        }
+      } catch (error: unknown) {
+        Logger.error('public tokens db error', error);
+      }
+    });
+  }
+
+  private async getLastProcessedBlock(chainId: number, walletAddress: string): Promise<number> {
+    const lastBlocks = (await get<Record<string, number>>(StorageKeys.PUBLIC_TOKENS_LAST_PROCESSED_BLOCKS)) || {};
+    const key = getStateKey(walletAddress, chainId);
+    return lastBlocks[key] || EVENTS_INITIAL_BLOCKS[chainId];
+  }
+
+  private async updateLastProcessedBlock(chainId: number, walletAddress: string, blockNumber: number): Promise<void> {
+    await update(StorageKeys.PUBLIC_TOKENS_LAST_PROCESSED_BLOCKS, (lastBlocks: Record<string, number> = {}) => {
+      const key = getStateKey(walletAddress, chainId);
+      return {
+        ...lastBlocks,
+        [key]: blockNumber,
+      };
+    });
+  }
+
+  private async getEvents(walletAddress: string, chainId: number) {
+    try {
+      const { fetchRpcUrl } = networkRegistry[chainId];
+      if (!fetchRpcUrl) throw Error('No fetchRpcUrl in PublicTokensDB');
+      const provider = createTorRpcProvider(fetchRpcUrl);
+
+      const fromBlock = (await this.getLastProcessedBlock(chainId, walletAddress)) + 1;
+      const latestBlock = await provider.getBlockNumber();
+
+      const paddedWalletAddress = ethers.utils.hexZeroPad(walletAddress.toLowerCase(), 32);
+
+      const filterTo = {
+        topics: [this.transferEventTopic, null, paddedWalletAddress],
+        fromBlock,
+        toBlock: latestBlock,
+      };
+
+      const filterFrom = {
+        topics: [this.transferEventTopic, paddedWalletAddress, null],
+        fromBlock,
+        toBlock: latestBlock,
+      };
+
+      const [toEvents, fromEvents] = await Promise.all([provider.getLogs(filterTo), provider.getLogs(filterFrom)]);
+      return { toEvents, fromEvents, latestBlock };
+    } catch (error) {
+      Logger.error('Error fetching events:', error);
+      return { toEvents: [], fromEvents: [], latestBlock: undefined };
+    }
+  }
+
+  // First get existed tokenIds from tokens
+  // Then add new tokenIds from toEvents (incoming transfers)
+  // Then remove tokenIds from fromEvents (outgoing transfers)
+  private updateTokenIds(fromEvents: ethers.providers.Log[], toEvents: ethers.providers.Log[], tokens: ERC20Token[]) {
+    const tokenIdsByAddress = new Map<string, string[]>();
+
+    tokens.forEach((token) => {
+      if (isNFTToken(token) && token.tokenIds) {
+        const address = token.erc20TokenAddress.toLowerCase();
+        tokenIdsByAddress.set(address, [...token.tokenIds]);
+      }
+    });
+
+    toEvents.forEach((event) => {
+      if (event.topics.length <= 3) return;
+
+      const address = event.address.toLowerCase();
+      const tokenId = ethers.BigNumber.from(event.topics[3]).toString();
+
+      if (!tokenIdsByAddress.has(address)) {
+        tokenIdsByAddress.set(address, []);
+      }
+      tokenIdsByAddress.get(address)?.push(tokenId);
+    });
+
+    fromEvents.forEach((event) => {
+      if (event.topics.length <= 3) return;
+
+      const address = event.address.toLowerCase();
+      const tokenArray = tokenIdsByAddress.get(address);
+
+      if (tokenArray?.length) {
+        const tokenId = ethers.BigNumber.from(event.topics[3]).toString();
+        const idx = tokenArray.indexOf(tokenId);
+        if (idx !== -1) {
+          tokenArray.splice(idx, 1);
+        }
+      }
+    });
+
+    tokens.forEach((token) => {
+      if (isNFTToken(token)) {
+        const address = token.erc20TokenAddress.toLowerCase();
+        const tokenArray = tokenIdsByAddress.get(address);
+        token.tokenIds = tokenArray?.length && tokenArray.length > 0 ? tokenArray : undefined;
+      }
+    });
+
+    return tokens;
+  }
+
+  private async fetchPublicTokens(
+    allEvents: ethers.providers.Log[],
+    chainId: number,
+    publicTokensAddresses: string[],
+  ): Promise<{ erc20Tokens: ERC20Token[] }> {
+    try {
+      const tokenAddresses = [zeroAddress, ...new Set(allEvents.map((event) => event.address))].filter(
+        (address) => address && !lowerCaseIncludes(publicTokensAddresses, address),
+      );
+
+      if (!tokenAddresses.length) return { erc20Tokens: [] };
+
+      const erc20Tokens = (await API.tokensInfoCall(chainId, tokenAddresses)).filter(
+        (token): token is ERC20Token => !!token,
+      );
+
+      return { erc20Tokens };
+    } catch (error) {
+      Logger.error('Error fetching public tokens:', error);
+      return { erc20Tokens: [] };
+    }
+  }
+}
+
+export const eventsPublicTokensDB = new EventsPublicTokensDB();

package/src/data-structures/TokenDBs/IPublicTokensDB.ts

@@ -0,0 +1,7 @@
+import { ERC20Token } from '../../types/token.types';
+
+export interface IPublicTokensDB {
+  getPublicTokens(chainId: number, walletAddress: string): Promise<ERC20Token[]>;
+  getFetchedTokens(chainId: number, walletAddress: string): ERC20Token[];
+  fetchAndUpdatePublicTokens(walletAddress: string, chainId: number): Promise<void>;
+}

package/src/data-structures/TokenDBs/PrivateTokensDB.ts

@@ -0,0 +1,96 @@
+import { get, update } from 'idb-keyval';
+import { API } from '../../API/API';
+import { Logger } from '../../error-handling/logger';
+import { lowerCaseIncludes } from '../../functions/utils/caseInsensitive.utils';
+import { ERC20Token } from '../../types/token.types';
+import { StorageKeys } from '../../types/cache.types';
+import { getStateKey } from '../../functions/utils/string.utils';
+import { tokenVisibilityStorage } from './token-visibility-db';
+
+export class PrivateTokensDB {
+  private fetchedTokens: Record<string, ERC20Token[]> = {};
+
+  public initalFetched = false;
+
+  public async updateFetchedTokens() {
+    const privateTokens = await get<Record<string, ERC20Token[]>>(StorageKeys.PRIVATE_TOKENS);
+    this.fetchedTokens = privateTokens ?? {};
+    this.initalFetched = true;
+  }
+
+  public async getPrivateTokens(chainId: number, walletAddress: string): Promise<ERC20Token[]> {
+    const key = getStateKey(walletAddress, chainId);
+    const privateTokens = await get<Record<string, ERC20Token[]>>(StorageKeys.PRIVATE_TOKENS);
+    return privateTokens?.[key] || [];
+  }
+
+  private async fetchPrivateTokens(
+    chainId: number,
+    erc20Addresses: string[],
+    privateTokensAddresses: string[],
+  ): Promise<ERC20Token[]> {
+    try {
+      const tokenAddresses = [...new Set(erc20Addresses.map((address) => address.toLowerCase()))].filter(
+        (address) => address && !lowerCaseIncludes(privateTokensAddresses, address),
+      );
+
+      if (!tokenAddresses.length) return [];
+
+      const erc20Tokens = (await API.tokensInfoCall(chainId, tokenAddresses)).filter(
+        (token): token is ERC20Token => !!token,
+      );
+
+      return erc20Tokens;
+    } catch (error) {
+      Logger.error('Error fetching private tokens:', error);
+      return [];
+    }
+  }
+
+  public async fetchAndUpdatePrivateTokens(
+    erc20Addresses: string[],
+    chainId: number,
+    walletAddress: string,
+    preFetchedTokens?: ERC20Token[],
+  ) {
+    const privateTokens = await this.getPrivateTokens(chainId, walletAddress);
+    const privateTokensAddresses = privateTokens.map((token) => token.erc20TokenAddress);
+
+    const erc20Tokens =
+      preFetchedTokens ?? (await this.fetchPrivateTokens(chainId, erc20Addresses, privateTokensAddresses));
+
+    const hiddenTokenAddresses = await tokenVisibilityStorage.hideSpamsAndFetchHiddenTokensAddresses(
+      chainId,
+      erc20Tokens,
+    );
+
+    const key = getStateKey(walletAddress, chainId);
+
+    await update(StorageKeys.PRIVATE_TOKENS, (privTokens: Record<string, ERC20Token[]> = {}) => {
+      const currentTokens = privTokens?.[key] || [];
+      const currentTokensAddresses = currentTokens.map((t) => t.erc20TokenAddress);
+      const newTokens = erc20Tokens.filter(
+        (token) => !lowerCaseIncludes(currentTokensAddresses, token.erc20TokenAddress),
+      );
+      currentTokens.push(...newTokens);
+
+      const nonHiddenErc20Tokens = currentTokens.filter(
+        (token) => !lowerCaseIncludes(hiddenTokenAddresses, token.erc20TokenAddress), // filter out hidden tokens
+      );
+
+      const newPrivateTokens = {
+        ...privTokens,
+        [key]: nonHiddenErc20Tokens,
+      };
+      this.fetchedTokens = newPrivateTokens;
+      return newPrivateTokens;
+    });
+  }
+
+  public getFetchedTokens(chainId: number, walletAddress: string): ERC20Token[] {
+    const key = getStateKey(walletAddress, chainId);
+    return this.fetchedTokens[key] || [];
+  }
+}
+
+export const privateTokensDB = new PrivateTokensDB();

package/src/data-structures/TokenDBs/PublicTokensDB.ts

@@ -0,0 +1,49 @@
+import { ERC20Token } from '../../types/token.types';
+import { alchemyPublicTokensDB } from './AlchemyPublicTokensDB';
+import { IPublicTokensDB } from './IPublicTokensDB';
+import { eventsPublicTokensDB } from './EventsPublicTokensDB';
+import { getStateKey } from '../../functions/utils/string.utils';
+import { arcPublicTokensDB } from './ArcPublicTokensDB';
+import { chainIds } from '../../constants/chains.constants';
+
+export class PublicTokensDB implements IPublicTokensDB {
+  private useAlternativeDB: Record<string, boolean> = {};
+
+  public async getPublicTokens(chainId: number, walletAddress: string): Promise<ERC20Token[]> {
+    const state = getStateKey(walletAddress, chainId);
+    if (chainId === chainIds.arcTestnet) return arcPublicTokensDB.getPublicTokens(walletAddress);
+
+    return this.useAlternativeDB[state]
+      ? eventsPublicTokensDB.getPublicTokens(chainId, walletAddress)
+      : alchemyPublicTokensDB.getPublicTokens(chainId, walletAddress);
+  }
+
+  public getFetchedTokens(chainId: number, walletAddress: string): ERC20Token[] {
+    const state = getStateKey(walletAddress, chainId);
+    if (chainId === chainIds.arcTestnet) return arcPublicTokensDB.getFetchedTokens(walletAddress);
+
+    return this.useAlternativeDB[state]
+      ? eventsPublicTokensDB.getFetchedTokens(chainId, walletAddress)
+      : alchemyPublicTokensDB.getFetchedTokens(chainId, walletAddress);
+  }
+
+  // this function should be called when:
+  // 1) user first initiates wallet on a given chain
+  // 2) user manually press refresh balances button
+  public async fetchAndUpdatePublicTokens(walletAddress: string, chainId: number) {
+    const state = getStateKey(walletAddress, chainId);
+    try {
+      if (chainId === chainIds.arcTestnet) {
+        await arcPublicTokensDB.fetchAndUpdatePublicTokens(walletAddress);
+      } else {
+        await alchemyPublicTokensDB.fetchAndUpdatePublicTokens(walletAddress, chainId);
+        this.useAlternativeDB[state] = false;
+      }
+    } catch {
+      await eventsPublicTokensDB.fetchAndUpdatePublicTokens(walletAddress, chainId);
+      this.useAlternativeDB[state] = true;
+    }
+  }
+}
+
+export const publicTokensDB = new PublicTokensDB();

package/src/data-structures/TokenDBs/index.ts

@@ -0,0 +1,4 @@
+export * from './PrivateTokensDB';
+export * from './PublicTokensDB';
+export * from './token-visibility-db';
+export * from './ArcPublicTokensDB';

package/src/data-structures/TokenDBs/token-visibility-db.ts

@@ -0,0 +1,154 @@
+import { get, update } from 'idb-keyval';
+import { Logger } from '../../error-handling/logger';
+import { caseInsensitiveEqual } from '../../functions/utils/caseInsensitive.utils';
+import { ERC20Token } from '../../types/token.types';
+
+type HiddenTokensStorage = Record<number, ERC20Token[]>;
+
+class TokenVisibilityStorage {
+  private readonly STORAGE_KEY = 'hiddenTokenAddresses';
+
+  private readonly UNHIDDEN_SPAM_KEY = 'unhiddenSpamTokens';
+
+  public async getHiddenTokens(chainId: number): Promise<ERC20Token[]> {
+    try {
+      const data = await get<HiddenTokensStorage>(this.STORAGE_KEY);
+      return data?.[chainId] || [];
+    } catch (err) {
+      Logger.error('Error retrieving hidden tokens', err);
+      return [];
+    }
+  }
+
+  private async getHiddenTokenAddresses(chainId: number): Promise<string[]> {
+    try {
+      const hiddenTokens = await this.getHiddenTokens(chainId);
+      return hiddenTokens.map(({ erc20TokenAddress }) => erc20TokenAddress.toLowerCase());
+    } catch (err) {
+      Logger.error('Error retrieving hidden tokens', err);
+      return [];
+    }
+  }
+
+  public async filterOutHiddenTokens(chainId: number, tokens: ERC20Token[]): Promise<ERC20Token[]> {
+    const hiddenTokens = await this.getHiddenTokens(chainId);
+    return tokens.filter(
+      (token) =>
+        !hiddenTokens.some((hiddenToken) =>
+          caseInsensitiveEqual(hiddenToken.erc20TokenAddress, token.erc20TokenAddress),
+        ),
+    );
+  }
+
+  public async hideToken(token: ERC20Token) {
+    try {
+      await update(this.STORAGE_KEY, (current: HiddenTokensStorage | undefined) => {
+        const data = current ?? {};
+        const { chainId } = token;
+        if (!data[chainId]) {
+          data[chainId] = [];
+        }
+        const alreadyHidden = data[chainId].some(({ erc20TokenAddress }) =>
+          caseInsensitiveEqual(erc20TokenAddress, token.erc20TokenAddress),
+        );
+        if (!alreadyHidden) {
+          data[chainId].push(token);
+        }
+        return data;
+      });
+      if (token.isSpam) {
+        // If the token is spam, we need to delete it from the unhidden spam tokens list to hide it if necessary in future
+        await this.deleteUnhiddenSpamToken(token);
+      }
+    } catch (err) {
+      Logger.error('Error hiding token', err);
+    }
+  }
+
+  public async showToken(token: ERC20Token) {
+    try {
+      await update(this.STORAGE_KEY, (current: HiddenTokensStorage | undefined) => {
+        const { chainId } = token;
+        const data = current ?? {};
+        if (!data[chainId]) {
+          data[chainId] = [];
+        }
+        data[chainId] = data[chainId].filter(
+          ({ erc20TokenAddress }) => !caseInsensitiveEqual(erc20TokenAddress, token.erc20TokenAddress),
+        );
+        return data;
+      });
+
+      if (token.isSpam) {
+        // If the token is spam, we need to store it in the unhidden spam tokens list to not hide it again automatically
+        await this.storeUnhiddenSpamToken(token);
+      }
+    } catch (err) {
+      Logger.error('Error showing token', err);
+    }
+  }
+
+  private async storeUnhiddenSpamToken(token: ERC20Token): Promise<void> {
+    const { chainId } = token;
+
+    try {
+      await update(this.UNHIDDEN_SPAM_KEY, (current: HiddenTokensStorage | undefined) => {
+        const data = current ?? {};
+        if (!data[chainId]) {
+          data[chainId] = [];
+        }
+        const alreadyStored = data[chainId].some(({ erc20TokenAddress }) =>
+          caseInsensitiveEqual(erc20TokenAddress, token.erc20TokenAddress),
+        );
+        if (!alreadyStored) {
+          data[chainId].push(token);
+        }
+        return data;
+      });
+    } catch (err) {
+      Logger.error('Error storing unhidden spam token', err);
+    }
+  }
+
+  private async deleteUnhiddenSpamToken(token: ERC20Token): Promise<void> {
+    await update(this.UNHIDDEN_SPAM_KEY, (current: HiddenTokensStorage | undefined) => {
+      const { chainId } = token;
+      const data = current ?? {};
+      data[chainId] = data[chainId]?.filter(
+        ({ erc20TokenAddress }) => !caseInsensitiveEqual(erc20TokenAddress, token.erc20TokenAddress),
+      );
+      return data;
+    });
+  }
+
+  public async getUnhiddenSpamTokens(chainId: number): Promise<ERC20Token[]> {
+    try {
+      const data = await get<HiddenTokensStorage>(this.UNHIDDEN_SPAM_KEY);
+      return data?.[chainId] || [];
+    } catch (err) {
+      Logger.error('Error retrieving unhidden spam tokens', err);
+      return [];
+    }
+  }
+
+  // From the list of tokens, hide the spam tokens that are not in the unhidden spam tokens list
+  private async hideUnnecessarySpamTokens(chainId: number, tokens: ERC20Token[]) {
+    const unhiddenSpamTokens = await this.getUnhiddenSpamTokens(chainId);
+    const unnecessarySpamTokens = tokens.filter(({ erc20TokenAddress, isSpam }) => {
+      if (!isSpam) return false;
+      return !unhiddenSpamTokens.some(({ erc20TokenAddress: unhiddenSpamTokenAddress }) =>
+        caseInsensitiveEqual(erc20TokenAddress, unhiddenSpamTokenAddress),
+      );
+    });
+
+    await Promise.all(unnecessarySpamTokens.map((token) => this.hideToken(token)));
+  }
+
+  // First hide spam tokens from the list, then fetch the all hidden tokens addresses
+  public async hideSpamsAndFetchHiddenTokensAddresses(chainId: number, tokens: ERC20Token[]) {
+    await this.hideUnnecessarySpamTokens(chainId, tokens);
+    return this.getHiddenTokenAddresses(chainId);
+  }
+}
+
+export const tokenVisibilityStorage = new TokenVisibilityStorage();

package/src/data-structures/ValueCache/ValueCache.ts

@@ -0,0 +1,29 @@
+/* eslint-disable @typescript-eslint/no-this-alias */
+export class ValueCache<T> {
+  constructor(timeoutInMs: number) {
+    this.timeoutInMs = timeoutInMs;
+    this.setTimer();
+  }
+
+  protected timeoutInMs;
+
+  public values: { [key: string]: T } = {};
+
+  private setTimer() {
+    if (this.timeoutInMs > 0) {
+      const self = this;
+      setInterval(() => {
+        self.onTimeout();
+      }, this.timeoutInMs);
+    }
+  }
+
+  // clear cache when times-up
+  private onTimeout() {
+    this.clear();
+  }
+
+  clear() {
+    this.values = {};
+  }
+}

package/src/data-structures/ValueCache/index.ts

@@ -0,0 +1 @@
+export * from './ValueCache';

package/src/data-structures/cacheDevices/AttachableMemoryCacheDevice.ts

@@ -0,0 +1,33 @@
+import { CustomJSONStringify } from '../../functions/utils/serialize.utils';
+import { BaseCacheDevice } from './BaseCacheDevice';
+
+export class AttachableMemoryCacheDevice<T> extends BaseCacheDevice<T> {
+  private isAttached = false;
+
+  override get(key: string): T | undefined {
+    return this.getInMemory(key);
+  }
+
+  override set(key: string, value: T): void {
+    this.setInMemory(key, value);
+  }
+
+  override serialize(): Record<string, string> {
+    return Object.fromEntries([...this.inMemoryCache].map(([key, value]) => [key, CustomJSONStringify(value)]));
+  }
+
+  attach<ArgsType extends unknown[]>(func: (...args: ArgsType) => T) {
+    if (this.isAttached) throw new Error("can't reattach cache device");
+    this.isAttached = true;
+    const callback = (...args: ArgsType) => {
+      const key = CustomJSONStringify(args);
+
+      const valueCandidate = this.get(key);
+      if (valueCandidate !== undefined) return valueCandidate;
+      const result = func(...args);
+      this.set(key, result);
+      return result;
+    };
+    return callback;
+  }
+}

package/src/data-structures/cacheDevices/BaseCacheDevice.ts

@@ -0,0 +1,30 @@
+import { CustomJSONParse } from '../../functions/utils/serialize.utils';
+import { ICacheDevice } from '../../types/ICacheDevice';
+
+export abstract class BaseCacheDevice<T = string> implements ICacheDevice<T> {
+  protected inMemoryCache: Map<string, T> = new Map<string, T>();
+
+  constructor(serialized?: Record<string, string>) {
+    if (serialized) this.mergeWithSerialized(serialized);
+  }
+
+  protected getInMemory(key: string): T | undefined {
+    return this.inMemoryCache.get(key) ?? undefined;
+  }
+
+  protected setInMemory(key: string, value: T): void {
+    this.inMemoryCache.set(key, value);
+  }
+
+  abstract get(key: string): T | undefined;
+
+  abstract set(key: string, value: T): void;
+
+  abstract serialize(): Record<string, string>;
+
+  mergeWithSerialized(serialized: Record<string, string>) {
+    Object.entries(serialized).forEach(([key, value]) => {
+      this.set(key, CustomJSONParse(value));
+    });
+  }
+}

package/src/data-structures/cacheDevices/FileCacheDevice.ts

@@ -0,0 +1,59 @@
+/* eslint-disable @typescript-eslint/no-var-requires */
+/* eslint-disable global-require */
+import { CustomJSONStringify } from '../../functions/utils/serialize.utils';
+import { logError } from '../../error-handling/logError';
+import { BaseCacheDevice } from './BaseCacheDevice';
+
+export class FileCacheDevice extends BaseCacheDevice {
+  private filePath: string;
+
+  private useFileCache: boolean;
+
+  constructor(useFileCache: boolean | undefined, filePath: string) {
+    super();
+    this.useFileCache = !!useFileCache;
+    this.filePath = filePath;
+    this.readFileFromDevice();
+  }
+
+  private readFileFromDevice() {
+    if (this.useFileCache && this.filePath) {
+      try {
+        const fs = require('fs');
+        if (fs.existsSync(this.filePath)) {
+          const fileContent: object = JSON.parse(fs.readFileSync(this.filePath).toString());
+          const entries = Object.entries(fileContent);
+          entries.forEach(([key, value]) => {
+            this.setInMemory(key, value);
+          });
+        }
+      } catch (err: unknown) {
+        logError('FileCacheDevice Constructor Error', { err });
+      }
+    }
+  }
+
+  get(key: string): string | undefined {
+    return this.getInMemory(key);
+  }
+
+  set(key: string, value: string): void {
+    // if somebody overwrite storage, we need to update inMemoryCache
+    this.readFileFromDevice();
+
+    this.setInMemory(key, value);
+
+    if (this.useFileCache && this.filePath) {
+      try {
+        const fs = require('fs');
+        fs.writeFileSync(this.filePath, JSON.stringify(Object.fromEntries(this.inMemoryCache)));
+      } catch (err: unknown) {
+        logError('FileCacheDevice set function', { err });
+      }
+    }
+  }
+
+  serialize(): Record<string, string> {
+    return Object.fromEntries([...this.inMemoryCache].map(([key, value]) => [key, CustomJSONStringify(value)]));
+  }
+}