{"id":15157,"library":"node-tlv","title":"TLV Parser for Node.js","description":"The `node-tlv` library provides a robust parser and builder for Tag-Length-Value (TLV) encoded data, commonly found in smart card protocols like EMV and ISO7816. It supports parsing both simple TLV and BER-TLV structures, allowing developers to extract and manipulate data elements such as DGI, EMV, ISO7816, and DOL tags. Currently at stable version 1.5.14, the package does not explicitly state a release cadence, but its versioning and continuous updates suggest ongoing maintenance. Its key differentiator lies in its focused support for financial and smart card industry standards, offering both parsing of raw hexadecimal strings into structured TLV objects and the ability to programmatically construct complex TLV hierarchies, useful for building responses like PPSE FCI or PSE records. It is designed for Node.js environments, providing a programmatic interface to navigate and construct TLV data structures.","status":"active","version":"1.5.14","language":"javascript","source_language":"en","source_url":"ssh://git@github.com/coolbong/node-tlv","tags":["javascript","TLV","DGI","Ber-TLV","EMV","ISO7816","SIMPLE-TLV","DOL"],"install":[{"cmd":"npm install node-tlv","lang":"bash","label":"npm"},{"cmd":"yarn add node-tlv","lang":"bash","label":"yarn"},{"cmd":"pnpm add node-tlv","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"import TLV from 'node-tlv';","symbol":"TLV","correct":"const TLV = require('node-tlv');"},{"note":"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.","wrong":"import { parse } from 'node-tlv';","symbol":"TLV.parse","correct":"const TLV = require('node-tlv');\nconst parsedTlv = TLV.parse('770E82025800...');"},{"note":"The `TLV` class constructor is accessed via the main default CommonJS export. Ensure `TLV` is correctly imported as the class itself before attempting instantiation.","wrong":"import { TLV } from 'node-tlv';\nconst newTlv = new TLV('84', '...');","symbol":"new TLV()","correct":"const TLV = require('node-tlv');\nconst newTlv = new TLV('84', '325041592E5359532E4444463031');"}],"quickstart":{"code":"const TLV = require('node-tlv');\nconst assert = require('assert');\n\n// A sample GPO (Get Processing Options) response in hex string format.\nconst resp = '770E8202580094080801010010010301';\n\n// Parse the raw hexadecimal string into a TLV object tree.\nconst tlv = TLV.parse(resp);\n\n// Assertions to verify the top-level TLV object's tag, length, and value.\nassert(tlv.getTag() === '77');\nassert(tlv.getLength() === 14); // Length in bytes for the value '8202580094080801010010010301'\nassert(tlv.getValue() === '8202580094080801010010010301');\n\n// Retrieve child TLV objects from the parsed structure.\nconst child = tlv.getChild();\nassert(child.length === 2);\nassert(child[0].getTag() === '82');\n\n// Find a specific TLV tag using either a number or string representation.\nconst aip = tlv.find(0x82); // Application Interchange Profile (AIP)\nassert(aip.getTag() === '82');\nassert(aip.getLength() === 2);\nassert(aip.getValue() === '5800');\n\nconst afl = tlv.find('94'); // Application File Locator (AFL)\nassert(afl.getTag() === '94');\nassert(afl.getLength() === 8);\nassert(afl.getValue() === '0801010010010301');","lang":"javascript","description":"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."},"warnings":[{"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');`.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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')`.","message":"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.","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":"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).","cause":"Attempting to use ES module `import` syntax in a Node.js environment or file configured for CommonJS, or without transpilation.","error":"SyntaxError: Cannot use import statement outside a 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.","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.","error":"TypeError: TLV.parse is not a function"},{"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.","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.","error":"AssertionError [ERR_ASSERTION]: TLV length mismatch"}],"ecosystem":"npm"}