metar-taf-parser 6.1.4 → 7.0.0

package/README.md

@@ -101,11 +101,13 @@ 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 (type = `FM`, `BECMG`, or `undefined`) - and there will always be one.
+Provides all relevant weather conditions for a given timestamp. It returns an `ICompositeForecast` with a `prevailing` and `supplemental` component. The `prevailing` component is the prevailing 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 `PROB` and/or `TEMPO`)
+The `supplemental` property is an array of weather condition periods valid for the given timestamp (any `PROB`, `TEMPO` and/or `INTER`) - conditions that are ephemeral and/or lower probability.
 
-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`.
+You will still need to write some logic to determine what data to use - for example, if `supplemental[0].visibility` exists, you may want to use it over `prevailing.visibility`, or otherwise present it to the user.
+
+This function throws a `TimestampOutOfBoundsError` if the provided date is outside of the report validity period.
 
 #### Example
 

package/metar-taf-parser.d.ts

@@ -192,6 +192,12 @@ declare enum WeatherChangeType {
      *     visibility two in mist and haze between 0000Z and 0600Z.
      */
     TEMPO = "TEMPO",
+    /**
+     * For periods up to 30 minutes (`INTER` or intermittent).
+     *
+     * Otherwise, similar to `TEMPO`
+     */
+    INTER = "INTER",
     /**
      * Probability Forecast
      *
@@ -811,6 +817,9 @@ interface IPrevailingVisibilityRemark extends IBaseRemark {
 
 interface ISeaLevelPressureRemark extends IBaseRemark {
     type: RemarkType.SeaLevelPressure;
+    /**
+     * Sea level pressure, in hPa/millibars
+     */
     pressure: number;
 }
 
@@ -1211,7 +1220,7 @@ interface IBaseTAFTrend extends IAbstractTrend {
      *
      * - FM trends also have `startMinutes`. They **DO NOT** have an explicit end
      *   validity (it is implied by the following FM).
-     * - All others (PROB, TEMPO, BECMG) have `endDay` and `endHour`.
+     * - All others (PROB, TEMPO, BECMG, INTER) have `endDay` and `endHour`.
      *
      * All properties are allowed to be accessed (as optionals), but if you want
      * type guarantees, you can check the trend type. For example:
@@ -1224,6 +1233,7 @@ interface IBaseTAFTrend extends IAbstractTrend {
      *   case WeatherChangeType.PROB:
      *   case WeatherChangeType.BECMG:
      *   case WeatherChangeType.TEMPO:
+     *   case WeatherChangeType.INTER:
      *     // trend.validity now has endHour, endDay defined
      * }
      * ```
