yarn add fetch-opts

Fetch Opts

Fetch Opts is a modern, type-safe builder for RequestInit. It leans on the latest MDN Fetch API guidance so you can configure headers, caching, streaming uploads, and experimental flags like priority or browsingTopics without memorizing the entire spec. Bundling is handled with Parcel's recommended library setup, so the published package ships optimized ESM, CJS, and type definitions out of the box.

Runtime requirement: Node.js ≥ 18.17 (or any runtime where fetch, Headers, Request, etc. are globally available).

Installation

npm install fetch-opts
# or
yarn add fetch-opts
# or
pnpm add fetch-opts

Usage

import { FetchOptionsBuilder } from 'fetch-opts';

const payload = {
  email: '[email protected]',
  password: 'password123',
};

const fetchOptions = FetchOptionsBuilder.from({ credentials: 'include' })
  .method('POST')
  .json(payload)
  .accept('application/json')
  .bearerToken(process.env.ACCESS_TOKEN ?? '')
  .keepalive() // keep uploads alive even when the page closes (MDN)
  .priority('high')
  .browsingTopics(false)
  .build();

const response = await fetch('https://api.example.com/signin', fetchOptions);
const data = await response.json();

API Highlights

| Category | Helpers | Notes | | ---------------------- | ------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------- | | HTTP essentials | method, credentials, cache, redirect, referrer, referrerPolicy, signal | Mirrors the RequestInit parameters documented on MDN. | | Headers | bearerToken, header, mergeHeaders, accept, contentType | Uses the platform Headers implementation so casing is normalized automatically. | | Bodies | body, json, searchParams, formUrlEncoded, multipart | json defaults the method to POST and body helpers throw for GET/HEAD, matching Fetch semantics. | | Modern Fetch knobs | keepalive, priority, browsingTopics, duplex, integrity | Surface the new/experimental flags highlighted by MDN so you can opt in with a single method call. | | Composition | merge, clone, FetchOptionsBuilder.from | Start from an existing RequestInit, override what you need, and reuse across calls. |

Additional patterns

Search params body

const options = new FetchOptionsBuilder()
  .method('POST')
  .searchParams({ page: 1, filter: 'latest' })
  .build();

await fetch('/search', options);

Multipart upload

const formData = new FormData();
formData.append('file', fileInput.files?.[0] ?? new Blob());

const uploadOptions = new FetchOptionsBuilder()
  .method('POST')
  .duplex('half')
  .multipart(formData)
  .build();

await fetch('/upload', uploadOptions);

Packaging & build

• fetch-opts exposes module, main, and types fields plus an explicit exports map for tooling compatibility.
• Builds use Parcel with @parcel/bundler-library so each export stays tree-shakeable and type definitions remain in sync.
• The npm run build script is cross-platform (rimraf lib && parcel build).
• Publishing is currently handled manually by the maintainers. The former GitHub Actions workflow was removed while the npm account billing lock is resolved, so releases happen from an internal environment.
• Internal release checklist:
  1. Run npm run lint, npm run format:check, npm test, and npm run build locally.
  2. From an authorized machine, run npm publish --access public (or the appropriate internal registry command) once billing access is restored.
• See CHANGELOG.md for release notes.

Quality scripts

| Command | Description | | ---------------------- | --------------------------------------------------------------------- | | npm run lint | ESLint with @typescript-eslint and Jest rules (--max-warnings=0). | | npm run lint:fix | Same as above but auto-fixes supported issues. | | npm run format | Prettier write mode for source, README, and changelog. | | npm run format:check | CI-friendly Prettier verification. | | npm test | Jest test suite. |

Contributing

Contributions are welcome! To get started:

1. Fork the repository.
2. Create a feature branch.
3. Make your changes and add/adjust tests.
4. Commit – Husky will automatically run Prettier and Jest.
5. Push your branch and open a pull request.

License

This project is licensed under MIT.