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

package/src/Cache/InMemoryCache.ts

@@ -0,0 +1,354 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { CacheList, defaultConfig, getCurrTime, CacheObject } from './Utils';
+
+import { StorageCache } from './StorageCache';
+import { ICache, CacheConfig, CacheItem, CacheItemOptions } from './types';
+import { ConsoleLogger as Logger } from '../Logger';
+import { asserts } from '../Util/errors/AssertError';
+import { STORAGE_CACHE_EXCEPTION } from '../constants';
+import { getCurrSizeKey } from './Utils/CacheUtils';
+
+const logger = new Logger('InMemoryCache');
+
+/**
+ * Customized in-memory cache with LRU implemented
+ * @member cacheObj - object which store items
+ * @member cacheList - list of keys in the cache with LRU
+ * @member curSizeInBytes - current size of the cache
+ * @member maxPriority - max of the priority
+ */
+export class InMemoryCacheClass extends StorageCache implements ICache {
+	private cacheList: CacheList[];
+	private curSizeInBytes: number;
+	private maxPriority: number;
+
+	/**
+	 * initialize the cache
+	 *
+	 * @param config - the configuration of the cache
+	 */
+	constructor(config?: CacheConfig) {
+		super(config);
+
+		this.cacheList = [];
+		this.curSizeInBytes = 0;
+		this.maxPriority = 5;
+
+		this.getItem = this.getItem.bind(this);
+		this.setItem = this.setItem.bind(this);
+		this.removeItem = this.removeItem.bind(this);
+
+		// initialize list for every priority
+		for (let i = 0; i < this.maxPriority; i += 1) {
+			this.cacheList[i] = new CacheList();
+		}
+	}
+
+	/**
+	 * decrease current size of the cache
+	 *
+	 * @param amount - the amount of the cache size which needs to be decreased
+	 */
+	private _decreaseCurSizeInBytes(amount: number): void {
+		this.curSizeInBytes -= amount;
+	}
+
+	/**
+	 * increase current size of the cache
+	 *
+	 * @param amount - the amount of the cache szie which need to be increased
+	 */
+	private _increaseCurSizeInBytes(amount: number): void {
+		this.curSizeInBytes += amount;
+	}
+
+	/**
+	 * check whether item is expired
+	 *
+	 * @param key - the key of the item
+	 *
+	 * @return true if the item is expired.
+	 */
+	private _isExpired(key: string): boolean {
+		const text: string | null = CacheObject.getItem(key);
+
+		asserts(text !== null, {
+			name: STORAGE_CACHE_EXCEPTION,
+			message: 'item from storage is null',
+		});
+		const item: CacheItem = JSON.parse(text);
+		if (getCurrTime() >= item.expires) {
+			return true;
+		}
+		return false;
+	}
+
+	/**
+	 * delete item from cache
+	 *
+	 * @param prefixedKey - the key of the item
+	 * @param listIdx - indicates which cache list the key belongs to
+	 */
+	private _removeItem(prefixedKey: string, listIdx: number): void {
+		// delete the key from the list
+		this.cacheList[listIdx].removeItem(prefixedKey);
+		// decrease the current size of the cache
+		const item = CacheObject.getItem(prefixedKey);
+		asserts(item !== null, {
+			name: STORAGE_CACHE_EXCEPTION,
+			message: 'item from storage is null',
+		});
+		this._decreaseCurSizeInBytes(JSON.parse(item).byteSize);
+		// finally remove the item from memory
+		CacheObject.removeItem(prefixedKey);
+	}
+
+	/**
+	 * put item into cache
+	 *
+	 * @param prefixedKey - the key of the item
+	 * @param itemData - the value of the item
+	 * @param itemSizeInBytes - the byte size of the item
+	 * @param listIdx - indicates which cache list the key belongs to
+	 */
+	private _setItem(
+		prefixedKey: string,
+		item: CacheItem,
+		listIdx: number
+	): void {
+		// insert the key into the list
+		this.cacheList[listIdx].insertItem(prefixedKey);
+		// increase the current size of the cache
+		this._increaseCurSizeInBytes(item.byteSize);
+		// finally add the item into memory
+		CacheObject.setItem(prefixedKey, JSON.stringify(item));
+	}
+
+	/**
+	 * see whether cache is full
+	 *
+	 * @param itemSize
+	 *
+	 * @return true if cache is full
+	 */
+	private _isCacheFull(itemSize: number): boolean {
+		return this.curSizeInBytes + itemSize > this.cacheConfig.capacityInBytes;
+	}
+
+	/**
+	 * check whether the cache contains the key
+	 *
+	 * @param key
+	 */
+	private containsKey(key: string): number {
+		const prefixedKey: string = this.cacheConfig.keyPrefix + key;
+		for (let i = 0; i < this.maxPriority; i += 1) {
+			if (this.cacheList[i].containsKey(prefixedKey)) {
+				return i + 1;
+			}
+		}
+		return -1;
+	}
+
+	/**
+	 * * 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 options - optional, the specified meta-data
+	 *
+	 * @throws if the item is too big which exceeds the limit of single item size
+	 * @throws if the key is invalid
+	 */
+	public setItem(
+		key: string,
+		value: object | string | number | boolean,
+		options?: CacheItemOptions
+	): void {
+		const prefixedKey: string = this.cacheConfig.keyPrefix + key;
+		// invalid keys
+		if (
+			prefixedKey === this.cacheConfig.keyPrefix ||
+			prefixedKey === 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;
+		}
+
+		const cacheItemOptions = {
+			priority:
+				options && options.priority !== undefined
+					? options.priority
+					: this.cacheConfig.defaultPriority,
+			expires:
+				options && options.expires !== undefined
+					? options.expires
+					: this.cacheConfig.defaultTTL + 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;
+		}
+
+		const item: CacheItem = this.fillCacheItem(
+			prefixedKey,
+			value,
+			cacheItemOptions
+		);
+
+		// check wether this item is too big;
+		if (item.byteSize > this.cacheConfig.itemMaxSize) {
+			logger.warn(
+				`Item with key: ${key} you are trying to put into is too big!`
+			);
+			return;
+		}
+
+		// if key already in the cache, then delete it.
+		const presentKeyPrio: number = this.containsKey(key);
+		if (presentKeyPrio !== -1) {
+			this._removeItem(prefixedKey, presentKeyPrio - 1);
+		}
+
+		// pop out items in the cache when cache is full based on LRU
+		// first start from lowest priority cache list
+		let cacheListIdx = this.maxPriority - 1;
+		while (this._isCacheFull(item.byteSize) && cacheListIdx >= 0) {
+			if (!this.cacheList[cacheListIdx].isEmpty()) {
+				const popedItemKey = this.cacheList[cacheListIdx].getLastItem();
+				this._removeItem(popedItemKey, cacheListIdx);
+			} else {
+				cacheListIdx -= 1;
+			}
+		}
+
+		this._setItem(prefixedKey, item, Number(item.priority) - 1);
+	}
+
+	/**
+	 * 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
+	 *
+	 * @param key - the key of the item
+	 * @param options - the options of callback function
+	 */
+	public getItem(key: string, options?: CacheItemOptions): any {
+		let ret: string | null = null;
+		const prefixedKey: string = this.cacheConfig.keyPrefix + key;
+
+		if (
+			prefixedKey === this.cacheConfig.keyPrefix ||
+			prefixedKey === getCurrSizeKey(this.cacheConfig.keyPrefix)
+		) {
+			logger.warn(`Invalid key: should not be empty or 'CurSize'`);
+			return null;
+		}
+
+		// check whether it's in the cachelist
+		const presentKeyPrio: number = this.containsKey(key);
+		if (presentKeyPrio !== -1) {
+			if (this._isExpired(prefixedKey)) {
+				// if expired, remove that item and return null
+				this._removeItem(prefixedKey, presentKeyPrio - 1);
+			} else {
+				// if not expired, great, return the value and refresh it
+				ret = CacheObject.getItem(prefixedKey) ?? '';
+				const item: CacheItem = JSON.parse(ret);
+				this.cacheList[item.priority - 1].refresh(prefixedKey);
+				return item.data;
+			}
+		}
+
+		if (options && options.callback !== undefined) {
+			const val: object | string | number | boolean = options.callback();
+			if (val !== null) {
+				this.setItem(key, val, options);
+			}
+			return val;
+		}
+		return null;
+	}
+
+	/**
+	 * remove item from the cache
+	 *
+	 * @param key - the key of the item
+	 */
+	public removeItem(key: string): void {
+		const prefixedKey: string = this.cacheConfig.keyPrefix + key;
+
+		// check if the key is in the cache
+		const presentKeyPrio: number = this.containsKey(key);
+		if (presentKeyPrio !== -1) {
+			this._removeItem(prefixedKey, presentKeyPrio - 1);
+		}
+	}
+
+	/**
+	 * clear the entire cache
+	 */
+	public clear(): void {
+		for (let i = 0; i < this.maxPriority; i += 1) {
+			for (const key of this.cacheList[i].getKeys()) {
+				this._removeItem(key, i);
+			}
+		}
+	}
+
+	/**
+	 * Return all the keys in the cache.
+	 */
+	public getAllKeys(): string[] {
+		const keys: string[] = [];
+		for (let i = 0; i < this.maxPriority; i += 1) {
+			for (const key of this.cacheList[i].getKeys()) {
+				keys.push(key.substring(this.cacheConfig.keyPrefix.length));
+			}
+		}
+
+		return keys;
+	}
+
+	/**
+	 * return the current size of the cache
+	 *
+	 * @return the current size of the cache
+	 */
+	public getCacheCurSize(): number {
+		return this.curSizeInBytes;
+	}
+
+	/**
+	 * Return a new instance of cache with customized configuration.
+	 * @param config - the customized configuration
+	 */
+	public createInstance(config: CacheConfig): ICache {
+		return new InMemoryCacheClass(config);
+	}
+}
+
+export const InMemoryCache: ICache = new InMemoryCacheClass();

