@acus9345/tinydur 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -1,12 +1,21 @@
-# Changelog
-
-All notable changes to this project are documented here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and this project uses [Semantic Versioning](https://semver.org/).
-
-## [0.1.0] - 2026-10-16
-
-### Added
-
-- `parse()` turns durations such as `"1h 30m"`, `"1.5h"` or `"2 days"` into milliseconds.
-- `format()` turns milliseconds into `"1h 30m"` or `"1 hour 30 minutes"`, with a `units` option.
-- `DurationError` with messages that explain how to fix bad input.
-- `tinydur` CLI with `--long`, `--units`, `--help` and `--version`.
+# Changelog
+
+All notable changes to this project are documented here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and this project uses [Semantic Versioning](https://semver.org/).
+
+## [0.2.0] - 2026-10-18
+
+### Added
+
+- `parseBytes()` turns sizes such as `"20MB"`, `"1.5 GiB"` or `"512kb"` into bytes. `KB`, `MB`... are powers of 1000 (or 1024 with `{ binary: true }`); `KiB`, `MiB`... are always powers of 1024.
+- `formatBytes()` turns bytes into `"20 MB"`, `"19.07 MiB"` or `"1.5 megabytes"`, with `binary`, `decimals` and `long` options.
+- `ByteSizeError` with messages that explain how to fix bad input.
+- The CLI converts sizes too: `tinydur 20MB`, `tinydur bytes 20000000`, and `--binary`.
+
+## [0.1.0] - 2026-10-16
+
+### Added
+
+- `parse()` turns durations such as `"1h 30m"`, `"1.5h"` or `"2 days"` into milliseconds.
+- `format()` turns milliseconds into `"1h 30m"` or `"1 hour 30 minutes"`, with a `units` option.
+- `DurationError` with messages that explain how to fix bad input.
+- `tinydur` CLI with `--long`, `--units`, `--help` and `--version`.

package/README.md

@@ -1,117 +1,164 @@
-# tinydur
-
-Tiny, zero-dependency duration parser and formatter: `"1h 30m"` ⇄ `5400000`, with a CLI.
-
-A small replacement for `ms`, `parse-duration` and `humanize-duration`. Fully typed, ESM, no dependencies.
-
-## Install
-
-```bash
-npm install @acus9345/tinydur
-```
-
-Requires Node.js 22 or newer.
-
-## Quick start
-
-Save this as `example.mjs`:
-
-```js
-import { parse, format } from "@acus9345/tinydur";
-
-console.log(parse("1h 30m"));                    // 5400000
-console.log(format(5400000));                    // 1h 30m
-console.log(format(5400000, { long: true }));    // 1 hour 30 minutes
-```
-
-Run it:
-
-```bash
-node example.mjs
-```
-
-Or use the CLI without installing anything:
-
-```bash
-npx @acus9345/tinydur 1h30m
-```
-
-## API
-
-### `parse(input: string | number): number`
-
-Turns a duration into milliseconds.
-
-| Input                     | Result       |
-| ------------------------- | ------------ |
-| `"1h 30m"`, `"1h30m"`     | `5400000`    |
-| `"1 hour and 30 minutes"` | `5400000`    |
-| `"1.5h"`                  | `5400000`    |
-| `"90s"`                   | `90000`      |
-| `"2 days"`                | `172800000`  |
-| `"-5m"`                   | `-300000`    |
-| `"100"` or `100`          | `100`        |
-
-Units: `ms`, `s`, `m`, `h`, `d`, `w`, `y`, plus long forms such as `sec`, `mins`, `hours`, `days`, `weeks`, `years`. Case and spacing don't matter. A year is 365.25 days.
-
-### `format(ms: number, options?): string`
-
-Turns milliseconds into a readable duration, using days, hours, minutes, seconds and milliseconds.
-
-| Option  | Default | Meaning                                                          |
-| ------- | ------- | ---------------------------------------------------------------- |
-| `long`  | `false` | `"1 hour 30 minutes"` instead of `"1h 30m"`                      |
-| `units` | `2`     | Maximum number of units, counting from the largest; the rest is rounded |
-
-```js
-format(90061001);                // "1d 1h"
-format(90061001, { units: 4 });  // "1d 1h 1m 1s"
-format(59999, { units: 1 });     // "1m"
-```
-
-### `DurationError`
-
-Both functions throw a `DurationError` (a subclass of `Error`) for bad input. Its message says what was wrong and how to fix it:
-
-```js
-import { parse, DurationError } from "@acus9345/tinydur";
-
-try {
-  parse("5 parsecs");
-} catch (error) {
-  if (error instanceof DurationError) console.log(error.message);
-  // Unknown unit "parsecs" in "5 parsecs". Use one of: ms, s, m, h, d, w, y (long names like "minutes" work too).
-}
-```
-
-## CLI
-
-```bash
-npx @acus9345/tinydur 1h30m
-npx @acus9345/tinydur "2 days 4 hours"
-npx @acus9345/tinydur 5400000 --long
-npx @acus9345/tinydur 90061001 --units 4
-```
-
-Prints `5400000`, `187200000`, `1 hour 30 minutes` and `1d 1h 1m 1s`. A plain number is formatted; anything else is parsed to milliseconds.
-
-| Option            | Meaning                                      |
-| ----------------- | -------------------------------------------- |
-| `-l`, `--long`    | Long unit names                              |
-| `-u`, `--units N` | Maximum number of units when formatting      |
-| `-h`, `--help`    | Show help                                    |
-| `-v`, `--version` | Show version                                 |
-
-Works the same in PowerShell, cmd and POSIX shells. Quote durations that contain spaces, or pass the parts as separate arguments (`npx @acus9345/tinydur 1h 30m`). After `npm install`, the command is also available as `tinydur` in npm scripts.
-
-## Troubleshooting
-
-- **`ERR_REQUIRE_ESM` or `require() of ES Module`**: tinydur is an ES module. Use `import`, or upgrade to Node.js 22.12+ where `require("@acus9345/tinydur")` works.
-- **`Missing unit after 30`**: every number in a multi-part duration needs a unit, e.g. `"1h 30m"` rather than `"1h 30"`. A single bare number is read as milliseconds.
-- **`m` means minutes**: there is no month unit because months vary in length. Use days or weeks.
-- **`format("5000")` throws**: `format` takes a number. Call `parse` first if you have a string.
-- **PowerShell treats `-5m` oddly in scripts**: quote it: `npx @acus9345/tinydur "-5m"`.
-
-## License
-
-MIT
+# tinydur
+
+Tiny, zero-dependency duration and byte-size parser and formatter: `"1h 30m"` ⇄ `5400000` and `"20MB"` ⇄ `20000000`, with a CLI.
+
+A small replacement for `ms`, `parse-duration`, `humanize-duration`, `bytes` and `pretty-bytes`. Fully typed, ESM, no dependencies.
+
+## Install
+
+```bash
+npm install @acus9345/tinydur
+```
+
+Requires Node.js 22 or newer.
+
+## Quick start
+
+Save this as `example.mjs`:
+
+```js
+import { parse, format, parseBytes, formatBytes } from "@acus9345/tinydur";
+
+console.log(parse("1h 30m"));                    // 5400000
+console.log(format(5400000));                    // 1h 30m
+console.log(format(5400000, { long: true }));    // 1 hour 30 minutes
+console.log(parseBytes("20MB"));                 // 20000000
+console.log(formatBytes(1610612736, { binary: true })); // 1.5 GiB
+```
+
+Run it:
+
+```bash
+node example.mjs
+```
+
+Or use the CLI without installing anything:
+
+```bash
+npx @acus9345/tinydur 1h30m
+```
+
+## API
+
+### `parse(input: string | number): number`
+
+Turns a duration into milliseconds.
+
+| Input                     | Result       |
+| ------------------------- | ------------ |
+| `"1h 30m"`, `"1h30m"`     | `5400000`    |
+| `"1 hour and 30 minutes"` | `5400000`    |
+| `"1.5h"`                  | `5400000`    |
+| `"90s"`                   | `90000`      |
+| `"2 days"`                | `172800000`  |
+| `"-5m"`                   | `-300000`    |
+| `"100"` or `100`          | `100`        |
+
+Units: `ms`, `s`, `m`, `h`, `d`, `w`, `y`, plus long forms such as `sec`, `mins`, `hours`, `days`, `weeks`, `years`. Case and spacing don't matter. A year is 365.25 days.
+
+### `format(ms: number, options?): string`
+
+Turns milliseconds into a readable duration, using days, hours, minutes, seconds and milliseconds.
+
+| Option  | Default | Meaning                                                          |
+| ------- | ------- | ---------------------------------------------------------------- |
+| `long`  | `false` | `"1 hour 30 minutes"` instead of `"1h 30m"`                      |
+| `units` | `2`     | Maximum number of units, counting from the largest; the rest is rounded |
+
+```js
+format(90061001);                // "1d 1h"
+format(90061001, { units: 4 });  // "1d 1h 1m 1s"
+format(59999, { units: 1 });     // "1m"
+```
+
+### `parseBytes(input: string | number, options?): number`
+
+Turns a size into bytes.
+
+| Input                    | Result          |
+| ------------------------ | --------------- |
+| `"20MB"`, `"20 mb"`      | `20000000`      |
+| `"1.5GB"`                | `1500000000`    |
+| `"1.5 GiB"`              | `1610612736`    |
+| `"512 KiB"`              | `524288`        |
+| `"1GB 512MB"`            | `1512000000`    |
+| `"2 megabytes"`          | `2000000`       |
+| `"100"` or `100`         | `100`           |
+
+`kB`, `MB`, `GB`, `TB`, `PB` and `EB` are powers of 1000, as in the SI standard and on macOS and Linux. Pass `{ binary: true }` to read them as powers of 1024, like Windows does. `KiB`, `MiB`, `GiB`... are always powers of 1024. Short forms (`k`, `m`, `g`) and long names (`kilobytes`, `gibibytes`) work too, case doesn't matter, and the result is rounded to whole bytes.
+
+### `formatBytes(bytes: number, options?): string`
+
+| Option     | Default | Meaning                                                    |
+| ---------- | ------- | ---------------------------------------------------------- |
+| `binary`   | `false` | Powers of 1024 with `KiB`, `MiB`... instead of `kB`, `MB`  |
+| `decimals` | `2`     | Most digits after the decimal point; trailing zeros dropped |
+| `long`     | `false` | `"20 megabytes"` instead of `"20 MB"`                      |
+
+```js
+formatBytes(20000000);                    // "20 MB"
+formatBytes(20000000, { binary: true });  // "19.07 MiB"
+formatBytes(1536);                        // "1.54 kB"
+formatBytes(1500000, { long: true });     // "1.5 megabytes"
+```
+
+Bad input throws a `ByteSizeError` that explains the fix, just like `DurationError` below.
+
+### `DurationError`
+
+Both functions throw a `DurationError` (a subclass of `Error`) for bad input. Its message says what was wrong and how to fix it:
+
+```js
+import { parse, DurationError } from "@acus9345/tinydur";
+
+try {
+  parse("5 parsecs");
+} catch (error) {
+  if (error instanceof DurationError) console.log(error.message);
+  // Unknown unit "parsecs" in "5 parsecs". Use one of: ms, s, m, h, d, w, y (long names like "minutes" work too).
+}
+```
+
+## CLI
+
+```bash
+npx @acus9345/tinydur 1h30m
+npx @acus9345/tinydur "2 days 4 hours"
+npx @acus9345/tinydur 5400000 --long
+npx @acus9345/tinydur 90061001 --units 4
+```
+
+Prints `5400000`, `187200000`, `1 hour 30 minutes` and `1d 1h 1m 1s`. A plain number is formatted; anything else is parsed to milliseconds.
+
+Sizes work the same way. Anything with a byte unit is converted to bytes, and `bytes` formats a number of bytes:
+
+```bash
+npx @acus9345/tinydur 20MB                    # 20000000
+npx @acus9345/tinydur 1.5GiB                  # 1610612736
+npx @acus9345/tinydur bytes 20000000          # 20 MB
+npx @acus9345/tinydur bytes 20000000 --binary # 19.07 MiB
+```
+
+`20m` on its own still means 20 minutes; write `20MB`, or `tinydur bytes 20m`, for megabytes.
+
+| Option            | Meaning                                      |
+| ----------------- | -------------------------------------------- |
+| `-l`, `--long`    | Long unit names                              |
+| `-u`, `--units N` | Maximum number of units when formatting      |
+| `-b`, `--binary`  | Sizes in powers of 1024 (`KiB`, `MiB`...)    |
+| `-h`, `--help`    | Show help                                    |
+| `-v`, `--version` | Show version                                 |
+
+Works the same in PowerShell, cmd and POSIX shells. Quote durations that contain spaces, or pass the parts as separate arguments (`npx @acus9345/tinydur 1h 30m`). After `npm install`, the command is also available as `tinydur` in npm scripts.
+
+## Troubleshooting
+
+- **`ERR_REQUIRE_ESM` or `require() of ES Module`**: tinydur is an ES module. Use `import`, or upgrade to Node.js 22.12+ where `require("@acus9345/tinydur")` works.
+- **`Missing unit after 30`**: every number in a multi-part duration needs a unit, e.g. `"1h 30m"` rather than `"1h 30"`. A single bare number is read as milliseconds.
+- **`m` means minutes**: there is no month unit because months vary in length. Use days or weeks.
+- **`format("5000")` throws**: `format` takes a number. Call `parse` first if you have a string.
+- **PowerShell treats `-5m` oddly in scripts**: quote it: `npx @acus9345/tinydur "-5m"`.
+
+## License
+
+MIT

package/dist/bytes.d.ts

@@ -0,0 +1,41 @@
+/** Thrown for invalid byte sizes or options. The message says what went wrong and how to fix it. */
+export declare class ByteSizeError extends Error {
+    constructor(message: string);
+}
+/** Options for {@link parseBytes}. */
+export interface ParseBytesOptions {
+    /**
+     * Read `KB`, `MB`, `GB`... as powers of 1024, like Windows and many older tools.
+     * Default: `false`, so `1 MB` is 1,000,000 bytes (SI). `KiB`, `MiB`... are always powers of 1024.
+     */
+    binary?: boolean;
+}
+/** Options for {@link formatBytes}. */
+export interface FormatBytesOptions {
+    /** Use powers of 1024 and `KiB`, `MiB`... Default: `false` (powers of 1000, `kB`, `MB`...). */
+    binary?: boolean;
+    /** Most digits after the decimal point; trailing zeros are dropped. Default: `2`. */
+    decimals?: number;
+    /** Long unit names: `"1.5 megabytes"`. Default: `false`. */
+    long?: boolean;
+}
+/** Byte units that can't be mistaken for anything else (used by the CLI to tell sizes from durations). */
+export declare const UNAMBIGUOUS_BYTE_UNIT: RegExp;
+/**
+ * Parse a human-readable size into bytes.
+ *
+ * Units: `B`, `kB`/`KB`, `MB`, `GB`, `TB`, `PB`, `EB` (powers of 1000, or 1024 with
+ * `{ binary: true }`), `KiB`, `MiB`, `GiB`, `TiB`, `PiB`, `EiB` (always 1024), the
+ * short forms `k`, `m`, `g`... and long names (`megabytes`, `gibibytes`). Case and
+ * spacing don't matter, decimals work (`"1.5GB"`), parts can be combined (`"1GB 512MB"`),
+ * and a bare number is bytes. The result is rounded to whole bytes.
+ *
+ * @throws {@link ByteSizeError} if the input is empty, malformed or uses an unknown unit.
+ */
+export declare function parseBytes(input: string | number, options?: ParseBytesOptions): number;
+/**
+ * Format a number of bytes, like `"20 MB"`, `"19.07 MiB"` or `"1.5 kilobytes"`.
+ *
+ * @throws {@link ByteSizeError} if `bytes` is not a finite number or `decimals` is invalid.
+ */
+export declare function formatBytes(bytes: number, options?: FormatBytesOptions): string;

package/dist/bytes.js

@@ -0,0 +1,126 @@
+/** Thrown for invalid byte sizes or options. The message says what went wrong and how to fix it. */
+export class ByteSizeError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ByteSizeError";
+    }
+}
+const PREFIXES = ["", "k", "m", "g", "t", "p", "e"];
+const LONG_PREFIXES = ["", "kilo", "mega", "giga", "tera", "peta", "exa"];
+const LONG_BINARY = ["", "kibi", "mebi", "gibi", "tebi", "pebi", "exbi"];
+/** unit name → [power, binary?]; `undefined` binary means "decimal unless the binary option is set". */
+const UNITS = new Map();
+for (const [power, prefix] of PREFIXES.entries()) {
+    if (power === 0) {
+        for (const name of ["b", "byte", "bytes"])
+            UNITS.set(name, [0, false]);
+        continue;
+    }
+    UNITS.set(`${prefix}b`, [power, undefined]);
+    UNITS.set(prefix, [power, undefined]);
+    UNITS.set(`${prefix}ib`, [power, true]);
+    UNITS.set(`${LONG_PREFIXES[power]}byte`, [power, undefined]);
+    UNITS.set(`${LONG_PREFIXES[power]}bytes`, [power, undefined]);
+    UNITS.set(`${LONG_BINARY[power]}byte`, [power, true]);
+    UNITS.set(`${LONG_BINARY[power]}bytes`, [power, true]);
+}
+const TOKEN = /(\d+(?:\.\d+)?|\.\d+)\s*([a-z]*)\s*(?:,\s*)?/y;
+const EXAMPLES = `Try something like "20MB", "1.5 GiB" or "512kb".`;
+/** Byte units that can't be mistaken for anything else (used by the CLI to tell sizes from durations). */
+export const UNAMBIGUOUS_BYTE_UNIT = /^(?:b|bytes?|[kmgtpe]i?b|(?:kilo|mega|giga|tera|peta|exa|kibi|mebi|gibi|tebi|pebi|exbi)bytes?)$/i;
+/**
+ * Parse a human-readable size into bytes.
+ *
+ * Units: `B`, `kB`/`KB`, `MB`, `GB`, `TB`, `PB`, `EB` (powers of 1000, or 1024 with
+ * `{ binary: true }`), `KiB`, `MiB`, `GiB`, `TiB`, `PiB`, `EiB` (always 1024), the
+ * short forms `k`, `m`, `g`... and long names (`megabytes`, `gibibytes`). Case and
+ * spacing don't matter, decimals work (`"1.5GB"`), parts can be combined (`"1GB 512MB"`),
+ * and a bare number is bytes. The result is rounded to whole bytes.
+ *
+ * @throws {@link ByteSizeError} if the input is empty, malformed or uses an unknown unit.
+ */
+export function parseBytes(input, options = {}) {
+    if (typeof input === "number") {
+        if (!Number.isFinite(input))
+            throw new ByteSizeError(`Expected a finite number of bytes, got ${input}.`);
+        return Math.round(input);
+    }
+    if (typeof input !== "string") {
+        throw new ByteSizeError(`Expected a size string like "20MB" or a number of bytes, got ${input === null ? "null" : typeof input}.`);
+    }
+    let text = input.trim().toLowerCase();
+    if (text === "")
+        throw new ByteSizeError(`Cannot parse an empty string as a size. ${EXAMPLES}`);
+    let sign = 1;
+    if (text[0] === "-" || text[0] === "+") {
+        if (text[0] === "-")
+            sign = -1;
+        text = text.slice(1).trimStart();
+    }
+    let total = 0;
+    TOKEN.lastIndex = 0;
+    while (TOKEN.lastIndex < text.length) {
+        const start = TOKEN.lastIndex;
+        const match = TOKEN.exec(text);
+        if (!match)
+            throw new ByteSizeError(`Cannot parse ${quote(input)} as a size: unexpected ${quote(text.slice(start))}. ${EXAMPLES}`);
+        const value = Number(match[1]);
+        const unit = match[2] ?? "";
+        if (unit === "") {
+            if (start !== 0 || TOKEN.lastIndex !== text.length) {
+                throw new ByteSizeError(`Missing unit after ${match[1]} in ${quote(input)}. Add one, e.g. "${match[1]}MB".`);
+            }
+            total += value;
+            continue;
+        }
+        const found = UNITS.get(unit);
+        if (found === undefined) {
+            throw new ByteSizeError(`Unknown unit ${quote(unit)} in ${quote(input)}. Use B, kB, MB, GB, TB, PB, or KiB, MiB, GiB, TiB, PiB.`);
+        }
+        const [power, binary] = found;
+        const base = (binary ?? options.binary === true) ? 1024 : 1000;
+        total += value * base ** power;
+    }
+    const bytes = Math.round(total);
+    if (!Number.isFinite(bytes))
+        throw new ByteSizeError(`${quote(input)} is too large to represent.`);
+    return bytes === 0 ? 0 : sign * bytes;
+}
+/**
+ * Format a number of bytes, like `"20 MB"`, `"19.07 MiB"` or `"1.5 kilobytes"`.
+ *
+ * @throws {@link ByteSizeError} if `bytes` is not a finite number or `decimals` is invalid.
+ */
+export function formatBytes(bytes, options = {}) {
+    if (typeof bytes !== "number" || !Number.isFinite(bytes)) {
+        throw new ByteSizeError(`formatBytes() expects a finite number of bytes, got ${String(bytes)}. Use parseBytes() first if you have a string.`);
+    }
+    const { binary = false, decimals = 2, long = false } = options;
+    if (!Number.isInteger(decimals) || decimals < 0 || decimals > 20) {
+        throw new ByteSizeError(`Option "decimals" must be a whole number from 0 to 20, got ${String(decimals)}.`);
+    }
+    const base = binary ? 1024 : 1000;
+    const sign = bytes < 0 ? "-" : "";
+    let value = Math.abs(bytes);
+    let power = 0;
+    while (value >= base && power < PREFIXES.length - 1) {
+        value /= base;
+        power++;
+    }
+    let rounded = Number(value.toFixed(power === 0 ? 0 : decimals));
+    // 999.999 kB rounds to 1000 kB: move up a unit.
+    if (rounded >= base && power < PREFIXES.length - 1) {
+        power++;
+        rounded = Number((rounded / base).toFixed(decimals));
+    }
+    const number = String(rounded);
+    if (long) {
+        const name = power === 0 ? "byte" : `${(binary ? LONG_BINARY : LONG_PREFIXES)[power]}byte`;
+        return `${sign}${number} ${name}${rounded === 1 ? "" : "s"}`;
+    }
+    const unit = power === 0 ? "B" : binary ? `${PREFIXES[power].toUpperCase()}iB` : `${power === 1 ? "k" : PREFIXES[power].toUpperCase()}B`;
+    return `${sign}${number} ${unit}`;
+}
+function quote(text) {
+    return JSON.stringify(text.length > 40 ? `${text.slice(0, 40)}...` : text);
+}

