> ## Documentation Index
> Fetch the complete documentation index at: https://docs.syntblaze.com/llms.txt
> Use this file to discover all available pages before exploring further.
# TypeScript Date
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.
```typescript theme={"dark"}
// 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.
```typescript theme={"dark"}
// 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.
```typescript theme={"dark"}
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.
```typescript theme={"dark"}
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.
```typescript theme={"dark"}
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());
}
}
```
Tired of Poor TypeScript Skills? Fix That With Deep Grasping!
Learn More
