@suzukihayate/humanun 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hayate Suzuki (鈴木颯)
+
+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

@@ -0,0 +1,46 @@
+# humanun
+
+Format **and** parse human-friendly **bytes**, **durations** and **numbers** — round-trippable, zero dependencies.
+
+Most libraries only format (number → string). `humanun` goes both ways, so `parse(format(x))` gives you back `x` for clean values.
+
+- Zero dependencies, typed (TypeScript), ESM — Node / Deno / Bun / browser
+- Bytes (SI or binary), durations, compact numbers
+
+## Install
+```bash
+npm install @suzukihayate/humanun
+```
+
+## Usage
+```js
+import { bytes, parseBytes, duration, parseDuration, number, parseNumber } from '@suzukihayate/humanun';
+
+bytes(1500);                  // "1.5 kB"
+bytes(1572864, { binary: true }); // "1.5 MiB"
+parseBytes('1.5 MB');         // 1500000
+parseBytes('1536 KiB');       // 1572864
+
+duration(5400000);            // "1h 30m"
+parseDuration('1h30m');       // 5400000
+parseDuration('2.5h');        // 9000000
+
+number(1500);                 // "1.5K"
+parseNumber('2.3M');          // 2300000
+parseNumber('1,500');         // 1500
+```
+
+## API
+- `bytes(n, { binary?, decimals?, space? })` / `parseBytes(str)`
+- `duration(ms, { parts? })` / `parseDuration(str)`  (units: ms, s, m, h, d, w)
+- `number(n, { decimals? })` / `parseNumber(str)`  (K, M, B, T)
+
+`parseBytes` understands both SI (`kB`, `MB`) and binary (`KiB`, `MiB`) suffixes, so parsing is always unambiguous.
+
+## Test
+```bash
+node --test
+```
+
+## License
+MIT © 2026 Hayate Suzuki

package/index.d.ts

@@ -0,0 +1,12 @@
+export function bytes(n: number, opts?: { binary?: boolean; decimals?: number; space?: boolean }): string;
+export function parseBytes(str: string): number;
+export function duration(ms: number, opts?: { parts?: number }): string;
+export function parseDuration(str: string): number;
+export function number(n: number, opts?: { decimals?: number }): string;
+export function parseNumber(str: string): number;
+declare const _default: {
+  bytes: typeof bytes; parseBytes: typeof parseBytes;
+  duration: typeof duration; parseDuration: typeof parseDuration;
+  number: typeof number; parseNumber: typeof parseNumber;
+};
+export default _default;

package/index.js

