0
# mime-types
1

2
The ultimate javascript content-type utility for MIME type lookups, extensions mapping, and charset detection. It provides comprehensive MIME type functionality without fallbacks, returning false for unrecognized types to enable explicit error handling.
3

4
## Package Information
5

6
- **Package Name**: mime-types
7
- **Package Type**: npm
8
- **Language**: JavaScript (Node.js)
9
- **Installation**: `npm install mime-types`
10

11
## Core Imports
12

13
```javascript
14
const mime = require('mime-types');
15
```
16

17
For ES modules:
18

19
```javascript
20
import mime from 'mime-types';
21
```
22

23
Individual function imports:
24

25
```javascript
26
const { lookup, contentType, extension, charset } = require('mime-types');
27
```
28

29
## Basic Usage
30

31
```javascript
32
const mime = require('mime-types');
33

34
// Look up MIME type from file extension
35
const type = mime.lookup('json'); // 'application/json'
36
const htmlType = mime.lookup('file.html'); // 'text/html'
37

38
// Create content-type header with charset
39
const header = mime.contentType('json'); // 'application/json; charset=utf-8'
40

41
// Get file extension from MIME type
42
const ext = mime.extension('text/html'); // 'html'
43

44
// Get default charset for a MIME type
45
const charset = mime.charset('text/html'); // 'UTF-8'
46

47
// Access lookup maps directly
48
const jsonType = mime.types['json']; // 'application/json'
49
const htmlExts = mime.extensions['text/html']; // ['html', 'htm']
50
```
51

52
## Capabilities
53

54
### MIME Type Lookup
55

56
Look up the MIME type for a file path, extension, or filename.
57

58
```javascript { .api }
59
/**
60
 * Lookup the MIME type for a file path/extension
61
 * @param {string} path - File path, extension, or filename
62
 * @returns {string|false} MIME type or false if not found
63
 */
64
function lookup(path);
65
```
66

67
**Usage Examples:**
68

69
```javascript
70
mime.lookup('json'); // 'application/json'
71
mime.lookup('.md'); // 'text/markdown'
72
mime.lookup('file.html'); // 'text/html'
73
mime.lookup('folder/file.js'); // 'application/javascript'
74
mime.lookup('folder/.htaccess'); // false
75
mime.lookup('unknown-extension'); // false
76
```
77

78
### Content-Type Header Generation
79

80
Create a full Content-Type header with appropriate charset from a MIME type or extension.
81

82
```javascript { .api }
83
/**
84
 * Create a full Content-Type header given a MIME type or extension
85
 * @param {string} str - MIME type or file extension
86
 * @returns {string|false} Full content-type header or false if invalid
87
 */
88
function contentType(str);
89
```
90

91
**Usage Examples:**
92

93
```javascript
94
// From extension
95
mime.contentType('markdown'); // 'text/x-markdown; charset=utf-8'
96
mime.contentType('file.json'); // 'application/json; charset=utf-8'
97

98
// From MIME type
99
mime.contentType('text/html'); // 'text/html; charset=utf-8'
100

101
// Preserves existing charset
102
mime.contentType('text/html; charset=iso-8859-1'); // 'text/html; charset=iso-8859-1'
103

104
// From full path extension
105
const path = require('path');
106
mime.contentType(path.extname('/path/to/file.json')); // 'application/json; charset=utf-8'
107

108
// Invalid input
109
mime.contentType('unknown'); // false
110
```
111

112
### Extension Lookup
113

114
Get the default file extension for a MIME type.
115

116
```javascript { .api }
117
/**
118
 * Get the default extension for a MIME type
119
 * @param {string} type - MIME type
120
 * @returns {string|false} File extension or false if not found
121
 */
122
function extension(type);
123
```
124

125
**Usage Examples:**
126

127
```javascript
128
mime.extension('application/octet-stream'); // 'bin'
129
mime.extension('text/html'); // 'html'
130
mime.extension('application/json'); // 'json'
131
mime.extension('image/png'); // 'png'
132
mime.extension('unknown/type'); // false
133
```
134

135
### Charset Detection
136

137
Get the default charset for a MIME type.
138

139
```javascript { .api }
140
/**
141
 * Get the default charset for a MIME type
142
 * @param {string} type - MIME type
143
 * @returns {string|false} Charset or false if no default charset
144
 */
145
function charset(type);
146
```
147

148
**Usage Examples:**
149

