Skip to content

Add getDuration for parsing time strings to milliseconds#61

Merged
recursivefunk merged 1 commit into
mainfrom
jra/get-duration
Apr 22, 2026
Merged

Add getDuration for parsing time strings to milliseconds#61
recursivefunk merged 1 commit into
mainfrom
jra/get-duration

Conversation

@recursivefunk

Copy link
Copy Markdown
Owner

Summary

Adds getDuration(key, defaultVal) (and the duration() alias) for parsing human-friendly time strings like "500ms", "30s", "5m", "2h", "1d", "1w" into milliseconds. This covers a very common env-var pattern (timeouts, TTLs, intervals) that today requires hand-rolled parsing on top of getNumber. Additive and non-breaking — bumps minor to 7.7.0.

Changed Files

  • src/index.js — new DURATION_UNITS, DURATION_RE, and parseDuration helpers plus getDuration/duration methods. Default-fallback behavior mirrors getIP (invalid env value → fall back to parsing the default).
  • src/index.d.ts — type declarations for getDuration and duration with a number | null return.
  • test/test.env — fixtures covering every unit, decimals, uppercase unit, and whitespace between number and unit.
  • test/test.js — seven new test blocks (18 assertions) covering every unit, decimals/case/whitespace, invalid values, default fallback, missing-key cases (string default, numeric default, no default), unparseable defaults (string, NaN, {}), and the alias.
  • README.md — new example in the Type Conversion section.
  • package.json — 7.6.3 → 7.7.0.

Steps to Verify

  • npm run ci — all 116 tests pass and 100% line coverage still holds.
  • env.getDuration('CACHE_TTL') with CACHE_TTL=5m returns 300000.
  • env.getDuration('UNSET', '30s') returns 30000.
  • env.getDuration('UNSET', 1000) returns 1000 (numeric default treated as ms).
  • env.getDuration('UNSET') returns null.
  • env.getDuration('INVALID') where INVALID=nope returns null; same call with a valid string default returns the parsed default.
  • env.duration('CACHE_TTL') matches env.getDuration('CACHE_TTL').

Introduces getDuration(key, defaultVal) and the duration() alias, which
parse values like "500ms", "30s", "5m", "2h", "1d", "1w" into
milliseconds. Units are case-insensitive, decimals are supported, and
whitespace between the number and unit is allowed. When the env value
is missing or unparseable the default is parsed (numeric defaults are
treated as ms). Returns null when neither resolves.

Also:
- TypeScript declarations for getDuration and duration.
- Test fixtures and tape tests covering every unit, decimals, case
  insensitivity, whitespace, invalid values, default fallback, and the
  alias.
- README: new example in the Type Conversion section.
- Bumps minor to 7.7.0 (additive API).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@recursivefunk recursivefunk self-assigned this Apr 22, 2026
@recursivefunk recursivefunk merged commit fa7873c into main Apr 22, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant