@superutils/promise 1.0.9 → 1.1.1

package/README.md

@@ -117,7 +117,7 @@ while (!appReady) {
 }
 ```
 
-#### `PromisE.delay(duration, callback)`: execute after delay
+#### `PromisE.delay(duration, callback, asRejected)`: execute after delay
 
 Creates a promise that executes a function after a specified duration and returns the value the function returns.
 
@@ -126,10 +126,13 @@ If callback returns undefined, default value will be the duration.
 ```typescript
 import PromisE from '@superutils/promise'
 
-const callback = () => {
-	/* do stuff here */
+const func = async () => {
+	console.log('Waiting for app initialization or something else to be ready')
+	// wait 3 seconds before proceeding
+	await PromisE.delay(3000)
+	console.log('App ready')
 }
-await PromisE.delay(100, callback)
+func()
 ```
 
 <div id="deferred"></div>
@@ -138,32 +141,48 @@ await PromisE.delay(100, callback)
 
 Create a function that debounces or throttles promise-returning function calls. This is useful for scenarios like auto-saving user input or preventing multiple rapid API calls.
 
-```typescript
-import PromisE, { ResolveIgnored } from '@superutils/promise'
+#### Debounce example:
 
-// Create a deferred function that waits 300ms after the last call
-const deferredSave = PromisE.deferred({
-	defer: 300,
-	/** ignored promises will resolve with `undefined` */
-	resolveIgnored: ResolveIgnored.WITH_UNDEFINED,
+```typescript
+const example = async (options = {}) => {
+	const df = PromisE.deferred({
+		delayMs: 100,
+		resolveIgnored: ResolveIgnored.NEVER, // never resolve ignored calls
+		...options,
+	})
+	df(() => PromisE.delay(500)).then(console.log)
+	df(() => PromisE.delay(1000)).then(console.log)
+	df(() => PromisE.delay(5000)).then(console.log)
+	// delay 2 seconds and invoke df() again
+	await PromisE.delay(2000)
+	df(() => PromisE.delay(200)).then(console.log)
+}
+example({ ignoreStale: false, throttle: false })
+// `200` and `1000` will be printed in the console
+example({ ignoreStale: true, throttle: false })
+// `200` will be printed in the console
+```
 
-	/** ignored promises will NEVER be resolved/rejected
-	 * USE WITH CAUTION!
-	 */
-	resolveIgnored: ResolveIgnored.NEVER,
+#### Throttle example:
 
-	// ignored promises will resolve with the result of the last call
-	resolveIgnored: ResolveIgnored.WITH_LAST, // (default)
-})
-
-// Simulate rapid calls
-deferredSave(() => api.save({ text: 'first' }))
-deferredSave(() => api.save({ text: 'second' }))
-// Only the 3rd call is executed.
-// But all of them are resolved with the result of the 3rd call when `resolveIgnored` is `ResolveIgnored.WITH_LAST`
-deferredSave(() => api.save({ text: 'third' })).then(response =>
-	console.log('Saved!', response),
-)
+```typescript
+const example = async (options = {}) => {
+	const df = PromisE.deferred({
+		delayMs: 100,
+		resolveIgnored: ResolveIgnored.NEVER, // never resolve ignored calls
+		...options,
+	})
+	df(() => PromisE.delay(5000)).then(console.log)
+	df(() => PromisE.delay(500)).then(console.log)
+	df(() => PromisE.delay(1000)).then(console.log)
+	// delay 2 seconds and invoke df() again
+	await PromisE.delay(2000)
+	df(() => PromisE.delay(200)).then(console.log)
+}
+example({ ignoreStale: true, throttle: true })
+// `200` will be printed in the console
+example({ ignoreStale: false, throttle: true })
+// `200` and `5000` will be printed in the console
 ```
 
 <div id="deferredCallback"></div>

package/dist/index.d.ts

@@ -85,14 +85,18 @@ 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>;
+    ignoreStale?: boolean;
     /** 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,17 +122,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;
-} & Omit<DeferredOptions, 'onError' | 'ThisArg' | 'tid'>) | {
-    /** Sequential execution. All promises will be executed sequentially making sure there is no overlap. */
-    delayMs: 0;
-    throttle?: false;
-});
+} & Pick<DeferredOptions, 'leading'>));
 /** Determines what to do when deferred promise/function fails */
 declare enum ResolveError {
     /** Neither resolve nor reject the failed */
@@ -176,7 +176,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;
@@ -224,7 +224,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;
@@ -352,7 +358,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)
@@ -378,8 +384,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;
     };
 }
