lb-fetch

library1.1.0jsnpmunverified

A lightweight load-balanced fetch wrapper that distributes HTTP requests across multiple server URLs. v1.1.0 supports both string and URL inputs, configurable balancer strategies (default random shuffle), and custom success predicates. Works with any fetch-compatible environment (Node.js, browser, Deno) and includes TypeScript types. Differs from traditional load balancers by providing client-side, application-level fallback: if one endpoint fails (throws or returns a server error >=500), it automatically tries the next URL.

devops

npm install lb-fetch

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · LB-FETCH

lb-fetch

devopsjavascriptv1.1.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

default

✓ import lbFetch from 'lb-fetch'

✗ const lbFetch = require('lb-fetch')

ESM-only package; does not export a CommonJS module. TypeScript users can also use `import lbFetch from 'lb-fetch'`.

randomBalancer

✓ import lbFetch, { randomBalancer } from 'lb-fetch'

✗ import { randomBalancer } from 'lb-fetch/randomBalancer'

randomBalancer is a named export from the main module, not a separate file.

reject500s

✓ import lbFetch, { reject500s } from 'lb-fetch'

✗ const { reject500s } = require('lb-fetch')

Named export used as default success predicate.

Balancer

✓ import type { Balancer } from 'lb-fetch'

✗ import { Balancer } from 'lb-fetch'

Balancer is a TypeScript type, only import using `import type`.

Demonstrates basic usage with custom balancer and success predicate, including fallback between two servers.

import lbFetch from 'lb-fetch'; const response = await lbFetch( [ 'https://server1.example.com/api/endpoint', new URL('https://server2.example.com/api/endpoint'), ], { method: 'POST', body: new URLSearchParams({ foo: 'bar', baz: '42' }), }, { fetch: fetch ?? globalThis.fetch, balancer: (inputs) => [...inputs].sort(() => Math.random() - 0.5), success: (res) => res.ok, } ); console.log(await response.json());

Debug

Known issues

breakinglb-fetch is ESM-only. It does not provide a CommonJS export and cannot be used with require().

fix

Use dynamic import in CommonJS: `const lbFetch = await import('lb-fetch')`, or migrate to ESM.

affects: >=1.0.0

gotchaThe default balancer works only with inputs of type `string | URL`. For custom input types, you must provide a balancer.

fix

Pass a custom balancer that handles your input type: `lbFetch(input, init, { balancer: myBalancer })`.

affects: >=1.0.0

gotchaThe default success predicate `reject500s` rejects only server errors (status >=500), not client errors (4xx). This may cause unexpected retries on malformed requests.

fix

Override the success predicate to define your own success criteria, e.g., `(res) => res.ok`.

affects: >=1.0.0

deprecatedNo deprecations reported yet.

fix

Stay updated with the package changelog.

affects: none

Errors

Common errors & fixes

ERR_REQUIRE_ESM

Trying to require an ESM-only package with `require('lb-fetch')`.

fix

Change to `import lbFetch from 'lb-fetch'` or use dynamic import.

TypeError: lbFetch is not a function

Using default import incorrectly (e.g., `import { lbFetch }` or `const { lbFetch } = require('lb-fetch')`).

fix

Use `import lbFetch from 'lb-fetch'`.

Error: balancer is required for non-string/URL inputs

Passing custom input type (e.g., objects) without specifying a balancer.

fix

Provide a `balancer` option in the third argument.

ReferenceError: fetch is not defined

Running in an environment without global fetch (older Node.js, Deno without permissions).

fix

Pass the fetch implementation explicitly via `options.fetch`, or use a polyfill like `node-fetch`.

Upgrade

Version history

1.1.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

8 hits · last 30 days

node

Bingbot

Resources

githubhttps://github.com/fabrykowski/lb-fetch ↗

packagelb-fetch ↗

homepagehttps://github.com/fabrykowski/lb-fetch#readme ↗