or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-media-typer

Simple RFC 6838 media type parser and formatter

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/media-typer@1.1.x

To install, run

npx @tessl/cli install tessl/npm-media-typer@1.1.0

index.mddocs/

Media Typer

Media Typer is a lightweight RFC 6838 compliant media type parser and formatter for Node.js applications. It provides utilities to parse media type strings (like 'image/svg+xml') into structured objects containing type, subtype, and suffix components, and format objects back into valid media type strings.

Package Information

  • Package Name: media-typer
  • Package Type: npm
  • Language: JavaScript
  • Installation: npm install media-typer

Core Imports

var typer = require('media-typer');

For destructuring:

const { parse, format, test } = require('media-typer');

Basic Usage

var typer = require('media-typer');

// Parse media type string
var obj = typer.parse('image/svg+xml');
// Result: { type: 'image', subtype: 'svg', suffix: 'xml' }

// Format object back to string
var str = typer.format({ type: 'image', subtype: 'svg', suffix: 'xml' });
// Result: 'image/svg+xml'

// Test if string is valid media type
var isValid = typer.test('image/svg+xml');
// Result: true

Architecture

Media Typer is built around three core functions that handle the complete media type lifecycle:

  • Parser: Converts strings to structured objects using RFC 6838 compliant regex
  • Formatter: Constructs valid media type strings from objects with validation
  • Validator: Tests string format compliance without full parsing
  • Internal Validation: Uses regex patterns for type, subtype, and suffix validation

Capabilities

Media Type Parsing

Parses media type strings into structured objects with type, subtype, and optional suffix components.

/**
 * Parse media type string into structured object
 * @param {string} string - Media type string to parse (required)
 * @returns {MediaType} Object with type, subtype, and optional suffix properties
 * @throws {TypeError} If string is invalid or not provided
 */
function parse(string);

/**
 * MediaType object returned by parse()
 * @typedef {Object} MediaType
 * @property {string} type - Main type (always lowercase)
 * @property {string} subtype - Subtype (always lowercase)
 * @property {string} [suffix] - Optional suffix (always lowercase)
 */

Usage Examples:

var typer = require('media-typer');

// Basic media type
var obj = typer.parse('text/html');
// Result: { type: 'text', subtype: 'html' }

// Media type with suffix
var obj = typer.parse('image/svg+xml');
// Result: { type: 'image', subtype: 'svg', suffix: 'xml' }

// Complex media type
var obj = typer.parse('application/vnd.api+json');
// Result: { type: 'application', subtype: 'vnd.api', suffix: 'json' }

// Error handling
try {
  typer.parse('invalid/media/type');
} catch (err) {
  // TypeError: invalid media type
}

Media Type Formatting

Formats objects with type, subtype, and optional suffix into valid media type strings.

/**
 * Format object into media type string
 * @param {Object} obj - Object with type, subtype, and optional suffix properties (required)
 * @param {string} obj.type - Main type (required)
 * @param {string} obj.subtype - Subtype (required)
 * @param {string} [obj.suffix] - Optional suffix
 * @returns {string} Valid media type string
 * @throws {TypeError} If object is invalid, required properties missing, or properties are invalid
 */
function format(obj);

Usage Examples:

var typer = require('media-typer');

// Basic formatting
var str = typer.format({ type: 'text', subtype: 'html' });
// Result: 'text/html'

// With suffix
var str = typer.format({ type: 'image', subtype: 'svg', suffix: 'xml' });
// Result: 'image/svg+xml'

// Error handling
try {
  typer.format({ type: 'text' }); // Missing subtype
} catch (err) {
  // TypeError: invalid subtype
}

try {
  typer.format({ type: 'text/', subtype: 'html' }); // Invalid type
} catch (err) {
  // TypeError: invalid type
}

Media Type Validation

Tests if strings conform to RFC 6838 media type format without full parsing.

/**
 * Test if string is valid media type format
 * @param {string} string - String to validate (required)
 * @returns {boolean} True if valid media type, false otherwise
 * @throws {TypeError} If string is not provided or not a string
 */
function test(string);

Usage Examples:

var typer = require('media-typer');

// Valid media types
typer.test('text/html'); // true
typer.test('image/svg+xml'); // true
typer.test('application/vnd.api+json'); // true

// Invalid media types
typer.test('text'); // false
typer.test('text/'); // false
typer.test('/html'); // false
typer.test('text/html/extra'); // false
typer.test(''); // false

// Error handling
try {
  typer.test(123); // Not a string
} catch (err) {
  // TypeError: argument string is required to be a string
}

Types

/**
 * MediaType class - objects returned by parse()
 * This constructor is not directly exported, instances are created by parse()
 * @constructor
 * @param {string} type - Main type
 * @param {string} subtype - Subtype  
 * @param {string} [suffix] - Optional suffix
 */
class MediaType {
  constructor(type, subtype, suffix);
  type: string;
  subtype: string;
  suffix?: string;
}

Error Handling

All functions throw TypeError for various error conditions:

  • Missing arguments: When required parameters are not provided
  • Invalid argument types: When arguments are not the expected type (string/object)
  • Invalid media type format: When strings don't conform to RFC 6838 specification
  • Invalid object structure: When format() receives objects with missing or invalid properties

Common error patterns:

// Missing argument errors
typer.parse(); // TypeError: argument string is required
typer.format(); // TypeError: argument obj is required
typer.test(); // TypeError: argument string is required

// Type validation errors
typer.parse(123); // TypeError: argument string is required to be a string
typer.format("string"); // TypeError: argument obj is required
typer.test([]); // TypeError: argument string is required to be a string

// Format validation errors
typer.parse("invalid"); // TypeError: invalid media type
typer.format({ type: "text" }); // TypeError: invalid subtype
typer.format({ type: "text/", subtype: "html" }); // TypeError: invalid type