A precise, lightweight, and type-safe utility to convert bytes into human-readable strings. Built for high performance and modern development standards.

🚀 Key Features

• Type-Safe: Written entirely in TypeScript for an excellent DX.
• O(1) Efficiency: Uses a logarithmic approach instead of loops.
• Hybrid Build: Supports both CommonJS (.cjs) and ES Modules (.js).
• Zero Dependencies: Lightweight and secure.
• Yottabyte (YB) Support: Handles massive datasets accurately.
• Tree-Shakable: Optimizes your application bundle size.

📦 Installation

Use your favorite package manager:

# npm
npm install precise-bytes

# pnpm
pnpm add precise-bytes

# yarn
yarn add precise-bytes

🛠️ Usage

Modern (TypeScript / ESM)

import { humanBytes } from 'precise-bytes';

console.log(humanBytes(1000)); // "1 KB"
console.log(humanBytes(1550000)); // "1.55 MB"
console.log(humanBytes(1234567, 1)); // "1.2 MB"

CommonJS

const { humanBytes } = require('precise-bytes');

console.log(humanBytes(1024)); // "1.02 KB"

Handling Edge Cases

humanBytes(0); // "0 Bytes"
humanBytes(-1); // "0 Bytes"
humanBytes(NaN); // "0 Bytes"

📐 Technical details

This library uses the decimal (SI) standard where 1 KB = 1000 Bytes. For high performance, scaling is calculated using the logarithmic formula:

$$i = \text{floor}(\frac{\ln(\text{bytes})}{\ln(1000)})$$

🧪 Testing

Run tests with Vitest to ensure reliability:

npm run test

🔐 Security

If you discover a security vulnerability, please see our Security Policy.

🤝 Contributing

Contributions are welcome! Please read our Contributing Guidelines to get started.

📄 License

This project is licensed under the MIT license.