@verifyhash/human-time 0.1.0 → 0.1.1

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 <OWNER-NAME PLACEHOLDER>
+Copyright (c) 2026 verifyhash
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -13,6 +13,16 @@ No install step, no `node_modules`, no network, no servers. One file:
 > `Intl.RelativeTimeFormat` or a full i18n library. This module optimizes for
 > being small, dependency-free, and predictable.
 
+## Install
+
+```bash
+npm install @verifyhash/human-time
+```
+
+Published as [`@verifyhash/human-time`](https://www.npmjs.com/package/@verifyhash/human-time);
+source lives in the [verifyhash/libs](https://github.com/verifyhash/libs) monorepo.
+Zero runtime dependencies — you can also vendor the folder directly.
+
 ## Who it's for
 
 Anyone rendering timestamps or durations in a CLI, log line, dashboard, or
@@ -27,7 +37,7 @@ approximate human phrasing and compact `ms`-style strings.
 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
+const { relative, format, parse } = require('@verifyhash/human-time'); // main = src/index.js
 ```
 
 ## API

package/index.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Type declarations for @verifyhash/human-time — zero-dependency
+ * human-readable relative time ("5 minutes ago", "in 3 days") plus compact
+ * ms-style duration format/parse ("2h30m" <-> milliseconds).
+ *
+ * Output is ENGLISH-ONLY by design (use Intl.RelativeTimeFormat for i18n).
+ * All functions are pure and throw on invalid input rather than silently
+ * returning 0.
+ */
+
+/** A moment in time: a JS Date or epoch milliseconds. */
+export type TimeInput = Date | number;
+
+/** The unit constants exposed as `units` (all in milliseconds). */
+export interface TimeUnits {
+  /** 1000 ms. */
+  SECOND: number;
+  /** 60 seconds. */
+  MINUTE: number;
+  /** 60 minutes. */
+  HOUR: number;
+  /** 24 hours. */
+  DAY: number;
+  /** 7 days. */
+  WEEK: number;
+  /** Mean Gregorian month (~30.44 days), rounded to whole ms. */
+  MONTH: number;
+  /** Mean Gregorian year (365.2425 days), rounded to whole ms. */
+  YEAR: number;
+}
+
+/**
+ * English relative phrase describing `from` as seen from the reference `to`
+ * (default: now). Past-tense when `from` is earlier ("5 minutes ago"),
+ * future-tense when later ("in 5 minutes"); sub-second gaps collapse to
+ * "just now". Months/years use mean calendar lengths — the phrasing is
+ * approximate by nature. Throws TypeError on an invalid Date or non-finite
+ * number.
+ */
+export function relative(from: TimeInput, to?: TimeInput): string;
+
+/**
+ * Compact duration string from milliseconds, e.g. 9000000 -> "2h30m",
+ * 45000 -> "45s". Emits every non-zero component from days down to ms so the
+ * result round-trips exactly through parse(); zero yields "0ms"; negative
+ * input is prefixed with "-"; fractional input is rounded to the nearest ms.
+ */
+export function format(ms: number): string;
+
+/**
+ * Milliseconds from a compact duration string — the inverse of format().
+ * Case-insensitive and tolerant of internal spacing ("2h30m", "2H 30M");
+ * understands d, h, m, s and ms; a leading "-" (or "+") sets the sign.
+ * Throws on empty/garbage input or unknown units.
+ */
+export function parse(str: string): number;
+
+/** The module's unit constants (all in milliseconds), exposed for callers. */
+export const units: TimeUnits;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@verifyhash/human-time",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "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",
@@ -15,6 +15,7 @@
     "zero-dependency"
   ],
   "main": "src/index.js",
+  "types": "index.d.ts",
   "scripts": {
     "test": "node test/index.test.js"
   },
@@ -22,7 +23,8 @@
   "files": [
     "src/index.js",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "index.d.ts"
   ],
   "publishConfig": {
     "access": "public"