UNPKG

@malagu/core

Version:
964 lines • 30.9 kB
"use strict"; Object.defineProperty(exports, "__esModule", { value: true }); exports.Promises = exports.DeferredPromise = exports.IntervalCounter = exports.TaskSequentializer = exports.retry = exports.RunOnceWorker = exports.ProcessTimeRunOnceScheduler = exports.RunOnceScheduler = exports.IntervalTimer = exports.TimeoutTimer = exports.Queue = exports.Limiter = exports.firstParallel = exports.first = exports.sequence = exports.disposableTimeout = exports.timeout = exports.AutoOpenBarrier = exports.Barrier = exports.ThrottledDelayer = exports.Delayer = exports.MicrotaskDelay = exports.SequencerByKey = exports.Sequencer = exports.Throttler = exports.asPromise = exports.raceTimeout = exports.raceCancellablePromises = exports.raceCancellationError = exports.raceCancellation = exports.createCancelablePromise = exports.waitForEvent = exports.wait = exports.delay = exports.isThenable = void 0; /* eslint-disable @typescript-eslint/no-shadow */ const cancellation_1 = require("./cancellation"); const disposable_1 = require("./disposable"); const emitter_1 = require("./emitter"); function isThenable(obj) { return !!obj && typeof obj.then === 'function'; } exports.isThenable = isThenable; /** * A function to allow a promise resolution to be delayed by a number of milliseconds. Usage is as follows: * * `const stringValue = await myPromise.then(delay(600)).then(value => value.toString());` * * @param ms the number of millisecond to delay * @returns a function that returns a promise that returns the given value, but delayed */ function delay(ms) { return value => new Promise((resolve, reject) => { setTimeout(() => resolve(value), ms); }); } exports.delay = delay; /** * Constructs a promise that will resolve after a given delay. * @param ms the number of milliseconds to wait */ async function wait(ms) { await delay(ms)(undefined); } exports.wait = wait; // eslint-disable-next-line @typescript-eslint/no-explicit-any function waitForEvent(event, ms, thisArg, disposables) { return new Promise((resolve, reject) => { const registration = setTimeout(() => { listener.dispose(); reject(new cancellation_1.CancellationError()); }, ms); const listener = event((evt) => { clearTimeout(registration); listener.dispose(); resolve(evt); }, thisArg, disposables); }); } exports.waitForEvent = waitForEvent; function createCancelablePromise(callback) { const source = new cancellation_1.CancellationTokenSource(); const thenable = callback(source.token); const promise = new Promise((resolve, reject) => { const subscription = source.token.onCancellationRequested(() => { subscription.dispose(); source.dispose(); reject(new cancellation_1.CancellationError()); }); Promise.resolve(thenable).then(value => { subscription.dispose(); source.dispose(); resolve(value); }, err => { subscription.dispose(); source.dispose(); reject(err); }); }); return new class { cancel() { source.cancel(); } then(resolve, reject) { return promise.then(resolve, reject); } catch(reject) { return this.then(undefined, reject); } finally(onfinally) { return promise.finally(onfinally); } }; } exports.createCancelablePromise = createCancelablePromise; function raceCancellation(promise, token, defaultValue) { return new Promise((resolve, reject) => { const ref = token.onCancellationRequested(() => { ref.dispose(); resolve(defaultValue); }); promise.then(resolve, reject).finally(() => ref.dispose()); }); } exports.raceCancellation = raceCancellation; function raceCancellationError(promise, token) { return new Promise((resolve, reject) => { const ref = token.onCancellationRequested(() => { ref.dispose(); reject(new cancellation_1.CancellationError()); }); promise.then(resolve, reject).finally(() => ref.dispose()); }); } exports.raceCancellationError = raceCancellationError; async function raceCancellablePromises(cancellablePromises) { let resolvedPromiseIndex = -1; const promises = cancellablePromises.map((promise, index) => promise.then(result => { resolvedPromiseIndex = index; return result; })); const result = await Promise.race(promises); cancellablePromises.forEach((cancellablePromise, index) => { if (index !== resolvedPromiseIndex) { cancellablePromise.cancel(); } }); return result; } exports.raceCancellablePromises = raceCancellablePromises; function raceTimeout(promise, timeout, onTimeout) { let promiseResolve = undefined; const timer = setTimeout(() => { promiseResolve === null || promiseResolve === void 0 ? void 0 : promiseResolve(undefined); onTimeout === null || onTimeout === void 0 ? void 0 : onTimeout(); }, timeout); return Promise.race([ promise.finally(() => clearTimeout(timer)), new Promise(resolve => promiseResolve = resolve) ]); } exports.raceTimeout = raceTimeout; function asPromise(callback) { return new Promise((resolve, reject) => { const item = callback(); if (isThenable(item)) { item.then(resolve, reject); } else { resolve(item); } }); } exports.asPromise = asPromise; /** * A helper to prevent accumulation of sequential async tasks. * * Imagine a mail man with the sole task of delivering letters. As soon as * a letter submitted for delivery, he drives to the destination, delivers it * and returns to his base. Imagine that during the trip, N more letters were submitted. * When the mail man returns, he picks those N letters and delivers them all in a * single trip. Even though N+1 submissions occurred, only 2 deliveries were made. * * The throttler implements this via the queue() method, by providing it a task * factory. Following the example: * * const throttler = new Throttler(); * const letters = []; * * function deliver() { * const lettersToDeliver = letters; * letters = []; * return makeTheTrip(lettersToDeliver); * } * * function onLetterReceived(l) { * letters.push(l); * throttler.queue(deliver); * } */ class Throttler { constructor() { this.activePromise = undefined; this.queuedPromise = undefined; this.queuedPromiseFactory = undefined; } queue(promiseFactory) { if (this.activePromise) { this.queuedPromiseFactory = promiseFactory; if (!this.queuedPromise) { const onComplete = () => { this.queuedPromise = undefined; const result = this.queue(this.queuedPromiseFactory); this.queuedPromiseFactory = undefined; return result; }; this.queuedPromise = new Promise(resolve => { this.activePromise.then(onComplete, onComplete).then(resolve); }); } return new Promise((resolve, reject) => { this.queuedPromise.then(resolve, reject); }); } this.activePromise = promiseFactory(); return new Promise((resolve, reject) => { this.activePromise.then((result) => { this.activePromise = undefined; resolve(result); }, (err) => { this.activePromise = undefined; reject(err); }); }); } } exports.Throttler = Throttler; class Sequencer { constructor() { this.current = Promise.resolve(undefined); } queue(promiseTask) { return this.current = this.current.then(() => promiseTask(), () => promiseTask()); } } exports.Sequencer = Sequencer; class SequencerByKey { constructor() { this.promiseMap = new Map(); } queue(key, promiseTask) { var _a; const runningPromise = (_a = this.promiseMap.get(key)) !== null && _a !== void 0 ? _a : Promise.resolve(); const newPromise = runningPromise .catch(() => { }) .then(promiseTask) .finally(() => { if (this.promiseMap.get(key) === newPromise) { this.promiseMap.delete(key); } }); this.promiseMap.set(key, newPromise); return newPromise; } } exports.SequencerByKey = SequencerByKey; const timeoutDeferred = (timeout, fn) => { let scheduled = true; const handle = setTimeout(() => { scheduled = false; fn(); }, timeout); return { isTriggered: () => scheduled, dispose: () => { clearTimeout(handle); scheduled = false; }, }; }; const microtaskDeferred = (fn) => { let scheduled = true; queueMicrotask(() => { if (scheduled) { scheduled = false; fn(); } }); return { isTriggered: () => scheduled, dispose: () => { scheduled = false; }, }; }; /** Can be passed into the Delayed to defer using a microtask */ exports.MicrotaskDelay = Symbol('MicrotaskDelay'); /** * A helper to delay (debounce) execution of a task that is being requested often. * * Following the throttler, now imagine the mail man wants to optimize the number of * trips proactively. The trip itself can be long, so he decides not to make the trip * as soon as a letter is submitted. Instead he waits a while, in case more * letters are submitted. After said waiting period, if no letters were submitted, he * decides to make the trip. Imagine that N more letters were submitted after the first * one, all within a short period of time between each other. Even though N+1 * submissions occurred, only 1 delivery was made. * * The delayer offers this behavior via the trigger() method, into which both the task * to be executed and the waiting period (delay) must be passed in as arguments. Following * the example: * * const delayer = new Delayer(WAITING_PERIOD); * const letters = []; * * function letterReceived(l) { * letters.push(l); * delayer.trigger(() => { return makeTheTrip(); }); * } */ class Delayer { constructor(defaultDelay) { this.defaultDelay = defaultDelay; this.deferred = undefined; this.completionPromise = undefined; this.doResolve = undefined; this.doReject = undefined; this.task = undefined; } trigger(task, delay = this.defaultDelay) { this.task = task; this.cancelTimeout(); if (!this.completionPromise) { this.completionPromise = new Promise((resolve, reject) => { this.doResolve = resolve; this.doReject = reject; }).then(() => { this.completionPromise = undefined; this.doResolve = undefined; if (this.task) { const task = this.task; this.task = undefined; return task(); } return undefined; }); } const fn = () => { var _a; this.deferred = undefined; (_a = this.doResolve) === null || _a === void 0 ? void 0 : _a.call(this, undefined); }; this.deferred = delay === exports.MicrotaskDelay ? microtaskDeferred(fn) : timeoutDeferred(delay, fn); return this.completionPromise; } isTriggered() { var _a; return !!((_a = this.deferred) === null || _a === void 0 ? void 0 : _a.isTriggered()); } cancel() { this.cancelTimeout(); if (this.completionPromise) { if (this.doReject) { this.doReject(new cancellation_1.CancellationError()); } this.completionPromise = undefined; } } cancelTimeout() { var _a; (_a = this.deferred) === null || _a === void 0 ? void 0 : _a.dispose(); this.deferred = undefined; } dispose() { this.cancel(); } } exports.Delayer = Delayer; /** * A helper to delay execution of a task that is being requested often, while * preventing accumulation of consecutive executions, while the task runs. * * The mail man is clever and waits for a certain amount of time, before going * out to deliver letters. While the mail man is going out, more letters arrive * and can only be delivered once he is back. Once he is back the mail man will * do one more trip to deliver the letters that have accumulated while he was out. */ class ThrottledDelayer { constructor(defaultDelay) { this.delayer = new Delayer(defaultDelay); this.throttler = new Throttler(); } trigger(promiseFactory, delay) { return this.delayer.trigger(() => this.throttler.queue(promiseFactory), delay); } isTriggered() { return this.delayer.isTriggered(); } cancel() { this.delayer.cancel(); } dispose() { this.delayer.dispose(); } } exports.ThrottledDelayer = ThrottledDelayer; /** * A barrier that is initially closed and then becomes opened permanently. */ class Barrier { constructor() { this._isOpen = false; this._promise = new Promise((c, e) => { this._completePromise = c; }); } isOpen() { return this._isOpen; } open() { this._isOpen = true; this._completePromise(true); } wait() { return this._promise; } } exports.Barrier = Barrier; /** * A barrier that is initially closed and then becomes opened permanently after a certain period of * time or when open is called explicitly */ class AutoOpenBarrier extends Barrier { constructor(autoOpenTimeMs) { super(); this._timeout = setTimeout(() => this.open(), autoOpenTimeMs); } open() { clearTimeout(this._timeout); super.open(); } } exports.AutoOpenBarrier = AutoOpenBarrier; function timeout(millis, token) { if (!token) { return createCancelablePromise(token => timeout(millis, token)); } return new Promise((resolve, reject) => { const handle = setTimeout(() => { disposable.dispose(); resolve(); }, millis); const disposable = token.onCancellationRequested(() => { clearTimeout(handle); disposable.dispose(); reject(new cancellation_1.CancellationError()); }); }); } exports.timeout = timeout; function disposableTimeout(handler, timeout = 0) { const timer = setTimeout(handler, timeout); return disposable_1.Disposable.create(() => clearTimeout(timer)); } exports.disposableTimeout = disposableTimeout; /** * Runs the provided list of promise factories in sequential order. The returned * promise will complete to an array of results from each promise. */ function sequence(promiseFactories) { const results = []; let index = 0; const len = promiseFactories.length; function next() { return index < len ? promiseFactories[index++]() : undefined; } function thenHandler(result) { if (result !== undefined && result !== undefined) { results.push(result); } const n = next(); if (n) { return n.then(thenHandler); } return Promise.resolve(results); } return Promise.resolve(undefined).then(thenHandler); } exports.sequence = sequence; function first(promiseFactories, shouldStop = t => !!t, defaultValue = undefined) { let index = 0; const len = promiseFactories.length; const loop = () => { if (index >= len) { return Promise.resolve(defaultValue); } const factory = promiseFactories[index++]; const promise = Promise.resolve(factory()); return promise.then(result => { if (shouldStop(result)) { return Promise.resolve(result); } return loop(); }); }; return loop(); } exports.first = first; function firstParallel(promiseList, shouldStop = t => !!t, defaultValue = undefined) { if (promiseList.length === 0) { return Promise.resolve(defaultValue); } let todo = promiseList.length; const finish = () => { var _a, _b; todo = -1; for (const promise of promiseList) { (_b = (_a = promise).cancel) === null || _b === void 0 ? void 0 : _b.call(_a); } }; return new Promise((resolve, reject) => { for (const promise of promiseList) { promise.then(result => { if (--todo >= 0 && shouldStop(result)) { finish(); resolve(result); } else if (todo === 0) { resolve(defaultValue); } }) .catch(err => { if (--todo >= 0) { finish(); reject(err); } }); } }); } exports.firstParallel = firstParallel; /** * A helper to queue N promises and run them all with a max degree of parallelism. The helper * ensures that at any time no more than M promises are running at the same time. */ class Limiter { constructor(maxDegreeOfParalellism) { this._size = 0; this.maxDegreeOfParalellism = maxDegreeOfParalellism; this.outstandingPromises = []; this.runningPromises = 0; this._onDrained = new emitter_1.Emitter(); } /** * An event that fires when every promise in the queue * has started to execute. In other words: no work is * pending to be scheduled. * * This is NOT an event that signals when all promises * have finished though. */ get onDrained() { return this._onDrained.event; } get size() { return this._size; } queue(factory) { this._size++; return new Promise((c, e) => { this.outstandingPromises.push({ factory, c, e }); this.consume(); }); } consume() { while (this.outstandingPromises.length && this.runningPromises < this.maxDegreeOfParalellism) { const iLimitedTask = this.outstandingPromises.shift(); this.runningPromises++; const promise = iLimitedTask.factory(); promise.then(iLimitedTask.c, iLimitedTask.e); promise.then(() => this.consumed(), () => this.consumed()); } } consumed() { this._size--; this.runningPromises--; if (this.outstandingPromises.length > 0) { this.consume(); } else { this._onDrained.fire(); } } dispose() { this._onDrained.dispose(); } } exports.Limiter = Limiter; /** * A queue is handles one promise at a time and guarantees that at any time only one promise is executing. */ class Queue extends Limiter { constructor() { super(1); } } exports.Queue = Queue; class TimeoutTimer { constructor(runner, timeout) { this._token = -1; if (typeof runner === 'function' && typeof timeout === 'number') { this.setIfNotSet(runner, timeout); } } dispose() { this.cancel(); } cancel() { if (this._token !== -1) { clearTimeout(this._token); this._token = -1; } } cancelAndSet(runner, timeout) { this.cancel(); this._token = setTimeout(() => { this._token = -1; runner(); }, timeout); } setIfNotSet(runner, timeout) { if (this._token !== -1) { // timer is already set return; } this._token = setTimeout(() => { this._token = -1; runner(); }, timeout); } } exports.TimeoutTimer = TimeoutTimer; class IntervalTimer { constructor() { this._token = -1; } dispose() { this.cancel(); } cancel() { if (this._token !== -1) { clearInterval(this._token); this._token = -1; } } cancelAndSet(runner, interval) { this.cancel(); this._token = setInterval(() => { runner(); }, interval); } } exports.IntervalTimer = IntervalTimer; class RunOnceScheduler { constructor(runner, delay) { this.timeoutToken = -1; this.runner = runner; this.timeout = delay; this.timeoutHandler = this.onTimeout.bind(this); } /** * Dispose RunOnceScheduler */ dispose() { this.cancel(); this.runner = undefined; } /** * Cancel current scheduled runner (if any). */ cancel() { if (this.isScheduled()) { clearTimeout(this.timeoutToken); this.timeoutToken = -1; } } /** * Cancel previous runner (if any) & schedule a new runner. */ schedule(delay = this.timeout) { this.cancel(); this.timeoutToken = setTimeout(this.timeoutHandler, delay); } get delay() { return this.timeout; } set delay(value) { this.timeout = value; } /** * Returns true if scheduled. */ isScheduled() { return this.timeoutToken !== -1; } onTimeout() { this.timeoutToken = -1; if (this.runner) { this.doRun(); } } doRun() { if (this.runner) { this.runner(); } } } exports.RunOnceScheduler = RunOnceScheduler; /** * Same as `RunOnceScheduler`, but doesn't count the time spent in sleep mode. * > **NOTE**: Only offers 1s resolution. * * When calling `setTimeout` with 3hrs, and putting the computer immediately to sleep * for 8hrs, `setTimeout` will fire **as soon as the computer wakes from sleep**. But * this scheduler will execute 3hrs **after waking the computer from sleep**. */ class ProcessTimeRunOnceScheduler { constructor(runner, delay) { if (delay % 1000 !== 0) { console.warn(`ProcessTimeRunOnceScheduler resolution is 1s, ${delay}ms is not a multiple of 1000ms.`); } this.runner = runner; this.timeout = delay; this.counter = 0; this.intervalToken = -1; this.intervalHandler = this.onInterval.bind(this); } dispose() { this.cancel(); this.runner = undefined; } cancel() { if (this.isScheduled()) { clearInterval(this.intervalToken); this.intervalToken = -1; } } /** * Cancel previous runner (if any) & schedule a new runner. */ schedule(delay = this.timeout) { if (delay % 1000 !== 0) { console.warn(`ProcessTimeRunOnceScheduler resolution is 1s, ${delay}ms is not a multiple of 1000ms.`); } this.cancel(); this.counter = Math.ceil(delay / 1000); this.intervalToken = setInterval(this.intervalHandler, 1000); } /** * Returns true if scheduled. */ isScheduled() { return this.intervalToken !== -1; } onInterval() { this.counter--; if (this.counter > 0) { // still need to wait return; } // time elapsed clearInterval(this.intervalToken); this.intervalToken = -1; if (this.runner) { this.runner(); } } } exports.ProcessTimeRunOnceScheduler = ProcessTimeRunOnceScheduler; class RunOnceWorker extends RunOnceScheduler { constructor(runner, timeout) { super(runner, timeout); this.units = []; } work(unit) { this.units.push(unit); if (!this.isScheduled()) { this.schedule(); } } doRun() { const units = this.units; this.units = []; if (this.runner) { this.runner(units); } } dispose() { this.units = []; super.dispose(); } } exports.RunOnceWorker = RunOnceWorker; async function retry(task, delay, retries) { let lastError; for (let i = 0; i < retries; i++) { try { return await task(); } catch (error) { lastError = error; await timeout(delay); } } throw lastError; } exports.retry = retry; class TaskSequentializer { hasPending(taskId) { if (!this._pending) { return false; } if (typeof taskId === 'number') { return this._pending.taskId === taskId; } return !!this._pending; } get pending() { return this._pending ? this._pending.promise : undefined; } cancelPending() { var _a; (_a = this._pending) === null || _a === void 0 ? void 0 : _a.cancel(); } setPending(taskId, promise, onCancel) { this._pending = { taskId, cancel: () => onCancel === null || onCancel === void 0 ? void 0 : onCancel(), promise }; promise.then(() => this.donePending(taskId), () => this.donePending(taskId)); return promise; } donePending(taskId) { if (this._pending && taskId === this._pending.taskId) { // only set pending to done if the promise finished that is associated with that taskId this._pending = undefined; // schedule the next task now that we are free if we have any this.triggerNext(); } } triggerNext() { if (this._next) { const next = this._next; this._next = undefined; // Run next task and complete on the associated promise next.run().then(next.promiseResolve, next.promiseReject); } } setNext(run) { // this is our first next task, so we create associated promise with it // so that we can return a promise that completes when the task has // completed. if (!this._next) { let promiseResolve; let promiseReject; const promise = new Promise((resolve, reject) => { promiseResolve = resolve; promiseReject = reject; }); this._next = { run, promise, promiseResolve: promiseResolve, promiseReject: promiseReject }; } else { this._next.run = run; } return this._next.promise; } } exports.TaskSequentializer = TaskSequentializer; // #endregion // #region /** * The `IntervalCounter` allows to count the number * of calls to `increment()` over a duration of * `interval`. This utility can be used to conditionally * throttle a frequent task when a certain threshold * is reached. */ class IntervalCounter { constructor(interval, nowFn = () => Date.now()) { this.interval = interval; this.nowFn = nowFn; this.lastIncrementTime = 0; this.value = 0; } increment() { const now = this.nowFn(); // We are outside of the range of `interval` and as such // start counting from 0 and remember the time if (now - this.lastIncrementTime > this.interval) { this.lastIncrementTime = now; this.value = 0; } this.value++; return this.value; } } exports.IntervalCounter = IntervalCounter; /** * Creates a promise whose resolution or rejection can be controlled imperatively. */ class DeferredPromise { constructor() { this.rejected = false; this.resolved = false; this.p = new Promise((c, e) => { this.completeCallback = c; this.errorCallback = e; }); } get isRejected() { return this.rejected; } get isResolved() { return this.resolved; } get isSettled() { return this.rejected || this.resolved; } complete(value) { return new Promise(resolve => { this.completeCallback(value); this.resolved = true; resolve(); }); } error(err) { return new Promise(resolve => { this.errorCallback(err); this.rejected = true; resolve(); }); } cancel() { new Promise(resolve => { this.errorCallback(new cancellation_1.CancellationError()); this.rejected = true; resolve(); }); } } exports.DeferredPromise = DeferredPromise; // #endregion // #region Promises var Promises; (function (Promises) { /** * A drop-in replacement for `Promise.all` with the only difference * that the method awaits every promise to either fulfill or reject. * * Similar to `Promise.all`, only the first error will be returned * if any. */ async function settled(promises) { let firstError = undefined; const result = await Promise.all(promises.map(promise => promise.then(value => value, error => { if (!firstError) { firstError = error; } return undefined; // do not rethrow so that other promises can settle }))); if (typeof firstError !== 'undefined') { throw firstError; } return result; // cast is needed and protected by the `throw` above } Promises.settled = settled; /** * A helper to create a new `Promise<T>` with a body that is a promise * itself. By default, an error that raises from the async body will * end up as a unhandled rejection, so this utility properly awaits the * body and rejects the promise as a normal promise does without async * body. * * This method should only be used in rare cases where otherwise `async` * cannot be used (e.g. when callbacks are involved that require this). */ function withAsyncBody(bodyFn) { // eslint-disable-next-line no-async-promise-executor return new Promise(async (resolve, reject) => { try { await bodyFn(resolve, reject); } catch (error) { reject(error); } }); } Promises.withAsyncBody = withAsyncBody; })(Promises = exports.Promises || (exports.Promises = {})); // #endregion //# sourceMappingURL=async.js.map