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