@aws-amplify/core 5.8.2 → 6.0.1-console-preview.7919075.0

package/lib/Cache/BrowserStorageCache.d.ts

@@ -0,0 +1,166 @@
+import { StorageCache } from './StorageCache';
+import { ICache, CacheConfig, CacheItemOptions } from './types';
+/**
+ * Customized storage based on the SessionStorage or LocalStorage with LRU implemented
+ */
+export declare class BrowserStorageCacheClass extends StorageCache implements ICache {
+    /**
+     * initialize the cache
+     * @param config - the configuration of the cache
+     */
+    constructor(config?: CacheConfig);
+    private getStorage;
+    /**
+     * decrease current size of the cache
+     *
+     * @private
+     * @param amount - the amount of the cache size which needs to be decreased
+     */
+    private _decreaseCurSizeInBytes;
+    /**
+     * increase current size of the cache
+     *
+     * @private
+     * @param amount - the amount of the cache szie which need to be increased
+     */
+    private _increaseCurSizeInBytes;
+    /**
+     * update the visited time if item has been visited
+     *
+     * @private
+     * @param item - the item which need to be refreshed
+     * @param prefixedKey - the key of the item
+     *
+     * @return the refreshed item
+     */
+    private _refreshItem;
+    /**
+     * check wether item is expired
+     *
+     * @private
+     * @param key - the key of the item
+     *
+     * @return true if the item is expired.
+     */
+    private _isExpired;
+    /**
+     * delete item from cache
+     *
+     * @private
+     * @param prefixedKey - the key of the item
+     * @param size - optional, the byte size of the item
+     */
+    private _removeItem;
+    /**
+     * put item into cache
+     *
+     * @private
+     * @param prefixedKey - the key of the item
+     * @param itemData - the value of the item
+     * @param itemSizeInBytes - the byte size of the item
+     */
+    private _setItem;
+    /**
+     * total space needed when poping out items
+     *
+     * @private
+     * @param itemSize
+     *
+     * @return total space needed
+     */
+    private _sizeToPop;
+    /**
+     * see whether cache is full
+     *
+     * @private
+     * @param itemSize
+     *
+     * @return true if cache is full
+     */
+    private _isCacheFull;
+    /**
+     * scan the storage and find out all the keys owned by this cache
+     * also clean the expired keys while scanning
+     *
+     * @private
+     *
+     * @return array of keys
+     */
+    private _findValidKeys;
+    /**
+     * get all the items we have, sort them by their priority,
+     * if priority is same, sort them by their last visited time
+     * pop out items from the low priority (5 is the lowest)
+     *
+     * @private
+     * @param keys - all the keys in this cache
+     * @param sizeToPop - the total size of the items which needed to be poped out
+     */
+    private _popOutItems;
+    /**
+     * Set item into cache. You can put number, string, boolean or object.
+     * The cache will first check whether has the same key.
+     * If it has, it will delete the old item and then put the new item in
+     * The cache will pop out items if it is full
+     * You can specify the cache item options. The cache will abort and output a warning:
+     * If the key is invalid
+     * If the size of the item exceeds itemMaxSize.
+     * If the value is undefined
+     * If incorrect cache item configuration
+     * If error happened with browser storage
+     *
+     * @param key - the key of the item
+     * @param value - the value of the item
+     * @param {Object} [options] - optional, the specified meta-data
+     */
+    setItem(key: string, value: object | number | string | boolean, options?: CacheItemOptions): void;
+    /**
+     * Get item from cache. It will return null if item doesn’t exist or it has been expired.
+     * If you specified callback function in the options,
+     * then the function will be executed if no such item in the cache
+     * and finally put the return value into cache.
+     * Please make sure the callback function will return the value you want to put into the cache.
+     * The cache will abort output a warning:
+     * If the key is invalid
+     * If error happened with browser storage
+     *
+     * @param key - the key of the item
+     * @param {Object} [options] - the options of callback function
+     *
+     * @return - return the value of the item
+     */
+    getItem(key: string, options?: CacheItemOptions): any;
+    /**
+     * remove item from the cache
+     * The cache will abort output a warning:
+     * If error happened with browser storage
+     * @param key - the key of the item
+     */
+    removeItem(key: string): void;
+    /**
+     * clear the entire cache
+     * The cache will abort output a warning:
+     * If error happened with browser storage
+     */
+    clear(): void;
+    /**
+     * Return all the keys in the cache.
+     *
+     * @return - all keys in the cache
+     */
+    getAllKeys(): string[];
+    /**
+     * return the current size of the cache
+     *
+     * @return - current size of the cache
+     */
+    getCacheCurSize(): number;
+    /**
+     * Return a new instance of cache with customized configuration.
+     * @param config - the customized configuration
+     *
+     * @return - new instance of Cache
+     */
+    createInstance(config: CacheConfig): ICache;
+}
+export declare const BrowserStorageCache: ICache;

