@squawk/airspace 0.2.2 → 0.3.0

package/README.md

@@ -19,14 +19,17 @@ Part of the [@squawk](https://www.npmjs.com/org/squawk) aviation library suite.
 import { usBundledAirspace } from '@squawk/airspace-data';
 import { createAirspaceResolver } from '@squawk/airspace';
 
-const resolve = createAirspaceResolver({ data: usBundledAirspace });
+const resolver = createAirspaceResolver({ data: usBundledAirspace });
 
 // Query a position and altitude
-const features = resolve({ lat: 33.9425, lon: -118.4081, altitudeFt: 3000 });
+const overhead = resolver.query({ lat: 33.9425, lon: -118.4081, altitudeFt: 3000 });
 
-for (const f of features) {
+for (const f of overhead) {
   console.log(f.type, f.name, f.identifier);
 }
+
+// Get every shell associated with an airport (for drawing the full wedding cake)
+const laxShells = resolver.byAirport('LAX');
 ```
 
 Consumers who have their own GeoJSON airspace data can use this package standalone:
@@ -34,19 +37,23 @@ Consumers who have their own GeoJSON airspace data can use this package standalo
 ```typescript
 import { createAirspaceResolver } from '@squawk/airspace';
 
-const resolve = createAirspaceResolver({ data: myGeoJson });
+const resolver = createAirspaceResolver({ data: myGeoJson });
 ```
 
 ## How it works
 
 `createAirspaceResolver` parses the GeoJSON FeatureCollection at initialization and
-returns a resolver function. Each call to the resolver performs two checks per
-feature:
+returns a resolver object with two methods:
 
-1. **Lateral** - a ray casting point-in-polygon test against the feature boundary
-2. **Vertical** - altitude comparison against floor and ceiling bounds
+- `query(AirspaceQuery)` - returns features containing the given position and
+  altitude, via a ray casting point-in-polygon test combined with a vertical
+  floor/ceiling comparison.
+- `byAirport(identifier, types?)` - returns every feature whose `identifier`
+  matches (case-insensitive). For Class B/C/D/E2 this groups all sectors of the
+  airspace around a given airport regardless of the point of interest.
 
-All matching features are returned as `AirspaceFeature` objects (from `@squawk/types`).
+All matching features are returned as `AirspaceFeature` objects (from `@squawk/types`),
+including the full polygon boundary coordinates.
 
 ## AGL altitude handling
 
@@ -74,14 +81,14 @@ for (const f of features) {
 
 ### `createAirspaceResolver(options)`
 
-Creates a resolver function from a GeoJSON dataset.
+Creates a resolver from a GeoJSON dataset.
 
 **Parameters:**
 
 - `options.data` - a GeoJSON `FeatureCollection` with airspace features
 
-**Returns:** `AirspaceResolver` - a function with signature
-`(query: AirspaceQuery) => AirspaceFeature[]`
+**Returns:** `AirspaceResolver` - an object exposing `query(AirspaceQuery)` and
+`byAirport(identifier, types?)` methods.
 
 ### `AirspaceQuery`
 
@@ -94,10 +101,26 @@ Creates a resolver function from a GeoJSON dataset.
 
 ```typescript
 // Only query tower-controlled airspace (exclude Class E and SUA)
-const controlled = resolve({
+const controlled = resolver.query({
   lat: 33.9425,
   lon: -118.4081,
   altitudeFt: 3000,
   types: new Set(['CLASS_B', 'CLASS_C', 'CLASS_D']),
 });
 ```
+
+### `resolver.byAirport(identifier, types?)`
+
+Returns every airspace feature whose `identifier` property matches. For
+Class B/C/D/E2 this is the associated airport's FAA location identifier
+(e.g. "JFK" for the NY Class B). For Special Use Airspace this is the NASR
+designator (e.g. "R-2508"). Lookup is case-insensitive. ICAO-prefixed codes
+like "KJFK" will not match - resolve to an FAA ID first via `@squawk/airports`.
+
+```typescript
+// Every sector of the NY Class B around JFK, with full polygon boundaries
+const jfkShells = resolver.byAirport('JFK');
+
+// Only the Class D for a towered field
+const safClassD = resolver.byAirport('SAF', new Set(['CLASS_D']));
+```

package/dist/resolver.d.ts

@@ -29,17 +29,41 @@ export interface AirspaceResolverOptions {
     data: FeatureCollection;
 }
 /**
- * A function that accepts a position and altitude and returns all
- * airspace features that contain that point laterally and vertically.
+ * Stateless resolver exposing airspace query methods.
  */
-export type AirspaceResolver = (query: AirspaceQuery) => AirspaceFeature[];
+export interface AirspaceResolver {
+    /**
+     * Returns every airspace feature whose lateral polygon contains the given
+     * position and whose vertical bounds contain the given altitude.
+     *
+     * @param query - Position, altitude, and optional type filter.
+     * @returns All matching features, in no particular order.
+     */
+    query(query: AirspaceQuery): AirspaceFeature[];
+    /**
+     * Returns every airspace feature associated with the given identifier,
+     * independent of position or altitude. Lookup is case-insensitive.
+     *
+     * For Class B/C/D/E2 airspace, the feature `identifier` is the associated
+     * airport's FAA location identifier (e.g. "JFK" for the NY Class B). For
+     * Special Use Airspace, it is the NASR designator (e.g. "R-2508"). Pass
+     * only the bare identifier - ICAO-prefixed codes like "KJFK" will not
+     * match; resolve to an FAA ID first via `@squawk/airports` if needed.
+     *
+     * @param identifier - FAA identifier or NASR designator.
+     * @param types - Optional type filter. Only features whose type is in this
+     *                set are returned. When omitted, all types are returned.
+     * @returns All features whose identifier matches, or an empty array.
+     */
+    byAirport(identifier: string, types?: ReadonlySet<AirspaceType>): AirspaceFeature[];
+}
 /**
- * Creates a stateless airspace resolver function. The resolver accepts a
- * GeoJSON FeatureCollection at initialization (typically from
- * `@squawk/airspace-data`) and returns a function that, given a position
- * and altitude, returns all matching airspace features.
+ * Creates a stateless airspace resolver. The resolver accepts a GeoJSON
+ * FeatureCollection at initialization (typically from `@squawk/airspace-data`)
+ * and returns an object with methods for querying by position and altitude
+ * or by associated airport / SUA identifier.
  *
- * The resolver performs two checks for each feature:
+ * Position queries perform two checks per feature:
  * 1. **Lateral** - point-in-polygon test against the feature boundary
  * 2. **Vertical** - altitude comparison against floor/ceiling bounds
  *
@@ -54,8 +78,9 @@ export type AirspaceResolver = (query: AirspaceQuery) => AirspaceFeature[];
  * import { usBundledAirspace } from '@squawk/airspace-data';
  * import { createAirspaceResolver } from '@squawk/airspace';
  *
- * const resolve = createAirspaceResolver({ data: usBundledAirspace });
- * const features = resolve({ lat: 33.9425, lon: -118.4081, altitudeFt: 3000 });
+ * const resolver = createAirspaceResolver({ data: usBundledAirspace });
+ * const overhead = resolver.query({ lat: 33.9425, lon: -118.4081, altitudeFt: 3000 });
+ * const laxShells = resolver.byAirport('LAX');
  * ```
  */
 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,EAAoB,MAAM,SAAS,CAAC;AACnE,OAAO,KAAK,EAAE,eAAe,EAAE,YAAY,EAAiB,MAAM,eAAe,CAAC;AAIlF;;;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;;;GAGG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,KAAK,EAAE,aAAa,KAAK,eAAe,EAAE,CAAC;AA+F3E;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,uBAAuB,GAAG,gBAAgB,CAqCzF"}
+{"version":3,"file":"resolver.d.ts","sourceRoot":"","sources":["../src/resolver.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAW,MAAM,SAAS,CAAC;AAC1D,OAAO,KAAK,EAAE,eAAe,EAAE,YAAY,EAAiB,MAAM,eAAe,CAAC;AAIlF;;;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;;;;;;;;;;;;;;OAcG;IACH,SAAS,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,WAAW,CAAC,YAAY,CAAC,GAAG,eAAe,EAAE,CAAC;CACrF;AAmDD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,uBAAuB,GAAG,gBAAgB,CAuDzF"}

package/dist/resolver.js

@@ -1,31 +1,5 @@
-import { pointInPolygon } from './point-in-polygon.js';
+import { polygon } from '@squawk/geo';
 import { altitudeMatches } from './vertical-filter.js';
-/**
- * Computes an axis-aligned bounding box from a polygon exterior ring.
- */
-function computeBoundingBox(ring) {
-    let minLon = Infinity;
-    let maxLon = -Infinity;
-    let minLat = Infinity;
-    let maxLat = -Infinity;
-    for (const coord of ring) {
-        const lon = coord[0];
-        const lat = coord[1];
-        if (lon < minLon) {
-            minLon = lon;
-        }
-        if (lon > maxLon) {
-            maxLon = lon;
-        }
-        if (lat < minLat) {
-            minLat = lat;
-        }
-        if (lat > maxLat) {
-            maxLat = lat;
-        }
-    }
-    return { minLon, maxLon, minLat, maxLat };
-}
 /**
  * Parses a GeoJSON Feature into an IndexedFeature, extracting the
  * AirspaceFeature properties and polygon ring. Returns null if the
@@ -36,8 +10,7 @@ function parseFeature(geoFeature) {
     if (!geom || geom.type !== 'Polygon') {
         return null;
     }
-    const polygon = geom;
-    const ring = polygon.coordinates[0];
+    const ring = geom.coordinates[0];
     if (!ring || ring.length < 4) {
         return null;
     }
@@ -51,20 +24,20 @@ function parseFeature(geoFeature) {
         identifier: props.identifier ?? '',
         floor: props.floor,
         ceiling: props.ceiling,
-        boundary: polygon,
+        boundary: geom,
         state: props.state ?? null,
         controllingFacility: props.controllingFacility ?? null,
         scheduleDescription: props.scheduleDescription ?? null,
     };
-    return { feature, ring, boundingBox: computeBoundingBox(ring) };
+    return { feature, ring, boundingBox: polygon.boundingBox(ring) };
 }
 /**
- * Creates a stateless airspace resolver function. The resolver accepts a
- * GeoJSON FeatureCollection at initialization (typically from
- * `@squawk/airspace-data`) and returns a function that, given a position
- * and altitude, returns all matching airspace features.
+ * Creates a stateless airspace resolver. The resolver accepts a GeoJSON
+ * FeatureCollection at initialization (typically from `@squawk/airspace-data`)
+ * and returns an object with methods for querying by position and altitude
+ * or by associated airport / SUA identifier.
  *
- * The resolver performs two checks for each feature:
+ * Position queries perform two checks per feature:
  * 1. **Lateral** - point-in-polygon test against the feature boundary
  * 2. **Vertical** - altitude comparison against floor/ceiling bounds
  *
@@ -79,39 +52,60 @@ function parseFeature(geoFeature) {
  * import { usBundledAirspace } from '@squawk/airspace-data';
  * import { createAirspaceResolver } from '@squawk/airspace';
  *
- * const resolve = createAirspaceResolver({ data: usBundledAirspace });
- * const features = resolve({ lat: 33.9425, lon: -118.4081, altitudeFt: 3000 });
+ * const resolver = createAirspaceResolver({ data: usBundledAirspace });
+ * const overhead = resolver.query({ lat: 33.9425, lon: -118.4081, altitudeFt: 3000 });
+ * const laxShells = resolver.byAirport('LAX');
  * ```
  */
 export function createAirspaceResolver(options) {
     const indexed = [];
+    const byIdentifierMap = new Map();
     for (const geoFeature of options.data.features) {
         const parsed = parseFeature(geoFeature);
         if (parsed) {
             indexed.push(parsed);
+            const key = parsed.feature.identifier.toUpperCase();
+            if (key.length > 0) {
+                const bucket = byIdentifierMap.get(key);
+                if (bucket === undefined) {
+                    byIdentifierMap.set(key, [parsed.feature]);
+                }
+                else {
+                    bucket.push(parsed.feature);
+                }
+            }
         }
     }
-    return (query) => {
-        const results = [];
-        const { lon, lat, altitudeFt, types } = query;
-        for (const { feature, ring, boundingBox } of indexed) {
-            if (types && !types.has(feature.type)) {
-                continue;
+    return {
+        query(query) {
+            const results = [];
+            const { lon, lat, altitudeFt, types } = query;
+            for (const { feature, ring, boundingBox } of indexed) {
+                if (types && !types.has(feature.type)) {
+                    continue;
+                }
+                if (!polygon.pointInBoundingBox(lon, lat, boundingBox)) {
+                    continue;
+                }
+                if (!polygon.pointInPolygon(lon, lat, ring)) {
+                    continue;
+                }
+                if (!altitudeMatches(altitudeFt, feature.floor, feature.ceiling)) {
+                    continue;
+                }
+                results.push(feature);
             }
-            if (lon < boundingBox.minLon ||
-                lon > boundingBox.maxLon ||
-                lat < boundingBox.minLat ||
-                lat > boundingBox.maxLat) {
-                continue;
+            return results;
+        },
+        byAirport(identifier, types) {
+            const bucket = byIdentifierMap.get(identifier.toUpperCase());
+            if (bucket === undefined) {
+                return [];
             }
-            if (!pointInPolygon(lon, lat, ring)) {
-                continue;
+            if (types === undefined) {
+                return bucket.slice();
             }
-            if (!altitudeMatches(altitudeFt, feature.floor, feature.ceiling)) {
-                continue;
-            }
-            results.push(feature);
-        }
-        return results;
+            return bucket.filter((f) => types.has(f.type));
+        },
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@squawk/airspace",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "type": "module",
   "description": "Pure logic library for querying US airspace geometry by position and altitude",
   "author": "Neil Cochran",
@@ -19,8 +19,8 @@
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
-      "import": "./dist/index.js",
-      "types": "./dist/index.d.ts"
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
     }
   },
   "files": [
@@ -30,9 +30,11 @@
   "scripts": {
     "build": "tsc",
     "test": "node --test 'dist/**/*.spec.js'",
-    "lint": "tsc --noEmit && eslint src"
+    "lint": "tsc --noEmit && eslint src",
+    "lint:pack": "publint && attw --pack . --profile esm-only"
   },
   "dependencies": {
+    "@squawk/geo": "*",
     "@squawk/types": "*"
   },
   "devDependencies": {

package/dist/point-in-polygon.d.ts

@@ -1,15 +0,0 @@
-/**
- * Tests whether a point is inside a polygon using the ray casting algorithm.
- * The polygon is represented as an array of [lon, lat] coordinate pairs
- * forming a closed ring (first and last points are identical).
- *
- * Returns true if the point is inside or on the boundary of the polygon.
- */
-export declare function pointInPolygon(
-/** Longitude of the test point in decimal degrees. */
-x: number, 
-/** Latitude of the test point in decimal degrees. */
-y: number, 
-/** Polygon exterior ring as [lon, lat] coordinate pairs. */
-ring: number[][]): boolean;
-//# sourceMappingURL=point-in-polygon.d.ts.map

package/dist/point-in-polygon.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"point-in-polygon.d.ts","sourceRoot":"","sources":["../src/point-in-polygon.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,wBAAgB,cAAc;AAC5B,sDAAsD;AACtD,CAAC,EAAE,MAAM;AACT,qDAAqD;AACrD,CAAC,EAAE,MAAM;AACT,4DAA4D;AAC5D,IAAI,EAAE,MAAM,EAAE,EAAE,GACf,OAAO,CAgBT"}

package/dist/point-in-polygon.js

@@ -1,27 +0,0 @@
-/**
- * Tests whether a point is inside a polygon using the ray casting algorithm.
- * The polygon is represented as an array of [lon, lat] coordinate pairs
- * forming a closed ring (first and last points are identical).
- *
- * Returns true if the point is inside or on the boundary of the polygon.
- */
-export function pointInPolygon(
-/** Longitude of the test point in decimal degrees. */
-x, 
-/** Latitude of the test point in decimal degrees. */
-y, 
-/** Polygon exterior ring as [lon, lat] coordinate pairs. */
-ring) {
-    let inside = false;
-    const len = ring.length;
-    for (let i = 0, j = len - 1; i < len; j = i++) {
-        const xi = ring[i][0];
-        const yi = ring[i][1];
-        const xj = ring[j][0];
-        const yj = ring[j][1];
-        if (yi > y !== yj > y && x < ((xj - xi) * (y - yi)) / (yj - yi) + xi) {
-            inside = !inside;
-        }
-    }
-    return inside;
-}