@squawk/fixes

Pure logic library for querying US fix/waypoint data. Look up fixes by identifier, geographic proximity, or fuzzy identifier search. Contains no bundled data - accepts an array of Fix records at initialization. For zero-config use, pair with @squawk/fix-data.

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

Usage

import { usBundledFixes } from '@squawk/fix-data';
import { createFixResolver } from '@squawk/fixes';

const resolver = createFixResolver({ data: usBundledFixes.records });

// Look up by identifier
const merit = resolver.byIdent('MERIT');

// Find nearest fixes to a position
const nearby = resolver.nearest({ lat: 40.6413, lon: -73.7781 });
for (const result of nearby) {
  console.log(result.fix.identifier, result.distanceNm, 'nm');
}

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

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

import { createFixResolver } from '@squawk/fixes';

const resolver = createFixResolver({ data: myFixes });
Copy

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/fix-data/browser:

import { loadUsBundledFixes } from '@squawk/fix-data/browser';
import { createFixResolver } from '@squawk/fixes/browser';

const dataset = await loadUsBundledFixes();
const resolver = createFixResolver({ data: dataset.records });
Copy

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

createFixResolver(options)

Creates a resolver object from an array of Fix records.

Parameters:

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

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

resolver.byIdent(ident)

Looks up fixes by identifier (e.g. "MERIT", "BOSCO"). Multiple fixes can share the same identifier in different ICAO regions. Case-insensitive. Returns Fix[].

resolver.byIdentAtPosition(ident, lat, lon, toleranceNm?)

Looks up the single fix sharing the given identifier that lies nearest to a geographic position. The same fix identifier can be published in more than one ICAO region; this disambiguates the collision by proximity to a known point such as a map-click location or an adjacent route waypoint.

Returns the nearest matching Fix by great-circle distance, or undefined when no fix carries the identifier or none fall within toleranceNm.

// Disambiguate a shared identifier against an adjacent route waypoint
const fix = resolver.byIdentAtPosition('BOSCO', 40.64, -73.78);
Copy

resolver.nearest(query)

Finds fixes nearest to a geographic position, sorted by distance ascending.

Returns NearestFixResult[], each containing:

• fix - the matched Fix record
• distanceNm - great-circle distance in nautical miles (rounded to 2 decimal places)

// Find the 5 nearest waypoints within 50 nm
const nearby = resolver.nearest({
  lat: 40.6413,
  lon: -73.7781,
  maxDistanceNm: 50,
  limit: 5,
  useCodes: new Set(['WP']),
});
Copy

resolver.search(query)

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

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

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

const results = resolver.search({ text: 'BOS', limit: 10 });
for (const { fix, score } of results) {
  console.log(fix.identifier, score);
}
Copy