@superutils/promise 1.0.7 → 1.1.0

package/dist/index.d.ts

@@ -85,14 +85,17 @@ type DeferredAsyncDefaults = Pick<Required<DeferredAsyncOptions>, 'delayMs' | 'r
 /** Options for `PromisE.deferred` and other related functions */
 type DeferredAsyncOptions<ThisArg = unknown, DelayMs extends number = number> = {
     /**
-     * Delay in milliseconds, used for `debounce` and `throttle` modes.
+     * Delay in milliseconds, used for `debounce` and `throttle` modes. Use `0` for sequential execution.
      *
-     * Default: `100`
+     * Use `0` to disable debounce/throttle and execute all operations sequentially.
+     *
+     * Default: `100` (or what is set in `PromisE.deferred.defaults.delayMs`)
      */
+    delayMs?: 0 | PositiveNumber<DelayMs>;
     /** Callback invoked whenever promise/function throws error */
     onError?: (this: ThisArg, err: unknown) => ValueOrPromise<unknown>;
     /**
-     * Whenever a promise/function is ignored when in debource/throttle mode, `onIgnored` wil be invoked.
+     * Whenever a promise/function is ignored when in debounce/throttle mode, `onIgnored` wil be invoked.
      * The promise/function will not be invoked, unless it's manually invoked using the `ignored` function.
      * Use for debugging or logging purposes.
      */
@@ -118,13 +121,13 @@ type DeferredAsyncOptions<ThisArg = unknown, DelayMs extends number = number> =
     thisArg?: ThisArg;
 } & (({
     /** Throttle duration in milliseconds */
-    delayMs?: PositiveNumber<DelayMs>;
+    delayMs: PositiveNumber<DelayMs>;
     throttle: true;
-} & Omit<ThrottleOptions, 'onError' | 'ThisArg' | 'tid'>) | ({
+} & Pick<ThrottleOptions, 'trailing'>) | ({
     /** Debounce/deferred duration in milliseconds */
     delayMs?: PositiveNumber<DelayMs>;
-    throttle?: false | undefined;
-} & Omit<DeferredOptions, 'onError' | 'ThisArg' | 'tid'>));
+    throttle?: false;
+} & Pick<DeferredOptions, 'leading'>));
 /** Determines what to do when deferred promise/function fails */
 declare enum ResolveError {
     /** Neither resolve nor reject the failed */
@@ -143,7 +146,7 @@ declare enum ResolveError {
 declare enum ResolveIgnored {
     /** Never resolve ignored promises. Caution: make sure this doesn't cause any memory leaks. */
     NEVER = "NEVER",
-    /** (default) resolve with active promise result, the one that caused the current promise/callback to be ignored).  */
+    /** (default) resolve with active promise result, the one that caused the current promise/callback to be ignored. */
     WITH_LAST = "WITH_LAST",
     /** resolve with `undefined` value */
     WITH_UNDEFINED = "WITH_UNDEFINED"
@@ -172,7 +175,7 @@ type RetryOptions<T = unknown> = {
      */
     retryDelay?: number;
     /**
-     * Add a random delay between 0ms and `retryDelayJitterMax` to the `retryDelayMs`.
+     * Add a random delay between 0ms and `retryDelayJitterMax` to the `retryDelay`.
      * Default: `true`
      */
     retryDelayJitter?: boolean;
@@ -220,7 +223,13 @@ declare class PromisEBase<T = unknown> extends Promise<T> implements IPromisE<T>
     get rejected(): boolean;
     /** Indicates if the promise has been resolved */
     get resolved(): boolean;
-    /** Get promise status code */
+    /**
+     * Get promise status code:
+     *
+     * - `0` = pending
+     * - `1` = resolved
+     * - `2` = rejected
+     */
     get state(): 0 | 1 | 2;
     /** Resovle pending promise early. */
     resolve: (value: T | PromiseLike<T>) => void;
@@ -348,7 +357,7 @@ type TimeoutOptions<Func extends string = 'all'> = {
  * @example Explanation & example usage:
  * ```typescript
  * const example = throttle => {
- *     const df = PromisE.deferred(throttle)
+ *     const df = PromisE.deferred({ delayMs: 100, throttle })
  *     df(() => PromisE.delay(5000)).then(console.log)
  *     df(() => PromisE.delay(500)).then(console.log)
  *     df(() => PromisE.delay(1000)).then(console.log)
@@ -374,8 +383,15 @@ type TimeoutOptions<Func extends string = 'all'> = {
 declare function deferred<T, ThisArg = unknown, Delay extends number = number>(options?: DeferredAsyncOptions<ThisArg, Delay>): DeferredAsyncCallback;
 declare namespace deferred {
     var defaults: {
+        /**
+         * Default delay in milliseconds, used in `debounce` and `throttle` modes.
+         *
+         * Use `0` (or negative number) to disable debounce/throttle and execute all operations sequentially.
+         */
         delayMs: number;
+        /** Set the default error resolution behavior. {@link ResolveError} for all options. */
         resolveError: ResolveError.REJECT;
+        /** Set the default ignored resolution behavior. See {@link ResolveIgnored} for all options. */
         resolveIgnored: ResolveIgnored.WITH_LAST;
     };
 }
@@ -682,7 +698,7 @@ declare class PromisE<T = unknown> extends PromisEBase<T> {
  * - `'linear'` uses a constant delay.
  *
  * Default: `'exponential'`
- * @param options.retryDelayMs (optional) The base delay in milliseconds between retries.
+ * @param options.retryDelay (optional) The base delay in milliseconds between retries.
  *
  * Default: `300`
  * @param options.retryDelayJitter (optional) If true, adds a random jitter to the delay to prevent

package/dist/index.js

@@ -76,7 +76,13 @@ var _PromisEBase = class _PromisEBase extends Promise {
   get resolved() {
     return this._state === 1;
   }
-  /** Get promise status code */
+  /**
+   * Get promise status code:
+   *
+   * - `0` = pending
+   * - `1` = resolved
+   * - `2` = rejected
+   */
   get state() {
     return this._state;
   }
@@ -169,101 +175,117 @@ var ResolveIgnored = /* @__PURE__ */ ((ResolveIgnored2) => {
 })(ResolveIgnored || {});
 
 // src/deferred.ts
-function deferred(options) {
-  const { defaults } = deferred;
-  options = objCopy(defaults, options, [], "empty");
+function deferred(options = {}) {
+  options = objCopy(
+    deferred.defaults,
+    options,
+    [],
+    "empty"
+  );
   let { onError, onIgnore, onResult } = options;
   const {
-    delayMs,
+    delayMs = 0,
     resolveError,
-    // by default reject on error
     resolveIgnored,
     thisArg,
     throttle
   } = options;
-  let lastPromisE = null;
+  let prevQItem = null;
   const queue = /* @__PURE__ */ new Map();
-  const gotDelay = isPositiveNumber(delayMs);
+  const isSequential = !isPositiveNumber(delayMs);
   if (thisArg !== void 0) {
     onError = onError == null ? void 0 : onError.bind(thisArg);
     onIgnore = onIgnore == null ? void 0 : onIgnore.bind(thisArg);
     onResult = onResult == null ? void 0 : onResult.bind(thisArg);
   }
-  const ignoreOrProceed = (currentId, qItem) => {
-    lastPromisE = null;
-    if (!gotDelay) {
+  const handleRemaining = (currentId) => {
+    const _prevQItem = prevQItem;
+    prevQItem = null;
+    if (isSequential) {
       queue.delete(currentId);
       const [nextId, nextItem] = [...queue.entries()][0] || [];
-      return nextId && nextItem && execute(nextId, nextItem);
+      return nextId && nextItem && handleItem(nextId, nextItem);
     }
-    const items = [...queue.entries()];
-    const currentIndex = items.findIndex(([id]) => id === currentId);
-    for (let i = 0; i <= currentIndex; i++) {
-      const [iId, iItem] = items[i];
-      queue.delete(iId);
-      if (iItem == void 0 || iItem.started) continue;
-      onIgnore && fallbackIfFails2(onIgnore, [iItem.getPromise], void 0);
+    let items = [...queue.entries()];
+    if (throttle && options.trailing) {
+      items = items.slice(
+        0,
+        items.findIndex(([id]) => id === currentId)
+      );
+    } else if (!throttle && options.leading) {
+      items = items.slice(0, -1);
+    }
+    for (const [iId, iItem] of items) {
+      !iItem.completed && queue.delete(iId);
+      if (iItem === void 0 || iItem.started || iItem.completed)
+        continue;
+      iItem.completed = true;
+      onIgnore && fallbackIfFails2(onIgnore, [iItem.getPromise], 0);
       switch (resolveIgnored) {
         case "WITH_UNDEFINED" /* WITH_UNDEFINED */:
           iItem.resolve(void 0);
           break;
         case "WITH_LAST" /* WITH_LAST */:
-          qItem == null ? void 0 : qItem.then(iItem.resolve, iItem.reject);
+          _prevQItem == null ? void 0 : _prevQItem.then(iItem.resolve, iItem.reject);
           break;
         case "NEVER" /* NEVER */:
           break;
       }
     }
   };
-  const finalizeCb = (resolve, id, qItem) => (resultOrErr) => {
-    ignoreOrProceed(id, qItem);
-    if (resolve) {
-      qItem.resolve(resultOrErr);
-      onResult && fallbackIfFails2(onResult, [resultOrErr], void 0);
-      return;
-    }
-    onError && fallbackIfFails2(onError, [resultOrErr], void 0);
-    switch (resolveError) {
-      case "REJECT" /* REJECT */:
-        qItem.reject(resultOrErr);
-      // eslint-disable-next-line no-fallthrough
-      case "NEVER" /* NEVER */:
-        break;
-      case "RESOLVE_UNDEFINED" /* WITH_UNDEFINED */:
-        resultOrErr = void 0;
-      // eslint-disable-next-line no-fallthrough
-      case "RESOLVE_ERROR" /* WITH_ERROR */:
-        qItem.resolve(resultOrErr);
-        break;
+  const executeItem = async (id, qItem) => {
+    if (!id || !(qItem == null ? void 0 : qItem.pending) || qItem.completed) return;
+    qItem.started = true;
+    prevQItem = qItem;
+    try {
+      const result = await PromisEBase_default.try(qItem.getPromise);
+      qItem.resolve(result);
+      onResult && fallbackIfFails2(onResult, [result], void 0);
+    } catch (err) {
+      onError && fallbackIfFails2(onError, [err], void 0);
+      switch (resolveError) {
+        case "REJECT" /* REJECT */:
+          qItem.reject(err);
+        // eslint-disable-next-line no-fallthrough
+        case "NEVER" /* NEVER */:
+          break;
+        case "RESOLVE_UNDEFINED" /* WITH_UNDEFINED */:
+          qItem.resolve(void 0);
+          break;
+        case "RESOLVE_ERROR" /* WITH_ERROR */:
+          qItem.resolve(err);
+          break;
+      }
     }
+    qItem.completed = true;
+    handleRemaining(id);
   };
-  const execute = (() => {
-    const execute2 = (id, qItem) => {
-      qItem.started = true;
-      lastPromisE = new PromisEBase_default(qItem.getPromise());
-      lastPromisE.then(
-        finalizeCb(true, id, qItem),
-        finalizeCb(false, id, qItem)
-      );
-    };
-    if (!gotDelay) return execute2;
-    const deferFn = throttle ? throttledCore : deferredCore;
-    return deferFn(execute2, delayMs, options);
-  })();
+  const handleItem = isSequential ? executeItem : (throttle ? throttledCore : deferredCore)(
+    executeItem,
+    delayMs,
+    options
+  );
   const deferredFunc = (promise) => {
-    const id = Symbol("deferred-queue-item-id");
+    const id = /* @__PURE__ */ Symbol("deferred-queue-item-id");
     const qItem = new PromisEBase_default();
     qItem.getPromise = isFn2(promise) ? promise : () => promise;
     qItem.started = false;
     queue.set(id, qItem);
-    if (gotDelay || !lastPromisE) execute(id, qItem);
+    if (!prevQItem || !isSequential) handleItem(id, qItem);
     return qItem;
   };
   return deferredFunc;
 }
 deferred.defaults = {
+  /**
+   * Default delay in milliseconds, used in `debounce` and `throttle` modes.
+   *
+   * Use `0` (or negative number) to disable debounce/throttle and execute all operations sequentially.
+   */
   delayMs: 100,
+  /** Set the default error resolution behavior. {@link ResolveError} for all options. */
   resolveError: "REJECT" /* REJECT */,
+  /** Set the default ignored resolution behavior. See {@link ResolveIgnored} for all options. */
   resolveIgnored: "WITH_LAST" /* WITH_LAST */
 };
 var deferred_default = deferred;

package/package.json

@@ -4,7 +4,7 @@
 		"url": "https://github.com/alien45/superutils/issues"
 	},
 	"dependencies": {
-		"@superutils/core": "^1.0.7"
+		"@superutils/core": "^1.1.1"
 	},
 	"description": "An extended Promise with extra features such as status tracking, deferred/throttled execution, timeout and retry mechanism.",
 	"files": [
@@ -23,7 +23,7 @@
 	"main": "dist/index.js",
 	"name": "@superutils/promise",
 	"peerDpendencies": {
-		"@superutils/core": "^1.0.7"
+		"@superutils/core": "^1.1.1"
 	},
 	"publishConfig": {
 		"access": "public"
@@ -43,5 +43,5 @@
 	"sideEffects": false,
 	"type": "module",
 	"types": "dist/index.d.ts",
-	"version": "1.0.7"
+	"version": "1.1.0"
 }