@@ -0,0 +1,111 @@
+// humanun — Format AND parse human-friendly bytes, durations and numbers.
+//   Round-trippable: parse(format(x)) === x for clean values.
+//   Zero dependencies.
+
+/* ----------------------------- bytes ----------------------------- */
+const SI = ['B', 'kB', 'MB', 'GB', 'TB', 'PB', 'EB'];
+const IEC = ['B', 'KiB', 'MiB', 'GiB', 'TiB', 'PiB', 'EiB'];
+
+/**
+ * Format a byte count into a human-readable string.
+ * @param {number} n bytes
+ * @param {{ binary?: boolean, decimals?: number, space?: boolean }} [opts]
+ *   binary: use 1024 + IEC units (KiB...). decimals: max fraction digits (default 2).
+ */
+export function bytes(n, opts = {}) {
+  const { binary = false, decimals = 2, space = true } = opts;
+  const base = binary ? 1024 : 1000;
+  const units = binary ? IEC : SI;
+  const sign = n < 0 ? '-' : '';
+  let v = Math.abs(n);
+  let i = 0;
+  while (v >= base && i < units.length - 1) { v /= base; i++; }
+  const num = i === 0 ? String(v) : trimNum(v.toFixed(decimals));
+  return `${sign}${num}${space ? ' ' : ''}${units[i]}`;
+}
+
+const BYTE_UNITS = {
+  b: 1, kb: 1e3, mb: 1e6, gb: 1e9, tb: 1e12, pb: 1e15, eb: 1e18,
+  kib: 1024, mib: 1024 ** 2, gib: 1024 ** 3, tib: 1024 ** 4, pib: 1024 ** 5, eib: 1024 ** 6,
+};
+
+/** Parse "1.5 MB" / "1536KiB" / "1024" into a number of bytes. */
+export function parseBytes(str) {
+  const m = String(str).trim().match(/^(-?\d+(?:\.\d+)?)\s*([a-zA-Z]+)?$/);
+  if (!m) throw new Error(`humanun: cannot parse bytes: "${str}"`);
+  const mult = m[2] ? BYTE_UNITS[m[2].toLowerCase()] : 1;
+  if (mult === undefined) throw new Error(`humanun: unknown byte unit: "${m[2]}"`);
+  return Math.round(parseFloat(m[1]) * mult);
+}
+
+/* ---------------------------- duration --------------------------- */
+const DUR = [
+  ['w', 604800000], ['d', 86400000], ['h', 3600000], ['m', 60000], ['s', 1000], ['ms', 1],
+];
+
+/**
+ * Format a millisecond duration into "1h 30m" style.
+ * @param {number} ms
+ * @param {{ parts?: number }} [opts] parts: max number of units to show (default 2).
+ */
+export function duration(ms, opts = {}) {
+  const { parts = 2 } = opts;
+  let rem = Math.abs(Math.round(ms));
+  const sign = ms < 0 ? '-' : '';
+  if (rem === 0) return '0ms';
+  const out = [];
+  for (const [unit, size] of DUR) {
+    if (rem >= size && out.length < parts) {
+      const q = Math.floor(rem / size);
+      rem -= q * size;
+      out.push(`${q}${unit}`);
+    }
+  }
+  return sign + out.join(' ');
+}
+
+const DUR_UNITS = { ms: 1, s: 1000, m: 60000, min: 60000, h: 3600000, hr: 3600000, d: 86400000, w: 604800000 };
+
+/** Parse "1h30m" / "90m" / "2.5h" / "500ms" into milliseconds. */
+export function parseDuration(str) {
+  const s = String(str).trim();
+  if (/^-?\d+(\.\d+)?$/.test(s)) return Math.round(parseFloat(s)); // bare number = ms
+  const re = /(-?\d+(?:\.\d+)?)\s*(ms|min|hr|[smhdw])/gi;
+  let total = 0, matched = false, m;
+  while ((m = re.exec(s)) !== null) {
+    matched = true;
+    total += parseFloat(m[1]) * DUR_UNITS[m[2].toLowerCase()];
+  }
+  if (!matched) throw new Error(`humanun: cannot parse duration: "${str}"`);
+  return Math.round(total);
+}
+
+/* ---------------------------- numbers ---------------------------- */
+const NUM = [['T', 1e12], ['B', 1e9], ['M', 1e6], ['K', 1e3]];
+
+/** Format a number compactly: 1500 -> "1.5K". */
+export function number(n, opts = {}) {
+  const { decimals = 1 } = opts;
+  const sign = n < 0 ? '-' : '';
+  const v = Math.abs(n);
+  for (const [suffix, size] of NUM) {
+    if (v >= size) return `${sign}${trimNum((v / size).toFixed(decimals))}${suffix}`;
+  }
+  return `${sign}${v}`;
+}
+
+const NUM_UNITS = { k: 1e3, m: 1e6, b: 1e9, t: 1e12 };
+
+/** Parse "1.5K" / "2.3M" / "1,500" into a number. */
+export function parseNumber(str) {
+  const s = String(str).trim().replace(/,/g, '');
+  const m = s.match(/^(-?\d+(?:\.\d+)?)\s*([kmbtKMBT])?$/);
+  if (!m) throw new Error(`humanun: cannot parse number: "${str}"`);
+  const mult = m[2] ? NUM_UNITS[m[2].toLowerCase()] : 1;
+  return parseFloat(m[1]) * mult;
+}
+
+/* ----------------------------- utils ----------------------------- */
+function trimNum(s) { return s.replace(/\.0+$/, '').replace(/(\.\d*?)0+$/, '$1'); }
+
+export default { bytes, parseBytes, duration, parseDuration, number, parseNumber };

package/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "@suzukihayate/humanun",
+  "version": "0.1.0",
+  "description": "Format AND parse human-friendly bytes, durations and numbers. Round-trippable, zero dependencies.",
+  "type": "module",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "exports": { ".": { "types": "./index.d.ts", "default": "./index.js" } },
+  "files": ["index.js", "index.d.ts", "README.md", "LICENSE"],
+  "scripts": { "test": "node --test" },
+  "keywords": ["humanize", "bytes", "filesize", "duration", "ms", "pretty", "format", "parse", "zero-dependency"],
+  "repository": { "type": "git", "url": "git+https://github.com/HaYaTedonn/humanun.git" },
+  "author": "Hayate Suzuki",
+  "license": "MIT",
+  "engines": { "node": ">=18" },
+  "sideEffects": false
+}