@acus9345/tinydur 0.0.0-stage → 0.2.0

package/CHANGELOG.md

@@ -0,0 +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.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/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 acus9345
+
+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

@@ -1,3 +1,164 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# 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.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+import { readFileSync } from "node:fs";
+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 <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", "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
+
+Examples:
+  tinydur 1h30m                  5400000
+  tinydur "2 days 4 hours"       187200000
+  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];
+        if (arg === "-h" || arg === "--help") {
+            process.stdout.write(HELP);
+            return;
+        }
+        if (arg === "-v" || arg === "--version") {
+            const pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+            process.stdout.write(`${pkg.version}\n`);
+            return;
+        }
+        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) {
+                throw new UsageError(`--units needs a whole number of at least 1, e.g. "--units 3"${raw === undefined ? "" : `, got "${raw}"`}.`);
+            }
+            units = Number(raw);
+        }
+        else if (/^--?[a-z]/i.test(arg)) {
+            throw new UsageError(`Unknown option "${arg}".`);
+        }
+        else {
+            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(bytesMode ? `Missing size. Example: tinydur bytes 20MB` : `Missing duration. Example: tinydur 1h30m`);
+    const input = values.join(" ").trim();
+    // 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 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

@@ -0,0 +1,50 @@
+/**
+ * tinydur: tiny, zero-dependency duration and byte-size parsing and formatting.
+ *
+ * @example
+ * 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);
+}
+/** Options for {@link format}. */
+export interface FormatOptions {
+    /** Use long unit names, e.g. `"1 hour 30 minutes"` instead of `"1h 30m"`. Default: `false`. */
+    long?: boolean;
+    /** Maximum number of units to show, counting from the largest; the rest is rounded. Default: `2`. */
+    units?: number;
+}
+/**
+ * Parse a human-readable duration into milliseconds.
+ *
+ * Accepts units `ms`, `s`, `m`, `h`, `d`, `w`, `y` and their long forms ("minutes", "hrs", ...),
+ * combined freely: `"1h30m"`, `"1 hour and 30 minutes"`, `"1.5h"`, `"-5m"`.
+ * A bare number such as `"100"` is read as milliseconds, and numbers are returned unchanged.
+ * A year is 365.25 days.
+ *
+ * @param input - The duration, e.g. `"1h 30m"`.
+ * @returns The duration in milliseconds.
+ * @throws {@link DurationError} if the input is empty, malformed or uses an unknown unit.
+ */
+export declare function parse(input: string | number): number;
+/**
+ * Format milliseconds as a human-readable duration.
+ *
+ * Uses days, hours, minutes, seconds and milliseconds. Shows at most `units` units
+ * (default 2), starting from the largest, and rounds the rest.
+ *
+ * @param ms - The duration in milliseconds. May be negative.
+ * @param options - See {@link FormatOptions}.
+ * @returns For example `"1h 30m"`, or `"1 hour 30 minutes"` with `{ long: true }`.
+ * @throws {@link DurationError} if `ms` is not a finite number or `units` is not a whole number of at least 1.
+ */
+export declare function format(ms: number, options?: FormatOptions): string;

package/dist/index.js

@@ -0,0 +1,170 @@
+/**
+ * tinydur: tiny, zero-dependency duration and byte-size parsing and formatting.
+ *
+ * @example
+ * 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) {
+        super(message);
+        this.name = "DurationError";
+    }
+}
+const SECOND = 1000;
+const MINUTE = 60 * SECOND;
+const HOUR = 60 * MINUTE;
+const DAY = 24 * HOUR;
+const WEEK = 7 * DAY;
+const YEAR = 365.25 * DAY;
+const UNIT_MS = new Map();
+for (const [ms, names] of [
+    [1, "ms msec msecs millisecond milliseconds"],
+    [SECOND, "s sec secs second seconds"],
+    [MINUTE, "m min mins minute minutes"],
+    [HOUR, "h hr hrs hour hours"],
+    [DAY, "d day days"],
+    [WEEK, "w wk wks week weeks"],
+    [YEAR, "y yr yrs year years"],
+]) {
+    for (const name of names.split(" "))
+        UNIT_MS.set(name, ms);
+}
+const FORMAT_UNITS = [
+    { ms: DAY, short: "d", long: "day" },
+    { ms: HOUR, short: "h", long: "hour" },
+    { ms: MINUTE, short: "m", long: "minute" },
+    { ms: SECOND, short: "s", long: "second" },
+    { ms: 1, short: "ms", long: "millisecond" },
+];
+const LAST_UNIT = FORMAT_UNITS.length - 1;
+// One "<number><unit>" pair plus any separator after it (spaces, a comma, "and").
+const TOKEN = /(\d+(?:\.\d+)?|\.\d+)\s*([a-z]*)\s*(?:,\s*)?(?:and\s+)?/y;
+const EXAMPLES = `Try something like "1h 30m", "90s" or "2 days".`;
+/**
+ * Parse a human-readable duration into milliseconds.
+ *
+ * Accepts units `ms`, `s`, `m`, `h`, `d`, `w`, `y` and their long forms ("minutes", "hrs", ...),
+ * combined freely: `"1h30m"`, `"1 hour and 30 minutes"`, `"1.5h"`, `"-5m"`.
+ * A bare number such as `"100"` is read as milliseconds, and numbers are returned unchanged.
+ * A year is 365.25 days.
+ *
+ * @param input - The duration, e.g. `"1h 30m"`.
+ * @returns The duration in milliseconds.
+ * @throws {@link DurationError} if the input is empty, malformed or uses an unknown unit.
+ */
+export function parse(input) {
+    if (typeof input === "number") {
+        if (!Number.isFinite(input))
+            throw new DurationError(`Expected a finite number of milliseconds, got ${input}.`);
+        return input;
+    }
+    if (typeof input !== "string") {
+        throw new DurationError(`Expected a duration string like "1h 30m" or a number of milliseconds, got ${describe(input)}.`);
+    }
+    let text = input.trim().toLowerCase();
+    if (text === "")
+        throw new DurationError(`Cannot parse an empty string as a duration. ${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 DurationError(`Cannot parse ${quote(input)} as a duration: unexpected ${quote(text.slice(start))}. ${EXAMPLES}`);
+        }
+        const value = Number(match[1]);
+        const unit = match[2] ?? "";
+        if (unit === "") {
+            // A lone number means milliseconds; inside a longer duration it is a missing unit.
+            if (start !== 0 || TOKEN.lastIndex !== text.length) {
+                throw new DurationError(`Missing unit after ${match[1]} in ${quote(input)}. Add one, e.g. "${match[1]}m" or "${match[1]}s".`);
+            }
+            total += value;
+        }
+        else {
+            const ms = UNIT_MS.get(unit);
+            if (ms === undefined) {
+                throw new DurationError(`Unknown unit ${quote(unit)} in ${quote(input)}. Use one of: ms, s, m, h, d, w, y (long names like "minutes" work too).`);
+            }
+            total += value * ms;
+        }
+    }
+    total = Math.round(total * 1000) / 1000; // drop float noise such as 1.1 * 1000 = 1100.0000000000002
+    if (!Number.isFinite(total))
+        throw new DurationError(`${quote(input)} is too large to represent in milliseconds.`);
+    return total === 0 ? 0 : sign * total;
+}
+/**
+ * Format milliseconds as a human-readable duration.
+ *
+ * Uses days, hours, minutes, seconds and milliseconds. Shows at most `units` units
+ * (default 2), starting from the largest, and rounds the rest.
+ *
+ * @param ms - The duration in milliseconds. May be negative.
+ * @param options - See {@link FormatOptions}.
+ * @returns For example `"1h 30m"`, or `"1 hour 30 minutes"` with `{ long: true }`.
+ * @throws {@link DurationError} if `ms` is not a finite number or `units` is not a whole number of at least 1.
+ */
+export function format(ms, options = {}) {
+    if (typeof ms !== "number" || !Number.isFinite(ms)) {
+        const got = typeof ms === "number" ? String(ms) : describe(ms);
+        throw new DurationError(`format() expects a finite number of milliseconds, got ${got}. Use parse() first if you have a string.`);
+    }
+    const { long = false, units = 2 } = options;
+    if (typeof units !== "number" || !Number.isInteger(units) || units < 1) {
+        throw new DurationError(`Option "units" must be a whole number of at least 1, got ${String(units)}.`);
+    }
+    const sign = ms < 0 ? "-" : "";
+    let abs = Math.round(Math.abs(ms));
+    if (abs === 0)
+        return long ? "0 milliseconds" : "0ms";
+    // Round to the smallest shown unit; repeat if rounding carried into a bigger unit (59.9s -> 1m).
+    let first = largestUnit(abs);
+    for (;;) {
+        const step = FORMAT_UNITS[Math.min(first + units - 1, LAST_UNIT)].ms;
+        abs = Math.round(abs / step) * step;
+        const next = largestUnit(abs);
+        if (next === first)
+            break;
+        first = next;
+    }
+    const last = Math.min(first + units - 1, LAST_UNIT);
+    const parts = [];
+    let rest = abs;
+    for (let i = first; i <= last; i++) {
+        const unit = FORMAT_UNITS[i];
+        const count = i === last ? Math.round(rest / unit.ms) : Math.floor(rest / unit.ms);
+        rest -= count * unit.ms;
+        if (count > 0)
+            parts.push(long ? `${count} ${unit.long}${count === 1 ? "" : "s"}` : `${count}${unit.short}`);
+    }
+    return sign + parts.join(" ");
+}
+function largestUnit(ms) {
+    const index = FORMAT_UNITS.findIndex((unit) => ms >= unit.ms);
+    return index === -1 ? LAST_UNIT : index;
+}
+function quote(text) {
+    return JSON.stringify(text.length > 40 ? `${text.slice(0, 40)}...` : text);
+}
+function describe(value) {
+    if (value === null)
+        return "null";
+    if (Array.isArray(value))
+        return "an array";
+    return typeof value;
+}

package/package.json

@@ -1,6 +1,62 @@
 {
   "name": "@acus9345/tinydur",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "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",
+    "ms",
+    "milliseconds",
+    "parse",
+    "format",
+    "humanize",
+    "cli",
+    "bytes",
+    "filesize",
+    "size",
+    "pretty-bytes",
+    "kib",
+    "mib"
+  ],
+  "homepage": "https://github.com/acus9345/tinydur#readme",
+  "bugs": {
+    "url": "https://github.com/acus9345/tinydur/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/acus9345/tinydur.git"
+  },
+  "license": "MIT",
+  "author": "acus9345 <acus9345@gmail.com>",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "tinydur": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "CHANGELOG.md"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "lint": "tsc -p tsconfig.json --noEmit",
+    "test": "npm run build && node --test",
+    "prepublishOnly": "npm run lint && npm test"
+  },
+  "devDependencies": {
+    "@types/node": "^26.6.5",
+    "typescript": "^7.0.2"
+  }
+}