@aws-amplify/core 6.0.1-preview-testing.be90020.0 → 6.0.1-ssr-api.df60e41.0

package/lib-esm/BackgroundProcessManager/BackgroundProcessManager.js

@@ -0,0 +1,283 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import { BackgroundManagerNotOpenError } from './BackgroundManagerNotOpenError';
+import { BackgroundProcessManagerState } from './types';
+/**
+ * @private For internal Amplify use.
+ *
+ * Creates a new scope for promises, observables, and other types of work or
+ * processes that may be running in the background. This manager provides
+ * an singular entrypoint to request termination and await completion.
+ *
+ * As work completes on its own prior to close, the manager removes them
+ * from the registry to avoid holding references to completed jobs.
+ */
+export class BackgroundProcessManager {
+    /**
+     * Creates a new manager for promises, observables, and other types
+     * of work that may be running in the background. This manager provides
+     * a centralized mechanism to request termination and await completion.
+     */
+    constructor() {
+        /**
+         * A string indicating whether the manager is accepting new work ("Open"),
+         * waiting for work to complete ("Closing"), or fully done with all
+         * submitted work and *not* accepting new jobs ("Closed").
+         */
+        this._state = BackgroundProcessManagerState.Open;
+        /**
+         * The list of outstanding jobs we'll need to wait for upon `close()`
+         */
+        this.jobs = new Set();
+    }
+    add(jobOrDescription, optionalDescription) {
+        let job;
+        let description;
+        if (typeof jobOrDescription === 'string') {
+            job = undefined;
+            description = jobOrDescription;
+        }
+        else {
+            job = jobOrDescription;
+            description = optionalDescription;
+        }
+        const error = this.closedFailure(description);
+        if (error)
+            return error;
+        if (job === undefined) {
+            return this.addHook(description);
+        }
+        else if (typeof job === 'function') {
+            return this.addFunction(job, description);
+        }
+        else if (job instanceof BackgroundProcessManager) {
+            return this.addManager(job, description);
+        }
+        else {
+            throw new Error('If `job` is provided, it must be an Observable, Function, or BackgroundProcessManager.');
+        }
+    }
+    /**
+     * Adds a **cleaner** function that doesn't immediately get executed.
+     * Instead, the caller gets a **terminate** function back. The *cleaner* is
+     * invoked only once the mananger *closes* or the returned **terminate**
+     * function is called.
+     *
+     * @param clean The cleanup function.
+     * @param description Optional description to help identify pending jobs.
+     * @returns A terminate function.
+     */
+    addCleaner(clean, description) {
+        const { resolve, onTerminate } = this.addHook(description);
+        const proxy = async () => {
+            await clean();
+            resolve();
+        };
+        onTerminate.then(proxy);
+        return proxy;
+    }
+    addFunction(job, description) {
+        // the function we call when we want to try to terminate this job.
+        let terminate;
+        // the promise the job can opt into listening to for termination.
+        const onTerminate = new Promise(resolve => {
+            terminate = resolve;
+        });
+        // finally! start the job.
+        const jobResult = job(onTerminate);
+        // depending on what the job gives back, register the result
+        // so we can monitor for completion.
+        if (typeof jobResult?.then === 'function') {
+            this.registerPromise(jobResult, terminate, description);
+        }
+        // At the end of the day, or you know, method call, it doesn't matter
+        // what the return value is at all; we just pass it through to the
+        // caller.
+        return jobResult;
+    }
+    addManager(manager, description) {
+        this.addCleaner(async () => await manager.close(), description);
+    }
+    /**
+     * Creates and registers a fabricated job for processes that need to operate
+     * with callbacks/hooks. The returned `resolve` and `reject`
+     * functions can be used to signal the job is done successfully or not.
+     * The returned `onTerminate` is a promise that will resolve when the
+     * manager is requesting the termination of the job.
+     *
+     * @param description Optional description to help identify pending jobs.
+     * @returns `{ resolve, reject, onTerminate }`
+     */
+    addHook(description) {
+        // the resolve/reject functions we'll provide to the caller to signal
+        // the state of the job.
+        let resolve;
+        let reject;
+        // the underlying promise we'll use to manage it, pretty much like
+        // any other promise.
+        const promise = new Promise((res, rej) => {
+            resolve = res;
+            reject = rej;
+        });
+        // the function we call when we want to try to terminate this job.
+        let terminate;
+        // the promise the job can opt into listening to for termination.
+        const onTerminate = new Promise(resolveTerminate => {
+            terminate = resolveTerminate;
+        });
+        this.registerPromise(promise, terminate, description);
+        return {
+            resolve,
+            reject,
+            onTerminate,
+        };
+    }
+    /**
+     * Adds a Promise based job to the list of jobs for monitoring and listens
+     * for either a success or failure, upon which the job is considered "done"
+     * and removed from the registry.
+     *
+     * @param promise A promise that is on its way to being returned to a
+     * caller, which needs to be tracked as a background job.
+     * @param terminate The termination function to register, which can be
+     * invoked to request the job stop.
+     * @param description Optional description to help identify pending jobs.
+     */
+    registerPromise(promise, terminate, description) {
+        const jobEntry = { promise, terminate, description };
+        this.jobs.add(jobEntry);
+        // in all of my testing, it is safe to multi-subscribe to a promise.
+        // so, rather than create another layer of promising, we're just going
+        // to hook into the promise we already have, and when it's done
+        // (successfully or not), we no longer need to wait for it upon close.
+        //
+        // sorry this is a bit hand-wavy:
+        //
+        // i believe we use `.then` and `.catch` instead of `.finally` because
+        // `.finally` is invoked in a different order in the sequence, and this
+        // breaks assumptions throughout and causes failures.
+        promise
+            .then(() => {
+            this.jobs.delete(jobEntry);
+        })
+            .catch(() => {
+            this.jobs.delete(jobEntry);
+        });
+    }
+    /**
+     * The number of jobs being waited on.
+     *
+     * We don't use this for anything. It's just informational for the caller,
+     * and can be used in logging and testing.
+     *
+     * @returns the number of jobs.
+     */
+    get length() {
+        return this.jobs.size;
+    }
+    /**
+     * The execution state of the manager. One of:
+     *
+     * 1. "Open" -> Accepting new jobs
+     * 1. "Closing" -> Not accepting new work. Waiting for jobs to complete.
+     * 1. "Closed" -> Not accepting new work. All submitted jobs are complete.
+     */
+    get state() {
+        return this._state;
+    }
+    /**
+     * The registered `description` of all still-pending jobs.
+     *
+     * @returns descriptions as an array.
+     */
+    get pending() {
+        return Array.from(this.jobs).map(job => job.description);
+    }
+    /**
+     * Whether the manager is accepting new jobs.
+     */
+    get isOpen() {
+        return this._state === BackgroundProcessManagerState.Open;
+    }
+    /**
+     * Whether the manager is rejecting new work, but still waiting for
+     * submitted work to complete.
+     */
+    get isClosing() {
+        return this._state === BackgroundProcessManagerState.Closing;
+    }
+    /**
+     * Whether the manager is rejecting work and done waiting for submitted
+     * work to complete.
+     */
+    get isClosed() {
+        return this._state === BackgroundProcessManagerState.Closed;
+    }
+    closedFailure(description) {
+        if (!this.isOpen) {
+            return Promise.reject(new BackgroundManagerNotOpenError([
+                `The manager is ${this.state}.`,
+                `You tried to add "${description}".`,
+                `Pending jobs: [\n${this.pending
+                    .map(t => '    ' + t)
+                    .join(',\n')}\n]`,
+            ].join('\n')));
+        }
+    }
+    /**
+     * Signals jobs to stop (for those that accept interruptions) and waits
+     * for confirmation that jobs have stopped.
+     *
+     * This immediately puts the manager into a closing state and just begins
+     * to reject new work. After all work in the manager is complete, the
+     * manager goes into a `Completed` state and `close()` returns.
+     *
+     * This call is idempotent.
+     *
+     * If the manager is already closing or closed, `finalCleaup` is not executed.
+     *
+     * @param onClosed
+     * @returns The settled results of each still-running job's promise. If the
+     * manager is already closed, this will contain the results as of when the
+     * manager's `close()` was called in an `Open` state.
+     */
+    async close() {
+        if (this.isOpen) {
+            this._state = BackgroundProcessManagerState.Closing;
+            for (const job of Array.from(this.jobs)) {
+                try {
+                    job.terminate();
+                }
+                catch (error) {
+                    // Due to potential races with a job's natural completion, it's
+                    // reasonable to expect the termination call to fail. Hence,
+                    // not logging as an error.
+                    console.warn(`Failed to send termination signal to job. Error: ${error.message}`, job);
+                }
+            }
+            // Use `allSettled()` because we want to wait for all to finish. We do
+            // not want to stop waiting if there is a failure.
+            this._closingPromise = Promise.allSettled(Array.from(this.jobs).map(j => j.promise));
+            await this._closingPromise;
+            this._state = BackgroundProcessManagerState.Closed;
+        }
+        return this._closingPromise;
+    }
+    /**
+     * Signals the manager to start accepting work (again) and returns once
+     * the manager is ready to do so.
+     *
+     * If the state is already `Open`, this call is a no-op.
+     *
+     * If the state is `Closed`, this call simply updates state and returns.
+     *
+     * If the state is `Closing`, this call waits for completion before it
+     * updates the state and returns.
+     */
+    async open() {
+        if (this.isClosing) {
+            await this.close();
+        }
+        this._state = BackgroundProcessManagerState.Open;
+    }
+}

