TNEF Parser for Node.js

Common errors

• Error: Cannot find module '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.
  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`.

• TypeError: tnef.parse is not a function

  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`.
  fix Ensure you are using the CommonJS `require` syntax and accessing methods as properties: `const tnef = require('node-tnef'); tnef.parse(...);`

• Error: callback is not a function

  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.
  fix Always provide a callback function in the format `(err, content) => { ... }` as the second argument to `tnef.parse` and `tnef.parseBuffer`.

• file does not contain the TNEF signature

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

Warnings

• gotcha 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.
  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.
• breaking 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.
  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.
• gotcha 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.
  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.

Install

• npm install node-tnef npm
• yarn add node-tnef yarn
• pnpm add node-tnef pnpm

Imports

• tnef
  wrong:

  import tnef from 'node-tnef'

  correct:

  const tnef = require('node-tnef')

  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.
• tnef.parse
  wrong:

  import { parse } from 'node-tnef'

  correct:

  const tnef = require('node-tnef');
  tnef.parse('/path/to/winmail.dat', (err, content) => { /* ... */ });

  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.
• tnef.parseBuffer
  wrong:

  import { parseBuffer } from 'node-tnef'

  correct:

  const tnef = require('node-tnef');
  tnef.parseBuffer(yourBuffer, (err, content) => { /* ... */ });

  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.

Quickstart

Demonstrates how to use `tnef.parseBuffer` to process an in-memory TNEF buffer and extract its contents, including writing an attachment to a file.

const tnef = require('node-tnef');
const fs = require('fs');
const path = require('path');

// A minimal, valid TNEF signature prefix for demonstration.
// A real winmail.dat file would be much larger and complex.
const dummyTnefBuffer = Buffer.from(
  '\x22\x34\x71\x9A\x00\x00\x00\x00\x01\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00',
  'binary'
);

tnef.parseBuffer(dummyTnefBuffer, (err, content) => {
  if (err) {
    console.error('Error parsing TNEF buffer:', err);
    return;
  }

  if (content && content.length > 0) {
    console.log(`Found ${content.length} attachment(s).`);
    const firstAttachment = content[0];
    console.log('First attachment title:', firstAttachment.Title);

    // Example: Writing the attachment data to a file
    const outputPath = path.join(__dirname, firstAttachment.Title || 'extracted_attachment.bin');
    fs.writeFile(outputPath, firstAttachment.Data, (writeErr) => {
      if (writeErr) {
        console.error('Error writing attachment to file:', writeErr);
      } else {
        console.log(`Attachment written to: ${outputPath}`);
      }
    });
  } else {
    console.log('No attachments or content found in TNEF buffer.');
  }
});