How to Type Dates in TypeScript

By the end of this page, you will understand that the correct way to type a JavaScript date in TypeScript is with the Date type. You will also learn when a value should be a Date object versus a date string or numeric timestamp, how to create and use Date values safely, and which common mistakes to avoid.

TypeScript uses the same runtime values as JavaScript, but adds static types on top. In JavaScript, dates are represented by the built-in Date class. Because of that, the correct TypeScript type for a date object is also Date.

let myDate: Date = new Date();

You do not need any, and object is too vague. Using Date gives TypeScript useful information:

• the value is a real date object
• methods like getFullYear() and toISOString() are available
• incorrect assignments can be caught early

For example:

let myDate: Date = new Date();
myDate.getFullYear(); // OK

myDate = "2025-01-01"; // Error

This matters because many programs work with time-based data:

• user account creation dates
• order timestamps
• event scheduling
• logs and analytics
• API responses containing dates

One important detail: a Date object is different from a date string.

let a: Date = new Date();
let b: string = "2025-01-01";

These are not the same type, even if they both represent a date conceptually. A Date is an object with date methods. A string is just text. TypeScript helps you keep that distinction clear.

Think of Date as a specialized tool, like a stopwatch.

• A string is like writing a time on paper: "2025-01-01"
• A number timestamp is like the raw machine reading behind the stopwatch
• A Date object is the actual stopwatch you can operate on

If you want to call methods such as:

• getTime()
• getMonth()
• toISOString()

then you need the stopwatch itself: a Date.

So the question is not just “does this value describe a date?” but “what kind of date value is this?”

• text date -> string
• Unix timestamp -> number
• JavaScript date object -> Date

The basic syntax is:

let myDate: Date = new Date();

You can also use Date in function parameters, return types, object properties, and interfaces.

Variable example

let createdAt: Date = new Date();

Function parameter example

function formatDate(date: Date): string {
  return date.toISOString();
}

Function return type example

function getCurrentDate(): Date {
  return new Date();
}

Object property example

type User = {
  name: string;
  joinedAt: Date;
};

const user: User = {
  name: "Ava",
  joinedAt: new Date(),
};

Optional date example

Sometimes a date may be missing.

let deletedAt: Date | null = null;

deletedAt = new Date();

Date string vs Date object

const rawDate: string = "2025-01-01";
const parsedDate: Date = new Date(rawDate);

Here:

• rawDate is text from an API, form, or file
• parsedDate is a real Date object

That conversion step is common in real applications.

Consider this example:

const raw = "2025-06-10";
const date: Date = new Date(raw);
const year = date.getFullYear();

console.log(year);

Step by step:

1. raw is created as a string.

   • Its type is string
   • It is not a Date yet

2. new Date(raw) creates a JavaScript Date object.

   • TypeScript understands that the result is of type Date

3. date is declared as Date.

   • This matches the value returned by new Date(raw)

4. date.getFullYear() is called.

   • This works because date is known to be a Date
   • TypeScript allows the method call safely

5. console.log(year) prints the year.

   • year is a number

So the flow is:

• start with a string
• convert it to a Date
• use Date methods
• get other values such as numbers or strings from it

Dates appear in almost every non-trivial application.

APIs

An API may return timestamps for records:

type ApiPost = {
  id: number;
  publishedAt: string;
};

After parsing, your app may convert that string into a Date for easier manipulation.

User activity tracking

type Session = {
  startedAt: Date;
  endedAt: Date | null;
};

This is useful for login sessions, timers, and analytics.

Scheduling

Calendar apps, booking systems, and reminders all work with Date objects to compare times and calculate durations.

Logging and monitoring

type LogEntry = {
  message: string;
  timestamp: Date;
};

Developers often store or generate dates for audit trails and debugging.

Expiration logic

Dates are used to decide whether something is still valid:

• password reset links
• discount coupons
• authentication tokens
• cached data

In real codebases, developers usually type date values based on where the data currently is in its lifecycle.

1. Use Date for in-memory date objects

type Order = {
  id: string;
  createdAt: Date;
};

If your code will call date methods, Date is the right type.

2. Use string for raw API payloads

Many APIs send ISO date strings:

type OrderDto = {
  id: string;
  createdAt: string;
};

Then map that data into your internal model:

function toOrder(dto: OrderDto): Order {
  return {
    id: dto.id,
    createdAt: new Date(dto.createdAt),
  };
}

