{"id":16437,"library":"mime-format","title":"MIME Format Lookup","description":"The `mime-format` library provides a utility for disambiguating the base format of HTTP response bodies based on their `Content-Type` header. It aims to resolve ambiguities, especially between `text/*` and `application/*` types, by maintaining an internal database of textual content types served under `application/*` (e.g., `application/json` is classified as `text`). The current stable version is 2.0.2, with releases appearing to be on an as-needed basis, indicated by the significant gap between v0.2.0 and v2.0.0. Key differentiators include its explicit handling of `application/*` types that are textual in nature, and its ability to guess or mark content types as unknown if they are not in its database, providing granular control over content interpretation.","status":"active","version":"2.0.2","language":"javascript","source_language":"en","source_url":"https://github.com/postmanlabs/mime-format","tags":["javascript","postman","http-code","mime","content-type"],"install":[{"cmd":"npm install mime-format","lang":"bash","label":"npm"},{"cmd":"yarn add mime-format","lang":"bash","label":"yarn"},{"cmd":"pnpm add mime-format","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The library is a CommonJS module that exports a default object/function, typically imported as `mimeFormat` in ESM. The `lookup` method is accessed directly on this imported object.","wrong":"import { lookup } from 'mime-format';","symbol":"mimeFormat","correct":"import mimeFormat from 'mime-format';"},{"note":"This is the standard CommonJS import pattern, as shown in the package's documentation. The package's `package.json` specifies `\"type\": \"commonjs\"`.","symbol":"mimeFormat","correct":"const mimeFormat = require('mime-format');"},{"note":"The `lookup` function is a method of the default exported `mimeFormat` object, not a named export itself.","wrong":"import { lookup } from 'mime-format'; lookup('application/json');","symbol":"lookup","correct":"import mimeFormat from 'mime-format'; mimeFormat.lookup('application/json');"}],"quickstart":{"code":"const mimeFormat = require('mime-format');\n\n// Look up a common XML content type with charset\nconst xmlResult = mimeFormat.lookup('application/xml; charset=gBk');\nconsole.log('XML result:', xmlResult);\n/*\nOutput:\n{\n  \"type\": \"text\",\n  \"format\": \"xml\",\n  \"charset\": \"gBk\"\n}\n*/\n\n// Example for a JSON content type, which it classifies as 'text'\nconst jsonResult = mimeFormat.lookup('application/json');\nconsole.log('JSON result:', jsonResult);\n/*\nOutput:\n{\n  \"type\": \"text\",\n  \"format\": \"json\"\n}\n*/\n\n// Example for an unknown content type, demonstrating 'guessed' or 'unknown'\nconst unknownResult = mimeFormat.lookup('application/x-custom-format');\nconsole.log('Unknown result:', unknownResult);\n/*\nOutput (may vary slightly based on internal logic):\n{\n  \"type\": \"application\",\n  \"format\": \"raw\",\n  \"guessed\": true\n}\n*/","lang":"javascript","description":"This quickstart demonstrates how to use `mime-format` to identify the base type, specific format, and charset from various `Content-Type` headers, including known types and those requiring guessing."},"warnings":[{"fix":"Consult the GitHub repository's commit history or `package.json` for details on API changes if migrating from pre-v1.0 or v1.x versions.","message":"The package underwent significant breaking changes between v0.x (e.g., v0.2.0 from 2017) and v2.x (released in 2024). Users migrating from older versions should review the API for changes, as the provided release notes are minimal for this major version bump.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Always check the `guessed` and `unknown` flags in the returned object, and implement fallback logic for unlisted or custom content types.","message":"When the `Content-Type` is not in the internal database, the module attempts to guess the format, returning `guessed: true`. If guessing fails, `unknown: true` and `format: 'raw'` are returned. Relying on an exact format without checking these flags can lead to unexpected handling of obscure or custom MIME types.","severity":"gotcha","affected_versions":">=0.2.0"},{"fix":"Prioritize the `type` property for broad content categorization. Use `format` only when a specific textual syntax (like 'json', 'xml') is relevant and expected.","message":"The `format` property, especially for `type: 'text'`, indicates the syntax (e.g., 'json', 'xml'). However, for some types, or when a specific text syntax isn't detected, it might return 'raw', which the documentation notes can be redundant for most cases. Primarily rely on the `type` property for general classification.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Ensure that the `contentType` argument passed to `mimeFormat.lookup()` is always a valid string representing an HTTP `Content-Type` header.","message":"Passing non-string values to the `lookup` method for the `contentType` argument will result in them being typecast to `String`. While this prevents immediate errors, it can lead to incorrect or unexpected format detection if the string representation is not a valid `Content-Type` header.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"For CommonJS: `const mimeFormat = require('mime-format');`. For ESM: `import mimeFormat from 'mime-format';`. Then access the method as `mimeFormat.lookup(...)`.","cause":"Attempting to destructure `lookup` from the module when it's a default export of an object or function, or incorrectly importing in an ESM context.","error":"TypeError: mimeFormat.lookup is not a function"},{"fix":"Either configure your Node.js project for ES modules by setting `\"type\": \"module\"` in `package.json` (and use `.mjs` or `.js` files), or switch to `require()` syntax: `const mimeFormat = require('mime-format');`.","cause":"Using `import` syntax in a CommonJS module (e.g., a `.js` file without `\"type\": \"module\"` in `package.json` or a `.cjs` file).","error":"SyntaxError: Cannot use import statement outside a module"},{"fix":"Double-check the exact `Content-Type` string being passed. If it's valid but not recognized, `mime-format` will resort to guessing or marking as unknown, which is its intended behavior for unlisted types. Consider contributing to the library's database for widely used missing types.","cause":"The `Content-Type` string might contain unusual parameters, be a non-standard but commonly used type not present in the library's internal database, or be subtly malformed.","error":"(No explicit error, but incorrect classification) Received 'format: \"raw\"' or 'unknown: true' for a seemingly standard content type."}],"ecosystem":"npm"}