150
```javascript
151
mime.charset('text/html'); // 'UTF-8'
152
mime.charset('application/json'); // 'UTF-8'
153
mime.charset('text/markdown'); // 'UTF-8'
154
mime.charset('application/javascript'); // 'UTF-8'
155

156
// Text types default to UTF-8
157
mime.charset('text/x-custom'); // 'UTF-8'
158

159
// Binary types have no default charset
160
mime.charset('application/octet-stream'); // false
161
mime.charset('image/png'); // false
162

163
// Unknown types return false
164
mime.charset('unknown/type'); // false
165
```
166

167
### Type Maps
168

169
Direct access to extension-to-type and type-to-extensions mappings.
170

171
```javascript { .api }
172
/**
173
 * Map of file extensions to MIME types
174
 * @type {Object<string, string>}
175
 */
176
const types;
177

178
/**
179
 * Map of MIME types to arrays of file extensions
180
 * @type {Object<string, string[]>}
181
 */
182
const extensions;
183
```
184

185
**Usage Examples:**
186

187
```javascript
188
// Extension to MIME type lookup
189
mime.types['json']; // 'application/json'
190
mime.types['html']; // 'text/html'
191
mime.types['js']; // 'application/javascript'
192

193
// MIME type to extensions lookup
194
mime.extensions['text/html']; // ['html', 'htm']
195
mime.extensions['application/javascript']; // ['js', 'mjs']
196
mime.extensions['image/jpeg']; // ['jpeg', 'jpg']
197

198
// Check if extension exists
199
if (mime.types['pdf']) {
200
  console.log('PDF MIME type:', mime.types['pdf']); // 'application/pdf'
201
}
202
```
203

204
### Legacy Compatibility
205

206
Compatibility object for legacy charset lookup patterns.
207

208
```javascript { .api }
209
/**
210
 * Legacy compatibility object with lookup method
211
 * @type {Object}
212
 */
213
const charsets;
214
```
215

216
**Usage:**
217

218
```javascript
219
// Legacy charset lookup (same as charset function)  
220
mime.charsets.lookup('text/html'); // 'UTF-8'
221
```
222

223
### Extension Conflicts Debugging
224

225
Internal array for tracking extension-to-type mapping changes during MIME score resolution.
226

227
```javascript { .api }
228
/**
229
 * Array tracking extension conflicts between legacy and new type resolution
230
 * @type {Array<[string, string, string]>}
231
 * @private
232
 * @deprecated This is a temporary debugging tool and may be removed in future versions
233
 */
234
const _extensionConflicts;
235
```
236

237
**Usage:**
238

239
```javascript
240
// Access conflicts that occurred during type resolution
241
const conflicts = mime._extensionConflicts;
242
// Each conflict is [extension, legacyType, newType]
243
// Example: ['m4a', 'audio/mp4', 'audio/x-m4a']
244

245
// Mainly used for development and debugging
246
console.log('Extension conflicts:', conflicts.length);
247
conflicts.forEach(([ext, legacy, current]) => {
248
  console.log(`Extension .${ext}: ${legacy} -> ${current}`);
249
});
250
```
251

252
## Error Handling
253

254
All functions return `false` for invalid input instead of throwing errors:
255

256
```javascript
257
// Invalid input types
258
mime.lookup(null); // false
259
mime.lookup({}); // false
260
mime.lookup(42); // false
261
mime.lookup(''); // false
262

263
mime.contentType(undefined); // false
264
mime.extension(true); // false
265
mime.charset([]); // false
266

267
// Unknown extensions/types
268
mime.lookup('unknown-ext'); // false
269
mime.extension('unknown/type'); // false
270
```
271

272
## Type Resolution
273

274
mime-types uses a sophisticated scoring system to resolve conflicts when multiple MIME types map to the same extension:
275

276
- Prefers official IANA types over other sources
277
- Uses mime-score algorithm for consistent type selection
278
- Avoids application/octet-stream when more specific types are available
279
- Shorter MIME type names are preferred when scores are equal
280

281
## API Behavior
282

283
- **Case Insensitive**: Extension and MIME type lookups are case-insensitive
284
- **Path Handling**: Full file paths are supported (extension is extracted)
285
- **Dot Handling**: Extensions work with or without leading dots
286
- **No Fallbacks**: Returns `false` for unrecognized input rather than guessing
287
- **Charset Detection**: Text types default to UTF-8, binary types return false
288
- **Thread Safe**: All operations are stateless and thread-safe