Date in JavaScript: new Date, formattazione e confronti

L'oggetto Date è un istante nel tempo

In JavaScript una Date rappresenta un singolo istante: internamente è solo un numero di millisecondi a partire dal 1° gennaio 1970 UTC (la "Unix epoch"). Tutto il resto (anni, mesi, giorni, fusi orari, formattazione) è una vista costruita sopra quel numero.

const now = new Date();
console.log(now);
console.log(now.getTime());

now.getTime() è il conteggio grezzo dei millisecondi. Tutto ciò che fa una Date (confrontare, aggiungere giorni, formattare) si riduce a manipolare quel numero e poi reinterpretarlo.

Tieni a mente questo modello. Una Date non è "14 marzo a Parigi". È un istante universale che può essere mostrato come 14 marzo a Parigi, o 13 marzo a Los Angeles, a seconda del fuso orario da cui lo guardi.

Creare le date

Ci sono quattro modi principali per costruire una Date:

const now = new Date();
const fromTimestamp = new Date(1_700_000_000_000);
const fromString = new Date("2026-03-14T09:30:00Z");
const fromParts = new Date(2026, 2, 14, 9, 30);

console.log(now.toISOString());
console.log(fromTimestamp.toISOString());
console.log(fromString.toISOString());
console.log(fromParts.toISOString());

Due cose da notare:

• Il costruttore per parti usa mesi con indice da zero. 2 significa marzo. Gennaio è 0. È una fonte costante di errori di uno: anche nel resto dell'API i mesi partono da 0, quindi almeno è coerente con sé stessa.
• new Date("2026-03-14") (senza orario) viene interpretata come mezzanotte UTC. new Date("2026-03-14T09:30") (senza Z) viene interpretata come ora locale. Questa asimmetria è un tranello classico.

Per avere "adesso" come numero, preferisci Date.now(): evita di creare l'oggetto:

const start = Date.now();
for (let i = 0; i < 1_000_000; i++) {}
const elapsed = Date.now() - start;
console.log(`${elapsed} ms`);

Date.now() è lo strumento giusto per misurare il tempo trascorso, per i timeout e per tutto ciò in cui non ti servono calcoli sul calendario.

Leggere le parti di una data

Una volta che hai una Date, ne estrai i componenti con i getter. Ognuno esiste in due versioni: ora locale e UTC.

const d = new Date("2026-03-14T09:30:00Z");

console.log(d.getFullYear());      // local year
console.log(d.getMonth());         // 0-11, local
console.log(d.getDate());          // day of month, local
console.log(d.getDay());           // day of week, 0=Sunday
console.log(d.getHours());
console.log(d.getMinutes());

console.log(d.getUTCFullYear());
console.log(d.getUTCHours());

Quelli locali dipendono dalla macchina su cui gira il codice. Se salvi o confronti date tra utenti e server diversi, scegli esplicitamente UTC o finirai a inseguire bug fantasma. Regola pratica: usa i getter UTC per tutto ciò che va in un database o in un log; usa i getter locali per tutto ciò che stai per mostrare a una persona.

Non usare getYear(). È un metodo legacy che restituisce year - 1900 ed esiste solo per compatibilità. Usa sempre getFullYear().

Formattare per le persone

Evita date.toString() per qualsiasi cosa ti importi: il suo output dipende dalle impostazioni locali e dal motore. Ci sono due formattatori da conoscere.

Per una stringa standard leggibile dalle macchine, usa toISOString():

const d = new Date("2026-03-14T09:30:00Z");
console.log(d.toISOString());

È il formato da usare per i log, per salvare in JSON o per inviare dati in rete. È sempre in UTC e sempre non ambiguo.

Per una stringa destinata alle persone, usa Intl.DateTimeFormat o i metodi toLocale*, che lo usano internamente:

const d = new Date("2026-03-14T09:30:00Z");

console.log(d.toLocaleDateString("en-US"));
console.log(d.toLocaleDateString("en-GB"));
console.log(d.toLocaleString("fr-FR", { dateStyle: "full", timeStyle: "short" }));

const formatter = new Intl.DateTimeFormat("en-US", {
    year: "numeric",
    month: "long",
    day: "numeric",
    timeZone: "America/New_York",
});
console.log(formatter.format(d));

Intl.DateTimeFormat gestisce lingue, fusi orari e ogni combinazione di campi che potresti volere. Usalo prima di scrivere a mano una formattazione come ${year}-${month}-${day}: è in quel tipo di costruzione di stringhe che si nascondono gli errori di un mese.

Confrontare le date

Due oggetti Date che rappresentano lo stesso istante non sono uguali con ===: === controlla l'identità dell'oggetto, non il valore. Confronta invece i loro timestamp:

const a = new Date("2026-03-14T09:30:00Z");
const b = new Date("2026-03-14T09:30:00Z");

console.log(a === b);              // false
console.log(a.getTime() === b.getTime());  // true
console.log(+a === +b);            // true - unary + coerces to number

Per l'ordinamento, gli operatori di confronto funzionano direttamente perché convertono in numeri:

