@squawk/airspace 0.7.1 → 0.8.6

package/README.md

@@ -67,7 +67,7 @@ The `/browser` entry is identical to the main entry; the separate subpath exists
 ## How it works
 
 `createAirspaceResolver` parses the GeoJSON FeatureCollection at initialization and
-returns a resolver object with three methods:
+returns a resolver object with the following methods:
 
 - `query(AirspaceQuery)` - returns features containing the given position and
   altitude, via a ray casting point-in-polygon test combined with a vertical
@@ -79,6 +79,19 @@ returns a resolver object with three methods:
 - `byArtcc(identifier, stratum?)` - returns every ARTCC feature for the given
   3-letter center code (e.g. `"ZNY"`), optionally filtered to a single
   stratum (`LOW`, `HIGH`, `UTA`, `CTA`, `FIR`, or `CTA/FIR`).
+- `byIdentifier(identifier, options?)` - type-agnostic identifier lookup that
+  spans both partitions in one call, with an optional `types` inclusion
+  filter and `includeArtcc` toggle.
+- `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),
+  where the centroid is the only stable handle.
+- `withinBbox(bbox)` - returns features whose pre-indexed bounding box
+  overlaps the query bbox. Reuses the bounding box cached at init time
+  rather than recomputing per call.
+- `forEachIndexed(callback)` - read-only iteration over the indexed corpus
+  with positional `(feature, ring, boundingBox)` arguments, for callers
+  that need to filter the corpus without reparsing the source GeoJSON.
 
 All matching features are returned as `AirspaceFeature` objects (from `@squawk/types`),
 including the full polygon boundary coordinates.
@@ -116,7 +129,9 @@ Creates a resolver from a GeoJSON dataset.
 - `options.data` - a GeoJSON `FeatureCollection` with airspace features
 
 **Returns:** `AirspaceResolver` - an object exposing `query(AirspaceQuery)`,
-`byAirport(identifier, types?)`, and `byArtcc(identifier, stratum?)` methods.
+`byAirport(identifier, types?)`, `byArtcc(identifier, stratum?)`,
+`byIdentifier(identifier, options?)`, `byCentroid(query)`, `withinBbox(bbox)`,
+and `forEachIndexed(callback)` methods.
 
 ### `AirspaceQuery`
 
@@ -169,6 +184,81 @@ const zny = resolver.byArtcc('ZNY');
 const zbwHigh = resolver.byArtcc('ZBW', 'HIGH');
 ```
 
+### `resolver.byIdentifier(identifier, options?)`
+
+Type-agnostic identifier lookup. Returns every feature whose `identifier`
+matches, spanning both the ARTCC and non-ARTCC partitions in one call.
+Reach for this when the airspace type is not known up-front (e.g. parsed
+from a URL); for ergonomic shortcuts, the partition-specific `byAirport` /
+`byArtcc` wrappers stay available.
+
+| Option         | Type                       | Description                                                                                     |
+| -------------- | -------------------------- | ----------------------------------------------------------------------------------------------- |
+| `types`        | ReadonlySet\<AirspaceType> | Optional. When provided, acts as the authoritative inclusion filter; `includeArtcc` is ignored. |
+| `includeArtcc` | boolean                    | Defaults to `true`. When `false` and `types` is omitted, ARTCC features are excluded.           |
+
+```typescript
+// Every feature for the identifier, ARTCC included
+const all = resolver.byIdentifier('ZNY');
+
+// Only the non-ARTCC partition
+const nonArtcc = resolver.byIdentifier('ZNY', { includeArtcc: false });
+
+// Only matching types
+const onlyClassB = resolver.byIdentifier('JFK', { types: new Set(['CLASS_B']) });
+```
+
+### `resolver.byCentroid(query)`
+
+Returns every feature whose polygon centroid is within `toleranceDeg` of
+`(lon, lat)`. The centroid is computed per call (not cached) so this is
+O(n) over the corpus - suitable for occasional URL-driven lookups, not
+hot loops. Useful for resolving features with an empty `identifier` (some
+Class E5 surfaces), where the centroid is the fallback URL handle.
+
+| Property       | Type   | Description                                                                                              |
+| -------------- | ------ | -------------------------------------------------------------------------------------------------------- |
+| `lon`          | number | Longitude in decimal degrees (WGS84)                                                                     |
+| `lat`          | number | Latitude in decimal degrees (WGS84)                                                                      |
+| `toleranceDeg` | number | Optional. Centroid match tolerance in degrees, applied independently to lon and lat. Defaults to 0.0001. |
+
+```typescript
+const matches = resolver.byCentroid({ lon: -118.4081, lat: 33.9425 });
+```
+
+### `resolver.withinBbox(bbox)`
+
+Returns every feature whose pre-indexed bounding box overlaps the query
+bbox. Reuses the bounding box cached at init time, so this is suitable
+for tight loops over the corpus. Bounding-box overlap is a coarse spatial
+filter: callers that need true polygon-polygon intersection should follow
+up with their own geometry test on the returned features.
+
+```typescript
+const overlapping = resolver.withinBbox({
+  minLon: -119,
+  minLat: 33,
+  maxLon: -118,
+  maxLat: 35,
+});
+```
+
+### `resolver.forEachIndexed(callback)`
+
+Read-only iteration over the indexed corpus, invoking `callback` once per
+feature with positional `(feature, ring, boundingBox)`. Exposes the
+resolver's pre-parsed shape so callers that need to filter the corpus
+themselves do not have to reparse the source GeoJSON or recompute geometry
+per call. The `ring` and `boundingBox` arguments are the resolver's
+internal caches and must not be mutated.
+
+```typescript
+resolver.forEachIndexed((feature, ring, boundingBox) => {
+  // ring is the parsed exterior ring (number[][]).
+  // boundingBox is the pre-computed axis-aligned bbox.
+});
+```
+
 ### ARTCC altitude bounds
 
 ARTCC features carry stratum-aligned floor/ceiling values for use with

