negotiator

library1.0.0jsnpmunverified

Negotiator is a lightweight, standalone utility for parsing and evaluating HTTP `Accept`, `Accept-Language`, `Accept-Encoding`, and `Accept-Charset` headers. It allows servers to determine the client's preferred content based on quality values (`q-factors`) specified in these headers. Primarily maintained by the `jshttp` organization, it serves as a core component for web frameworks like Express.js by abstracting complex RFC specifications for content negotiation. The current stable version is `1.0.0`. The package operates in a maintenance mode, with infrequent but significant major releases that often include breaking changes to align with evolving Node.js environments and best practices. It distinguishes itself by providing a robust and dependency-free solution for this specific HTTP concern.

http-networking web-framework

npm install negotiator

github ↗package ↗

INSTALL

IMPORT

SIG · NEGOTIATOR

negotiator

http-networkingjavascriptv1.0.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

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

Negotiator

✓ import Negotiator from 'negotiator'

✗ import { Negotiator } from 'negotiator'

The primary export is a default export representing the Negotiator constructor. Avoid named imports for the main class.

Negotiator

✓ const Negotiator = require('negotiator')

✗ const { Negotiator } = require('negotiator')

For CommonJS, the module exports the Negotiator constructor directly.

Demonstrates initializing Negotiator with mock request headers and using its methods to determine preferred content types, languages, and encodings based on client preferences and available options.

import Negotiator from 'negotiator'; const mockRequest = { headers: { 'accept': 'text/html, application/xhtml+xml, application/json;q=0.9, image/webp, */*;q=0.8', 'accept-language': 'en-US,en;q=0.9,es;q=0.7', 'accept-encoding': 'gzip, deflate, br;q=0.9, identity;q=0.5' } }; const negotiator = new Negotiator(mockRequest); console.log('Preferred Media Types (all):', negotiator.mediaTypes()); console.log('Preferred Media Type (available):', negotiator.mediaType(['application/json', 'text/plain'])); console.log('Preferred Languages (all):', negotiator.languages()); console.log('Preferred Language (available):', negotiator.language(['es', 'fr'])); console.log('Preferred Encodings (all):', negotiator.encodings()); console.log('Preferred Encoding (available):', negotiator.encoding(['gzip', 'br', 'identity'])); /* Example Output: Preferred Media Types (all): [ 'text/html', 'application/xhtml+xml', 'application/json', 'image/webp', '*/*' ] Preferred Media Type (available): application/json Preferred Languages (all): [ 'en-US', 'en', 'es' ] Preferred Language (available): es Preferred Encodings (all): [ 'gzip', 'br', 'identity', 'deflate' ] Preferred Encoding (available): gzip */

Debug

Known issues

breakingVersion `1.0.0` dropped support for Node.js versions older than 18. Applications running on Node.js <18 must remain on `negotiator@0.6.x` or upgrade their Node.js environment.

fix

Upgrade Node.js to version 18 or higher, or pin `negotiator` to `^0.6.0` in your `package.json`.

affects: >=1.0.0

gotchaIncorrect understanding or parsing of `q` values (quality factors) in `Accept` headers can lead to unexpected negotiation results. The `negotiator` library correctly sorts preferences, but developers must ensure their available lists align with expected client preferences.

fix

Thoroughly test negotiation logic with various `Accept` header values and explicit `q` factors. Refer to RFC 7231 for details on `q` values.

affects: >=0.5.0

gotchaMedia type parameters and header values are typically case-insensitive according to HTTP specifications. Older versions (pre-0.5.3) had fixes related to case-insensitivity in matching. Ensure your application's `available` lists use consistent casing or handle potential variations if manually constructing them.

fix

Upgrade to `negotiator@0.5.3` or newer to benefit from internal fixes for case-insensitive parameter matching. Always test your header parsing logic.

affects: <0.5.3

gotchaWhen dealing with `Accept-Encoding`, the `identity` encoding is implicitly supported unless explicitly excluded by a `q=0` factor. The library handles this, but applications might overlook `identity` when checking for available encodings, leading to unexpected default behavior.

fix

Always include `identity` in your `availableEncodings` list if you intend to support uncompressed responses, and be aware of its default `q` value if not specified otherwise.

affects: >=0.5.0

Errors

Common errors & fixes

TypeError: Negotiator is not a constructor

Attempting to instantiate `Negotiator` when it was imported incorrectly, often due to a named import or incorrect CommonJS `require` usage.

fix

For ESM, use `import Negotiator from 'negotiator';`. For CommonJS, use `const Negotiator = require('negotiator');` and then `new Negotiator(request);`.

Unexpected content type/language/encoding returned by negotiator.mediaType() (or similar method)

The `Accept` header or corresponding `Accept-` header from the client either has unexpected `q` values, a different order of preference, or the `available` list provided to the negotiator method does not match the expected options.

fix

Inspect the raw `Accept` headers received by the server. Verify the `q` values and syntax. Ensure the `available` array passed to `negotiator.mediaType(available)` accurately reflects what your application can provide and is not empty.

Upgrade

Version history

1.0.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/jshttp/negotiator ↗

packagehttps://www.npmjs.com/package/negotiator ↗