# JavaScript Date & Epoch: Complete Guide

Dates and times are tricky in frontend and backend apps. Understanding **epoch, Date objects, instance methods, and static methods** is essential for correct time computation, formatting, and transport.

---

## **1️⃣ Epoch Time**

**Epoch time** is the number of seconds or milliseconds since the **Unix Epoch**:

```plaintext
1970-01-01T00:00:00 UTC
```

* **Milliseconds** → JavaScript `Date` uses this internally
    
* **Seconds** → Common in Unix, logs, APIs
    

### Example:

```js
const now = new Date();
console.log(now.getTime());        // 1766750599479 (milliseconds)
console.log(Math.floor(now.getTime() / 1000)); // 1766750599 (seconds)
```

**Rule of thumb**:

| Unit | Usage |
| --- | --- |
| Milliseconds | JavaScript Date arithmetic |
| Seconds | Unix timestamps, logs, APIs |
| ISO String | Transport between backend and frontend |

---

## **2️⃣** [`Date.now`](http://Date.now)`()`

**Static method** that gives **current timestamp** in milliseconds.

```js
console.log(Date.now()); // 1766750599479
```

* Does **not require creating a Date object**
    
* Useful for benchmarking, timers, logging
    
* Equivalent to `(new Date()).getTime()`, but faster
    

### Example: Measuring execution time

```js
const start = Date.now();
// some work
const end = Date.now();
console.log("Duration:", end - start, "ms");
```

---

## **3️⃣** `date.getTime()`

**Instance method** for any `Date` object. Returns **milliseconds since epoch**.

```js
const date = new Date("2025-12-26T12:03:19Z");
console.log(date.getTime()); // 1766750599479
```

* Use this when you have a **specific date** to compute differences, sort events, or store numeric timestamp.
    
* Works well for **arithmetic between dates**:
    

```js
const start = new Date("2025-12-26T10:00:00Z");
const end = new Date("2025-12-26T12:00:00Z");

const diffMs = end.getTime() - start.getTime(); // 7200000 ms
const diffSeconds = diffMs / 1000;             // 7200 seconds
```

**Key difference from** [`Date.now`](http://Date.now)`()`:

* `getTime()` → timestamp of that specific `Date` object
    
* [`Date.now`](http://Date.now)`()` → timestamp of the current instant
    

---

## **4️⃣ Other Important** `Date` Instance Methods

| Method | Description | Example |
| --- | --- | --- |
| `getFullYear()` | Returns 4-digit year | `date.getFullYear()` → 2025 |
| `getMonth()` | Returns month (0–11) | `date.getMonth()` → 11 for December |
| `getDate()` | Returns day of month | `date.getDate()` → 26 |
| `getDay()` | Returns day of week (0–6, Sunday = 0) | `date.getDay()` → 5 (Friday) |
| `getHours()` | Returns hour (0–23) | `date.getHours()` → 12 |
| `getMinutes()` | Returns minutes (0–59) | `date.getMinutes()` → 3 |
| `getSeconds()` | Returns seconds (0–59) | `date.getSeconds()` → 19 |
| `getMilliseconds()` | Returns ms (0–999) | `date.getMilliseconds()` → 479 |
| `toISOString()` | Returns ISO 8601 string | `date.toISOString()` → `"2025-12-26T12:03:19.479Z"` |
| `toDateString()` | Human-readable date | `"Fri Dec 26 2025"` |
| `toTimeString()` | Human-readable time | `"12:03:19 GMT+0000 (UTC)"` |
| `toLocaleString(locale, options)` | Locale-based formatting | `"26 Dec 2025, 12:03"` |

> **Tip:** `getUTC*()` versions exist (e.g., `getUTCHours()`) to get UTC values instead of local.

---

## **5️⃣ Other Important** `Date` Static Methods

| Method | Description | Example |
| --- | --- | --- |
| [`Date.now`](http://Date.now)`()` | Returns current timestamp (ms) | [`Date.now`](http://Date.now)`()` → 1766750599479 |
| `Date.parse()` | Parses date string to timestamp | `Date.parse("2025-12-26T12:03:19Z")` → 1766750599479 |
| `Date.UTC()` | Creates timestamp in UTC from components | `Date.UTC(2025, 11, 26, 12, 3, 19)` → 1766750599000 |
| `Date.prototype` | Access prototype for custom extensions | N/A |

---

## **6️⃣ When to use which**

| Task | Method |
| --- | --- |
| Current timestamp for logging or intervals | [`Date.now`](http://Date.now)`()` |
| Timestamp of a specific date | `date.getTime()` |
| Create timestamp in UTC from components | `Date.UTC()` |
| Parse ISO string from backend | `new Date(isoString)` or `Date.parse()` |
| Localized formatting for UI | `toLocaleString()` or `Intl.DateTimeFormat` |

---

## **7️⃣ Example: Full Flow**

```js
// Backend sends ISO string
const isoString = "2025-12-26T12:03:19.479Z";

// Frontend parses ISO string → Date object
const date = new Date(isoString);

// Current timestamp
const nowMs = Date.now();
console.log(nowMs);

// Timestamp of specific date
console.log(date.getTime());

// Compute difference in seconds
const diffSeconds = (nowMs - date.getTime()) / 1000;
console.log(diffSeconds);

// Format for user
console.log(new Intl.DateTimeFormat("en-GB", {
  dateStyle: "medium",
  timeStyle: "short",
  timeZone: "Europe/London"
}).format(date));
```

---

## **8️⃣ Key Takeaways**

1. **Epoch milliseconds** → JavaScript standard; `Date` stores this internally.
    
2. **Epoch seconds** → common in Unix systems or APIs.
    
3. [`Date.now`](http://Date.now)`()` → current timestamp in milliseconds (static).
    
4. `date.getTime()` → timestamp for that specific Date object (instance).
    
5. **Other instance methods** → extract year, month, day, hour, minute, etc.
    
6. **Other static methods** → `Date.UTC()`, `Date.parse()`.
    
7. **Use ISO strings for transport**, epoch for computation, `Intl` for display.