asn1-per-ts

Try it in the sandbox

TypeScript library for encoding and decoding data using ASN.1 PER (Packed Encoding Rules) unaligned variant (ITU-T X.691).

Features

• Bit-level buffer with MSB-first encoding and automatic growth
• Primitive codecs: BOOLEAN, INTEGER, ENUMERATED, BIT STRING, OCTET STRING, IA5String, VisibleString, UTF8String, NULL
• Composite codecs: CHOICE, SEQUENCE, SEQUENCE OF
• Constraint support: value ranges, size constraints, extensibility markers, default values
• Schema-driven encoding: define types as JSON, encode/decode plain objects
• Metadata decoding: decodeWithMetadata returns a tree of DecodedNode objects with bit positions, raw bytes, and codec references for every field

Install

npm install asn1-per-ts

Usage

Low-level codec API

import { BitBuffer, IntegerCodec, BooleanCodec, SequenceCodec } from 'asn1-per-ts';

// Constrained integer (0..255) uses 8 bits
const intCodec = new IntegerCodec({ min: 0, max: 255 });

const buf = BitBuffer.alloc();
intCodec.encode(buf, 42);
buf.reset();
console.log(intCodec.decode(buf)); // 42

Schema-driven API

import { SchemaCodec } from 'asn1-per-ts';

const codec = new SchemaCodec({
  type: 'SEQUENCE',
  fields: [
    { name: 'id', schema: { type: 'INTEGER', min: 0, max: 255 } },
    { name: 'active', schema: { type: 'BOOLEAN' } },
    { name: 'status', schema: { type: 'ENUMERATED', values: ['pending', 'approved', 'rejected'] } },
  ],
});

const hex = codec.encodeToHex({ id: 42, active: true, status: 'approved' });
console.log(hex);

const decoded = codec.decodeFromHex(hex);
console.log(decoded);

Decoding with Metadata

decodeWithMetadata returns a DecodedNode tree with full encoding metadata (bit offsets, bit lengths, raw bytes, codec references) for every field. Use stripMetadata to convert back to a plain object identical to decode().

import { SchemaCodec, stripMetadata } from 'asn1-per-ts';
import type { DecodedNode } from 'asn1-per-ts';

const codec = new SchemaCodec({
  type: 'SEQUENCE',
  fields: [
    { name: 'id', schema: { type: 'INTEGER', min: 0, max: 255 } },
    { name: 'active', schema: { type: 'BOOLEAN' } },
  ],
});

const hex = codec.encodeToHex({ id: 42, active: true });
const node = codec.decodeFromHexWithMetadata(hex);

// Access field metadata
const fields = node.value as Record<string, DecodedNode>;
console.log(fields.id.value);           // 42
console.log(fields.id.meta.bitOffset);  // 0
console.log(fields.id.meta.bitLength);  // 8
console.log(fields.id.meta.rawBytes);   // Uint8Array([0x2a])

// Strip metadata to get plain object
const plain = stripMetadata(node);
// plain === { id: 42, active: true }

Extension Markers

Extension markers (...) indicate that a type may be extended in future versions, providing forward compatibility. When present, PER encoding includes a 1-bit extension marker prefix (0 = not extended, 1 = extended).

In ASN.1 notation

Use ... to mark a type as extensible in ASN.1 schema text parsed by the built-in parser:

-- SEQUENCE: extension marker separates root fields from extension additions
MessageV1 ::= SEQUENCE {
    id     INTEGER (0..255),
    name   IA5String,
    ...                        -- extensible, no extensions yet
}

MessageV2 ::= SEQUENCE {
    id     INTEGER (0..255),
    name   IA5String,
    ...,                       -- extension marker
    email  IA5String           -- extension addition
}

-- ENUMERATED: extension marker separates root values from extension values
Color ::= ENUMERATED { red, green, blue, ... }
ColorV2 ::= ENUMERATED { red, green, blue, ..., yellow, purple }

-- CHOICE: extension marker separates root alternatives from extension alternatives
Shape ::= CHOICE { circle BOOLEAN, ..., polygon INTEGER }

-- Constraints: extensible constraints allow values outside the root range
FlexInt ::= INTEGER (0..100, ...)
FlexStr ::= OCTET STRING (SIZE (1..50, ...))

In JSON SchemaNode definitions

When building schemas directly as JSON SchemaNode objects, indicate extensibility with these properties:

// SEQUENCE: provide extensionFields (even empty [] to mark as extensible)
const schema: SchemaNode = {
  type: 'SEQUENCE',
  fields: [
    { name: 'id', schema: { type: 'INTEGER', min: 0, max: 255 } },
  ],
  extensionFields: [],  // extensible with no additions yet
};

// ENUMERATED: provide extensionValues
{ type: 'ENUMERATED', values: ['red', 'green'], extensionValues: [] }

// CHOICE: provide extensionAlternatives
{ type: 'CHOICE', alternatives: [...], extensionAlternatives: [] }

// Constrained types: set extensible: true
{ type: 'INTEGER', min: 0, max: 100, extensible: true }
{ type: 'BIT STRING', minSize: 1, maxSize: 50, extensible: true }

Key distinction: providing an empty array (extensionFields: []) marks the type as extensible, while omitting the property entirely (extensionFields: undefined) means the type is not extensible. This matters because extensible types include the 1-bit extension marker in the encoding.

Supported Types

Type	Description
BOOLEAN	Single bit
INTEGER	Constrained, semi-constrained, or unconstrained
ENUMERATED	Indexed enumeration with optional extensions
BIT STRING	Bit sequences with size constraints
OCTET STRING	Byte sequences with size constraints
IA5String	ASCII strings with optional alphabet constraints
VisibleString	Printable strings with optional alphabet constraints
UTF8String	UTF-8 encoded strings
NULL	Zero-bit placeholder
CHOICE	Tagged union of alternatives
SEQUENCE	Ordered fields with OPTIONAL/DEFAULT support
SEQUENCE OF	Homogeneous list with size constraints

Examples

The examples/ directory contains detailed usage guides with code samples:

• Schema Parser - Parse ASN.1 text notation into SchemaNode definitions, constraint options, extension markers, CLI usage
• Encoding - Encode JavaScript objects to PER unaligned binary using SchemaCodec or low-level codecs
• Decoding - Decode PER unaligned binary data back into objects

Sister Project

dosipas-ts — a TypeScript library built on top of asn1-per-ts for encoding and decoding DOSIPAS / ERA electronic ticket data.

Development

npm test          # Run tests
npm run build     # Build library

Website

The website/ directory contains a React + TailwindCSS demo app for interactive ASN.1 PER encoding and decoding.

cd website
npm install
npm run build     # Build for GitHub Pages (uses ./ asset path)
npm run dev       # Development server

License

MIT