JavaScript: usare Math, Date e JSON per costruire un convertitore di fusi orari

Introduzione

Gli oggetti globali Math, Date e JSON sono tra gli strumenti più utili in JavaScript quando devi lavorare con dati reali. In questo tutorial vediamo un caso pratico e molto comune: creare un convertitore di fusi orari.

Un convertitore di fusi orari serve a trasformare una data e un’ora da un fuso all’altro, ad esempio da Europe/Rome a America/New_York. Questo tipo di funzionalità è utile in applicazioni di booking, dashboard internazionali, sistemi di supporto clienti, calendari condivisi e strumenti per team distribuiti in paesi diversi.

Per farlo useremo:

• Date per gestire la data e l’orario di partenza;
• Math per arrotondare e normalizzare i risultati;
• JSON per serializzare e salvare la conversione in modo strutturato.

Codice completo

// Convertitore semplice di fusi orari con JavaScript
// Nota: per una gestione completa dei timezone reali, in produzione è meglio usare librerie
// come Intl.DateTimeFormat o librerie dedicate. Qui costruiamo un esempio didattico.

const timezoneOffsets = {
  "Europe/Rome": 1,       // UTC+1
  "UTC": 0,               // UTC
  "America/New_York": -5, // UTC-5
  "America/Los_Angeles": -8, // UTC-8
  "Asia/Tokyo": 9         // UTC+9
};

// Funzione per convertire una data da un fuso a un altro
function convertTimezone(dateString, fromZone, toZone) {
  if (!timezoneOffsets.hasOwnProperty(fromZone) || !timezoneOffsets.hasOwnProperty(toZone)) {
    throw new Error("Fuso orario non supportato.");
  }

  // Creiamo una data di partenza
  const inputDate = new Date(dateString);

  if (isNaN(inputDate.getTime())) {
    throw new Error("Data non valida.");
  }

  // Differenza tra i due fusi orari in ore
  const offsetDifference = timezoneOffsets[toZone] - timezoneOffsets[fromZone];

  // Convertiamo in millisecondi
  const convertedTime = inputDate.getTime() + offsetDifference * 60 * 60 * 1000;

  const resultDate = new Date(convertedTime);

  // Formattiamo i valori in modo leggibile
  const year = resultDate.getFullYear();
  const month = String(resultDate.getMonth() + 1).padStart(2, "0");
  const day = String(resultDate.getDate()).padStart(2, "0");
  const hours = String(resultDate.getHours()).padStart(2, "0");
  const minutes = String(resultDate.getMinutes()).padStart(2, "0");
  const seconds = String(resultDate.getSeconds()).padStart(2, "0");

  // Usiamo Math per arrotondare i minuti residui se necessario
  const totalMinutes = Math.round((convertedTime / 1000 / 60) % 60);

  const conversion = {
    input: {
      dateTime: dateString,
      timezone: fromZone
    },
    output: {
      dateTime: `${year}-${month}-${day} ${hours}:${minutes}:${seconds}`,
      timezone: toZone
    },
    meta: {
      offsetDifferenceHours: offsetDifference,
      roundedMinutesSample: Math.abs(totalMinutes)
    }
  };

  return JSON.stringify(conversion, null, 2);
}

// Esempio di utilizzo
try {
  const jsonResult = convertTimezone(
    "2026-06-12T14:30:00",
    "Europe/Rome",
    "America/New_York"
  );

  console.log(jsonResult);
} catch (error) {
  console.error("Errore:", error.message);
}

Spiegazione

Vediamo il codice passo per passo.

1. Mappa dei fusi orari

Abbiamo creato un oggetto timezoneOffsets che associa a ogni fuso un offset rispetto a UTC. Per esempio, Europe/Rome è impostato a 1, mentre Asia/Tokyo a 9.

Questa soluzione è semplice e utile per imparare, ma ricorda che nella realtà i fusi orari possono cambiare per via dell’ora legale. Quindi questo approccio è adatto a esercizi, prototipi o casi controllati.

2. Validazione dell’input

Prima controlliamo che il fuso di partenza e quello di destinazione siano presenti nella mappa. Poi creiamo un oggetto Date a partire dalla stringa passata come input.

Il controllo isNaN(inputDate.getTime()) serve a verificare se la data è valida. Se l’input non è interpretabile, il programma genera un errore esplicito.

3. Calcolo della differenza oraria

La conversione si basa sulla differenza tra i due offset:

• se il fuso di destinazione è avanti rispetto a quello di partenza, aggiungiamo ore;
• se è indietro, sottraiamo ore.

La conversione avviene in millisecondi perché Date lavora internamente con questo formato. Per questo moltiplichiamo le ore per 60 * 60 * 1000.

4. Uso di Math

In questo esempio Math.round() viene usato per arrotondare i minuti residui. Anche se il calcolo principale è basato sulle ore, può essere utile mostrare come usare Math per normalizzare o presentare i dati in modo più pulito.

In applicazioni reali, Math è molto utile anche per:

• arrotondare durate;
• calcolare intervalli approssimati;
• convertire frazioni di tempo in unità leggibili.

5. Serializzazione con JSON

Alla fine restituiamo il risultato con JSON.stringify(). Questo è molto pratico perché il risultato diventa facilmente salvabile, inviabile via API o mostrabile in un’interfaccia frontend.

La struttura JSON contiene:

• input: i dati originali inseriti dall’utente;
• output: la data convertita;
• meta: informazioni aggiuntive utili per debug o logging.

Best practice

Quando lavori con date e fusi orari, ci sono alcune regole importanti da seguire.

• Preferisci ISO 8601: usa formati come 2026-06-12T14:30:00 per ridurre ambiguità.
• Valida sempre l’input: una data non valida può generare bug difficili da tracciare.
• Non fidarti degli offset fissi in produzione: i fusi reali includono l’ora legale e variazioni regionali.
• Usa JSON per scambiare dati: è perfetto per API, log e salvataggi semplici.
• Separa logica e presentazione: la conversione deve restituire dati puliti, mentre la UI si occupa della visualizzazione.
• Documenta il comportamento: specifica chiaramente se il sistema supporta o meno l’ora legale.

Se il tuo obiettivo è una soluzione robusta per il mondo reale, considera l’uso di Intl.DateTimeFormat o librerie specializzate. Tuttavia, per capire bene il ruolo di Math, Date e JSON, questo esempio è perfetto.

Riepilogo

In questo tutorial abbiamo costruito un convertitore di fusi orari usando tre oggetti globali fondamentali di JavaScript:

• Date per leggere e manipolare date e orari;
• Math per arrotondare e normalizzare i valori numerici;
• JSON per produrre un risultato strutturato e riutilizzabile.

Il vantaggio di questo approccio è che unisce concetti base e uso pratico. È un ottimo esercizio per imparare a gestire dati temporali, a validare input e a generare output adatto a un’app moderna.

Approfondisci con risorse ufficiali

• MDN - Math: documentazione completa sugli oggetti e metodi matematici di JavaScript.
• MDN - Date: guida ufficiale per creare, leggere e manipolare date.
• MDN - JSON: riferimenti per JSON.stringify() e JSON.parse().
• MDN - Intl.DateTimeFormat: utile per formattare date e orari in modo corretto per località e fusi orari.

Se vuoi fare un passo avanti, il prossimo esercizio ideale è trasformare questo convertitore in un piccolo widget web con selezione del fuso, input data e output formattato in tempo reale.