Solution

We are building a small buffer that accepts text in uneven bursts and hands it back one character at a time on a fixed heartbeat.

The problem, in plain English

Picture a chat app streaming a reply from a language model. The text does not arrive smoothly — the network hands you The qu, then a pause, then ick brown fox. If you paint each chunk on screen the instant it lands, the reader sees stutters: a freeze, a jump, a freeze. What you want instead is a calm, even "typing" effect. The pacer sits between the messy input and the screen: text goes in in lumps, and comes out one steady character at a time.

The mental model

Think of a funnel. Bursts of text pour into the top at random moments and pile up in a buffer. Underneath sits a metronome ticking at a fixed interval, and on every tick it lets exactly one character fall through. The pile rises and falls with the bursts, but the drip out of the bottom never changes its rhythm.

The two moving parts are a queue (the pile of characters waiting their turn) and a single timer (the metronome). Everything else follows from keeping those two honest.

A first attempt

The obvious idea: when a burst arrives, schedule one setTimeout per character, spacing them by delay.

function typewriterPacer(onChar, delay = 20) {
  return {
    push(text) {
      [...text].forEach((ch, i) => {
        setTimeout(() => onChar(ch), i * delay);
      });
    },
    flush() {},
    stop() {},
  };
}

This looks right for a single burst, but it falls apart the moment a second burst arrives before the first has finished. Each push starts its own timeline from now, so the two timelines overlap: the second burst's first character fires at almost the same moment as one of the first burst's later characters. The output arrives in colliding clumps — two characters at once, then a gap — which is the exact jitter we set out to remove. And because every timer is already scheduled, there is no clean way to flush or stop.

The working solution

Keep one shared queue and one timer. A burst simply appends to the queue; the timer drains it one character per tick and reschedules itself until the queue runs dry.

function typewriterPacer(onChar, delay = 20) {
  const queue = []; // characters buffered but not yet shown
  let timer = null; // the single drain timer; null means idle

  function tick() {
    onChar(queue.shift()); // release exactly one character
    // Reschedule only while text remains; otherwise go idle.
    timer = queue.length > 0 ? setTimeout(tick, delay) : null;
  }

  return {
    push(text) {
      for (const ch of text) queue.push(ch); // enqueue the whole burst
      // Start the metronome only if it is not already running.
      if (timer === null && queue.length > 0) {
        timer = setTimeout(tick, delay);
      }
    },
    flush() {
      if (timer !== null) {
        clearTimeout(timer);
        timer = null;
      }
      while (queue.length > 0) onChar(queue.shift()); // dump the rest now
    },
    stop() {
      if (timer !== null) {
        clearTimeout(timer);
        timer = null;
      }
      queue.length = 0; // drop whatever was buffered
    },
  };
}

module.exports = { typewriterPacer };

The shift in thinking is that arrival and display are now separate concerns. push never touches the clock's rhythm — it only adds to the pile. A single timer owns the cadence, and the timer === null guard is what stops a second burst from starting a competing metronome. When the queue empties, tick sets the timer back to null so the next push can start a fresh one.

Walking through one call

Say delay is 20ms and onChar writes to the screen.

• push('Hi') — the queue becomes ['H', 'i']. The timer was null, so we schedule the first tick for t=20ms.
• t=20ms — tick runs onChar('H'), leaving ['i']. Text remains, so it reschedules for t=40ms.
• push('!') at t=25ms — the queue becomes ['i', '!']. The timer is not null (a tick is already pending for t=40ms), so we just add to the pile and leave the rhythm alone.
• t=40ms — onChar('i'), queue ['!'], reschedule for t=60ms.
• t=60ms — onChar('!'), the queue is empty, so the timer becomes null and the metronome rests.

Three characters, emitted at 20/40/60ms — a perfectly even beat, even though the '!' arrived in the middle of the stream.

Gotchas

• Starting a second timer on every push — if push always calls setTimeout, two overlapping bursts run two metronomes and the output doubles up. Fix: only start the timer when timer === null.
• Never going idle — if tick reschedules unconditionally, it keeps firing on an empty queue and calls onChar(undefined) forever. Fix: reschedule only while queue.length > 0, and set timer = null otherwise.
• Splitting with text.split('') — that cuts a multi-byte emoji such as 🎉 into two broken halves. Fix: iterate with for...of (or [...text]), which walks whole Unicode code points.
• Forgetting to clear the timer in flush/stop — dumping the queue without clearTimeout leaves a pending tick that later fires into an empty queue. Fix: clear the timer and null it before touching the buffer.