{"id":17228,"library":"fetch-smartly","title":"Fetch Smartly","description":"Fetch Smartly is a zero-dependency, isomorphic HTTP client that wraps the native `fetch` API to provide production-grade resilience and intelligence for Node.js 18+, browsers, Cloudflare Workers, Deno, and Bun environments. It addresses common pain points of raw `fetch` by incorporating intelligent retry mechanisms with exponential backoff and jitter, respecting `Retry-After` headers, and automatically avoiding retries for 4xx client errors. The library offers a comprehensive typed error hierarchy, including `NetworkError`, `TimeoutError`, `HttpError`, and `RateLimitError`, enabling granular error handling via `instanceof` checks. Key features also include an automatic circuit breaker for failure isolation, request deduplication for identical concurrent GET/HEAD requests, and an offline queue with pluggable storage for replaying failed requests. Currently at version 1.0.2, the package is actively maintained with recent minor updates, distinguishing itself through its lightweight nature, strict TypeScript support, and robust, built-in resilience features.","status":"active","version":"1.0.2","language":"javascript","source_language":"en","source_url":"https://github.com/Ali-Raza-Arain/fetch-smartly","tags":["javascript","fetch","http","http-client","retry","exponential-backoff","circuit-breaker","rate-limit","timeout","typescript"],"install":[{"cmd":"npm install fetch-smartly","lang":"bash","label":"npm"},{"cmd":"yarn add fetch-smartly","lang":"bash","label":"yarn"},{"cmd":"pnpm add fetch-smartly","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The library primarily uses ES modules; CommonJS imports may work but ESM is the idiomatic usage for modern Node.js environments (>=18).","wrong":"const fetchWithRetry = require('fetch-smartly');","symbol":"fetchWithRetry","correct":"import { fetchWithRetry } from 'fetch-smartly';"},{"note":"These are part of the custom typed error hierarchy for robust error handling using `instanceof`.","symbol":"HttpError, NetworkError, TimeoutError","correct":"import { HttpError, NetworkError, TimeoutError } from 'fetch-smartly';"},{"note":"Import types separately using `import type` for clarity and to assist bundlers and type checkers.","symbol":"FetchSmartlyConfig","correct":"import type { FetchSmartlyConfig } from 'fetch-smartly';"}],"quickstart":{"code":"import { fetchWithRetry, HttpError, NetworkError, TimeoutError, RateLimitError } from 'fetch-smartly';\n\nasync function fetchDataWithResilience() {\n  try {\n    const response = await fetchWithRetry({\n      url: 'https://api.github.com/users/octocat', // Example public API endpoint\n      method: 'GET',\n      retry: {\n        attempts: 5,\n        delay: 'exponential', // Use exponential backoff\n        maxDelay: 5000, // Cap retry delay at 5 seconds\n        shouldRetry: (error) => !(error instanceof HttpError && error.status >= 400 && error.status < 500), // Don't retry client errors\n      },\n      timeout: 3000, // 3-second timeout for the request\n      circuitBreaker: {\n        threshold: 3, // Open after 3 consecutive failures\n        resetTimeout: 10000, // Try to close after 10 seconds\n      },\n      headers: {\n        'Content-Type': 'application/json',\n        'User-Agent': 'fetch-smartly-example',\n        'Authorization': `Bearer ${process.env.API_KEY ?? ''}` // Example of using an environment variable for auth\n      }\n    });\n\n    if (response.ok) {\n      const data = await response.json();\n      console.log('Fetched data:', data);\n    } else {\n      console.error('HTTP Error:', response.status, response.statusText);\n    }\n  } catch (error) {\n    if (error instanceof HttpError) {\n      console.error(`Request failed with HTTP status ${error.status}: ${error.message}`);\n      if (error instanceof RateLimitError) {\n        console.warn(`Rate limited! Retry-After: ${error.retryAfter} seconds`);\n      }\n    } else if (error instanceof NetworkError) {\n      console.error('Network connection error:', error.message);\n    } else if (error instanceof TimeoutError) {\n      console.error('Request timed out:', error.message);\n    } else {\n      console.error('An unexpected error occurred:', error);\n    }\n  }\n}\n\nfetchDataWithResilience();","lang":"typescript","description":"This quickstart demonstrates how to use `fetchWithRetry` with intelligent retry logic, a request timeout, and a circuit breaker. It also shows how to handle the library's custom error hierarchy, including `HttpError`, `NetworkError`, `TimeoutError`, and `RateLimitError`, for robust error management."},"warnings":[{"fix":"Implement and provide a storage adapter to the `offlineQueue` configuration. Refer to the official documentation for examples.","message":"The `offlineQueue` feature requires a pluggable storage mechanism (e.g., localStorage or a custom adapter). If no storage is configured, requests queued during offline periods will be lost upon application restart or page refresh.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Thoroughly test HTTP request patterns and error handling in all target environments where strict consistency is critical.","message":"While `fetch-smartly` aims for isomorphism, subtle differences in the underlying `fetch` implementation across various JavaScript runtimes (e.g., Node.js, browsers, Cloudflare Workers, Deno, Bun) may still lead to minor behavioral variances, especially concerning stream handling or error reporting specifics.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Carefully configure the `retry.shouldRetry` callback for non-GET/HEAD requests, explicitly defining conditions under which a retry is safe and appropriate. Avoid retrying 4xx errors unless explicitly desired.","message":"The default retry policy will *not* retry 4xx client errors by default (unless specifically overridden by `shouldRetry`). Ensure that non-idempotent requests (e.g., POST, PUT, PATCH, DELETE) are handled carefully if `shouldRetry` is customized, to prevent unintended side effects on repeated execution.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Ensure you are running in a Node.js environment version 18 or higher, a modern browser, or a compatible serverless environment. If using an older Node.js, consider polyfilling `fetch` (though not recommended for `fetch-smartly` as it expects native behavior).","cause":"The environment where `fetch-smartly` is running does not expose a global `fetch` API.","error":"TypeError: fetch is not a function"},{"fix":"This is expected behavior for a failing service. Wait for the `circuitBreaker.resetTimeout` to elapse, which will attempt to transition the circuit breaker to 'half-open' to test the service. Investigate and resolve the underlying service instability.","cause":"The circuit breaker mechanism has detected a high rate of failures and has 'opened' to prevent further requests from overloading the failing service, protecting both the client and the service.","error":"CircuitBreakerOpenError: Circuit breaker is currently open. Request was short-circuited."},{"fix":"Always provide a valid URL string via the `url` property in the configuration object, e.g., `{ url: 'https://api.example.com/data' }`.","cause":"The `url` property, which specifies the target URL for the HTTP request, was omitted from the configuration object passed to `fetchWithRetry`.","error":"FetchSmartlyConfigError: 'url' is a required option in the fetchWithRetry configuration."}],"ecosystem":"npm","meta_description":null}