@gvray/eskit/lib/debounced.js

A rich and colorful toolkit about typescript and javascript.

"use strict";
var __read = (this && this.__read) || function (o, n) {
    var m = typeof Symbol === "function" && o[Symbol.iterator];
    if (!m) return o;
    var i = m.call(o), r, ar = [], e;
    try {
        while ((n === void 0 || n-- > 0) && !(r = i.next()).done) ar.push(r.value);
    }
    catch (error) { e = { error: error }; }
    finally {
        try {
            if (r && !r.done && (m = i["return"])) m.call(i);
        }
        finally { if (e) throw e.error; }
    }
    return ar;
};
var __spreadArray = (this && this.__spreadArray) || function (to, from, pack) {
    if (pack || arguments.length === 2) for (var i = 0, l = from.length, ar; i < l; i++) {
        if (ar || !(i in from)) {
            if (!ar) ar = Array.prototype.slice.call(from, 0, i);
            ar[i] = from[i];
        }
    }
    return to.concat(ar || Array.prototype.slice.call(from));
};
Object.defineProperty(exports, "__esModule", { value: true });
exports.debounce = debounce;
/**
 * Creates a debounced function that waits for the specified delay after the last call before executing.
 * 创建一个防抖函数，在最后一次调用后等待指定延迟时间再执行。
 *
 * @param fn The function to wrap. / 要包装的函数
 * @param delay The delay time (in milliseconds) before the function is executed. / 函数执行前的延迟时间（毫秒）
 * @param immediate Whether to execute the function immediately on the first call. / 是否在第一次调用时立即执行函数
 * @returns The wrapped debounced function. / 包装后的防抖函数
 *
 * @example
 * ```typescript
 * // Basic debounce
 * const debouncedFn = debounce(() => {
 *   console.log('Called after delay!');
 * }, 1000);
 *
 * // With immediate execution
 * const immediateDebounced = debounce(() => {
 *   console.log('Called immediately!');
 * }, 1000, true);
 *
 * // Search input example
 * const searchDebounced = debounce((query: string) => {
 *   performSearch(query);
 * }, 300);
 *
 * // Cancel if needed
 * searchDebounced('hello');
 * searchDebounced.cancel(); // Cancels the pending call
 *
 * // Force execution
 * searchDebounced('world');
 * searchDebounced.flush(); // Executes immediately
 * ```
 */
function debounce(fn, delay, immediate) {
    var timeout = null;
    var lastArgs;
    var result;
    var debounced = function () {
        var args = [];
        for (var _i = 0; _i < arguments.length; _i++) {
            args[_i] = arguments[_i];
        }
        lastArgs = args;
        var later = function () {
            timeout = null;
            if (!immediate) {
                result = fn.apply(void 0, __spreadArray([], __read(args), false));
            }
        };
        var shouldCallNow = immediate && timeout === null;
        if (timeout !== null) {
            clearTimeout(timeout);
        }
        timeout = setTimeout(later, delay);
        if (shouldCallNow) {
            result = fn.apply(void 0, __spreadArray([], __read(args), false));
        }
    };
    /**
     * Cancels the debouncing, so that the debounced function no longer waits and does not execute.
     * 取消防抖，使防抖函数不再等待且不执行。
     */
    debounced.cancel = function () {
        if (timeout !== null) {
            clearTimeout(timeout);
            timeout = null;
        }
    };
    /**
     * Immediately executes the debounced function with the last arguments.
     * 立即执行防抖函数，使用最后的参数。
     */
    debounced.flush = function () {
        if (timeout !== null) {
            clearTimeout(timeout);
            timeout = null;
            if (lastArgs) {
                result = fn.apply(void 0, __spreadArray([], __read(lastArgs), false));
            }
        }
    };
    /**
     * Checks if the debounced function is pending execution.
     * 检查防抖函数是否正在等待执行。
     */
    debounced.pending = function () {
        return timeout !== null;
    };
    return debounced;
}
exports.default = debounce;
//# sourceMappingURL=debounced.js.map