@@ -1343,17 +1353,16 @@ interface IForecastContainer extends IFlags {
 }
 interface ICompositeForecast {
     /**
-     * The base forecast (type is `FM` or initial group)
+     * Prevailing conditions: type is `FM`, `BECMG` or initial conditions (`undefined` type)
      */
-    base: Forecast;
+    prevailing: Forecast;
     /**
-     * Any forecast here should pre-empt the base forecast. These forecasts may
-     * have probabilities of occuring, be temporary, or otherwise notable
-     * precipitation events
+     * supplemental forecasts may have probabilities of occuring, be temporary,
+     * or otherwise notable change of conditions. They enhance the prevailing forecast.
      *
-     * `type` is (`BECMG`, `TEMPO` or `PROB`)
+     * `type` is (`TEMPO`, `INTER` or `PROB`)
      */
-    additional: Forecast[];
+    supplemental: Forecast[];
 }
 declare class TimestampOutOfBoundsError extends ParseError {
     name: string;

package/metar-taf-parser.js

@@ -384,6 +384,12 @@ var WeatherChangeType;
      *     visibility two in mist and haze between 0000Z and 0600Z.
      */
     WeatherChangeType["TEMPO"] = "TEMPO";
+    /**
+     * For periods up to 30 minutes (`INTER` or intermittent).
+     *
+     * Otherwise, similar to `TEMPO`
+     */
+    WeatherChangeType["INTER"] = "INTER";
     /**
      * Probability Forecast
      *
@@ -1797,7 +1803,6 @@ class MainVisibilityCommand {
         const distance = convertVisibility(matches[1]);
         if (!container.visibility)
             container.visibility = distance;
-        container.visibility = { ...container.visibility, ...distance };
         if (matches[2] === "NDV")
             container.visibility.ndv = true;
         return true;
@@ -2159,6 +2164,7 @@ class AbstractParser {
         this.locale = locale;
         this.FM = "FM";
         this.TEMPO = "TEMPO";
+        this.INTER = "INTER";
         this.BECMG = "BECMG";
         this.RMK = "RMK";
         // Safari does not currently support negative lookbehind
@@ -2263,6 +2269,7 @@ class MetarParser extends AbstractParser {
         let i = index + 1;
         while (i < trendParts.length &&
             trendParts[i] !== this.TEMPO &&
+            trendParts[i] !== this.INTER &&
             trendParts[i] !== this.BECMG) {
             if (trendParts[i].startsWith(this.FM) ||
                 trendParts[i].startsWith(this.TL) ||
@@ -2306,6 +2313,7 @@ class MetarParser extends AbstractParser {
                     metar.nosig = true;
                 }
                 else if (metarTab[index] === this.TEMPO ||
+                    metarTab[index] === this.INTER ||
                     metarTab[index] === this.BECMG) {
                     const startIndex = index;
                     const trend = {
@@ -2348,6 +2356,27 @@ class TAFParser extends AbstractParser {
         this.TN = "TN";
         _TAFParser_validityPattern.set(this, /^\d{4}\/\d{4}$/);
     }
+    /**
+     * TAF messages can be formatted poorly
+     *
+     * Attempt to handle those situations gracefully
+     */
+    parseMessageStart(input) {
+        let index = 0;
+        if (input[index] === this.TAF)
+            index += 1;
+        if (input[index + 1] === this.TAF)
+            index += 2;
+        const flags1 = findFlags(input[index]);
+        if (flags1)
+            index += 1;
+        if (input[index] === this.TAF)
+            index += 1;
+        const flags2 = findFlags(input[index]);
+        if (flags2)
+            index += 1;
+        return [index, { ...flags1, ...flags2 }];
+    }
     /**
      * the message to parse
      * @param input
@@ -2356,15 +2385,7 @@ class TAFParser extends AbstractParser {
      */
     parse(input) {
         const lines = this.extractLinesTokens(input);
-        let index = 0;
-        if (lines[0][0] === this.TAF)
-            index = 1;
-        if (lines[0][1] === this.TAF)
-            index = 2;
-        const flags = findFlags(lines[0][index]);
-        if (flags) {
-            index += 1;
-        }
+        let [index, flags] = this.parseMessageStart(lines[0]);
         const station = lines[0][index];
         index += 1;
         const time = parseDeliveryTime(lines[0][index]);
@@ -2428,12 +2449,12 @@ class TAFParser extends AbstractParser {
         const singleLine = tafCode.replace(/\n/g, " ");
         const cleanLine = singleLine.replace(/\s{2,}/g, " ");
         const lines = joinProbIfNeeded(cleanLine
-            .replace(/\s(?=PROB\d{2}\sTEMPO|TEMPO|BECMG|FM|PROB)/g, "\n")
+            .replace(/\s(?=PROB\d{2}\s(?=TEMPO|INTER)|TEMPO|INTER|BECMG|FM|PROB)/g, "\n")
             .split(/\n/));
         // TODO cleanup
         function joinProbIfNeeded(ls) {
             for (let i = 0; i < ls.length; i++) {
-                if (/^PROB\d{2}$/.test(ls[i]) && /^TEMPO/.test(ls[i + 1])) {
+                if (/^PROB\d{2}$/.test(ls[i]) && /^TEMPO|INTER/.test(ls[i + 1])) {
                     ls.splice(i, 2, `${ls[i]} ${ls[i + 1]}`);
                 }
             }
@@ -2468,7 +2489,8 @@ class TAFParser extends AbstractParser {
                 validity,
                 raw: lineTokens.join(" "),
             };
-            if (lineTokens.length > 1 && lineTokens[1] === this.TEMPO) {
+            if (lineTokens.length > 1 &&
+                (lineTokens[1] === this.TEMPO || lineTokens[1] === this.INTER)) {
                 trend = {
                     ...this.makeEmptyTAFTrend(),
                     type: WeatherChangeType[lineTokens[1]],
@@ -2667,8 +2689,9 @@ function tafDatesHydrator(report, date) {
 }
 
 function getForecastFromTAF(taf) {
+    const { trends, wind, visibility, verticalVisibility, windShear, cavok, remark, remarks, clouds, weatherConditions, initialRaw, validity, ...tafWithoutBaseProperties } = taf;
     return {
-        ...taf,
+        ...tafWithoutBaseProperties,
         start: getReportDate(taf.issued, taf.validity.startDay, taf.validity.startHour),
         end: getReportDate(taf.issued, taf.validity.endDay, taf.validity.endHour),
         forecast: hydrateEndDates([makeInitialForecast(taf), ...taf.trends], taf.validity),
@@ -2721,8 +2744,9 @@ function hydrateEndDates(trends, reportValidity) {
         const currentTrend = trends[i];
         const nextTrend = findNext(i + 1);
         if (!hasImplicitEnd(currentTrend)) {
+            const { validity, ...trend } = currentTrend;
             forecasts.push({
-                ...currentTrend,
+                ...trend,
                 start: currentTrend.validity.start,
                 // Has a type and not a FM/BECMG/undefined, so always has an end
                 end: currentTrend.validity.end,
@@ -2730,9 +2754,10 @@ function hydrateEndDates(trends, reportValidity) {
             continue;
         }
         let forecast;
+        const { validity, ...trendWithoutValidity } = currentTrend;
         if (nextTrend === undefined) {
             forecast = hydrateWithPreviousContextIfNeeded({
-                ...currentTrend,
+                ...trendWithoutValidity,
                 start: currentTrend.validity.start,
                 end: reportValidity.end,
                 ...byIfNeeded(currentTrend),
@@ -2740,7 +2765,7 @@ function hydrateEndDates(trends, reportValidity) {
         }
         else {
             forecast = hydrateWithPreviousContextIfNeeded({
-                ...currentTrend,
+                ...trendWithoutValidity,
                 start: currentTrend.validity.start,
                 end: new Date(nextTrend.validity.start),
                 ...byIfNeeded(currentTrend),
@@ -2762,12 +2787,16 @@ function hydrateWithPreviousContextIfNeeded(forecast, context) {
     context = { ...context };
     delete context.remark;
     context.remarks = [];
+    // vertical visibility should not be carried over, if clouds exist
+    if (forecast.clouds.length)
+        delete context.verticalVisibility;
     forecast = {
         ...context,
         ...forecast,
     };
-    if (!forecast.clouds.length)
+    if (!forecast.clouds.length) {
         forecast.clouds = context.clouds;
+    }
     if (!forecast.weatherConditions.length)
         forecast.weatherConditions = context.weatherConditions;
     return forecast;
@@ -2784,25 +2813,25 @@ function getCompositeForecastForDate(date, forecastContainer) {
     if (date.getTime() > forecastContainer.end.getTime() ||
         date.getTime() < forecastContainer.start.getTime())
         throw new TimestampOutOfBoundsError("Provided timestamp is outside the report validity period");
-    let base;
-    let additional = [];
+    let prevailing;
+    let supplemental = [];
     for (const forecast of forecastContainer.forecast) {
         if (hasImplicitEnd(forecast) &&
             forecast.start.getTime() <= date.getTime()) {
-            // Is FM or initial forecast
-            base = forecast;
+            // Is FM, BECMG or initial forecast
+            prevailing = forecast;
         }
         if (!hasImplicitEnd(forecast) &&
             forecast.end &&
             forecast.end.getTime() - date.getTime() > 0 &&
             forecast.start.getTime() - date.getTime() <= 0) {
-            // Is TEMPO, BECMG etc
-            additional.push(forecast);
+            // Is TEMPO, INTER, PROB etc
+            supplemental.push(forecast);
         }
     }
-    if (!base)
+    if (!prevailing)
         throw new UnexpectedParseError("Unable to find trend for date");
-    return { base, additional };
+    return { prevailing, supplemental };
 }
 function byIfNeeded(forecast) {
     if (forecast.type !== WeatherChangeType.BECMG)
@@ -2824,7 +2853,7 @@ function parse(rawReport, options, parser, datesHydrator) {
     const lang = options?.locale || en;
     try {
         const report = new parser(lang).parse(rawReport);
-        if (options && "issued" in options) {
+        if (options && "issued" in options && options.issued) {
             return datesHydrator(report, options.issued);
         }
         return report;

package/package.json

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