@prexjs/accepts

Higher-level HTTP content negotiation for Node.js, handling media types, encodings, charsets, and languages.

@prexjs/accepts provides high-level content negotiation utilities based on @prexjs/negotiator and @prexjs/mime-types. It enables HTTP servers to easily inspect incoming request headers (Accept, Accept-Encoding, Accept-Charset, Accept-Language) and select the best response representation for clients.

Features

• Media Type Negotiation: Inspect Accept headers with automatic extension resolution (e.g. 'html', 'json').
• Encoding Selection: Negotiate compression algorithms such as gzip, deflate, br, or identity.
• Charset & Language Resolution: Prioritize character encodings and locales based on client quality factors (q values).
• Flexible Argument Parsing: Accepts arguments as arrays or spread strings (types('json', 'html') or types(['json', 'html'])).
• Dual Module Support: Full ESM (.mjs) and CommonJS (.cjs) builds with TypeScript types out of the box.

Installation

Install using your preferred package manager:

# npm
npm install @prexjs/accepts

# pnpm
pnpm add @prexjs/accepts

# Yarn
yarn add @prexjs/accepts

# Bun
bun add @prexjs/accepts

Quick start

import http from 'node:http';
import accepts from '@prexjs/accepts';

const server = http.createServer((req, res) => {
  const accept = accepts(req);

  // Negotiate media type
  switch (accept.type(['json', 'html', 'text'])) {
    case 'json':
      res.setHeader('Content-Type', 'application/json');
      res.end(JSON.stringify({ message: 'Hello, World!' }));
      break;
    case 'html':
      res.setHeader('Content-Type', 'text/html');
      res.end('<h1>Hello, World!</h1>');
      break;
    case 'text':
      res.setHeader('Content-Type', 'text/plain');
      res.end('Hello, World!');
      break;
    default:
      res.statusCode = 406;
      res.end('Not Acceptable');
      break;
  }
});

server.listen(3000);

API

accepts(req) / new Accepts(req)

Creates a new Accepts instance for the given request.

• req: An object with HTTP headers (e.g., standard http.IncomingMessage).

accept.types(types?) (alias: accept.type(...))

• Returns all accepted media types when called with no arguments.
• Returns the best match when passed an array or list of candidate types/extensions.
• Returns false if none of the candidates match.

// Given Accept: text/html, application/json;q=0.9
accept.types('html', 'json'); // => 'html'
accept.types(['json', 'image/png']); // => 'json'
accept.types(); // => ['text/html', 'application/json']

accept.encodings(encodings?) (alias: accept.encoding(...))

• Returns all accepted encodings ordered by quality when called with no arguments.
• Returns the best matching encoding or false.

// Given Accept-Encoding: gzip, deflate;q=0.8
accept.encodings('gzip', 'deflate', 'identity'); // => 'gzip'
accept.encodings(); // => ['gzip', 'deflate', 'identity']

accept.charsets(charsets?) (alias: accept.charset(...))

• Returns accepted character sets ordered by quality preference.
• Returns the best match from the provided options or false.

// Given Accept-Charset: utf-8, iso-8859-1;q=0.2
accept.charsets('utf-8', 'iso-8859-1'); // => 'utf-8'

accept.languages(languages?) (aliases: lang, langs, language)

• Returns accepted languages ordered by client preference.
• Returns the best matching language code or false.

// Given Accept-Language: en;q=0.8, es, pt
accept.languages('en', 'es', 'fr'); // => 'es'

Compatibility

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

Related Packages

• @prexjs/negotiator: Low-level HTTP negotiation parser.
• @prexjs/mime-types: MIME type resolution and mapping.
• @prexjs/type-is: Request body type matching.

License

MIT