@squawk/airways

  @squawk/airways

Pure logic library for querying US airway data. Look up airways by designation, expand route segments between fixes, find airways through a specific fix, or fuzzy-search by designation. Contains no bundled data - accepts an array of Airway records at initialization. For zero-config use, pair with @squawk/airway-data.

Part of the @squawk aviation library suite. See all packages on npm.

Usage

import { usBundledAirways } from '@squawk/airway-data';
import { createAirwayResolver } from '@squawk/airways';

const resolver = createAirwayResolver({ data: usBundledAirways.records });

// Look up by designation
const v16 = resolver.byDesignation('V16');

// Expand an airway between two fixes
const segment = resolver.expand('J60', 'MERIT', 'MARTN');
if (segment) {
  for (const wp of segment.waypoints) {
    console.log(wp.identifier, wp.mea, 'ft MEA');
  }
}

// Find all airways through a fix
const throughBos = resolver.byFix('BOS');
for (const result of throughBos) {
  console.log(result.airway.designation);
}

// Fuzzy-search by designation (scored, best match first)
const results = resolver.search({ text: 'V1' });
console.log(results[0]?.airway.designation, results[0]?.score);

Consumers who have their own airway data can use this package standalone:

import { createAirwayResolver } from '@squawk/airways';

const resolver = createAirwayResolver({ data: myAirways });

Browser / SPA usage

The resolver factory has no Node-specific imports and ships an explicit /browser subpath for SPAs and edge runtimes. Pair it with @squawk/airway-data/browser:

import { loadUsBundledAirways } from '@squawk/airway-data/browser';
import { createAirwayResolver } from '@squawk/airways/browser';

const dataset = await loadUsBundledAirways();
const resolver = createAirwayResolver({ data: dataset.records });

The /browser entry is identical to the main entry; the separate subpath exists so browser support is an explicit, publint-verified part of the public API surface.

API

createAirwayResolver(options)

Creates a resolver object from an array of Airway records.

Parameters:

• options.data - an array of Airway objects (from @squawk/types)

Returns: AirwayResolver - an object with the lookup methods described below.

resolver.byDesignation(designation)

Looks up airways by designation (e.g. "V16", "J60", "Q1"). Multiple airways can share the same designation in different regions (e.g. V16 exists in both the contiguous US and Hawaii). Case-insensitive. Returns Airway[].

resolver.expand(designation, entryFix, exitFix)

Expands an airway between two fixes, returning the ordered sequence of waypoints from the entry fix to the exit fix (inclusive). This is the primary use case for flight plan route decoding - given a route string like MERIT J60 MARTN, expand J60 between MERIT and MARTN.

Airways can be traversed in either direction. When the entry fix appears after the exit fix in the stored waypoint order, the returned waypoints are reversed so they always run entry-to-exit.

Returns AirwayExpansionResult | undefined. Returns undefined if:

• The airway designation is not found
• Either fix is not on the airway

The result contains:

• airway - the full Airway record
• waypoints - the ordered slice of waypoints between the two fixes

resolver.byFix(ident)

Finds all airways that pass through a given fix or navaid identifier. Case-insensitive. Returns AirwayByFixResult[], each containing:

• airway - the Airway record
• waypointIndex - the index of the matching waypoint in the airway

resolver.search(query)

Fuzzy-searches airways by designation. Matching is case-insensitive and tolerant of prefixes, substrings, subsequences, and small typos. Results are scored and returned best-match first.

Property	Type	Description
text	string	Search text, matched fuzzily against each airway's designation
limit	number	Optional. Maximum number of results. Defaults to 20
types	ReadonlySet<AirwayType>	Optional. When provided, only these airway types are returned
minScore	number	Optional. Minimum match score (exclusive) in [0, 1] a result must reach. Defaults to 0

Returns AirwaySearchResult[], sorted by descending score, each containing:

• airway - the matched Airway record
• score - match strength in [0, 1], where 1 is an exact designation match
• matchedField - which field produced the best match: 'designation'
• ranges - matched character ranges within the best-matching field's text, for highlighting

const results = resolver.search({ text: 'V1', limit: 10 });
for (const { airway, score } of results) {
  console.log(airway.designation, score);
}