metar-taf-parser 5.0.0 → 6.0.0

package/README.md

@@ -45,7 +45,7 @@ const datedMetar = parseMetar(rawMetarString, { issued });
 
 #### `parseTAF`
 
-👉 **Note:** One of the common use cases for TAF reports is to get relevant forecast data for a given date. Check out [the `Forecast` abstraction](#higher-level-parsing-the-forecast-abstraction) below which may provide TAF data in a more normalized format, depending on your use case.
+> 👉 **Note:** One of the common use cases for TAF reports is to get relevant forecast data for a given `Date`, or display the various forecast groups to the user. Check out [the `Forecast` abstraction](#higher-level-parsing-the-forecast-abstraction) below which may provide TAF data in a more normalized and easier to use format, depending on your use case.
 
 ```ts
 import { parseTAF } from "metar-taf-parser";
@@ -61,11 +61,32 @@ const datedTAF = parseTAF(rawTAFString, { issued });
 
 ### Higher level parsing: The Forecast abstraction
 
-TAF reports are a little funky... FM, BECMG, PROB, etc. You may find the `Forecast` abstraction more helpful.
+TAF reports are a little funky... FM, BECMG, PROB, weird validity periods, etc. You may find the higher level `Forecast` abstraction more helpful.
+
+⚠️ **Important:** The `Forecast` abstraction makes some assumptions in order to make it easier to consume the TAF. If you want different behavior, you may want to use the lower level `parseTAF` function directly (see above). Below are some of the assumptions the `Forecast` API makes:
+
+1.  The `validity` object found from `parseTAF`'s `trends[]` is too low level, so it is removed. Instead, you will find `start` and `end` on the base `Forecast` object. The end of a `FM` and `BECMG` group is derived from the start of the next `FM`/`BECMG` trend, or the end of the report validity if the last.
+
+    Additionally, there is a property, `by`, on `BECMG` trends for when conditions are expected to finish transitioning. You will need to type guard `type = BECMG` to access this property.
+
+    ```ts
+    const firstForecast = report.forecast[1];
+    if (firstForecast.type === WeatherChangeType.BECMG) {
+      // Can now access `by`
+      console.log(firstForecast.by);
+    }
+    ```
+
+2.  `BECMG` trends are hydrated with the context of previous trends. For example, if:
+
+        TAF SBBR 221500Z 2218/2318 15008KT 9999 FEW045
+          BECMG 2308/2310 09002KT
+
+    Then the `BECMG` group will also have visibility and clouds from previously found conditions, with updated winds.
 
 #### `parseTAFAsForecast`
 
-Returns a more normalized TAF report. Most notably: while the `parseTAF` function returns initial weather conditions on the base of the returned result (and further conditions on `trends[]`), the `parseTAFAsForecast` function returns the initial weather conditions as the first element of the `forecast[]` property, followed by subsequent trends. This makes it much easier to iterate though.
+Returns a more normalized TAF report than `parseTAF`. Most notably: while the `parseTAF` function returns initial weather conditions on the base of the returned result (and further conditions on `trends[]`), the `parseTAFAsForecast` function returns the initial weather conditions as the first element of the `forecast[]` property (with `type = undefined`), followed by subsequent trends. (For more, please see the above about the forecast abstraction.) This makes it much easier to render a UI similar to the [aviationweather.gov](https://www.aviationweather.gov/taf/data?ids=SBPJ&format=decoded&metars=off&layout=on) TAF decoder.
 
 ```ts
 import { parseTAFAsForecast } from "metar-taf-parser";
@@ -80,11 +101,11 @@ console.log(report.forecast);
 
 > ⚠️ **Warning:** Experimental API
 
-Provides all relevant weather conditions for a given timestamp. It returns a `ICompositeForecast` with a `base` and `additional` component. The `base` component is the base weather condition period (the FM part of the report) - and there will always be one.
+Provides all relevant weather conditions for a given timestamp. It returns a `ICompositeForecast` with a `base` and `additional` component. The `base` component is the base weather condition period (type = `FM`, `BECMG`, or `undefined`) - and there will always be one.
 
-The `additional` property is an array of weather condition periods valid for the given timestamp (any `BECMG`, `PROB`, `TEMPO`, etc.)
+The `additional` property is an array of weather condition periods valid for the given timestamp (any `PROB` and/or `TEMPO`)
 
-You will still need to write some logic to use this API to determine what data to use - for example, if `additional[0].visibility` exists, use it over `base.visibility`.
+You will still need to write some logic to use this API to determine what data to use - for example, if `additional[0].visibility` exists, you may want to use it over `base.visibility`.
 
 #### Example
 

package/metar-taf-parser.d.ts

@@ -1045,6 +1045,9 @@ interface IAirport {
 interface IWind {
     speed: number;
     direction: string;
+    /**
+     * If undefined, direction is variable
+     */
     degrees?: number;
     gust?: number;
     minVariation?: number;
@@ -1077,11 +1080,14 @@ interface IWeatherCondition {
     phenomenons: Phenomenon[];
 }
 declare function isWeatherConditionValid(weather: IWeatherCondition): boolean;
-interface ITemperatureDated {
+interface ITemperature {
     temperature: number;
     day: number;
     hour: number;
 }
+interface ITemperatureDated extends ITemperature {
+    date: Date;
+}
 interface IRunwayInfo {
     name: string;
     minRange: number;
@@ -1168,12 +1174,17 @@ interface IMetar extends IAbstractWeatherCode {
 }
 interface ITAF extends IAbstractWeatherCode {
     validity: IValidity;
-    maxTemperature?: ITemperatureDated;
-    minTemperature?: ITemperatureDated;
+    maxTemperature?: ITemperature;
+    minTemperature?: ITemperature;
     trends: TAFTrend[];
+    /**
+     * Just the first part of the TAF message without trends (FM, BECMG, etc)
+     */
+    initialRaw: string;
 }
 interface IAbstractTrend extends IAbstractWeatherContainer {
     type: WeatherChangeType;
+    raw: string;
 }
 interface IMetarTrendTime extends ITime {
     type: TimeIndicator;
@@ -1260,6 +1271,8 @@ interface ITAFDated extends ITAF {
         start: Date;
         end: Date;
     };
+    minTemperature?: ITemperatureDated;
+    maxTemperature?: ITemperatureDated;
     trends: TAFTrendDated[];
 }
 
@@ -1292,14 +1305,34 @@ declare class UnexpectedParseError extends ParseError {
  * The initial forecast, extracted from the first line of the TAF, does not have
  * a trend type (FM, BECMG, etc)
  */
-declare type Forecast = Omit<TAFTrendDated, "type"> & Partial<Pick<TAFTrendDated, "type">>;
-interface IForecastContainer {
+declare type ForecastWithoutDates = Omit<TAFTrendDated, "type"> & Partial<Pick<TAFTrendDated, "type">>;
+declare type ForecastWithoutValidity = Omit<ForecastWithoutDates, "validity">;
+declare type Forecast = Omit<ForecastWithoutValidity, "type"> & {
+    start: Date;
+    end: Date;
+} & ({
+    type: Exclude<WeatherChangeType, WeatherChangeType.BECMG> | undefined;
+} | {
+    type: WeatherChangeType.BECMG;
+    /**
+     * BECMG has a special date, `by`, for when the transition will finish
+     *
+     * For example, a BECMG trend may `start` at 1:00PM and `end` at 5:00PM, but
+     * `by` may be `3:00PM` to denote that conditions will transition from a period of
+     * 1:00PM to 3:00PM
+     */
+    by: Date;
+});
+interface IForecastContainer extends IFlags {
     station: string;
     issued: Date;
     start: Date;
     end: Date;
     message: string;
     forecast: Forecast[];
+    amendment?: true;
+    maxTemperature?: ITemperatureDated;
+    minTemperature?: ITemperatureDated;
 }
 interface ICompositeForecast {
     /**
@@ -1339,4 +1372,4 @@ declare function parseTAF(rawTAF: string, options?: IMetarTAFParserOptions): ITA
 declare function parseTAF(rawTAF: string, options?: IMetarTAFParserOptionsDated): ITAFDated;
 declare function parseTAFAsForecast(rawTAF: string, options: IMetarTAFParserOptionsDated): IForecastContainer;
 
-export { CloudQuantity, CloudType, CommandExecutionError, Descriptive, Direction, Distance, DistanceUnit, Forecast, IAbstractTrend, IAbstractValidity, IAbstractWeatherCode, IAbstractWeatherCodeDated, IAbstractWeatherContainer, IAirport, IBaseRemark, IBaseTAFTrend, ICeilingHeightRemark, ICeilingSecondLocationRemark, ICloud, ICompositeForecast, ICountry, IEndValidity, IFMValidity, IFlags, IForecastContainer, IHourlyMaximumMinimumTemperatureRemark, IHourlyMaximumTemperatureRemark, IHourlyMinimumTemperatureRemark, IHourlyPrecipitationAmountRemark, IHourlyPressureRemark, IHourlyTemperatureDewPointRemark, IIceAccretionRemark, IMetar, IMetarTAFParserOptions, IMetarTAFParserOptionsDated, IMetarTrend, IMetarTrendTime, IObscurationRemark, IPrecipitationAmount24HourRemark, IPrecipitationAmount36HourRemark, IPrecipitationBegEndRemark, IPrevailingVisibilityRemark, IRunwayInfo, ISeaLevelPressureRemark, ISecondLocationVisibilityRemark, ISectorVisibilityRemark, ISmallHailSizeRemark, ISnowIncreaseRemark, ISnowPelletsRemark, ISunshineDurationRemark, ISurfaceVisibilityRemark, ITAF, ITAFDated, ITemperatureDated, IThunderStormLocationMovingRemark, IThunderStormLocationRemark, ITime, ITornadicActivityBegEndRemark, ITornadicActivityBegRemark, ITornadicActivityEndRemark, ITowerVisibilityRemark, IUnknownRemark, IValidity, IValidityDated, IVariableSkyHeightRemark, IVariableSkyRemark, IVirgaDirectionRemark, IWaterEquivalentSnowRemark, IWeatherCondition, IWind, IWindPeakCommandRemark, IWindShear, IWindShiftFropaRemark, Intensity, InvalidWeatherStatementError, Locale, ParseError, Phenomenon, Remark, RemarkType, RunwayInfoTrend, RunwayInfoUnit, TAFTrend, TAFTrendDated, TimeIndicator, TimestampOutOfBoundsError, UnexpectedParseError, ValueIndicator, Visibility, WeatherChangeType, getCompositeForecastForDate, isWeatherConditionValid, parseMetar, parseTAF, parseTAFAsForecast };
+export { CloudQuantity, CloudType, CommandExecutionError, Descriptive, Direction, Distance, DistanceUnit, Forecast, IAbstractTrend, IAbstractValidity, IAbstractWeatherCode, IAbstractWeatherCodeDated, IAbstractWeatherContainer, IAirport, IBaseRemark, IBaseTAFTrend, ICeilingHeightRemark, ICeilingSecondLocationRemark, ICloud, ICompositeForecast, ICountry, IEndValidity, IFMValidity, IFlags, IForecastContainer, IHourlyMaximumMinimumTemperatureRemark, IHourlyMaximumTemperatureRemark, IHourlyMinimumTemperatureRemark, IHourlyPrecipitationAmountRemark, IHourlyPressureRemark, IHourlyTemperatureDewPointRemark, IIceAccretionRemark, IMetar, IMetarTAFParserOptions, IMetarTAFParserOptionsDated, IMetarTrend, IMetarTrendTime, IObscurationRemark, IPrecipitationAmount24HourRemark, IPrecipitationAmount36HourRemark, IPrecipitationBegEndRemark, IPrevailingVisibilityRemark, IRunwayInfo, ISeaLevelPressureRemark, ISecondLocationVisibilityRemark, ISectorVisibilityRemark, ISmallHailSizeRemark, ISnowIncreaseRemark, ISnowPelletsRemark, ISunshineDurationRemark, ISurfaceVisibilityRemark, ITAF, ITAFDated, ITemperature, ITemperatureDated, IThunderStormLocationMovingRemark, IThunderStormLocationRemark, ITime, ITornadicActivityBegEndRemark, ITornadicActivityBegRemark, ITornadicActivityEndRemark, ITowerVisibilityRemark, IUnknownRemark, IValidity, IValidityDated, IVariableSkyHeightRemark, IVariableSkyRemark, IVirgaDirectionRemark, IWaterEquivalentSnowRemark, IWeatherCondition, IWind, IWindPeakCommandRemark, IWindShear, IWindShiftFropaRemark, Intensity, InvalidWeatherStatementError, Locale, ParseError, Phenomenon, Remark, RemarkType, RunwayInfoTrend, RunwayInfoUnit, TAFTrend, TAFTrendDated, TimeIndicator, TimestampOutOfBoundsError, UnexpectedParseError, ValueIndicator, Visibility, WeatherChangeType, getCompositeForecastForDate, isWeatherConditionValid, parseMetar, parseTAF, parseTAFAsForecast };

package/metar-taf-parser.js

@@ -2304,6 +2304,7 @@ class MetarParser extends AbstractParser {
                         clouds: [],
                         times: [],
                         remarks: [],
+                        raw: input,
                     };
                     index = this.parseTrend(index, trend, metarTab);
                     metar.trends.push(trend);
@@ -2369,6 +2370,7 @@ class TAFParser extends AbstractParser {
             remarks: [],
             clouds: [],
             weatherConditions: [],
+            initialRaw: lines[0].join(" "),
         };
         for (let i = index + 1; i < lines[0].length; i++) {
             const token = lines[0][i];
@@ -2435,6 +2437,7 @@ class TAFParser extends AbstractParser {
                 ...this.makeEmptyTAFTrend(),
                 type: WeatherChangeType.FM,
                 validity: parseFromValidity(lineTokens[0]),
+                raw: lineTokens.join(" "),
             };
         }
         else if (lineTokens[0].startsWith(this.PROB)) {
@@ -2445,12 +2448,14 @@ class TAFParser extends AbstractParser {
                 ...this.makeEmptyTAFTrend(),
                 type: WeatherChangeType.PROB,
                 validity,
+                raw: lineTokens.join(" "),
             };
             if (lineTokens.length > 1 && lineTokens[1] === this.TEMPO) {
                 trend = {
                     ...this.makeEmptyTAFTrend(),
                     type: WeatherChangeType[lineTokens[1]],
                     validity,
+                    raw: lineTokens.join(" "),
                 };
                 index = 2;
             }
@@ -2464,6 +2469,7 @@ class TAFParser extends AbstractParser {
                 ...this.makeEmptyTAFTrend(),
                 type: WeatherChangeType[lineTokens[0]],
                 validity,
+                raw: lineTokens.join(" "),
             };
         }
         this.parseTrend(index, lineTokens, trend);
@@ -2609,6 +2615,18 @@ function tafDatesHydrator(report, date) {
             start: getReportDate(issued, report.validity.startDay, report.validity.startHour),
             end: getReportDate(issued, report.validity.endDay, report.validity.endHour),
         },
+        minTemperature: report.minTemperature
+            ? {
+                ...report.minTemperature,
+                date: getReportDate(issued, report.minTemperature.day, report.minTemperature.hour),
+            }
+            : undefined,
+        maxTemperature: report.maxTemperature
+            ? {
+                ...report.maxTemperature,
+                date: getReportDate(issued, report.maxTemperature.day, report.maxTemperature.hour),
+            }
+            : undefined,
         trends: report.trends.map((trend) => ({
             ...trend,
             validity: (() => {
@@ -2632,12 +2650,10 @@ function tafDatesHydrator(report, date) {
 
 function getForecastFromTAF(taf) {
     return {
-        issued: taf.issued,
-        station: taf.station,
-        message: taf.message,
+        ...taf,
         start: getReportDate(taf.issued, taf.validity.startDay, taf.validity.startHour),
         end: getReportDate(taf.issued, taf.validity.endDay, taf.validity.endHour),
-        forecast: [makeInitialForecast(taf), ...taf.trends],
+        forecast: hydrateEndDates([makeInitialForecast(taf), ...taf.trends], taf.validity),
     };
 }
 /**
@@ -2654,6 +2670,7 @@ function makeInitialForecast(taf) {
         remarks: taf.remarks,
         clouds: taf.clouds,
         weatherConditions: taf.weatherConditions,
+        raw: taf.initialRaw,
         validity: {
             // End day/hour are for end of the entire TAF
             startDay: taf.validity.startDay,
@@ -2663,6 +2680,80 @@ function makeInitialForecast(taf) {
         },
     };
 }
+function hasImplicitEnd({ type }) {
+    return (type === WeatherChangeType.FM ||
+        // BECMG are special - the "end" date in the validity isn't actually
+        // the end date, it's when the change that's "becoming" is expected to
+        // finish transition. The actual "end" date of the BECMG is determined by
+        // the next FM/BECMG/end of the report validity, just like a FM
+        type === WeatherChangeType.BECMG ||
+        // Special case for beginning of report conditions
+        type === undefined);
+}
+function hydrateEndDates(trends, reportValidity) {
+    function findNext(index) {
+        for (let i = index; i < trends.length; i++) {
+            if (hasImplicitEnd(trends[i]))
+                return trends[i];
+        }
+    }
+    const forecasts = [];
+    let previouslyHydratedTrend;
+    for (let i = 0; i < trends.length; i++) {
+        const currentTrend = trends[i];
+        const nextTrend = findNext(i + 1);
+        if (!hasImplicitEnd(currentTrend)) {
+            forecasts.push({
+                ...currentTrend,
+                start: currentTrend.validity.start,
+                // Has a type and not a FM/BECMG/undefined, so always has an end
+                end: currentTrend.validity.end,
+            });
+            continue;
+        }
+        let forecast;
+        if (nextTrend === undefined) {
+            forecast = hydrateWithPreviousContextIfNeeded({
+                ...currentTrend,
+                start: currentTrend.validity.start,
+                end: reportValidity.end,
+                ...byIfNeeded(currentTrend),
+            }, previouslyHydratedTrend);
+        }
+        else {
+            forecast = hydrateWithPreviousContextIfNeeded({
+                ...currentTrend,
+                start: currentTrend.validity.start,
+                end: new Date(nextTrend.validity.start),
+                ...byIfNeeded(currentTrend),
+            }, previouslyHydratedTrend);
+        }
+        forecasts.push(forecast);
+        previouslyHydratedTrend = forecast;
+    }
+    return forecasts;
+}
+/**
+ * BECMG doesn't always have all the context for the period, so
+ * it needs to be populated
+ */
+function hydrateWithPreviousContextIfNeeded(forecast, context) {
+    if (forecast.type !== WeatherChangeType.BECMG || !context)
+        return forecast;
+    // Remarks should not be carried over
+    context = { ...context };
+    delete context.remark;
+    context.remarks = [];
+    forecast = {
+        ...context,
+        ...forecast,
+    };
+    if (!forecast.clouds.length)
+        forecast.clouds = context.clouds;
+    if (!forecast.weatherConditions.length)
+        forecast.weatherConditions = context.weatherConditions;
+    return forecast;
+}
 class TimestampOutOfBoundsError extends ParseError {
     constructor(message) {
         super(message);
@@ -2678,15 +2769,16 @@ function getCompositeForecastForDate(date, forecastContainer) {
     let base;
     let additional = [];
     for (const forecast of forecastContainer.forecast) {
-        if (!forecast.validity.end &&
-            forecast.validity.start.getTime() <= date.getTime()) {
+        if (hasImplicitEnd(forecast) &&
+            forecast.start.getTime() <= date.getTime()) {
             // Is FM or initial forecast
             base = forecast;
         }
-        if (forecast.validity.end &&
-            forecast.validity.end.getTime() - date.getTime() > 0 &&
-            forecast.validity.start.getTime() - date.getTime() <= 0) {
-            // Is BECMG or TEMPO
+        if (!hasImplicitEnd(forecast) &&
+            forecast.end &&
+            forecast.end.getTime() - date.getTime() > 0 &&
+            forecast.start.getTime() - date.getTime() <= 0) {
+            // Is TEMPO, BECMG etc
             additional.push(forecast);
         }
     }
@@ -2694,6 +2786,11 @@ function getCompositeForecastForDate(date, forecastContainer) {
         throw new UnexpectedParseError("Unable to find trend for date");
     return { base, additional };
 }
+function byIfNeeded(forecast) {
+    if (forecast.type !== WeatherChangeType.BECMG)
+        return {};
+    return { by: forecast.validity.end };
+}
 
 function parseMetar(rawMetar, options) {
     return parse(rawMetar, options, MetarParser, metarDatesHydrator);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "metar-taf-parser",
-  "version": "5.0.0",
+  "version": "6.0.0",
   "description": "Parse METAR and TAF reports",
   "homepage": "https://aeharding.github.io/metar-taf-parser",
   "keywords": [