API reference › @evolu/common › Schedule › jitter

function jitter(
  percentage?: Percentage,
  mode?: "below" | "around",
): <Output, Input>(
  schedule: Schedule<Output, Input>,
) => Schedule<Output, Input>;

Defined in: packages/common/src/Schedule.ts:927

Randomizes delays by up to a percentage.

Jitter helps prevent "thundering herd" when many clients retry simultaneously after a service recovers. By default, the original delay is the upper bound:

  • "0%" — no jitter (original delay)
  • "50%" — equal jitter, shortens the delay by up to 50%
  • "100%" — full jitter, shortens the delay by up to 100%

Pass "around" to preserve the average delay for periodic work:

  • "0%" — no jitter (original delay)
  • "50%" — varies by up to 50% below or above the original delay
  • "100%" — varies by up to 100% below or above the original delay

Jittering below or around a delay

import {
  assertOk,
  exponential,
  jitter,
  spaced,
  testCreateDeps,
  type RandomNumber,
} from "@evolu/common";

const deps = {
  ...testCreateDeps(),
  random: { next: () => 0.5 as RandomNumber },
};

// Shorten retry delays by at most 25%.
const conservative = jitter("25%")(exponential("1s"));
// Poll around a 30s target cadence, from 27s to 33s.
const polling = jitter("10%", "around")(spaced("30s"));

assertOk(conservative(deps)(undefined), [1000, 875]);
assertOk(polling(deps)(undefined), [30000, 30000]);
Markdown for LLMs