atmosx-nwws-parser 1.0.19 → 1.0.22

package/src/parsers/stanza.ts

@@ -0,0 +1,132 @@
+/*
+                                            _               _     __   __
+         /\  | |                           | |             (_)    \ \ / /
+        /  \ | |_ _ __ ___   ___  ___ _ __ | |__   ___ _ __ _  ___ \ V / 
+       / /\ \| __| "_ ` _ \ / _ \/ __| "_ \| "_ \ / _ \ "__| |/ __| > <  
+      / ____ \ |_| | | | | | (_) \__ \ |_) | | | |  __/ |  | | (__ / . \ 
+     /_/    \_\__|_| |_| |_|\___/|___/ .__/|_| |_|\___|_|  |_|\___/_/ \_\
+                                     | |                                 
+                                     |_|                                                                                                                
+    
+    Written by: KiyoWx (k3yomi)                
+*/
+
+
+import * as loader from '../bootstrap';
+import * as types from '../types';
+
+export class StanzaParser {
+
+    /**
+     * @function validate
+     * @description
+     *     Validates and parses a stanza message, extracting its attributes and metadata.
+     *     Handles both raw message strings (for debug/testing) and actual stanza objects.
+     *     Determines whether the message is a CAP alert, contains VTEC codes, or contains UGCs,
+     *     and identifies the AWIPS product type and prefix.
+     *
+     * @static
+     * @param {any} stanza
+     * @param {boolean | types.StanzaAttributes} [isDebug=false]
+     * @returns {{
+     *     message: string;
+     *     attributes: types.StanzaAttributes;
+     *     isCap: boolean,
+     *     isPVtec: boolean;
+     *     isCapDescription: boolean;
+     *     awipsType: Record<string, string>;
+     *     isApi: boolean;
+     *     ignore: boolean;
+     *     isUGC?: boolean;
+     * }}
+     */
+    public static validate(stanza: any, isDebug: boolean | types.StanzaAttributes = false): { message: string; attributes: types.StanzaAttributes; isCap: any; isPVtec: boolean; isCapDescription: any; awipsType: any; isApi: boolean; ignore: boolean; isUGC?: boolean; } {
+        if (isDebug !== false) { 
+            const vTypes = isDebug as types.StanzaAttributes;  
+            const message = stanza;
+            const attributes = vTypes;
+            const isCap = vTypes.isCap ?? message.includes(`<?xml`);
+            const isCapDescription = message.includes(`<areaDesc>`);
+            const isPVtec = message.match(loader.definitions.regular_expressions.pvtec) != null;
+            const isUGC = message.match(loader.definitions.regular_expressions.ugc1) != null;
+            const awipsType = this.getType(attributes);
+            return { message, attributes, isCap, isPVtec, isUGC, isCapDescription, awipsType: awipsType, isApi: false, ignore: false };
+        }
+        if (stanza.is(`message`)) {
+            let cb = stanza.getChild(`x`)
+            if (cb && cb.children) {
+                let message = unescape(cb.children[0])
+                let attributes = cb.attrs
+                if (attributes.awipsid && attributes.awipsid.length > 1) {
+                    const isCap = message.includes(`<?xml`);
+                    const isCapDescription = message.includes(`<areaDesc>`);
+                    const isPVtec = message.match(loader.definitions.regular_expressions.pvtec) != null;
+                    const isUGC = message.match(loader.definitions.regular_expressions.ugc1) != null;
+                    const awipsType = this.getType(attributes);
+                    this.cache(message, {attributes, isCap, isPVtec, awipsType });
+                    return { message, attributes, isCap, isPVtec, isUGC, isCapDescription, awipsType: awipsType, isApi: false, ignore: false  };
+                }
+            }
+        }
+        return { message: null, attributes: null, isApi: null, isCap: null, isPVtec: null, isUGC: null, isCapDescription: null, awipsType: null, ignore: true };
+    }
+
+    /**
+     * @function getType
+     * @description
+     *     Determines the AWIPS product type and prefix from a stanza's attributes.
+     *     Returns a default type of 'XX' if the attributes are missing or the AWIPS ID
+     *     does not match any known definitions.
+     *
+     * @private
+     * @static
+     * @param {unknown} attributes
+     * @returns {Record<string, string>}
+     */
+    private static getType(attributes: unknown): Record<string, string> {
+        const attrs = attributes as types.StanzaAttributesType | undefined;
+        if (!attrs?.awipsid) return { type: 'XX', prefix: 'XX' };
+        const awipsDefs = loader.definitions.awips;
+        for (const [prefix, type] of Object.entries(awipsDefs)) {
+            if (attrs.awipsid.startsWith(prefix)) {
+                return { type, prefix };
+            }
+        }
+        return { type: 'XX', prefix: 'XX' };
+    }
+
+    /**
+     * @function cache
+     * @description
+     *     Saves a compiled stanza message to the local cache directory.
+     *     Ensures the message contains "STANZA ATTRIBUTES..." metadata and timestamps,
+     *     and appends the formatted entry to both a category-specific file and a general cache file.
+     *
+     * @private
+     * @static
+     * @async
+     * @param {unknown} compiled
+     * @returns {Promise<void>}
+     */
+    private static async cache(message: string, compiled: unknown): Promise<void> {
+        if (!compiled) return;
+        const data = compiled as types.StanzaCompiled;
+        const settings = loader.settings as types.ClientSettingsTypes;
+        const { fs, path } = loader.packages;
+        if (!message || !settings.noaa_weather_wire_service_settings.cache.directory) return;
+        const cacheDir = settings.noaa_weather_wire_service_settings.cache.directory;
+        if (!fs.existsSync(cacheDir)) fs.mkdirSync(cacheDir, { recursive: true });
+        const prefix = `category-${data.awipsType.prefix}-${data.awipsType.type}s`;
+        const suffix = `${data.isCap ? 'cap' : 'raw'}${data.isPVtec ? '-vtec' : ''}`;
+        const categoryFile = path.join(cacheDir, `${prefix}-${suffix}.bin`);
+        const cacheFile = path.join(cacheDir, `cache-${suffix}.bin`);
+        const entry = `[SoF]\nSTANZA ATTRIBUTES...${JSON.stringify(compiled)}\n[EoF]\n${message}`;
+        await Promise.all([
+            fs.promises.appendFile(categoryFile, entry, 'utf8'),
+            fs.promises.appendFile(cacheFile, entry, 'utf8'),
+        ]);
+    }
+    
+}
+
+export default StanzaParser;

