ensureDate

Safely converts a date-like value to a valid Date object, or returns null.

Accepts Date, timestamps (seconds or milliseconds, auto-detected), date strings, and objects with an epochMilliseconds property (e.g. Temporal.Instant, Temporal.ZonedDateTime). Returns null for null, undefined, empty strings, 0, and any value that produces an invalid Date.

This is the date equivalent of ensureArray — it normalizes flexible input into a guaranteed type (or a safe fallback).

Available since v2.0.0

Import

import { ensureDate } from '@helpers4/date';

Signature

ensureDate(input: DateLike | null | undefined): Date | null

Parameters

Parameter	Type	Description
input	DateLike | null | undefined	A date-like value to convert

Returns

Date | null — A valid Date object, or null if the input is invalid

Examples

ensureDate

ensureDate('2025-01-19T12:00:00Z') // => Date
ensureDate(1737290400)             // => Date (from Unix seconds)
ensureDate(1737290400000)          // => Date (from milliseconds)
ensureDate(new Date())             // => Date (same reference)
ensureDate(null)                   // => null
ensureDate('invalid')              // => null

Related Types

DateLike

A value that can be converted to a Date.

• Date — used as-is (validated for Invalid Date)
• number — treated as a timestamp (seconds or milliseconds, auto-detected); 0 is treated as invalid and produces null in ensureDate
• string — parsed via new Date(string)
• EpochMilliseconds — any object with a epochMilliseconds property (e.g. Temporal.Instant, Temporal.ZonedDateTime)

// TODO: When the Temporal API reaches Stage 4 and is available without // flags in all major runtimes, consider narrowing the union to the // concrete Temporal types for stricter type-checking.

type DateLike = Date | number | string | EpochMilliseconds

EpochMilliseconds

An object that exposes an epoch timestamp in milliseconds.

This structural type is satisfied by Temporal.Instant and Temporal.ZonedDateTime (and any future object that carries the same property), so callers can pass Temporal values without importing them.

interface EpochMilliseconds {
  epochMilliseconds: number;
}

Source

View source on GitHub