bytes-to-human 1.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Drakos
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,14 @@
+# Bytes to Human
+Convert bytes to human format like "1 KB". 0 dependencies. Easy to copy paste into new projects.
+
+# How to install
+
+```bash
+pnpm install human-to-bytes
+```
+
+# How to use
+```ts
+formatBytes(1500, 1) // 1.5 KB
+formatBytes(1048576) // 1MB 
+```

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export declare function bytesToHuman(bytes: number, decimals?: number): string;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,GAAE,MAAU,GAAG,MAAM,CAaxE"}

package/dist/index.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.bytesToHuman = bytesToHuman;
+function bytesToHuman(bytes, decimals = 1) {
+    if (!Number.isFinite(bytes) || bytes < 0) {
+        throw new RangeError(`Invalid byte value: ${bytes}`);
+    }
+    if (bytes === 0)
+        return "0 B";
+    const UNITS = ["B", "KB", "MB", "GB", "TB", "PB", "EB"];
+    const exponent = Math.min(Math.floor(Math.log2(bytes) / 10), UNITS.length - 1);
+    const value = bytes / (1024 ** exponent);
+    const formatted = Number(value.toFixed(decimals)).toString(); // strips trailing zeros
+    return `${formatted} ${UNITS[exponent]}`;
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;AAAA,oCAaC;AAbD,SAAgB,YAAY,CAAC,KAAa,EAAE,WAAmB,CAAC;IAC9D,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC,EAAE,CAAC;QACzC,MAAM,IAAI,UAAU,CAAC,uBAAuB,KAAK,EAAE,CAAC,CAAC;IACvD,CAAC;IAED,IAAI,KAAK,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IAE9B,MAAM,KAAK,GAAG,CAAC,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,CAAU,CAAC;IACjE,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,EAAE,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IAC/E,MAAM,KAAK,GAAG,KAAK,GAAG,CAAC,IAAI,IAAI,QAAQ,CAAC,CAAC;IACzC,MAAM,SAAS,GAAG,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC,wBAAwB;IAEtF,OAAO,GAAG,SAAS,IAAI,KAAK,CAAC,QAAQ,CAAC,EAAE,CAAC;AAC3C,CAAC"}

package/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "bytes-to-human",
+  "version": "1.1.2",
+  "description": "Convert bytes to human format like '1 KB'",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "test": "vitest run"
+  },
+  "keywords": [],
+  "author": "Drakos",
+  "license": "MIT",
+  "packageManager": "pnpm@10.32.1",
+  "devDependencies": {
+    "@types/node": "^25.8.0",
+    "vitest": "^4.1.6"
+  }
+}

package/src/index.ts

@@ -0,0 +1,14 @@
+export function bytesToHuman(bytes: number, decimals: number = 1): string {
+  if (!Number.isFinite(bytes) || bytes < 0) {
+    throw new RangeError(`Invalid byte value: ${bytes}`);
+  }
+
+  if (bytes === 0) return "0 B";
+
+  const UNITS = ["B", "KB", "MB", "GB", "TB", "PB", "EB"] as const;
+  const exponent = Math.min(Math.floor(Math.log2(bytes) / 10), UNITS.length - 1);
+  const value = bytes / (1024 ** exponent);
+  const formatted = Number(value.toFixed(decimals)).toString(); // strips trailing zeros
+
+  return `${formatted} ${UNITS[exponent]}`;
+}

package/test/index.test.ts