package/src/parsers/text.ts

@@ -0,0 +1,166 @@
+/*
+                                            _               _     __   __
+         /\  | |                           | |             (_)    \ \ / /
+        /  \ | |_ _ __ ___   ___  ___ _ __ | |__   ___ _ __ _  ___ \ V / 
+       / /\ \| __| "_ ` _ \ / _ \/ __| "_ \| "_ \ / _ \ "__| |/ __| > <  
+      / ____ \ |_| | | | | | (_) \__ \ |_) | | | |  __/ |  | | (__ / . \ 
+     /_/    \_\__|_| |_| |_|\___/|___/ .__/|_| |_|\___|_|  |_|\___/_/ \_\
+                                     | |                                 
+                                     |_|                                                                                                                
+    
+    Written by: KiyoWx (k3yomi)                
+*/
+
+import * as loader from '../bootstrap';
+
+export class TextParser {
+    
+    /**
+     * @function textProductToString
+     * @description
+     *     Searches a text product message for a line containing a specific value,
+     *     extracts the substring immediately following that value, and optionally
+     *     removes additional specified strings. Cleans up the extracted string by
+     *     trimming whitespace and removing any remaining occurrences of the search
+     *     value or '<' characters.
+     *
+     * @static
+     * @param {string} message
+     * @param {string} value
+     * @param {string[]} [removal=[]]
+     * @returns {string | null}
+     */
+    public static textProductToString(message: string,value: string,removal: string[] = []): string | null {
+        const lines = message.split('\n');
+        for (const line of lines) {
+            if (line.includes(value)) {
+                let result = line.slice(line.indexOf(value) + value.length).trim();
+                for (const str of removal) { result = result.split(str).join(''); }
+                result = result.replace(value, '').replace('<', '').trim();
+                return result || null;
+            }
+        }
+        return null;
+    }
+
+    /**
+     * @function textProductToPolygon
+     * @description
+     *     Parses a text product message to extract polygon coordinates based on
+     *     LAT...LON data. Coordinates are converted to [latitude, longitude] pairs
+     *     with longitude negated (assumes Western Hemisphere). If the polygon has
+     *     more than two points, the first point is repeated at the end to close it.
+     *
+     * @static
+     * @param {string} message
+     * @returns {[number, number][]}
+     */
+    public static textProductToPolygon(message: string): [number, number][] {
+        const coordinates: [number, number][] = [];
+        const latLonMatch = message.match(/LAT\.{3}LON\s+([\d\s]+)/i);
+        if (!latLonMatch || !latLonMatch[1]) return coordinates;
+        const coordStrings = latLonMatch[1].replace(/\n/g, ' ').trim().split(/\s+/);
+        for (let i = 0; i < coordStrings.length - 1; i += 2) {
+            const lat = parseFloat(coordStrings[i]) / 100;
+            const lon = -parseFloat(coordStrings[i + 1]) / 100;
+            if (!isNaN(lat) && !isNaN(lon)) { coordinates.push([lon, lat]); }
+        }
+        if (coordinates.length > 2) { coordinates.push(coordinates[0]); }
+        return coordinates;
+    }
+
+    /**
+     * @function textProductToDescription
+     * @description
+     *     Extracts a clean description portion from a text product message, optionally
+     *     removing a handle and any extra metadata such as "STANZA ATTRIBUTES...".
+     *     Also trims and normalizes whitespace.
+     *
+     * @static
+     * @param {string} message
+     * @param {string | null} [handle=null]
+     * @returns {string}
+     */
+    public static textProductToDescription(message: string, handle: string = null): string {
+        const original = message;
+        const discoveredDates = Array.from(message.matchAll(loader.definitions.regular_expressions.dateline));
+        if (discoveredDates.length) {
+            const lastMatch = discoveredDates[discoveredDates.length - 1][0];
+            const startIdx = message.lastIndexOf(lastMatch);
+            if (startIdx !== -1) {
+                const endIdx = message.indexOf('&&', startIdx);
+                message = message.substring(startIdx + lastMatch.length, endIdx !== -1 ? endIdx : undefined).trimStart();
+                if (message.startsWith('/')) message = message.slice(1).trimStart();
+                if (handle && message.includes(handle)) {
+                    const handleIdx = message.indexOf(handle);
+                    message = message.substring(handleIdx + handle.length).trimStart();
+                    if (message.startsWith('/')) message = message.slice(1).trimStart();
+                }
+            }
+        } else if (handle) {
+            const handleIdx = message.indexOf(handle);
+            if (handleIdx !== -1) {
+                let afterHandle = message.substring(handleIdx + handle.length).trimStart();
+                if (afterHandle.startsWith('/')) afterHandle = afterHandle.slice(1).trimStart();
+                const latEnd = afterHandle.indexOf('&&')
+                message = latEnd !== -1 ? afterHandle.substring(0, latEnd).trim() : afterHandle.trim();
+            }
+        }
+        return message.replace(/\s+/g, ' ').trim().startsWith('STANZA ATTRIBUTES...') ? original : message.split('STANZA ATTRIBUTES...')[0].trim();
+    }
+    
+    /**
+     * @function getXmlValues
+     * @description
+     *     Recursively extracts specified values from a parsed XML-like object.
+     *     Searches both object keys and array items for matching keys (case-insensitive)
+     *     and returns the corresponding values. If multiple unique values are found for
+     *     a key, an array is returned; if one value is found, it returns that value; 
+     *     if none are found, returns `null`.
+     *
+     * @static
+     * @param {any} parsed
+     * @param {string[]} valuesToExtract
+     * @returns {Record<string, string | string[] | null>}
+     */
+    public static getXmlValues(parsed: any, valuesToExtract: string[]): Record<string, string> {
+        const extracted: Record<string, any> = {};   
+        const findValueByKey = (obj: any, searchKey: string) => {
+            const results = [];
+            if (obj === null || typeof obj !== 'object') {
+                return results;
+            }
+            const searchKeyLower = searchKey.toLowerCase();
+            for (const key in obj) {
+                if (obj.hasOwnProperty(key) && key.toLowerCase() === searchKeyLower) {
+                    results.push(obj[key]);
+                }
+            }
+            if (Array.isArray(obj)) {
+                for (const item of obj) {
+                    if (item.valueName && item.valueName.toLowerCase() === searchKeyLower && item.value !== undefined) {
+                        results.push(item.value);
+                    }
+                    const nestedResults = findValueByKey(item, searchKey);
+                    results.push(...nestedResults);
+                }
+            }
+            for (const key in obj) {
+                if (obj.hasOwnProperty(key)) {
+                    const nestedResults = findValueByKey(obj[key], searchKey);
+                    results.push(...nestedResults);
+                }
+            }
+            return results;
+        };
+        for (const key of valuesToExtract) {
+            const values = findValueByKey(parsed.alert, key);
+            const uniqueValues = [...new Set(values)];
+            extracted[key] = uniqueValues.length === 0 ? null : (uniqueValues.length === 1 ? uniqueValues[0] : uniqueValues);
+        }
+        return extracted;
+    }
+    
+}
+
+export default TextParser;

