content-types-lite

Tiny, type-safe HTTP media type constants and utilities for TypeScript and JavaScript. It provides a curated set of common values—not a large file-extension database—and focused helpers for working with Content-Type headers.

• Zero runtime dependencies
• Literal TypeScript types derived from one source of truth
• ESM and CommonJS builds
• Root and tree-shakeable subpath exports
• Safe parsing and formatting of header parameters
• Wildcard and structured-suffix matching
• IANA-registered values with clearly named legacy aliases

Install

npm install content-types-lite

Requires Node.js 18.17 or newer when used in Node. The ESM build also works in modern browsers and bundlers.

Quick start

import contentTypes, {
    JSON,
    formatContentType,
    isJsonLike,
    matchesMediaType,
    parseContentType,
} from 'content-types-lite';

JSON; // 'application/json'
contentTypes.PDF; // 'application/pdf'

formatContentType(JSON, { charset: 'utf-8' });
// 'application/json; charset=utf-8'

parseContentType('Application/Problem+JSON; charset="utf-8"');
// { type: 'application/problem+json', parameters: { charset: 'utf-8' } }

isJsonLike('application/problem+json'); // true
matchesMediaType('application/problem+json', 'application/*+json'); // true

CommonJS is supported:

const { JSON, withCharset } = require('content-types-lite');

withCharset(JSON); // 'application/json; charset=utf-8'

Constants and types

Named constants use literal types. The default export is a frozen object for compatibility with 1.x.

import contentTypes, { type ContentTypeName, type MediaType, JSON } from 'content-types-lite';

const name: ContentTypeName = 'JSON';
const value: MediaType = JSON;

contentTypes[name]; // inferred as 'application/json' | ...

ContentType remains as a deprecated alias of ContentTypeName for compatibility.

The collection includes common text, structured data, multipart, document, archive, image, audio, video, and font types. Browse the typed contentTypes object in your editor for the complete list.

Canonical and legacy values

Canonical constants follow the IANA Media Types registry:

| Constant | Value | | ---------- | ------------------------- | | YAML | application/yaml | | MSGPACK | application/vnd.msgpack | | PROTOBUF | application/protobuf |

Older values remain available when integrating with systems that require them:

| Constant | Value | | ----------------- | ------------------------ | | YAML_LEGACY | application/x-yaml | | MSGPACK_LEGACY | application/x-msgpack | | PROTOBUF_LEGACY | application/x-protobuf | | NDJSON | application/x-ndjson |

Formatting

import { formatContentType, normalizeContentType, withCharset } from 'content-types-lite/format';

withCharset('text/html');
// 'text/html; charset=utf-8'

formatContentType('text/plain', { title: 'hello world' });
// 'text/plain; title="hello world"'

normalizeContentType('Text/HTML; Charset="utf-8"');
// 'text/html; charset=utf-8'

Invalid names, media types, and control characters throw TypeError during formatting. This prevents malformed values and header injection.

Parsing

import { getMediaType, parseContentType } from 'content-types-lite/parse';

parseContentType('text/html; charset=utf-8');
// { type: 'text/html', parameters: { charset: 'utf-8' } }

getMediaType('Text/HTML; Charset=UTF-8');
// 'text/html'

parseContentType('invalid');
// null

Parsing is strict and side-effect free. Duplicate parameters and malformed quoted strings return null.

Matching and guards

import { isJsonLike, isTextual } from 'content-types-lite/guards';
import { matchesMediaType } from 'content-types-lite/match';

matchesMediaType('image/avif', 'image/*'); // true
matchesMediaType('application/problem+json', 'application/*+json'); // true
isJsonLike('application/vnd.api+json'); // true
isTextual('application/yaml'); // true

Available guards are isContentType, isJsonLike, isXmlLike, isTextual, isImage, isAudio, and isVideo.

Multipart form data

In browsers, do not manually set Content-Type: multipart/form-data when sending a FormData body. Let fetch or XMLHttpRequest generate the header so its required boundary matches the encoded body.

The constant is intended for parsing, matching, server-side generation where a boundary is supplied separately, and integrations that explicitly require the bare media type.

Package scope

This package intentionally does not infer a media type from a filename or inspect file contents. Use a comprehensive MIME database or file-signature detector for those jobs. content-types-lite focuses on common HTTP values and correct header handling.

Development

npm ci
npm run check
npm run attw

npm run check runs linting, formatting, static type checks, runtime tests, public type tests, builds, and package validation.

See CONTRIBUTING.md for contribution and media-type inclusion rules.

License

MIT © Mohammad Montasim-Al-Mamun Shuvo