timestring

Timestring is a tiny, zero-dependency JavaScript library that converts human-readable time expressions such as ‘1h 15m’ or ‘1d 3h 25m 18s’ into a single numeric value. By default it returns seconds, but the return unit can be configured to minutes, hours, days, weeks, months, or years.

It recognizes a flexible range of keyword aliases for each unit and lets you customize how many hours are in a day or days are in a month, making it handy for parsing user input, config values, and duration expressions in Node.js and the browser.

What You Get

• A single function that turns strings like ‘1d 3h 25m 18s’ into numeric durations
• Configurable return units: seconds, minutes, hours, days, weeks, months, or years
• Flexible keyword aliases for each time unit (s, sec, second, seconds, etc.)
• Options to override hours-per-day and days-per-month for domain-specific math
• A zero-dependency implementation usable in Node.js and the browser

Common Use Cases

• Parsing user-entered durations in forms or CLIs
• Reading human-friendly timeout or interval values from config files
• Converting duration expressions into seconds for timers or scheduling
• Normalizing time inputs across an application

Under The Hood

Architecture - Timestring is a single-module library: index.js exports one parsing function that tokenizes the input string with a regular expression, maps each matched keyword to a canonical unit via an alias table, multiplies each value by its second-equivalent, sums the groups, and then divides by the requested return unit. Configuration (unit keywords, hours-per-day, days-per-month) is merged from an options object over sensible defaults. Tech Stack - Plain JavaScript with no runtime dependencies, distributed as a CommonJS module (main: index.js) targeting both Node.js and browsers. Development uses standard npm tooling with lint, test, and coverage scripts. Code Quality - The project ships a dedicated test.js suite with Coveralls coverage reporting and CI via GitHub Actions, and the small surface area keeps the implementation easy to reason about; the code is straightforward and readable, though it is minimally maintained with low recent activity. API Design - The public API is intentionally trivial: import the function and call it with a string and optional options object. There is essentially no boilerplate, the option names are self-descriptive, and the README documents every unit alias and configuration knob, giving a very gentle learning curve.