Meteo Generator

Libreria TypeScript/JavaScript per la simulazione di condizioni meteo, tempo simulato (giorno/notte), stagioni, fasi lunari e traduzioni localizzate.

Installazione

npm install meteo-generator

Funzionalità Principali

• Simulazione del tempo (accelera o rallenta secondi, minuti, ore, giorni, mesi, anni) tramite il parametro rate.
• Modalità tempo: realtime (default) o manuale per simulazioni controllate.
• Profili climatici (moderate, dry, rainy, desert, polar, mediterranean, tropical, continental, alpine) che modulano probabilità meteo e temperature.
• Supporto altitudine con coordinate 3D (x, y, z) e calcolo temperatura basato su lapse rate atmosferico.
• Sistema temperatura avanzato con smoothing, componenti stagionali, giornaliere e di rumore.
• Temperatura percepita con wind chill (freddo) e heat index (caldo umido).
• Sistema atmosferico completo:
  • Vento (velocità, raffiche, direzione cardinale)
  • Umidità relativa (%)
  • Pressione atmosferica (hPa) con trend (rising/steady/falling)
  • Copertura nuvolosa (%)
  • Intensità precipitazioni (mm/h)
  • Visibilità (km) e condizioni di nebbia
  • Indice UV basato su ora, stagione, nuvole e altitudine
• Eventi meteo estremi pseudo-casuali (ondate di calore, gelate improvvise, grandinate, tempeste di sabbia, blizzard).
• Stagioni e meteo generati su base pseudo-casuale, con possibilità di definire un seed costante.
• Fasi lunari e fasi del giorno (mattino, pomeriggio, sera, notte).
• Supporto multilingua (it_IT, en_US, es_ES) tramite la classe Lang.
• Getter dedicati che restituiscono separatamente le chiavi tecniche (weatherKey, weatherSeasonKey ecc.) e le rispettive label tradotte (weather, weatherSeason ecc.).
• Riepilogo completo dei dati meteo tramite meteo.recap (tecnico) e meteo.recapLocalized (label/UI).
• Forecast per generare serie future (ore/giorni) con parametri riproducibili.
• Transizioni meteo controllate con parametri di hold/isteresi per rendere i cambi più realistici.

Costanti / Domini delle Chiavi Tecniche

La classe Meteo espone diverse chiavi tecniche (nomi costanti) che utilizza per gestire la logica interna e che possono essere lette dai getter (es. weatherKey, dayStatusKey, ecc.). Di seguito un elenco dei principali domini (ogni chiave ha poi la relativa label localizzata):

Le costanti numeriche della simulazione (soglie, fattori e parametri) sono centralizzate in METEO_CONST:

import Meteo, { METEO_CONST } from "meteo-generator";

1. Stagioni (SEASONS):

   • WINTER
   • SPRING
   • SUMMER
   • AUTUMN

2. Condizioni Meteo (WEATHER):

   • SUNNY
   • CLOUDY
   • LIGHT_RAIN
   • MODERATE_RAIN
   • HEAVY_RAIN
   • LIGHT_SNOW
   • HEAVY_SNOW
   • THUNDERSTORM

3. Elementi Giorno/Notte/Luna (ELEMENTS):

   • DAY
   • NIGHT
   • SUN
   • MOON
   • NA (per indicare “non applicabile” in alcuni contesti)

4. Fasi del Giorno (PHASE_DAY):

   • MORNING
   • AFTERNOON
   • EVENING
   • NIGHT

5. Fasi Lunari (PHASE_MOON):

   • NEW_MOON
   • WAXING_CRESCENT
   • FIRST_QUARTER
   • WAXING_GIBBOUS
   • FULL_MOON
   • WANING_GIBBOUS
   • LAST_QUARTER
   • WANING_CRESCENT

6. Profili Climatici (CLIMATE_PROFILES):

   • moderate - Clima equilibrato (default)
   • dry - Più sole, meno pioggia
   • rainy - Più pioggia e nuvole
   • desert - Prevalentemente soleggiato, pioggia rarissima
   • polar - Freddo intenso, più neve
   • mediterranean - Estati calde e secche, inverni miti
   • tropical - Caldo umido, piogge frequenti e temporali
   • continental - Forte escursione stagionale, inverni freddi e neve
   • alpine - Freddo di quota, neve frequente e venti sostenuti

