TypeScript Date - SyntBlaze

The Date object in TypeScript is a built-in standard library interface representing a single moment in time, measured in milliseconds since the Unix Epoch (January 1, 1970, 00:00:00 UTC). TypeScript inherits the runtime behavior directly from JavaScript’s Date object while overlaying it with static type definitions via the Date interface and the DateConstructor type.

Type Declaration and Instantiation

Variables and properties are typed using the Date interface. The DateConstructor provides four primary overload signatures for instantiation.

// 1. No arguments: captures the current date and time
const now: Date = new Date();

// 2. Unix timestamp (number): milliseconds since the Epoch
const fromEpoch: Date = new Date(1672531200000);

// 3. Date string (string): parsed internally via Date.parse()
const fromString: Date = new Date("2023-01-01T00:00:00Z");

// 4. Component values (numbers): year, month (0-indexed), date, hours, minutes, seconds, ms
const fromComponents: Date = new Date(2023, 0, 1, 0, 0, 0, 0);

Note: The month argument in the component constructor is 0-indexed (0 represents January, 11 represents December).

Static Methods

The Date constructor object exposes static methods that return numeric values (timestamps) rather than Date instances.

// Returns the current timestamp in milliseconds
const currentMs: number = Date.now();

// Parses a valid ISO 8601 date string into a timestamp
const parsedMs: number = Date.parse("2023-01-01T12:00:00Z");

// Returns a timestamp from UTC component values
const utcMs: number = Date.UTC(2023, 0, 1);

Instance Methods

The Date interface defines methods for interacting with the underlying timestamp. These are strictly typed to return number or string.

Component Getters and Setters

Methods are available for both local time and UTC. Getters extract specific time components, while setters mutate the underlying instance.

const dt: Date = new Date();

// Getters return numbers
const year: number = dt.getFullYear();       // e.g., 2023
const month: number = dt.getMonth();         // 0-11
const day: number = dt.getDay();             // 0-6 (0 = Sunday)
const utcHours: number = dt.getUTCHours();   // 0-23

// Setters mutate the instance and return the new timestamp (number)
const newTimestamp: number = dt.setFullYear(2024);

Serialization and Conversion

These methods convert the Date instance into formatted strings or primitive numeric values.

const dt: Date = new Date();

// ISO 8601 string format (YYYY-MM-DDTHH:mm:ss.sssZ)
const iso: string = dt.toISOString();

// Primitive value (timestamp in milliseconds)
const ms: number = dt.getTime();
const valueOf: number = dt.valueOf();

// Locale-specific formatting
const localeDate: string = dt.toLocaleDateString();
const localeTime: string = dt.toLocaleTimeString();

Type Guards and Validation

Because Date is an object (typeof new Date() === "object"), runtime validation requires specific checks beyond standard TypeScript type narrowing. Furthermore, an improperly instantiated Date object will not throw an error; instead, it creates an “Invalid Date” object.

const input: unknown = new Date("invalid-string");

// 1. Type narrowing via instanceof
if (input instanceof Date) {
    // TypeScript now recognizes 'input' as a Date object
    
    // 2. Validating the internal timestamp
    // An invalid date returns NaN for getTime()
    const isValid: boolean = !isNaN(input.getTime());
    
    if (isValid) {
        console.log(input.toISOString());
    }
}