@squawk/fixes 0.1.0

package/README.md

@@ -0,0 +1,94 @@
+# @squawk/fixes
+
+Pure logic library for querying US fix/waypoint data. Look up fixes by
+identifier, geographic proximity, or identifier search. Contains no bundled
+data - accepts an array of Fix records at initialization. For zero-config use,
+pair with `@squawk/fix-data`.
+
+## Usage
+
+```typescript
+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');
+}
+
+// Search by identifier
+const results = resolver.search({ text: 'BOS' });
+```
+
+Consumers who have their own fix data can use this package standalone:
+
+```typescript
+import { createFixResolver } from '@squawk/fixes';
+
+const resolver = createFixResolver({ data: myFixes });
+```
+
+## 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)
+
+```typescript
+// 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)`
+
+Searches fixes by identifier using case-insensitive substring matching.
+Results are returned in alphabetical order by identifier.
+
+| Property   | Type                     | Description                                                           |
+| ---------- | ------------------------ | --------------------------------------------------------------------- |
+| `text`     | string                   | Case-insensitive substring to match against fix 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 |
+
+Returns `Fix[]`.

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * @packageDocumentation
+ * Pure logic library for querying US fix/waypoint data.
+ */
+export { createFixResolver } from './resolver.js';
+export type { FixResolver, FixResolverOptions, NearestFixQuery, NearestFixResult, FixSearchQuery, } from './resolver.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAClD,YAAY,EACV,WAAW,EACX,kBAAkB,EAClB,eAAe,EACf,gBAAgB,EAChB,cAAc,GACf,MAAM,eAAe,CAAC"}

package/dist/index.js

@@ -0,0 +1,5 @@
+/**
+ * @packageDocumentation
+ * Pure logic library for querying US fix/waypoint data.
+ */
+export { createFixResolver } from './resolver.js';

package/dist/resolver.d.ts

@@ -0,0 +1,86 @@
+import type { Fix, FixUseCode } from '@squawk/types';
+/**
+ * Options for creating a fix resolver.
+ */
+export interface FixResolverOptions {
+    /** Array of Fix records to index for queries. */
+    data: Fix[];
+}
+/**
+ * A query to find fixes near a geographic position.
+ */
+export interface NearestFixQuery {
+    /** Latitude in decimal degrees (WGS84). */
+    lat: number;
+    /** Longitude in decimal degrees (WGS84). */
+    lon: number;
+    /** Maximum distance in nautical miles. Defaults to 30. */
+    maxDistanceNm?: number;
+    /** Maximum number of results to return. Defaults to 10. */
+    limit?: number;
+    /** Optional set of use codes to include. When omitted, all use codes are included. */
+    useCodes?: ReadonlySet<FixUseCode>;
+}
+/**
+ * A fix result with distance information from a nearest-fix query.
+ */
+export interface NearestFixResult {
+    /** The matched fix record. */
+    fix: Fix;
+    /** Distance in nautical miles from the query position. */
+    distanceNm: number;
+}
+/**
+ * Options for a text search query against fix identifiers.
+ */
+export interface FixSearchQuery {
+    /** Case-insensitive substring to match against fix identifier. */
+    text: string;
+    /** Maximum number of results to return. Defaults to 20. */
+    limit?: number;
+    /** Optional set of use codes to include. When omitted, all use codes are included. */
+    useCodes?: ReadonlySet<FixUseCode>;
+}
+/**
+ * A stateless resolver providing fix lookup methods.
+ */
+export interface FixResolver {
+    /**
+     * Looks up fixes by identifier (e.g. "MERIT", "BOSCO").
+     * Multiple fixes can share the same identifier in different ICAO regions.
+     * Returns an empty array if no match is found.
+     */
+    byIdent(ident: string): Fix[];
+    /**
+     * Finds fixes nearest to a geographic position, sorted by distance.
+     * Results are filtered by max distance and limited to the requested count.
+     */
+    nearest(query: NearestFixQuery): NearestFixResult[];
+    /**
+     * Searches fixes by identifier using case-insensitive substring matching.
+     * Results are returned in alphabetical order by identifier.
+     */
+    search(query: FixSearchQuery): Fix[];
+}
+/**
+ * Creates a stateless fix resolver. The resolver accepts an array of
+ * Fix records at initialization (typically from `@squawk/fix-data`)
+ * and returns an object with methods for looking up fixes by identifier,
+ * proximity, or identifier search.
+ *
+ * The resolver builds internal indexes at creation time for fast lookups
+ * by identifier. Proximity and text searches iterate over the full dataset.
+ *
+ * ```typescript
+ * import { usBundledFixes } from '@squawk/fix-data';
+ * import { createFixResolver } from '@squawk/fixes';
+ *
+ * const resolver = createFixResolver({ data: usBundledFixes.records });
+ *
+ * const merit = resolver.byIdent('MERIT');
+ * const nearby = resolver.nearest({ lat: 40.6413, lon: -73.7781 });
+ * const results = resolver.search({ text: 'BOS' });
+ * ```
+ */
+export declare function createFixResolver(options: FixResolverOptions): FixResolver;
+//# sourceMappingURL=resolver.d.ts.map

