@verifyhash/human-time 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 <OWNER-NAME PLACEHOLDER>
+
+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,128 @@
+# human-time
+
+A tiny, **zero-dependency** Node.js library for two everyday time chores:
+
+1. **Relative phrases** — turn a timestamp into `"5 minutes ago"` or `"in 3 days"`.
+2. **Compact durations** — turn milliseconds into `"2h30m"` and back again.
+
+No install step, no `node_modules`, no network, no servers. One file:
+[`src/index.js`](src/index.js). Node 12+.
+
+> **English only.** Output is fixed English. There is no locale/pluralization
+> layer here on purpose — if you need localized phrasing, reach for
+> `Intl.RelativeTimeFormat` or a full i18n library. This module optimizes for
+> being small, dependency-free, and predictable.
+
+## Who it's for
+
+Anyone rendering timestamps or durations in a CLI, log line, dashboard, or
+small web app who wants friendly output without pulling in `moment`, `dayjs`,
+`date-fns`, or `ms`. It is deliberately **distinct from the sibling
+`iso-duration` library**: `iso-duration` parses/formats ISO 8601 durations
+(`PT1H30M`) and does calendar-correct date arithmetic; `human-time` does
+approximate human phrasing and compact `ms`-style strings.
+
+## Install / use
+
+Copy the folder in, or `require` it directly — there is nothing to build.
+
+```js
+const { relative, format, parse } = require('human-time'); // main = src/index.js
+```
+
+## API
+
+### `relative(from, to?) -> string`
+
+Describes `from` as seen from the reference `to`. Both arguments accept a
+`Date` **or** epoch-milliseconds (a `number`). `to` defaults to `Date.now()`
+when omitted — so the common one-argument call just works:
+
+```js
+relative(Date.now() - 5 * 60 * 1000);   // "5 minutes ago"
+relative(Date.now() + 90 * 60 * 1000);  // "in 2 hours"
+relative(new Date('2000-01-01'), new Date('2000-01-01')); // "just now"
+```
+
+Direction is chosen so single-argument calls read naturally: when `from` is
+earlier than `to` you get past tense (`"N ... ago"`); when `from` is later you
+get future tense (`"in N ..."`). Anything under one second, in either
+direction, is `"just now"`.
+
+The threshold ladder (each band rounds to its nearest whole unit):
+
+| Gap                     | Output examples              |
+| ----------------------- | ---------------------------- |
+| `< 1s`                  | `just now`                   |
+| `1s` … `< 1m`           | `1 second ago` … `59 seconds ago` |
+| `1m` … `< 1h`           | `5 minutes ago`, `in 12 minutes` |
+| `1h` … `< 1d`           | `3 hours ago`                |
+| `1d` … `< 1w`           | `3 days ago`                 |
+| `1w` … `< 1 month`      | `2 weeks ago`                |
+| `1 month` … `< 1 year`  | `3 months ago`               |
+| `>= 1 year`             | `2 years ago`, `in 5 years`  |
+
+**Honest limits:** months and years use *average* Gregorian lengths
+(30.436875 and 365.2425 days), so `"3 months ago"` is approximate, never
+calendar-exact — if you need "exactly 3 calendar months", use date arithmetic
+(e.g. the `iso-duration` sibling), not this. Values sit in a single band and
+round, so a 25-hour gap reads `"1 day ago"`, not `"1 day 1 hour ago"`.
+
+### `format(ms) -> string`
+
+Compact, `ms`-package-style duration string. Emits every non-zero component
+from days down to milliseconds, largest first, so it round-trips through
+`parse`:
+
+```js
+format(9_000_000);          // "2h30m"
+format(24*3600*1000 + 4*3600*1000); // "1d4h"
+format(45_000);             // "45s"
+format(500);                // "500ms"
+format(1_500);              // "1s500ms"
+format(0);                  // "0ms"
+format(-5_000);             // "-5s"
+```
+
+Fractional input is rounded to the nearest millisecond. Non-finite input
+throws.
+
+### `parse(str) -> number` (milliseconds)
+
+The inverse of `format`. Case-insensitive and tolerant of spacing. Understands
+`d`, `h`, `m`, `s`, and `ms`, plus an optional leading `-`/`+`:
+
+```js
+parse('2h30m');    // 9000000
+parse('2H 30M');   // 9000000  (case + spacing don't matter)
+parse('1d4h');     // 100800000
+parse('500ms');    // 500
+parse('-1m30s');   // -90000
+parse('1.5h');     // 5400000  (fractional units allowed)
+```
+
+Empty, garbage, or unknown-unit input **throws** rather than silently
+returning `0`, so typos surface loudly.
+
+### `units`
+
+The unit sizes in milliseconds are exposed as
+`units.SECOND / MINUTE / HOUR / DAY / WEEK / MONTH / YEAR` for callers who want
+the same constants.
+
+## Running the tests
+
+One command, no dependencies:
+
+```
+node test/index.test.js
+```
+
+It exits `0` when all assertions pass (and prints a pass/fail count). The suite
+covers past **and** future phrasing, every threshold band, `format`⇄`parse`
+round-trips, sub-second inputs, negative/zero durations, and invalid-input
+error handling.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@verifyhash/human-time",
+  "version": "0.1.0",
+  "description": "Zero-dependency human-readable relative time ('5 minutes ago', 'in 3 days') plus compact ms-style duration format/parse ('2h30m' <-> ms) for Node.js. English-only.",
+  "keywords": [
+    "relative-time",
+    "time-ago",
+    "humanize",
+    "duration",
+    "compact",
+    "format",
+    "parse",
+    "ms",
+    "2h30m",
+    "zero-dependency"
+  ],
+  "main": "src/index.js",
+  "scripts": {
+    "test": "node test/index.test.js"
+  },
+  "license": "MIT",
+  "files": [
+    "src/index.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/verifyhash/libs.git",
+    "directory": "human-time"
+  },
+  "homepage": "https://github.com/verifyhash/libs/tree/main/human-time#readme",
+  "bugs": {
+    "url": "https://github.com/verifyhash/libs/issues"
+  }
+}

