@prexjs/negotiator

HTTP content negotiator for Node.js to determine preferred media types, encodings, languages, and charsets.

@prexjs/negotiator is a lightweight HTTP content negotiation library. It parses request headers (Accept, Accept-Encoding, Accept-Language, and Accept-Charset) conforming to RFC standards, accurately computing quality factors (q) and specificity to resolve the best match against supported server formats.

Features

• Media Type Negotiation: Parses Accept headers, respects wildcards (*/*, image/*), and sorts by specificity and quality factors.
• Encoding Preference: Evaluates Accept-Encoding preferences including support for gzip, deflate, br, and identity matching.
• Language & Charset Selection: Compares available locales and character sets against client preferences.
• Configurable Candidates: Filter preferences against an array of available options or return all client preferences.
• Zero External Dependencies: Pure TypeScript implementation with full CommonJS and ES Module builds.

Installation

Install using your preferred package manager:

# npm
npm install @prexjs/negotiator

# pnpm
pnpm add @prexjs/negotiator

# Yarn
yarn add @prexjs/negotiator

# Bun
bun add @prexjs/negotiator

Quick start

import http from 'node:http';
import Negotiator from '@prexjs/negotiator';

const server = http.createServer((req, res) => {
  const negotiator = new Negotiator(req);

  // Determine preferred media type
  const availableTypes = ['text/html', 'application/json', 'text/plain'];
  const preferredType = negotiator.mediaType(availableTypes);

  // Determine preferred language
  const availableLanguages = ['en-US', 'fr-FR', 'es-ES'];
  const preferredLanguage = negotiator.language(availableLanguages);

  // Determine preferred encoding
  const availableEncodings = ['gzip', 'deflate', 'identity'];
  const preferredEncoding = negotiator.encoding(availableEncodings);

  res.setHeader('Content-Type', preferredType || 'text/plain');
  res.setHeader('Content-Language', preferredLanguage || 'en-US');
  if (preferredEncoding) {
    res.setHeader('Content-Encoding', preferredEncoding);
  }

  res.end(`Preferred: ${preferredType}, ${preferredLanguage}, ${preferredEncoding}`);
});

server.listen(3000);

API

new Negotiator(request) / negotiator(request)

Creates a negotiator instance for an HTTP request object containing headers.

negotiator.mediaType(available?)

Returns the most preferred media type from available, or undefined if none match.

negotiator.mediaTypes(available?)

Returns an array of preferred media types sorted by quality factor and specificity.

negotiator.encoding(available?, options?)

Returns the most preferred encoding from available, or undefined.

negotiator.encodings(available?, options?)

Returns an array of preferred encodings sorted by preference.

negotiator.language(available?)

Returns the most preferred language code, or undefined.

negotiator.languages(available?)

Returns an array of preferred languages sorted by preference.

negotiator.charset(available?)

Returns the most preferred character set, or undefined.

negotiator.charsets(available?)

Returns an array of preferred charsets sorted by preference.

Compatibility

• Node.js >= 18.0.0
• Supports both ESM and CommonJS
• TypeScript 5.0+

Related Packages

• @prexjs/accepts: Higher-level content negotiation wrapper.
• @prexjs/content-type: Content-Type header parser and formatter.

License

MIT