Debounce y throttle: no trabajar en cada pulsación

Escribes seis caracteres por segundo. Si tu plugin recalcula un diagnóstico, lanza un grep o consulta un servidor en cada TextChanged, has pedido seis trabajos caros por segundo para tirar cinco de ellos a la basura. Las dos técnicas que corrigen esto son viejas, se llaman debounce y throttle, y en Neovim se construyen exactamente con lo aprendido en las lecciones anteriores: un timer de vim.uv y un salto de vuelta con vim.schedule. No son la misma técnica con distinto nombre; responden a preguntas distintas y elegir mal produce un plugin que se siente peor que sin optimizar.

Dos respuestas a la misma avalancha

Ante una ráfaga de eventos, hay exactamente dos cosas razonables que hacer: esperar a que la ráfaga termine, o dejar pasar uno cada tanto. Todo lo demás son variantes.

Un buscador que consulta al escribir quiere debounce: los resultados de “neo” no le sirven a nadie si vas a escribir “neovim”. Una barra de progreso que refleja una compilación quiere throttle: quedarse muda hasta el final sería inútil, pero redibujar mil veces por segundo también.

flowchart TB
subgraph Debounce
  d1[Pulsaciones seguidas] --> d2[Cada una reinicia el timer]
  d2 --> d3[Solo tras el silencio se ejecuta una vez]
end
subgraph Throttle
  t1[Pulsaciones seguidas] --> t2[La primera ejecuta ya]
  t2 --> t3[Las siguientes se descartan hasta cumplir el intervalo]
end
style d3 fill:#a6e3a1,color:#11111b
style t2 fill:#89b4fa,color:#11111b

Debounce con vim.uv

La implementación es directa si recuerdas que t:start sobre un timer ya activo reinicia su cuenta. Esa es toda la magia: cada llamada cancela la anterior.

local uv = vim.uv

local function debounce(ms, fn)
  local timer = uv.new_timer()
  local envuelto = function(...)
    local args = { ... }
    timer:stop()
    timer:start(ms, 0, function()
      timer:stop()
      vim.schedule(function() fn(unpack(args)) end)
    end)
  end
  return envuelto, timer
end

Tres detalles importan más de lo que parece. Primero, los argumentos se capturan en una tabla porque el callback del timer no los recibe. Segundo, vim.schedule es obligatorio: el cuerpo de fn casi siempre tocará la API del editor. Tercero, la función devuelve también el timer, para que quien la use pueda cerrarlo cuando el plugin se descargue.

local recalcular = debounce(250, function(bufnr)
  vim.diagnostic.reset(nil, bufnr)
  -- trabajo caro sobre el buffer, ya en contexto seguro
end)

vim.api.nvim_create_autocmd({ "TextChanged", "TextChangedI" }, {
  callback = function(ev) recalcular(ev.buf) end,
})

Throttle y la limpieza de handles

El throttle invierte la lógica: ejecuta primero y luego calla. La variante más simple es la de borde de entrada, que dispara inmediatamente y descarta lo que llegue durante el periodo de enfriamiento.

local function throttle(ms, fn)
  local en_espera = false
  local timer = uv.new_timer()
  local envuelto = function(...)
    if en_espera then return end
    en_espera = true
    fn(...)
    timer:start(ms, 0, function()
      timer:stop()
      en_espera = false
    end)
  end
  return envuelto, timer
end

Su defecto conocido es que pierde el último evento: si la ráfaga termina justo dentro del periodo de enfriamiento, ese estado final nunca se procesa. La cura habitual es guardar los últimos argumentos y, al vencer el timer, ejecutar una vez más si hubo llamadas descartadas. Eso es un throttle con borde de salida, y en la práctica es lo que quieres casi siempre.

local function throttle_final(ms, fn)
  local en_espera, pendiente = false, nil
  local timer = uv.new_timer()
  local function disparar(...)
    fn(...)
    en_espera = true
    timer:start(ms, 0, function()
      timer:stop()
      en_espera = false
      if pendiente then
        local args = pendiente
        pendiente = nil
        vim.schedule(function() disparar(unpack(args)) end)
      end
    end)
  end
  return function(...)
    if en_espera then pendiente = { ... } else disparar(...) end
  end, timer
end

Sea cual sea la variante, el timer que has creado sigue vivo. Un plugin serio lo cierra al desmontarse, y lo hace de forma defensiva porque cerrar dos veces es un error.

local function cerrar(timer)
  if timer and not timer:is_closing() then
    timer:stop()
    timer:close()
  end
end