bytecon

A zero-dependency TypeScript library for precise bit/byte conversions with BigInt support and helpful parsing/formatting utilities.

Quick verdict

• ✅ Use when you need exact integer conversions or safe handling of very large sizes.
• ⚠️ Use convertToNumber / formatBytes for human-friendly fractional results.

🚀 Features

• 🔁 Precise conversions between bits and bytes, including binary (kib, mib, gib, ...) and decimal (kb, mb, gb, ...) prefixes
• 💎 BigInt-aware core: returns BigInt for exact integer results
• ✨ Relaxed number API for fractional output and formatting
• 🧰 Helpers: parse strings like "1.5 GB", format outputs, and convenience extractors
• ⚙️ TypeScript-first, zero runtime dependencies

📦 Install

npm

npm install bytecon

🔧 Quick usage

import {
  convert,
  convertToBigInt,
  convertToNumber,
  parseBytes,
  formatBytes,
  toBigIntResult,
  toNumberResult,
} from "bytecon";

// mixed return: BigInt (exact) or number (fractional)
const r1 = convert(1n, "kib", "kb"); // ~0.9765625 (number)
const r2 = convert(8n, "byte", "bit"); // 64n (BigInt)

// strict BigInt API (throws if fractional)
const exact = convertToBigInt(8, "byte", "bit"); // 64n

// relaxed number API (may lose precision for huge values)
const approx = convertToNumber("1", "kb", "kib", "binary"); // ~0.9765625

// parse and format
const parsed = parseBytes("1.5 GB"); // { value: 1.5, unit: "gb" }
const pretty = formatBytes(1024n, "kb", { unit: "mb", digits: 3 }); // "1.000 mb"

// helpers
const maybeBig = toBigIntResult(r2); // bigint | undefined
const maybeNum = toNumberResult(r1); // number | undefined

📚 API (high level)

• convert(value, from, to, mode = "standard"): bigint | number | undefined
• convertToBigInt(value, from, to, mode): bigint (throws if fractional)
• convertToNumber(value, from, to, mode): number (throws if BigInt too large to coerce)
• parseBytes(input): { value: number | bigint; unit: string }
• formatBytes(value, fromUnit, opts): string
• toBigIntResult(convertResult): bigint | undefined
• toNumberResult(convertResult): number | undefined
• exports: unitMap, byteUnits, binaryMap, chooseBestUnit (utility)

🧭 Units supported

• Short keys: bit, byte, kbit, mbit, gbit, ..., kib, mib, gib, ..., kb, mb, gb, ...
• Long names mapped to canonical keys (e.g., "kilobyte" → "kb")
• Binary mapping (kb ↔ kib etc.) included 🔄

📝 Behavior notes

• BigInt is returned only for exact integer results.
• convertToBigInt enforces integer-only results (throws if fractional).
• convertToNumber returns a number but will throw when a BigInt is too large to represent safely.
• chooseBestUnit is an exported helper to pick a human-friendly unit; useful for auto-scaling formatters.