package/lib/Cache/BrowserStorageCache.js

@@ -0,0 +1,469 @@
+"use strict";
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+var __extends = (this && this.__extends) || (function () {
+    var extendStatics = function (d, b) {
+        extendStatics = Object.setPrototypeOf ||
+            ({ __proto__: [] } instanceof Array && function (d, b) { d.__proto__ = b; }) ||
+            function (d, b) { for (var p in b) if (Object.prototype.hasOwnProperty.call(b, p)) d[p] = b[p]; };
+        return extendStatics(d, b);
+    };
+    return function (d, b) {
+        if (typeof b !== "function" && b !== null)
+            throw new TypeError("Class extends value " + String(b) + " is not a constructor or null");
+        extendStatics(d, b);
+        function __() { this.constructor = d; }
+        d.prototype = b === null ? Object.create(b) : (__.prototype = b.prototype, new __());
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BrowserStorageCache = exports.BrowserStorageCacheClass = void 0;
+var Logger_1 = require("../Logger");
+var Utils_1 = require("./Utils");
+var StorageCache_1 = require("./StorageCache");
+var AssertError_1 = require("../Util/errors/AssertError");
+var constants_1 = require("../constants");
+var CacheUtils_1 = require("./Utils/CacheUtils");
+var logger = new Logger_1.ConsoleLogger('Cache');
+/**
+ * Customized storage based on the SessionStorage or LocalStorage with LRU implemented
+ */
+var BrowserStorageCacheClass = /** @class */ (function (_super) {
+    __extends(BrowserStorageCacheClass, _super);
+    /**
+     * initialize the cache
+     * @param config - the configuration of the cache
+     */
+    function BrowserStorageCacheClass(config) {
+        var _this = _super.call(this, config) || this;
+        (0, AssertError_1.asserts)(!!_this.cacheConfig.storage, {
+            name: constants_1.STORAGE_CACHE_EXCEPTION,
+            message: 'Storage is not defined in the cache config',
+        });
+        _this.cacheConfig.storage = _this.cacheConfig.storage;
+        _this.getItem = _this.getItem.bind(_this);
+        _this.setItem = _this.setItem.bind(_this);
+        _this.removeItem = _this.removeItem.bind(_this);
+        return _this;
+    }
+    BrowserStorageCacheClass.prototype.getStorage = function () {
+        (0, AssertError_1.asserts)(!!this.cacheConfig.storage, {
+            name: constants_1.STORAGE_CACHE_EXCEPTION,
+            message: 'Storage is not defined in the cache config',
+        });
+        return this.cacheConfig.storage;
+    };
+    /**
+     * decrease current size of the cache
+     *
+     * @private
+     * @param amount - the amount of the cache size which needs to be decreased
+     */
+    BrowserStorageCacheClass.prototype._decreaseCurSizeInBytes = function (amount) {
+        var curSize = this.getCacheCurSize();
+        this.getStorage().setItem((0, CacheUtils_1.getCurrSizeKey)(this.cacheConfig.keyPrefix), (curSize - amount).toString());
+    };
+    /**
+     * increase current size of the cache
+     *
+     * @private
+     * @param amount - the amount of the cache szie which need to be increased
+     */
+    BrowserStorageCacheClass.prototype._increaseCurSizeInBytes = function (amount) {
+        var curSize = this.getCacheCurSize();
+        this.getStorage().setItem((0, CacheUtils_1.getCurrSizeKey)(this.cacheConfig.keyPrefix), (curSize + amount).toString());
+    };
+    /**
+     * update the visited time if item has been visited
+     *
+     * @private
+     * @param item - the item which need to be refreshed
+     * @param prefixedKey - the key of the item
+     *
+     * @return the refreshed item
+     */
+    BrowserStorageCacheClass.prototype._refreshItem = function (item, prefixedKey) {
+        item.visitedTime = (0, Utils_1.getCurrTime)();
+        this.getStorage().setItem(prefixedKey, JSON.stringify(item));
+        return item;
+    };
+    /**
+     * check wether item is expired
+     *
+     * @private
+     * @param key - the key of the item
+     *
+     * @return true if the item is expired.
+     */
+    BrowserStorageCacheClass.prototype._isExpired = function (key) {
+        var text = this.getStorage().getItem(key);
+        (0, AssertError_1.asserts)(text !== null, {
+            name: constants_1.STORAGE_CACHE_EXCEPTION,
+            message: "Item not found in the storage by the key: ".concat(key, "."),
+        });
+        var item = JSON.parse(text);
+        if ((0, Utils_1.getCurrTime)() >= item.expires) {
+            return true;
+        }
+        return false;
+    };
+    /**
+     * delete item from cache
+     *
+     * @private
+     * @param prefixedKey - the key of the item
+     * @param size - optional, the byte size of the item
+     */
+    BrowserStorageCacheClass.prototype._removeItem = function (prefixedKey, size) {
+        var item = this.getStorage().getItem(prefixedKey);
+        (0, AssertError_1.asserts)(item !== null, {
+            name: constants_1.STORAGE_CACHE_EXCEPTION,
+            message: "Item not found in the storage by the key: ".concat(prefixedKey, "."),
+        });
+        var itemSize = size !== null && size !== void 0 ? size : JSON.parse(item).byteSize;
+        this._decreaseCurSizeInBytes(itemSize);
+        // remove the cache item
+        this.getStorage().removeItem(prefixedKey);
+    };
+    /**
+     * put item into cache
+     *
+     * @private
+     * @param prefixedKey - the key of the item
+     * @param itemData - the value of the item
+     * @param itemSizeInBytes - the byte size of the item
+     */
+    BrowserStorageCacheClass.prototype._setItem = function (prefixedKey, item) {
+        // update the cache size
+        this._increaseCurSizeInBytes(item.byteSize);
+        try {
+            this.getStorage().setItem(prefixedKey, JSON.stringify(item));
+        }
+        catch (setItemErr) {
+            // if failed, we need to rollback the cache size
+            this._decreaseCurSizeInBytes(item.byteSize);
+            logger.error("Failed to set item ".concat(setItemErr));
+        }
+    };
+    /**
+     * total space needed when poping out items
+     *
+     * @private
+     * @param itemSize
+     *
+     * @return total space needed
+     */
+    BrowserStorageCacheClass.prototype._sizeToPop = function (itemSize) {
+        var spaceItemNeed = this.getCacheCurSize() + itemSize - this.cacheConfig.capacityInBytes;
+        var cacheThresholdSpace = (1 - this.cacheConfig.warningThreshold) *
+            this.cacheConfig.capacityInBytes;
+        return spaceItemNeed > cacheThresholdSpace
+            ? spaceItemNeed
+            : cacheThresholdSpace;
+    };
+    /**
+     * see whether cache is full
+     *
+     * @private
+     * @param itemSize
+     *
+     * @return true if cache is full
+     */
+    BrowserStorageCacheClass.prototype._isCacheFull = function (itemSize) {
+        return itemSize + this.getCacheCurSize() > this.cacheConfig.capacityInBytes;
+    };
+    /**
+     * scan the storage and find out all the keys owned by this cache
+     * also clean the expired keys while scanning
+     *
+     * @private
+     *
+     * @return array of keys
+     */
+    BrowserStorageCacheClass.prototype._findValidKeys = function () {
+        var keys = [];
+        var keyInCache = [];
+        // get all keys in Storage
+        for (var i = 0; i < this.getStorage().length; i += 1) {
+            var key = this.getStorage().key(i);
+            if (key) {
+                keyInCache.push(key);
+            }
+        }
+        // find those items which belong to our cache and also clean those expired items
+        for (var i = 0; i < keyInCache.length; i += 1) {
+            var key = keyInCache[i];
+            if (key.indexOf(this.cacheConfig.keyPrefix) === 0 &&
+                key !== (0, CacheUtils_1.getCurrSizeKey)(this.cacheConfig.keyPrefix)) {
+                if (this._isExpired(key)) {
+                    this._removeItem(key);
+                }
+                else {
+                    keys.push(key);
+                }
+            }
+        }
+        return keys;
+    };
+    /**
+     * get all the items we have, sort them by their priority,
+     * if priority is same, sort them by their last visited time
+     * pop out items from the low priority (5 is the lowest)
+     *
+     * @private
+     * @param keys - all the keys in this cache
+     * @param sizeToPop - the total size of the items which needed to be poped out
+     */
+    BrowserStorageCacheClass.prototype._popOutItems = function (keys, sizeToPop) {
+        var items = [];
+        var remainedSize = sizeToPop;
+        // get the items from Storage
+        for (var i = 0; i < keys.length; i += 1) {
+            var val = this.getStorage().getItem(keys[i]);
+            if (val != null) {
+                var item = JSON.parse(val);
+                items.push(item);
+            }
+        }
+        // first compare priority
+        // then compare visited time
+        items.sort(function (a, b) {
+            if (a.priority > b.priority) {
+                return -1;
+            }
+            else if (a.priority < b.priority) {
+                return 1;
+            }
+            else {
+                if (a.visitedTime < b.visitedTime) {
+                    return -1;
+                }
+                else
+                    return 1;
+            }
+        });
+        for (var i = 0; i < items.length; i += 1) {
+            // pop out items until we have enough room for new item
+            this._removeItem(items[i].key, items[i].byteSize);
+            remainedSize -= items[i].byteSize;
+            if (remainedSize <= 0) {
+                return;
+            }
+        }
+    };
+    /**
+     * Set item into cache. You can put number, string, boolean or object.
+     * The cache will first check whether has the same key.
+     * If it has, it will delete the old item and then put the new item in
+     * The cache will pop out items if it is full
+     * You can specify the cache item options. The cache will abort and output a warning:
+     * If the key is invalid
+     * If the size of the item exceeds itemMaxSize.
+     * If the value is undefined
+     * If incorrect cache item configuration
+     * If error happened with browser storage
+     *
+     * @param key - the key of the item
+     * @param value - the value of the item
+     * @param {Object} [options] - optional, the specified meta-data
+     */
+    BrowserStorageCacheClass.prototype.setItem = function (key, value, options) {
+        logger.log("Set item: key is ".concat(key, ", value is ").concat(value, " with options: ").concat(options));
+        var prefixedKey = this.cacheConfig.keyPrefix + key;
+        // invalid keys
+        if (prefixedKey === this.cacheConfig.keyPrefix ||
+            prefixedKey === (0, CacheUtils_1.getCurrSizeKey)(this.cacheConfig.keyPrefix)) {
+            logger.warn("Invalid key: should not be empty or 'CurSize'");
+            return;
+        }
+        if (typeof value === 'undefined') {
+            logger.warn("The value of item should not be undefined!");
+            return;
+        }
+        var cacheItemOptions = {
+            priority: options && options.priority !== undefined
+                ? options.priority
+                : this.cacheConfig.defaultPriority,
+            expires: options && options.expires !== undefined
+                ? options.expires
+                : this.cacheConfig.defaultTTL + (0, Utils_1.getCurrTime)(),
+        };
+        if (cacheItemOptions.priority < 1 || cacheItemOptions.priority > 5) {
+            logger.warn("Invalid parameter: priority due to out or range. It should be within 1 and 5.");
+            return;
+        }
+        var item = this.fillCacheItem(prefixedKey, value, cacheItemOptions);
+        // check wether this item is too big;
+        if (item.byteSize > this.cacheConfig.itemMaxSize) {
+            logger.warn("Item with key: ".concat(key, " you are trying to put into is too big!"));
+            return;
+        }
+        try {
+            // first look into the storage, if it exists, delete it.
+            var val = this.getStorage().getItem(prefixedKey);
+            if (val) {
+                this._removeItem(prefixedKey, JSON.parse(val).byteSize);
+            }
+            // check whether the cache is full
+            if (this._isCacheFull(item.byteSize)) {
+                var validKeys = this._findValidKeys();
+                // check again and then pop out items
+                if (this._isCacheFull(item.byteSize)) {
+                    var sizeToPop = this._sizeToPop(item.byteSize);
+                    this._popOutItems(validKeys, sizeToPop);
+                }
+            }
+            // put item in the cache
+            // may failed due to storage full
+            this._setItem(prefixedKey, item);
+        }
+        catch (e) {
+            logger.warn("setItem failed! ".concat(e));
+        }
+    };
+    /**
+     * Get item from cache. It will return null if item doesn’t exist or it has been expired.
+     * If you specified callback function in the options,
+     * then the function will be executed if no such item in the cache
+     * and finally put the return value into cache.
+     * Please make sure the callback function will return the value you want to put into the cache.
+     * The cache will abort output a warning:
+     * If the key is invalid
+     * If error happened with browser storage
+     *
+     * @param key - the key of the item
+     * @param {Object} [options] - the options of callback function
+     *
+     * @return - return the value of the item
+     */
+    BrowserStorageCacheClass.prototype.getItem = function (key, options) {
+        logger.log("Get item: key is ".concat(key, " with options ").concat(options));
+        var ret = null;
+        var prefixedKey = this.cacheConfig.keyPrefix + key;
+        if (prefixedKey === this.cacheConfig.keyPrefix ||
+            prefixedKey === (0, CacheUtils_1.getCurrSizeKey)(this.cacheConfig.keyPrefix)) {
+            logger.warn("Invalid key: should not be empty or 'CurSize'");
+            return null;
+        }
+        try {
+            ret = this.getStorage().getItem(prefixedKey);
+            if (ret != null) {
+                if (this._isExpired(prefixedKey)) {
+                    // if expired, remove that item and return null
+                    this._removeItem(prefixedKey, JSON.parse(ret).byteSize);
+                    ret = null;
+                }
+                else {
+                    // if not expired, great, return the value and refresh it
+                    var item = JSON.parse(ret);
+                    item = this._refreshItem(item, prefixedKey);
+                    return item.data;
+                }
+            }
+            if (options && options.callback !== undefined) {
+                var val = options.callback();
+                if (val !== null) {
+                    this.setItem(key, val, options);
+                }
+                return val;
+            }
+            return null;
+        }
+        catch (e) {
+            logger.warn("getItem failed! ".concat(e));
+            return null;
+        }
+    };
+    /**
+     * remove item from the cache
+     * The cache will abort output a warning:
+     * If error happened with browser storage
+     * @param key - the key of the item
+     */
+    BrowserStorageCacheClass.prototype.removeItem = function (key) {
+        logger.log("Remove item: key is ".concat(key));
+        var prefixedKey = this.cacheConfig.keyPrefix + key;
+        if (prefixedKey === this.cacheConfig.keyPrefix ||
+            prefixedKey === (0, CacheUtils_1.getCurrSizeKey)(this.cacheConfig.keyPrefix)) {
+            return;
+        }
+        try {
+            var val = this.getStorage().getItem(prefixedKey);
+            if (val) {
+                this._removeItem(prefixedKey, JSON.parse(val).byteSize);
+            }
+        }
+        catch (e) {
+            logger.warn("removeItem failed! ".concat(e));
+        }
+    };
+    /**
+     * clear the entire cache
+     * The cache will abort output a warning:
+     * If error happened with browser storage
+     */
+    BrowserStorageCacheClass.prototype.clear = function () {
+        logger.log("Clear Cache");
+        var keysToRemove = [];
+        for (var i = 0; i < this.getStorage().length; i += 1) {
+            var key = this.getStorage().key(i);
+            if ((key === null || key === void 0 ? void 0 : key.indexOf(this.cacheConfig.keyPrefix)) === 0) {
+                keysToRemove.push(key);
+            }
+        }
+        try {
+            for (var i = 0; i < keysToRemove.length; i += 1) {
+                this.getStorage().removeItem(keysToRemove[i]);
+            }
+        }
+        catch (e) {
+            logger.warn("clear failed! ".concat(e));
+        }
+    };
+    /**
+     * Return all the keys in the cache.
+     *
+     * @return - all keys in the cache
+     */
+    BrowserStorageCacheClass.prototype.getAllKeys = function () {
+        var keys = [];
+        for (var i = 0; i < this.getStorage().length; i += 1) {
+            var key = this.getStorage().key(i);
+            if (key &&
+                key.indexOf(this.cacheConfig.keyPrefix) === 0 &&
+                key !== (0, CacheUtils_1.getCurrSizeKey)(this.cacheConfig.keyPrefix)) {
+                keys.push(key.substring(this.cacheConfig.keyPrefix.length));
+            }
+        }
+        return keys;
+    };
+    /**
+     * return the current size of the cache
+     *
+     * @return - current size of the cache
+     */
+    BrowserStorageCacheClass.prototype.getCacheCurSize = function () {
+        var ret = this.getStorage().getItem((0, CacheUtils_1.getCurrSizeKey)(this.cacheConfig.keyPrefix));
+        if (!ret) {
+            this.getStorage().setItem((0, CacheUtils_1.getCurrSizeKey)(this.cacheConfig.keyPrefix), '0');
+            ret = '0';
+        }
+        return Number(ret);
+    };
+    /**
+     * Return a new instance of cache with customized configuration.
+     * @param config - the customized configuration
+     *
+     * @return - new instance of Cache
+     */
+    BrowserStorageCacheClass.prototype.createInstance = function (config) {
+        if (!config.keyPrefix || config.keyPrefix === Utils_1.defaultConfig.keyPrefix) {
+            logger.error('invalid keyPrefix, setting keyPrefix with timeStamp');
+            config.keyPrefix = Utils_1.getCurrTime.toString();
+        }
+        return new BrowserStorageCacheClass(config);
+    };
+    return BrowserStorageCacheClass;
+}(StorageCache_1.StorageCache));
+exports.BrowserStorageCacheClass = BrowserStorageCacheClass;
+exports.BrowserStorageCache = new BrowserStorageCacheClass();