@@ -0,0 +1,74 @@
+import { bytesToHuman } from "../src/index";
+import { describe, expect, it } from "vitest";
+
+describe("bytesToHuman", () => {
+  it("formats zero bytes", () => {
+    expect(bytesToHuman(0)).toBe("0 B");
+  });
+
+  it("formats bytes", () => {
+    expect(bytesToHuman(500)).toBe("500 B");
+  });
+
+  it("formats kilobytes", () => {
+    expect(bytesToHuman(1024)).toBe("1 KB");
+    expect(bytesToHuman(2560)).toBe("2.5 KB");
+  });
+
+  it("formats megabytes", () => {
+    expect(bytesToHuman(1048576)).toBe("1 MB");
+    expect(bytesToHuman(5242880)).toBe("5 MB");
+  });
+
+  it("formats gigabytes", () => {
+    expect(bytesToHuman(1073741824)).toBe("1 GB");
+    expect(bytesToHuman(2147483648)).toBe("2 GB");
+  });
+
+  it("formats terabytes", () => {
+    expect(bytesToHuman(1099511627776)).toBe("1 TB");
+  });
+
+  it("formats petabytes", () => {
+    expect(bytesToHuman(1125899906842624)).toBe("1 PB");
+  });
+
+  it("respects decimal precision", () => {
+    expect(bytesToHuman(1500, 0)).toBe("1 KB");
+    expect(bytesToHuman(1500, 1)).toBe("1.5 KB");
+    expect(bytesToHuman(1500, 2)).toBe("1.46 KB");
+    expect(bytesToHuman(1500, 3)).toBe("1.465 KB");
+  });
+
+  it("strips trailing zeros", () => {
+    expect(bytesToHuman(1024, 2)).toBe("1 KB");
+    expect(bytesToHuman(2048, 1)).toBe("2 KB");
+  });
+
+  it("throws on negative values", () => {
+    expect(() => bytesToHuman(-1)).toThrow(RangeError);
+    expect(() => bytesToHuman(-1)).toThrow("Invalid byte value: -1");
+  });
+
+  it("throws on non-finite values", () => {
+    expect(() => bytesToHuman(Infinity)).toThrow(RangeError);
+    expect(() => bytesToHuman(NaN)).toThrow(RangeError);
+    expect(() => bytesToHuman(Infinity)).toThrow("Invalid byte value: Infinity");
+  });
+
+  it("throws on non-numeric values", () => {
+    // biome-ignore lint/suspicious/noExplicitAny: off
+    expect(() => bytesToHuman("100" as any)).toThrow(RangeError);
+    // biome-ignore lint/suspicious/noExplicitAny: off
+    expect(() => bytesToHuman(null as any)).toThrow(RangeError);
+    // biome-ignore lint/suspicious/noExplicitAny: off
+    expect(() => bytesToHuman(undefined as any)).toThrow(RangeError);
+  });
+
+  it("handles values just below unit thresholds", () => {
+    expect(bytesToHuman(1023)).toBe("1023 B");
+    expect(bytesToHuman(1023999)).toBe("1000 KB");
+    expect(bytesToHuman(1048575)).toBe("1024 KB");
+    expect(bytesToHuman(1048576)).toBe("1 MB");
+  });
+});

package/tsconfig.json

@@ -0,0 +1,45 @@
+{
+  // Visit https://aka.ms/tsconfig to read more about this file
+  "compilerOptions": {
+    // File Layout
+    "rootDir": "./src",
+    "outDir": "./dist",
+
+    // Environment Settings
+    // See also https://aka.ms/tsconfig/module
+    "module": "nodenext",
+    "target": "esnext",
+    // For nodejs:
+    "lib": ["esnext"],
+    "types": ["node"],
+    // and npm install -D @types/node
+
+    // Other Outputs
+    "sourceMap": true,
+    "declaration": true,
+    "declarationMap": true,
+
+    // Stricter Typechecking Options
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true,
+
+    // Style Options
+    // "noImplicitReturns": true,
+    // "noImplicitOverride": true,
+    // "noUnusedLocals": true,
+    // "noUnusedParameters": true,
+    // "noFallthroughCasesInSwitch": true,
+    // "noPropertyAccessFromIndexSignature": true,
+
+    // Recommended Options
+    "strict": true,
+    "jsx": "react-jsx",
+    // "verbatimModuleSyntax": true,
+    "isolatedModules": true,
+    "noUncheckedSideEffectImports": true,
+    "moduleDetection": "force",
+    "skipLibCheck": true,
+  },
+  "exclude": ["test"],
+  "include": ["src"]
+}