package/dist/cli.js

@@ -1,15 +1,19 @@
 #!/usr/bin/env node
 import { readFileSync } from "node:fs";
-import { DurationError, format, parse } from "./index.js";
-const HELP = `tinydur - convert between readable durations and milliseconds
+import { ByteSizeError, DurationError, format, formatBytes, parse, parseBytes } from "./index.js";
+import { UNAMBIGUOUS_BYTE_UNIT } from "./bytes.js";
+const HELP = `tinydur - convert between readable durations or sizes and numbers
 
 Usage:
-  tinydur <duration>         Print the duration in milliseconds
-  tinydur <milliseconds>     Print the milliseconds as a readable duration
+  tinydur <duration>            Print the duration in milliseconds
+  tinydur <milliseconds>        Print the milliseconds as a readable duration
+  tinydur <size>                Print the size in bytes (when it has a byte unit, like 20MB)
+  tinydur bytes <size|bytes>    Convert sizes either way
 
 Options:
-  -l, --long         Use long unit names ("1 hour 30 minutes")
-  -u, --units <n>    Maximum number of units when formatting (default: 2)
+  -l, --long         Use long unit names ("1 hour 30 minutes", "20 megabytes")
+  -u, --units <n>    Maximum number of units when formatting durations (default: 2)
+  -b, --binary       Sizes: KB, MB... mean powers of 1024, and output uses KiB, MiB...
   -h, --help         Show this help
   -v, --version      Show the version number
 