package/dist/index.d.ts

@@ -1,3 +1,7 @@
+/**
+ * @packageDocumentation
+ * Pure logic library for point-in-airspace queries against US airspace polygons.
+ */
 export { createAirspaceResolver } from './resolver.js';
-export type { AirspaceResolver, AirspaceResolverOptions, AirspaceQuery } from './resolver.js';
+export type { AirspaceResolver, AirspaceResolverOptions, AirspaceQuery, AirspaceCentroidQuery, AirspaceByIdentifierOptions, } 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,OAAO,EAAE,sBAAsB,EAAE,MAAM,eAAe,CAAC;AACvD,YAAY,EAAE,gBAAgB,EAAE,uBAAuB,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC"}
+{"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"}

package/dist/index.js

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

package/dist/resolver.d.ts

@@ -1,4 +1,5 @@
 import type { FeatureCollection } from 'geojson';
+import { type BoundingBox } from '@squawk/geo';
 import type { AirspaceFeature, AirspaceType, ArtccStratum } from '@squawk/types';
 /**
  * A query describing a geographic position and altitude to resolve
@@ -21,6 +22,48 @@ export interface AirspaceQuery {
      */
     types?: ReadonlySet<AirspaceType>;
 }
+/**
+ * A query describing a geographic position and tolerance for a centroid-based
+ * airspace lookup.
+ */
+export interface AirspaceCentroidQuery {
+    /** Longitude in decimal degrees (WGS84). */
+    lon: number;
+    /** Latitude in decimal degrees (WGS84). */
+    lat: number;
+    /**
+     * Optional tolerance in degrees for the centroid match. A feature is
+     * returned when both `|centroidLon - lon|` and `|centroidLat - lat|`
+     * fall below this value. Defaults to `0.0001` (~11 m), generous enough to
+     * absorb floating-point round-trips through URL parsing for centroids
+     * encoded to ~5 decimal places.
+     */
+    toleranceDeg?: number;
+}
+/**
+ * Options accepted by {@link AirspaceResolver.byIdentifier}.
+ */
+export interface AirspaceByIdentifierOptions {
+    /**
+     * Optional set of airspace types to include in the results. When provided,
+     * acts as an inclusion filter and overrides the partition between ARTCC and
+     * non-ARTCC features: callers who want ARTCC results in addition to the
+     * usual partition include `'ARTCC'` in this set explicitly, and callers who
+     * want only non-ARTCC results pass a set of the non-ARTCC types. When
+     * omitted, every type is eligible (subject to {@link includeArtcc}).
+     */
+    types?: ReadonlySet<AirspaceType>;
+    /**
+     * When `true` (the default), ARTCC features for the identifier are included
+     * alongside the airport-associated and SUA features. When `false`, ARTCC
+     * features are excluded - useful when you only want the non-ARTCC partition
+     * for an identifier without enumerating every non-ARTCC type yourself.
+     *
+     * Ignored when {@link types} is provided: `types` is the authoritative
+     * inclusion list in that case.
+     */
+    includeArtcc?: boolean;
+}
 /**
  * Options for creating an airspace resolver.
  */
