@acus9345/tinydur 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,12 @@
+# 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`.

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,117 @@
-# Temporary Holding Version
+# tinydur
 
-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.
+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

package/dist/cli.d.ts

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

package/dist/cli.js

@@ -0,0 +1,71 @@
+#!/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
+
+Usage:
+  tinydur <duration>         Print the duration in milliseconds
+  tinydur <milliseconds>     Print the milliseconds as a readable duration
+
+Options:
+  -l, --long         Use long unit names ("1 hour 30 minutes")
+  -u, --units <n>    Maximum number of units when formatting (default: 2)
+  -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
+`;
+class UsageError extends Error {
+}
+function main(argv) {
+    const values = [];
+    let long = 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 === "-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);
+        }
+    }
+    if (values.length === 0)
+        throw new UsageError(`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));
+    process.stdout.write(`${output}\n`);
+}
+try {
+    main(process.argv.slice(2));
+}
+catch (error) {
+    if (!(error instanceof DurationError || 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,46 @@
+/**
+ * tinydur: tiny, zero-dependency duration parsing and formatting.
+ *
+ * @example
+ * import { parse, format } from "tinydur";
+ * parse("1h 30m");   // 5400000
+ * format(5400000);   // "1h 30m"
+ *
+ * @packageDocumentation
+ */
+/** 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,167 @@
+/**
+ * tinydur: tiny, zero-dependency duration parsing and formatting.
+ *
+ * @example
+ * import { parse, format } from "tinydur";
+ * parse("1h 30m");   // 5400000
+ * format(5400000);   // "1h 30m"
+ *
+ * @packageDocumentation
+ */
+/** 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,56 @@
 {
   "name": "@acus9345/tinydur",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "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.",
+  "keywords": [
+    "duration",
+    "time",
+    "ms",
+    "milliseconds",
+    "parse",
+    "format",
+    "humanize",
+    "cli"
+  ],
+  "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"
+  }
+}