@superutils/promise 1.1.3 → 1.1.5

package/dist/index.d.ts

@@ -81,17 +81,24 @@ type PromiseParams<T = unknown> = ConstructorParameters<typeof Promise<T>>;
 type DeferredAsyncCallback<TArgs extends unknown[] | [] = []> = <TResult = unknown>(promise: Promise<TResult> | ((...args: TArgs) => Promise<TResult>)) => IPromisE<TResult>;
 type DeferredAsyncGetPromise<T> = <TResult = T>() => Promise<TResult>;
 /** Default options used by `PromisE.deferred` and related functions */
-type DeferredAsyncDefaults = Pick<Required<DeferredAsyncOptions>, 'delayMs' | 'resolveError' | 'resolveIgnored'>;
+type DeferredAsyncDefaults<ThisArg = unknown, Delay = unknown> = Pick<Required<DeferredAsyncOptions<ThisArg, Delay>>, 'delayMs' | 'resolveError' | 'resolveIgnored'>;
 /** Options for `PromisE.deferred` and other related functions */
-type DeferredAsyncOptions<ThisArg = unknown, DelayMs extends number = number> = {
+type DeferredAsyncOptions<ThisArg = unknown, Delay = unknown> = {
     /**
      * Delay in milliseconds, used for `debounce` and `throttle` modes. Use `0` for sequential execution.
      *
      * Use `0` to disable debounce/throttle and execute all operations sequentially.
      *
-     * Default: `100` (or what is set in `PromisE.deferred.defaults.delayMs`)
+     * Default: `100` (or whatever is set in `PromisE.deferred.defaults.delayMs`)
+     */
+    delayMs?: 0 | PositiveNumber<Delay>;
+    /**
+     * Whether to ignore (based on `resolveIgnored` settings) stale promises.
+     * In debouce/throttle mode, when an older promise is resolved after a newly resolved promise,
+     * the older one is considered stale.
+     *
+     * Default: `false`
      */
-    delayMs?: 0 | PositiveNumber<DelayMs>;
     ignoreStale?: boolean;
     /** Callback invoked whenever promise/function throws error */
     onError?: (this: ThisArg, err: unknown) => ValueOrPromise<unknown>;
@@ -121,14 +128,15 @@ type DeferredAsyncOptions<ThisArg = unknown, DelayMs extends number = number> =
     /** The value to be used as "thisArg" whenever any of the callbacks are invoked */
     thisArg?: ThisArg;
 } & (({
-    /** Throttle duration in milliseconds */
-    delayMs: PositiveNumber<DelayMs>;
+    delayMs: PositiveNumber<Delay>;
     throttle: true;
 } & Pick<ThrottleOptions, 'trailing'>) | ({
-    /** Debounce/deferred duration in milliseconds */
-    delayMs?: PositiveNumber<DelayMs>;
+    delayMs?: PositiveNumber<Delay>;
+    throttle?: false;
+} & Pick<DeferredOptions, 'leading'>) | {
+    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 */
@@ -354,34 +362,51 @@ type TimeoutOptions<Func extends string = 'all'> = {
  * - debounced: when `delayMs > 0` and `throttle = false`
  * - throttled: when `delayMs > 0` and `throttle = true`
  *
- *
- * @example Explanation & example usage:
+ * @example Debounce calls
  * ```typescript
- * const example = 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)
- *     // delay 2 seconds and invoke df() again
- *     setTimeout(() => {
- *         df(() => PromisE.delay(200)).then(console.log)
- *     }, 2000)
+ * 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
+ * ```
  *
- * // Without throttle
- * example(false)
- * // `1000` and `200` will be printed in the console
+ * @example Throttle calls
+ * ```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)
+ * }
  *
- * // with throttle
- * example(true)
- * // `5000` and `200` will be printed in the console
+ * example({ ignoreStale: true, throttle: true })
+ * // `200` will be printed in the console
  *
- * // with throttle with strict mode
- * example(true)
- * // `5000` will be printed in the console
+ * example({ ignoreStale: false, throttle: true })
+ * // `200` and `5000` will be printed in the console
  * ```
  */
-declare function deferred<T, ThisArg = unknown, Delay extends number = number>(options?: DeferredAsyncOptions<ThisArg, Delay>): DeferredAsyncCallback;
+declare function deferred<T = unknown, ThisArg = unknown, Delay = unknown>(options?: DeferredAsyncOptions<ThisArg, Delay>): DeferredAsyncCallback;
 declare namespace deferred {
     var defaults: {
         /**
@@ -429,7 +454,7 @@ declare namespace deferred {
  * // 200, 600, 1100
  * ```
  */
-declare function deferredCallback<TDefault, ThisArg, Delay extends number = number, CbArgs extends unknown[] = unknown[]>(callback: (...args: CbArgs) => TDefault | Promise<TDefault>, options?: DeferredAsyncOptions<ThisArg, Delay>): <TResult = TDefault>(...args: CbArgs) => IPromisE<TResult>;
+declare function deferredCallback<TDefault = unknown, ThisArg = unknown, Delay = unknown, CbArgs extends unknown[] = unknown[]>(callback: (...args: CbArgs) => TDefault | Promise<TDefault>, options?: DeferredAsyncOptions<ThisArg, Delay>): <TResult = TDefault>(...args: CbArgs) => IPromisE<TResult>;
 
 /**
  * Creates a promise that completes after given delay/duration.
@@ -444,16 +469,14 @@ declare function deferredCallback<TDefault, ThisArg, Delay extends number = numb
  * Default: `delayMs` when resolved or timed out error when rejected
  * @param asRejected (optional) if `true`, will reject the promise after the delay.
  *
- * @returns a promise
+ * @returns promise
  *
- * @example Delay before continuing execution
+ * @example Create a  promise that resolves after specified delay.
  * ```typescript
  * import PromisE from '@superutils/promise'
  *
- * 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')
+ * // Resolves after 1 second delay
+ * PromisE.delay(1000).then(console.log)
  * ```
  *
  * @example Execute a function after delay.
@@ -463,6 +486,19 @@ declare function deferredCallback<TDefault, ThisArg, Delay extends number = numb
  *
  * PromisE.delay(1000, () => console.log('Prints after 1 second delay'))
  * ```
+ *
+ * @example Delay before continuing execution
+ * ```typescript
+ * import PromisE from '@superutils/promise'
+ *
+ * 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')
+ * }
+ * func()
+ * ```
  */
 declare function delay<T = number, TReject extends boolean = boolean>(duration?: number, result?: T | (() => T), asRejected?: TReject): IPromisE_Delay<T>;
 declare namespace delay {

package/dist/index.js

@@ -227,11 +227,9 @@ function deferred(options = {}) {
     }
     let items = [...queue.entries()];
     if (throttle && options.trailing) {
-      items = items.slice(
-        0,
-        items.findIndex(([id]) => id === currentId)
-      );
-    } else if (!throttle && options.leading) {
+      const currentIndex = items.findIndex(([id]) => id === currentId);
+      items = items.slice(0, currentIndex);
+    } else if (!throttle) {
       items = items.slice(0, -1);
     }
     handleIgnore(items, _prevQItem);

package/package.json

@@ -4,7 +4,7 @@
 		"url": "https://github.com/alien45/superutils/issues"
 	},
 	"dependencies": {
-		"@superutils/core": "^1.1.1"
+		"@superutils/core": "^1.1.5"
 	},
 	"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.1.1"
+		"@superutils/core": "^1.1.5"
 	},
 	"publishConfig": {
 		"access": "public"
@@ -43,5 +43,5 @@
 	"sideEffects": false,
 	"type": "module",
 	"types": "dist/index.d.ts",
-	"version": "1.1.3"
+	"version": "1.1.5"
 }