Skip to content

parseDate

Attempts to parse a value into a valid Date instance. This parser accepts existing Date objects, ISO date strings, and numeric timestamps. It rejects invalid timestamps and all non-date-like values.

It never throws and never mutates input. Use it when you need a normalized, guaranteed-valid Date before further validation or domain logic.

Signature

function parseDate(value: unknown): ParseResult<Date>

Parameters

Returns

  • ok: true, value: Date, issues: []: When the value is a valid Date or can be parsed into one.
  • ok: false, value: null, issues: string[]: When the value cannot be parsed into a valid Date.

Behavior

  • Uses isDate internally to detect valid Date instances.

  • Accepts:

  • Valid Date objects (returned unchanged).
  • ISO date strings.
  • Numeric timestamps.
  • Rejects:
  • Invalid Date objects (new Date("invalid")).
  • Invalid strings.
  • NaN, Infinity, -Infinity.
  • Objects, arrays, booleans, null, undefined.
  • Never throws and never mutates input.
  • Always returns a structured ParseResult with value and issues.

Examples

parseDate(new Date("2020-01-01"))
// { ok: true, value: Date(...), issues: [] }

parseDate("2020-05-15T12:30:00Z")
// { ok: true, value: Date(...), issues: [] }

parseDate(1609459200000)
// { ok: true, value: Date(...), issues: [] }

parseDate("not-a-date")
// { ok: false, value: null, issues: ["Value must be a valid Date or a parseable date string/number"] }

parseDate({})
// { ok: false, value: null, issues: ["Value must be a valid Date or a parseable date string/number"] }

Notes

  • This parser does not coerce non-string, non-number values.
  • Strings are passed directly to the Date constructor; invalid timestamps are rejected.
  • Suitable for normalization before validation or domain logic that requires a guaranteed-valid Date instance.
  • The parser is pure, deterministic, and side-effect-free.