package/src/Cache/StorageCache.ts

@@ -0,0 +1,157 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { getCurrTime, getByteLength, defaultConfig } from './Utils';
+import { AmplifyV6 } from '../singleton';
+import { CacheConfig, CacheItem, CacheItemOptions } from './types';
+import { ConsoleLogger as Logger } from '../Logger';
+
+const logger = new Logger('StorageCache');
+
+/**
+ * Initialization of the cache
+ *
+ */
+export class StorageCache {
+	// Contains any fields that have been customized for this Cache instance (i.e. without default values)
+	private instanceConfig?: CacheConfig;
+
+	/**
+	 * Initialize the cache
+	 *
+	 * @param config - Custom configuration for this instance.
+	 */
+	constructor(config?: CacheConfig) {
+		if (config) {
+			// A configuration was specified for this specific instance
+			this.instanceConfig = config;
+		}
+
+		this.sanitizeConfig();
+	}
+
+	public getModuleName() {
+		return 'Cache';
+	}
+
+	private sanitizeConfig(): void {
+		const tempInstanceConfig = this.instanceConfig || ({} as CacheConfig);
+
+		if (this.cacheConfig.itemMaxSize > this.cacheConfig.capacityInBytes) {
+			logger.error(
+				'Invalid parameter: itemMaxSize. It should be smaller than capacityInBytes. Setting back to default.'
+			);
+			tempInstanceConfig.itemMaxSize = defaultConfig.itemMaxSize;
+		}
+
+		if (
+			this.cacheConfig.defaultPriority > 5 ||
+			this.cacheConfig.defaultPriority < 1
+		) {
+			logger.error(
+				'Invalid parameter: defaultPriority. It should be between 1 and 5. Setting back to default.'
+			);
+			tempInstanceConfig.defaultPriority = defaultConfig.defaultPriority;
+		}
+
+		if (
+			Number(this.cacheConfig.warningThreshold) > 1 ||
+			Number(this.cacheConfig.warningThreshold) < 0
+		) {
+			logger.error(
+				'Invalid parameter: warningThreshold. It should be between 0 and 1. Setting back to default.'
+			);
+			tempInstanceConfig.warningThreshold = defaultConfig.warningThreshold;
+		}
+
+		// Set 5MB limit
+		const cacheLimit: number = 5 * 1024 * 1024;
+		if (this.cacheConfig.capacityInBytes > cacheLimit) {
+			logger.error(
+				'Cache Capacity should be less than 5MB. Setting back to default. Setting back to default.'
+			);
+			tempInstanceConfig.capacityInBytes = defaultConfig.capacityInBytes;
+		}
+
+		// Apply sanitized values to the instance config
+		if (Object.keys(tempInstanceConfig).length > 0) {
+			this.instanceConfig = tempInstanceConfig;
+		}
+	}
+
+	/**
+	 * produce a JSON object with meta-data and data value
+	 * @param value - the value of the item
+	 * @param options - optional, the specified meta-data
+	 *
+	 * @return - the item which has the meta-data and the value
+	 */
+	protected fillCacheItem(
+		key: string,
+		value: object | number | string | boolean,
+		options: CacheItemOptions
+	): CacheItem {
+		const ret: CacheItem = {
+			key,
+			data: value,
+			timestamp: getCurrTime(),
+			visitedTime: getCurrTime(),
+			priority: options.priority ?? 0,
+			expires: options.expires ?? 0,
+			type: typeof value,
+			byteSize: 0,
+		};
+
+		ret.byteSize = getByteLength(JSON.stringify(ret));
+
+		// for accurate size
+		ret.byteSize = getByteLength(JSON.stringify(ret));
+		return ret;
+	}
+
+	/**
+	 * Set custom configuration for the cache instance.
+	 *
+	 * @param config - customized configuration (without keyPrefix, which can't be changed)
+	 *
+	 * @return - the current configuration
+	 */
+	public configure(config?: Omit<CacheConfig, 'keyPrefix'>): CacheConfig {
+		if (config) {
+			if ((config as CacheConfig).keyPrefix) {
+				logger.warn(
+					'keyPrefix can not be re-configured on an existing Cache instance.'
+				);
+			}
+
+			this.instanceConfig = this.instanceConfig
+				? Object.assign({}, this.instanceConfig, config)
+				: (config as CacheConfig);
+		}
+
+		this.sanitizeConfig();
+
+		return this.cacheConfig;
+	}
+
+	/**
+	 * Returns an appropriate configuration for the Cache instance. Will apply any custom configuration for this
+	 * instance on top of the global configuration. Default configuration will be applied in all cases.
+	 *
+	 * @internal
+	 */
+	protected get cacheConfig(): CacheConfig {
+		const globalCacheConfig = AmplifyV6.getConfig().Cache || {};
+
+		if (this.instanceConfig) {
+			return Object.assign(
+				{},
+				defaultConfig,
+				globalCacheConfig,
+				this.instanceConfig
+			);
+		} else {
+			return Object.assign({}, defaultConfig, globalCacheConfig);
+		}
+	}
+}

