@aeroswarm/weather 0.1.5 → 0.2.0

package/README.md

@@ -46,3 +46,50 @@ temperature) for any model source. `parseWeatherGridSeries`, `serializeWeatherGr
 `seriesFieldsAt`, and the Open-Meteo adapter (`latticePoints`, `weatherGridFromOpenMeteo`) are in the
 package; the network call stays in the app.
 
+## Tokens that are understood
+
+Checked against 2,400 real METAR/SPECI and 212 real TAF from 100+ airports (see `test/fixtures/README.md`).
+Every token of that corpus is either read or recognised as a group the model does not use; the one
+exception is a typo in the source (`VEB03KT`), which stays visible in `unparsed`.
+
+| Group | Read into the model | Recognised, not modelled |
+|---|---|---|
+| Wind | `dddffKT`, `dddffGggKT`, `dddffMPS`, `VRB`, variable range `dddVddd` (also glued to the wind group) | |
+| Visibility | metres (`9999`, `0750`), statute miles (`10SM`, `1/2SM`, `1 1/2SM`, `P6SM`), `CAVOK` | directional lowest visibility (`0500NE`) |
+| RVR | `R06R/0600N`, `R28/P2000`, `R35L/1200V1400FT` (metres or feet, trend, variable) in `conditions.rvr` | runway state (`R06C/CLRD62`, `R88/090065`) |
+| Weather | intensity, descriptor and phenomena (`+TSRA`, `VCTS`, `FZFG`, `BCFG`...), `NSW` | recent weather (`RERA`, `RETS`) |
+| Cloud | `FEW/SCT/BKN/OVC` with `CB/TCU`, `VV`, `SKC/CLR/NSC/NCD` | |
+| Temperature, pressure | `tt/dd` (also `M`), `Qpppp`, `Appp` (inHg to hPa) | |
+| Flags, trend | `AUTO`, `COR`, `NOSIG`, `BECMG`, `TEMPO`; everything after `RMK` is ignored | `//` (missing group), wind shear (`WS020/14030KT`, `WS R10`, `WS ALL RWY`) |
+| TAF | `AMD`, `COR`, `CNL`, `FMddhhmm`, `BECMG`, `TEMPO`, `PROBnn [TEMPO]`, `TX/TN` | remarks |
+
+A token that is none of these ends up in `Metar.unparsed` / `TafPeriod.unparsed` instead of silently
+disappearing. A report with an impossible date (for example `0000/0000`) is rejected (`null`), not
+guessed. A fuzz test mutates real reports (truncated, tokens removed, inserted, swapped) and requires
+that the parser never throws and never returns invalid numbers or dates.
+
+Not supported: the US domestic SIGMET formats (convective SIGMET, `AREA EMBD TS ...` with VOR-radial
+points), graphical G-AIRMET, and ICAO Annex 3 trend groups with `FM`/`TL`/`AT` times inside a METAR
+trend.
+
+
+
+## Warnings and special messages
+
+`decodeWeatherMessage` and `extractReports` also recognise these, and tell them apart by `kind`:
+
+| Kind | Reader | What is read | Verified against |
+|---|---|---|---|
+| `NIL` | `parseNil` | `METAR/SPECI/TAF [COR/AMD] ICAO [ddhhmmZ] NIL` | ICAO template only (no real NIL in the corpus) |
+| `SIGMET`, `AIRMET` | `parseSigmet` | FIR, series, validity, MWO, hazard (thunderstorm, turbulence, icing, mountain wave, volcanic ash, tropical cyclone, dust/sand storm, radioactive cloud, surface wind/visibility/cloud, cancellation), observed or forecast time, area (polygon, line with side, circle, latitude/longitude line, corridor, entire FIR, several areas), levels, movement, trend, volcano and cyclone names with positions, forecast position | 124 real SIGMET (aviationweather.gov); AIRMET only against the Annex 3 template |
+| `VAA` | `parseVaa` | VAAC, issue time, volcano and number, position, summit elevation, advisory number, colour code, eruption details, observed/estimated ash cloud, +6/+12/+18 h forecasts (layers with boundary points, movement, wind at the vent level), remarks, next advisory | 60 real advisories (Tokyo VAAC, JMA) |
+| `SNOWTAM` | `parseSnowtam` | lettered format A) to T): aerodrome, assessment time, every runway (cleared length and width, deposits and depth per third, friction), next observation, remarks. The global reporting format: head only (aerodrome, time), the rest in `unparsed` | Annex 15 items only (no real message) |
+
+Anything in these messages that is not understood is returned in `unparsed`, not dropped.
+A message whose header cannot be read returns `null`. The store counts these messages as `other`
+and does not keep them (they are not weather conditions at a station).
+
+Honest limits: AIRMET, NIL and SNOWTAM were written from the ICAO specification because no real
+messages could be collected (aviationweather.gov does not publish them; the Bureau of Meteorology
+blocks automated access, so Darwin VAAC advisories were not collected). Treat those three as
+specification-checked, not field-proven, until real samples are added to `test/fixtures`.

package/dist/aftn.d.ts

@@ -1,13 +1,13 @@
 import type { ReportKind } from "./types.js";
 export interface RawReport {
     kind: ReportKind;
-    /** Teks laporan dari kata kunci (METAR/SPECI/TAF) sampai sebelum `=`, spasi dirapikan. */
+    /** Teks laporan dari kata kunci sampai sebelum laporan berikutnya, spasi dirapikan. */
     text: string;
 }
 /**
- * Ambil laporan cuaca dari teks mentah: boleh berupa laporan polos, buletin dengan header
- * (`SAID31 WARR 021030`), atau pesan AFTN lengkap (`ZCZC ... NNNN` dengan baris alamat). Satu pesan
- * bisa memuat beberapa laporan yang masing-masing diakhiri `=`.
+ * Ambil laporan dari teks mentah: boleh berupa laporan polos, buletin dengan header
+ * (`SAID31 WARR 021030`), atau pesan AFTN lengkap (`ZCZC ... NNNN` dengan baris alamat). Banyak laporan
+ * dalam satu pesan dipisah per kata kunci, dengan atau tanpa tanda `=`.
  */
 export declare function extractReports(message: string): RawReport[];
 //# sourceMappingURL=aftn.d.ts.map

package/dist/aftn.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"aftn.d.ts","sourceRoot":"","sources":["../src/aftn.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,UAAU,CAAC;IACjB,0FAA0F;IAC1F,IAAI,EAAE,MAAM,CAAC;CACd;AAID;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,EAAE,CAe3D"}
+{"version":3,"file":"aftn.d.ts","sourceRoot":"","sources":["../src/aftn.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,UAAU,CAAC;IACjB,uFAAuF;IACvF,IAAI,EAAE,MAAM,CAAC;CACd;AAYD;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,EAAE,CAwB3D"}

package/dist/conditions.d.ts

@@ -1,4 +1,4 @@
-import type { CloudLayer, Conditions, PresentWeather, Wind } from "./types.js";
+import type { CloudLayer, Conditions, PresentWeather, Rvr, Wind } from "./types.js";
 export declare function emptyConditions(): Conditions;
 export interface ConditionTokens {
     wind?: Wind;
@@ -6,6 +6,7 @@ export interface ConditionTokens {
     cavok?: boolean;
     clouds?: CloudLayer[];
     weather?: PresentWeather[];
+    rvr?: Rvr[];
     noSignificantWeather?: boolean;
     /** Token yang tidak dikenali (diteruskan ke pemanggil, mis. suhu atau QNH). */
     rest: string[];

package/dist/conditions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"conditions.d.ts","sourceRoot":"","sources":["../src/conditions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAEV,UAAU,EACV,UAAU,EACV,cAAc,EACd,IAAI,EAEL,MAAM,YAAY,CAAC;AAYpB,wBAAgB,eAAe,IAAI,UAAU,CAa5C;AAgCD,MAAM,WAAW,eAAe;IAC9B,IAAI,CAAC,EAAE,IAAI,CAAC;IACZ,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,MAAM,CAAC,EAAE,UAAU,EAAE,CAAC;IACtB,OAAO,CAAC,EAAE,cAAc,EAAE,CAAC;IAC3B,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,+EAA+E;IAC/E,IAAI,EAAE,MAAM,EAAE,CAAC;CAChB;AAED,qFAAqF;AACrF,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,eAAe,CAkFtE;AAED,yFAAyF;AACzF,wBAAgB,eAAe,CAC7B,IAAI,EAAE,UAAU,EAChB,IAAI,EAAE,OAAO,CAAC,UAAU,CAAC,GAAG;IAAE,oBAAoB,CAAC,EAAE,OAAO,CAAA;CAAE,GAC7D,UAAU,CAqBZ"}
+{"version":3,"file":"conditions.d.ts","sourceRoot":"","sources":["../src/conditions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAEV,UAAU,EACV,UAAU,EACV,cAAc,EACd,GAAG,EACH,IAAI,EAEL,MAAM,YAAY,CAAC;AAgCpB,wBAAgB,eAAe,IAAI,UAAU,CAa5C;AAgCD,MAAM,WAAW,eAAe;IAC9B,IAAI,CAAC,EAAE,IAAI,CAAC;IACZ,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,MAAM,CAAC,EAAE,UAAU,EAAE,CAAC;IACtB,OAAO,CAAC,EAAE,cAAc,EAAE,CAAC;IAC3B,GAAG,CAAC,EAAE,GAAG,EAAE,CAAC;IACZ,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,+EAA+E;IAC/E,IAAI,EAAE,MAAM,EAAE,CAAC;CAChB;AAED,qFAAqF;AACrF,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,eAAe,CA+JtE;AAED,yFAAyF;AACzF,wBAAgB,eAAe,CAC7B,IAAI,EAAE,UAAU,EAChB,IAAI,EAAE,OAAO,CAAC,UAAU,CAAC,GAAG;IAAE,oBAAoB,CAAC,EAAE,OAAO,CAAA;CAAE,GAC7D,UAAU,CAsBZ"}

package/dist/geo.d.ts

@@ -0,0 +1,54 @@
+/** Posisi dan ketinggian pada pesan peringatan (SIGMET, AIRMET, VAA): murni, tanpa jaringan. */
+export interface GeoPosition {
+    lat: number;
+    lon: number;
+}
+export type Compass = "N" | "NNE" | "NE" | "ENE" | "E" | "ESE" | "SE" | "SSE" | "S" | "SSW" | "SW" | "WSW" | "W" | "WNW" | "NW" | "NNW";
+export declare const isCompass: (value: string) => value is Compass;
+/** Derajat dari utara untuk arah mata angin 16 titik. */
+export declare const compassDegrees: (direction: Compass) => number;
+/**
+ * Satu titik seperti `N1034 W07726` atau `S0200W07820`. Lintang `ddmm` (atau `dd`), bujur `dddmm` (atau
+ * `ddd`). Bujur empat angka (`W5815`, salah ketik yang ada pada laporan nyata) dibaca `ddmm`.
+ */
+export declare const POINT: string;
+export declare function parsePosition(text: string): GeoPosition | null;
+/** Semua titik dalam teks, berurutan. */
+export declare function parsePositions(text: string): GeoPosition[];
+/** Rentang ketinggian dalam kaki; `null` = tidak disebut, `0` = permukaan (SFC). */
+export interface AltitudeRange {
+    baseFt: number | null;
+    topFt: number | null;
+    /** `TOP ABV FL450`: puncaknya di atas nilai itu. */
+    topAbove?: boolean;
+}
+export declare const ALTITUDE_PATTERNS: {
+    /** `TOP FL490`, `TOP ABV FL450`, `TOP FL250/390`. */
+    readonly top: RegExp;
+    /** `FL240/300`, `SFC/FL100`, `SFC/6000FT`, `2000/4000FT`. */
+    readonly range: RegExp;
+    /** `ABV FL250` sendirian. */
+    readonly above: RegExp;
+};
+/**
+ * Cari satu petunjuk ketinggian dalam `text`. Mengembalikan rentangnya dan bagian teks yang dipakai,
+ * atau null.
+ */
+export declare function findAltitude(text: string): {
+    range: AltitudeRange;
+    matched: string;
+} | null;
+export interface Movement {
+    stationary: boolean;
+    direction?: Compass;
+    /** Kecepatan (kt); untuk rentang (`10-15KT`) nilai terbesar. */
+    speedKt?: number;
+    /** Batas bawah bila kecepatan dilaporkan sebagai rentang. */
+    speedMinKt?: number;
+}
+/** `MOV NW 10KT`, `MOV ENE`, `MOV E 25KMH`, `STNR`. */
+export declare function findMovement(text: string): {
+    movement: Movement;
+    matched: string;
+} | null;
+//# sourceMappingURL=geo.d.ts.map

package/dist/geo.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"geo.d.ts","sourceRoot":"","sources":["../src/geo.ts"],"names":[],"mappings":"AAAA,gGAAgG;AAEhG,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;CACb;AAED,MAAM,MAAM,OAAO,GACf,GAAG,GACH,KAAK,GACL,IAAI,GACJ,KAAK,GACL,GAAG,GACH,KAAK,GACL,IAAI,GACJ,KAAK,GACL,GAAG,GACH,KAAK,GACL,IAAI,GACJ,KAAK,GACL,GAAG,GACH,KAAK,GACL,IAAI,GACJ,KAAK,CAAC;AAqBV,eAAO,MAAM,SAAS,GAAI,OAAO,MAAM,KAAG,KAAK,IAAI,OAAmC,CAAC;AAEvF,yDAAyD;AACzD,eAAO,MAAM,cAAc,GAAI,WAAW,OAAO,KAAG,MAAoC,CAAC;AAEzF;;;GAGG;AACH,eAAO,MAAM,KAAK,QAAwC,CAAC;AAW3D,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI,CAU9D;AAED,yCAAyC;AACzC,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,EAAE,CAO1D;AAED,oFAAoF;AACpF,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,oDAAoD;IACpD,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAeD,eAAO,MAAM,iBAAiB;IAC5B,qDAAqD;;IAErD,6DAA6D;;IAE7D,6BAA6B;;CAErB,CAAC;AAEX;;;GAGG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG;IAAE,KAAK,EAAE,aAAa,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAsC3F;AAED,MAAM,WAAW,QAAQ;IACvB,UAAU,EAAE,OAAO,CAAC;IACpB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,gEAAgE;IAChE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,6DAA6D;IAC7D,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAID,uDAAuD;AACvD,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG;IAAE,QAAQ,EAAE,QAAQ,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAmBzF"}

package/dist/index.d.ts

@@ -2,16 +2,22 @@ import type { Report } from "./types.js";
 export * from "./aftn.js";
 export * from "./animation.js";
 export * from "./conditions.js";
+export * from "./geo.js";
 export * from "./grid.js";
 export * from "./gridSeries.js";
 export * from "./openMeteo.js";
 export * from "./metar.js";
+export * from "./nil.js";
+export * from "./sigmet.js";
+export * from "./snowtam.js";
 export * from "./taf.js";
 export * from "./store.js";
 export * from "./time.js";
 export * from "./types.js";
+export * from "./vaa.js";
 /**
- * Baca semua laporan cuaca (METAR, SPECI, TAF) dari satu pesan mentah, termasuk bungkus AFTN.
+ * Baca semua laporan cuaca dari satu pesan mentah, termasuk bungkus AFTN: METAR, SPECI, TAF, NIL,
+ * SIGMET, AIRMET, pemberitahuan abu vulkanik (VAA), dan SNOWTAM.
  * Laporan yang tidak terbaca dilewati. `reference` = waktu pesan diterima (menentukan bulan/tahun).
  */
 export declare function decodeWeatherMessage(message: string, reference?: Date): Report[];

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAEzC,cAAc,WAAW,CAAC;AAC1B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,iBAAiB,CAAC;AAChC,cAAc,WAAW,CAAC;AAC1B,cAAc,iBAAiB,CAAC;AAChC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,YAAY,CAAC;AAC3B,cAAc,UAAU,CAAC;AACzB,cAAc,YAAY,CAAC;AAC3B,cAAc,WAAW,CAAC;AAC1B,cAAc,YAAY,CAAC;AAE3B;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,MAAM,EACf,SAAS,GAAE,IAAiB,GAC3B,MAAM,EAAE,CAUV"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAEzC,cAAc,WAAW,CAAC;AAC1B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,iBAAiB,CAAC;AAChC,cAAc,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC;AAC1B,cAAc,iBAAiB,CAAC;AAChC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,YAAY,CAAC;AAC3B,cAAc,UAAU,CAAC;AACzB,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,UAAU,CAAC;AACzB,cAAc,YAAY,CAAC;AAC3B,cAAc,WAAW,CAAC;AAC1B,cAAc,YAAY,CAAC;AAC3B,cAAc,UAAU,CAAC;AAEzB;;;;GAIG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,MAAM,EACf,SAAS,GAAE,IAAiB,GAC3B,MAAM,EAAE,CA0BV"}