@squawk/airspace 0.8.6 → 0.9.0

package/README.md

@@ -3,8 +3,9 @@
 [![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](../../../LICENSE.md) [![npm](https://img.shields.io/npm/v/@squawk/airspace)](https://www.npmjs.com/package/@squawk/airspace) ![TypeScript](https://img.shields.io/badge/TypeScript-blue?logo=typescript&logoColor=white)
 
 Pure logic library for querying US airspace geometry. Given a position and altitude,
-returns all applicable airspace designations. Contains no bundled data - accepts a
-GeoJSON dataset at initialization. For zero-config use, pair with `@squawk/airspace-data`.
+returns all applicable airspace designations, or look up and fuzzy-search features by
+identifier and name. Contains no bundled data - accepts a GeoJSON dataset at
+initialization. For zero-config use, pair with `@squawk/airspace-data`.
 
 Part of the [@squawk](https://www.npmjs.com/org/squawk) aviation library suite. See all packages on npm.
 
@@ -40,6 +41,10 @@ const laxShells = resolver.byAirport('LAX');
 
 // Get every ARTCC center boundary (one feature per stratum)
 const ny = resolver.byArtcc('ZNY');
+
+// Fuzzy-search features by identifier and name (scored, best match first)
+const matches = resolver.search({ text: 'LAX' });
+console.log(matches[0]?.feature.identifier, matches[0]?.score);
 ```
 
 Consumers who have their own GeoJSON airspace data can use this package standalone:
@@ -82,6 +87,9 @@ returns a resolver object with the following methods:
 - `byIdentifier(identifier, options?)` - type-agnostic identifier lookup that
   spans both partitions in one call, with an optional `types` inclusion
   filter and `includeArtcc` toggle.
+- `search(AirspaceSearchQuery)` - fuzzy-searches features by identifier and
+  name, returning scored results best-match first with the matched field and
+  highlight ranges, optionally filtered by type.
 - `byCentroid({ lon, lat, toleranceDeg? })` - returns features whose polygon
   centroid lies within tolerance of the query coordinates. Useful for
   resolving features whose `identifier` is empty (some Class E5 surfaces),
@@ -130,8 +138,8 @@ Creates a resolver from a GeoJSON dataset.
 
 **Returns:** `AirspaceResolver` - an object exposing `query(AirspaceQuery)`,
 `byAirport(identifier, types?)`, `byArtcc(identifier, stratum?)`,
-`byIdentifier(identifier, options?)`, `byCentroid(query)`, `withinBbox(bbox)`,
-and `forEachIndexed(callback)` methods.
+`byIdentifier(identifier, options?)`, `search(query)`, `byCentroid(query)`,
+`withinBbox(bbox)`, and `forEachIndexed(callback)` methods.
 
 ### `AirspaceQuery`
 
@@ -259,6 +267,36 @@ resolver.forEachIndexed((feature, ring, boundingBox) => {
 });
 ```
 
+### `resolver.search(query)`
+
+Fuzzy-searches airspace features across identifier and name. 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 feature's identifier and name                  |
+| `limit`    | number                     | Optional. Maximum number of results. Defaults to 20                                      |
+| `types`    | ReadonlySet\<AirspaceType> | Optional. When provided, only features of these types are returned                       |
+| `minScore` | number                     | Optional. Minimum match score (exclusive) in `[0, 1]` a result must reach. Defaults to 0 |
+
+Returns `AirspaceSearchResult[]`, sorted by descending score, each containing:
+
+- `feature` - the matched `AirspaceFeature` record
+- `score` - match strength in `[0, 1]`, where 1 is an exact identifier or name match
+- `matchedField` - which field produced the best match: `'identifier'` or `'name'`
+- `ranges` - matched character ranges within the best-matching field's text, for highlighting
+
+Features with an empty identifier and name (some Class E5 surfaces) never match a
+non-empty query and are simply absent from results.
+
+```typescript
+const results = resolver.search({ text: 'LAX', limit: 10 });
+for (const { feature, score, matchedField } of results) {
+  console.log(feature.identifier, score, `(matched ${matchedField})`);
+}
+```
+
 ### ARTCC altitude bounds
 
 ARTCC features carry stratum-aligned floor/ceiling values for use with

package/dist/index.d.ts

@@ -2,6 +2,7 @@
  * @packageDocumentation
  * Pure logic library for point-in-airspace queries against US airspace polygons.
  */
+export type { MatchRange } from '@squawk/search';
 export { createAirspaceResolver } from './resolver.js';
-export type { AirspaceResolver, AirspaceResolverOptions, AirspaceQuery, AirspaceCentroidQuery, AirspaceByIdentifierOptions, } from './resolver.js';
+export type { AirspaceResolver, AirspaceResolverOptions, AirspaceQuery, AirspaceCentroidQuery, AirspaceByIdentifierOptions, AirspaceSearchField, AirspaceSearchQuery, AirspaceSearchResult, } from './resolver.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,sBAAsB,EAAE,MAAM,eAAe,CAAC;AACvD,YAAY,EACV,gBAAgB,EAChB,uBAAuB,EACvB,aAAa,EACb,qBAAqB,EACrB,2BAA2B,GAC5B,MAAM,eAAe,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,YAAY,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AACjD,OAAO,EAAE,sBAAsB,EAAE,MAAM,eAAe,CAAC;AACvD,YAAY,EACV,gBAAgB,EAChB,uBAAuB,EACvB,aAAa,EACb,qBAAqB,EACrB,2BAA2B,EAC3B,mBAAmB,EACnB,mBAAmB,EACnB,oBAAoB,GACrB,MAAM,eAAe,CAAC"}

package/dist/index.js

@@ -1,5 +1 @@
-/**
- * @packageDocumentation
- * Pure logic library for point-in-airspace queries against US airspace polygons.
- */
 export { createAirspaceResolver } from './resolver.js';

package/dist/resolver.d.ts

@@ -1,5 +1,6 @@
 import type { FeatureCollection } from 'geojson';
 import { type BoundingBox } from '@squawk/geo';
+import type { MatchRange } from '@squawk/search';
 import type { AirspaceFeature, AirspaceType, ArtccStratum } from '@squawk/types';
 /**
  * A query describing a geographic position and altitude to resolve
@@ -64,6 +65,36 @@ export interface AirspaceByIdentifierOptions {
      */
     includeArtcc?: boolean;
 }
+/**
+ * The searchable fields an airspace {@link AirspaceSearchResult} can match on.
+ */
+export type AirspaceSearchField = 'identifier' | 'name';
+/**
+ * Options for a fuzzy text search query against airspace identifiers and names.
+ */
+export interface AirspaceSearchQuery {
+    /** Search text, matched fuzzily and case-insensitively against each feature's identifier and name. */
+    text: string;
+    /** Maximum number of results to return. Defaults to 20. */
+    limit?: number;
+    /** Optional set of airspace types to include. When omitted, all types are included. */
+    types?: ReadonlySet<AirspaceType>;
+    /** Minimum match score (exclusive) in `[0, 1]` a result must reach. Defaults to 0, which keeps every match. Raise it to drop weak fuzzy matches. */
+    minScore?: number;
+}
+/**
+ * A scored airspace result from a fuzzy {@link AirspaceResolver.search}.
+ */
+export interface AirspaceSearchResult {
+    /** The matched airspace feature. */
+    feature: AirspaceFeature;
+    /** Match strength in `[0, 1]`, where 1 is an exact identifier or name match. */
+    score: number;
+    /** Which field produced the best match, identifying what {@link AirspaceSearchResult.ranges} index into. */
+    matchedField: AirspaceSearchField;
+    /** Matched character ranges within the best-matching field's text, for highlighting. */
+    ranges: MatchRange[];
+}
 /**
  * Options for creating an airspace resolver.
  */
@@ -159,6 +190,15 @@ export interface AirspaceResolver {
      * @returns All matching features, or an empty array.
      */
     byIdentifier(identifier: string, options?: AirspaceByIdentifierOptions): AirspaceFeature[];
+    /**
+     * Fuzzy-searches airspace features across identifier and name. Results are
+     * scored and returned best-match first, each carrying the matched field and
+     * character ranges for highlighting.
+     *
+     * Features with an empty identifier and name (some Class E5 surfaces) never
+     * match a non-empty query and are simply absent from results.
+     */
+    search(query: AirspaceSearchQuery): AirspaceSearchResult[];
     /**
      * Returns every airspace feature whose pre-indexed bounding box overlaps
      * the given bounding box. Reuses the bounding box computed once at

package/dist/resolver.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resolver.d.ts","sourceRoot":"","sources":["../src/resolver.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAW,MAAM,SAAS,CAAC;AAE1D,OAAO,EAA2B,KAAK,WAAW,EAAE,MAAM,aAAa,CAAC;AACxE,OAAO,KAAK,EAAE,eAAe,EAAE,YAAY,EAAiB,YAAY,EAAE,MAAM,eAAe,CAAC;AAIhG;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,2CAA2C;IAC3C,GAAG,EAAE,MAAM,CAAC;IACZ,4CAA4C;IAC5C,GAAG,EAAE,MAAM,CAAC;IACZ,wEAAwE;IACxE,UAAU,EAAE,MAAM,CAAC;IACnB;;;;;;;OAOG;IACH,KAAK,CAAC,EAAE,WAAW,CAAC,YAAY,CAAC,CAAC;CACnC;AAED;;;GAGG;AACH,MAAM,WAAW,qBAAqB;IACpC,4CAA4C;IAC5C,GAAG,EAAE,MAAM,CAAC;IACZ,2CAA2C;IAC3C,GAAG,EAAE,MAAM,CAAC;IACZ;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,2BAA2B;IAC1C;;;;;;;OAOG;IACH,KAAK,CAAC,EAAE,WAAW,CAAC,YAAY,CAAC,CAAC;IAClC;;;;;;;;OAQG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,8DAA8D;IAC9D,IAAI,EAAE,iBAAiB,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;;;OAMG;IACH,KAAK,CAAC,KAAK,EAAE,aAAa,GAAG,eAAe,EAAE,CAAC;IAE/C;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,SAAS,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,WAAW,CAAC,YAAY,CAAC,GAAG,eAAe,EAAE,CAAC;IAEpF;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,eAAe,EAAE,CAAC;IAEvE;;;;;;;;;;;;;;;;;OAiBG;IACH,UAAU,CAAC,KAAK,EAAE,qBAAqB,GAAG,eAAe,EAAE,CAAC;IAE5D;;;;;;;;;;;;;;;;;;OAkBG;IACH,YAAY,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,2BAA2B,GAAG,eAAe,EAAE,CAAC;IAE3F;;;;;;;;;;;;;;;OAeG;IACH,UAAU,CAAC,IAAI,EAAE,WAAW,GAAG,eAAe,EAAE,CAAC;IAEjD;;;;;;;;;;;;OAYG;IACH,cAAc,CACZ,QAAQ,EAAE,CACR,OAAO,EAAE,eAAe,EACxB,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,EACzB,WAAW,EAAE,WAAW,KACrB,IAAI,GACR,IAAI,CAAC;CACT;AAoDD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,uBAAuB,GAAG,gBAAgB,CA2HzF"}
+{"version":3,"file":"resolver.d.ts","sourceRoot":"","sources":["../src/resolver.ts"],"names":[],"mappings":"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"}

package/dist/resolver.js

@@ -1,5 +1,10 @@
 import { polygon, polygonGeoJson } from '@squawk/geo';
+import { fuzzySearch } from '@squawk/search';
 import { altitudeMatches } from './vertical-filter.js';
+/**
+ * Default maximum number of results for text search queries.
+ */
+const DEFAULT_SEARCH_LIMIT = 20;
 /**
  * Parses a GeoJSON Feature into an IndexedFeature, extracting the
  * AirspaceFeature properties and polygon ring. Returns null if the
@@ -81,6 +86,7 @@ export function createAirspaceResolver(options) {
             }
         }
     }
+    const searchableFeatures = indexed.map((entry) => entry.feature);
     return {
         query(query) {
             const results = [];
@@ -153,6 +159,26 @@ export function createAirspaceResolver(options) {
             }
             return bucket.filter((f) => f.type !== 'ARTCC');
         },
+        search(query) {
+            const options = {
+                keys: (feature) => [
+                    { name: 'identifier', text: feature.identifier },
+                    { name: 'name', text: feature.name },
+                ],
+                limit: query.limit ?? DEFAULT_SEARCH_LIMIT,
+                minScore: query.minScore ?? 0,
+            };
+            const types = query.types;
+            if (types) {
+                options.filter = (feature) => types.has(feature.type);
+            }
+            return fuzzySearch(searchableFeatures, query.text, options).map((match) => ({
+                feature: match.item,
+                score: match.score,
+                matchedField: match.field,
+                ranges: match.ranges,
+            }));
+        },
         withinBbox(bbox) {
             const results = [];
             for (const { feature, boundingBox } of indexed) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@squawk/airspace",
-  "version": "0.8.6",
+  "version": "0.9.0",
   "type": "module",
   "description": "Pure logic library for querying US airspace geometry by position and altitude",
   "author": "Neil Cochran",
@@ -42,6 +42,7 @@
   },
   "dependencies": {
     "@squawk/geo": "^0.4.3",
+    "@squawk/search": "^0.1.0",
     "@squawk/types": "^0.8.0",
     "@types/geojson": "^7946.0.16"
   },