Skip to content

Add getDate for parsing date strings to Date objects#62

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

Add getDate for parsing date strings to Date objects#62
recursivefunk merged 1 commit into
mainfrom
jra/get-date

Conversation

@recursivefunk

Copy link
Copy Markdown
Owner

Summary

Adds getDate(key, defaultVal) (and the date() alias) for parsing ISO 8601 date strings into native Date objects. This covers the common env-var pattern of release/deploy times, expiration dates, and schedule anchors. Additive and non-breaking — bumps minor to 7.8.0.

Changed Files

  • src/index.js — new parseDate helper plus getDate/date methods. Uses Date constructor semantics, validates via Number.isFinite(d.getTime()). Default-fallback behavior mirrors getIP and getDuration.
  • src/index.d.ts — type declarations for getDate and date with a Date | null return.
  • test/test.env — fixtures for a valid ISO datetime, a valid date-only string, and an invalid value.
  • test/test.js — seven new test blocks (14 assertions) covering ISO datetime parsing, date-only parsing, invalid env values, default fallback, missing-key cases (string default, Date instance default, no default), unparseable defaults (garbage string, invalid Date, number, object), and the alias.
  • README.md — new example in the Type Conversion section.
  • package.json — 7.7.0 → 7.8.0.

Design Notes

  • ISO 8601 is recommended. The parser calls new Date(input), so anything the Date constructor accepts will work. Strings without a timezone are interpreted as local time per ECMA-262 — consumers should prefer ISO strings with Z or +HH:MM for portability.
  • Numbers are intentionally rejected. Storing a Unix timestamp as an env var and reading it through getDate is ambiguous (seconds vs. milliseconds) and mixes well-typed and stringly-typed behavior. Consumers who need that can env.getNumber('TS') and pass to new Date() themselves, or supply a Date instance as the default.

Steps to Verify

  • npm run ci — all 130 tests pass and 100% line coverage still holds.
  • env.getDate('RELEASE_AT') with RELEASE_AT=2024-01-15T10:30:00Z returns a valid Date at that instant.
  • env.getDate('UNSET', '2024-01-01') returns a Date at 2024-01-01 UTC.
  • env.getDate('UNSET', new Date()) returns that Date instance unchanged.
  • env.getDate('UNSET') returns null.
  • env.getDate('INVALID') where INVALID=nope returns null; same call with a valid default returns the parsed default.
  • env.date('RELEASE_AT') matches env.getDate('RELEASE_AT').

Introduces getDate(key, defaultVal) and the date() alias, which parse
values via JavaScript's Date constructor — ISO 8601 strings are the
recommended input. Defaults may be ISO strings or Date instances
(Date instances are returned as-is). Numbers and other types are
rejected; use a Date instance if you want to pass a timestamp. Returns
null when neither the env value nor the default resolves to a valid
date.

Also:
- TypeScript declarations for getDate and date.
- Test fixtures and tape tests covering ISO datetime, ISO date-only,
  invalid values, default fallback, string/Date defaults, unparseable
  defaults (garbage string, invalid Date, number, object), and the
  alias.
- README: new example in the Type Conversion section.
- Bumps minor to 7.8.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 c36fbc4 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