package/lib-esm/BackgroundProcessManager/index.d.ts

@@ -0,0 +1 @@
+export { BackgroundProcessManager } from './BackgroundProcessManager';

package/lib-esm/BackgroundProcessManager/index.js

@@ -0,0 +1,3 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+export { BackgroundProcessManager } from './BackgroundProcessManager';

package/lib-esm/BackgroundProcessManager/types.d.ts

@@ -0,0 +1,41 @@
+/**
+ * All possible states a `BackgroundProcessManager` instance can be in.
+ */
+export declare enum BackgroundProcessManagerState {
+    /**
+     * Accepting new jobs.
+     */
+    Open = "Open",
+    /**
+     * Not accepting new jobs. Waiting for submitted jobs to complete.
+     */
+    Closing = "Closing",
+    /**
+     * Not accepting new jobs. All submitted jobs are complete.
+     */
+    Closed = "Closed"
+}
+/**
+ * Completely internal to `BackgroundProcessManager`, and describes the structure of
+ * an entry in the jobs registry.
+ */
+export type JobEntry = {
+    /**
+     * The underlying promise provided by the job function to wait for.
+     */
+    promise: Promise<any>;
+    /**
+     * Request the termination of the job.
+     */
+    terminate: () => void;
+    /**
+     * An object provided by the caller that can be used to identify the description
+     * of the job, which can otherwise be unclear from the `promise` and
+     * `terminate` function. The `description` can be a string. (May be extended
+     * later to also support object refs.)
+     *
+     * Useful for troubleshooting why a manager is waiting for long periods of time
+     * on `close()`.
+     */
+    description?: string;
+};

