@atomiqlabs/sdk 8.1.8 → 8.3.5

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 => {