diff --git a/lib/Debouncer.ts b/lib/Debouncer.ts index ff3b27d..e05e468 100644 --- a/lib/Debouncer.ts +++ b/lib/Debouncer.ts @@ -3,7 +3,7 @@ import { NanoEmitter } from "./NanoEmitter.js"; //#region types /** - * The type of edge to use for the debouncer - [see this issue for an explanation and diagram.](https://github.com/Sv443-Network/UserUtils/issues/46) + * The type of edge to use for the debouncer - [see the docs for a diagram and explanation.](https://github.com/Sv443-Network/UserUtils/blob/main/README.md#debouncer) * - `immediate` - (default & recommended) - calls the listeners at the very first call ("rising" edge) and queues the latest call until the timeout expires * - Pros: * - First call is let through immediately @@ -28,14 +28,14 @@ export type DebouncerEventMap = { change: (timeout: number, type: DebouncerType) => void; }; -//#region class +//#region debounce class /** * A debouncer that calls all listeners after a specified timeout, discarding all calls in-between. * It is very useful for event listeners that fire quickly, like `input` or `mousemove`, to prevent the listeners from being called too often and hogging resources. * The exact behavior can be customized with the `type` parameter. * - * The instance inherits from NanoEmitter and emits the following events: + * The instance inherits from {@linkcode NanoEmitter} and emits the following events: * - `call` - emitted when the debouncer calls all listeners - use this as a pub-sub alternative to the default callback-style listeners * - `change` - emitted when the timeout or edge type is changed after the instance was created */ @@ -52,7 +52,7 @@ export class Debouncer extends NanoEmitter> { /** * Creates a new debouncer with the specified timeout and edge type. * @param timeout Timeout in milliseconds between letting through calls - defaults to 200 - * @param type The type of edge to use for the debouncer - see {@linkcode DebouncerType} for details or [this issue for an explanation and diagram](https://github.com/Sv443-Network/UserUtils/issues/46) - defaults to "immediate" + * @param type The edge type to use for the debouncer - see {@linkcode DebouncerType} for details or [the documentation for an explanation and diagram](https://github.com/Sv443-Network/UserUtils/blob/main/README.md#debouncer) - defaults to "immediate" */ constructor(protected timeout = 200, protected type: DebouncerType = "immediate") { super(); @@ -159,7 +159,9 @@ export class Debouncer extends NanoEmitter> { /** * Creates a {@linkcode Debouncer} instance with the specified timeout and edge type and attaches the passed function as a listener. * The returned function can be called with any arguments and will execute the `call()` method of the debouncer. - * The debouncer instance is accessible via the `debouncer` property of the returned function. + * The debouncer instance is accessible via the `debouncer` property of the returned function. + * + * Refer to the {@linkcode Debouncer} class definition or the [Debouncer documentation](https://github.com/Sv443-Network/UserUtils/blob/main/README.md#debouncer) for more information. */ export function debounce< TFunc extends DebouncerFunc, @@ -167,9 +169,9 @@ export function debounce< > ( fn: TFunc, timeout = 200, - edge: DebouncerType = "immediate" + type: DebouncerType = "immediate" ): DebouncerFunc & { debouncer: Debouncer } { - const debouncer = new Debouncer(timeout, edge); + const debouncer = new Debouncer(timeout, type); debouncer.addListener(fn); const func = (...args: TArgs[]) => debouncer.call(...args); @@ -177,38 +179,3 @@ export function debounce< return func; } - -//#region #DBG old - -// TODO:FIXME: https://github.com/Sv443-Network/UserUtils/issues/46 -/** - * Calls the passed {@linkcode func} after the specified {@linkcode timeout} in ms (defaults to 300). - * Any subsequent calls to this function will reset the timer and discard all previous calls. - * @param func The function to call after the timeout - * @param timeout The time in ms to wait before calling the function - * @param edge Whether to call the function at the very first call ("rising" edge) or the very last call ("falling" edge, default) - * @deprecated Replaced by {@linkcode Debouncer} and {@linkcode debounce()} - */ -export function debounceOld< - TFunc extends (...args: TArgs[]) => void, - TArgs = unknown, -> ( - func: TFunc, - timeout = 300, - edge: "rising" | "falling" = "falling" -): (...args: TArgs[]) => void { - let id: ReturnType | undefined; - - return function(...args: TArgs[]) { - if(edge === "rising") { - if(!id) { - func.apply(this, args); - id = setTimeout(() => id = undefined, timeout); - } - } - else { - clearTimeout(id); - id = setTimeout(() => func.apply(this, args), timeout); - } - }; -}