js.nbt

A robust, type-safe, and high-performance NBT (Named Binary Tag) library for JavaScript and TypeScript. Designed to be easy to use while providing full control over the NBT format. Supports both CommonJS and ES Modules.

Features

• 🚀 High Performance: Optimized for speed and low memory usage.
• 📦 Dual Build: Works seamlessly with CommonJS (require) and ES Modules (import).
• 🔒 Type-Safe: Written in TypeScript with complete type definitions.
• 🗜️ Compression Support: Built-in support for Gzip compression/decompression.
• 🌐 Universal: Works in Node.js and modern environments supporting Buffers.

Installation

npm install js.nbt

Usage

CommonJS (require)

const { parse, writeSync } = require("js.nbt");
const fs = require("fs");

// Reading
const buffer = fs.readFileSync("level.dat");
const nbt = parse(buffer);

// Writing
const newBuffer = writeSync(nbt);

ES Modules / TypeScript (import)

Reading NBT Files

You can read NBT data from a file or buffer. The library automatically detects if the data is Gzipped.

import { parse, parseSync } from "js.nbt";
import * as fs from "fs";

// Async
async function readNbt() {
  const buffer = await fs.promises.readFile("level.dat");
  const nbt = await parse(buffer);
  console.log(nbt);
}

// Sync
const buffer = fs.readFileSync("level.dat");
const nbt = parseSync(buffer);
console.log(nbt);

Writing NBT Files

You can create NBT data structures and serialize them back to a buffer.

import { write, writeSync, ParsedNBT } from "js.nbt";
import * as fs from "fs";

const data: ParsedNBT = {
  name: "MyLevel",
  value: {
    LevelName: "New World",
    SpawnX: 100,
    SpawnY: 64,
    SpawnZ: 100,
    Player: {
      Health: 20.0,
      Inventory: [],
    },
  },
};

// Async (Compressed)
async function saveNbt() {
  const buffer = await write(data, true); // true for Gzip compression
  await fs.promises.writeFile("level.dat", buffer);
}

// Sync (Uncompressed)
const buffer = writeSync(data, false);
fs.writeFileSync("level_uncompressed.dat", buffer);

Type Mapping

The library maps NBT tags to JavaScript types as follows:

NBT Tag	JavaScript Type
Byte	number
Short	number
Int	number
Long	bigint
Float	number
Double	number
ByteArray	Buffer
String	string
List	Array
Compound	Object
IntArray	Int32Array
LongArray	BigInt64Array

API Reference

parse(buffer: Buffer): Promise<ParsedNBT>

Asynchronously parses an NBT buffer. Automatically handles Gzip decompression.

parseSync(buffer: Buffer): ParsedNBT

Synchronously parses an NBT buffer. Automatically handles Gzip decompression.

write(nbt: ParsedNBT, compress?: boolean): Promise<Buffer>

Asynchronously serializes NBT data. Set compress to true to Gzip the output.

writeSync(nbt: ParsedNBT, compress?: boolean): Buffer

Synchronously serializes NBT data. Set compress to true to Gzip the output.

License

MIT