{"id":16151,"library":"node-tnef","title":"TNEF Parser for Node.js","description":"node-tnef is a Node.js library designed to parse Transport Neutral Encapsulation Format (TNEF) files, commonly encountered as `winmail.dat` attachments in emails. This proprietary Microsoft format is often sent by Outlook users but is not natively understood by other email clients. The library extracts embedded content and attachments from these files, addressing a niche but persistent interoperability problem. It offers both a command-line interface for direct file or directory parsing and a programmatic API for use within Node.js projects, primarily through its `parse` (for file paths) and `parseBuffer` (for in-memory buffers) methods. The current stable version is 1.4.0. The package maintains an ad-hoc release cadence, focusing on bug fixes and feature enhancements, such as the addition of `parseBuffer` in version 1.3.0 and the removal of the `bluebird` dependency in 1.4.0.","status":"active","version":"1.4.0","language":"javascript","source_language":"en","source_url":"https://github.com/gatewayapps/node-tnef","tags":["javascript","tnef","node","parser","email"],"install":[{"cmd":"npm install node-tnef","lang":"bash","label":"npm"},{"cmd":"yarn add node-tnef","lang":"bash","label":"yarn"},{"cmd":"pnpm add node-tnef","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"This module is primarily designed for CommonJS. Direct ESM import syntax is not officially documented or guaranteed to work without specific Node.js configuration for CJS interoperability.","wrong":"import tnef from 'node-tnef'","symbol":"tnef","correct":"const tnef = require('node-tnef')"},{"note":"The `parse` method is a property of the main module object, not a top-level named export. Attempting to destructure it as a named export from an ESM import will likely result in a runtime error.","wrong":"import { parse } from 'node-tnef'","symbol":"tnef.parse","correct":"const tnef = require('node-tnef');\ntnef.parse('/path/to/winmail.dat', (err, content) => { /* ... */ });"},{"note":"The `parseBuffer` method, introduced in v1.3.0, is accessed as a property of the main module object. It is not a named export directly from the module.","wrong":"import { parseBuffer } from 'node-tnef'","symbol":"tnef.parseBuffer","correct":"const tnef = require('node-tnef');\ntnef.parseBuffer(yourBuffer, (err, content) => { /* ... */ });"}],"quickstart":{"code":"const tnef = require('node-tnef');\nconst fs = require('fs');\nconst path = require('path');\n\n// A minimal, valid TNEF signature prefix for demonstration.\n// A real winmail.dat file would be much larger and complex.\nconst dummyTnefBuffer = Buffer.from(\n  '\\x22\\x34\\x71\\x9A\\x00\\x00\\x00\\x00\\x01\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00',\n  'binary'\n);\n\ntnef.parseBuffer(dummyTnefBuffer, (err, content) => {\n  if (err) {\n    console.error('Error parsing TNEF buffer:', err);\n    return;\n  }\n\n  if (content && content.length > 0) {\n    console.log(`Found ${content.length} attachment(s).`);\n    const firstAttachment = content[0];\n    console.log('First attachment title:', firstAttachment.Title);\n\n    // Example: Writing the attachment data to a file\n    const outputPath = path.join(__dirname, firstAttachment.Title || 'extracted_attachment.bin');\n    fs.writeFile(outputPath, firstAttachment.Data, (writeErr) => {\n      if (writeErr) {\n        console.error('Error writing attachment to file:', writeErr);\n      } else {\n        console.log(`Attachment written to: ${outputPath}`);\n      }\n    });\n  } else {\n    console.log('No attachments or content found in TNEF buffer.');\n  }\n});\n","lang":"javascript","description":"Demonstrates how to use `tnef.parseBuffer` to process an in-memory TNEF buffer and extract its contents, including writing an attachment to a file."},"warnings":[{"fix":"Use Node.js's `util.promisify` to convert the callback-based methods into Promise-returning functions if `async/await` is desired, or adhere to the callback pattern.","message":"The library utilizes a callback-based asynchronous API (`(err, content) => { ... }`) for its `parse` and `parseBuffer` methods. Modern Node.js development often favors Promises or async/await syntax. Developers expecting Promise-based functions will need to wrap the callback-based methods or adapt their code accordingly.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"If your project implicitly relied on `bluebird` through `node-tnef`, explicitly install `bluebird` as a direct dependency or migrate to native Promises where appropriate. The library itself now uses native Node.js asynchronous patterns.","message":"In version 1.4.0, the `bluebird` promise library was removed as a dependency. While primarily an internal change for promise management, if any consuming application had an implicit reliance on `bluebird` being present or its specific promise behavior when interacting with `node-tnef`'s internals, this could lead to unexpected behavior.","severity":"breaking","affected_versions":">=1.4.0"},{"fix":"Before passing files to `tnef.parse`, consider pre-validating their content or implementing custom error handling in your callback to differentiate between actual parsing failures and non-TNEF files.","message":"When processing files or directories, `node-tnef` explicitly checks for the TNEF signature. If a file does not contain this signature, the parser will log a message to the console and skip the file without throwing an error in the programmatic API. Users should implement their own validation if specific error handling for non-TNEF files is required.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"For `node-tnef` v1.4.0 and later, `bluebird` is no longer a dependency. If your project still requires `bluebird`, install it explicitly: `npm install bluebird`.","cause":"An application (or an older version of node-tnef) implicitly or explicitly expected `bluebird` to be available, but it was removed in v1.4.0 or not installed.","error":"Error: Cannot find module 'bluebird'"},{"fix":"Ensure you are using the CommonJS `require` syntax and accessing methods as properties: `const tnef = require('node-tnef'); tnef.parse(...);`","cause":"This error often occurs when attempting to use ESM `import { parse } from 'node-tnef'` or similar destructuring, but the module primarily exposes an object via CommonJS `module.exports` or properties on `module.exports`.","error":"TypeError: tnef.parse is not a function"},{"fix":"Always provide a callback function in the format `(err, content) => { ... }` as the second argument to `tnef.parse` and `tnef.parseBuffer`.","cause":"The `parse` or `parseBuffer` method was called without providing a valid callback function as its second argument, or the provided argument was not a function.","error":"Error: callback is not a function"},{"fix":"Verify that the file you are attempting to parse is indeed a TNEF-encoded file (e.g., typically named `winmail.dat`). The library will skip non-TNEF files without throwing a programmatic error, but logs this message to the console.","cause":"The input file specified to `tnef.parse` (or a file within a directory scanned by the CLI) was not a valid TNEF file. The library detected that the file did not begin with the expected TNEF magic number.","error":"file does not contain the TNEF signature"}],"ecosystem":"npm"}