node-tlv

library1.5.14jsnpmunverified

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.

data serialization payments

npm install node-tlv

github ↗package ↗

INSTALL

IMPORT

SIG · NODE-TLV

node-tlv

datajavascriptv1.5.14

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

TLV

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

✗ import TLV from '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

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

✗ import { parse } from 'node-tlv';

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()

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

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

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

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');

Debug

Known issues

gotchaThe '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');`.

affects: >=1.0.0

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

affects: >=1.0.0

gotchaWhen 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')`.

affects: >=1.0.0

Errors

Common errors & fixes

SyntaxError: Cannot use import statement outside a module

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

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

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.

Upgrade

Version history

1.5.14latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

34 hits · last 30 days

node

Resources

githubhttps://github.com/coolbong/node-tlv ↗

packagehttps://www.npmjs.com/package/node-tlv ↗