7. Punti Cardinali (direzione vento):

   • N - Nord
   • NE - Nord-Est
   • E - Est
   • SE - Sud-Est
   • S - Sud
   • SW - Sud-Ovest
   • W - Ovest
   • NW - Nord-Ovest

8. Tendenza Pressione (pressureTrend):

   • rising - In aumento
   • steady - Stabile
   • falling - In diminuzione

Questi domini ti consentono di scrivere logica personalizzata in base alle chiavi tecniche (che rimangono sempre fisse), a prescindere dalla localizzazione.

Utilizzo di Base

Importazione

In TypeScript/ES6:

import Meteo from "meteo-generator";
import Lang from "meteo-generator/lang"; // Se vuoi accedere esplicitamente a "Lang"

In JavaScript (CommonJS):

const Meteo = require("meteo-generator").default;
const Lang = require("meteo-generator/lang").default;

Creazione di un'istanza

const meteo = new Meteo({
  startYear: 2025,      // Anno iniziale della simulazione
  startMonth: 6,        // Mese iniziale (1-12, opzionale)
  rate: 48,             // Velocità a cui avanza il tempo simulato
  seed: "example-seed", // Seed per il generatore pseudocasuale
  temperatureType: "celsius", // o "fahrenheit"
  weatherHoldHours: 6,        // Durata minima (ore) prima di cambiare meteo
  weatherHysteresisHours: 2,  // Isteresi: il candidato deve "resistere" N ore
  extremeEventHoldHours: 12,  // Durata minima (ore) evento estremo
  position: { x: 0, y: 0, z: 1500 }, // Posizione 3D (z = altitudine in metri)
  climateProfile: "moderate", // "moderate", "dry", "rainy", "desert", "polar", "mediterranean", "tropical", "continental", "alpine"
  timeMode: "realtime", // "realtime" o "manual"
  timestampMs: null,    // Timestamp manuale in millisecondi (solo se timeMode = "manual")
});

Getter Principali

Una volta istanziato, puoi accedere alle informazioni simulate:

// Tempo e data simulati
console.log(meteo.hour);     // Ora virtuale (0-23)
console.log(meteo.day);      // Giorno (1-30)
console.log(meteo.month);    // Mese (1-12)
console.log(meteo.year);     // Anno

// Condizioni meteo
console.log(meteo.weatherKey);   // Chiave tecnica, es: "SUNNY", "CLOUDY", ...
console.log(meteo.weather);      // Label localizzata, es: "sunny", "nuvoloso", ...

// Stagione
console.log(meteo.weatherSeasonKey);   // Chiave tecnica, es: "WINTER", "SPRING"
console.log(meteo.weatherSeason);      // Label localizzata, es: "Winter", "Primavera"

// Giorno o notte
console.log(meteo.dayStatusKey);      // "DAY" o "NIGHT"
console.log(meteo.dayStatus);         // Label localizzata, es: "Day", "Night"

// Temperatura
console.log(meteo.temperature);       // Valore in °C (numerico)
console.log(meteo.temperatureString); // Stringa con °C o °F, es: "24°C", "75°F"
console.log(meteo.perceivedTemperature); // Temperatura percepita (wind chill/heat index)

// Dati atmosferici
console.log(meteo.windSpeed);         // Velocità vento in km/h
console.log(meteo.windGustSpeed);     // Raffiche di vento in km/h
console.log(meteo.windDirectionCardinal); // Direzione cardinale (N, NE, E, SE, S, SW, W, NW)
console.log(meteo.humidity);          // Umidità relativa (0-100%)
console.log(meteo.pressure);          // Pressione atmosferica (hPa)
console.log(meteo.pressureTrend);     // Tendenza: "rising", "steady", "falling"
console.log(meteo.cloudCover);        // Copertura nuvolosa (0-100%)
console.log(meteo.precipitationIntensity); // Intensità precipitazioni (mm/h)
console.log(meteo.visibility);        // Visibilità in km
console.log(meteo.uvIndex);           // Indice UV (0-11+)

Recap Completo

La proprietà meteo.recap restituisce un oggetto tecnico con chiavi e valori numerici/booleani, utile per logiche e calcoli.
La proprietà meteo.recapLocalized usa le stesse chiavi dove possibile, ma con valori localizzati (label) e stringhe formattate per la UI.