package/dist/resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolver.d.ts","sourceRoot":"","sources":["../src/resolver.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAKrD;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,iDAAiD;IACjD,IAAI,EAAE,GAAG,EAAE,CAAC;CACb;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,2CAA2C;IAC3C,GAAG,EAAE,MAAM,CAAC;IACZ,4CAA4C;IAC5C,GAAG,EAAE,MAAM,CAAC;IACZ,0DAA0D;IAC1D,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,2DAA2D;IAC3D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,sFAAsF;IACtF,QAAQ,CAAC,EAAE,WAAW,CAAC,UAAU,CAAC,CAAC;CACpC;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,8BAA8B;IAC9B,GAAG,EAAE,GAAG,CAAC;IACT,0DAA0D;IAC1D,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,kEAAkE;IAClE,IAAI,EAAE,MAAM,CAAC;IACb,2DAA2D;IAC3D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,sFAAsF;IACtF,QAAQ,CAAC,EAAE,WAAW,CAAC,UAAU,CAAC,CAAC;CACpC;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B;;;;OAIG;IACH,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,GAAG,EAAE,CAAC;IAE9B;;;OAGG;IACH,OAAO,CAAC,KAAK,EAAE,eAAe,GAAG,gBAAgB,EAAE,CAAC;IAEpD;;;OAGG;IACH,MAAM,CAAC,KAAK,EAAE,cAAc,GAAG,GAAG,EAAE,CAAC;CACtC;AAiBD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,kBAAkB,GAAG,WAAW,CAgE1E"}

package/dist/resolver.js

@@ -0,0 +1,86 @@
+import { distance } from '@squawk/units';
+const { greatCircleDistanceNm } = distance;
+/**
+ * Default maximum distance in nautical miles for nearest-fix queries.
+ */
+const DEFAULT_MAX_DISTANCE_NM = 30;
+/**
+ * Default maximum number of results for nearest-fix queries.
+ */
+const DEFAULT_NEAREST_LIMIT = 10;
+/**
+ * Default maximum number of results for text search queries.
+ */
+const DEFAULT_SEARCH_LIMIT = 20;
+/**
+ * Creates a stateless fix resolver. The resolver accepts an array of
+ * Fix records at initialization (typically from `@squawk/fix-data`)
+ * and returns an object with methods for looking up fixes by identifier,
+ * proximity, or identifier search.
+ *
+ * The resolver builds internal indexes at creation time for fast lookups
+ * by identifier. Proximity and text searches iterate over the full dataset.
+ *
+ * ```typescript
+ * import { usBundledFixes } from '@squawk/fix-data';
+ * import { createFixResolver } from '@squawk/fixes';
+ *
+ * const resolver = createFixResolver({ data: usBundledFixes.records });
+ *
+ * const merit = resolver.byIdent('MERIT');
+ * const nearby = resolver.nearest({ lat: 40.6413, lon: -73.7781 });
+ * const results = resolver.search({ text: 'BOS' });
+ * ```
+ */
+export function createFixResolver(options) {
+    const fixes = options.data;
+    const byIdentMap = new Map();
+    for (const fix of fixes) {
+        const key = fix.identifier.toUpperCase();
+        let arr = byIdentMap.get(key);
+        if (!arr) {
+            arr = [];
+            byIdentMap.set(key, arr);
+        }
+        arr.push(fix);
+    }
+    return {
+        byIdent(ident) {
+            return byIdentMap.get(ident.toUpperCase()) ?? [];
+        },
+        nearest(query) {
+            const maxDist = query.maxDistanceNm ?? DEFAULT_MAX_DISTANCE_NM;
+            const limit = query.limit ?? DEFAULT_NEAREST_LIMIT;
+            const results = [];
+            for (const fix of fixes) {
+                if (query.useCodes && !query.useCodes.has(fix.useCode)) {
+                    continue;
+                }
+                const dist = greatCircleDistanceNm(query.lat, query.lon, fix.lat, fix.lon);
+                if (dist <= maxDist) {
+                    results.push({ fix, distanceNm: Math.round(dist * 100) / 100 });
+                }
+            }
+            results.sort((a, b) => a.distanceNm - b.distanceNm);
+            return results.slice(0, limit);
+        },
+        search(query) {
+            const limit = query.limit ?? DEFAULT_SEARCH_LIMIT;
+            const needle = query.text.toUpperCase();
+            if (needle.length === 0) {
+                return [];
+            }
+            const results = [];
+            for (const fix of fixes) {
+                if (query.useCodes && !query.useCodes.has(fix.useCode)) {
+                    continue;
+                }
+                if (fix.identifier.toUpperCase().includes(needle)) {
+                    results.push(fix);
+                }
+            }
+            results.sort((a, b) => a.identifier.localeCompare(b.identifier));
+            return results.slice(0, limit);
+        },
+    };
+}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@squawk/fixes",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Fix/waypoint queries by identifier, location, or name search",
+  "author": "Neil Cochran",
+  "license": "MIT",
+  "homepage": "https://github.com/neilcochran/squawk",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/neilcochran/squawk.git",
+    "directory": "packages/fixes"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "typedocMain": "src/index.ts",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.spec.*"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "node --test 'dist/**/*.spec.js'",
+    "lint": "tsc --noEmit && eslint src"
+  },
+  "dependencies": {
+    "@squawk/types": "*",
+    "@squawk/units": "*"
+  },
+  "devDependencies": {
+    "@squawk/fix-data": "*",
+    "@types/node": "^25.5.2"
+  },
+  "keywords": [
+    "aviation",
+    "typescript",
+    "fix",
+    "waypoint",
+    "intersection",
+    "faa",
+    "nasr"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}