const earlier = new Date("2026-01-01");
const later = new Date("2026-06-01");

console.log(earlier < later);
console.log(later > earlier);

const differenceMs = later - earlier;
const differenceDays = differenceMs / (1000 * 60 * 60 * 24);
console.log(`${differenceDays} days apart`);

La sottrazione ti dà la distanza in millisecondi. Dividi per 1000 * 60 * 60 * 24 per ottenere i giorni. Scrivi la costante per esteso la prima volta; dopo un po' riconoscerai 86_400_000 a colpo d'occhio.

Calcoli con le date

Non esiste un metodo addDays. Il modo idiomatico è usare setDate, setMonth e simili: accettano valori fuori intervallo e passano correttamente al periodo successivo:

function addDays(date, days) {
    const result = new Date(date);
    result.setDate(result.getDate() + days);
    return result;
}

const today = new Date("2026-03-14");
console.log(addDays(today, 7).toISOString());
console.log(addDays(today, 30).toISOString());
console.log(addDays(today, -5).toISOString());

Due cose da sottolineare:

• new Date(date) copia la data. setDate modifica l'oggetto, quindi copia sempre prima, altrimenti cambierai il valore di chi ha chiamato la funzione.
• setDate(35) su un mese di 31 giorni passa automaticamente al mese successivo. Lo stesso vale per setMonth(14), che fa avanzare l'anno. Questo rende i calcoli molto meno dolorosi di quanto sembri.

Per qualsiasi cosa complessa (giorni lavorativi, eventi ricorrenti, durate che tengono conto dei mesi) usa una libreria (date-fns, Luxon o la futura API Temporal). Scriverti da solo la matematica del calendario oltre il "aggiungi qualche giorno" è una palude.

Fusi orari: un bagno di realtà

I fusi orari sono la più grande fonte di bug con le date. Le regole da assimilare:

• Una Date memorizza un istante UTC. Il fuso orario viene applicato solo quando ne leggi le parti o la formatti.
• Il fuso orario usato da getHours(), getDate() e simili è quello locale della macchina che esegue il codice. Server e browser spesso non sono d'accordo.
• new Date("2026-03-14") (solo data) viene interpretata come UTC. new Date("2026-03-14T00:00") (con orario, senza fuso) come ora locale. new Date(2026, 2, 14) (per parti) è in ora locale.

const fromString = new Date("2026-03-14");
const fromParts = new Date(2026, 2, 14);

console.log(fromString.toISOString());
console.log(fromParts.toISOString());

// These may differ by several hours depending on your timezone.

Quando ti serve un fuso orario specifico per la visualizzazione, passa timeZone a Intl.DateTimeFormat:

const d = new Date("2026-03-14T09:30:00Z");

const tokyo = new Intl.DateTimeFormat("en-US", {
    dateStyle: "short",
    timeStyle: "short",
    timeZone: "Asia/Tokyo",
});
const nyc = new Intl.DateTimeFormat("en-US", {
    dateStyle: "short",
    timeStyle: "short",
    timeZone: "America/New_York",
});

console.log(tokyo.format(d));
console.log(nyc.format(d));

Stesso istante, due viste. L'oggetto Date in sé non è cambiato.

Un piccolo esempio funzionante

Mettiamo tutto insieme: una funzione che indica quanto tempo fa è successo qualcosa:

function timeAgo(date) {
    const seconds = Math.floor((Date.now() - date.getTime()) / 1000);
    if (seconds < 60) return `${seconds}s ago`;

    const minutes = Math.floor(seconds / 60);
    if (minutes < 60) return `${minutes}m ago`;

    const hours = Math.floor(minutes / 60);
    if (hours < 24) return `${hours}h ago`;

    const days = Math.floor(hours / 24);
    return `${days}d ago`;
}

const past = new Date(Date.now() - 3 * 60 * 60 * 1000);
console.log(timeAgo(past));

const older = new Date(Date.now() - 5 * 24 * 60 * 60 * 1000);
console.log(timeAgo(older));

Timestamp in ingresso, stringa leggibile in uscita. È la forma del 90% del codice reale sulle date: sottrai due istanti, dividi per un'unità, arrotonda, formatta.

Cosa portarti a casa

• Una Date è un istante UTC. I fusi orari compaiono quando la leggi o la formatti.
• Usa Date.now() per i timestamp, new Date() per i calcoli sul calendario.
• Usa toISOString() per il salvataggio e i log, Intl.DateTimeFormat per gli utenti.
• Confronta con getTime() o con </>. Mai con ===.
• I mesi partono da 0. Attenzione alla trappola del parsing delle stringhe con la sola data.
• Per calcoli seri sulle date, usa una libreria.

Prossimo passo: URL e query string

Le date compaiono spesso negli URL: filtri per intervallo di date, timestamp passati come parametri di query. Analizzare e costruire URL a mano è soggetto a errori tanto quanto formattare le date a mano, e la libreria standard ha un oggetto URL che se ne occupa in modo pulito. È il prossimo argomento.