package/src/Cache/Utils/CacheList.ts

@@ -0,0 +1,198 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { asserts } from '../../Util/errors/AssertError';
+import { CACHE_LIST_EXCEPTION } from '../../constants';
+
+class DoubleLinkedNode {
+	key: string;
+	prevNode: DoubleLinkedNode | null;
+	nextNode: DoubleLinkedNode | null;
+
+	constructor(keyVal?: string) {
+		this.key = keyVal ? keyVal : '';
+		this.prevNode = null;
+		this.nextNode = null;
+	}
+}
+
+/**
+ * double linked list plus a hash table inside
+ * each key in the cache stored as a node in the list
+ * recently visited node will be rotated to the head
+ * so the Last Recently Visited node will be at the tail
+ *
+ * @member head - dummy head of the linked list
+ * @member tail - dummy tail of the linked list
+ * @member hashtable - the hashtable which maps cache key to list node
+ * @member length - length of the list
+ */
+export default class CacheList {
+	private head: DoubleLinkedNode;
+	private tail: DoubleLinkedNode;
+	private hashtable: Record<string, any>;
+	private length: number;
+
+	/**
+	 * initialization
+	 */
+	constructor() {
+		this.head = new DoubleLinkedNode();
+		this.tail = new DoubleLinkedNode();
+		this.hashtable = {};
+		this.length = 0;
+
+		this.head.nextNode = this.tail;
+		this.tail.prevNode = this.head;
+	}
+
+	/**
+	 * insert node to the head of the list
+	 *
+	 * @param node
+	 */
+	private insertNodeToHead(node: DoubleLinkedNode) {
+		const tmp: DoubleLinkedNode | null = this.head.nextNode;
+		this.head.nextNode = node;
+		node.nextNode = tmp;
+		node.prevNode = this.head;
+		asserts(tmp !== null, {
+			name: CACHE_LIST_EXCEPTION,
+			message: 'previous node is null',
+		});
+		tmp.prevNode = node;
+
+		this.length = this.length + 1;
+	}
+
+	/**
+	 * remove node
+	 *
+	 * @param node
+	 */
+	private removeNode(node: DoubleLinkedNode): void {
+		asserts(node.prevNode !== null, {
+			name: CACHE_LIST_EXCEPTION,
+			message: 'previous node is null',
+		});
+		asserts(node.nextNode !== null, {
+			name: CACHE_LIST_EXCEPTION,
+			message: 'nextNode node is null',
+		});
+		node.prevNode.nextNode = node.nextNode;
+		node.nextNode.prevNode = node.prevNode;
+
+		node.prevNode = null;
+		node.nextNode = null;
+
+		this.length = this.length - 1;
+	}
+
+	/**
+	 * @return true if list is empty
+	 */
+	public isEmpty(): boolean {
+		return this.length === 0;
+	}
+
+	/**
+	 * refresh node so it is rotated to the head
+	 *
+	 * @param key - key of the node
+	 */
+	public refresh(key: string): void {
+		const node: DoubleLinkedNode = this.hashtable[key];
+		this.removeNode(node);
+		this.insertNodeToHead(node);
+	}
+
+	/**
+	 * insert new node to the head and add it in the hashtable
+	 *
+	 * @param key - the key of the node
+	 */
+	public insertItem(key: string): void {
+		const node: DoubleLinkedNode = new DoubleLinkedNode(key);
+		this.hashtable[key] = node;
+		this.insertNodeToHead(node);
+	}
+
+	/**
+	 * @return the LAST Recently Visited key
+	 */
+	public getLastItem(): string {
+		asserts(this.tail.prevNode !== null, {
+			name: CACHE_LIST_EXCEPTION,
+			message: 'previous node is null',
+		});
+		return this.tail.prevNode.key;
+	}
+
+	/**
+	 * remove the cache key from the list and hashtable
+	 * @param key - the key of the node
+	 */
+	public removeItem(key: string): void {
+		const removedItem: DoubleLinkedNode = this.hashtable[key];
+		this.removeNode(removedItem);
+		delete this.hashtable[key];
+	}
+
+	/**
+	 * @return length of the list
+	 */
+	public getSize(): number {
+		return this.length;
+	}
+
+	/**
+	 * @return true if the key is in the hashtable
+	 * @param key
+	 */
+	public containsKey(key: string): boolean {
+		return key in this.hashtable;
+	}
+
+	/**
+	 * clean up the list and hashtable
+	 */
+	public clearList(): void {
+		for (const key of Object.keys(this.hashtable)) {
+			if (this.hashtable.hasOwnProperty(key)) {
+				delete this.hashtable[key];
+			}
+		}
+		this.head.nextNode = this.tail;
+		this.tail.prevNode = this.head;
+		this.length = 0;
+	}
+
+	/**
+	 * @return all keys in the hashtable
+	 */
+	public getKeys(): string[] {
+		return Object.keys(this.hashtable);
+	}
+
+	/**
+	 * mainly for test
+	 *
+	 * @param key
+	 * @return true if key is the head node
+	 */
+	public isHeadNode(key: string): boolean {
+		const node = this.hashtable[key];
+		return node.prevNode === this.head;
+	}
+
+	/**
+	 * mainly for test
+	 *
+	 * @param key
+	 * @return true if key is the tail node
+	 */
+	public isTailNode(key: string): boolean {
+		const node = this.hashtable[key];
+		return node.nextNode === this.tail;
+	}
+}