HTTP Content-Type Header Utility

Common errors

• TypeError: argument string is required

  cause The `parse` function was called without an argument or with `null`/`undefined`.
  fix Ensure that a non-empty string is always passed to `contentType.parse()`. If parsing from `req.headers['content-type']`, explicitly check if the header exists before calling parse.

• TypeError: invalid media type

  cause The string provided to `parse` does not conform to a valid HTTP Content-Type header format.
  fix Verify the input string's syntax. It should follow the `type/subtype; parameter=value` structure. For example, `text/html`, `application/json; charset=utf-8` are valid, while `html` or `application/json;` (with trailing semicolon) might be invalid.

• TypeError: invalid type

  cause When using `contentType.format(obj)`, the `obj.type` property is missing, `null`, `undefined`, or not a valid media type string.
  fix Ensure the object passed to `contentType.format()` has a `type` property which is a valid media type string (e.g., `'application/json'`, `'text/plain'`).

Warnings

• gotcha The `parse` function throws a `TypeError` if the input string is `null`, `undefined`, or an invalid Content-Type header format. Always wrap calls to `parse` in a `try...catch` block when dealing with potentially unreliable input, such as user-provided headers or network data.
  Fix: ```javascript try { const parsed = contentType.parse(headerValue); // ... use parsed object } catch (error) { if (error instanceof TypeError) { console.error('Invalid Content-Type header:', error.message); // Handle invalid header, e.g., return 400 Bad Request } else { throw error; } } ```
• gotcha When parsing from `req` or `res` objects, `contentType.parse(req)` is a shortcut for `contentType.parse(req.headers['content-type'])`. If the `Content-Type` header is entirely missing from the `req.headers` object, this will result in a `TypeError` as `undefined` is passed to the underlying parsing logic. Ensure the header exists if you expect to parse it.
  Fix: ```javascript const header = req.headers['content-type']; if (header) { try { const parsed = contentType.parse(header); // ... } catch (error) { // Handle invalid format } } else { console.warn('Content-Type header is missing.'); // Handle missing header explicitly } ```
• breaking Version 1.0.0 was an initial implementation derived from `media-typer@0.3.0`. While intended to be a direct replacement for `media-typer`'s Content-Type specific features, users migrating from `media-typer` should verify their parsing and formatting logic, especially regarding error handling and edge cases, as the internal implementation changed.
  Fix: Review existing usage of `media-typer` and ensure `content-type` provides equivalent functionality and handles error conditions identically. Specifically check how invalid input strings are handled, as `content-type` consistently throws `TypeError`.

Install

• npm install content-type npm
• yarn add content-type yarn
• pnpm add content-type pnpm

Imports

• contentType
  wrong:

  const contentType = require('content-type');

  correct:

  import * as contentType from 'content-type';

  CommonJS is shown in documentation; for ESM, use `import * as` as it exports a module object with named functions.
• parse
  wrong:

  import contentType from 'content-type'; // Then contentType.parse()

  correct:

  import { parse } from 'content-type';

  While `contentType.parse` works with the `* as` import, named imports directly import the function. `content-type` does not export a default.
• format
  wrong:

  import contentType from 'content-type'; // Then contentType.format()

  correct:

  import { format } from 'content-type';

  Similar to `parse`, `format` is a named export. Direct named import is preferred for clarity and tree-shaking.

Quickstart

This quickstart demonstrates parsing Content-Type headers from strings and simulated HTTP requests, and formatting objects back into header strings.

import { parse, format } from 'content-type';
import http from 'http';

// Example 1: Parsing a Content-Type string
try {
  const headerString = 'text/html; charset=utf-8; boundary=xyz';
  const parsed = parse(headerString);
  console.log('Parsed string:', parsed); // { type: 'text/html', parameters: { charset: 'utf-8', boundary: 'xyz' } }
} catch (error) {
  console.error('Error parsing string:', error.message);
}

// Example 2: Formatting an object to a Content-Type string
try {
  const objToFormat = {
    type: 'application/json',
    parameters: { charset: 'utf-8' }
  };
  const formatted = format(objToFormat);
  console.log('Formatted object:', formatted); // 'application/json; charset=utf-8'
} catch (error) {
  console.error('Error formatting object:', error.message);
}

// Example 3: Parsing from an incoming HTTP request (simulated)
const server = http.createServer((req, res) => {
  req.headers['content-type'] = 'application/x-www-form-urlencoded; encoding=UTF-8';

  try {
    const parsedReqHeader = parse(req);
    console.log('Parsed from request:', parsedReqHeader);
    res.writeHead(200, { 'Content-Type': format({
      type: 'text/plain',
      parameters: { charset: 'utf-8' }
    }) });
    res.end('Content-Type processed');
  } catch (error) {
    console.error('Error parsing request content-type:', error.message);
    res.writeHead(400, { 'Content-Type': 'text/plain' });
    res.end('Invalid Content-Type');
  }
});

server.listen(3000, () => {
  console.log('Server listening on http://localhost:3000');
  server.close(); // Close immediately for quickstart example
});