@@ -686,7 +699,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;
   }
@@ -170,105 +176,124 @@ var ResolveIgnored = /* @__PURE__ */ ((ResolveIgnored2) => {
 
 // src/deferred.ts
 function deferred(options = {}) {
-  const { defaults } = deferred;
+  let sequence = 0;
   options = objCopy(
-    defaults,
+    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) {
-      queue.delete(currentId);
-      const [nextId, nextItem] = [...queue.entries()][0] || [];
-      return nextId && nextItem && execute(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];
+  const handleIgnore = (items, prevQItem2) => {
+    for (const [iId, iItem] of items) {
       queue.delete(iId);
-      if (iItem == void 0 || iItem.started) continue;
-      onIgnore && fallbackIfFails2(onIgnore, [iItem.getPromise], void 0);
+      if (iItem === void 0 || iItem.started) continue;
+      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);
+          prevQItem2 == null ? void 0 : prevQItem2.then(iItem.resolve, iItem.reject);
           break;
         case "NEVER" /* NEVER */:
           break;
       }
     }
+    if (!queue.size) sequence = 0;
   };
-  const finalizeCb = (resolve, id, qItem) => (resultOrErr) => {
-    ignoreOrProceed(id, qItem);
-    if (resolve) {
-      qItem.resolve(resultOrErr);
-      onResult && fallbackIfFails2(onResult, [resultOrErr], void 0);
-      return;
+  const handleRemaining = (currentId) => {
+    const _prevQItem = prevQItem;
+    prevQItem = null;
+    if (isSequential) {
+      queue.delete(currentId);
+      const [nextId, nextItem] = [...queue.entries()][0] || [];
+      return nextId && nextItem && handleItem(nextId, nextItem);
     }
-    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;
+    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);
     }
+    handleIgnore(items, _prevQItem);
   };
-  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);
-  })();
+  let prevSeq = 0;
+  const executeItem = async (id, qItem) => {
+    var _a;
+    qItem.started = true;
+    const _prevQItem = prevQItem;
+    prevQItem = qItem;
+    prevSeq = (_a = prevQItem == null ? void 0 : prevQItem.sequence) != null ? _a : 0;
+    try {
+      const result = await PromisEBase_default.try(qItem.getPromise);
+      const ignore = !isSequential && options.ignoreStale && prevSeq > qItem.sequence;
+      if (ignore) return handleIgnore([[id, qItem]], _prevQItem);
+      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;
+      }
+    }
+    handleRemaining(id);
+  };
+  const handleItem = isSequential ? executeItem : (throttle ? throttledCore : deferredCore)(
+    executeItem,
+    delayMs,
+    options
+  );
   const deferredFunc = (promise) => {
     const id = /* @__PURE__ */ Symbol("deferred-queue-item-id");
     const qItem = new PromisEBase_default();
     qItem.getPromise = isFn2(promise) ? promise : () => promise;
     qItem.started = false;
+    qItem.sequence = ++sequence;
     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.8"
+		"@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.8"
+		"@superutils/core": "^1.1.1"
 	},
 	"publishConfig": {
 		"access": "public"
@@ -43,5 +43,5 @@
 	"sideEffects": false,
 	"type": "module",
 	"types": "dist/index.d.ts",
-	"version": "1.0.9"
+	"version": "1.1.1"
 }