package/src/parsers/ugc.ts

@@ -0,0 +1,197 @@
+/*
+                                            _               _     __   __
+         /\  | |                           | |             (_)    \ \ / /
+        /  \ | |_ _ __ ___   ___  ___ _ __ | |__   ___ _ __ _  ___ \ V / 
+       / /\ \| __| "_ ` _ \ / _ \/ __| "_ \| "_ \ / _ \ "__| |/ __| > <  
+      / ____ \ |_| | | | | | (_) \__ \ |_) | | | |  __/ |  | | (__ / . \ 
+     /_/    \_\__|_| |_| |_|\___/|___/ .__/|_| |_|\___|_|  |_|\___/_/ \_\
+                                     | |                                 
+                                     |_|                                                                                                                
+    
+    Written by: KiyoWx (k3yomi)                
+*/
+
+import * as loader from '../bootstrap';
+import * as types from '../types';
+
+
+export class UGCParser {
+    
+    /**
+     * @function ugcExtractor
+     * @description
+     *     Extracts UGC (Universal Geographic Code) information from a message.
+     *     This includes parsing the header, resolving zones, calculating the expiry
+     *     date, and retrieving associated location names from the database.
+     *
+     * @static
+     * @async
+     * @param {string} message
+     * @returns {Promise<types.UGCEntry | null>}
+     */
+    public static async ugcExtractor(message: string): Promise<types.UGCEntry | null> {
+        const header = this.getHeader(message);
+        if (!header) return null;
+        const zones = this.getZones(header);
+        if (zones.length === 0) return null;
+        const expiry = this.getExpiry(message);
+        const locations = await this.getLocations(zones);
+        return { 
+            zones: zones, 
+            locations: locations,
+            expiry: expiry
+        };
+    }
+
+    /**
+     * @function getHeader
+     * @description
+     *     Extracts the UGC header from a message by locating patterns defined in
+     *     `ugc1` and `ugc2` regular expressions. Removes all whitespace and the
+     *     trailing character from the matched header.
+     *
+     * @static
+     * @param {string} message
+     * @returns {string | null}
+     */
+    public static getHeader(message: string): string | null {
+        const start = message.search(loader.definitions.regular_expressions.ugc1);
+        const subMessage = message.substring(start);
+        const end = subMessage.search(loader.definitions.regular_expressions.ugc2);
+        const full = subMessage.substring(0, end).replace(/\s+/g, '').slice(0, -1);
+        return full || null;
+    }
+
+    /**
+     * @function getExpiry
+     * @description
+     *     Extracts an expiration date from a message using the UGC3 format.
+     *     The function parses day, hour, and minute from the message and constructs
+     *     a Date object in the current month and year. Returns `null` if no valid
+     *     expiration is found.
+     *
+     * @static
+     * @param {string} message
+     * @returns {Date | null}
+     */
+    public static getExpiry(message: string): Date | null {
+        const start = message.match(loader.definitions.regular_expressions.ugc3);
+        const day = parseInt(start[0].substring(0, 2), 10);
+        const hour = parseInt(start[0].substring(2, 4), 10);
+        const minute = parseInt(start[0].substring(4, 6), 10);
+        const now = new Date();
+        const expires = new Date(now.getUTCFullYear(), now.getUTCMonth(), day, hour, minute, 0);
+        return expires;
+    }
+
+    /**
+     * @function getLocations
+     * @description
+     *     Retrieves human-readable location names for an array of zone identifiers
+     *     from the shapefiles database. If a zone is not found, the zone ID itself
+     *     is returned. Duplicate locations are removed and the result is sorted.
+     *
+     * @static
+     * @async
+     * @param {string[]} zones
+     * @returns {Promise<string[]>}
+     */
+    public static async getLocations(zones: string[]): Promise<string[]> {
+        const uniqueZones = Array.from(new Set(zones.map(z => z.trim())));
+        const placeholders = uniqueZones.map(() => '?').join(',');
+        const rows = await loader.cache.db.prepare(
+            `SELECT id, location FROM shapefiles WHERE id IN (${placeholders})`
+        ).all(...uniqueZones);
+        const locationMap = new Map<string, string>();
+        for (const row of rows) { locationMap.set(row.id, row.location) }
+        const locations = uniqueZones.map(id => locationMap.get(id) ?? id);
+        return locations.sort();
+    }
+
+    /**
+     * @function getCoordinates
+     * @description
+     *     Retrieves geographic coordinates for an array of zone identifiers
+     *     from the shapefiles database. Returns the coordinates of the first
+     *     polygon found for any matching zone.
+     *
+     * @static
+     * @param {string[]} zones
+     * @returns {[number, number][]}
+     */
+    public static getCoordinates(zones: string[]): any | null {
+        const polygons: any[] = [];
+        for (const zone of zones.map(z => z.trim())) {
+            const row = loader.cache.db.prepare(`SELECT geometry FROM shapefiles WHERE id = ?`).get(zone);
+            if (row !== undefined) {
+                const geometry = JSON.parse(row.geometry);
+                if (geometry?.type === 'Polygon') {
+                    polygons.push({
+                        type: "Feature",
+                        geometry,
+                        properties: {}
+                    });
+                }
+            }
+        }
+        if (polygons.length === 0) return null;
+        let merged = polygons[0];
+        for (let i = 1; i < polygons.length; i++) {
+            merged = loader.packages.turf.union(merged, polygons[i]);
+        }
+        const outerRing = merged.geometry.type === "Polygon"
+            ? merged.geometry.coordinates[0]
+            : merged.geometry.coordinates[0][0];
+        const skip = loader.settings.global_settings.shapefile_skip;
+        const skippedRing = outerRing.filter((_: any, index: number) => index % skip === 0);
+        return [skippedRing]
+    }
+
+    /**
+     * @function getZones
+     * @description
+     *     Parses a UGC header string and returns an array of individual zone
+     *     identifiers. Handles ranges indicated with `>` and preserves the
+     *     state and format prefixes.
+     *
+     * @static
+     * @param {string} header
+     * @returns {string[]}
+     */
+    public static getZones(header: string): string[] {
+        const ugcSplit = header.split('-');
+        const zones: string[] = [];
+        let state = ugcSplit[0].substring(0, 2);
+        const format = ugcSplit[0].substring(2, 3);
+        for (const part of ugcSplit) {
+            if (/^[A-Z]/.test(part)) {
+                state = part.substring(0, 2);
+                if (part.includes('>')) {
+                    const [start, end] = part.split('>');
+                    const startNum = parseInt(start.substring(3), 10);
+                    const endNum = parseInt(end, 10);
+                    for (let j = startNum; j <= endNum; j++) {
+                        zones.push(`${state}${format}${j.toString().padStart(3, '0')}`);
+                    }
+                } else {
+                    zones.push(part);
+                }
+                continue;
+            }
+            if (part.includes('>')) {
+                const [start, end] = part.split('>');
+                const startNum = parseInt(start, 10);
+                const endNum = parseInt(end, 10);
+                for (let j = startNum; j <= endNum; j++) {
+                    zones.push(`${state}${format}${j.toString().padStart(3, '0')}`);
+                }
+            } else {
+                zones.push(`${state}${format}${part}`);
+            }
+        }
+        return zones.filter(item => item !== '');
+    }
+   
+}
+
+export default UGCParser;