@alwatr/debounce 1.0.0 → 1.0.1
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.
- package/CHANGELOG.md +6 -0
- package/README.md +21 -21
- package/dist/debounce.d.ts +8 -8
- package/dist/main.cjs +6 -6
- package/dist/main.cjs.map +2 -2
- package/dist/main.mjs +6 -6
- package/dist/main.mjs.map +2 -2
- package/dist/type.d.ts +4 -4
- package/dist/type.d.ts.map +1 -1
- package/package.json +2 -2
package/CHANGELOG.md
CHANGED
|
@@ -3,6 +3,12 @@
|
|
|
3
3
|
All notable changes to this project will be documented in this file.
|
|
4
4
|
See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
|
|
5
5
|
|
|
6
|
+
## [1.0.1](https://github.com/Alwatr/nanolib/compare/@alwatr/debounce@1.0.0...@alwatr/debounce@1.0.1) (2025-09-14)
|
|
7
|
+
|
|
8
|
+
### 🔨 Code Refactoring
|
|
9
|
+
|
|
10
|
+
* **debounce:** rename 'callback' to 'func' for consistency in API ([df7ede1](https://github.com/Alwatr/nanolib/commit/df7ede1a78109831cca22389bd2d69df2e0ae366))
|
|
11
|
+
|
|
6
12
|
## [1.0.0](https://github.com/Alwatr/nanolib/compare/@alwatr/debounce@1.0.0-rc.0...@alwatr/debounce@1.0.0) (2025-09-14)
|
|
7
13
|
|
|
8
14
|
### 🔨 Code Refactoring
|
package/README.md
CHANGED
|
@@ -73,7 +73,7 @@ import {createDebouncer} from '@alwatr/debounce';
|
|
|
73
73
|
// 1. Create a debouncer instance
|
|
74
74
|
const debouncer = createDebouncer({
|
|
75
75
|
// The function you want to debounce
|
|
76
|
-
|
|
76
|
+
func: (query: string) => {
|
|
77
77
|
console.log(`Searching for: ${query}`);
|
|
78
78
|
},
|
|
79
79
|
// The delay in milliseconds
|
|
@@ -100,13 +100,13 @@ A factory function that creates a new `Debouncer` instance. It's the recommended
|
|
|
100
100
|
|
|
101
101
|
This is the configuration object passed to `createDebouncer` or the `Debouncer` constructor.
|
|
102
102
|
|
|
103
|
-
| Property | Type | Description
|
|
104
|
-
| :------------ | :---------------------- |
|
|
105
|
-
| `
|
|
106
|
-
| `delay` | `number` | **(Required)** The debounce delay in milliseconds.
|
|
107
|
-
| `thisContext` | `ThisParameterType<F>` | The `this` context for the
|
|
108
|
-
| `leading` | `boolean` | If `true`, executes the function on the leading edge.
|
|
109
|
-
| `trailing` | `boolean` | If `true`, executes the function on the trailing edge.
|
|
103
|
+
| Property | Type | Description | Default |
|
|
104
|
+
| :------------ | :---------------------- | :------------------------------------------------------------------- | :---------- |
|
|
105
|
+
| `func` | `F extends AnyFunction` | **(Required)** The function to be debounced. | - |
|
|
106
|
+
| `delay` | `number` | **(Required)** The debounce delay in milliseconds. | - |
|
|
107
|
+
| `thisContext` | `ThisParameterType<F>` | The `this` context for the `func`. Essential when using class methods. | `undefined` |
|
|
108
|
+
| `leading` | `boolean` | If `true`, executes the function on the leading edge. | `false` |
|
|
109
|
+
| `trailing` | `boolean` | If `true`, executes the function on the trailing edge. | `true` |
|
|
110
110
|
|
|
111
111
|
### `Debouncer` Instance
|
|
112
112
|
|
|
@@ -120,7 +120,7 @@ An instance of the `Debouncer` class returned by `createDebouncer`.
|
|
|
120
120
|
#### Methods
|
|
121
121
|
|
|
122
122
|
- **`trigger(...args: Parameters<F>): void`**
|
|
123
|
-
Triggers the debounce timer. Each call resets the timer. The arguments passed here will be forwarded to the `
|
|
123
|
+
Triggers the debounce timer. Each call resets the timer. The arguments passed here will be forwarded to the `func` function.
|
|
124
124
|
|
|
125
125
|
- **`cancel(): void`**
|
|
126
126
|
Cancels any pending execution and clears internal state. This is crucial for preventing memory leaks.
|
|
@@ -143,7 +143,7 @@ In modern Single-Page Applications (SPAs) or any component-based architecture, c
|
|
|
143
143
|
```typescript
|
|
144
144
|
class MyComponent {
|
|
145
145
|
private debouncer = createDebouncer({
|
|
146
|
-
|
|
146
|
+
func: this.doSomething,
|
|
147
147
|
thisContext: this, // Bind `this` correctly!
|
|
148
148
|
delay: 500,
|
|
149
149
|
});
|
|
@@ -175,7 +175,7 @@ function MyComponent() {
|
|
|
175
175
|
const debouncedApiCall = useMemo(
|
|
176
176
|
() =>
|
|
177
177
|
createDebouncer({
|
|
178
|
-
|
|
178
|
+
func: (query) => fetch(`/api/search?q=${query}`),
|
|
179
179
|
delay: 300,
|
|
180
180
|
}),
|
|
181
181
|
[],
|
|
@@ -195,12 +195,12 @@ function MyComponent() {
|
|
|
195
195
|
|
|
196
196
|
### Using with `thisContext`
|
|
197
197
|
|
|
198
|
-
When your
|
|
198
|
+
When your `func` is a method on a class, `this` can lose its context. Pass the class instance to `thisContext` to ensure it's bound correctly.
|
|
199
199
|
|
|
200
200
|
```typescript
|
|
201
201
|
class ApiService {
|
|
202
202
|
private debouncer = createDebouncer({
|
|
203
|
-
|
|
203
|
+
func: this.sendRequest,
|
|
204
204
|
thisContext: this, // Ensures `this` inside `sendRequest` is `ApiService`
|
|
205
205
|
delay: 500,
|
|
206
206
|
});
|
|
@@ -309,7 +309,7 @@ import {createDebouncer} from '@alwatr/debounce';
|
|
|
309
309
|
// ۱. یک نمونه دیبانسر بسازید
|
|
310
310
|
const debouncer = createDebouncer({
|
|
311
311
|
// تابعی که میخواهید دیبانس کنید
|
|
312
|
-
|
|
312
|
+
func: (query: string) => {
|
|
313
313
|
console.log(`در حال جستجو برای: ${query}`);
|
|
314
314
|
},
|
|
315
315
|
// تأخیر بر حسب میلیثانیه
|
|
@@ -338,9 +338,9 @@ debouncer.trigger('علی');
|
|
|
338
338
|
|
|
339
339
|
| ویژگی | نوع | توضیحات | پیشفرض |
|
|
340
340
|
| :------------ | :---------------------- | :-------------------------------------------------------------------- | :---------- |
|
|
341
|
-
| `
|
|
341
|
+
| `func` | `F extends AnyFunction` | **(الزامی)** تابعی که باید دیبانس شود. | - |
|
|
342
342
|
| `delay` | `number` | **(الزامی)** تأخیر دیبانس بر حسب میلیثانیه. | - |
|
|
343
|
-
| `thisContext` | `ThisParameterType<F>` | کانتکست `this` برای
|
|
343
|
+
| `thisContext` | `ThisParameterType<F>` | کانتکست `this` برای `func`. هنگام استفاده از متدهای کلاس ضروری است. | `undefined` |
|
|
344
344
|
| `leading` | `boolean` | اگر `true` باشد، تابع در لبه بالارونده (leading edge) اجرا میشود. | `false` |
|
|
345
345
|
| `trailing` | `boolean` | اگر `true` باشد، تابع در لبه پایینرونده (trailing edge) اجرا میشود. | `true` |
|
|
346
346
|
|
|
@@ -356,7 +356,7 @@ debouncer.trigger('علی');
|
|
|
356
356
|
#### متدها
|
|
357
357
|
|
|
358
358
|
- **`trigger(...args: Parameters<F>): void`**
|
|
359
|
-
تایمر دیبانس را فعال میکند. هر فراخوانی، تایمر را ریست میکند. آرگومانهای پاس داده شده به این متد، به تابع `
|
|
359
|
+
تایمر دیبانس را فعال میکند. هر فراخوانی، تایمر را ریست میکند. آرگومانهای پاس داده شده به این متد، به تابع `func` ارسال میشوند.
|
|
360
360
|
|
|
361
361
|
- **`cancel(): void`**
|
|
362
362
|
هرگونه اجرای در حال انتظار را لغو کرده و وضعیت داخلی را پاک میکند. این متد برای جلوگیری از نشت حافظه بسیار حیاتی است.
|
|
@@ -379,7 +379,7 @@ debouncer.trigger('علی');
|
|
|
379
379
|
```typescript
|
|
380
380
|
class MyComponent {
|
|
381
381
|
private debouncer = createDebouncer({
|
|
382
|
-
|
|
382
|
+
func: this.doSomething,
|
|
383
383
|
thisContext: this, // `this` را به درستی متصل کنید!
|
|
384
384
|
delay: 500,
|
|
385
385
|
});
|
|
@@ -411,7 +411,7 @@ function MyComponent() {
|
|
|
411
411
|
const debouncedApiCall = useMemo(
|
|
412
412
|
() =>
|
|
413
413
|
createDebouncer({
|
|
414
|
-
|
|
414
|
+
func: (query) => fetch(`/api/search?q=${query}`),
|
|
415
415
|
delay: 300,
|
|
416
416
|
}),
|
|
417
417
|
[],
|
|
@@ -431,12 +431,12 @@ function MyComponent() {
|
|
|
431
431
|
|
|
432
432
|
### استفاده با `thisContext`
|
|
433
433
|
|
|
434
|
-
زمانی که `
|
|
434
|
+
زمانی که `func` شما یک متد از یک کلاس است، `this` ممکن است کانتکست خود را از دست بدهد. برای اطمینان از اتصال صحیح، نمونه کلاس را به `thisContext` پاس دهید.
|
|
435
435
|
|
|
436
436
|
```typescript
|
|
437
437
|
class ApiService {
|
|
438
438
|
private debouncer = createDebouncer({
|
|
439
|
-
|
|
439
|
+
func: this.sendRequest,
|
|
440
440
|
thisContext: this, // تضمین میکند که `this` در داخل `sendRequest` همان `ApiService` است
|
|
441
441
|
delay: 500,
|
|
442
442
|
});
|
package/dist/debounce.d.ts
CHANGED
|
@@ -9,7 +9,7 @@ import type { DebouncerConfig } from './type.ts';
|
|
|
9
9
|
* @example
|
|
10
10
|
* ```typescript
|
|
11
11
|
* const debouncer = new Debouncer({
|
|
12
|
-
*
|
|
12
|
+
* func: (text: string) => console.log('Searching:', text),
|
|
13
13
|
* delay: 300,
|
|
14
14
|
* leading: false,
|
|
15
15
|
* trailing: true,
|
|
@@ -21,7 +21,7 @@ import type { DebouncerConfig } from './type.ts';
|
|
|
21
21
|
*
|
|
22
22
|
* // Advanced: With leading edge
|
|
23
23
|
* const leadingDebouncer = new Debouncer({
|
|
24
|
-
*
|
|
24
|
+
* func: () => console.log('Immediate and delayed'),
|
|
25
25
|
* delay: 500,
|
|
26
26
|
* leading: true,
|
|
27
27
|
* trailing: true,
|
|
@@ -41,12 +41,12 @@ export declare class Debouncer<F extends AnyFunction> {
|
|
|
41
41
|
get isPending(): boolean;
|
|
42
42
|
/**
|
|
43
43
|
* Triggers the debounced function with the stored `thisContext`.
|
|
44
|
-
* @param args The arguments to pass to the
|
|
44
|
+
* @param args The arguments to pass to the `func`.
|
|
45
45
|
*
|
|
46
46
|
* @example
|
|
47
47
|
* ```typescript
|
|
48
48
|
* const debouncer = new Debouncer({
|
|
49
|
-
*
|
|
49
|
+
* func: (value: number) => console.log('Value:', value),
|
|
50
50
|
* delay: 500,
|
|
51
51
|
* });
|
|
52
52
|
* debouncer.trigger(42); // Logs after 500ms if not triggered again
|
|
@@ -64,7 +64,7 @@ export declare class Debouncer<F extends AnyFunction> {
|
|
|
64
64
|
* @example
|
|
65
65
|
* ```typescript
|
|
66
66
|
* const debouncer = new Debouncer({
|
|
67
|
-
*
|
|
67
|
+
* func: () => console.log('Executed'),
|
|
68
68
|
* delay: 1000,
|
|
69
69
|
* });
|
|
70
70
|
* debouncer.trigger();
|
|
@@ -85,7 +85,7 @@ export declare class Debouncer<F extends AnyFunction> {
|
|
|
85
85
|
* @example
|
|
86
86
|
* ```typescript
|
|
87
87
|
* const debouncer = new Debouncer({
|
|
88
|
-
*
|
|
88
|
+
* func: () => console.log('Flushed'),
|
|
89
89
|
* delay: 1000,
|
|
90
90
|
* });
|
|
91
91
|
* debouncer.trigger();
|
|
@@ -109,7 +109,7 @@ export declare class Debouncer<F extends AnyFunction> {
|
|
|
109
109
|
* @example
|
|
110
110
|
* ```typescript
|
|
111
111
|
* const debouncer = createDebouncer({
|
|
112
|
-
*
|
|
112
|
+
* func: (text: string) => console.log('Searching:', text),
|
|
113
113
|
* delay: 300,
|
|
114
114
|
* leading: false,
|
|
115
115
|
* trailing: true,
|
|
@@ -122,7 +122,7 @@ export declare class Debouncer<F extends AnyFunction> {
|
|
|
122
122
|
* // With custom thisContext
|
|
123
123
|
* const obj = { log: (msg: string) => console.log('Obj:', msg) };
|
|
124
124
|
* const debouncerWithContext = createDebouncer({
|
|
125
|
-
*
|
|
125
|
+
* func: obj.log,
|
|
126
126
|
* thisContext: obj,
|
|
127
127
|
* delay: 200,
|
|
128
128
|
* });
|
package/dist/main.cjs
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
/* @alwatr/debounce v1.0.
|
|
1
|
+
/* @alwatr/debounce v1.0.1 */
|
|
2
2
|
"use strict";
|
|
3
3
|
var __defProp = Object.defineProperty;
|
|
4
4
|
var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
|
|
@@ -41,12 +41,12 @@ var Debouncer = class {
|
|
|
41
41
|
}
|
|
42
42
|
/**
|
|
43
43
|
* Triggers the debounced function with the stored `thisContext`.
|
|
44
|
-
* @param args The arguments to pass to the
|
|
44
|
+
* @param args The arguments to pass to the `func`.
|
|
45
45
|
*
|
|
46
46
|
* @example
|
|
47
47
|
* ```typescript
|
|
48
48
|
* const debouncer = new Debouncer({
|
|
49
|
-
*
|
|
49
|
+
* func: (value: number) => console.log('Value:', value),
|
|
50
50
|
* delay: 500,
|
|
51
51
|
* });
|
|
52
52
|
* debouncer.trigger(42); // Logs after 500ms if not triggered again
|
|
@@ -79,7 +79,7 @@ var Debouncer = class {
|
|
|
79
79
|
* @example
|
|
80
80
|
* ```typescript
|
|
81
81
|
* const debouncer = new Debouncer({
|
|
82
|
-
*
|
|
82
|
+
* func: () => console.log('Executed'),
|
|
83
83
|
* delay: 1000,
|
|
84
84
|
* });
|
|
85
85
|
* debouncer.trigger();
|
|
@@ -108,7 +108,7 @@ var Debouncer = class {
|
|
|
108
108
|
* @example
|
|
109
109
|
* ```typescript
|
|
110
110
|
* const debouncer = new Debouncer({
|
|
111
|
-
*
|
|
111
|
+
* func: () => console.log('Flushed'),
|
|
112
112
|
* delay: 1000,
|
|
113
113
|
* });
|
|
114
114
|
* debouncer.trigger();
|
|
@@ -130,7 +130,7 @@ var Debouncer = class {
|
|
|
130
130
|
*/
|
|
131
131
|
invoke__() {
|
|
132
132
|
if (this.lastArgs__) {
|
|
133
|
-
this.config__.
|
|
133
|
+
this.config__.func.apply(this.config__.thisContext, this.lastArgs__);
|
|
134
134
|
}
|
|
135
135
|
}
|
|
136
136
|
};
|
package/dist/main.cjs.map
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"version": 3,
|
|
3
3
|
"sources": ["../src/main.ts", "../src/debounce.ts"],
|
|
4
|
-
"sourcesContent": ["export * from './debounce.js';\nexport type * from './type.js';\n", "import type {DebouncerConfig} from './type.ts';\n\n/**\n * A powerful and type-safe Debouncer class.\n * \n * It encapsulates the debouncing logic, state, and provides a rich control API.\n * Debouncing delays function execution until after a specified delay has passed since the last invocation.\n * Useful for optimizing performance in scenarios like search inputs, resize events, or API calls.\n * \n * @example\n * ```typescript\n * const debouncer = new Debouncer({\n *
|
|
5
|
-
"mappings": ";;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACgCO,IAAM,YAAN,MAAuC;AAAA,EAIrC,YAA6B,UAA8B;AAA9B;AAClC,SAAK,SAAS,aAAa;AAAA,EAC7B;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,IAAW,YAAqB;AAC9B,WAAO,KAAK,cAAc;AAAA,EAC5B;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAmBO,WAAW,MAA2B;AAC3C,SAAK,aAAa;AAClB,UAAM,aAAa,KAAK;AAExB,QAAI,YAAY;AACd,mBAAa,KAAK,SAAU;AAAA,IAC9B;AAEA,QAAI,KAAK,SAAS,YAAY,QAAQ,CAAC,YAAY;AACjD,WAAK,SAAS;AAAA,IAChB;AAEA,SAAK,YAAY,WAAW,MAAM;AAChC,UAAI,KAAK,SAAS,aAAa,QAAQ,YAAY;AACjD,aAAK,SAAS;AAAA,MAChB;AACA,WAAK,UAAU;AAAA,IACjB,GAAG,KAAK,SAAS,KAAK;AAAA,EACxB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAkBO,SAAe;AACpB,QAAI,KAAK,WAAW;AAClB,mBAAa,KAAK,SAAU;AAAA,IAC9B;AACA,SAAK,UAAU;AAAA,EACjB;AAAA;AAAA;AAAA;AAAA,EAKQ,YAAkB;AACxB,WAAO,KAAK;AACZ,WAAO,KAAK;AAAA,EACd;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAoBO,QAAc;AACnB,QAAI,KAAK,WAAW;AAClB,WAAK,OAAO;AACZ,WAAK,SAAS;AAAA,IAChB;AAAA,EACF;AAAA;AAAA;AAAA;AAAA,EAKQ,WAAiB;AACvB,QAAI,KAAK,YAAY;AAEnB,WAAK,SAAS,
|
|
4
|
+
"sourcesContent": ["export * from './debounce.js';\nexport type * from './type.js';\n", "import type {DebouncerConfig} from './type.ts';\n\n/**\n * A powerful and type-safe Debouncer class.\n * \n * It encapsulates the debouncing logic, state, and provides a rich control API.\n * Debouncing delays function execution until after a specified delay has passed since the last invocation.\n * Useful for optimizing performance in scenarios like search inputs, resize events, or API calls.\n * \n * @example\n * ```typescript\n * const debouncer = new Debouncer({\n * func: (text: string) => console.log('Searching:', text),\n * delay: 300,\n * leading: false,\n * trailing: true,\n * });\n * \n * // Debounce search input\n * debouncer.trigger('hello');\n * debouncer.trigger('hello world'); // Only 'hello world' will log after 300ms\n * \n * // Advanced: With leading edge\n * const leadingDebouncer = new Debouncer({\n * func: () => console.log('Immediate and delayed'),\n * delay: 500,\n * leading: true,\n * trailing: true,\n * });\n * leadingDebouncer.trigger(); // Logs immediately, then again after 500ms if not cancelled\n * ```\n */\nexport class Debouncer<F extends AnyFunction> {\n private timerId__?: number | NodeJS.Timeout;\n private lastArgs__?: Parameters<F>;\n\n public constructor(private readonly config__: DebouncerConfig<F>) {\n this.config__.trailing ??= true;\n }\n\n /**\n * Checks if there is a pending execution scheduled.\n * Returns true if a timer is active, indicating a debounced call is waiting.\n */\n public get isPending(): boolean {\n return this.timerId__ !== undefined;\n }\n\n /**\n * Triggers the debounced function with the stored `thisContext`.\n * @param args The arguments to pass to the `func`.\n * \n * @example\n * ```typescript\n * const debouncer = new Debouncer({\n * func: (value: number) => console.log('Value:', value),\n * delay: 500,\n * });\n * debouncer.trigger(42); // Logs after 500ms if not triggered again\n * \n * // Edge case: Rapid triggers only execute the last one\n * debouncer.trigger(1);\n * debouncer.trigger(2); // Only 2 will execute after delay\n * ```\n */\n public trigger(...args: Parameters<F>): void {\n this.lastArgs__ = args;\n const wasPending = this.isPending;\n\n if (wasPending) {\n clearTimeout(this.timerId__!);\n }\n\n if (this.config__.leading === true && !wasPending) {\n this.invoke__();\n }\n\n this.timerId__ = setTimeout(() => {\n if (this.config__.trailing === true && wasPending) {\n this.invoke__();\n }\n this.cleanup__();\n }, this.config__.delay);\n }\n\n /**\n * Cancels any pending debounced execution and cleans up internal state.\n * Useful for stopping execution when the operation is no longer needed (e.g., component unmount).\n * \n * @example\n * ```typescript\n * const debouncer = new Debouncer({\n * func: () => console.log('Executed'),\n * delay: 1000,\n * });\n * debouncer.trigger();\n * debouncer.cancel(); // Prevents execution\n * \n * // Note: After cancel, isPending becomes false\n * ```\n */\n public cancel(): void {\n if (this.isPending) {\n clearTimeout(this.timerId__!);\n }\n this.cleanup__();\n }\n\n /**\n * Cleans up internal state by deleting timer and arguments.\n */\n private cleanup__(): void {\n delete this.timerId__;\n delete this.lastArgs__;\n }\n\n /**\n * Immediately executes the pending function if one exists.\n * Bypasses the delay and cleans up state. If no pending call, does nothing.\n * \n * @example\n * ```typescript\n * const debouncer = new Debouncer({\n * func: () => console.log('Flushed'),\n * delay: 1000,\n * });\n * debouncer.trigger();\n * setTimeout(() => debouncer.flush(), 500); // Executes immediately\n * \n * // Edge case: Flush after cancel does nothing\n * debouncer.cancel();\n * debouncer.flush(); // No execution\n * ```\n */\n public flush(): void {\n if (this.isPending) {\n this.cancel();\n this.invoke__();\n }\n }\n\n /**\n * The core execution logic.\n */\n private invoke__(): void {\n if (this.lastArgs__) {\n // `thisContext` is now read directly from the stored config.\n this.config__.func.apply(this.config__.thisContext, this.lastArgs__);\n }\n }\n}\n\n/**\n * Factory function for creating a Debouncer instance for better type inference.\n * @param config Configuration for the debouncer.\n * \n * @example\n * ```typescript\n * const debouncer = createDebouncer({\n * func: (text: string) => console.log('Searching:', text),\n * delay: 300,\n * leading: false,\n * trailing: true,\n * });\n * \n * // Debounce search input\n * debouncer.trigger('hello');\n * debouncer.trigger('hello world'); // Only 'hello world' will log after 300ms\n * \n * // With custom thisContext\n * const obj = { log: (msg: string) => console.log('Obj:', msg) };\n * const debouncerWithContext = createDebouncer({\n * func: obj.log,\n * thisContext: obj,\n * delay: 200,\n * });\n * debouncerWithContext.trigger('test'); // Logs 'Obj: test'\n * ```\n */\nexport function createDebouncer<F extends AnyFunction>(config: DebouncerConfig<F>): Debouncer<F> {\n return new Debouncer(config);\n}\n"],
|
|
5
|
+
"mappings": ";;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACgCO,IAAM,YAAN,MAAuC;AAAA,EAIrC,YAA6B,UAA8B;AAA9B;AAClC,SAAK,SAAS,aAAa;AAAA,EAC7B;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,IAAW,YAAqB;AAC9B,WAAO,KAAK,cAAc;AAAA,EAC5B;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAmBO,WAAW,MAA2B;AAC3C,SAAK,aAAa;AAClB,UAAM,aAAa,KAAK;AAExB,QAAI,YAAY;AACd,mBAAa,KAAK,SAAU;AAAA,IAC9B;AAEA,QAAI,KAAK,SAAS,YAAY,QAAQ,CAAC,YAAY;AACjD,WAAK,SAAS;AAAA,IAChB;AAEA,SAAK,YAAY,WAAW,MAAM;AAChC,UAAI,KAAK,SAAS,aAAa,QAAQ,YAAY;AACjD,aAAK,SAAS;AAAA,MAChB;AACA,WAAK,UAAU;AAAA,IACjB,GAAG,KAAK,SAAS,KAAK;AAAA,EACxB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAkBO,SAAe;AACpB,QAAI,KAAK,WAAW;AAClB,mBAAa,KAAK,SAAU;AAAA,IAC9B;AACA,SAAK,UAAU;AAAA,EACjB;AAAA;AAAA;AAAA;AAAA,EAKQ,YAAkB;AACxB,WAAO,KAAK;AACZ,WAAO,KAAK;AAAA,EACd;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAoBO,QAAc;AACnB,QAAI,KAAK,WAAW;AAClB,WAAK,OAAO;AACZ,WAAK,SAAS;AAAA,IAChB;AAAA,EACF;AAAA;AAAA;AAAA;AAAA,EAKQ,WAAiB;AACvB,QAAI,KAAK,YAAY;AAEnB,WAAK,SAAS,KAAK,MAAM,KAAK,SAAS,aAAa,KAAK,UAAU;AAAA,IACrE;AAAA,EACF;AACF;AA6BO,SAAS,gBAAuC,QAA0C;AAC/F,SAAO,IAAI,UAAU,MAAM;AAC7B;",
|
|
6
6
|
"names": []
|
|
7
7
|
}
|
package/dist/main.mjs
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
/* @alwatr/debounce v1.0.
|
|
1
|
+
/* @alwatr/debounce v1.0.1 */
|
|
2
2
|
|
|
3
3
|
// src/debounce.ts
|
|
4
4
|
var Debouncer = class {
|
|
@@ -15,12 +15,12 @@ var Debouncer = class {
|
|
|
15
15
|
}
|
|
16
16
|
/**
|
|
17
17
|
* Triggers the debounced function with the stored `thisContext`.
|
|
18
|
-
* @param args The arguments to pass to the
|
|
18
|
+
* @param args The arguments to pass to the `func`.
|
|
19
19
|
*
|
|
20
20
|
* @example
|
|
21
21
|
* ```typescript
|
|
22
22
|
* const debouncer = new Debouncer({
|
|
23
|
-
*
|
|
23
|
+
* func: (value: number) => console.log('Value:', value),
|
|
24
24
|
* delay: 500,
|
|
25
25
|
* });
|
|
26
26
|
* debouncer.trigger(42); // Logs after 500ms if not triggered again
|
|
@@ -53,7 +53,7 @@ var Debouncer = class {
|
|
|
53
53
|
* @example
|
|
54
54
|
* ```typescript
|
|
55
55
|
* const debouncer = new Debouncer({
|
|
56
|
-
*
|
|
56
|
+
* func: () => console.log('Executed'),
|
|
57
57
|
* delay: 1000,
|
|
58
58
|
* });
|
|
59
59
|
* debouncer.trigger();
|
|
@@ -82,7 +82,7 @@ var Debouncer = class {
|
|
|
82
82
|
* @example
|
|
83
83
|
* ```typescript
|
|
84
84
|
* const debouncer = new Debouncer({
|
|
85
|
-
*
|
|
85
|
+
* func: () => console.log('Flushed'),
|
|
86
86
|
* delay: 1000,
|
|
87
87
|
* });
|
|
88
88
|
* debouncer.trigger();
|
|
@@ -104,7 +104,7 @@ var Debouncer = class {
|
|
|
104
104
|
*/
|
|
105
105
|
invoke__() {
|
|
106
106
|
if (this.lastArgs__) {
|
|
107
|
-
this.config__.
|
|
107
|
+
this.config__.func.apply(this.config__.thisContext, this.lastArgs__);
|
|
108
108
|
}
|
|
109
109
|
}
|
|
110
110
|
};
|
package/dist/main.mjs.map
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"version": 3,
|
|
3
3
|
"sources": ["../src/debounce.ts"],
|
|
4
|
-
"sourcesContent": ["import type {DebouncerConfig} from './type.ts';\n\n/**\n * A powerful and type-safe Debouncer class.\n * \n * It encapsulates the debouncing logic, state, and provides a rich control API.\n * Debouncing delays function execution until after a specified delay has passed since the last invocation.\n * Useful for optimizing performance in scenarios like search inputs, resize events, or API calls.\n * \n * @example\n * ```typescript\n * const debouncer = new Debouncer({\n *
|
|
5
|
-
"mappings": ";;;AAgCO,IAAM,YAAN,MAAuC;AAAA,EAIrC,YAA6B,UAA8B;AAA9B;AAClC,SAAK,SAAS,aAAa;AAAA,EAC7B;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,IAAW,YAAqB;AAC9B,WAAO,KAAK,cAAc;AAAA,EAC5B;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAmBO,WAAW,MAA2B;AAC3C,SAAK,aAAa;AAClB,UAAM,aAAa,KAAK;AAExB,QAAI,YAAY;AACd,mBAAa,KAAK,SAAU;AAAA,IAC9B;AAEA,QAAI,KAAK,SAAS,YAAY,QAAQ,CAAC,YAAY;AACjD,WAAK,SAAS;AAAA,IAChB;AAEA,SAAK,YAAY,WAAW,MAAM;AAChC,UAAI,KAAK,SAAS,aAAa,QAAQ,YAAY;AACjD,aAAK,SAAS;AAAA,MAChB;AACA,WAAK,UAAU;AAAA,IACjB,GAAG,KAAK,SAAS,KAAK;AAAA,EACxB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAkBO,SAAe;AACpB,QAAI,KAAK,WAAW;AAClB,mBAAa,KAAK,SAAU;AAAA,IAC9B;AACA,SAAK,UAAU;AAAA,EACjB;AAAA;AAAA;AAAA;AAAA,EAKQ,YAAkB;AACxB,WAAO,KAAK;AACZ,WAAO,KAAK;AAAA,EACd;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAoBO,QAAc;AACnB,QAAI,KAAK,WAAW;AAClB,WAAK,OAAO;AACZ,WAAK,SAAS;AAAA,IAChB;AAAA,EACF;AAAA;AAAA;AAAA;AAAA,EAKQ,WAAiB;AACvB,QAAI,KAAK,YAAY;AAEnB,WAAK,SAAS,
|
|
4
|
+
"sourcesContent": ["import type {DebouncerConfig} from './type.ts';\n\n/**\n * A powerful and type-safe Debouncer class.\n * \n * It encapsulates the debouncing logic, state, and provides a rich control API.\n * Debouncing delays function execution until after a specified delay has passed since the last invocation.\n * Useful for optimizing performance in scenarios like search inputs, resize events, or API calls.\n * \n * @example\n * ```typescript\n * const debouncer = new Debouncer({\n * func: (text: string) => console.log('Searching:', text),\n * delay: 300,\n * leading: false,\n * trailing: true,\n * });\n * \n * // Debounce search input\n * debouncer.trigger('hello');\n * debouncer.trigger('hello world'); // Only 'hello world' will log after 300ms\n * \n * // Advanced: With leading edge\n * const leadingDebouncer = new Debouncer({\n * func: () => console.log('Immediate and delayed'),\n * delay: 500,\n * leading: true,\n * trailing: true,\n * });\n * leadingDebouncer.trigger(); // Logs immediately, then again after 500ms if not cancelled\n * ```\n */\nexport class Debouncer<F extends AnyFunction> {\n private timerId__?: number | NodeJS.Timeout;\n private lastArgs__?: Parameters<F>;\n\n public constructor(private readonly config__: DebouncerConfig<F>) {\n this.config__.trailing ??= true;\n }\n\n /**\n * Checks if there is a pending execution scheduled.\n * Returns true if a timer is active, indicating a debounced call is waiting.\n */\n public get isPending(): boolean {\n return this.timerId__ !== undefined;\n }\n\n /**\n * Triggers the debounced function with the stored `thisContext`.\n * @param args The arguments to pass to the `func`.\n * \n * @example\n * ```typescript\n * const debouncer = new Debouncer({\n * func: (value: number) => console.log('Value:', value),\n * delay: 500,\n * });\n * debouncer.trigger(42); // Logs after 500ms if not triggered again\n * \n * // Edge case: Rapid triggers only execute the last one\n * debouncer.trigger(1);\n * debouncer.trigger(2); // Only 2 will execute after delay\n * ```\n */\n public trigger(...args: Parameters<F>): void {\n this.lastArgs__ = args;\n const wasPending = this.isPending;\n\n if (wasPending) {\n clearTimeout(this.timerId__!);\n }\n\n if (this.config__.leading === true && !wasPending) {\n this.invoke__();\n }\n\n this.timerId__ = setTimeout(() => {\n if (this.config__.trailing === true && wasPending) {\n this.invoke__();\n }\n this.cleanup__();\n }, this.config__.delay);\n }\n\n /**\n * Cancels any pending debounced execution and cleans up internal state.\n * Useful for stopping execution when the operation is no longer needed (e.g., component unmount).\n * \n * @example\n * ```typescript\n * const debouncer = new Debouncer({\n * func: () => console.log('Executed'),\n * delay: 1000,\n * });\n * debouncer.trigger();\n * debouncer.cancel(); // Prevents execution\n * \n * // Note: After cancel, isPending becomes false\n * ```\n */\n public cancel(): void {\n if (this.isPending) {\n clearTimeout(this.timerId__!);\n }\n this.cleanup__();\n }\n\n /**\n * Cleans up internal state by deleting timer and arguments.\n */\n private cleanup__(): void {\n delete this.timerId__;\n delete this.lastArgs__;\n }\n\n /**\n * Immediately executes the pending function if one exists.\n * Bypasses the delay and cleans up state. If no pending call, does nothing.\n * \n * @example\n * ```typescript\n * const debouncer = new Debouncer({\n * func: () => console.log('Flushed'),\n * delay: 1000,\n * });\n * debouncer.trigger();\n * setTimeout(() => debouncer.flush(), 500); // Executes immediately\n * \n * // Edge case: Flush after cancel does nothing\n * debouncer.cancel();\n * debouncer.flush(); // No execution\n * ```\n */\n public flush(): void {\n if (this.isPending) {\n this.cancel();\n this.invoke__();\n }\n }\n\n /**\n * The core execution logic.\n */\n private invoke__(): void {\n if (this.lastArgs__) {\n // `thisContext` is now read directly from the stored config.\n this.config__.func.apply(this.config__.thisContext, this.lastArgs__);\n }\n }\n}\n\n/**\n * Factory function for creating a Debouncer instance for better type inference.\n * @param config Configuration for the debouncer.\n * \n * @example\n * ```typescript\n * const debouncer = createDebouncer({\n * func: (text: string) => console.log('Searching:', text),\n * delay: 300,\n * leading: false,\n * trailing: true,\n * });\n * \n * // Debounce search input\n * debouncer.trigger('hello');\n * debouncer.trigger('hello world'); // Only 'hello world' will log after 300ms\n * \n * // With custom thisContext\n * const obj = { log: (msg: string) => console.log('Obj:', msg) };\n * const debouncerWithContext = createDebouncer({\n * func: obj.log,\n * thisContext: obj,\n * delay: 200,\n * });\n * debouncerWithContext.trigger('test'); // Logs 'Obj: test'\n * ```\n */\nexport function createDebouncer<F extends AnyFunction>(config: DebouncerConfig<F>): Debouncer<F> {\n return new Debouncer(config);\n}\n"],
|
|
5
|
+
"mappings": ";;;AAgCO,IAAM,YAAN,MAAuC;AAAA,EAIrC,YAA6B,UAA8B;AAA9B;AAClC,SAAK,SAAS,aAAa;AAAA,EAC7B;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,IAAW,YAAqB;AAC9B,WAAO,KAAK,cAAc;AAAA,EAC5B;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAmBO,WAAW,MAA2B;AAC3C,SAAK,aAAa;AAClB,UAAM,aAAa,KAAK;AAExB,QAAI,YAAY;AACd,mBAAa,KAAK,SAAU;AAAA,IAC9B;AAEA,QAAI,KAAK,SAAS,YAAY,QAAQ,CAAC,YAAY;AACjD,WAAK,SAAS;AAAA,IAChB;AAEA,SAAK,YAAY,WAAW,MAAM;AAChC,UAAI,KAAK,SAAS,aAAa,QAAQ,YAAY;AACjD,aAAK,SAAS;AAAA,MAChB;AACA,WAAK,UAAU;AAAA,IACjB,GAAG,KAAK,SAAS,KAAK;AAAA,EACxB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAkBO,SAAe;AACpB,QAAI,KAAK,WAAW;AAClB,mBAAa,KAAK,SAAU;AAAA,IAC9B;AACA,SAAK,UAAU;AAAA,EACjB;AAAA;AAAA;AAAA;AAAA,EAKQ,YAAkB;AACxB,WAAO,KAAK;AACZ,WAAO,KAAK;AAAA,EACd;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAoBO,QAAc;AACnB,QAAI,KAAK,WAAW;AAClB,WAAK,OAAO;AACZ,WAAK,SAAS;AAAA,IAChB;AAAA,EACF;AAAA;AAAA;AAAA;AAAA,EAKQ,WAAiB;AACvB,QAAI,KAAK,YAAY;AAEnB,WAAK,SAAS,KAAK,MAAM,KAAK,SAAS,aAAa,KAAK,UAAU;AAAA,IACrE;AAAA,EACF;AACF;AA6BO,SAAS,gBAAuC,QAA0C;AAC/F,SAAO,IAAI,UAAU,MAAM;AAC7B;",
|
|
6
6
|
"names": []
|
|
7
7
|
}
|
package/dist/type.d.ts
CHANGED
|
@@ -5,7 +5,7 @@
|
|
|
5
5
|
* Key notes:
|
|
6
6
|
* - `leading` and `trailing` control execution timing: leading executes immediately on first trigger, trailing after delay.
|
|
7
7
|
* - If both are true, execution happens on first trigger and last trigger (after delay).
|
|
8
|
-
* - `thisContext` ensures the
|
|
8
|
+
* - `thisContext` ensures the `func` is bound to the correct `this` value, useful in class methods or event handlers.
|
|
9
9
|
* - `delay` must be a positive number.
|
|
10
10
|
*/
|
|
11
11
|
export interface DebouncerConfig<F extends AnyFunction> {
|
|
@@ -13,11 +13,11 @@ export interface DebouncerConfig<F extends AnyFunction> {
|
|
|
13
13
|
* The function to be executed after the delay.
|
|
14
14
|
* Can be any function type, with type safety enforced by generics.
|
|
15
15
|
*/
|
|
16
|
-
|
|
16
|
+
func: F;
|
|
17
17
|
/**
|
|
18
|
-
* The `this` context to be used when invoking the
|
|
18
|
+
* The `this` context to be used when invoking the func.
|
|
19
19
|
* If provided, it will be stored and used for all invocations.
|
|
20
|
-
* Omit if the
|
|
20
|
+
* Omit if the func doesn't rely on `this` or uses arrow functions.
|
|
21
21
|
*/
|
|
22
22
|
thisContext?: ThisParameterType<F>;
|
|
23
23
|
/**
|
package/dist/type.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"type.d.ts","sourceRoot":"","sources":["../src/type.ts"],"names":[],"mappings":"AAEA;;;;;;;;;GASG;AACH,MAAM,WAAW,eAAe,CAAC,CAAC,SAAS,WAAW;IACpD;;;OAGG;IACH,
|
|
1
|
+
{"version":3,"file":"type.d.ts","sourceRoot":"","sources":["../src/type.ts"],"names":[],"mappings":"AAEA;;;;;;;;;GASG;AACH,MAAM,WAAW,eAAe,CAAC,CAAC,SAAS,WAAW;IACpD;;;OAGG;IACH,IAAI,EAAE,CAAC,CAAC;IAER;;;;OAIG;IACH,WAAW,CAAC,EAAE,iBAAiB,CAAC,CAAC,CAAC,CAAC;IAEnC;;;OAGG;IACH,KAAK,EAAE,MAAM,CAAC;IAEd;;;;OAIG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB"}
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@alwatr/debounce",
|
|
3
3
|
"description": "A powerful, modern, and type-safe debouncer utility designed for high-performance applications. It's framework-agnostic, works seamlessly in both Node.js and browsers, and provides a rich API for fine-grained control over function execution.",
|
|
4
|
-
"version": "1.0.
|
|
4
|
+
"version": "1.0.1",
|
|
5
5
|
"author": "S. Ali Mihandoost <ali.mihandoost@gmail.com>",
|
|
6
6
|
"bugs": "https://github.com/Alwatr/nanolib/issues",
|
|
7
7
|
"devDependencies": {
|
|
@@ -77,5 +77,5 @@
|
|
|
77
77
|
},
|
|
78
78
|
"type": "module",
|
|
79
79
|
"types": "./dist/main.d.ts",
|
|
80
|
-
"gitHead": "
|
|
80
|
+
"gitHead": "0ee186f1ec8973608f06155e739d55ab5d4bd816"
|
|
81
81
|
}
|