node-request-retry

requestretry is a drop-in replacement for the classic Node.js request library that adds automatic retry behavior for recoverable failures. It re-attempts a call when the connection fails with errors like ECONNRESET, ETIMEDOUT, or ECONNREFUSED, or when the server responds with a 429 or 5xx status code, since these are typically transient conditions that succeed on a subsequent try.

Beyond the default behavior, it exposes pluggable retry and delay strategies so callers can define exactly when to retry and how long to wait between attempts, including asynchronous strategies that can refresh an auth token before retrying. It supports both callback and promise-based usage, tracks the number of attempts on the response or error object, and forwards to the underlying postman-request client so existing request-style code needs minimal changes to adopt it.

What You Get

• Drop-in request()-compatible API with get/post/put/patch/delete/head helpers
• Configurable maxAttempts and retryDelay with sane defaults (5 attempts, 5s delay)
• Built-in HTTPError, NetworkError, and HTTPOrNetworkError retry strategies
• Support for custom synchronous or async retryStrategy and delayStrategy functions
• Automatic Cookie/Authorization header stripping on cross-origin redirects
• Callback and Promise (with a pluggable promiseFactory) usage patterns

Common Use Cases

• Retrying calls to flaky third-party APIs that intermittently return 502/503
• Building resilient internal service-to-service HTTP calls in Node backends
• Adding exponential backoff to webhook delivery or polling clients
• Refreshing an expired auth token mid-retry via a custom async retryStrategy

Under The Hood

Architecture The library is a single-file module (index.js) exporting a Factory function that wraps the postman-request client in a Request object tracking maxAttempts, retryDelay, and attempts, with retry/delay strategy functions injected via options or defaulted from strategies/index.js (HTTPError, NetworkError, and a composed HTTPOrNetworkError). Request.prototype._tryUntilFail recursively re-invokes postman-request on failure, awaits an optionally-async retryStrategy result before scheduling a setTimeout-based retry via delayStrategy, and Request.prototype exposes pass-through methods (end/on/pipe/etc.) plus promise methods (then/catch/finally) so instances can stand in for both the original request API and a promise. A defaults() factory mirrors request.defaults, closing over merged default options and re-exporting the verb helpers built by makeHelper. This is a thin decorator over a single external HTTP client dependency rather than a layered system; if the retry loop or options-merging logic in _tryUntilFail changed shape, every consumer relying on drop-in compatibility and the strategy contract would break.

Tech Stack Plain JavaScript (no TypeScript), CommonJS modules, with runtime dependencies on extend (deep option merging) and lodash (type checks, cloning, array helpers used throughout index.js and the strategies). The actual HTTP transport is a peer dependency on postman-request, a maintained fork of the deprecated request package. The dev/test stack uses Mocha and Chai for tests, Sinon for mocking, nyc for coverage with a 100%-statements/lines/functions/branches threshold configured in package.json, conventional-changelog for changelog generation, and CircleCI (pinned to an old node:10.16.3 image) for continuous integration.

Code Quality Tests are substantial and varied: eleven test files covering retry strategies, promise handling, defaults, cookies, auth, aborts, memory leaks, API surface, and option cloning, all using Mocha/Chai/Sinon. The nyc coverage configuration demanding full statement/line/function/branch coverage indicates genuine testing discipline. Error handling is explicit, passing errors and responses through Node-style callbacks and resolving/rejecting the promise wrapper appropriately, and retry strategies are handed the error object directly rather than having failures swallowed. There is no static typing (plain JS, no TypeScript or Flow) and linting is limited to an older .jshintrc rather than a modern linter, so type safety is comparatively weak even though test coverage is strong.

API Design The public API deliberately mirrors the original request module’s shape (request(options, callback), request.get/post/put/patch/delete/head, request.defaults()) so existing request-based code can adopt it with minimal changes, and it layers on exactly three new concepts — maxAttempts, retryDelay/delayStrategy, and retryStrategy — keeping the surface area small. The README documents callback and promise usage, custom retry/delay strategies (including an exponential-backoff recipe and an async token-refresh recipe), and how to reach the underlying postman-request instance, which lowers the ramp-up cost for anyone already familiar with request.