以下是一个健壮、可维护的 JavaScript 实现，满足你的全部要求。它提供 throttle、debounce、hybrid 三种模式，支持 leading/trailing、maxWait、raf/setTimeout 调度器，提供 cancel/flush/pendingCount，并保证 this/参数传递正确、避免重入与并发竞态。
函数名称：smartThrottleDebounce
代码：
function smartThrottleDebounce(
fn,
waitMs,
mode = 'debounce',
leading = false,
trailing = true,
maxWaitMs,
scheduler = 'setTimeout',
context
) {
if (typeof fn !== 'function') {
throw new TypeError('fn must be a function');
}
waitMs = Math.max(0, Number(waitMs) || 0);
const useRaf = scheduler === 'raf' && typeof requestAnimationFrame === 'function';
const now = typeof performance !== 'undefined' && performance.now
? () => performance.now()
: () => Date.now();
// Internal state
let lastArgs = null;
let lastThis = null;
let lastResult;
let lastCallTime = 0;
let lastExecTime = null; // timestamp of last actual execution
let burstStartTime = null; // first call time in the current burst (for maxWait)
let inFlight = false; // fn is executing (async or sync)
let flushRequested = false; // request immediate execution after in-flight completes
let cancelled = false;
// Due times for scheduled execution
let debounceDue = null; // for debounce/hybrid final trailing (after inactivity)
let throttleDue = null; // for throttle end-of-window trailing
let forceDue = null; // forced execution due to maxWait
// Timer handle
let timerActive = false;
let timerId = null; // setTimeout handle or raf id
// Coalesced waiters for scheduled results
const waiters = []; // array of {resolve, reject}
// Pending count = waiters.length
const pendingCount = () => waiters.length;
function clearTimer() {
if (!timerActive) return;
if (useRaf) {
cancelAnimationFrame(timerId);
} else {
clearTimeout(timerId);
}
timerId = null;
timerActive = false;
}
function nextDue() {
let d = null;
if (debounceDue != null) d = debounceDue;
if (throttleDue != null) d = d == null ? throttleDue : Math.min(d, throttleDue);
if (forceDue != null) d = d == null ? forceDue : Math.min(d, forceDue);
return d;
}
function scheduleTimer() {
const due = nextDue();
if (due == null) {
clearTimer();
return;
}
const t = now();
const delay = Math.max(0, due - t);
clearTimer();
timerActive = true;
if (useRaf) {
const target = t + delay;
const loop = () => {
const n = now();
if (n >= due) {
timerActive = false;
timerId = null;
onTimer();
} else {
timerId = requestAnimationFrame(loop);
}
};
timerId = requestAnimationFrame(loop);
} else {
timerId = setTimeout(() => {
timerActive = false;
timerId = null;
onTimer();
}, delay);
}
}
function updateForceDue(currentTime) {
if (typeof maxWaitMs === 'number' && maxWaitMs > 0) {
const base = lastExecTime != null ? lastExecTime : (burstStartTime != null ? burstStartTime : currentTime);
forceDue = base + maxWaitMs;
} else {
forceDue = null;
}
}
function resolveWaitersWith(value) {
const list = waiters.splice(0, waiters.length);
for (const w of list) w.resolve(value);
}
function rejectWaitersWith(err) {
const list = waiters.splice(0, waiters.length);
for (const w of list) w.reject(err);
}
function postFlight() {
// After an execution finishes, run a requested flush immediately
if (flushRequested) {
flushRequested = false;
// Ignore windows: run ASAP with latest args (if any)
if (lastArgs != null && !inFlight) {
// Avoid recursion: schedule microtask-like immediate run
if (useRaf) {
requestAnimationFrame(() => {
if (!inFlight && lastArgs != null) runNow();
});
} else {
setTimeout(() => {
if (!inFlight && lastArgs != null) runNow();
}, 0);
}
}
}
}
function runNow() {
if (inFlight) {
// If currently in flight, defer immediate execution when it finishes
flushRequested = true;
return;
}
cancelled = false;
const thisArg = context !== undefined ? context : lastThis;
const args = lastArgs;
// Snapshot args to avoid mutation during execution
const snapshotArgs = Array.isArray(args) ? args.slice() : args;
inFlight = true;
try {
const result = fn.apply(thisArg, snapshotArgs);
if (result && typeof result.then === 'function') {
return Promise.resolve(result)
.then(res => {
lastResult = res;
inFlight = false;
lastExecTime = now();
resolveWaitersWith(res);
// Reset pending windows on success if nothing more pending
postFlight();
scheduleTimer(); // reschedule if some due remains
return res;
})
.catch(err => {
inFlight = false;
rejectWaitersWith(err);
scheduleTimer();
throw err;
});
} else {
lastResult = result;
inFlight = false;
lastExecTime = now();
resolveWaitersWith(result);
postFlight();
scheduleTimer();
return result;
}
} catch (err) {
inFlight = false;
rejectWaitersWith(err);
scheduleTimer();
throw err;
}
}
function onTimer() {
const t = now();
let shouldRun = false;
// Forced execution (maxWait) has highest priority if there is something pending
if (forceDue != null && t >= forceDue && (waiters.length > 0 || debounceDue != null || throttleDue != null)) {
forceDue = null;
shouldRun = true;
}
// Throttle trailing (end-of-window)
if (!shouldRun && throttleDue != null && t >= throttleDue) {
throttleDue = null;
shouldRun = true;
}
// Debounce trailing (after inactivity)
if (!shouldRun && debounceDue != null && t >= debounceDue) {
// For hybrid/debounce: ensure inactivity
if (t - lastCallTime >= waitMs) {
debounceDue = null;
shouldRun = true;
} else {
// Not inactive yet; push next due to lastCallTime + waitMs
debounceDue = lastCallTime + waitMs;
}
}
if (shouldRun) {
runNow();
}
scheduleTimer();
}
// Decide scheduling/execution for an invocation
function planForInvoke(currentTime) {
let ran = false;
let result;
const sinceExec = lastExecTime == null ? Infinity : (currentTime - lastExecTime);
if (mode === 'debounce') {
// leading immediate if no pending timer and no in-flight execution
if (leading && !timerActive && !inFlight && (lastExecTime == null || currentTime - lastCallTime >= waitMs)) {
ran = true;
result = runNow();
}
// Always schedule debounce trailing when calls happen
debounceDue = currentTime + waitMs;
updateForceDue(currentTime);
scheduleTimer();
return { ran, result, scheduled: !ran };
}
if (mode === 'throttle') {
if (sinceExec >= waitMs) {
if (leading && !inFlight) {
ran = true;
result = runNow();
} else if (trailing) {
throttleDue = currentTime + waitMs; // first call if leading false
}
} else {
if (trailing) {
const due = (lastExecTime || currentTime) + waitMs;
throttleDue = throttleDue == null ? due : Math.min(throttleDue, due);
}
}
updateForceDue(currentTime);
scheduleTimer();
const scheduled = !ran && (throttleDue != null || forceDue != null);
return { ran, result, scheduled };
}
// hybrid: throttle while active, plus a final debounce after inactivity
if (mode === 'hybrid') {
if (sinceExec >= waitMs) {
if (leading && !inFlight) {
ran = true;
result = runNow();
} else if (trailing) {
throttleDue = currentTime + waitMs;
}
} else {
if (trailing) {
const due = (lastExecTime || currentTime) + waitMs;
throttleDue = throttleDue == null ? due : Math.min(throttleDue, due);
}
}
// Always maintain a debounce due for final trailing after inactivity
debounceDue = currentTime + waitMs;
updateForceDue(currentTime);
scheduleTimer();
const scheduled = !ran && (debounceDue != null || throttleDue != null || forceDue != null);
return { ran, result, scheduled };
}
// Unknown mode fallback: act as debounce
debounceDue = currentTime + waitMs;
updateForceDue(currentTime);
scheduleTimer();
return { ran: false, result: undefined, scheduled: true };
}
// Public API
function invoke(...args) {
const t = now();
if (burstStartTime == null) burstStartTime = t;
lastArgs = args;
lastThis = this;
lastCallTime = t;
const plan = planForInvoke(t);
if (plan.ran) {
return plan.result; // could be Promise or value
}
if (plan.scheduled) {
// Return a coalesced promise to the eventual result
return new Promise((resolve, reject) => {
waiters.push({ resolve, reject });
});
}
// No action (e.g., throttle with leading true, trailing false within window)
// Return the last known result for consistency
return lastResult;
}
function cancel() {
clearTimer();
debounceDue = null;
throttleDue = null;
forceDue = null;
burstStartTime = null;
cancelled = true;
const err = new Error('Cancelled');
rejectWaitersWith(err);
}
function flush() {
// "立即以最新参数触发一次"：忽略窗口限制，但避免重入
if (lastArgs == null) return lastResult;
if (!inFlight) {
clearTimer();
debounceDue = null;
throttleDue = null;
forceDue = null;
return runNow();
}
// In-flight: queue to run immediately after current execution
flushRequested = true;
return new Promise((resolve, reject) => {
waiters.push({ resolve, reject });
});
}
return { invoke, cancel, flush, pendingCount };
}
使用说明与要点：
- 参数：
- fn: 要包装的函数（可同步或返回 Promise）
- waitMs: 窗口时长，单位毫秒
- mode: 'throttle' | 'debounce' | 'hybrid'（默认 'debounce'）
- leading: 布尔，是否在窗口开始执行（默认 false）
- trailing: 布尔，是否在窗口结束/停止后执行（默认 true）
- maxWaitMs: 可选，强制执行的最长等待时间，避免持续抖动导致永不执行
- scheduler: 'setTimeout' | 'raf'（默认 'setTimeout'）。'raf' 适合动画/滚动场景（若环境不支持，则自动退回 setTimeout）
- context: 可选，用于绑定 this（若不传，默认使用 invoke 时的 this）
- 返回：
- invoke(...args): 按模式控制执行，返回 Promise 或同步值（当立即执行时）；当被合并延迟时返回 Promise
- cancel(): 取消所有挂起的执行，并拒绝所有待决的 Promise
- flush(): 立即以最新参数触发一次（忽略窗口限制），但避免与正在执行的 fn 并发；若 fn 正在执行，返回一个 Promise，在执行完成后立即再次触发
- pendingCount(): 返回当前被合并的待决 Promise 数量，用于监控高频交互
行为细节：
- debounce：连续触发只在停止后 waitMs 才执行；支持 leading 在首次触发立即执行；trailing 控制停止后的收尾执行；maxWaitMs 保证即便持续触发也会周期性执行。
- throttle：在任意 waitMs 窗口内最多执行一次；leading 决定窗口开始是否立即执行；trailing 决定窗口末尾是否补一次；maxWaitMs 保证长时间内至少执行一次。
- hybrid：持续触发按 throttle 限制执行频率，并在停止触发后进行一次 debounce 收尾。
- Promise 统一返回：对延迟执行的调用，invoke 返回一个 Promise，完成后统一把最新一次执行结果分发给所有等待者。
- 竞态与重入：内部通过 inFlight 和 flushRequested 控制，避免并发重入；flush 会在当前执行完成后立即再次执行一次。
- this 与参数：执行时使用 context（若提供）或 invoke 的 this，参数为最后一次调用的最新参数。
- raf 调度：通过 requestAnimationFrame 循环等待到期，适合动画/滚动场景；否则用 setTimeout。
如需 TypeScript 声明或更强类型约束，我可以补充类型定义与更细致的单元测试示例。