This separation is very common.

3. Validate before using

A Date object can still be invalid if parsing fails.

const date = new Date("not a real date");

if (Number.isNaN(date.getTime())) {
  throw new Error("Invalid date");
}

4. Use nullable or optional dates when needed

type User = {
  bannedAt?: Date;
  deletedAt: Date | null;
};

This models real application states clearly.

5. Use helper functions for conversion

Large projects often centralize parsing and formatting:

function parseApiDate(value: string): Date {
  const date = new Date(value);

  if (Number.isNaN(date.getTime())) {
    throw new Error("Invalid API date");
  }

  return date;
}

This avoids scattered date parsing logic across the codebase.

Using any

let myDate: any = new Date();
myDate.notARealMethod(); // No type error, but will fail at runtime

Why it is a problem:

• TypeScript cannot protect you
• invalid method calls are allowed

Use this instead:

let myDate: Date = new Date();

Using object

let myDate: object = new Date();

Why it is a problem:

• object is too broad
• you cannot safely call date-specific methods

For example:

let myDate: object = new Date();
// myDate.getFullYear(); // Error

Confusing Date with string

let createdAt: Date = "2025-01-01"; // Error

A string that looks like a date is still a string.

Correct approach:

let createdAt: Date = new Date("2025-01-01");

Forgetting that parsed dates can be invalid

const d: Date = new Date("bad input");
console.log(d.getFullYear());

This compiles, but the date may be invalid.

Safer version:

const d: Date = new Date("bad input");

if (Number.isNaN(d.getTime())) {
  console.log("Invalid date");
} else {
  console.log(d.getFullYear());
}

Typing API date fields as Date too early

If the API returns strings, this is misleading:

type ApiUser = {
  createdAt: Date;
};

Better:

type ApiUser = {
  createdAt: string;
};

Then convert it after reading the data.

Date vs string

• Date has methods like getTime() and toISOString()
• string is just text and must be parsed first

Date vs number

• Date is easier to work with when formatting and extracting parts
• number is useful for timestamps and performance-sensitive comparisons

Date vs any

• Date gives type safety
• any disables type checking

In most normal TypeScript code, if the value is a JavaScript date object, the right type is simply Date.

// Correct way to type a date object
let myDate: Date = new Date();

Common patterns

function save(date: Date): void {}
function now(): Date {
  return new Date();
}

type Event = {
  startsAt: Date;
  endsAt: Date | null;
};

Raw API data vs parsed app data

type EventDto = {
  startsAt: string;
};

type EventModel = {
  startsAt: Date;
};

Convert string to Date

const d: Date = new Date("2025-01-01");

Check for invalid date

const d = new Date(input);
const isInvalid = Number.isNaN(d.getTime());

Rules

• Use Date for JavaScript date objects
• Use string for raw date text
• Use number for timestamps
• Avoid any unless necessary
• Avoid object for date-specific values

Useful methods

date.getFullYear();
date.getMonth();
date.getDate();
date.getTime();
date.toISOString();

Is Date a valid type in TypeScript?

Yes. Date is the correct type for JavaScript date objects in TypeScript.

Should I use any for dates in TypeScript?

No. Use Date if the value is a real date object. any removes type safety.

What is the difference between Date and string in TypeScript?

Date is an object with date methods. string is plain text, even if it contains something like "2025-01-01".

How do I type a date from an API response?

Usually as string first, because many APIs send dates as text. Then convert it to Date in your application code.

Can a Date object be invalid even if the type is Date?

Yes. new Date(badValue) still creates a Date object, but it may represent an invalid date. Check with Number.isNaN(date.getTime()).

How do I type an optional date?

Use Date | null or an optional property such as deletedAt?: Date depending on your data model.

Should I use object for a date value?

No. object is too general and does not let TypeScript understand date-specific methods.

• Date object: The core built-in JavaScript object for date and time values.
• string types: Important because many dates arrive as strings from APIs or forms.
• number types: Useful for timestamps such as milliseconds since the Unix epoch.
• union types: Helpful for values like Date | null or Date | undefined.
• type aliases: Useful for defining models that contain date fields.
• interfaces: Common for typing API responses and domain objects with dates.
• type narrowing: Helpful when a value could be a Date, string, or null.
• function parameter and return types: Important for passing and returning dates safely.