@squawk/airspace 0.5.0 → 0.6.0

package/README.md

@@ -12,6 +12,13 @@ Part of the [@squawk](https://www.npmjs.com/org/squawk) aviation library suite.
 
 - Class B, C, D, and E controlled airspace (E2 through E7 subtypes)
 - Special Use Airspace: MOAs, restricted, prohibited, warning, alert, and national security areas
+- ARTCC (Air Route Traffic Control Center) lateral boundaries for every
+  US-controlled center, published per stratum: LOW/HIGH for the 20 CONUS
+  centers and Anchorage (ZAN), UTA for Oakland (ZOA) only, and oceanic
+  CTA/FIR strata for the Pacific (ZAK, ZAP), Atlantic (ZWY), and the
+  contiguous overlays on ZAN, ZHN, ZHU, ZMA, ZSU. Within-stratum sector
+  polygons and per-sector enroute frequencies are not included - the FAA
+  does not publish either data set in machine-readable form.
 
 ## Usage
 
@@ -30,6 +37,9 @@ for (const f of overhead) {
 
 // Get every shell associated with an airport (for drawing the full wedding cake)
 const laxShells = resolver.byAirport('LAX');
+
+// Get every ARTCC center boundary (one feature per stratum)
+const ny = resolver.byArtcc('ZNY');
 ```
 
 Consumers who have their own GeoJSON airspace data can use this package standalone:
@@ -43,14 +53,18 @@ const resolver = createAirspaceResolver({ data: myGeoJson });
 ## How it works
 
 `createAirspaceResolver` parses the GeoJSON FeatureCollection at initialization and
-returns a resolver object with two methods:
+returns a resolver object with three methods:
 
 - `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.
+- `byAirport(identifier, types?)` - returns every non-ARTCC 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.
+- `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`).
 
 All matching features are returned as `AirspaceFeature` objects (from `@squawk/types`),
 including the full polygon boundary coordinates.
@@ -87,8 +101,8 @@ Creates a resolver from a GeoJSON dataset.
 
 - `options.data` - a GeoJSON `FeatureCollection` with airspace features
 
-**Returns:** `AirspaceResolver` - an object exposing `query(AirspaceQuery)` and
-`byAirport(identifier, types?)` methods.
+**Returns:** `AirspaceResolver` - an object exposing `query(AirspaceQuery)`,
+`byAirport(identifier, types?)`, and `byArtcc(identifier, stratum?)` methods.
 
 ### `AirspaceQuery`
 
@@ -111,7 +125,7 @@ const controlled = resolver.query({
 
 ### `resolver.byAirport(identifier, types?)`
 
-Returns every airspace feature whose `identifier` property matches. For
+Returns every non-ARTCC 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
@@ -124,3 +138,45 @@ const jfkShells = resolver.byAirport('JFK');
 // Only the Class D for a towered field
 const safClassD = resolver.byAirport('SAF', new Set(['CLASS_D']));
 ```
+
+### `resolver.byArtcc(identifier, stratum?)`
+
+Returns every ARTCC feature for the given three-letter center code
+(e.g. `"ZNY"`, `"ZBW"`). Each US ARTCC is published as multiple features -
+one per stratum (`LOW`, `HIGH`, plus oceanic `UTA`, `CTA`, `FIR`, or
+`CTA/FIR` where applicable) - because the lateral extent can vary between
+strata. Pass an optional stratum filter to narrow results.
+
+```typescript
+// Both LOW and HIGH boundaries for the New York center
+const zny = resolver.byArtcc('ZNY');
+
+// Just the high-altitude boundary for the Boston center
+const zbwHigh = resolver.byArtcc('ZBW', 'HIGH');
+```
+
+### ARTCC altitude bounds
+
+ARTCC features carry stratum-aligned floor/ceiling values for use with
+`query()`:
+
+| Stratum   | Floor         | Ceiling       |
+| --------- | ------------- | ------------- |
+| `LOW`     | SFC           | 18,000 ft MSL |
+| `HIGH`    | 18,000 ft MSL | 60,000 ft MSL |
+| `UTA`     | 60,000 ft MSL | 99,999 ft MSL |
+| `CTA`     | SFC           | 99,999 ft MSL |
+| `FIR`     | SFC           | 99,999 ft MSL |
+| `CTA/FIR` | SFC           | 99,999 ft MSL |
+
+These are operational stratum approximations rather than legal limits.
+The `99,999` ceiling is a sentinel meaning "effectively unlimited" -
+queries above FL600 will still match the relevant stratum.
+
+Oceanic FIR boundaries that cross the 180th meridian (ZAK FIR/CTA and ZAP
+FIR/CTA in the central Pacific) are split at the antimeridian during the
+data build, so each emitted feature has coordinates within the standard
+`[-180, 180]` range. A single source stratum produces two features in
+those cases - one for the eastern sub-polygon and one for the western - but
+both share the same `identifier` and `artccStratum`, so `byArtcc("ZAK")`
+returns them together.

package/dist/resolver.d.ts

@@ -1,5 +1,5 @@
 import type { FeatureCollection } from 'geojson';
-import type { AirspaceFeature, AirspaceType } from '@squawk/types';
+import type { AirspaceFeature, AirspaceType, ArtccStratum } from '@squawk/types';
 /**
  * A query describing a geographic position and altitude to resolve
  * against loaded airspace data.
@@ -50,12 +50,33 @@ export interface AirspaceResolver {
      * only the bare identifier - ICAO-prefixed codes like "KJFK" will not
      * match; resolve to an FAA ID first via `@squawk/airports` if needed.
      *
+     * Note: ARTCC features share the identifier-keyed index but are typically
+     * looked up via {@link byArtcc} for clearer ergonomics. ARTCC features are
+     * excluded from `byAirport` results since their identifier is a center code
+     * (e.g. "ZNY"), not an airport identifier.
+     *
      * @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.
+     *                set are returned. When omitted, all non-ARTCC types are
+     *                returned.
      * @returns All features whose identifier matches, or an empty array.
      */
     byAirport(identifier: string, types?: ReadonlySet<AirspaceType>): AirspaceFeature[];
+    /**
+     * Returns every ARTCC feature associated with the given center identifier,
+     * independent of position or altitude. Lookup is case-insensitive.
+     *
+     * Each US ARTCC is published as multiple features - one per stratum (LOW,
+     * HIGH, UTA, CTA, FIR, CTA/FIR) - because the lateral extent can vary
+     * between strata. Pass an optional stratum filter to narrow results to a
+     * single stratum.
+     *
+     * @param identifier - Three-letter ARTCC code (e.g. "ZNY", "ZBW").
+     * @param stratum - Optional stratum filter. When provided, only features
+     *                  whose `artccStratum` matches are returned.
+     * @returns All matching ARTCC features, or an empty array.
+     */
+    byArtcc(identifier: string, stratum?: ArtccStratum): AirspaceFeature[];
 }
 /**
  * Creates a stateless airspace resolver. The resolver accepts a GeoJSON
@@ -81,6 +102,7 @@ export interface AirspaceResolver {
  * const resolver = createAirspaceResolver({ data: usBundledAirspace });
  * const overhead = resolver.query({ lat: 33.9425, lon: -118.4081, altitudeFt: 3000 });
  * const laxShells = resolver.byAirport('LAX');
+ * const newYorkArtcc = resolver.byArtcc('ZNY');
  * ```
  */
 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;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"}
+{"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,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"}

package/dist/resolver.js

@@ -28,6 +28,7 @@ function parseFeature(geoFeature) {
         state: props.state ?? null,
         controllingFacility: props.controllingFacility ?? null,
         scheduleDescription: props.scheduleDescription ?? null,
+        artccStratum: props.artccStratum ?? null,
     };
     return { feature, ring, boundingBox: polygon.boundingBox(ring) };
 }
@@ -55,6 +56,7 @@ function parseFeature(geoFeature) {
  * const resolver = createAirspaceResolver({ data: usBundledAirspace });
  * const overhead = resolver.query({ lat: 33.9425, lon: -118.4081, altitudeFt: 3000 });
  * const laxShells = resolver.byAirport('LAX');
+ * const newYorkArtcc = resolver.byArtcc('ZNY');
  * ```
  */
 export function createAirspaceResolver(options) {
@@ -103,9 +105,20 @@ export function createAirspaceResolver(options) {
                 return [];
             }
             if (types === undefined) {
-                return bucket.slice();
+                return bucket.filter((f) => f.type !== 'ARTCC');
             }
-            return bucket.filter((f) => types.has(f.type));
+            return bucket.filter((f) => f.type !== 'ARTCC' && types.has(f.type));
+        },
+        byArtcc(identifier, stratum) {
+            const bucket = byIdentifierMap.get(identifier.toUpperCase());
+            if (bucket === undefined) {
+                return [];
+            }
+            const artccFeatures = bucket.filter((f) => f.type === 'ARTCC');
+            if (stratum === undefined) {
+                return artccFeatures;
+            }
+            return artccFeatures.filter((f) => f.artccStratum === stratum);
         },
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@squawk/airspace",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "type": "module",
   "description": "Pure logic library for querying US airspace geometry by position and altitude",
   "author": "Neil Cochran",
@@ -34,11 +34,11 @@
     "lint:pack": "publint && attw --pack . --profile esm-only"
   },
   "dependencies": {
-    "@squawk/geo": "^0.3.0",
-    "@squawk/types": "^0.5.0"
+    "@squawk/geo": "^0.3.2",
+    "@squawk/types": "^0.7.0"
   },
   "devDependencies": {
-    "@squawk/airspace-data": "^0.3.2",
+    "@squawk/airspace-data": "^0.4.0",
     "@types/node": "^25.6.0"
   },
   "keywords": [