@squawk
@squawk
TypeScript libraries for building aviation applications - airspace geometry, weather parsing, flight planning, aircraft registry lookup, and more.
Security Notice (2026-05-11): A mini-Shai-Hulud npm supply-chain attack affected some @squawk/* versions; malicious versions have been pulled and new installs are safe. If you have an older version pinned, check it against the affected-version list in the incident report.
Layout
The repo splits into three top-level directories:
apps/- runnable applications built on the squawk libraries. Currently Atlas, the official chart-first viewer.packages/libs/- the published@squawk/*libraries listed below.tools/- internal data-build pipelines that produce the bundled snapshots in the*-datalibraries.
Packages
| Package | Description |
|---|---|
@squawk/types |
Shared type definitions used across all packages |
@squawk/units |
Aviation-aware unit conversion and formatting utilities |
@squawk/geo |
Geospatial utilities: great-circle distance, bearing, midpoint, point-in-polygon |
@squawk/flight-math |
Aviation flight computer calculations (E6B wind triangle, altitude, airspeed) |
@squawk/search |
Domain-agnostic fuzzy string matching and ranked search scoring |
@squawk/icao-registry |
ICAO hex to N-number and aircraft info lookup with FAA parsing utilities |
@squawk/icao-registry-data |
Pre-processed FAA ReleasableAircraft snapshot for use with @squawk/icao-registry |
@squawk/airspace |
Point-in-airspace queries for Class B/C/D/E and Special Use Airspace |
@squawk/airspace-data |
Pre-processed FAA NASR airspace GeoJSON snapshot for use with @squawk/airspace |
@squawk/airports |
Airport queries by identifier, location, or fuzzy search |
@squawk/airport-data |
Pre-processed FAA NASR airport snapshot with runways, frequencies, and ILS data |
@squawk/navaids |
Navaid queries by identifier, frequency, type, location, or fuzzy search |
@squawk/navaid-data |
Pre-processed FAA NASR navaid snapshot for use with @squawk/navaids |
@squawk/fixes |
Fix/waypoint queries by identifier, location, or fuzzy search |
@squawk/fix-data |
Pre-processed FAA NASR fix/waypoint snapshot for use with @squawk/fixes |
@squawk/airways |
Airway lookup, traversal, and expansion by designation, fix, or search |
@squawk/airway-data |
Pre-processed FAA NASR airway snapshot for use with @squawk/airways |
@squawk/procedures |
Instrument procedure lookup and expansion for SIDs, STARs, and IAPs (CIFP) |
@squawk/procedure-data |
Pre-processed FAA CIFP procedure snapshot for use with @squawk/procedures |
@squawk/flightplan |
Flight plan route string parsing and resolution using composed resolvers |
@squawk/weather |
Parse raw aviation weather strings (METAR, SPECI, TAF, SIGMET, AIRMET, PIREP) |
@squawk/notams |
Parse raw ICAO-format and FAA domestic NOTAM strings into structured objects |
@squawk/mcp |
Model Context Protocol server exposing the squawk libraries as tools for LLMs |
Development
npm install
npm run build # build all packages
npm run test # run all tests
npm run lint # lint all packages
npm run docs # generate documentation
Tools
The tools/ directory contains the build pipelines that produce the data packages from raw FAA source files. They are not published to npm but are fully usable if you want to rebuild data from a newer FAA cycle or customize the pipeline. Most tools accept a NASR subscription .zip or extracted directory via --local and write their output to the corresponding data package. The ICAO registry tool parses the FAA ReleasableAircraft database; the procedure tool parses the FAA CIFP (ARINC 424) zip. See npm run build:data -- --help for the orchestrator that runs them all.
| Tool | Description |
|---|---|
build-airspace-data |
Processes FAA NASR shapefiles and AIXM XML into airspace GeoJSON |
build-icao-registry-data |
Processes FAA ReleasableAircraft into ICAO registry JSON |
build-airport-data |
Processes FAA NASR airport, runway, frequency, and ILS CSVs into JSON |
build-navaid-data |
Processes FAA NASR NAV_BASE.csv into navaid JSON |
build-fix-data |
Processes FAA NASR FIX CSVs into fix/waypoint JSON |
build-airway-data |
Processes FAA NASR AWY.txt and ATS.txt into airway JSON |
build-procedure-data |
Processes FAA CIFP into SID / STAR / IAP procedure JSON |