package/src/index.js

@@ -0,0 +1,193 @@
+'use strict';
+
+/**
+ * human-time — zero-dependency human-readable relative time and compact
+ * ms-style duration formatting/parsing for Node.js.
+ *
+ * OUTPUT IS ENGLISH-ONLY. There is no locale/i18n layer here by design; if you
+ * need localized phrasing use Intl.RelativeTimeFormat or a full i18n library.
+ *
+ * This is intentionally DISTINCT from tools/iso-duration, which deals with
+ * ISO 8601 durations (PT1H30M) and calendar arithmetic. This module deals with
+ * (1) friendly "5 minutes ago" / "in 3 days" phrases and (2) compact "2h30m"
+ * style strings that survive a format<->parse round trip.
+ */
+
+// Unit sizes in milliseconds. Months and years use average calendar lengths
+// (Gregorian mean month/year) because relative phrasing is approximate by
+// nature — "3 months ago" never needs to be calendar-exact.
+var SEC = 1000;
+var MIN = 60 * SEC;
+var HOUR = 60 * MIN;
+var DAY = 24 * HOUR;
+var WEEK = 7 * DAY;
+var MONTH = Math.round(30.436875 * DAY); // mean Gregorian month
+var YEAR = Math.round(365.2425 * DAY); // mean Gregorian year
+
+// Convert a Date or epoch-milliseconds value into a numeric timestamp.
+function toMillis(value, label) {
+  if (value instanceof Date) {
+    var t = value.getTime();
+    if (isNaN(t)) throw new TypeError(label + ': invalid Date');
+    return t;
+  }
+  if (typeof value === 'number') {
+    if (!isFinite(value)) throw new TypeError(label + ': non-finite number');
+    return value;
+  }
+  throw new TypeError(label + ': expected a Date or epoch-milliseconds number');
+}
+
+/**
+ * relative(from, to) -> English relative phrase.
+ *
+ * `from` and `to` may each be a Date or epoch-milliseconds. `to` defaults to
+ * the current time (Date.now()) when omitted.
+ *
+ * The phrase describes `from` as seen from the reference `to`. When `from` is
+ * earlier than `to` it is past-tense ("N ... ago"); when `from` is later than
+ * `to` it is future-tense ("in N ..."). This makes the common single-argument
+ * call read naturally: relative(fiveMinutesAgo) === "5 minutes ago", and
+ * relative(fiveMinutesFromNow) === "in 5 minutes". Sub-second gaps in either
+ * direction collapse to "just now".
+ */
+function relative(from, to) {
+  var f = toMillis(from, 'from');
+  var t = to === undefined ? Date.now() : toMillis(to, 'to');
+
+  var delta = f - t; // > 0 => `from` is later than the reference => future
+  var abs = Math.abs(delta);
+  var future = delta > 0;
+
+  if (abs < SEC) return 'just now';
+
+  var n, unit;
+  if (abs < MIN) {
+    n = Math.round(abs / SEC);
+    unit = 'second';
+  } else if (abs < HOUR) {
+    n = Math.round(abs / MIN);
+    unit = 'minute';
+  } else if (abs < DAY) {
+    n = Math.round(abs / HOUR);
+    unit = 'hour';
+  } else if (abs < WEEK) {
+    n = Math.round(abs / DAY);
+    unit = 'day';
+  } else if (abs < MONTH) {
+    n = Math.round(abs / WEEK);
+    unit = 'week';
+  } else if (abs < YEAR) {
+    n = Math.round(abs / MONTH);
+    unit = 'month';
+  } else {
+    n = Math.round(abs / YEAR);
+    unit = 'year';
+  }
+
+  var phrase = n + ' ' + unit + (n === 1 ? '' : 's');
+  return future ? 'in ' + phrase : phrase + ' ago';
+}
+
+// Ordered largest-to-smallest so format emits e.g. "1d4h" not "4h1d".
+var FORMAT_UNITS = [
+  ['d', DAY],
+  ['h', HOUR],
+  ['m', MIN],
+  ['s', SEC],
+  ['ms', 1]
+];
+
+/**
+ * format(ms) -> compact string, e.g. 9000000 -> "2h30m", 45000 -> "45s".
+ *
+ * Emits every non-zero component from days down to milliseconds, so the result
+ * round-trips exactly through parse(). Zero yields "0ms". Negative durations
+ * are prefixed with "-". Fractional input is rounded to the nearest ms.
+ */
+function format(ms) {
+  var value = Number(ms);
+  if (!isFinite(value)) {
+    throw new TypeError('format: expected a finite number of milliseconds');
+  }
+  value = Math.round(value);
+  if (value === 0) return '0ms';
+
+  var sign = value < 0 ? '-' : '';
+  var rem = Math.abs(value);
+  var out = '';
+
+  for (var i = 0; i < FORMAT_UNITS.length; i++) {
+    var label = FORMAT_UNITS[i][0];
+    var size = FORMAT_UNITS[i][1];
+    if (rem >= size) {
+      var count = Math.floor(rem / size);
+      rem -= count * size;
+      out += count + label;
+    }
+  }
+  return sign + out;
+}
+
+// Longest-first alternation so "ms" is matched before a bare "m".
+var TOKEN_RE = /(\d+(?:\.\d+)?)\s*(ms|s|m|h|d)/g;
+var UNIT_TO_MS = { ms: 1, s: SEC, m: MIN, h: HOUR, d: DAY };
+
+/**
+ * parse(str) -> milliseconds, the inverse of format().
+ *
+ * Case-insensitive and tolerant of internal spacing: "2h30m", "2H 30M" and
+ * " 2h 30m " all yield 9000000. Understands d, h, m, s and ms. A leading "-"
+ * (or "+") sets the sign. Throws on empty/garbage input or unknown units so
+ * mistakes surface loudly instead of silently returning 0.
+ */
+function parse(str) {
+  if (typeof str !== 'string') {
+    throw new TypeError('parse: expected a string');
+  }
+  var s = str.trim().toLowerCase();
+  if (s === '') throw new Error('parse: empty string');
+
+  var sign = 1;
+  if (s.charAt(0) === '-') {
+    sign = -1;
+    s = s.slice(1).trim();
+  } else if (s.charAt(0) === '+') {
+    s = s.slice(1).trim();
+  }
+
+  // Verify the whole body is nothing but recognized tokens (+ whitespace).
+  var leftover = s.replace(TOKEN_RE, '').replace(/\s+/g, '');
+  if (leftover !== '') {
+    throw new Error('parse: unexpected content in "' + str + '"');
+  }
+
+  TOKEN_RE.lastIndex = 0;
+  var total = 0;
+  var matched = false;
+  var m;
+  while ((m = TOKEN_RE.exec(s)) !== null) {
+    matched = true;
+    total += parseFloat(m[1]) * UNIT_TO_MS[m[2]];
+  }
+  if (!matched) {
+    throw new Error('parse: no recognizable duration in "' + str + '"');
+  }
+  return sign * total;
+}
+
+module.exports = {
+  relative: relative,
+  format: format,
+  parse: parse,
+  // Exposed for callers who want the same unit constants (all in ms).
+  units: {
+    SECOND: SEC,
+    MINUTE: MIN,
+    HOUR: HOUR,
+    DAY: DAY,
+    WEEK: WEEK,
+    MONTH: MONTH,
+    YEAR: YEAR
+  }
+};