@squawk/airways
[](../../../LICENSE.md) [](https://www.npmjs.com/package/@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](https://www.npmjs.com/org/squawk) aviation library suite. See all packages on npm.
## Usage
```typescript
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:
```typescript
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`:
```typescript
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\ | 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
```typescript
const results = resolver.search({ text: 'V1', limit: 10 });
for (const { airway, score } of results) {
console.log(airway.designation, score);
}
```