Small pacing engine for one class of problem:
Can I do this now, and if not, when should I retry?
The package is intentionally minimal:
- a
Pacer<C>is a flat list ofRule<C> - each rule returns either
ready, a concreteretryAt, ornull(never retry) - the pacer runs all rules and takes the maximum blocking time
Everything interesting lives in your rules and your context, not in the pacer itself.
Think of the pacer as:
- run every rule
- collect every block
- if nothing blocks, return
ready: true - otherwise return the latest
retryAt— ornullif any rule is permanently blocked
That means you can model very different systems with the same primitive:
- message pacing
- per-IP scraping limits
- business hours
- cooldowns after failures
- rolling quotas
- deduplication / one-shot gates
- reservation-backed slot allocation
One pacing rule for one context type.
export type RuleResult =
| { readonly ready: true }
| {
readonly ready: false;
/** Concrete time to retry. null means permanently blocked — never retry. */
readonly retryAt: Date | null;
readonly reason: string;
};
export interface Rule<C> {
readonly name: string;
check(context: C, now: Date): RuleResult | Promise<RuleResult>;
}The engine that aggregates rules.
export interface Pacer<C> {
check(context: C, now: Date): Promise<Verdict>;
}The combined answer.
export interface Block {
readonly rule: string;
/** Concrete time to retry. null means permanently blocked — never retry. */
readonly retryAt: Date | null;
readonly reason: string;
}
export type Verdict =
| { readonly ready: true }
| {
readonly ready: false;
/** Latest retryAt across all blocks. null if any block is permanent. */
readonly retryAt: Date | null;
readonly blocks: readonly Block[];
};Build a pacer from a flat list of rules.
import { createPacer } from "@1cedsoda/pacer";
const pacer = createPacer(rules);
const verdict = await pacer.check(context, new Date());import {
createPacer,
minGap,
fixedQuota,
startOfDay,
endOfDay,
} from "@1cedsoda/pacer";
type Context = {
email: string;
events: {
getLastEventTime(scope: string): Promise<Date | null>;
countSince(scope: string, since: Date): Promise<number>;
};
};
const pacer = createPacer<Context>([
minGap({
name: "email-min-gap",
scope: (context) => `email:${context.email}`,
gapMs: 8 * 60_000,
getLastEventTime: (context, scope) => context.events.getLastEventTime(scope),
}),
fixedQuota({
name: "email-daily-cap",
scope: (context) => `email:${context.email}`,
limit: 30,
window: (_context, now) => ({
start: startOfDay(now),
end: endOfDay(now),
}),
getCount: (context, scope, window) =>
context.events.countSince(scope, window.start),
}),
]);
const verdict = await pacer.check(
{
email: "alice@example.com",
events,
},
new Date(),
);
if (!verdict.ready) {
if (verdict.retryAt === null) {
console.log("Permanently blocked:", verdict.blocks);
} else {
console.log("Retry at:", verdict.retryAt.toISOString());
console.log("Blocked by:", verdict.blocks);
}
}Core:
createPacergroupanyOfallOf
Rule factories:
minGapfixedWindownotBeforefixedQuotaslidingQuotacooldownconcurrencyLimitbackoffdedupe
Helpers:
startOfHour/endOfHour— UTC hour boundariesstartOfDay/endOfDay— UTC day boundariesaddMscreateWindowScopeKey
The built-in factories use accessor callbacks instead of package-owned store interfaces. That keeps the package storage-agnostic.
Use when one scope needs a minimum delay between actions.
You provide:
scope(context)gapMs— number of milliseconds, or a function(context) => numbergetLastEventTime(context, scope)
Use cases:
- minimum delay between messages from one email
- minimum delay between requests from one IP
- minimum delay between retries for one account
Use when actions are only allowed during a known time window.
You provide:
isOpen(context, now)nextOpen(context, now)
Use cases:
- business hours only
- send only in evenings
- API usage only during a maintenance-safe window
Use when an action has a single scheduled start time.
You provide:
getTime(context)— returns the earliest allowed time
Use cases:
- scheduled workflow step that must not start early
- spawn staggering: each child gets a different
runAt - embargo window: process after a fixed delay from creation
Use when usage resets on a fixed boundary.
You provide:
scope(context)limitwindow(context, now)returning{ start, end }getCount(context, scope, window)
Use cases:
- max 30 messages per day
- max 100 requests per hour on the hour
- max 5 actions per calendar minute
Use when the window rolls continuously.
You provide:
scope(context)limitwindowMsgetEventTimes(context, scope, since, until)
Use cases:
- max 20 actions in any rolling 10 minutes
- max 50 requests in any rolling hour
- max 3 retries in any rolling 15 minutes
fixedQuota and slidingQuota are different:
- fixed quota resets at known boundaries
- sliding quota depends on when old events age out
Use when a recent failure should pause a scope for some time.
You provide:
scope(context)cooldownMs— number of milliseconds, or a function(context) => number(useful for exponential back-off based on attempt count)getLastFailureTime(context, scope)
Use cases:
- cooldown after login failure
- cooldown after anti-bot detection
- cooldown after a send error
- exponential back-off:
cooldownMs: (ctx) => 1_000 * 2 ** ctx.attempts
Use when a scope can only have a limited number of inflight actions.
You provide:
scope(context)maxgetInflightCount(context, scope)- optional
retryAfterMs— number or(context, now, scope, active) => number
Use cases:
- only one message send per account at a time
- max 3 concurrent workers per tenant
- max 2 inflight page fetches per IP
Use when a series of attempts should wait progressively longer between retries.
You provide:
scope(context)baseMs— delay for the first retry (attempt = 1)getAttempts(context, scope)— number of attempts already made (0 → ready immediately)getLastAttemptTime(context, scope)- optional
multiplier— growth factor per attempt (default2for exponential;1for flat) - optional
maxMs— cap on the computed delay
The delay formula is: min(baseMs × multiplier^(attempts − 1), maxMs)
| attempts | multiplier=2, baseMs=10s | multiplier=1, baseMs=10s |
|---|---|---|
| 1 | 10s | 10s |
| 2 | 20s | 10s |
| 3 | 40s | 10s |
| 4 | 80s | 10s |
Use cases:
- retry a failing HTTP request with exponential back-off
- re-queue a workflow step after each failed attempt
- flatten retries to a fixed interval when exponential growth is undesirable
Use when an item should only be processed once, ever.
You provide:
scope(context)getCompletedAt(context, scope)— returns the completion timestamp, ornull/undefinedif not yet processed
When getCompletedAt returns a date the rule returns retryAt: null — permanently blocked. The pacer (and any combinator wrapping it) will propagate null upward.
Use cases:
- skip a lead that has already been contacted
- gate an idempotency check before expensive work
- prevent a one-shot workflow from running twice
Pure naming helper.
It prefixes rule names:
email/min-gapemail/fixed-quotaip/concurrency-limit
This is only for organization and debugging.
Returns ready if any child rule is ready. All branches run in parallel.
retryAt semantics when all branches block:
- returns the earliest concrete
retryAtacross branches — retry as soon as any branch might unblock - returns
nullonly when every branch is permanently blocked
Use when you want branch-style logic:
- any proxy may be available
- any account in a pool may be available
- any slot source may unblock the action
Returns blocked if any child rule blocks. All rules run in parallel.
retryAt semantics when rules block:
- returns the latest concrete
retryAt— all rules must be satisfied before retrying - returns
nullif any rule is permanently blocked
This is mostly useful for nesting inside anyOf.
Top-level pacer behavior is already effectively allOf.
Optional branded string helper if you want stronger typing for scopes.
You do not need it to use the package.
Some rules can signal that a scope will never be ready: retryAt: null.
Rules that can produce null:
dedupe— when the item has already been completed- any custom rule that returns
retryAt: null
Propagation rules:
createPacer:nulltakes precedence over any concreteDatein the finalVerdictallOf:nullin any child →nullin the combined resultanyOf:nullonly in the combined result when all branches are permanently blocked; a mix ofnulland concreteretryAtvalues yields the earliest concrete date (the timed branch may still become ready)
Always check for null before calling .getTime() on verdict.retryAt:
if (!verdict.ready) {
if (verdict.retryAt === null) {
// Permanently blocked — do not schedule a retry
} else {
await sleepUntil(verdict.retryAt);
}
}All date helpers operate in UTC. Do not rely on them for local-time boundaries.
| Helper | Returns |
|---|---|
startOfHour(date) |
Start of the current UTC hour |
endOfHour(date) |
Start of the next UTC hour |
startOfDay(date) |
Midnight UTC of the current day |
endOfDay(date) |
Midnight UTC of the next day |
addMs(date, ms) |
New date offset by ms milliseconds |
createWindow(start, end) |
TimeWindow object |
For timezone-aware windows (e.g. "07:00 Europe/Berlin") use Intl or a timezone library in your fixedWindow.isOpen / fixedWindow.nextOpen callbacks.
Goal:
- minimum delay between messages from one email
- daily send cap per email
import {
createPacer,
minGap,
fixedQuota,
startOfDay,
endOfDay,
} from "@1cedsoda/pacer";
type Context = {
email: string;
events: {
getLastEventTime(scope: string): Promise<Date | null>;
countSince(scope: string, since: Date): Promise<number>;
};
};
const pacer = createPacer<Context>([
minGap({
name: "email-min-gap",
scope: (context) => `email:${context.email}`,
gapMs: 8 * 60_000,
getLastEventTime: (context, scope) => context.events.getLastEventTime(scope),
}),
fixedQuota({
name: "email-daily-cap",
scope: (context) => `email:${context.email}`,
limit: 30,
window: (_context, now) => ({
start: startOfDay(now),
end: endOfDay(now),
}),
getCount: (context, scope, window) =>
context.events.countSince(scope, window.start),
}),
]);Goal:
- minimum delay per IP
- scraping only allowed between 07:00 and 23:00 UTC
import { createPacer, fixedWindow, minGap } from "@1cedsoda/pacer";
type Context = {
ip: string;
events: {
getLastEventTime(scope: string): Promise<Date | null>;
};
};
const pacer = createPacer<Context>([
minGap({
name: "ip-min-gap",
scope: (context) => `ip:${context.ip}`,
gapMs: 3_000,
getLastEventTime: (context, scope) => context.events.getLastEventTime(scope),
}),
fixedWindow({
name: "wakeful-hours",
isOpen: (_context, now) => {
const hour = now.getUTCHours();
return hour >= 7 && hour < 23;
},
nextOpen: (_context, now) => {
const next = new Date(now);
if (now.getUTCHours() < 7) {
next.setUTCHours(7, 0, 0, 0);
} else {
next.setUTCDate(next.getUTCDate() + 1);
next.setUTCHours(7, 0, 0, 0);
}
return next;
},
}),
]);Goal:
- max 50 actions in any rolling hour
import { createPacer, slidingQuota } from "@1cedsoda/pacer";
type Context = {
ip: string;
events: {
getEventTimes(scope: string, since: Date, until: Date): Promise<readonly Date[]>;
};
};
const pacer = createPacer<Context>([
slidingQuota({
scope: (context) => `ip:${context.ip}`,
limit: 50,
windowMs: 60 * 60_000,
getEventTimes: (context, scope, since, until) =>
context.events.getEventTimes(scope, since, until),
}),
]);Goal:
- stop attempting for 15 minutes after the most recent failure
import { createPacer, cooldown } from "@1cedsoda/pacer";
type Context = {
email: string;
failures: {
getLastFailure(scope: string): Promise<Date | null>;
};
};
const pacer = createPacer<Context>([
cooldown({
scope: (context) => `email:${context.email}`,
cooldownMs: 15 * 60_000,
getLastFailureTime: (context, scope) => context.failures.getLastFailure(scope),
}),
]);Goal:
- only one inflight send per email
import { createPacer, concurrencyLimit } from "@1cedsoda/pacer";
type Context = {
email: string;
inflight: {
count(scope: string): Promise<number>;
};
};
const pacer = createPacer<Context>([
concurrencyLimit({
scope: (context) => `email:${context.email}`,
max: 1,
getInflightCount: (context, scope) => context.inflight.count(scope),
retryAfterMs: 5_000,
}),
]);Goal:
- wait progressively longer after each failed attempt (1s, 2s, 4s, 8s…), capped at 5 minutes
import { createPacer, backoff } from "@1cedsoda/pacer";
type Context = {
jobId: string;
jobs: {
getAttemptCount(scope: string): Promise<number>;
getLastAttemptTime(scope: string): Promise<Date | null>;
};
};
const pacer = createPacer<Context>([
backoff({
scope: (context) => `job:${context.jobId}`,
baseMs: 1_000,
multiplier: 2,
maxMs: 5 * 60_000,
getAttempts: (context, scope) => context.jobs.getAttemptCount(scope),
getLastAttemptTime: (context, scope) => context.jobs.getLastAttemptTime(scope),
}),
]);Goal:
- skip any lead that has already been contacted
import { createPacer, dedupe, minGap } from "@1cedsoda/pacer";
type Context = {
leadId: number;
email: string;
db: {
getContactedAt(scope: string): Promise<Date | null>;
getLastSentAt(scope: string): Promise<Date | null>;
};
};
const pacer = createPacer<Context>([
dedupe({
name: "already-contacted",
scope: (context) => `lead:${context.leadId}`,
getCompletedAt: (context, scope) => context.db.getContactedAt(scope),
}),
minGap({
name: "send-gap",
scope: (context) => `email:${context.email}`,
gapMs: 10 * 60_000,
getLastEventTime: (context, scope) => context.db.getLastSentAt(scope),
}),
]);
const verdict = await pacer.check(context, new Date());
if (!verdict.ready) {
if (verdict.retryAt === null) {
// Lead already contacted — discard permanently, do not reschedule
} else {
await sleepUntil(verdict.retryAt);
}
}Goal:
- total tenant budget is shared across active accounts
- each account gets a dynamic daily share
import { createPacer, type Rule, startOfDay, endOfDay } from "@1cedsoda/pacer";
type Context = {
email: string;
tenantDailyBudget: number;
activeAccountCount: number;
events: {
countSince(scope: string, since: Date): Promise<number>;
};
};
const dynamicAccountQuota: Rule<Context> = {
name: "dynamic-account-quota",
async check(context, now) {
const scope = `email:${context.email}`;
const perAccountLimit = Math.max(
1,
Math.floor(context.tenantDailyBudget / context.activeAccountCount),
);
const count = await context.events.countSince(scope, startOfDay(now));
if (count < perAccountLimit) return { ready: true };
return {
ready: false,
retryAt: endOfDay(now),
reason: `account share exhausted (${count}/${perAccountLimit})`,
};
},
};
const pacer = createPacer([dynamicAccountQuota]);This is the point of the package: special business logic becomes a rule, not a pacer feature.
Goal:
- if global failure rate is too high, slow the whole system down
import { createPacer, addMs, type Rule } from "@1cedsoda/pacer";
type Context = {
globalFailureRate: number;
};
const globalFailureBreaker: Rule<Context> = {
name: "global-failure-breaker",
check(context, now) {
if (context.globalFailureRate < 0.2) return { ready: true };
return {
ready: false,
retryAt: addMs(now, 5 * 60_000),
reason: `global failure rate too high (${(context.globalFailureRate * 100).toFixed(1)}%)`,
};
},
};
const pacer = createPacer([globalFailureBreaker]);Goal:
- use a reservation store to spread work into reserved future slots
import { createPacer, type Rule } from "@1cedsoda/pacer";
type Context = {
email: string;
reservations: {
getActiveReservation(scope: string, now: Date): Promise<unknown | null>;
tryReserve(scope: string, now: Date): Promise<{
reserved: boolean;
nextAvailable: Date;
}>;
};
};
const reservationRequired: Rule<Context> = {
name: "reservation-required",
async check(context, now) {
const scope = `email:${context.email}`;
const existing = await context.reservations.getActiveReservation(scope, now);
if (existing) return { ready: true };
const attempt = await context.reservations.tryReserve(scope, now);
if (attempt.reserved) return { ready: true };
return {
ready: false,
retryAt: attempt.nextAvailable,
reason: "no reservation slot available",
};
},
};
const pacer = createPacer([reservationRequired]);The pacer stays stateless. Restart safety lives in your reservation store and lease semantics.
If the built-ins do not fit, write a plain Rule<C>.
import { type Rule } from "@1cedsoda/pacer";
type Context = {
tenantId: string;
backlogSize: number;
};
const backlogShaper: Rule<Context> = {
name: "backlog-shaper",
check(context, now) {
if (context.backlogSize < 100) return { ready: true };
return {
ready: false,
retryAt: new Date(now.getTime() + 2 * 60_000),
reason: "backlog is too large right now",
};
},
};Return retryAt: null to signal a permanent block:
const permanentGate: Rule<Context> = {
name: "permanent-gate",
async check(context, _now) {
const done = await db.isCompleted(context.id);
if (!done) return { ready: true };
return { ready: false, retryAt: null, reason: "already completed" };
},
};If any rule throws, pacer.check() throws.
The pacer does not:
- swallow errors
- treat errors as
ready - silently skip failing rules
Blocked pacing and execution failure are different outcomes.
The pacer is stateless.
That means:
- no pacing-critical state lives inside the pacer instance
- all durable state lives in your stores
- a fresh pacer with the same rules should produce the same verdicts given the same context-backed data
When possible:
- derive quotas from durable events
- derive cooldowns from durable failures
- use lease semantics for reservations and inflight claims
- Keep your rules small and focused.
- Put storage access behind accessor callbacks.
- Prefer plain rules before adding abstractions.
- Use
group(...)for readability, not for behavior. - Use
anyOf(...)only when you actually need branch-style logic. - Keep retry reasons human-readable. They show up in
verdict.blocks. - Always guard
verdict.retryAtfornullbefore calling.getTime()orsleepUntil.
The pacer is intentionally boring.
That is the point.
It should be easy to explain:
- rules decide
- pacer aggregates
- context carries everything else