console.log(meteo.recap); // tecnico
console.log(meteo.recapLocalized); // label/UI

• meteo.recapString restituisce gli stessi valori in un’unica stringa multilinea.
• meteo.json restituisce un JSON stringificato.

Schema recap (tecnico)

| Campo | Tipo | Descrizione | | --- | --- | --- | | second | number | Secondo corrente (0-59). | | minute | number | Minuto corrente (0-59). | | hour | number | Ora corrente (0-23). | | day | number | Giorno corrente (1-30). | | month | number | Mese corrente (1-12). | | year | number | Anno corrente (offset incluso). | | yearOffset | number | Offset rispetto all’anno iniziale. | | weatherSeasonKey | string | Stagione tecnica (WINTER, SPRING, SUMMER, AUTUMN). | | weatherKey | string | Meteo tecnico (SUNNY, CLOUDY, LIGHT_RAIN, MODERATE_RAIN, HEAVY_RAIN, THUNDERSTORM, LIGHT_SNOW, HEAVY_SNOW). | | climateProfile | string | Profilo climatico (moderate, dry, rainy, desert, polar, mediterranean, tropical, continental, alpine). | | temperatureType | string | Tipo temperatura (celsius o fahrenheit). | | temperatureValue | number | Temperatura in °C (valore numerico). | | perceivedTemperatureValue | number | Temperatura percepita in °C. | | dayStatusKey | string | Giorno/notte (DAY o NIGHT). | | sunOrMoonKey | string | Sole/Luna (SUN o MOON). | | windSpeed | number | Velocità vento (km/h). | | windGustSpeed | number | Raffiche (km/h). | | windDirection | number | Direzione vento in gradi (0-360). | | humidity | number | Umidità relativa (%). | | pressure | number | Pressione atmosferica (hPa). | | pressureTrend | string | Trend pressione (rising, steady, falling). | | cloudCover | number | Copertura nuvolosa (%). | | precipitationIntensity | number | Intensità precipitazioni (mm/h). | | visibility | number | Visibilità (km). | | uvIndex | number | Indice UV (0-11+). | | hail | boolean | Presenza grandine. | | fog | boolean | Presenza nebbia. | | extremeEventKey | string | Evento estremo (HEAT_WAVE, SUDDEN_FROST, HAILSTORM, SANDSTORM, BLIZZARD, NONE). | | sunPhaseKey | string | Fase solare (MORNING, AFTERNOON, EVENING, NIGHT). | | moonPhaseIndex | number | Indice fase lunare (0-7). | | moonPhaseKey | string | Fase lunare (NEW_MOON, WAXING_CRESCENT, FIRST_QUARTER, WAXING_GIBBOUS, FULL_MOON, WANING_GIBBOUS, LAST_QUARTER, WANING_CRESCENT). | | dayPhaseKey | string | Fase del giorno (MORNING, AFTERNOON, EVENING, NIGHT). |

Schema recapLocalized (label/UI)

| Campo | Tipo | Descrizione | | --- | --- | --- | | date | string | Data formattata (DD/MM/YYYY). | | time | string | Ora formattata (HH:MM:00). | | datetime | string | Data+ora formattate. | | second | number | Secondo corrente (0-59). | | minute | number | Minuto corrente (0-59). | | hour | number | Ora corrente (0-23). | | day | number | Giorno corrente (1-30). | | month | number | Mese corrente (1-12). | | year | number | Anno corrente (offset incluso). | | yearOffset | number | Offset rispetto all’anno iniziale. | | weatherSeasonKey | string | Stagione localizzata (label). | | weatherKey | string | Meteo localizzato (label). | | climateProfile | string | Profilo climatico. | | temperatureType | string | Tipo temperatura (celsius o fahrenheit). | | temperatureValue | number | Temperatura in °C (valore numerico). | | temperatureString | string | Temperatura formattata (°C o °F). | | perceivedTemperatureValue | number | Temperatura percepita in °C. | | perceivedTemperatureString | string | Temperatura percepita formattata. | | dayStatusKey | string | Giorno/notte localizzato (label). | | sunOrMoonKey | string | Sole/luna localizzato (label). | | windSpeed | number | Velocità vento (km/h). | | windGustSpeed | number | Raffiche (km/h). | | windDirection | number | Direzione vento in gradi (0-360). | | windDirectionCardinal | string | Direzione cardinale (N, NE, E, ...). | | humidity | number | Umidità relativa (%). | | pressure | number | Pressione atmosferica (hPa). | | pressureTrend | string | Trend pressione. | | cloudCover | number | Copertura nuvolosa (%). | | precipitationIntensity | number | Intensità precipitazioni (mm/h). | | visibility | number | Visibilità (km). | | uvIndex | number | Indice UV (0-11+). | | hail | boolean | Presenza grandine. | | fog | boolean | Presenza nebbia. | | extremeEventKey | string | Evento estremo localizzato (label). | | sunPhaseKey | string | Fase solare localizzata (label). | | moonPhaseIndex | number | Indice fase lunare (0-7). | | moonPhaseKey | string | Fase lunare localizzata (label). | | dayPhaseKey | string | Fase del giorno localizzata (label). |

