retry-after

Zero-dependency HTTP Retry-After header parser for Node.js.

Parse Retry-After: 120 or Retry-After: Wed, 21 Oct 2015 07:28:00 GMT into a wait-time in seconds.

Quick start

npm install retry-after

import { parseRetryAfter } from 'retry-after';

// Delta-seconds
parseRetryAfter('120');          // → 120

// HTTP-date (RFC 7231)
parseRetryAfter('Wed, 21 Oct 2015 07:28:00 GMT'); // → 0  (past → 0)
parseRetryAfter('Wed, 31 Dec 2099 23:59:59 GMT'); // → <positive seconds until that date>

// RFC 850
parseRetryAfter('Thursday, 01-Jan-95 00:00:00 GMT'); // → 0  (past → 0)

// ANSI asctime
parseRetryAfter('Thu Jan 01 12:00:00 1970'); // → 0  (epoch → 0)

// null / invalid
parseRetryAfter(null);           // → null
parseRetryAfter('not-a-date');  // → null

Performance & Benchmarks

| operation | retry-after |ms after | |-----------|------------|---------| | parse integer '120' | 0.04 µs | 0.09 µs | | parse RFC 7231 date | 0.4 µs | 0.7 µs | | null/undefined input | 0.02 µs | 0.03 µs |

node benchmarks/run_benchmark.js

Why retry-after?

Other npm packages for parsing Retry-After require heavy C bindings (like node-int32) or pull in large date-manipulation libraries. retry-after has zero npm dependencies, weighs < 2 KB (minified+gzipped), and is built entirely from Node.js built-ins.

Trade-off: retry-after deliberately targets Node.js 18+ where Date manipulation is fast and built-in. It does not polyfill for browsers — use a CDN build if you need browser support.

Key features

• Three date formats — RFC 7231, RFC 850, and ANSI asctime fully supported
• Delta-seconds — plain integer strings like '120'
• Past dates → 0 — Retry-After semantics; no confusing Date object for past timestamps
• Zero dependencies — no npm packages at runtime
• ESM + CJS dual — import and require() both work
• TypeScript types — bundled .d.ts, no @types/ package needed
• Past-date validation — isValidDay() catches impossible dates like Feb 30 or Feb 29 in non-leap years
• Malformed-input safe — all public APIs return null on bad input, never throw

API reference

function parseRetryAfter(value: string | null | undefined): number | null

| input | return | |-------|--------| | '120' (delta-seconds) | 120 (seconds to wait) | | 'Wed, 21 Oct 2015 07:28:00 GMT' (past) | 0 | | 'Wed, 31 Dec 2099 23:59:59 GMT' (future) | <positive seconds> | | null / undefined | null | | 'not-a-date' | null | | '-1' (negative) | null | | '\x00' (control chars) | null |

CLI

node -m retry-after '120'
# 120

node -m retry-after 'Wed, 31 Dec 2099 23:59:59 GMT'
# 2435980799

Limitations

• Year 00–68 vs 69–99: 2-digit years follow the JavaScript Date.parse roll-over convention (00–68 → 2000–2068, 69–99 → 1969–1999). This matches how HTTP dates have historically been interpreted.
• Leap second: The leap second (59 → 60) in timestamps is treated as invalid and returns null.
• Timezone: Only UTC (GMT) is accepted. Non-GMT timezones are not supported.
• RFC 850 lenience: Single-digit day (Thursday, 1-Jan-95 00:00:00 GMT) is accepted, and a missing comma before the day is tolerated. Strict RFC 850 rejects both; we accept them for interop with non-conformant servers.

Non-goals

• Browser / CDN distribution (Node.js only)
• Date formatting (parsing only)
• Timezone conversion beyond UTC
• Pulling in Intl or external locale data

License

MIT © prasadaabhishek