Come JavaScript memorizza il tempo internamente
Ogni Date di JavaScript è internamente un singolo float a 64 bit che rappresenta i millisecondi dall'epoch Unix (1° gennaio 1970 00:00:00 UTC). Questo numero è ciò che restituiscono Date.getTime() e Date.now(). Nessun fuso è memorizzato dentro un Date — è sempre un conteggio di millisecondi UTC. Le informazioni sul fuso contano solo quando formatti la data per la visualizzazione, ed è per questo che lo stesso oggetto Date può apparire come lunedì sera a Los Angeles e martedì mattina a Tokyo. Questo articolo si concentra su Date.now() e sulla conversione dei timestamp; per una panoramica più ampia di ogni attività con i timestamp in JavaScript, vedi la guida di riferimento completa collegata sotto.
Ottenere il timestamp Unix attuale
Usa Date.now() per i millisecondi e Math.floor(Date.now() / 1000) per i secondi. Entrambi sono ampiamente supportati e non richiedono import. L'abitudine di denominazione importante è includere l'unità nel nome della variabile: createdAtMs, expiresAtSeconds o unixSeconds. I nomi con unità impediscono a un futuro consumatore dell'API di indovinare cosa significa un campo timestamp nudo.
- Date.now() → 1700000000000 (milliseconds, 13 digits)
- Math.floor(Date.now() / 1000) → 1700000000 (seconds, 10 digits)
- +new Date() → same as Date.now() via unary coercion
- new Date().getTime() → same result, slightly more verbose
Date.now() vs performance.now()
Date.now() serve per i timestamp dell'orologio: log, payload API, campi di database, scadenza della cache e tutto ciò che deve allinearsi al tempo di calendario reale. performance.now() serve a misurare la durata trascorsa all'interno della pagina o del processo corrente. È monotono e ad alta precisione, ma non è un timestamp Unix e non può essere convertito in una data reale senza un punto di riferimento aggiuntivo.
- Usa Date.now() quando il valore verrà memorizzato, inviato a un'API o mostrato come data
- Usa performance.now() per misurare quanto sono durati il rendering, il parsing o una richiesta
- Non memorizzare performance.now() in un database come tempo di evento
- Non sottrarre due valori di Date.now() per la temporizzazione sensibile alla sicurezza; i cambi dell'orologio di sistema possono influenzarli
Convertire un timestamp in un Date
Il costruttore Date accetta millisecondi. Se il tuo timestamp è in secondi (10 cifre), moltiplica per 1000 prima di passarlo. Dimenticarlo è l'errore di timestamp più comune in JavaScript. Un controllo rapido è il numero di cifre: i secondi Unix attuali hanno 10 cifre, i millisecondi Unix attuali ne hanno 13, e una chiamata al costruttore Date dovrebbe ricevere la forma a 13 cifre in millisecondi.
- new Date(1700000000 * 1000) → Tue Nov 14 2023 22:13:20 UTC ✓ correct
- new Date(1700000000) → Tue Jan 20 1970 16:13:20 UTC ✗ missing × 1000
- new Date(1700000000 * 1000).toISOString() → '2023-11-14T22:13:20.000Z'
- new Date(1700000000 * 1000).toUTCString() → 'Tue, 14 Nov 2023 22:13:20 GMT'
Formattazione consapevole del fuso con Intl
Usa Intl.DateTimeFormat per un output consapevole di locale e fuso. Gestisce l'ora legale automaticamente e non richiede librerie esterne. È la via integrata più sicura per dashboard, strumenti di amministrazione, pagine di stato e timestamp rivolti all'utente, perché ti permette di scegliere esplicitamente sia il locale sia il fuso IANA.
- new Intl.DateTimeFormat('en-US', { timeZone: 'America/New_York', dateStyle: 'full', timeStyle: 'long' }).format(date)
- date.toLocaleString('en-GB', { timeZone: 'Europe/London', hour12: false })
- date.toLocaleString('zh-CN', { timeZone: 'Asia/Shanghai' })
- new Intl.DateTimeFormat('en-CA', { timeZone: tz }).formatToParts(date) → array of {type, value} for custom layouts
Parsare stringhe di data in sicurezza
Il parsing è dove JavaScript diventa sorprendente. Le stringhe ISO con una Z o un offset esplicito sono sicure perché identificano un istante esatto. Le date nude e le stringhe informali sono più facili da leggere, ma spesso dipendono dalle regole del browser o dal fuso del runtime. Per i contratti API, preferisci stringhe ISO 8601 con fuso o timestamp Unix numerici con l'unità scritta nel nome del campo.
- Safe: new Date('2026-05-19T14:30:00Z') — explicit UTC
- Safe: new Date('2026-05-19T10:30:00-04:00') — explicit offset
- Risky: new Date('05/19/2026') — locale-dependent and ambiguous
- Risky: new Date('2026-05-19 10:30') — not a strict ISO timestamp in all runtimes
Errori comuni di timestamp in JavaScript
- new Date(1700000000) invece di new Date(1700000000 * 1000) — cade nel 1970, non nel 2023
- getMonth() restituisce 0–11, non 1–12 — usa sempre date.getMonth() + 1 nella visualizzazione
- new Date('2024-01-01') viene parsato come mezzanotte UTC; new Date('2024/01/01') come mezzanotte locale
- Sommare 86400000 ms per «domani» si rompe alle transizioni dell'ora legale — usa setDate(d.getDate() + 1)
- Confrontare oggetti Date con === fallisce sempre — confronta invece i loro valori .getTime()
Checklist consigliata dei timestamp in JavaScript
Il pattern di produzione più semplice è memorizzare un singolo istante canonico e formattarlo solo al bordo. Mantieni i timestamp in UTC, includi le unità nei nomi e converti in un fuso leggibile solo nella UI o nel livello di reporting.
- Usa i millisecondi Unix per lo stato solo-browser e la costruzione di Date in JavaScript
- Usa i secondi Unix quando chiami API che documentano il tempo Unix in secondi
- Usa ISO 8601 con Z o un offset esplicito quando delle persone possono ispezionare i payload
- Usa Intl.DateTimeFormat con un timeZone esplicito per la visualizzazione
- Aggiungi test intorno ai confini dell'ora legale quando contano le date di calendario locali
FAQ sui timestamp in JavaScript
FAQ
- Does Date.now() return seconds or milliseconds?
- Date.now() returns milliseconds since January 1, 1970 00:00:00 UTC. Divide by 1000 and use Math.floor() when an API expects Unix seconds.
- Why does new Date(1700000000) show 1970?
- The Date constructor expects milliseconds. 1700000000 is a seconds timestamp, so JavaScript reads it as only 1.7 billion milliseconds after the epoch. Use new Date(1700000000 * 1000).
- Does a JavaScript Date store a timezone?
- No. A Date stores a UTC millisecond count. The timezone is applied only when formatting with methods like toString(), toLocaleString(), or Intl.DateTimeFormat.
- How do I convert a Unix timestamp to a JavaScript Date?
- Pass milliseconds to the constructor: new Date(seconds * 1000) for a 10-digit seconds value, or new Date(ms) for a 13-digit milliseconds value. Forgetting the × 1000 is why a 2023 timestamp can render as 1970.