Profili Climatici

I profili climatici modulano le probabilità di ogni condizione meteo e i parametri termici:

• moderate: clima equilibrato (default)
• dry: più sole, meno pioggia, temperature più alte
• rainy: più pioggia e nuvole, temperature più basse
• desert: prevalentemente soleggiato, pioggia rarissima, grandi escursioni termiche
• polar: freddo intenso, più neve che pioggia, escursioni ridotte
• mediterranean: estati calde e secche, inverni miti e piogge moderate
• tropical: caldo umido, piogge frequenti e temporali
• continental: forte escursione stagionale, estati calde e inverni freddi
• alpine: freddo di quota, neve frequente e venti sostenuti

meteo.setClimateProfile("desert");
console.log(meteo.weatherKey); // Più probabilità di "SUNNY"

Modalità Tempo Manuale

Puoi controllare manualmente il timestamp invece di usare l'orologio di sistema:

// Imposta un timestamp specifico
meteo.setManualTimestamp(1640995200000); // timestamp in millisecondi
// oppure
meteo.setManualTimestampSeconds(1640995200); // timestamp in secondi

// Torna al tempo reale
meteo.useRealtimeTimestamp();

Aggiungere tempo simulato

In modalità manuale (o quando vuoi forzare il passaggio a manuale), puoi avanzare il tempo virtuale:

meteo.addSeconds(30);
meteo.addMinutes(15);
meteo.addHours(3);
meteo.addDays(1);
meteo.addMonths(1);
meteo.addYears(1);

Le unità sono virtuali e rispettano il rate impostato.

Stabilizzazione del meteo (hold & isteresi)

Per rendere i cambi meteo più realistici puoi usare questi parametri:

• weatherHoldHours: durata minima (in ore) prima che il meteo possa cambiare.
• weatherHysteresisHours: il nuovo meteo deve rimanere candidato per N ore prima di essere accettato.
• extremeEventHoldHours: durata minima (in ore) di un evento estremo.

Impostali a 0 per disattivare completamente il comportamento.

const meteo = new Meteo({
  weatherHoldHours: 6,
  weatherHysteresisHours: 2,
  extremeEventHoldHours: 12,
});

Altitudine e Temperatura

L'altitudine (coordinata z) influenza la temperatura con un lapse rate atmosferico di 6.5°C per 1000 metri:

const meteoMountain = new Meteo({
  position: { x: 0, y: 0, z: 2000 }, // 2000 metri di altitudine
  climateProfile: "moderate"
});

console.log(meteoMountain.temperature); // Circa 13°C più bassa rispetto a z=0

Inoltre, a temperature ≤ 0°C, la pioggia si trasforma automaticamente in neve.

Dati Atmosferici Avanzati

La libreria simula un sistema atmosferico completo con smoothing e transizioni realistiche:

Vento

console.log(meteo.windSpeed);              // 12.5 (km/h)
console.log(meteo.windGustSpeed);          // 18.3 (km/h)
console.log(meteo.windDirection);          // 245 (gradi, 0=Nord)
console.log(meteo.windDirectionCardinal);  // "SW"

Il vento è influenzato dal profilo climatico e varia con smoothing per evitare cambi bruschi.

Temperatura Percepita

console.log(meteo.temperature);            // 5°C
console.log(meteo.perceivedTemperature);   // 2°C (wind chill con vento)

// Con caldo e umidità
console.log(meteo.temperature);            // 32°C
console.log(meteo.perceivedTemperature);   // 38°C (heat index)