@@ -19,12 +23,18 @@ Examples:
   tinydur 5400000                1h 30m
   tinydur 5400000 --long         1 hour 30 minutes
   tinydur 90061001 --units 4     1d 1h 1m 1s
+  tinydur 20MB                   20000000
+  tinydur 1.5GiB                 1610612736
+  tinydur bytes 20000000         20 MB
+  tinydur bytes 20000000 -b      19.07 MiB
 `;
 class UsageError extends Error {
 }
+const NUMBER = /^[+-]?(\d+\.?\d*|\.\d+)$/;
 function main(argv) {
     const values = [];
     let long = false;
+    let binary = false;
     let units;
     for (let i = 0; i < argv.length; i++) {
         const arg = argv[i];
@@ -40,6 +50,9 @@ function main(argv) {
         if (arg === "-l" || arg === "--long") {
             long = true;
         }
+        else if (arg === "-b" || arg === "--binary") {
+            binary = true;
+        }
         else if (arg === "-u" || arg === "--units" || arg.startsWith("--units=")) {
             const raw = arg.startsWith("--units=") ? arg.slice("--units=".length) : argv[++i];
             if (raw === undefined || !/^\d+$/.test(raw) || Number(raw) < 1) {
@@ -54,17 +67,32 @@ function main(argv) {
             values.push(arg);
         }
     }
+    let bytesMode = false;
+    if (values[0]?.toLowerCase() === "bytes" || values[0]?.toLowerCase() === "size") {
+        bytesMode = true;
+        values.shift();
+    }
     if (values.length === 0)
-        throw new UsageError(`Missing duration. Example: tinydur 1h30m`);
+        throw new UsageError(bytesMode ? `Missing size. Example: tinydur bytes 20MB` : `Missing duration. Example: tinydur 1h30m`);
     const input = values.join(" ").trim();
-    const output = /^[+-]?(\d+\.?\d*|\.\d+)$/.test(input) ? format(Number(input), { long, units }) : String(parse(input));
+    // A size with an unmistakable byte unit (20MB, 1.5 GiB) is converted to bytes even without "bytes".
+    const units_ = input.toLowerCase().match(/[a-z]+/g) ?? [];
+    if (!bytesMode && units_.length > 0 && units_.every((u) => UNAMBIGUOUS_BYTE_UNIT.test(u)))
+        bytesMode = true;
+    let output;
+    if (bytesMode) {
+        output = NUMBER.test(input) ? formatBytes(Number(input), { binary, long }) : String(parseBytes(input, { binary }));
+    }
+    else {
+        output = NUMBER.test(input) ? format(Number(input), { long, units }) : String(parse(input));
+    }
     process.stdout.write(`${output}\n`);
 }
 try {
     main(process.argv.slice(2));
 }
 catch (error) {
-    if (!(error instanceof DurationError || error instanceof UsageError))
+    if (!(error instanceof DurationError || error instanceof ByteSizeError || error instanceof UsageError))
         throw error;
     process.stderr.write(`tinydur: ${error.message}\nRun "tinydur --help" for usage.\n`);
     process.exitCode = 1;

package/dist/index.d.ts

@@ -1,13 +1,17 @@
 /**
- * tinydur: tiny, zero-dependency duration parsing and formatting.
+ * tinydur: tiny, zero-dependency duration and byte-size parsing and formatting.
  *
  * @example
- * import { parse, format } from "tinydur";
- * parse("1h 30m");   // 5400000
- * format(5400000);   // "1h 30m"
+ * import { parse, format, parseBytes, formatBytes } from "@acus9345/tinydur";
+ * parse("1h 30m");          // 5400000
+ * format(5400000);          // "1h 30m"
+ * parseBytes("20MB");       // 20000000
+ * formatBytes(20000000);    // "20 MB"
  *
  * @packageDocumentation
  */
+export { ByteSizeError, formatBytes, parseBytes } from "./bytes.js";
+export type { FormatBytesOptions, ParseBytesOptions } from "./bytes.js";
 /** Thrown for invalid durations or options. The message says what went wrong and how to fix it. */
 export declare class DurationError extends Error {
     constructor(message: string);

package/dist/index.js

@@ -1,13 +1,16 @@
 /**
- * tinydur: tiny, zero-dependency duration parsing and formatting.
+ * tinydur: tiny, zero-dependency duration and byte-size parsing and formatting.
  *
  * @example
- * import { parse, format } from "tinydur";
- * parse("1h 30m");   // 5400000
- * format(5400000);   // "1h 30m"
+ * import { parse, format, parseBytes, formatBytes } from "@acus9345/tinydur";
+ * parse("1h 30m");          // 5400000
+ * format(5400000);          // "1h 30m"
+ * parseBytes("20MB");       // 20000000
+ * formatBytes(20000000);    // "20 MB"
  *
  * @packageDocumentation
  */
+export { ByteSizeError, formatBytes, parseBytes } from "./bytes.js";
 /** Thrown for invalid durations or options. The message says what went wrong and how to fix it. */
 export class DurationError extends Error {
     constructor(message) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@acus9345/tinydur",
-  "version": "0.1.0",
-  "description": "Tiny, zero-dependency duration parser and formatter (\"1h 30m\" <-> milliseconds) with a CLI. A small replacement for ms, parse-duration and humanize-duration.",
+  "version": "0.2.0",
+  "description": "Tiny, zero-dependency duration and byte-size parser and formatter (\"1h 30m\" <-> milliseconds, \"20MB\" <-> bytes) with a CLI. A small replacement for ms, parse-duration, humanize-duration, bytes and pretty-bytes.",
   "keywords": [
     "duration",
     "time",
@@ -10,7 +10,13 @@
     "parse",
     "format",
     "humanize",
-    "cli"
+    "cli",
+    "bytes",
+    "filesize",
+    "size",
+    "pretty-bytes",
+    "kib",
+    "mib"
   ],
   "homepage": "https://github.com/acus9345/tinydur#readme",
   "bugs": {