tlv-kit

tlv-kit is a modern TypeScript library for working with Tag-Length-Value (TLV) data structures. It provides robust tools for encoding, decoding, parsing, and inspecting TLV objects, supporting both primitive and constructed types. With a clean API and utility functions, tlv-kit makes it easy to handle TLV data in payment, identity, smart card, and protocol applications. Designed for flexibility, reliability, and ease of integration in Node.js and browser environments.

Installation

npm i @interledger/tlv-kit

Usage

import {
  TLV,
  TLVParser,
  uint8ArrayToHex,
  hexToUint8Array,
  asciiToUint8Array
} from 'tlv-kit'

// Create a primitive TLV
const tag = new Uint8Array([0xc1])
let value = hexToUint8Array('48656C6C6F20576F726C64') // 'Hello World' in hex
// or
value = asciiToUint8Array('Hello World')
const tlv = new TLV(tag, false, value)

// Encode to binary format
const encoded = tlv.encode()
console.log(encoded) // Uint8Array

// Parse from binary format using TLVParser
const parsed = TLVParser(encoded)[0]
console.log(uint8ArrayToHex(parsed.getTag())) // 'C1'
console.log(uint8ArrayToHex(parsed.getValue())) // '48656C6C6F20576F726C64'

// Working with constructed TLV and children
const parent = new TLV(new Uint8Array([0x21]), true)
parent.addChild(
  new TLV(hexToUint8Array('C1'), false, hexToUint8Array('6669727374'))
)
parent.addChild(
  new TLV(hexToUint8Array('C2'), false, hexToUint8Array('7365636F6E64'))
)

// Find child by tag
const foundChild = parent.getChild(hexToUint8Array('C1'))
console.log(uint8ArrayToHex(foundChild?.getValue() ?? new Uint8Array())) // '6669727374'

// Hex utilities
uint8ArrayToHex(tag) // 'C1'
hexToUint8Array('ABCD') // Uint8Array [0xAB, 0xCD]

// DOL (Data Object List) usage
// Define a DOL with two fields: 9F1A (length 2), 5F2A (length 2)
const dol = new DOL(new Uint8Array([]))
dol.addField(hexToUint8Array('9F1A'), 2)
dol.addField(hexToUint8Array('5F2A'), 2)

// Encode DOL structure
const dolEncoded = dol.encode()
console.log(Array.from(dolEncoded)) // [0x9F, 0x1A, 0x02, 0x5F, 0x2A, 0x02]

// Map data to TLVs using DOL
const data = hexToUint8Array('01020304')
const tlvs = dol.mapToTLVs(data)
console.log(tlvs[0].getTag()) // Uint8Array [0x9F, 0x1A]
console.log(tlvs[0].getValue()) // Uint8Array [0x01, 0x02]
console.log(tlvs[1].getTag()) // Uint8Array [0x5F, 0x2A]
console.log(tlvs[1].getValue()) // Uint8Array [0x03, 0x04]

Features

• Encode and decode TLV (Tag-Length-Value) structures
• Support for constructed and primitive TLVs
• Parse TLV data from binary format
• Utility functions for hex and Uint8Array conversions
• Child TLV management and lookup
• DOL (Data Object List) parsing, encoding, and mapping to TLVs
• Error handling via custom TLVError, TLVParseError, and DOLParseError classes

API Reference

TLV

• constructor(tag: Uint8Array, isConstructed: boolean, value?: Uint8Array | Array<TLV> | null)
• encode(): Uint8Array — Encode TLV to binary
• setValue(value: Uint8Array): TLV - Set value (primitive TLV only)
• addChild(child: TLV): TLV — Add child TLV (constructed TLV only)
• getChild(tag: Uint8Array): TLV | null — Find child by tag
• getChildren: Array<TLV> — Get children (constructed TLV only)
• getValue: Uint8Array | null — Get value
• isStructured: boolean - Retrieves structured status of TLV

DOL

• constructor(input: Uint8Array) — Create a DOL from binary input
• addField(tag: Uint8Array, length: number): DOL — Add a field to the DOL
• getFields(): Array<DOLField> — Get all fields
• getTotalLength(): number — Get total length of all fields
• encode(): Uint8Array — Encode DOL structure
• mapToTLVs(data: Uint8Array): Array<TLV> — Map data to TLVs based on DOL

TLVParser

• TLVParser(input: Uint8Array, offset?: number, limit?: number): Array<TLV> — Parse TLV(s) from binary

Utility Functions

• uint8ArrayToHex(arr: Uint8Array): string — Convert Uint8Array to hex string
• hexToUint8Array(hex: string): Uint8Array — Convert hex string to Uint8Array
• isTagConstructed(tag: Uint8Array): boolean — Check if a tag is constructed
• getLengthBytes(length: number): Uint8Array — Encode length as TLV bytes
• parseTag(input: Uint8Array, offset: number): Uint8Array — Parse tag from input
• parseLength(input: Uint8Array, offset: number): number — Parse length from input

Supported TLV Formats

Supports BER-like TLV encoding and decoding. Handles both primitive and constructed TLVs. Customizable for other TLV formats as needed.

Error Handling

All errors are thrown as instances of TLVError, TLVParseError, or DOLParseError. Catch and handle these for invalid input, encoding, or parsing issues.

Contributing

Contributions are welcome! Please open issues or submit pull requests. For major changes, discuss them first via an issue.

Testing

Run all tests using:

pnpm test

Tests cover encoding, parsing, error handling, utility functions, and DOL features.