package/lib-esm/BackgroundProcessManager/types.js

@@ -0,0 +1,20 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * All possible states a `BackgroundProcessManager` instance can be in.
+ */
+export var BackgroundProcessManagerState;
+(function (BackgroundProcessManagerState) {
+    /**
+     * Accepting new jobs.
+     */
+    BackgroundProcessManagerState["Open"] = "Open";
+    /**
+     * Not accepting new jobs. Waiting for submitted jobs to complete.
+     */
+    BackgroundProcessManagerState["Closing"] = "Closing";
+    /**
+     * Not accepting new jobs. All submitted jobs are complete.
+     */
+    BackgroundProcessManagerState["Closed"] = "Closed";
+})(BackgroundProcessManagerState || (BackgroundProcessManagerState = {}));

package/lib-esm/Cache/StorageCache.d.ts

@@ -1,39 +1,22 @@
-import { CacheConfig, CacheItem, CacheItemOptions } from './types';
+import { StorageCacheCommon } from './StorageCacheCommon';
+import { Cache, CacheConfig } from './types';
 /**
- * Initialization of the cache
- *
+ * Customized storage based on the SessionStorage or LocalStorage with LRU implemented
  */
-export declare class StorageCache {
-    private instanceConfig?;
+export declare class StorageCache extends StorageCacheCommon implements Cache {
+    storage: Storage;
     /**
-     * Initialize the cache
-     *
-     * @param config - Custom configuration for this instance.
+     * initialize the cache
+     * @param config - the configuration of the cache
      */
     constructor(config?: CacheConfig);
-    getModuleName(): string;
-    private sanitizeConfig;
+    protected getAllCacheKeys(options?: {
+        omitSizeKey?: boolean;
+    }): Promise<string[]>;
     /**
-     * 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
+     * Return a new instance of cache with customized configuration.
+     * @param {Object} config - the customized configuration
+     * @return {Object} - the new instance of Cache
      */
-    protected fillCacheItem(key: string, value: object | number | string | boolean, options: CacheItemOptions): CacheItem;
-    /**
-     * Set custom configuration for the cache instance.
-     *
-     * @param config - customized configuration (without keyPrefix, which can't be changed)
-     *
-     * @return - the current configuration
-     */
-    configure(config?: Omit<CacheConfig, 'keyPrefix'>): 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;
+    createInstance(config: CacheConfig): Cache;
 }

package/lib-esm/Cache/StorageCache.js

@@ -1,118 +1,52 @@
 // Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
 // SPDX-License-Identifier: Apache-2.0
-import { getCurrTime, getByteLength, defaultConfig } from './Utils';
 import { ConsoleLogger as Logger } from '../Logger';
-var logger = new Logger('StorageCache');
+import { KeyValueStorage } from '../storage/KeyValueStorage';
+import { getLocalStorageWithFallback } from '../storage/utils';
+import { defaultConfig } from './constants';
+import { StorageCacheCommon } from './StorageCacheCommon';
+import { getCurrentSizeKey, getCurrentTime } from './utils';
+const logger = new Logger('Cache');
 /**
- * Initialization of the cache
- *
+ * Customized storage based on the SessionStorage or LocalStorage with LRU implemented
  */
-var StorageCache = /** @class */ (function () {
+export class StorageCache extends StorageCacheCommon {
     /**
-     * Initialize the cache
-     *
-     * @param config - Custom configuration for this instance.
+     * initialize the cache
+     * @param config - the configuration of the cache
      */
-    function StorageCache(config) {
-        if (config) {
-            // A configuration was specified for this specific instance
-            this.instanceConfig = config;
-        }
-        this.sanitizeConfig();
+    constructor(config) {
+        const storage = getLocalStorageWithFallback();
+        super({ config, keyValueStorage: new KeyValueStorage(storage) });
+        this.storage = storage;
+        this.getItem = this.getItem.bind(this);
+        this.setItem = this.setItem.bind(this);
+        this.removeItem = this.removeItem.bind(this);
     }
-    StorageCache.prototype.getModuleName = function () {
-        return 'Cache';
-    };
-    StorageCache.prototype.sanitizeConfig = function () {
-        var tempInstanceConfig = this.instanceConfig || {};
-        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
-        var cacheLimit = 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;
+    async getAllCacheKeys(options) {
+        const { omitSizeKey } = options ?? {};
+        const keys = [];
+        for (let i = 0; i < this.storage.length; i++) {
+            const key = this.storage.key(i);
+            if (omitSizeKey && key === getCurrentSizeKey(this.config.keyPrefix)) {
+                continue;
+            }
+            if (key?.startsWith(this.config.keyPrefix)) {
+                keys.push(key.substring(this.config.keyPrefix.length));
+            }
         }
-    };
-    /**
-     * 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
-     */
-    StorageCache.prototype.fillCacheItem = function (key, value, options) {
-        var _a, _b;
-        var ret = {
-            key: key,
-            data: value,
-            timestamp: getCurrTime(),
-            visitedTime: getCurrTime(),
-            priority: (_a = options.priority) !== null && _a !== void 0 ? _a : 0,
-            expires: (_b = options.expires) !== null && _b !== void 0 ? _b : 0,
-            type: typeof value,
-            byteSize: 0,
-        };
-        ret.byteSize = getByteLength(JSON.stringify(ret));
-        // for accurate size
-        ret.byteSize = getByteLength(JSON.stringify(ret));
-        return ret;
-    };
+        return keys;
+    }
     /**
-     * Set custom configuration for the cache instance.
-     *
-     * @param config - customized configuration (without keyPrefix, which can't be changed)
-     *
-     * @return - the current configuration
+     * Return a new instance of cache with customized configuration.
+     * @param {Object} config - the customized configuration
+     * @return {Object} - the new instance of Cache
      */
-    StorageCache.prototype.configure = function (config) {
-        if (config) {
-            if (config.keyPrefix) {
-                logger.warn('keyPrefix can not be re-configured on an existing Cache instance.');
-            }
-            this.instanceConfig = this.instanceConfig
-                ? Object.assign({}, this.instanceConfig, config)
-                : config;
+    createInstance(config) {
+        if (!config.keyPrefix || config.keyPrefix === defaultConfig.keyPrefix) {
+            logger.error('invalid keyPrefix, setting keyPrefix with timeStamp');
+            config.keyPrefix = getCurrentTime.toString();
         }
-        this.sanitizeConfig();
-        return this.cacheConfig;
-    };
-    Object.defineProperty(StorageCache.prototype, "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
-         */
-        get: function () {
-            // const globalCacheConfig = Amplify.getConfig().Cache || {};
-            var globalCacheConfig = {};
-            if (this.instanceConfig) {
-                return Object.assign({}, defaultConfig, globalCacheConfig, this.instanceConfig);
-            }
-            else {
-                return Object.assign({}, defaultConfig, globalCacheConfig);
-            }
-        },
-        enumerable: false,
-        configurable: true
-    });
-    return StorageCache;
-}());
-export { StorageCache };
+        return new StorageCache(config);
+    }
+}

package/lib-esm/Cache/StorageCache.native.d.ts

@@ -0,0 +1,19 @@
+import { StorageCacheCommon } from './StorageCacheCommon';
+import { Cache, CacheConfig } from './types';
+export declare class StorageCache extends StorageCacheCommon implements Cache {
+    /**
+     * initialize the cache
+     * @param config - the configuration of the cache
+     */
+    constructor(config?: CacheConfig);
+    protected getAllCacheKeys(options?: {
+        omitSizeKey?: boolean;
+    }): Promise<string[]>;
+    protected getAllStorageKeys(): Promise<readonly string[]>;
+    /**
+     * Return a new instance of cache with customized configuration.
+     * @param {Object} config - the customized configuration
+     * @return {Object} - the new instance of Cache
+     */
+    createInstance(config: CacheConfig): Cache;
+}

package/lib-esm/Cache/StorageCache.native.js

@@ -0,0 +1,58 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import { loadAsyncStorage } from '@aws-amplify/react-native';
+import { ConsoleLogger as Logger } from '../Logger';
+import { defaultConfig } from './constants';
+import { StorageCacheCommon } from './StorageCacheCommon';
+import { getCurrentSizeKey, getCurrentTime } from './utils';
+const logger = new Logger('StorageCache');
+const AsyncStorage = loadAsyncStorage();
+/*
+ * Customized cache which based on the AsyncStorage with LRU implemented
+ */
+export class StorageCache extends StorageCacheCommon {
+    /**
+     * initialize the cache
+     * @param config - the configuration of the cache
+     */
+    constructor(config) {
+        super({ config, keyValueStorage: AsyncStorage });
+        this.getItem = this.getItem.bind(this);
+        this.setItem = this.setItem.bind(this);
+        this.removeItem = this.removeItem.bind(this);
+    }
+    async getAllCacheKeys(options) {
+        const { omitSizeKey } = options ?? {};
+        const keys = [];
+        for (const key of await AsyncStorage.getAllKeys()) {
+            if (omitSizeKey && key === getCurrentSizeKey(this.config.keyPrefix)) {
+                continue;
+            }
+            if (key?.startsWith(this.config.keyPrefix)) {
+                keys.push(key.substring(this.config.keyPrefix.length));
+            }
+        }
+        return keys;
+    }
+    async getAllStorageKeys() {
+        try {
+            return AsyncStorage.getAllKeys();
+        }
+        catch (e) {
+            logger.warn(`getAllKeys failed! ${e}`);
+            return [];
+        }
+    }
+    /**
+     * Return a new instance of cache with customized configuration.
+     * @param {Object} config - the customized configuration
+     * @return {Object} - the new instance of Cache
+     */
+    createInstance(config) {
+        if (!config.keyPrefix || config.keyPrefix === defaultConfig.keyPrefix) {
+            logger.error('invalid keyPrefix, setting keyPrefix with timeStamp');
+            config.keyPrefix = getCurrentTime.toString();
+        }
+        return new StorageCache(config);
+    }
+}