@aws-amplify/core 5.8.6-unstable.7762f1a.0 → 6.0.0

package/README.md

@@ -0,0 +1,3 @@
+> INTERNAL USE ONLY
+
+This package contains the AWS Amplify core utilities and is intended for internal use only. To integrate Amplify into your app, please use [aws-amplify](https://www.npmjs.com/package/aws-amplify).

package/internals/adapter-core/package.json

@@ -0,0 +1,8 @@
+{
+	"name": "@aws-amplify/core/internals/adapter-core",
+	"types": "../../lib-esm/adapterCore/index.d.ts",
+	"main": "../../lib/adapterCore/index.js",
+	"module": "../../lib-esm/adapterCore/index.js",
+	"react-native": "../../lib-esm/adapterCore/index.js",
+	"sideEffects": false
+}

package/internals/aws-clients/pinpoint/package.json

@@ -1,8 +1,8 @@
 {
 	"name": "@aws-amplify/core/internals/aws-clients/pinpoint",
-	"types": "../../../lib-esm/AwsClients/Pinpoint/index.d.ts",
-	"main": "../../../lib/AwsClients/Pinpoint/index.js",
-	"module": "../../../lib-esm/AwsClients/Pinpoint/index.js",
-	"react-native": "../../../lib-esm/AwsClients/Pinpoint/index.js",
+	"types": "../../../lib-esm/awsClients/pinpoint/index.d.ts",
+	"main": "../../../lib/awsClients/pinpoint/index.js",
+	"module": "../../../lib-esm/awsClients/pinpoint/index.js",
+	"react-native": "../../../lib-esm/awsClients/pinpoint/index.js",
 	"sideEffects": false
 }

package/internals/providers/pinpoint/package.json

@@ -0,0 +1,8 @@
+{
+	"name": "@aws-amplify/core/internals/providers/pinpoint",
+	"types": "../../../lib-esm/providers/pinpoint/index.d.ts",
+	"main": "../../../lib/providers/pinpoint/index.js",
+	"module": "../../../lib-esm/providers/pinpoint/index.js",
+	"react-native": "../../../lib-esm/providers/pinpoint/index.js",
+	"sideEffects": false
+}

package/internals/utils/package.json

@@ -0,0 +1,7 @@
+{
+	"name": "@aws-amplify/core/internals/utils",
+	"types": "../../lib-esm/libraryUtils.d.ts",
+	"main": "../../lib/libraryUtils.js",
+	"module": "../../lib-esm/libraryUtils.js",
+	"react-native": "../../lib-esm/libraryUtils.js"
+}

package/lib/BackgroundProcessManager/BackgroundManagerNotOpenError.d.ts

@@ -0,0 +1,3 @@
+export declare class BackgroundManagerNotOpenError extends Error {
+    constructor(message: string);
+}

package/lib/BackgroundProcessManager/BackgroundManagerNotOpenError.js

@@ -0,0 +1,11 @@
+"use strict";
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BackgroundManagerNotOpenError = void 0;
+class BackgroundManagerNotOpenError extends Error {
+    constructor(message) {
+        super(`BackgroundManagerNotOpenError: ${message}`);
+    }
+}
+exports.BackgroundManagerNotOpenError = BackgroundManagerNotOpenError;

package/lib/BackgroundProcessManager/BackgroundProcessManager.d.ts

@@ -0,0 +1,182 @@
+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 declare class BackgroundProcessManager {
+    /**
+     * 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").
+     */
+    private _state;
+    private _closingPromise;
+    /**
+     * The list of outstanding jobs we'll need to wait for upon `close()`
+     */
+    private jobs;
+    /**
+     * 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();
+    /**
+     * Executes an async `job` function, passing the return value through to
+     * the caller, registering it as a running job in the manager. When the
+     * manager *closes*, it will `await` the job.
+     *
+     * @param job The function to execute.
+     * @param description Optional description to help identify pending jobs.
+     * @returns The return value from the given function.
+     */
+    add<T>(job: () => Promise<T>, description?: string): Promise<T>;
+    /**
+     * Executes an async `job` function, passing the return value through to
+     * the caller, registering it as a running job in the manager. When the
+     * manager *closes*, it will request termination by resolving the
+     * provided `onTerminate` promise. It will then `await` the job, so it is
+     * important that the job still `resolve()` or `reject()` when responding
+     * to a termination request.
+     *
+     * @param job The function to execute.
+     * @param description Optional description to help identify pending jobs.
+     * @returns The return value from the given function.
+     */
+    add<T>(job: (onTerminate: Promise<void>) => Promise<T>, description?: string): Promise<T>;
+    /**
+     * Create a no-op job, registers it with the manager, and returns hooks
+     * to the caller to signal the job's completion and respond to termination
+     * requests.
+     *
+     * When the manager closes, the no-op job will be `await`-ed, so its
+     * important to always `resolve()` or `reject()` when done responding to an
+     * `onTerminate` signal.
+     * @param description Optional description to help identify pending jobs.
+     * @returns Job promise hooks + onTerminate signaling promise
+     */
+    add(description?: string): {
+        resolve: (value?: unknown) => void;
+        reject: (reason?: any) => void;
+        onTerminate: Promise<void>;
+    };
+    /**
+     * Adds another job manager to await on at the time of closing. the inner
+     * manager's termination is signaled when this manager's `close()` is
+     * called for.
+     *
+     * @param job The inner job manager to await.
+     * @param description Optional description to help identify pending jobs.
+     */
+    add<T>(job: BackgroundProcessManager, description?: string): Promise<T>;
+    /**
+     * 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<T>(clean: () => Promise<T>, description?: string): () => Promise<void>;
+    private addFunction;
+    private addManager;
+    /**
+     * 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 }`
+     */
+    private addHook;
+    /**
+     * 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.
+     */
+    private registerPromise;
+    /**
+     * 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(): number;
+    /**
+     * 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(): BackgroundProcessManagerState;
+    /**
+     * The registered `description` of all still-pending jobs.
+     *
+     * @returns descriptions as an array.
+     */
+    get pending(): (string | undefined)[];
+    /**
+     * Whether the manager is accepting new jobs.
+     */
+    get isOpen(): boolean;
+    /**
+     * Whether the manager is rejecting new work, but still waiting for
+     * submitted work to complete.
+     */
+    get isClosing(): boolean;
+    /**
+     * Whether the manager is rejecting work and done waiting for submitted
+     * work to complete.
+     */
+    get isClosed(): boolean;
+    private closedFailure;
+    /**
+     * 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.
+     */
+    close(): Promise<any>;
+    /**
+     * 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.
+     */
+    open(): Promise<void>;
+}

package/lib/BackgroundProcessManager/BackgroundProcessManager.js

@@ -0,0 +1,287 @@
+"use strict";
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BackgroundProcessManager = void 0;
+const BackgroundManagerNotOpenError_1 = require("./BackgroundManagerNotOpenError");
+const types_1 = require("./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.
+ */
+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 = types_1.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 === types_1.BackgroundProcessManagerState.Open;
+    }
+    /**
+     * Whether the manager is rejecting new work, but still waiting for
+     * submitted work to complete.
+     */
+    get isClosing() {
+        return this._state === types_1.BackgroundProcessManagerState.Closing;
+    }
+    /**
+     * Whether the manager is rejecting work and done waiting for submitted
+     * work to complete.
+     */
+    get isClosed() {
+        return this._state === types_1.BackgroundProcessManagerState.Closed;
+    }
+    closedFailure(description) {
+        if (!this.isOpen) {
+            return Promise.reject(new BackgroundManagerNotOpenError_1.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 = types_1.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 = types_1.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 = types_1.BackgroundProcessManagerState.Open;
+    }
+}
+exports.BackgroundProcessManager = BackgroundProcessManager;

package/lib/BackgroundProcessManager/index.d.ts

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

package/lib/BackgroundProcessManager/index.js

@@ -0,0 +1,7 @@
+"use strict";
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BackgroundProcessManager = void 0;
+var BackgroundProcessManager_1 = require("./BackgroundProcessManager");
+Object.defineProperty(exports, "BackgroundProcessManager", { enumerable: true, get: function () { return BackgroundProcessManager_1.BackgroundProcessManager; } });

package/lib/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/BackgroundProcessManager/types.js

@@ -0,0 +1,23 @@
+"use strict";
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BackgroundProcessManagerState = void 0;
+/**
+ * All possible states a `BackgroundProcessManager` instance can be in.
+ */
+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 = exports.BackgroundProcessManagerState || (exports.BackgroundProcessManagerState = {}));

package/lib/Cache/StorageCache.d.ts

@@ -0,0 +1,22 @@
+import { StorageCacheCommon } from './StorageCacheCommon';
+import { Cache, CacheConfig } from './types';
+/**
+ * Customized storage based on the SessionStorage or LocalStorage with LRU implemented
+ */
+export declare class StorageCache extends StorageCacheCommon implements Cache {
+    storage: Storage;
+    /**
+     * initialize the cache
+     * @param config - the configuration of the cache
+     */
+    constructor(config?: CacheConfig);
+    protected getAllCacheKeys(options?: {
+        omitSizeKey?: boolean;
+    }): Promise<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;
+}