mime-types

mime-types is a small, dependency-light Node.js utility that maps between file extensions and MIME content types. Built on top of the canonical mime-db dataset, it lets you look up the content type for a path, build a complete Content-Type header with the right charset, and find the default extension for a given type.

Unlike naive alternatives, it never guesses: every function returns false for unknown or invalid input, so you stay in full control of fallbacks. Its tiny, function-based API has made it a foundational building block across the Node.js ecosystem, powering frameworks like Express and countless file-serving and upload pipelines.

What You Get

• Extension-to-MIME lookup via mime.lookup(path) that accepts bare extensions, dotted extensions, or full file paths
• Full Content-Type header construction with mime.contentType(type), automatically appending the correct charset
• Reverse mime.extension(type) lookup to get the default file extension for any MIME type
• Charset resolution with mime.charset(type) plus direct mime.types and mime.extensions maps for custom logic

Common Use Cases

• Setting the correct Content-Type response header when serving static files from a Node.js server
• Validating and labelling uploaded files by mapping their extension to an expected MIME type
• Choosing a sensible file extension when saving a downloaded resource identified only by its content type

Under The Hood

Architecture - The entire library lives in a single index.js that, at load time, calls populateMaps() to iterate every entry in the mime-db database and build two lookup tables on the exported object: types (extension to MIME type) and extensions (MIME type to extension list). Public functions lookup, contentType, extension, and charset are thin readers over these maps, with lookup normalizing input via Node’s path.extname('x.' + path) trick and a shared EXTRACT_TYPE_REGEXP stripping parameters from content types. When two types claim the same extension, _preferredType() in mimeScore.js resolves the conflict deterministically.

Tech Stack - Plain CommonJS JavaScript targeting Node.js >= 18 with a single runtime dependency, mime-db (^1.54.0), which supplies the underlying type data. mimeScore.js is a back-ported, dependency-free scoring function. Development tooling uses Mocha and nyc for tests and coverage, and ESLint with the Standard config for linting; there is no build step or transpilation.

Code Quality - The codebase is small, readable, and thoroughly covered by a 247-line Mocha suite in test/test.js exercising every public function across valid, invalid, and edge-case inputs. Input guards consistently reject non-string arguments by returning false, and functions are documented with JSDoc annotations. A small amount of transitional legacy code (_preferredTypeLegacy, _extensionConflicts) remains from a scoring migration.

API Design - The public surface is intentionally minimal: four functions plus two data maps, all destructurable directly from the module because nothing is stateful or class-based. Every function follows the same contract of returning false on failure, which makes fallback handling explicit and predictable. The API is deliberately compatible with the older mime@1.x module while removing its implicit fallbacks, and the README documents each function with concrete examples.