perfect-debounce 1.0.0 → 2.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (6) hide show
  1. package/README.md +69 -42
  2. package/dist/index.d.mts +49 -0
  3. package/dist/index.mjs +84 -52
  4. package/package.json +19 -22
  5. package/dist/index.cjs +0 -59
  6. package/dist/index.d.ts +0 -34
package/README.md CHANGED
@@ -1,40 +1,37 @@
1
1
  # perfect-debounce
2
2
 
3
- [![npm version][npm-version-src]][npm-version-href]
4
- [![npm downloads][npm-downloads-src]][npm-downloads-href]
5
- [![Github Actions][github-actions-src]][github-actions-href]
6
- [![Codecov][codecov-src]][codecov-href]
3
+ <!-- automd:badges color=yellow codecov bundlephobia packagephobia -->
7
4
 
8
- > An improved debounce function with Promise support.
5
+ [![npm version](https://img.shields.io/npm/v/perfect-debounce?color=yellow)](https://npmjs.com/package/perfect-debounce)
6
+ [![npm downloads](https://img.shields.io/npm/dm/perfect-debounce?color=yellow)](https://npm.chart.dev/perfect-debounce)
7
+ [![bundle size](https://img.shields.io/bundlephobia/minzip/perfect-debounce?color=yellow)](https://bundlephobia.com/package/perfect-debounce)
8
+ [![install size](https://badgen.net/packagephobia/install/perfect-debounce?color=yellow)](https://packagephobia.com/result?p=perfect-debounce)
9
+ [![codecov](https://img.shields.io/codecov/c/gh/unjs/perfect-debounce?color=yellow)](https://codecov.io/gh/unjs/perfect-debounce)
10
+
11
+ <!-- /automd -->
12
+
13
+ Improved debounce function with Promise support.
14
+
15
+ ## Features
9
16
 
10
17
  - Well tested debounce implementation
11
18
  - Native Promise support
12
19
  - Avoid duplicate calls while promise is being resolved
13
20
  - Configurable `trailing` and `leading` behavior
21
+ - Control methods
14
22
 
15
23
  ## Usage
16
24
 
17
25
  Install package:
18
26
 
19
27
  ```sh
20
- # npm
21
- npm install perfect-debounce
22
-
23
- # yarn
24
- yarn add perfect-debounce
25
-
26
- # pnpm
27
- pnpm add perfect-debounce
28
+ npx nypm i perfect-debounce
28
29
  ```
29
30
 
30
31
  Import:
31
32
 
32
33
  ```js
33
- // ESM
34
- import { debounce } from 'perfect-debounce'
35
-
36
- // CommonJS
37
- const { debounce } = require('perfect-debounce')
34
+ import { debounce } from "perfect-debounce";
38
35
  ```
39
36
 
40
37
  Debounce function:
@@ -42,25 +39,70 @@ Debounce function:
42
39
  ```js
43
40
  const debounced = debounce(async () => {
44
41
  // Some heavy stuff
45
- }, 25)
42
+ }, 25);
46
43
  ```
47
44
 
48
- When calling `debounced`, it will wait at least for `25ms` as configured before actually calling our function. This helps to avoid multiple calls.
45
+ When calling `debounced`, it will wait at least for `25ms` as configured before actually calling your function. This helps to avoid multiple calls.
46
+
47
+ ### Control Methods
48
+
49
+ The returned debounced function provides additional control methods:
50
+
51
+ - `debounced.cancel()`: Cancel any pending invocation that has not yet occurred.
52
+ - `await debounced.flush()`: Immediately invoke the pending function call (if any) and return its result.
53
+ - `debounced.isPending()`: Returns `true` if there is a pending invocation waiting to be called, otherwise `false`.
54
+
55
+ ```js
56
+ debounced.cancel(); // Cancel any pending call
57
+ await debounced.flush(); // Immediately invoke pending call (if any)
58
+ debounced.isPending(); // Returns true if a call is pending
59
+ ```
60
+
61
+ ### Example
62
+
63
+ ```js
64
+ const debounced = debounce(async (value) => {
65
+ // Some async work
66
+ return value * 2;
67
+ }, 100);
68
+
69
+ debounced(1);
70
+ debounced(2);
71
+ debounced(3);
72
+
73
+ // Check if a call is pending
74
+ console.log(debounced.isPending()); // true
75
+
76
+ // Immediately invoke the pending call
77
+ const result = await debounced.flush();
78
+ console.log(result); // 6
79
+
80
+ // Cancel any further pending calls
81
+ debounced.cancel();
82
+ ```
49
83
 
50
84
  To avoid initial wait, we can set `leading: true` option. It will cause function to be immediately called if there is no other call:
51
85
 
52
86
  ```js
53
- const debounced = debounce(async () => {
54
- // Some heavy stuff
55
- }, 25, { leading: true })
87
+ const debounced = debounce(
88
+ async () => {
89
+ // Some heavy stuff
90
+ },
91
+ 25,
92
+ { leading: true },
93
+ );
56
94
  ```
57
95
 
58
96
  If executing async function takes longer than debounce value, duplicate calls will be still prevented a last call will happen. To disable this behavior, we can set `trailing: false` option:
59
97
 
60
98
  ```js
61
- const debounced = debounce(async () => {
62
- // Some heavy stuff
63
- }, 25, { trailing: false })
99
+ const debounced = debounce(
100
+ async () => {
101
+ // Some heavy stuff
102
+ },
103
+ 25,
104
+ { trailing: false },
105
+ );
64
106
  ```
65
107
 
66
108
  ## 💻 Development
@@ -72,21 +114,6 @@ const debounced = debounce(async () => {
72
114
 
73
115
  ## License
74
116
 
75
- Made with 💛
76
-
77
117
  Based on [sindresorhus/p-debounce](https://github.com/sindresorhus/p-debounce).
78
118
 
79
- Published under [MIT License](./LICENSE).
80
-
81
- <!-- Badges -->
82
- [npm-version-src]: https://img.shields.io/npm/v/perfect-debounce?style=flat-square
83
- [npm-version-href]: https://npmjs.com/package/perfect-debounce
84
-
85
- [npm-downloads-src]: https://img.shields.io/npm/dm/perfect-debounce?style=flat-square
86
- [npm-downloads-href]: https://npmjs.com/package/perfect-debounce
87
-
88
- [github-actions-src]: https://img.shields.io/github/workflow/status/unjs/perfect-debounce/ci/main?style=flat-square
89
- [github-actions-href]: https://github.com/unjs/perfect-debounce/actions?query=workflow%3Aci
90
-
91
- [codecov-src]: https://img.shields.io/codecov/c/gh/unjs/perfect-debounce/main?style=flat-square
92
- [codecov-href]: https://codecov.io/gh/unjs/perfect-debounce
119
+ Made with 💛 Published under [MIT License](./LICENSE).
package/dist/index.d.mts ADDED
@@ -0,0 +1,49 @@
1
+ //#region src/index.d.ts
2
+ interface DebounceOptions {
3
+ /**
4
+ Call the `fn` on the [leading edge of the timeout](https://css-tricks.com/debouncing-throttling-explained-examples/#article-header-id-1).
5
+ Meaning immediately, instead of waiting for `wait` milliseconds.
6
+ @default false
7
+ */
8
+ readonly leading?: boolean;
9
+ /**
10
+ Call the `fn` on trailing edge with last used arguments. Result of call is from previous call.
11
+ @default true
12
+ */
13
+ readonly trailing?: boolean;
14
+ }
15
+ type DebouncedReturn<ArgumentsT extends unknown[], ReturnT> = ((...args: ArgumentsT) => Promise<ReturnT>) & {
16
+ /**
17
+ * Cancel pending function call
18
+ */
19
+ cancel: () => void;
20
+ /**
21
+ * Immediately invoke pending function call
22
+ */
23
+ flush: () => Promise<ReturnT> | undefined;
24
+ /**
25
+ * Get pending function call
26
+ */
27
+ isPending: () => boolean;
28
+ };
29
+ /**
30
+ Debounce functions
31
+ @param fn - Promise-returning/async function to debounce.
32
+ @param wait - Milliseconds to wait before calling `fn`. Default value is 25ms
33
+ @returns A function that delays calling `fn` until after `wait` milliseconds have elapsed since the last time it was called.
34
+ @example
35
+ ```
36
+ import { debounce } from 'perfect-debounce';
37
+ const expensiveCall = async input => input;
38
+ const debouncedFn = debounce(expensiveCall, 200);
39
+ for (const number of [1, 2, 3]) {
40
+ console.log(await debouncedFn(number));
41
+ }
42
+ //=> 1
43
+ //=> 2
44
+ //=> 3
45
+ ```
46
+ */
47
+ declare function debounce<ArgumentsT extends unknown[], ReturnT>(fn: (...args: ArgumentsT) => PromiseLike<ReturnT> | ReturnT, wait?: number, options?: DebounceOptions): DebouncedReturn<ArgumentsT, ReturnT>;
48
+ //#endregion
49
+ export { DebounceOptions, DebouncedReturn, debounce };
package/dist/index.mjs CHANGED
@@ -1,57 +1,89 @@
1
- const DEBOUNCE_DEFAULTS = {
2
- trailing: true
3
- };
1
+ //#region src/index.ts
2
+ const DEBOUNCE_DEFAULTS = { trailing: true };
3
+ /**
4
+ Debounce functions
5
+ @param fn - Promise-returning/async function to debounce.
6
+ @param wait - Milliseconds to wait before calling `fn`. Default value is 25ms
7
+ @returns A function that delays calling `fn` until after `wait` milliseconds have elapsed since the last time it was called.
8
+ @example
9
+ ```
10
+ import { debounce } from 'perfect-debounce';
11
+ const expensiveCall = async input => input;
12
+ const debouncedFn = debounce(expensiveCall, 200);
13
+ for (const number of [1, 2, 3]) {
14
+ console.log(await debouncedFn(number));
15
+ }
16
+ //=> 1
17
+ //=> 2
18
+ //=> 3
19
+ ```
20
+ */
4
21
  function debounce(fn, wait = 25, options = {}) {
5
- options = { ...DEBOUNCE_DEFAULTS, ...options };
6
- if (!Number.isFinite(wait)) {
7
- throw new TypeError("Expected `wait` to be a finite number");
8
- }
9
- let leadingValue;
10
- let timeout;
11
- let resolveList = [];
12
- let currentPromise;
13
- let trailingArgs;
14
- const applyFn = (_this, args) => {
15
- currentPromise = _applyPromised(fn, _this, args);
16
- currentPromise.finally(() => {
17
- currentPromise = null;
18
- if (options.trailing && trailingArgs && !timeout) {
19
- const promise = applyFn(_this, trailingArgs);
20
- trailingArgs = null;
21
- return promise;
22
- }
23
- });
24
- return currentPromise;
25
- };
26
- return function(...args) {
27
- if (currentPromise) {
28
- if (options.trailing) {
29
- trailingArgs = args;
30
- }
31
- return currentPromise;
32
- }
33
- return new Promise((resolve) => {
34
- const shouldCallNow = !timeout && options.leading;
35
- clearTimeout(timeout);
36
- timeout = setTimeout(() => {
37
- timeout = null;
38
- const promise = options.leading ? leadingValue : applyFn(this, args);
39
- for (const _resolve of resolveList) {
40
- _resolve(promise);
41
- }
42
- resolveList = [];
43
- }, wait);
44
- if (shouldCallNow) {
45
- leadingValue = applyFn(this, args);
46
- resolve(leadingValue);
47
- } else {
48
- resolveList.push(resolve);
49
- }
50
- });
51
- };
22
+ options = {
23
+ ...DEBOUNCE_DEFAULTS,
24
+ ...options
25
+ };
26
+ if (!Number.isFinite(wait)) throw new TypeError("Expected `wait` to be a finite number");
27
+ let leadingValue;
28
+ let timeout;
29
+ let resolveList = [];
30
+ let currentPromise;
31
+ let trailingArgs;
32
+ const applyFn = (_this, args) => {
33
+ currentPromise = _applyPromised(fn, _this, args);
34
+ currentPromise.finally(() => {
35
+ currentPromise = null;
36
+ if (options.trailing && trailingArgs && !timeout) {
37
+ const promise = applyFn(_this, trailingArgs);
38
+ trailingArgs = null;
39
+ return promise;
40
+ }
41
+ });
42
+ return currentPromise;
43
+ };
44
+ const debounced = function(...args) {
45
+ if (options.trailing) trailingArgs = args;
46
+ if (currentPromise) return currentPromise;
47
+ return new Promise((resolve) => {
48
+ const shouldCallNow = !timeout && options.leading;
49
+ clearTimeout(timeout);
50
+ timeout = setTimeout(() => {
51
+ timeout = null;
52
+ const promise = options.leading ? leadingValue : applyFn(this, args);
53
+ trailingArgs = null;
54
+ for (const _resolve of resolveList) _resolve(promise);
55
+ resolveList = [];
56
+ }, wait);
57
+ if (shouldCallNow) {
58
+ leadingValue = applyFn(this, args);
59
+ resolve(leadingValue);
60
+ } else resolveList.push(resolve);
61
+ });
62
+ };
63
+ const _clearTimeout = (timer) => {
64
+ if (timer) {
65
+ clearTimeout(timer);
66
+ timeout = null;
67
+ }
68
+ };
69
+ debounced.isPending = () => !!timeout;
70
+ debounced.cancel = () => {
71
+ _clearTimeout(timeout);
72
+ resolveList = [];
73
+ trailingArgs = null;
74
+ };
75
+ debounced.flush = () => {
76
+ _clearTimeout(timeout);
77
+ if (!trailingArgs || currentPromise) return;
78
+ const args = trailingArgs;
79
+ trailingArgs = null;
80
+ return applyFn(this, args);
81
+ };
82
+ return debounced;
52
83
  }
53
84
  async function _applyPromised(fn, _this, args) {
54
- return await fn.apply(_this, args);
85
+ return await fn.apply(_this, args);
55
86
  }
56
87
 
57
- export { debounce };
88
+ //#endregion
89
+ export { debounce };
package/package.json CHANGED
@@ -1,44 +1,41 @@
1
1
  {
2
2
  "name": "perfect-debounce",
3
- "version": "1.0.0",
3
+ "version": "2.1.0",
4
4
  "description": "",
5
5
  "repository": "unjs/perfect-debounce",
6
6
  "license": "MIT",
7
7
  "sideEffects": false,
8
8
  "type": "module",
9
9
  "exports": {
10
- ".": {
11
- "types": "./dist/index.d.ts",
12
- "import": "./dist/index.mjs",
13
- "require": "./dist/index.cjs"
14
- }
10
+ ".": "./dist/index.mjs"
15
11
  },
16
- "main": "./dist/index.cjs",
12
+ "main": "./dist/index.mjs",
17
13
  "module": "./dist/index.mjs",
18
- "types": "./dist/index.d.ts",
14
+ "types": "./dist/index.d.mts",
19
15
  "files": [
20
16
  "dist"
21
17
  ],
22
18
  "scripts": {
23
- "build": "unbuild",
19
+ "build": "obuild",
24
20
  "dev": "vitest dev",
25
- "lint": "eslint --ext .ts,.js,.mjs,.cjs . && prettier --check src test",
26
- "lint:fix": "eslint --ext .ts,.js,.mjs,.cjs . --fix && prettier -w src test",
21
+ "lint": "eslint . && prettier --check src test",
22
+ "lint:fix": "eslint . --fix && prettier -w src test",
27
23
  "release": "pnpm test && pnpm build && changelogen --release --push && npm publish",
28
24
  "test": "vitest run --coverage"
29
25
  },
30
26
  "devDependencies": {
31
- "@types/node": "^18.16.3",
32
- "@vitest/coverage-c8": "^0.31.0",
33
- "changelogen": "^0.5.3",
34
- "eslint": "^8.39.0",
35
- "eslint-config-unjs": "^0.1.0",
27
+ "@types/node": "^25.0.10",
28
+ "@vitest/coverage-v8": "^4.0.17",
29
+ "automd": "^0.4.2",
30
+ "changelogen": "^0.6.2",
31
+ "eslint": "^9.39.2",
32
+ "eslint-config-unjs": "^0.6.2",
36
33
  "in-range": "^3.0.0",
37
- "prettier": "^2.8.8",
34
+ "obuild": "^0.4.18",
35
+ "prettier": "^3.8.1",
38
36
  "time-span": "^5.1.0",
39
- "typescript": "^5.0.4",
40
- "unbuild": "^1.2.1",
41
- "vitest": "^0.31.0"
37
+ "typescript": "^5.9.3",
38
+ "vitest": "^4.0.17"
42
39
  },
43
- "packageManager": "pnpm@8.4.0"
44
- }
40
+ "packageManager": "pnpm@10.28.1"
41
+ }
package/dist/index.cjs DELETED
@@ -1,59 +0,0 @@
1
- 'use strict';
2
-
3
- const DEBOUNCE_DEFAULTS = {
4
- trailing: true
5
- };
6
- function debounce(fn, wait = 25, options = {}) {
7
- options = { ...DEBOUNCE_DEFAULTS, ...options };
8
- if (!Number.isFinite(wait)) {
9
- throw new TypeError("Expected `wait` to be a finite number");
10
- }
11
- let leadingValue;
12
- let timeout;
13
- let resolveList = [];
14
- let currentPromise;
15
- let trailingArgs;
16
- const applyFn = (_this, args) => {
17
- currentPromise = _applyPromised(fn, _this, args);
18
- currentPromise.finally(() => {
19
- currentPromise = null;
20
- if (options.trailing && trailingArgs && !timeout) {
21
- const promise = applyFn(_this, trailingArgs);
22
- trailingArgs = null;
23
- return promise;
24
- }
25
- });
26
- return currentPromise;
27
- };
28
- return function(...args) {
29
- if (currentPromise) {
30
- if (options.trailing) {
31
- trailingArgs = args;
32
- }
33
- return currentPromise;
34
- }
35
- return new Promise((resolve) => {
36
- const shouldCallNow = !timeout && options.leading;
37
- clearTimeout(timeout);
38
- timeout = setTimeout(() => {
39
- timeout = null;
40
- const promise = options.leading ? leadingValue : applyFn(this, args);
41
- for (const _resolve of resolveList) {
42
- _resolve(promise);
43
- }
44
- resolveList = [];
45
- }, wait);
46
- if (shouldCallNow) {
47
- leadingValue = applyFn(this, args);
48
- resolve(leadingValue);
49
- } else {
50
- resolveList.push(resolve);
51
- }
52
- });
53
- };
54
- }
55
- async function _applyPromised(fn, _this, args) {
56
- return await fn.apply(_this, args);
57
- }
58
-
59
- exports.debounce = debounce;
package/dist/index.d.ts DELETED
@@ -1,34 +0,0 @@
1
- interface DebounceOptions {
2
- /**
3
- Call the `fn` on the [leading edge of the timeout](https://css-tricks.com/debouncing-throttling-explained-examples/#article-header-id-1).
4
- Meaning immediately, instead of waiting for `wait` milliseconds.
5
- @default false
6
- */
7
- readonly leading?: boolean;
8
- /**
9
- Call the `fn` on trailing edge with last used arguments. Result of call is from previous call.
10
- @default false
11
- */
12
- readonly trailing?: boolean;
13
- }
14
- /**
15
- Debounce functions
16
- @param fn - Promise-returning/async function to debounce.
17
- @param wait - Milliseconds to wait before calling `fn`. Default value is 25ms
18
- @returns A function that delays calling `fn` until after `wait` milliseconds have elapsed since the last time it was called.
19
- @example
20
- ```
21
- import { debounce } from 'perfect-debounce';
22
- const expensiveCall = async input => input;
23
- const debouncedFn = debounce(expensiveCall, 200);
24
- for (const number of [1, 2, 3]) {
25
- console.log(await debouncedFn(number));
26
- }
27
- //=> 3
28
- //=> 3
29
- //=> 3
30
- ```
31
- */
32
- declare function debounce<ArgumentsT extends unknown[], ReturnT>(fn: (...args: ArgumentsT) => PromiseLike<ReturnT> | ReturnT, wait?: number, options?: DebounceOptions): (...args: ArgumentsT) => Promise<ReturnT>;
33
-
34
- export { DebounceOptions, debounce };