HTTP Media Type

A utility library for processing HTTP and MIME media types.

Key features

• Parse and format media types according to RFC 7231, RFC 6838.
• Compare for equality and compatibility with other media types.
• Custom process media type parameters in parsing and comparison.

Quick guide

Instantiating

A new media type instance can be created either with separate arguments

const mediaType = new MediaType('text', 'plain')
// text/plain

const mediaType = new MediaType('text')
// text/*

const mediaType = new MediaType()
// */*

const mediaType = new MediaType('text', 'plain', {
	charset: 'utf-8'
})
// text/plain; charset=utf-8

... or with a single combined argument.

const mediaType = new MediaType({
	type: 'text',
	subtype: 'plain'
})
// text/plain

const mediaType = new MediaType({
	type: 'application',
	subtype: 'vnd.company.media',
	suffix: 'format',
	parameters: {
		version: 1
	}
})
// application/vnd.company.media+format; version=1

Parsing

A new media type instance can be parsed from a string

const mediaType = MediaType.parse('application/vnd.company.media+format; version=1')

... and with additional parameter processing

const mediaType = MediaType.parse('application/vnd.company.media+format; version=1; embedded=other-content; q=0.9',
	(parameter, value) => {
		switch (parameter) {
			case 'version':
				// convert 'version' to int
				return Number.parseInt(value)
			case 'q':
				// ignore 'q'
				return undefined
			default:
				// store other parmeter values as strings
				return value
		}
	})

Formatting

The formatted property holds the textual representation of a media type instance

const mediaType = ('application', 'vnd.company.media', {
	version: 2,
	embedded: 'other-media'
})

console.log(mediaType.formatted)
// application/vnd.company.media; version=2; embedded=other-media

Parameters

Media type parameters are case-insensitive when individually accessed with property accessors or with in operator

const mediaType = new MediaType('application/json; CharSet=utf-8; VARIANT=HAL')
const charset = mediaType.parameters.charset
// utf-8

const hasVariant = 'Variant' in mediaType.parameters
// true

... but preserve letter case when iterated or retrieved altogether

const mediaType = new MediaType('application/json; CharSet=utf-8; VARIANT=HAL')
for (const parameter in mediaType.parameters) {
	// CharSet
	// VARIANT
}

const prameters = Object.keys(mediaType.parameters)
// ['CharSet', 'VARIANT']

Comparison

Media type instances can be compared for equality using the equals method

const mediaType1 = new MediaType('text', 'plain')
const mediaType2 = MediaType.parse('text/plain')
mediaType1.equals(mediaType2)
// true

const mediaType1 = new MediaType('text', 'plain')
const mediaType2 = MediaType.parse('text/plain; charset=utf-8')
mediaType1.equals(mediaType2)
// false

const mediaType1 = new MediaType('text', 'plain')
const mediaType2 = MediaType.parse('text/*')
mediaType1.equals(mediaType2)
// false

...and with custom parameter value comparison

const mediaType1 = MediaType.parse('text/plain; charset=UTF-8; version=2')
const mediaType2 = MediaType.parse('text/plain; charset=utf-8')

mediaType1.equals(mediaType2)
// false

mediaType1.equals(mediaType2, (parameter, value1, value2) => {
	// ignore 'version' parameter
	// compare other parameters as case-insensitive
	return parameter === 'version'
		|| value1.toLowerCase() === value2.toLowerCase()
})
// true

Comparison with wildcards

Media types can be compared to media types with wildcards (*) using the matches method.

const mediaType1 = MediaType.parse('text/plain; encoding=none')
const mediaType2 = MediaType.parse('text/*; charset=utf-8; encoding=zip')

mediaType1.equals(mediaType2)
// false

mediaType1.matches(mediaType2)
// true

An custom parameter value comparison can be applied, just like in the equals method.

License

MIT