@@ -77,6 +120,76 @@ export interface AirspaceResolver {
      * @returns All matching ARTCC features, or an empty array.
      */
     byArtcc(identifier: string, stratum?: ArtccStratum): AirspaceFeature[];
+    /**
+     * Returns every airspace feature whose polygon centroid lies within the
+     * given tolerance of the query coordinates. Useful for resolving features
+     * that have an empty `identifier` (some Class E5 surfaces) and therefore
+     * have no stable identifier-keyed lookup - the polygon centroid is the
+     * fallback handle.
+     *
+     * Reach for this when you have a centroid encoded into a URL or other
+     * external string and want to recover the original feature(s); for
+     * identifier-keyed lookups, prefer {@link byIdentifier} (or the more
+     * specific {@link byAirport} / {@link byArtcc}). Centroid is computed
+     * per call - no internal caching - so this is O(n) over the indexed
+     * corpus, suitable for occasional URL-driven lookups but not for
+     * tight loops.
+     *
+     * @param query - Query coordinates and optional tolerance.
+     * @returns All features whose centroid is within tolerance, in dataset order.
+     */
+    byCentroid(query: AirspaceCentroidQuery): AirspaceFeature[];
+    /**
+     * Returns every airspace feature for the given identifier across both the
+     * ARTCC and non-ARTCC partitions, independent of position or altitude.
+     * Lookup is case-insensitive.
+     *
+     * Reach for this when you have an identifier whose airspace type is not
+     * known up-front (e.g. parsed from a URL) and you want a single call that
+     * returns the matching feature(s) regardless of partition. For ergonomic
+     * shortcuts when the partition is known, prefer {@link byAirport} (returns
+     * non-ARTCC features only) or {@link byArtcc} (returns ARTCC features
+     * only) - those wrappers encode the common "shells for this airport" /
+     * "stratums for this center" questions and stay available alongside this
+     * type-agnostic form.
+     *
+     * @param identifier - FAA identifier, NASR designator, or ARTCC code.
+     * @param options - Optional `types` inclusion filter and `includeArtcc`
+     *                  toggle. See {@link AirspaceByIdentifierOptions}.
+     * @returns All matching features, or an empty array.
+     */
+    byIdentifier(identifier: string, options?: AirspaceByIdentifierOptions): AirspaceFeature[];
+    /**
+     * Returns every airspace feature whose pre-indexed bounding box overlaps
+     * the given bounding box. Reuses the bounding box computed once at
+     * resolver creation time rather than recomputing per call, so this is
+     * suitable for tight loops over the corpus (e.g. a chip rebuild against
+     * a selection footprint).
+     *
+     * Bounding-box overlap is a coarse spatial filter: it matches any feature
+     * whose axis-aligned rectangle intersects the query rectangle, including
+     * features whose actual polygon does not. Callers that need true
+     * polygon-polygon intersection should follow up with their own geometry
+     * test on the returned features.
+     *
+     * @param bbox - Query bounding box.
+     * @returns All features whose pre-indexed bounding box overlaps, in dataset order.
+     */
+    withinBbox(bbox: BoundingBox): AirspaceFeature[];
+    /**
+     * Iterates the indexed corpus in dataset order, invoking `callback` once
+     * per feature with the parsed feature, its exterior ring, and its
+     * pre-computed bounding box. Exposes the resolver's pre-parsed shape so
+     * callers that need to filter the corpus themselves do not have to
+     * reparse the source GeoJSON or recompute geometry per call.
+     *
+     * The `ring` and `boundingBox` arguments are the resolver's internal
+     * caches and must not be mutated by the callback - copy them first if a
+     * mutation is needed.
+     *
+     * @param callback - Function invoked once per indexed feature.
+     */
+    forEachIndexed(callback: (feature: AirspaceFeature, ring: readonly number[][], boundingBox: BoundingBox) => void): void;
 }
 /**
  * Creates a stateless airspace resolver. The resolver accepts a GeoJSON
@@ -103,6 +216,9 @@ export interface AirspaceResolver {
  * const overhead = resolver.query({ lat: 33.9425, lon: -118.4081, altitudeFt: 3000 });
  * const laxShells = resolver.byAirport('LAX');
  * const newYorkArtcc = resolver.byArtcc('ZNY');
+ * const anyZnyFeature = resolver.byIdentifier('ZNY');
+ * const nearbyByCentroid = resolver.byCentroid({ lon: -118.4, lat: 33.9 });
+ * const overlapping = resolver.withinBbox({ minLon: -119, minLat: 33, maxLon: -118, maxLat: 35 });
  * ```
  */
 export declare function createAirspaceResolver(options: AirspaceResolverOptions): AirspaceResolver;

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;AAG1D,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;;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;CACxE;AAoDD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,uBAAuB,GAAG,gBAAgB,CAmEzF"}
+{"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"}

