Here's a JavaScript snippet that, on rare occasions in production, will fail:

const start = Date.now(); doSomeWork(); const end = Date.now(); const elapsed = end - start; console.log(`Took ${elapsed}ms`); // → Sometimes: "Took -1832ms" 

How can end be smaller than start? The work happened in real time, and the calls were sequential. What's going on?

Date.now() reads the wall clock

Date.now() returns the system wall clock, the same clock shown in your operating system's status bar. That clock can be changed underneath your program:

  • Clock step corrections. Time-sync daemons normally slew the clock (speed it up or slow it down a little), which never goes backwards. But when the offset is large, they step it. For example, ntpd steps the clock by default if the offset is above 128 ms (Red Hat NTP docs). A step can go backwards.
  • Manual adjustment. Someone changes the time in the system settings.
  • Virtual machine resume. When a VM is suspended and resumed, its clock may snap forward or backward to match the host.
  • Daylight saving time does not cause this. DST changes the displayed local time, but Date.now() returns milliseconds since the Unix epoch, which has no time zone.

Any of the first three can make two consecutive Date.now() calls return non-monotonic values. It's rare, but it happens often enough in production to be a real source of bugs.

The fix: performance.now() for durations

performance.now() reads a different clock. MDN describes the time origin it counts from as "a monotonic clock: its current time never decreases and isn't subject to adjustments". It returns a high-resolution value in milliseconds, with fractions.

const start = performance.now(); doSomeWork(); const end = performance.now(); const elapsed = end - start; // elapsed is never negative 

Use performance.now() for anything that measures a duration. Use Date.now() when you need to record an absolute moment (a log entry, a database row, a scheduled event). Don't use Date.now() for timing.

The other failure mode: ID generation

A common pattern:

// Generate a "unique" ID using the current time function makeId() { return Date.now().toString(36); } 

This works until two events happen in the same millisecond, and then you get a duplicate. People usually add a random suffix:

function makeId() { return Date.now().toString(36) + Math.random().toString(36).slice(2, 6); } 

Better, but it still has the non-monotonic problem. If your IDs are supposed to sort by creation time (an assumption that often goes unstated), a backward clock jump can produce new IDs that sort before older ones. If you use IDs as cursors in a paginated API, that's a real bug.

UUIDv7 puts a timestamp at the front, so IDs sort by time. RFC 9562 describes optional methods for keeping UUIDv7 values increasing: an implementation remembers the last timestamp it used and counts up from it if the wall clock moves backwards. Many libraries do this, but a plain generator doesn't have to. Node's built-in crypto.randomUUID() only makes random v4 UUIDs, so use a library for v7 and check that it keeps IDs monotonic.

The sneakier failure: cache expiration

This TTL cache looks correct but has the same bug:

class TtlCache { constructor(ttlMs) { this.ttl = ttlMs; this.store = new Map(); } set(key, value) { this.store.set(key, { value: value, expiresAt: Date.now() + this.ttl }); } get(key) { const entry = this.store.get(key); if (!entry) return undefined; if (Date.now() > entry.expiresAt) { this.store.delete(key); return undefined; } return entry.value; } } 

It works until the clock jumps. If the clock jumps forward an hour (a manual change or a VM resume, say), every entry expires at once, because Date.now() is now an hour ahead of when they were set. Your cache hit rate drops to near zero and your downstream service gets hammered. A jump backwards does the opposite: entries live longer than their TTL.

The fix is to base the deadline on a monotonic clock: store performance.now() + ttl, and compare against performance.now(). Or use a cache library that already does this.

What you can do

  • Use performance.now() for durations. Never Date.now() - Date.now().
  • Use UUIDv7 for time-ordered IDs, from a library that keeps them monotonic. Don't build them from Date.now() yourself.
  • Use a monotonic clock for cache TTLs, or a library that does.
  • For absolute timestamps in logs, Date.now() is fine. Just don't rely on it only moving forward.
  • Test the bad case: mock Date.now() and check that your code survives a clock that suddenly moves back an hour.

Precision of performance.now()

Browsers deliberately limit the precision of performance.now() to make timing attacks harder. The High Resolution Time spec sets a default resolution of 100 microseconds, or 5 microseconds when the page is cross-origin isolated, and says implementations may use a coarser value (W3C spec, section 4). MDN gives the same two numbers.

That is fine for almost every use. If you need sharper timing for benchmarks, look into cross-origin isolation (see MDN's reduced time precision section).

For everyday work: performance.now() for elapsed time, Date.now() for wall-clock moments, and don't assume wall-clock time only moves forward.