webklv

A fully web-compatible, zero-dependency KLV (Key-Length-Value) data parsing library for JavaScript/TypeScript.

Features

• ✅ 100% web compatible — uses only standard browser APIs (TextEncoder, Uint8Array, BigInt)
• 🔒 Fully typed — complete TypeScript types with generics and strict mode
• ⚡ Full sync — no async, no streams, no callbacks; parse buffer in, structured data out
• 🧩 MISB ST 0601 — complete UAS Local Metadata Set (105 tags)
• 🔐 MISB ST 0102 — Security Metadata nested local set
• 📦 Built with rslib — ESM + CJS dual output with declaration maps
• 🛡️ Pristine error handling — typed errors (KLVError, BERDecodeError, TruncatedDataError, …)
• ✔️ Validated — passes the complete klvdata Python library test suite

---

Installation

npm install webklv
# or
pnpm add webklv

---

Quick Start

Parse a raw KLV buffer

import { KLVParser } from "webklv";

const buffer = new Uint8Array([0x02, 0x08, 0x00, 0x04, 0x60, 0x50, 0x58, 0x4e, 0x01, 0x80]);
const parser = new KLVParser(buffer, { keyLength: 1 });

for (const { key, value } of parser) {
  console.log(key, value);
  // Uint8Array [2]  Uint8Array [0x00, 0x04, ...]
}

Parse a MISB ST 0601 packet

import { StreamParser, UASLocalMetadataSet, PrecisionTimeStamp } from "webklv";
import "webklv"; // MISB parsers auto-register on import

for (const packet of new StreamParser(buffer)) {
  if (packet instanceof UASLocalMetadataSet) {
    const ts = packet.get(PrecisionTimeStamp.key);
    if (ts instanceof PrecisionTimeStamp) {
      console.log(ts.value.toString()); // "2009-01-12 22:08:22+00:00"
    }
  }
}

Encode a value

import { PlatformHeadingAngle } from "webklv";

const elem = new PlatformHeadingAngle(159.974);
const bytes = elem.toBytes();
// Uint8Array [0x05, 0x02, 0x71, 0xC2]

---

Architecture

src/
├── core/
│   ├── ber.ts          BER length field encode/decode
│   ├── checksum.ts     SMPTE ST 336 packet checksum
│   ├── errors.ts       Typed error classes
│   └── types.ts        Core TypeScript interfaces
├── converters/
│   ├── bytes.ts        Integer ↔ Uint8Array
│   ├── datetime.ts     Microsecond UTC timestamp ↔ Uint8Array (BigInt precision)
│   ├── float.ts        Linear-mapped fixed-point float ↔ Uint8Array
│   ├── hexstr.ts       Hex string ↔ Uint8Array
│   └── string.ts       UTF-8 string ↔ Uint8Array
├── element/
│   ├── element.ts      Abstract Element base, UnknownElement
│   ├── parsers.ts      BytesElementParser, DateTimeElementParser, etc.
│   ├── set.ts          SetParser (nested local sets)
│   └── values.ts       BytesValue, StringValue, DateTimeValue, MappedValue
├── stream/
│   ├── parser.ts       KLVParser (raw TLV iterator)
│   └── streamparser.ts StreamParser (16-byte UL dispatch)
└── misb/
    ├── misb0601.ts     MISB ST 0601 — UAS Local Metadata Set + Tags 1–25
    ├── misb0601-nav.ts Tags 26–65 (navigation, sensor, platform)
    ├── misb0601-ext.ts Tags 66–105 (extended/alternate platform)
    └── misb0102.ts     MISB ST 0102 — Security Metadata nested set

---

API Reference

KLVParser

Low-level iterator that yields raw { key, value } pairs.

const parser = new KLVParser(buffer, { keyLength: 1 });
for (const { key, value } of parser) { ... }

StreamParser

High-level iterator that dispatches 16-byte Universal Labels to registered set parsers.

for (const packet of new StreamParser(buffer)) { ... }

SetParser (base class)

Base for all MISB local sets. Parsed items accessible via:

set.items                    // Map<string, Element>
set.get(key)                 // Element | undefined
set.toBytes()                // Uint8Array — re-encode to wire format

Element Types

Class	Value Type	Notes
BytesElementParser	BytesValue (raw bytes)	Checksum, opaque fields
StringElementParser	StringValue (string)	UTF-8 text fields
DateTimeElementParser	DateTimeValue (Date)	Microsecond precision
MappedElementParser	MappedValue (number)	Fixed-point → float
UnknownElement	Uint8Array	Fallback for unknown keys

Utility Functions

// BER encoding
berEncode(128)   // Uint8Array [0x81, 0x80]
berDecode(bytes) // number

// Checksum
packetChecksum(fullPacket) // Uint8Array [hi, lo]

// Converters
bytesToFloat(bytes, domain, range)
floatToBytes(value, domain, range)
bytesToDatetime(bytes)   // Date
datetimeToBytes(date)    // Uint8Array
hexstrToBytes("06 0E 2B 34")
bytesToHexstr(bytes)

Error Classes

Class	When thrown
KLVError	Base for all library errors
BERDecodeError	Malformed BER length field
RangeError	Value outside linear map domain
TruncatedDataError	Buffer ends unexpectedly
LengthError	Wrong byte count for data type
ValidationError	Schema validation failure

---

MISB ST 0601 Tags

All 105 registered tags including:

• Tags 1–25: Checksum, timestamp, mission ID, platform heading/pitch/roll, sensor position, frame center
• Tags 26–65: Corner offsets, wind, pressure, target location, weapons, call sign
• Tags 66–105: Alternate platform, event start time, ellipsoid heights, full-precision corners

---

Building

pnpm install
pnpm build      # ESM + CJS + types
pnpm test       # 156 tests
pnpm test:coverage
pnpm lint       # TypeScript type check

---

License

MIT

---

Comparison with the Python klvdata library

This library is a faithful TypeScript port of the klvdata Python library, passing its complete test suite. Key differences:

Feature	webklv (TypeScript)	klvdata (Python)
Platform	Web + Node.js	Python only
Precision	BigInt microseconds	Python float
Types	Full TypeScript types	Dynamic
Build	rslib (ESM + CJS)	setuptools