package/dist/resolver.js

@@ -1,4 +1,4 @@
-import { polygon } from '@squawk/geo';
+import { polygon, polygonGeoJson } from '@squawk/geo';
 import { altitudeMatches } from './vertical-filter.js';
 /**
  * Parses a GeoJSON Feature into an IndexedFeature, extracting the
@@ -57,6 +57,9 @@ function parseFeature(geoFeature) {
  * const overhead = resolver.query({ lat: 33.9425, lon: -118.4081, altitudeFt: 3000 });
  * const laxShells = resolver.byAirport('LAX');
  * const newYorkArtcc = resolver.byArtcc('ZNY');
+ * const anyZnyFeature = resolver.byIdentifier('ZNY');
+ * const nearbyByCentroid = resolver.byCentroid({ lon: -118.4, lat: 33.9 });
+ * const overlapping = resolver.withinBbox({ minLon: -119, minLat: 33, maxLon: -118, maxLat: 35 });
  * ```
  */
 export function createAirspaceResolver(options) {
@@ -120,5 +123,49 @@ export function createAirspaceResolver(options) {
             }
             return artccFeatures.filter((f) => f.artccStratum === stratum);
         },
+        byCentroid(query) {
+            const tolerance = query.toleranceDeg ?? 0.0001;
+            const results = [];
+            for (const { feature } of indexed) {
+                const centroid = polygonGeoJson.polygonCentroid(feature.boundary);
+                if (centroid === undefined) {
+                    continue;
+                }
+                if (Math.abs(centroid[0] - query.lon) < tolerance &&
+                    Math.abs(centroid[1] - query.lat) < tolerance) {
+                    results.push(feature);
+                }
+            }
+            return results;
+        },
+        byIdentifier(identifier, options) {
+            const bucket = byIdentifierMap.get(identifier.toUpperCase());
+            if (bucket === undefined) {
+                return [];
+            }
+            const types = options?.types;
+            if (types !== undefined) {
+                return bucket.filter((f) => types.has(f.type));
+            }
+            const includeArtcc = options?.includeArtcc ?? true;
+            if (includeArtcc) {
+                return bucket.slice();
+            }
+            return bucket.filter((f) => f.type !== 'ARTCC');
+        },
+        withinBbox(bbox) {
+            const results = [];
+            for (const { feature, boundingBox } of indexed) {
+                if (polygonGeoJson.boundingBoxesOverlap(bbox, boundingBox)) {
+                    results.push(feature);
+                }
+            }
+            return results;
+        },
+        forEachIndexed(callback) {
+            for (const { feature, ring, boundingBox } of indexed) {
+                callback(feature, ring, boundingBox);
+            }
+        },
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@squawk/airspace",
-  "version": "0.7.1",
+  "version": "0.8.6",
   "type": "module",
   "description": "Pure logic library for querying US airspace geometry by position and altitude",
   "author": "Neil Cochran",
@@ -36,7 +36,9 @@
     "test": "vitest run",
     "test:coverage": "vitest run --coverage",
     "lint": "tsc --noEmit && eslint src",
-    "lint:pack": "publint && attw --pack . --profile esm-only"
+    "lint:pack": "publint && attw --pack . --profile esm-only",
+    "api:check": "api-extractor run --verbose",
+    "api:report": "api-extractor run --local --verbose"
   },
   "dependencies": {
     "@squawk/geo": "^0.4.3",
@@ -45,7 +47,7 @@
   },
   "devDependencies": {
     "@squawk/airspace-data": "^0.5.2",
-    "@types/node": "^25.6.0"
+    "@types/node": "^25.9.3"
   },
   "keywords": [
     "aviation",