Fast Content-Type Header Parser

Common errors

• TypeError: Invalid Content-Type header string

  cause The input string provided to the `parse` method does not conform to RFC 7231 specifications for a Content-Type header.
  fix Ensure the input string is a valid HTTP Content-Type header, or use the `safeParse` method if you want to handle invalid input gracefully without throwing an error.

• ReferenceError: require is not defined

  cause Attempting to use `require()` syntax in a pure ESM (ECMAScript Module) context, such as a file with `type: "module"` in `package.json` or an `.mjs` file, without proper transpilation or bundling.
  fix In ESM contexts, use `import { parse, safeParse } from 'fast-content-type-parse';`. The package provides dual CommonJS/ESM entry points.

Warnings

• breaking Version 3.0.0 of `fast-content-type-parse` dropped support for Node.js 16 and Node.js 18. Projects running on these End-of-Life Node.js versions will need to update their Node.js runtime or remain on an older version of the package.
  Fix: Upgrade your Node.js runtime to version 20 or newer, or pin `fast-content-type-parse` to a `^2.x` version in your `package.json`.
• gotcha The `parse` method throws a `TypeError` for invalid Content-Type header strings, while `safeParse` returns an object with `type: ''` and `parameters: {}` without throwing.
  Fix: Choose `parse` if you require strict validation and explicit error handling, or `safeParse` for robustness against malformed input without needing `try/catch` blocks.

Install

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

Imports

• parse
  wrong:

  const parse = require('fast-content-type-parse').parse;

  correct:

  import { parse } from 'fast-content-type-parse';

  For ESM projects, use named imports. Direct `require().parse` in ESM contexts can lead to `ReferenceError` unless transpiled. The library provides dual CommonJS/ESM entry points.
• safeParse
  wrong:

  const safeParse = require('fast-content-type-parse').safeParse;

  correct:

  import { safeParse } from 'fast-content-type-parse';

  Named import for `safeParse` in ESM. This function will not throw on invalid input, unlike `parse`.
• FastContentTypeParse (CommonJS)
  wrong:

  import fastContentTypeParse from 'fast-content-type-parse';

  correct:

  const { parse, safeParse } = require('fast-content-type-parse');

  While `fast-content-type-parse` offers dual ESM/CJS compatibility, the CommonJS export is an object containing `parse` and `safeParse`. A default import in ESM would be incorrect if the CJS bundle doesn't provide a default export, though `exports` maps can handle this.

Quickstart

Demonstrates both `parse` (strict, throws on error) and `safeParse` (returns empty object on error) methods for HTTP Content-Type headers.

import { parse, safeParse } from 'fast-content-type-parse';

// Example 1: Valid Content-Type header
try {
  const contentType = parse('application/json; charset=utf-8');
  console.log('Parsed (strict):', contentType); // { type: 'application/json', parameters: { charset: 'utf-8' } }
} catch (error) {
  console.error('Error parsing (strict):', error.message);
}

// Example 2: Invalid Content-Type header with strict parse (will throw)
try {
  const invalidContentType = parse('invalid-type;');
  console.log('Parsed (strict):', invalidContentType);
} catch (error) {
  console.error('Error parsing (strict):', error.message); // TypeError: Invalid Content-Type header string
}

// Example 3: Invalid Content-Type header with safeParse (will not throw)
const safeInvalidContentType = safeParse('invalid-type;');
console.log('Parsed (safe):', safeInvalidContentType); // { type: '', parameters: {} }

// Example 4: Another valid header with safeParse
const safeContentType = safeParse('text/html; boundary="foo"');
console.log('Parsed (safe):', safeContentType); // { type: 'text/html', parameters: { boundary: 'foo' } }