Merge pull request #13 from DouglasNeuroInformatics/dev

feat: add formatByteSize

Author: joshunrau

src/__tests__/number.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, it } from 'vitest';
 
-import { isNumberLike, parseNumber } from '../number.js';
+import { formatByteSize, isNumberLike, parseNumber } from '../number.js';
 
 const NUMBER_LIKE_VALUES = [
   5e3,
@@ -72,3 +72,54 @@ describe('parseNumber', () => {
     });
   });
 });
+
+describe('formatByteSize', () => {
+  it('should return bytes for values less than threshold (SI)', () => {
+    expect(formatByteSize(999, true)).toBe('999 B');
+  });
+  it('should return bytes for values less than threshold (Binary)', () => {
+    expect(formatByteSize(1023)).toBe('1023 B');
+  });
+
+  it('should format 1 KB correctly (SI)', () => {
+    expect(formatByteSize(1000, true)).toBe('1.0 KB');
+  });
+
+  it('should format 1 KiB correctly (Binary)', () => {
+    expect(formatByteSize(1024)).toBe('1.0 KiB');
+  });
+
+  it('should format MB correctly with default dp (SI)', () => {
+    expect(formatByteSize(1_500_000, true)).toBe('1.5 MB');
+  });
+
+  it('should format MiB correctly with default dp (Binary)', () => {
+    expect(formatByteSize(1_572_864)).toBe('1.5 MiB'); // 1024 * 1024 * 1.5
+  });
+
+  it('should format GB correctly with custom dp (SI)', () => {
+    expect(formatByteSize(3_000_000_000, true, 2)).toBe('3.00 GB');
+  });
+
+  it('should format GiB correctly with custom dp (Binary)', () => {
+    expect(formatByteSize(3_221_225_472, false, 3)).toBe('3.000 GiB'); // 1024^3 * 3
+  });
+
+  it('should handle zero bytes', () => {
+    expect(formatByteSize(0)).toBe('0 B');
+  });
+
+  it('should handle negative values', () => {
+    expect(formatByteSize(-1024)).toBe('-1.0 KiB');
+  });
+
+  it('should not exceed the unit array length', () => {
+    const large = 10 ** 30; // Very large number
+    const result = formatByteSize(large, true);
+    expect(result.endsWith('YB')).toBe(true); // YB is the last SI unit
+  });
+
+  it('should round correctly with dp = 0', () => {
+    expect(formatByteSize(1536, false, 0)).toBe('2 KiB'); // 1536 / 1024 = 1.5 → rounded to 2
+  });
+});

src/number.ts

@@ -20,3 +20,25 @@ export function isNumberLike(value: unknown): value is number | string {
 export function parseNumber(value: unknown): number {
   return isNumberLike(value) ? Number(value) : NaN;
 }
+
+export function formatByteSize(bytes: number, si = false, dp = 1): string {
+  const thresh = si ? 1000 : 1024;
+
+  if (Math.abs(bytes) < thresh) {
+    return bytes + ' B';
+  }
+
+  const units = si
+    ? ['KB', 'MB', 'GB', 'TB', 'PB', 'EB', 'ZB', 'YB']
+    : ['KiB', 'MiB', 'GiB', 'TiB', 'PiB', 'EiB', 'ZiB', 'YiB'];
+
+  let u = -1;
+  const r = 10 ** dp;
+
+  do {
+    bytes /= thresh;
+    ++u;
+  } while (Math.round(Math.abs(bytes) * r) / r >= thresh && u < units.length - 1);
+
+  return bytes.toFixed(dp) + ' ' + units[u];
+}