@squawk/fixes

  @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);

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

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

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

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 });

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.

Parameter	Type	Description
ident	string	Fix identifier (case-insensitive)
lat	number	Latitude of the reference position in decimal degrees (WGS84)
lon	number	Longitude of the reference position in decimal degrees (WGS84)
toleranceNm	number	Optional. Maximum great-circle distance in nautical miles. Omit to let the nearest match win regardless

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);

resolver.nearest(query)

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

Property	Type	Description
lat	number	Latitude in decimal degrees (WGS84)
lon	number	Longitude in decimal degrees (WGS84)
maxDistanceNm	number	Optional. Maximum distance in nautical miles. Defaults to 30
limit	number	Optional. Maximum number of results. Defaults to 10
useCodes	ReadonlySet<FixUseCode>	Optional. When provided, only fixes with these use codes are returned

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']),
});

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.

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

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);
}