0
# Media Typer
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: media-typer
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install media-typer`
10

11
## Core Imports
12

13
```javascript
14
var typer = require('media-typer');
15
```
16

17
For destructuring:
18

19
```javascript
20
const { parse, format, test } = require('media-typer');
21
```
22

23
## Basic Usage
24

25
```javascript
26
var typer = require('media-typer');
27

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

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

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

41
## Architecture
42

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

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

50
## Capabilities
51

52
### Media Type Parsing
53

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

56
```javascript { .api }
57
/**
58
 * Parse media type string into structured object
59
 * @param {string} string - Media type string to parse (required)
60
 * @returns {MediaType} Object with type, subtype, and optional suffix properties
61
 * @throws {TypeError} If string is invalid or not provided
62
 */
63
function parse(string);
64

65
/**
66
 * MediaType object returned by parse()
67
 * @typedef {Object} MediaType
68
 * @property {string} type - Main type (always lowercase)
69
 * @property {string} subtype - Subtype (always lowercase)
70
 * @property {string} [suffix] - Optional suffix (always lowercase)
71
 */
72
```
73

74
**Usage Examples:**
75

76
```javascript
77
var typer = require('media-typer');
78

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

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

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

91
// Error handling
92
try {
93
  typer.parse('invalid/media/type');
94
} catch (err) {
95
  // TypeError: invalid media type
96
}
97
```
98

99
### Media Type Formatting
100

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

103
```javascript { .api }
104
/**
105
 * Format object into media type string
106
 * @param {Object} obj - Object with type, subtype, and optional suffix properties (required)
107
 * @param {string} obj.type - Main type (required)
108
 * @param {string} obj.subtype - Subtype (required)
109
 * @param {string} [obj.suffix] - Optional suffix
110
 * @returns {string} Valid media type string
111
 * @throws {TypeError} If object is invalid, required properties missing, or properties are invalid
112
 */
113
function format(obj);
114
```
115

116
**Usage Examples:**
117

118
```javascript
119
var typer = require('media-typer');
120

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

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

129
// Error handling
130
try {
131
  typer.format({ type: 'text' }); // Missing subtype
132
} catch (err) {
133
  // TypeError: invalid subtype
134
}
135

136
try {
137
  typer.format({ type: 'text/', subtype: 'html' }); // Invalid type
138
} catch (err) {
139
  // TypeError: invalid type
140
}
141
```
142

143
### Media Type Validation
144

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

147
```javascript { .api }
148
/**
149
 * Test if string is valid media type format
150
 * @param {string} string - String to validate (required)
151
 * @returns {boolean} True if valid media type, false otherwise
152
 * @throws {TypeError} If string is not provided or not a string
153
 */
154
function test(string);
155
```
156

157
**Usage Examples:**
158

159
```javascript
160
var typer = require('media-typer');
161

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

167
// Invalid media types
168
typer.test('text'); // false
169
typer.test('text/'); // false
170
typer.test('/html'); // false
171
typer.test('text/html/extra'); // false
172
typer.test(''); // false
173

174
// Error handling
175
try {
176
  typer.test(123); // Not a string
177
} catch (err) {
178
  // TypeError: argument string is required to be a string
179
}
180
```
181

182
## Types
183

184
```javascript { .api }
185
/**
186
 * MediaType class - objects returned by parse()
187
 * This constructor is not directly exported, instances are created by parse()
188
 * @constructor
189
 * @param {string} type - Main type
190
 * @param {string} subtype - Subtype  
191
 * @param {string} [suffix] - Optional suffix
192
 */
193
class MediaType {
194
  constructor(type, subtype, suffix);
195
  type: string;
196
  subtype: string;
197
  suffix?: string;
198
}
199
```
200

201
## Error Handling
202

203
All functions throw `TypeError` for various error conditions:
204

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

210
Common error patterns:
211

212
```javascript
213
// Missing argument errors
214
typer.parse(); // TypeError: argument string is required
215
typer.format(); // TypeError: argument obj is required
216
typer.test(); // TypeError: argument string is required
217

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

223
// Format validation errors
224
typer.parse("invalid"); // TypeError: invalid media type
225
typer.format({ type: "text" }); // TypeError: invalid subtype
226
typer.format({ type: "text/", subtype: "html" }); // TypeError: invalid type
227
```