@superutils/promise 1.1.0 → 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

@@ -92,6 +92,7 @@ type DeferredAsyncOptions<ThisArg = unknown, DelayMs extends number = number> =
      * 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>;
     /**

package/dist/index.js

@@ -176,6 +176,7 @@ var ResolveIgnored = /* @__PURE__ */ ((ResolveIgnored2) => {
 
 // src/deferred.ts
 function deferred(options = {}) {
+  let sequence = 0;
   options = objCopy(
     deferred.defaults,
     options,
@@ -198,6 +199,24 @@ function deferred(options = {}) {
     onIgnore = onIgnore == null ? void 0 : onIgnore.bind(thisArg);
     onResult = onResult == null ? void 0 : onResult.bind(thisArg);
   }
+  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], 0);
+      switch (resolveIgnored) {
+        case "WITH_UNDEFINED" /* WITH_UNDEFINED */:
+          iItem.resolve(void 0);
+          break;
+        case "WITH_LAST" /* WITH_LAST */:
+          prevQItem2 == null ? void 0 : prevQItem2.then(iItem.resolve, iItem.reject);
+          break;
+        case "NEVER" /* NEVER */:
+          break;
+      }
+    }
+    if (!queue.size) sequence = 0;
+  };
   const handleRemaining = (currentId) => {
     const _prevQItem = prevQItem;
     prevQItem = null;
@@ -215,30 +234,19 @@ function deferred(options = {}) {
     } 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 */:
-          _prevQItem == null ? void 0 : _prevQItem.then(iItem.resolve, iItem.reject);
-          break;
-        case "NEVER" /* NEVER */:
-          break;
-      }
-    }
+    handleIgnore(items, _prevQItem);
   };
+  let prevSeq = 0;
   const executeItem = async (id, qItem) => {
-    if (!id || !(qItem == null ? void 0 : qItem.pending) || qItem.completed) return;
+    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) {
@@ -257,7 +265,6 @@ function deferred(options = {}) {
           break;
       }
     }
-    qItem.completed = true;
     handleRemaining(id);
   };
   const handleItem = isSequential ? executeItem : (throttle ? throttledCore : deferredCore)(
@@ -270,6 +277,7 @@ function deferred(options = {}) {
     const qItem = new PromisEBase_default();
     qItem.getPromise = isFn2(promise) ? promise : () => promise;
     qItem.started = false;
+    qItem.sequence = ++sequence;
     queue.set(id, qItem);
     if (!prevQItem || !isSequential) handleItem(id, qItem);
     return qItem;

package/package.json

@@ -43,5 +43,5 @@
 	"sideEffects": false,
 	"type": "module",
 	"types": "dist/index.d.ts",
-	"version": "1.1.0"
+	"version": "1.1.1"
 }