TLV Parser for Node.js

Common errors

• SyntaxError: Cannot use import statement outside a module

  cause Attempting to use ES module `import` syntax in a Node.js environment or file configured for CommonJS, or without transpilation.
  fix Change `import TLV from 'node-tlv';` to `const TLV = require('node-tlv');`. If your `package.json` contains `"type": "module"`, consider removing it or explicitly configuring your file to be CommonJS (e.g., using a `.cjs` extension).

• TypeError: TLV.parse is not a function

  cause Incorrectly importing the `node-tlv` module, leading to `TLV` not being the expected class with the static `parse` method, or attempting to destructure an incorrectly exported CommonJS module.
  fix Verify your import statement. For CommonJS, it should typically be `const TLV = require('node-tlv');`. Ensure you are not trying to destructure `TLV` (e.g., `const { parse } = require('node-tlv');`) as `parse` is a static method of the main `TLV` export.

• AssertionError [ERR_ASSERTION]: TLV length mismatch

  cause The input hexadecimal string provided to `TLV.parse()` or the `TLV` constructor is malformed, has an incorrect length indicator, or contains non-hexadecimal characters.
  fix Carefully inspect the input string. Ensure it's a valid, clean hexadecimal representation of TLV data, where length fields correctly correspond to the subsequent value data length. Use a hex editor or online TLV decoder to validate the input structure.

Warnings

• gotcha The 'node-tlv' library is primarily distributed as a CommonJS module. Attempting to import it using ES module syntax (e.g., `import TLV from 'node-tlv';`) directly in an ESM project might lead to import errors or unexpected behavior.
  Fix: For ESM projects, consider using a dynamic import (`await import('node-tlv')`) or configure your bundler/Node.js environment to handle CommonJS modules. The recommended approach is to use `const TLV = require('node-tlv');`.
• gotcha The parsing functions (`TLV.parse()` and `new TLV()`) expect valid hexadecimal string input for TLV data. Providing non-hexadecimal characters, odd-length strings, or malformed TLV structures (e.g., incorrect length fields) will result in parsing errors or incorrect data representation.
  Fix: Ensure all input strings passed to TLV methods are clean, even-length hexadecimal strings. Implement rigorous input validation and error handling before parsing, especially if data sources are untrusted or external.
• gotcha When building TLV objects using `new TLV(tag, value)`, the `value` parameter expects the raw hexadecimal data content of that TLV tag, *not* the full TLV string including its own tag and length. The library automatically calculates and inserts the length field.
  Fix: Provide only the hexadecimal value data for the `value` argument. For example, for a tag `82` with value `5800`, you would use `new TLV('82', '5800')`, not `new TLV('82', '82025800')`.

Install

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

Imports

• TLV
  wrong:

  import TLV from 'node-tlv';

  correct:

  const TLV = require('node-tlv');

  The library's primary export is the TLV class/object via CommonJS `module.exports`. Direct ES module `import` syntax may not work without transpilation or specific Node.js configuration.
• TLV.parse
  wrong:

  import { parse } from 'node-tlv';

  correct:

  const TLV = require('node-tlv');
  const parsedTlv = TLV.parse('770E82025800...');

  The `parse` function is a static method of the `TLV` class, not a standalone named export. It must be accessed via the main `TLV` object.
• new TLV()
  wrong:

  import { TLV } from 'node-tlv';
  const newTlv = new TLV('84', '...');

  correct:

  const TLV = require('node-tlv');
  const newTlv = new TLV('84', '325041592E5359532E4444463031');

  The `TLV` class constructor is accessed via the main default CommonJS export. Ensure `TLV` is correctly imported as the class itself before attempting instantiation.

Quickstart

This quickstart demonstrates how to parse a raw hexadecimal string containing TLV data into a structured object, navigate its child elements, and find specific tags by their hexadecimal value or string representation, crucial for EMV transaction processing.

const TLV = require('node-tlv');
const assert = require('assert');

// A sample GPO (Get Processing Options) response in hex string format.
const resp = '770E8202580094080801010010010301';

// Parse the raw hexadecimal string into a TLV object tree.
const tlv = TLV.parse(resp);

// Assertions to verify the top-level TLV object's tag, length, and value.
assert(tlv.getTag() === '77');
assert(tlv.getLength() === 14); // Length in bytes for the value '8202580094080801010010010301'
assert(tlv.getValue() === '8202580094080801010010010301');

// Retrieve child TLV objects from the parsed structure.
const child = tlv.getChild();
assert(child.length === 2);
assert(child[0].getTag() === '82');

// Find a specific TLV tag using either a number or string representation.
const aip = tlv.find(0x82); // Application Interchange Profile (AIP)
assert(aip.getTag() === '82');
assert(aip.getLength() === 2);
assert(aip.getValue() === '5800');

const afl = tlv.find('94'); // Application File Locator (AFL)
assert(afl.getTag() === '94');
assert(afl.getLength() === 8);
assert(afl.getValue() === '0801010010010301');