gingersnap 0.22.0

package/future/future.mjs

@@ -0,0 +1,548 @@
+import { __awaiter } from '../_virtual/_tslib.mjs';
+import { FutureCancelled } from '../errors/FutureCancelled.mjs';
+import { FutureError } from '../errors/FutureError.mjs';
+import { InvalidValue } from '../errors/InvalidValue.mjs';
+import { TimeoutError } from '../errors/TimeoutError.mjs';
+import * as R from 'ramda';
+import { SimpleQueue } from '../data-structures/object/SimpleQueue.mjs';
+import { v4 } from 'uuid';
+import { FutureResult } from './result.mjs';
+import { Stream } from '../stream.mjs';
+
+const calculatePeriodValue = (period) => {
+    var _a, _b, _c, _d;
+    return ((_a = period.hours) !== null && _a !== void 0 ? _a : 0) * 60 * 60 * 1000 +
+        ((_b = period.minutes) !== null && _b !== void 0 ? _b : 0) * 60 * 1000 +
+        ((_c = period.seconds) !== null && _c !== void 0 ? _c : 0) * 1000 +
+        ((_d = period.milliseconds) !== null && _d !== void 0 ? _d : 0);
+};
+/**
+ * Represents an eventual result of some asynchronous operation. Futures are quite similar to Promise, and can be
+ * awaited as they are **Thenable** objects
+ */
+class Future {
+    constructor(executor, signal) {
+        this.guid = v4();
+        this.executor = executor;
+        this.defaultSignal = signal !== null && signal !== void 0 ? signal : new AbortController().signal;
+        this.signals = new Set([this.defaultSignal]);
+        this.fulfilled = false;
+        this.isRunning = false;
+        this.processors = new SimpleQueue();
+        this.finallyHandlers = new SimpleQueue();
+    }
+    /**
+     * Creates a future that wraps the given future, and prevents it from being cancellable on the call to "cancel" method
+     * @param future
+     */
+    static shield(future) {
+        return Future.of((resolve, reject) => {
+            future
+                .thenApply(({ value }) => resolve(value))
+                .catch(reject)
+                .schedule();
+        });
+    }
+    /**
+     * Creates a future from the value provided
+     * @param value an Executor function (callback for the new Future constructor)
+     * @param signal Abort Signal to establish the future with. If not provided, the future will only have the default
+     * signals
+     */
+    static of(value, signal) {
+        return new Future(value, signal);
+    }
+    /**
+     * Wraps a promise as a future
+     * @param value
+     */
+    static wrap(value) {
+        return new Future((resolve, reject) => {
+            value.then(resolve).catch(reject);
+        });
+    }
+    /**
+     * Waits for the given future to complete. If not completed within the given timeframe, the given future is cancelled
+     * @param value
+     * @param timeout wait period object or the number of milliseconds to wait
+     */
+    static waitFor(value, timeout) {
+        const timeableFuture = Future.sleep(timeout)
+            .registerSignal(value.defaultSignal)
+            .catch(() => { });
+        return Future.of((resolve, reject) => Promise.race([timeableFuture, value.run()])
+            .then((v) => {
+            if (value.done) {
+                timeableFuture.cancel();
+                resolve(v);
+                return;
+            }
+            value.cancel();
+            reject(new TimeoutError());
+        })
+            .catch((error) => {
+            if (!timeableFuture.failed) {
+                timeableFuture.cancel();
+            }
+            reject(error);
+        }), value.defaultSignal);
+    }
+    /**
+     * Sleeps for the given period. If period is a number, then it's the sleep duration in seconds
+     * @param period
+     * @param signal
+     */
+    static sleep(period, signal) {
+        return new Future((resolve, reject, futureSignal) => {
+            const totalTime = typeof period === "number" ? period * 1000 : calculatePeriodValue(period);
+            const timer = setTimeout(resolve, totalTime);
+            futureSignal.addEventListener("abort", () => {
+                clearTimeout(timer);
+                reject(new FutureCancelled());
+            }, { once: true });
+        }, signal);
+    }
+    /**
+     * Returns a future that completes with the given value.
+     * Important Note:
+     * Passing a Future or Stream to this function will execute it once and yield the result.
+     * @param value
+     */
+    static completed(value) {
+        return new Future((resolve) => resolve(value));
+    }
+    /**
+     * Returns a future that fails with the given value
+     * @param value
+     */
+    static exceptionally(value) {
+        return new Future((_, reject) => reject(value));
+    }
+    /**
+     * Returns the first completed or failed. If this is cancelled, then all futures provided will also be cancelled
+     * @param futures list of futures
+     * @param signal optinal abort signal
+     */
+    static firstCompleted(futures, signal) {
+        return Future.of((resolve, reject, signal) => {
+            futures.forEach((future) => {
+                future.registerSignal(signal);
+            });
+            Promise.race(futures)
+                .then(resolve)
+                .catch(reject)
+                .finally(() => {
+                futures.forEach((future) => {
+                    future.unregisterSignal(signal);
+                });
+            });
+        }, signal);
+    }
+    /**
+     * Awaits all futures completion, and collects the results in an array. If this future is cancelled, then all provided
+     * futures will also be cancelled.
+     * @param futures list of futures
+     * @param signal optional abort signal
+     */
+    static collect(futures, signal) {
+        return Future.of((resolve, reject, signal) => {
+            futures.forEach((future) => {
+                future.registerSignal(signal);
+            });
+            Promise.all(futures.map((f) => f.run()))
+                .then(resolve)
+                .catch(reject)
+                .finally(() => {
+                futures.forEach((future) => {
+                    future.unregisterSignal(signal);
+                });
+            });
+        }, signal);
+    }
+    /**
+     * Awaits futures finishing all possible executions, and returns the same list of futures. Whether each future
+     * completed or failed, the future is returned in the array
+     * @param futures
+     */
+    static collectSettled(futures) {
+        return Future.of((resolve, reject, signal) => {
+            futures.forEach((future) => {
+                future.registerSignal(signal);
+            });
+            Promise.allSettled(futures.map((f) => f.run()))
+                .then(() => resolve(futures))
+                .catch(reject)
+                .finally(() => {
+                futures.forEach((future) => {
+                    future.unregisterSignal(signal);
+                });
+            });
+        });
+    }
+    /**
+     * Creates a future that schedules the provided functor at the given frequency intervals
+     * @param functor function to be executed at specified intervals
+     * @param frequency interval used to schedule the functor's call
+     */
+    static periodic(functor, frequency) {
+        return Future.of((resolve, reject, signal) => {
+            // eslint-disable-next-line @typescript-eslint/no-misused-promises
+            const cancel = setInterval(() => __awaiter(this, void 0, void 0, function* () {
+                const result = functor(signal);
+                if (result instanceof Promise || result instanceof Future) {
+                    yield result;
+                }
+            }), calculatePeriodValue(frequency));
+            signal.addEventListener("abort", () => {
+                clearInterval(cancel);
+                resolve(undefined);
+            }, { once: true });
+        });
+    }
+    /**
+     * Unique ID of the future
+     */
+    get id() {
+        return this.guid;
+    }
+    /**
+     * Changes the future ID
+     * @param value
+     */
+    set id(value) {
+        this.guid = value;
+    }
+    /**
+     * Checks if the future completed. A completed future is one that ran successfully without termination.
+     */
+    get done() {
+        return this.fulfilled;
+    }
+    /**
+     * Checks if the future failed
+     */
+    get failed() {
+        return this.error instanceof Error;
+    }
+    /**
+     * Retrieves the result of the future, if there is any
+     */
+    get result() {
+        return this.completedResult;
+    }
+    /**
+     * Checks if the future is running
+     */
+    get running() {
+        return this.isRunning;
+    }
+    /**
+     * Retrieves the error if any occurred
+     */
+    get error() {
+        return this.failureResult;
+    }
+    /**
+     * Convert the future to a stream
+     */
+    get stream() {
+        return Stream.of(this);
+    }
+    /**
+     * Registers additional signal to the current future
+     * @param signal
+     */
+    registerSignal(signal) {
+        if (!this.done && !this.failed) {
+            this.signals.add(signal);
+            if (this.signalRegisteredCallback) {
+                this.signalRegisteredCallback(signal);
+            }
+        }
+        return this;
+    }
+    /**
+     * Removes the given signal from the future
+     * @param signal
+     */
+    unregisterSignal(signal) {
+        if (signal === this.defaultSignal) {
+            throw new InvalidValue("Cannot deregister default signal");
+        }
+        this.signals.delete(signal);
+        return this;
+    }
+    /**
+     * Runs the future in the background
+     */
+    schedule() {
+        this.run().catch(() => { });
+        return this;
+    }
+    /**
+     * Launches the future
+     */
+    run() {
+        return this.__run__();
+    }
+    /**
+     * Cancels the future if it is currently running
+     */
+    cancel() {
+        if (this.running) {
+            this.cancelWithSignal(this.defaultSignal);
+        }
+    }
+    /**
+     * Used to chain additional steps to be executed. This creates a new future
+     * @param callback
+     * @param clone whether the future should be cloned or not.Defaults to true
+     */
+    thenApply(callback, clone = false) {
+        if (this.running) {
+            const newFuture = Future.wrap(this.underLyingPromise)
+                .thenApply(callback)
+                .registerSignal(this.defaultSignal);
+            this.signals.forEach((signal) => newFuture.registerSignal(signal));
+            return newFuture;
+        }
+        else if (this.done) {
+            const newFuture = Future.wrap(this.underLyingPromise).thenApply(callback);
+            return newFuture;
+        }
+        const newFuture = (clone ? this.clone() : this);
+        newFuture.processors.enqueue({ success: callback });
+        return newFuture;
+    }
+    /**
+     * Used to run callback irrespective of the future completing or failing
+     * @param callback
+     * @param clone whether the future should be cloned or not.Defaults to true
+     */
+    finally(callback, clone = false) {
+        const newFuture = clone ? this.clone() : this;
+        newFuture.finallyHandlers.enqueue(callback);
+        return newFuture;
+    }
+    /**
+     * Handles any error that occurs in the previous steps inside the future
+     * @param callback
+     * @param clone whether the future should be cloned or not.Defaults to true
+     */
+    catch(callback, clone = false) {
+        const newFuture = (clone ? this.clone() : this);
+        newFuture.processors.enqueue({ failure: callback });
+        return newFuture;
+    }
+    /**
+     * Clones the current future
+     */
+    clone() {
+        const future = new Future(this.executor, this.defaultSignal);
+        future.signals = new Set(this.signals);
+        future.defaultSignal = this.defaultSignal;
+        future.processors = this.processors.clone();
+        future.fulfilled = this.fulfilled;
+        return future;
+    }
+    /**
+     * Internal. Only to be called by the internal JS runtime during await
+     * @private
+     */
+    then(onFulfilled, onRejected) {
+        return this.__run__(onFulfilled, onRejected);
+    }
+    /**
+     * Executes the future. Should only be triggered by the JS runtime via then(), or the user via run()
+     * @param onFulfilled
+     * @param onRejected
+     * @private
+     */
+    __run__(onFulfilled, onRejected) {
+        if (this.underLyingPromise) {
+            return this.underLyingPromise
+                .then((v) => {
+                onFulfilled === null || onFulfilled === void 0 ? void 0 : onFulfilled(v);
+                return v;
+            })
+                .catch((error) => {
+                if (!(error instanceof Error)) {
+                    error = new FutureError(error);
+                }
+                onRejected === null || onRejected === void 0 ? void 0 : onRejected(error);
+                throw error;
+            });
+        }
+        this.isRunning = true;
+        const resolvePromise = (promise) => {
+            return promise
+                .then((result) => __awaiter(this, void 0, void 0, function* () {
+                while (!this.processors.empty) {
+                    const { success } = this.processors.dequeue();
+                    if (!success)
+                        continue;
+                    try {
+                        result = yield this.postResultProcessing(success(new FutureResult(result, this.defaultSignal)));
+                    }
+                    catch (error) {
+                        const handler = this.findFailureHandler();
+                        if (!handler) {
+                            throw error;
+                        }
+                        result = yield this.postResultProcessing(handler(error instanceof Error ? error : new Error(String(error))));
+                    }
+                }
+                return result;
+            }))
+                .then((v) => {
+                onFulfilled === null || onFulfilled === void 0 ? void 0 : onFulfilled(v);
+                return v;
+            })
+                .catch((error) => __awaiter(this, void 0, void 0, function* () {
+                const handler = this.findFailureHandler();
+                if (!handler) {
+                    if (!(error instanceof Error)) {
+                        error = new FutureError(error);
+                    }
+                    onRejected === null || onRejected === void 0 ? void 0 : onRejected(error);
+                    throw error;
+                }
+                try {
+                    const result = yield this.postResultProcessing(handler(error));
+                    return yield resolvePromise(Promise.resolve(result));
+                }
+                catch (e) {
+                    onRejected === null || onRejected === void 0 ? void 0 : onRejected(e);
+                    throw e;
+                }
+            }));
+        };
+        this.underLyingPromise = resolvePromise(new Promise((resolve, reject) => {
+            if (Array.from(this.signals).some((v) => v.aborted)) {
+                reject(new FutureCancelled());
+                return;
+            }
+            let rejected = false;
+            const timeouts = [];
+            const abort = R.once(() => this.cancelWithSignal(this.defaultSignal));
+            const resolver = (v) => {
+                if (v instanceof Promise) {
+                    v.then((v) => {
+                        this.fulfilled = true;
+                        resolve(v);
+                    }).catch(reject);
+                }
+                else if (v instanceof Future) {
+                    v.run()
+                        .then((v) => {
+                        this.fulfilled = true;
+                        resolve(v);
+                    })
+                        .catch(reject);
+                }
+                else if (v instanceof FutureResult) {
+                    this.fulfilled = true;
+                    resolve(v.value);
+                }
+                else {
+                    this.fulfilled = true;
+                    resolve(v);
+                }
+            };
+            const rejecter = (reason) => {
+                rejected = true;
+                timeouts.forEach((v) => clearTimeout(v));
+                reject(reason);
+            };
+            this.signalRegisteredCallback = (v) => v.addEventListener("abort", () => {
+                abort();
+                if (!rejected)
+                    timeouts.push(setTimeout(() => reject(new FutureCancelled()), 1000));
+            }, { once: true });
+            this.signals.forEach((v) => {
+                v.addEventListener("abort", () => {
+                    abort();
+                    if (!rejected) {
+                        timeouts.push(setTimeout(() => reject(new FutureCancelled()), 1000));
+                    }
+                }, { once: true });
+            });
+            const result = this.executor(resolver, rejecter, this.defaultSignal);
+            if (result instanceof Promise) {
+                result
+                    .then(() => {
+                    if (!this.fulfilled) {
+                        this.fulfilled = true;
+                        resolve(null);
+                    }
+                })
+                    .catch(rejecter);
+            }
+        }))
+            .then((v) => {
+            this.completedResult = v;
+            return v;
+        })
+            .catch((e) => {
+            this.failureResult = e instanceof Error ? e : new Error(String(e));
+            throw this.failureResult;
+        })
+            .finally(() => {
+            this.finallyHandlers.forEach((handler) => handler(this));
+        })
+            .catch((e) => {
+            this.failureResult = e instanceof Error ? e : new Error(String(e));
+            throw this.failureResult;
+        })
+            .finally(() => {
+            this.signals = new Set();
+            this.isRunning = false;
+        });
+        return this.underLyingPromise;
+    }
+    /**
+     * Fires the abort signal
+     * @param signal
+     * @private
+     */
+    cancelWithSignal(signal) {
+        if (!signal.aborted) {
+            signal.dispatchEvent(new CustomEvent("abort"));
+        }
+    }
+    /**
+     * Checks if any handler exist to process errors
+     * @private
+     */
+    findFailureHandler() {
+        while (!this.processors.empty) {
+            const { failure } = this.processors.dequeue();
+            if (failure)
+                return failure;
+        }
+    }
+    /**
+     * Nested processing of a future result
+     * @param result
+     * @private
+     */
+    postResultProcessing(result) {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (result instanceof FutureResult) {
+                result = result.value;
+            }
+            else if (result instanceof Future) {
+                result = yield result.registerSignal(this.defaultSignal).run();
+            }
+            else if (result instanceof Promise) {
+                result = yield result;
+            }
+            else if (result instanceof Stream) {
+                result = yield result.execute();
+            }
+            return result;
+        });
+    }
+}
+
+export { Future, calculatePeriodValue };