@atomiqlabs/sdk 8.1.7 → 8.3.1

package/src/prices/providers/KrakenPriceProvider.ts

@@ -30,6 +30,9 @@ export class KrakenPriceProvider<T extends MultiChain> extends ExchangePriceProv
         super(coinsMap, url, httpRequestTimeout);
     }
 
+    /**
+     * @inheritDoc
+     */
     protected async fetchPair(pair: string, abortSignal?: AbortSignal) {
         const response = await httpGet<KrakenResponse>(
             this.url+"/public/Ticker?pair="+pair,
@@ -40,6 +43,9 @@ export class KrakenPriceProvider<T extends MultiChain> extends ExchangePriceProv
         return parseFloat(response.result[pair].c[0]);
     }
 
+    /**
+     * @inheritDoc
+     */
     protected async fetchUsdPrice(abortSignal?: AbortSignal): Promise<number> {
         const response = await httpGet<KrakenResponse>(
             this.url+"/public/Ticker?pair=XBTUSDC",
@@ -50,6 +56,9 @@ export class KrakenPriceProvider<T extends MultiChain> extends ExchangePriceProv
         return parseFloat(response.result["XBTUSDC"].c[0])/100000000;
     }
 
+    /**
+     * @inheritDoc
+     */
     protected async fetchPrice(token: CoinType, abortSignal?: AbortSignal): Promise<bigint> {
         const pairs: string[] = token.coinId.split(";");
 

package/src/prices/providers/OKXPriceProvider.ts

@@ -30,6 +30,9 @@ export class OKXPriceProvider<T extends MultiChain> extends ExchangePriceProvide
         super(coinsMap, url, httpRequestTimeout);
     }
 
+    /**
+     * @inheritDoc
+     */
     async fetchPair(pair: string, abortSignal?: AbortSignal) {
         const response = await httpGet<OKXResponse>(
             this.url+"/market/index-tickers?instId="+pair,
@@ -40,6 +43,9 @@ export class OKXPriceProvider<T extends MultiChain> extends ExchangePriceProvide
         return parseFloat(response.data[0].idxPx);
     }
 
+    /**
+     * @inheritDoc
+     */
     protected async fetchUsdPrice(abortSignal?: AbortSignal): Promise<number> {
         const response = await httpGet<OKXResponse>(
             this.url+"/market/index-tickers?instId=BTC-USD",

package/src/prices/providers/abstract/ExchangePriceProvider.ts

@@ -13,6 +13,9 @@ export abstract class ExchangePriceProvider<T extends MultiChain> extends HttpPr
      */
     protected abstract fetchPair(pair: string, abortSignal?: AbortSignal): Promise<number>;
 
+    /**
+     * @inheritDoc
+     */
     protected async fetchPrice(token: CoinType, abortSignal?: AbortSignal): Promise<bigint> {
         const pairs: string[] = token.coinId.split(";");
         const prices: number[] = await Promise.all(pairs.map(pair => {

package/src/storage/IUnifiedStorage.ts

@@ -1,21 +1,30 @@
 
 /**
- * Query parameters for storage operations
+ * Params for querying the storage
+ *
  * @category Storage
  */
 export type QueryParams = {
+    /**
+     * Key that should be matched
+     */
     key: string,
+    /**
+     * A value that the key needs to have, if an array is passed, the conditions are `OR`-ed
+     */
     value: any | any[]
 };
 
 /**
- * Base type for stored objects
+ * Base type for stored objects, every storage object MUST have an `id` field
+ *
  * @category Storage
  */
 export type UnifiedStoredObject = {id: string} & any;
 
 /**
  * Defines simple indexes (for queries that use a single key)
+ *
  * @category Storage
  */
 export type UnifiedStorageIndexes = readonly {
@@ -27,6 +36,7 @@ export type UnifiedStorageIndexes = readonly {
 
 /**
  * Defines composite indexes (for queries that use multiple keys)
+ *
  * @category Storage
  */
 export type UnifiedStorageCompositeIndexes = readonly {
@@ -35,13 +45,15 @@ export type UnifiedStorageCompositeIndexes = readonly {
 }[];
 
 /**
- * Interface for unified storage implementations
+ * Interface for a generic unified storage implementations
+ *
  * @category Storage
  */
 export interface IUnifiedStorage<I extends UnifiedStorageIndexes, C extends UnifiedStorageCompositeIndexes> {
 
     /**
      * Initializes the storage with given indexes and composite indexes
+     *
      * @param indexes
      * @param compositeIndexes
      */
@@ -58,25 +70,25 @@ export interface IUnifiedStorage<I extends UnifiedStorageIndexes, C extends Unif
 
     /**
      * Saves an object to storage, updating indexes as needed
-     * @param value - Object to save (must have an id property)
+     * @param value Object to save (must have an id property)
      */
     save(value: UnifiedStoredObject): Promise<void>;
 
     /**
      * Saves multiple objects to storage in a batch operation
-     * @param value - Array of objects to save
+     * @param value Array of objects to save
      */
     saveAll(value: UnifiedStoredObject[]): Promise<void>;
 
     /**
      * Removes an object from storage
-     * @param value - Object to remove (must have an id property)
+     * @param value Object to remove (must have an id property)
      */
     remove(value: UnifiedStoredObject): Promise<void>;
 
     /**
      * Removes multiple objects from storage in a batch operation
-     * @param value - Array of objects to remove
+     * @param value Array of objects to remove
      */
     removeAll(value: UnifiedStoredObject[]): Promise<void>;
 

package/src/storage/UnifiedSwapStorage.ts

@@ -15,7 +15,8 @@ const indexes = [
     {key: "paymentHash", type: "string", unique: false, nullable: true},
 ] as const;
 /**
- * Index types for swap storage
+ * Simple index types for SDK swap storage
+ *
  * @category Storage
  */
 export type UnifiedSwapStorageIndexes = typeof indexes;
@@ -27,13 +28,16 @@ const compositeIndexes = [
     {keys: ["type", "initiator", "state"], unique: false}
 ] as const;
 /**
- * Composite index types for swap storage
+ * Composite index types for SDK swap storage
+ *
  * @category Storage
  */
 export type UnifiedSwapStorageCompositeIndexes = typeof compositeIndexes;
 
 /**
- * Unified swap persistence layer with caching
+ * Unified swap persistence layer for the SDK utilizing an underlying {@link IUnifiedStorage} instance
+ *  with optional in-memory caching via weak refs {@link WeakRef}
+ *
  * @category Storage
  */
 export class UnifiedSwapStorage<T extends ChainType> {
@@ -42,11 +46,20 @@ export class UnifiedSwapStorage<T extends ChainType> {
     readonly weakRefCache: Map<string, WeakRef<ISwap<T>>> = new Map();
     readonly noWeakRefMap?: boolean;
 
+    /**
+     * @param storage Underlying storage persistence layer
+     * @param noWeakRefMap Whether to disable caching of the swap objects in the weak ref map, this
+     *  should be set when you need multiple different clients accessing the same swap database (such
+     *  as when running the SDK in a serverless environment like AWS or Azure)
+     */
     constructor(storage: IUnifiedStorage<UnifiedSwapStorageIndexes, UnifiedSwapStorageCompositeIndexes>, noWeakRefMap?: boolean) {
         this.storage = storage;
         this.noWeakRefMap = noWeakRefMap;
     }
 
+    /**
+     * Initializes the underlying storage
+     */
     init(): Promise<void> {
         return this.storage.init(indexes, compositeIndexes);
     }
@@ -81,21 +94,38 @@ export class UnifiedSwapStorage<T extends ChainType> {
         return result;
     }
 
+    /**
+     * Saves the swap to storage, updating indexes as needed
+     *
+     * @param value Swap to save
+     */
     save<S extends ISwap<T>>(value: S): Promise<void> {
         if(!this.noWeakRefMap) this.weakRefCache.set(value.getId(), new WeakRef<ISwap<T>>(value));
         return this.storage.save(value.serialize());
     }
 
+    /**
+     * Saves multiple swaps to storage in a batch operation
+     * @param values Array of swaps to save
+     */
     saveAll<S extends ISwap<T>>(values: S[]): Promise<void> {
         if(!this.noWeakRefMap) values.forEach(value => this.weakRefCache.set(value.getId(), new WeakRef<ISwap<T>>(value)));
         return this.storage.saveAll(values.map(obj => obj.serialize()));
     }
 
+    /**
+     * Removes a swap from storage
+     * @param value Swap to remove
+     */
     remove<S extends ISwap<T>>(value: S): Promise<void> {
         if(!this.noWeakRefMap) this.weakRefCache.delete(value.getId());
         return this.storage.remove(value.serialize());
     }
 
+    /**
+     * Removes multiple swaps from storage in a batch operation
+     * @param values Array of swaps to remove
+     */
     removeAll<S extends ISwap<T>>(values: S[]): Promise<void> {
         if(!this.noWeakRefMap) values.forEach(value => this.weakRefCache.delete(value.getId()));
         return this.storage.removeAll(values.map(obj => obj.serialize()));

package/src/storage-browser/IndexedDBUnifiedStorage.ts

@@ -60,13 +60,14 @@ const indexes: Record<string, {key: string | string[], unique: boolean}> = {
 
 /**
  * Browser IndexedDB storage implementation
+ *
  * @category Storage
  */
 export class IndexedDBUnifiedStorage implements IUnifiedStorage<UnifiedSwapStorageIndexes, UnifiedStorageCompositeIndexes> {
 
     protected readonly logger: LoggerType;
 
-    storageKey: string;
+    readonly storageKey: string;
     db?: IDBDatabase;
 
     constructor(storageKey: string) {
@@ -166,7 +167,15 @@ export class IndexedDBUnifiedStorage implements IUnifiedStorage<UnifiedSwapStora
         }
     }
 
-    //NOTE: Reviver also needs to update the swap to the latest version
+    /**
+     * Attempts to migrate the swap database from old implementations (either using prior version of IndexedDB or
+     *  Local Storage)
+     *
+     * NOTE: Reviver also needs to update the swap to the latest version
+     *
+     * @param storageKeys An array of tuples of storage keys used for the corresponding swap types
+     * @param reviver Swap data deserializer
+     */
     public async tryMigrate(storageKeys: [string, SwapType][], reviver: (obj: any) => ISwap): Promise<boolean> {
         let someMigrated = false;
         for(let storageKey of storageKeys) {
@@ -231,6 +240,9 @@ export class IndexedDBUnifiedStorage implements IUnifiedStorage<UnifiedSwapStora
         return result.flat();
     }
 
+    /**
+     * @inheritDoc
+     */
     async init(): Promise<void> {
         if(this.db==null) {
             this.db = await new Promise<IDBDatabase>((resolve, reject) => {
@@ -251,11 +263,7 @@ export class IndexedDBUnifiedStorage implements IUnifiedStorage<UnifiedSwapStora
     }
 
     /**
-     * Params are specified in the following way:
-     *  - [[condition1, condition2]] - returns all rows where condition1 AND condition2 is met
-     *  - [[condition1], [condition2]] - returns all rows where condition1 OR condition2 is met
-     *  - [[condition1, condition2], [condition3]] - returns all rows where (condition1 AND condition2) OR condition3 is met
-     * @param params
+     * @inheritDoc
      */
     async query(params: Array<Array<QueryParams>>): Promise<Array<UnifiedStoredObject>> {
         if(params.length===0) return await this.querySingle([]);
@@ -264,7 +272,10 @@ export class IndexedDBUnifiedStorage implements IUnifiedStorage<UnifiedSwapStora
         return Array.from(resultSet);
     }
 
-    async querySingle(params: Array<QueryParams>): Promise<Array<UnifiedStoredObject>> {
+    /**
+     * @internal
+     */
+    protected async querySingle(params: Array<QueryParams>): Promise<Array<UnifiedStoredObject>> {
         if(params.length===0) {
             return await this.executeTransaction((objectStore) => objectStore.getAll(), true);
         }
@@ -302,11 +313,17 @@ export class IndexedDBUnifiedStorage implements IUnifiedStorage<UnifiedSwapStora
         }
     }
 
+    /**
+     * @inheritDoc
+     */
     async remove(object: UnifiedStoredObject): Promise<void> {
         await this.executeTransaction<undefined>(store => store.delete(object.id), false)
             .catch(() => null);
     }
 
+    /**
+     * @inheritDoc
+     */
     async removeAll(arr: UnifiedStoredObject[]): Promise<void> {
         if(arr.length===0) return;
         await this.executeTransactionArr<undefined>(store => arr.map(object => {
@@ -314,10 +331,16 @@ export class IndexedDBUnifiedStorage implements IUnifiedStorage<UnifiedSwapStora
         }), false);
     }
 
+    /**
+     * @inheritDoc
+     */
     async save(object: UnifiedStoredObject): Promise<void> {
         await this.executeTransaction<IDBValidKey>(store => store.put(object), false);
     }
 
+    /**
+     * @inheritDoc
+     */
     async saveAll(arr: UnifiedStoredObject[]): Promise<void> {
         if(arr.length===0) return;
         await this.executeTransactionArr<IDBValidKey>(store => arr.map(object => {

package/src/storage-browser/LocalStorageManager.ts

@@ -1,7 +1,9 @@
 import {IStorageManager, StorageObject} from "@atomiqlabs/base";
 
 /**
- * StorageManager using browser's local storage API
+ * {@link IStorageManager} implementation using browser's local storage API, this is used as general purpose
+ *  key-value storage, not used for storing swaps! See {@link IUnifiedStorage} for swap storage interface.
+ *
  * @category Storage
  */
 export class LocalStorageManager<T extends StorageObject> implements IStorageManager<T> {
@@ -15,10 +17,17 @@ export class LocalStorageManager<T extends StorageObject> implements IStorageMan
         [hash: string]: T
     } = {};
 
+    /**
+     * @param storageKey The key-value store is stored as JSON serialized parameter of the Local Storage under
+     *  the specified `storageKey`
+     */
     constructor(storageKey: string) {
         this.storageKey = storageKey;
     }
 
+    /**
+     * @inheritDoc
+     */
     init(): Promise<void> {
         const completedTxt = window.localStorage.getItem(this.storageKey);
         if(completedTxt!=null) {
@@ -30,6 +39,9 @@ export class LocalStorageManager<T extends StorageObject> implements IStorageMan
         return Promise.resolve();
     }
 
+    /**
+     * @inheritDoc
+     */
     saveData(hash: string, object: T): Promise<void> {
         this.data[hash] = object;
         this.rawData[hash] = object.serialize();
@@ -37,6 +49,9 @@ export class LocalStorageManager<T extends StorageObject> implements IStorageMan
         return this.save();
     }
 
+    /**
+     * @inheritDoc
+     */
     saveDataArr(arr: {id: string, object: T}[]): Promise<void> {
         arr.forEach(e => {
             this.data[e.id] = e.object;
@@ -46,6 +61,9 @@ export class LocalStorageManager<T extends StorageObject> implements IStorageMan
         return this.save();
     }
 
+    /**
+     * @inheritDoc
+     */
     removeData(hash: string): Promise<void> {
         if(this.rawData[hash]!=null) {
             if(this.data[hash]!=null) delete this.data[hash];
@@ -55,6 +73,9 @@ export class LocalStorageManager<T extends StorageObject> implements IStorageMan
         return Promise.resolve();
     }
 
+    /**
+     * @inheritDoc
+     */
     removeDataArr(hashArr: string[]): Promise<void> {
         hashArr.forEach(hash => {
             if(this.rawData[hash]!=null) {
@@ -65,6 +86,9 @@ export class LocalStorageManager<T extends StorageObject> implements IStorageMan
         return this.save();
     }
 
+    /**
+     * @inheritDoc
+     */
     loadData(type: new (data: any) => T): Promise<T[]> {
         return Promise.resolve(
             Object.keys(this.rawData).map(e => {