bytecon/README.md

A TypeScript utility for precise bit/byte conversions with BigInt support, parsing, and formatting.

# 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
```bash
npm install bytecon
```

---

## 🔧 Quick usage

```ts
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.