La temperatura percepita usa wind chill quando fa freddo e c'è vento, o heat index quando fa caldo con umidità elevata.

Pressione Atmosferica

console.log(meteo.pressure);        // 1013 (hPa)
console.log(meteo.pressureTrend);   // "falling" | "steady" | "rising"

La pressione varia tra 980-1030 hPa e tende a essere più bassa con maltempo.

Umidità, Nuvole e Precipitazioni

console.log(meteo.humidity);                  // 75 (%)
console.log(meteo.cloudCover);                // 85 (%)
console.log(meteo.precipitationIntensity);    // 4.2 (mm/h)

Visibilità e UV

console.log(meteo.visibility);    // 8.5 (km, ridotta con nebbia/pioggia)
console.log(meteo.uvIndex);       // 7 (0-11+, varia con ora/stagione/nuvole/altitudine)

Condizioni Speciali

console.log(meteo.isFoggy);       // true/false
console.log(meteo.isHailing);     // true/false (grandine)

Eventi Meteo Estremi

console.log(meteo.extremeEventKey);   // "HEAT_WAVE" | "SUDDEN_FROST" | ...
console.log(meteo.extremeEvent);      // Label localizzata

Gli eventi estremi sono deterministici rispetto al seed e al tempo simulato.

Override di Alcuni Parametri al Volo (getMeteo)

Puoi generare una nuova istanza di Meteo basandoti sull'istanza corrente e sovrascrivere alcuni parametri (come posizione, velocità, seed, ecc.):

const newMeteo = meteo.getMeteo({
  rate: 1,          // per questa nuova istanza
  seed: "otherSeed",
  temperatureType: "fahrenheit",
  position: { x: 100, y: 200, z: 500 },
  climateProfile: "rainy"
});

console.log(newMeteo.recap);

Questo metodo non modifica l'istanza originale, ma ne crea una nuova con i parametri combinati.

Forecast (serie temporali)

Puoi generare una serie futura di riepiloghi con step configurabili:

const nextHours = meteo.getForecastHours(24, 1); // 24 step orari
const nextDays = meteo.getForecastDays(7, 1);    // 7 step giornalieri

È disponibile anche l'API generica:

const forecast = meteo.getForecast({
  hours: 12,
  stepHours: 3,
  includeCurrent: false,
  seed: "custom-seed",
});

Tuning avanzato (opzionale)

Il comportamento della selezione meteo è legato al rumore e alla sua distribuzione. Il parametro METEO_CONST.NOISE.WEATHER.DISTRIBUTION_EXPONENT permette di modificarla: valori più bassi (es. 0.7) aumentano la frequenza di eventi più rari; valori più alti (es. 1.1) la riducono.

Localizzazione

Per cambiare lingua o aggiungere traduzioni personalizzate, puoi usare la classe Lang. Ad esempio:

Lang.setLang("it_IT");
// Oppure aggiungere dizionari personalizzati
Lang.addLang("it_IT", {
  "METEO.WEATHER": {
    SUNNY: "soleggiato",
    CLOUDY: "nuvoloso",
    // etc...
  }
});

Le label localizzate (come meteo.weather) si aggiorneranno di conseguenza.

Esempio Completo

import Meteo from "meteo-generator";
import Lang from "meteo-generator/lang";

Lang.setLang("it_IT");

const meteo = new Meteo({
  startYear: 2025,
  startMonth: 6,
  rate: 48,
  seed: "example-seed",
  temperatureType: "celsius",
  position: { x: 0, y: 0, z: 1200 }, // 1200m altitudine
  climateProfile: "moderate",
});

// Stampa ogni 2 secondi il recap
setInterval(() => {
  console.log(meteo.recapString);
}, 2000);

Uso in Browser

La libreria può essere usata anche nel browser tramite bundle IIFE:

<script src="node_modules/meteo-generator/dist/meteo.browser.js"></script>
<script>
  const meteo = new MeteoLib.default({
    startYear: 2025,
    climateProfile: "rainy",
    position: { x: 0, y: 0, z: 500 }
  });

  console.log(meteo.recap);
</script>

Contributi

Puoi contribuire segnalando bug o proponendo nuove funzionalità attraverso la sezione Issues del repository.

Licenza

Distribuito sotto licenza MIT.

Buona simulazione con Meteo Generator!