From 825e1126fc8d9a015987faf2f6ccf608fc92585e Mon Sep 17 00:00:00 2001 From: Jason Mulligan Date: Sat, 26 Sep 2026 17:34:51 -0400 Subject: [PATCH 1/3] docs: fix README accuracy errors - Correct test count from 149 to 255 - Update source file line counts (filesize.js 286, helpers.js 538, constants.js 82) - Fix npm run dev description (watch mode, not live reload) - Correct npm run lint:fix to npm run fix --- README.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 9391eaa..9bccbf7 100644 --- a/README.md +++ b/README.md @@ -164,7 +164,7 @@ npm test # Run all tests (lint + node:test) npm run test:watch # Live test watching ``` -**100% test coverage** with 149 tests: +**100% test coverage** with 255 tests: ``` --------------|---------|----------|---------|---------|------------------- @@ -181,10 +181,10 @@ All files | 100 | 100 | 100 | 100 | ```bash npm install # Install dependencies -npm run dev # Development mode with live reload +npm run dev # Build distributions in watch mode npm run build # Build distributions npm run lint # Check code style -npm run lint:fix # Auto-fix linting issues +npm run fix # Auto-fix linting issues ``` ### Project Structure @@ -192,9 +192,9 @@ npm run lint:fix # Auto-fix linting issues ``` filesize.js/ ├── src/ -│ ├── filesize.js # Main implementation (285 lines) -│ ├── helpers.js # Helper functions (215 lines) -│ └── constants.js # Constants (81 lines) +│ ├── filesize.js # Main implementation (286 lines) +│ ├── helpers.js # Helper functions (538 lines) +│ └── constants.js # Constants (82 lines) ├── tests/ │ └── unit/ ├── dist/ # Built distributions From 27aa769f1516763c42067b34dc3553c431ff66bc Mon Sep 17 00:00:00 2001 From: Jason Mulligan Date: Sat, 26 Sep 2026 17:52:19 -0400 Subject: [PATCH 2/3] docs: rewrite README for clarity and consistent tone - Reposition as 'a popular choice' (filesize trails bytes and pretty-bytes in downloads, so 'most popular' would be inaccurate) - Fix Standards section: standard wins over base; IEC does not require base: 2 - Add a Standards comparison table (base + symbols + example) - Clarify round vs precision precedence - Move TypeScript section after Usage, keep examples verified - Tighten prose: concrete benefits over vague claims --- README.md | 111 +++++++++++++++++++++++++++++------------------------- 1 file changed, 59 insertions(+), 52 deletions(-) diff --git a/README.md b/README.md index 9bccbf7..bd02bb7 100644 --- a/README.md +++ b/README.md @@ -4,18 +4,18 @@ [![License](https://img.shields.io/badge/License-BSD%203--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause) [![Build Status](https://github.com/avoidwork/filesize.js/actions/workflows/ci.yml/badge.svg)](https://github.com/avoidwork/filesize.js/actions) -A lightweight, high-performance file size utility that converts bytes to human-readable strings. Zero dependencies. 100% test coverage. +A lightweight, zero-dependency JavaScript utility that converts bytes to human-readable strings. A popular choice for client and server applications that need to display file sizes — from download counters to disk-usage reports. ## Why filesize? -- **Zero dependencies** - Pure JavaScript, no external packages -- **100% test coverage** - Reliable, well-tested codebase -- **TypeScript ready** - Full type definitions included -- **Multiple standards** - SI, IEC, and JEDEC support -- **Localization** - Intl API for international formatting -- **BigInt support** - Handle extremely large file sizes -- **Functional API** - Partial application for reusable formatters -- **Browser & Node.js** - Works everywhere +- **Zero dependencies** — no install weight, no supply-chain surface. +- **100% test coverage** — every line, branch, and function is tested. +- **TypeScript ready** — full type definitions for options and return types. +- **Three unit standards** — SI, IEC, and JEDEC, each with its own symbols. +- **Localization** — Intl-based formatting for any locale. +- **BigInt support** — sizes beyond `Number.MAX_SAFE_INTEGER`. +- **Functional API** — `partial()` creates reusable, immutable formatters. +- **Client & server** — ships ESM, CJS, and UMD builds. ## Installation @@ -23,19 +23,6 @@ A lightweight, high-performance file size utility that converts bytes to human-r npm install filesize ``` -## TypeScript - -Fully typed with TypeScript definitions included: - -```typescript -import { filesize, partial } from 'filesize'; - -const result: string = filesize(1024); -const formatted: { value: number; symbol: string; exponent: number; unit: string } = filesize(1024, { output: 'object' }); - -const formatter: (arg: number | bigint) => string = partial({ standard: 'iec' }); -``` - ## Usage ```javascript @@ -47,7 +34,9 @@ filesize(1024, {standard: "iec"}); // "1 KiB" filesize(1024, {bits: true}); // "8.19 kbit" ``` -### Partial Application +### Partial application + +`partial()` returns a pre-configured formatter with frozen options. Use it when you format many values with the same settings — it avoids re-parsing options on every call. ```javascript import {partial} from "filesize"; @@ -57,14 +46,28 @@ formatBinary(1024); // "1 KiB" formatBinary(1048576); // "1 MiB" ``` +## Standards + +filesize supports three unit standards. They differ in two ways: the base (1000 or 1024) and the unit symbols. + +| Standard | Base | Unit symbols | Example | +|----------|------|--------------|---------| +| SI | 1000 | kB, MB, GB | `filesize(1000)` → "1 kB" | +| IEC | 1024 | KiB, MiB, GiB | `filesize(1024, {standard: "iec"})` → "1 KiB" | +| JEDEC | 1024 | KB, MB, GB | `filesize(1024, {standard: "jedec"})` → "1 KB" | + +When you set `standard`, the base is implied and `base` is ignored. `base` is only consulted when `standard` is not set. + ## Options | Option | Type | Default | Description | |--------|------|---------|-------------| | `bits` | boolean | `false` | Calculate bits instead of bytes | -| `base` | number | `-1` | Number base (2 for binary, 10 for decimal, -1 for auto) | -| `round` | number | `2` | Decimal places to round | -| `locale` | string\|boolean | `""` | Locale for formatting, `true` for system locale | +| `base` | number | `-1` | Number base (2 for binary, 10 for decimal, -1 for auto). Ignored when `standard` is set | +| `round` | number | `2` | Decimal places to round to | +| `precision` | number | `0` | Significant digits (0 for auto). When set, overrides `round` | +| `pad` | boolean | `false` | Pad decimal places to match `round` | +| `locale` | string\|boolean | `""` | Locale for formatting; `true` for the system locale | | `localeOptions` | Object | `{}` | Additional locale options | | `separator` | string | `""` | Custom decimal separator | | `spacer` | string | `" "` | Value-unit separator | @@ -73,41 +76,28 @@ formatBinary(1048576); // "1 MiB" | `output` | string | `"string"` | Output format (`string`, `array`, `object`, `exponent`) | | `fullform` | boolean | `false` | Use full unit names | | `fullforms` | Array | `[]` | Custom full unit names | -| `exponent` | number | `-1` | Force specific exponent (-1 for auto) | +| `exponent` | number | `-1` | Force a specific exponent (-1 for auto) | | `roundingMethod` | string | `"round"` | Math method (`round`, `floor`, `ceil`) | -| `precision` | number | `0` | Significant digits (0 for auto) | -| `pad` | boolean | `false` | Pad decimal places | -## Output Formats +`round` controls decimal places; `precision` controls significant digits. When `precision` is greater than 0, it takes precedence over `round`. + +## Output formats ```javascript // String (default) filesize(1536); // "1.54 kB" -// Array +// Array: [value, symbol] filesize(1536, {output: "array"}); // [1.54, "kB"] -// Object +// Object: {value, symbol, exponent, unit} filesize(1536, {output: "object"}); // {value: 1.54, symbol: "kB", exponent: 1, unit: "kB"} -// Exponent +// Exponent: the unit index filesize(1536, {output: "exponent"}); // 1 ``` -## Standards - -```javascript -// SI (default, base 10) -filesize(1000); // "1 kB" - -// IEC (binary, requires base: 2) -filesize(1024, {base: 2, standard: "iec"}); // "1 KiB" - -// JEDEC (binary calculation, traditional symbols) -filesize(1024, {standard: "jedec"}); // "1 KB" -``` - ## Examples ```javascript @@ -115,17 +105,17 @@ filesize(1024, {standard: "jedec"}); // "1 KB" filesize(1024, {bits: true}); // "8.19 kbit" filesize(1024, {bits: true, base: 2}); // "8 Kibit" -// Full form +// Full unit names filesize(1024, {fullform: true}); // "1.02 kilobytes" filesize(1024, {base: 2, fullform: true}); // "1 kibibyte" -// Custom separator +// Custom decimal separator filesize(265318, {separator: ","}); // "265,32 kB" // Padding filesize(1536, {round: 3, pad: true}); // "1.536 kB" -// Precision +// Significant digits filesize(1536, {precision: 3}); // "1.54 kB" // Locale @@ -134,14 +124,16 @@ filesize(265318, {locale: "de"}); // "265,32 kB" // Custom symbols filesize(1, {symbols: {B: "Б"}}); // "1 Б" -// BigInt support +// BigInt filesize(BigInt(1024)); // "1.02 kB" // Negative numbers filesize(-1024); // "-1.02 kB" ``` -## Error Handling +## Error handling + +`filesize()` throws a `TypeError` for invalid input. ```javascript try { @@ -157,6 +149,21 @@ try { } ``` +Invalid input includes non-numeric values, `NaN`, `Infinity`, and BigInt values that overflow `Number.MAX_SAFE_INTEGER`. + +## TypeScript + +Fully typed with definitions included: + +```typescript +import {filesize, partial} from "filesize"; + +const result: string = filesize(1024); +const formatted: {value: number; symbol: string; exponent: number; unit: string} = filesize(1024, {output: "object"}); + +const formatter: (arg: number | bigint) => string = partial({standard: "iec"}); +``` + ## Testing ```bash @@ -187,7 +194,7 @@ npm run lint # Check code style npm run fix # Auto-fix linting issues ``` -### Project Structure +### Project structure ``` filesize.js/ From ca2a3adbbbeff85c3e19078185d85ab67734a97e Mon Sep 17 00:00:00 2001 From: Jason Mulligan Date: Sat, 26 Sep 2026 17:54:42 -0400 Subject: [PATCH 3/3] docs: refine intro positioning Drop the 'popular choice' framing and the download-count claim from the intro. State what the library is and who it serves, without a number that would drift over time. --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index bd02bb7..96daaf1 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ [![License](https://img.shields.io/badge/License-BSD%203--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause) [![Build Status](https://github.com/avoidwork/filesize.js/actions/workflows/ci.yml/badge.svg)](https://github.com/avoidwork/filesize.js/actions) -A lightweight, zero-dependency JavaScript utility that converts bytes to human-readable strings. A popular choice for client and server applications that need to display file sizes — from download counters to disk-usage reports. +A lightweight, zero-dependency JavaScript utility that converts bytes to human-readable strings. Built for client and server applications that need to display file sizes — from download counters to disk-usage reports. ## Why filesize?