@squawk/airspace 0.2.0

package/README.md

@@ -0,0 +1,99 @@
+# @squawk/airspace
+
+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`.
+
+## Coverage
+
+- Class B, C, D, and E controlled airspace (E2 through E7 subtypes)
+- Special Use Airspace: MOAs, restricted, prohibited, warning, alert, and national security areas
+
+## Usage
+
+```typescript
+import { usBundledAirspace } from '@squawk/airspace-data';
+import { createAirspaceResolver } from '@squawk/airspace';
+
+const resolve = createAirspaceResolver({ data: usBundledAirspace });
+
+// Query a position and altitude
+const features = resolve({ lat: 33.9425, lon: -118.4081, altitudeFt: 3000 });
+
+for (const f of features) {
+  console.log(f.type, f.name, f.identifier);
+}
+```
+
+Consumers who have their own GeoJSON airspace data can use this package standalone:
+
+```typescript
+import { createAirspaceResolver } from '@squawk/airspace';
+
+const resolve = 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:
+
+1. **Lateral** - a ray casting point-in-polygon test against the feature boundary
+2. **Vertical** - altitude comparison against floor and ceiling bounds
+
+All matching features are returned as `AirspaceFeature` objects (from `@squawk/types`).
+
+## AGL altitude handling
+
+Some airspace features have floor or ceiling bounds referenced to AGL (above ground
+level) rather than MSL. Converting AGL to MSL requires terrain elevation data that
+this library does not include.
+
+The resolver handles AGL bounds conservatively: when it cannot determine the MSL
+equivalent, it **includes** the feature rather than silently excluding it. This means
+the resolver may return features whose AGL bounds do not actually contain the
+queried altitude.
+
+Consumers can inspect the `reference` field on the returned `AltitudeBound` objects
+and apply their own terrain lookup if needed:
+
+```typescript
+for (const f of features) {
+  if (f.floor.reference === 'AGL') {
+    // This feature's floor is AGL - apply terrain data if available
+  }
+}
+```
+
+## API
+
+### `createAirspaceResolver(options)`
+
+Creates a resolver function from a GeoJSON dataset.
+
+**Parameters:**
+
+- `options.data` - a GeoJSON `FeatureCollection` with airspace features
+
+**Returns:** `AirspaceResolver` - a function with signature
+`(query: AirspaceQuery) => AirspaceFeature[]`
+
+### `AirspaceQuery`
+
+| Property     | Type                       | Description                                                        |
+| ------------ | -------------------------- | ------------------------------------------------------------------ |
+| `lat`        | number                     | Latitude in decimal degrees (WGS84)                                |
+| `lon`        | number                     | Longitude in decimal degrees (WGS84)                               |
+| `altitudeFt` | number                     | Altitude in feet MSL                                               |
+| `types`      | ReadonlySet\<AirspaceType> | Optional. When provided, only features of these types are returned |
+
+```typescript
+// Only query tower-controlled airspace (exclude Class E and SUA)
+const controlled = resolve({
+  lat: 33.9425,
+  lon: -118.4081,
+  altitudeFt: 3000,
+  types: new Set(['CLASS_B', 'CLASS_C', 'CLASS_D']),
+});
+```

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { createAirspaceResolver } from './resolver.js';
+export type { AirspaceResolver, AirspaceResolverOptions, AirspaceQuery } 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,OAAO,EAAE,sBAAsB,EAAE,MAAM,eAAe,CAAC;AACvD,YAAY,EAAE,gBAAgB,EAAE,uBAAuB,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC"}

package/dist/index.js

@@ -0,0 +1 @@
+export { createAirspaceResolver } from './resolver.js';

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

@@ -0,0 +1,15 @@
+/**
+ * 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

@@ -0,0 +1 @@
+{"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

@@ -0,0 +1,27 @@
+/**
+ * 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;
+}

package/dist/resolver.d.ts

@@ -0,0 +1,62 @@
+import type { FeatureCollection } from 'geojson';
+import type { AirspaceFeature, AirspaceType } from '@squawk/types';
+/**
+ * A query describing a geographic position and altitude to resolve
+ * against loaded airspace data.
+ */
+export interface AirspaceQuery {
+    /** Latitude in decimal degrees (WGS84). */
+    lat: number;
+    /** Longitude in decimal degrees (WGS84). */
+    lon: number;
+    /** Altitude in feet MSL to compare against airspace vertical bounds. */
+    altitudeFt: number;
+    /**
+     * Optional set of airspace types to include in the results. When provided,
+     * only features whose type is in this set are considered. Features of other
+     * types are skipped before any geometry or altitude checks, improving query
+     * performance when only specific airspace classes are needed.
+     *
+     * When omitted, all airspace types are included.
+     */
+    types?: ReadonlySet<AirspaceType>;
+}
+/**
+ * Options for creating an airspace resolver.
+ */
+export interface AirspaceResolverOptions {
+    /** GeoJSON FeatureCollection containing airspace features. */
+    data: FeatureCollection;
+}
+/**
+ * A function that accepts a position and altitude and returns all
+ * airspace features that contain that point laterally and vertically.
+ */
+export type AirspaceResolver = (query: AirspaceQuery) => 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.
+ *
+ * The resolver performs two checks for each feature:
+ * 1. **Lateral** - point-in-polygon test against the feature boundary
+ * 2. **Vertical** - altitude comparison against floor/ceiling bounds
+ *
+ * AGL-referenced altitude bounds are handled conservatively: when the
+ * resolver cannot determine the MSL equivalent (because it has no terrain
+ * data), it includes the feature rather than silently excluding it. This
+ * means the resolver may return features whose AGL bounds do not actually
+ * contain the queried altitude. Consumers can inspect the returned
+ * AltitudeBound references and apply their own terrain lookup if needed.
+ *
+ * ```typescript
+ * 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 });
+ * ```
+ */
+export declare function createAirspaceResolver(options: AirspaceResolverOptions): AirspaceResolver;
+//# 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,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"}

package/dist/resolver.js

@@ -0,0 +1,117 @@
+import { pointInPolygon } from './point-in-polygon.js';
+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
+ * feature cannot be parsed (missing geometry, invalid type, etc.).
+ */
+function parseFeature(geoFeature) {
+    const geom = geoFeature.geometry;
+    if (!geom || geom.type !== 'Polygon') {
+        return null;
+    }
+    const polygon = geom;
+    const ring = polygon.coordinates[0];
+    if (!ring || ring.length < 4) {
+        return null;
+    }
+    const props = geoFeature.properties;
+    if (!props) {
+        return null;
+    }
+    const feature = {
+        type: props.type,
+        name: props.name ?? '',
+        identifier: props.identifier ?? '',
+        floor: props.floor,
+        ceiling: props.ceiling,
+        boundary: polygon,
+        state: props.state ?? null,
+        controllingFacility: props.controllingFacility ?? null,
+        scheduleDescription: props.scheduleDescription ?? null,
+    };
+    return { feature, ring, boundingBox: computeBoundingBox(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.
+ *
+ * The resolver performs two checks for each feature:
+ * 1. **Lateral** - point-in-polygon test against the feature boundary
+ * 2. **Vertical** - altitude comparison against floor/ceiling bounds
+ *
+ * AGL-referenced altitude bounds are handled conservatively: when the
+ * resolver cannot determine the MSL equivalent (because it has no terrain
+ * data), it includes the feature rather than silently excluding it. This
+ * means the resolver may return features whose AGL bounds do not actually
+ * contain the queried altitude. Consumers can inspect the returned
+ * AltitudeBound references and apply their own terrain lookup if needed.
+ *
+ * ```typescript
+ * 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 });
+ * ```
+ */
+export function createAirspaceResolver(options) {
+    const indexed = [];
+    for (const geoFeature of options.data.features) {
+        const parsed = parseFeature(geoFeature);
+        if (parsed) {
+            indexed.push(parsed);
+        }
+    }
+    return (query) => {
+        const results = [];
+        const { lon, lat, altitudeFt, types } = query;
+        for (const { feature, ring, boundingBox } of indexed) {
+            if (types && !types.has(feature.type)) {
+                continue;
+            }
+            if (lon < boundingBox.minLon ||
+                lon > boundingBox.maxLon ||
+                lat < boundingBox.minLat ||
+                lat > boundingBox.maxLat) {
+                continue;
+            }
+            if (!pointInPolygon(lon, lat, ring)) {
+                continue;
+            }
+            if (!altitudeMatches(altitudeFt, feature.floor, feature.ceiling)) {
+                continue;
+            }
+            results.push(feature);
+        }
+        return results;
+    };
+}

package/dist/vertical-filter.d.ts

@@ -0,0 +1,23 @@
+import type { AltitudeBound } from '@squawk/types';
+/**
+ * Tests whether an altitude in feet MSL falls within the vertical bounds
+ * defined by a floor and ceiling AltitudeBound pair.
+ *
+ * Altitude reference handling:
+ * - `SFC` - treated as 0 ft MSL (surface level)
+ * - `MSL` - compared directly against the queried altitude
+ * - `AGL` - the vertical check is skipped for that bound (returns true),
+ *   because converting AGL to MSL requires terrain elevation data that this
+ *   library does not have. This is a conservative approach: the feature is
+ *   included rather than silently excluded when the bound cannot be resolved.
+ *   Consumers can inspect the returned AltitudeBound references and apply
+ *   their own terrain lookup if needed.
+ */
+export declare function altitudeMatches(
+/** Queried altitude in feet MSL. */
+altitudeFt: number, 
+/** Lower vertical bound of the airspace feature. */
+floor: AltitudeBound, 
+/** Upper vertical bound of the airspace feature. */
+ceiling: AltitudeBound): boolean;
+//# sourceMappingURL=vertical-filter.d.ts.map

package/dist/vertical-filter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vertical-filter.d.ts","sourceRoot":"","sources":["../src/vertical-filter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAEnD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe;AAC7B,oCAAoC;AACpC,UAAU,EAAE,MAAM;AAClB,oDAAoD;AACpD,KAAK,EAAE,aAAa;AACpB,oDAAoD;AACpD,OAAO,EAAE,aAAa,GACrB,OAAO,CAaT"}

package/dist/vertical-filter.js

@@ -0,0 +1,48 @@
+/**
+ * Tests whether an altitude in feet MSL falls within the vertical bounds
+ * defined by a floor and ceiling AltitudeBound pair.
+ *
+ * Altitude reference handling:
+ * - `SFC` - treated as 0 ft MSL (surface level)
+ * - `MSL` - compared directly against the queried altitude
+ * - `AGL` - the vertical check is skipped for that bound (returns true),
+ *   because converting AGL to MSL requires terrain elevation data that this
+ *   library does not have. This is a conservative approach: the feature is
+ *   included rather than silently excluded when the bound cannot be resolved.
+ *   Consumers can inspect the returned AltitudeBound references and apply
+ *   their own terrain lookup if needed.
+ */
+export function altitudeMatches(
+/** Queried altitude in feet MSL. */
+altitudeFt, 
+/** Lower vertical bound of the airspace feature. */
+floor, 
+/** Upper vertical bound of the airspace feature. */
+ceiling) {
+    const floorFt = resolveAltitude(floor);
+    const ceilingFt = resolveAltitude(ceiling);
+    // If either bound is AGL (resolved as null), skip that side of the check.
+    if (floorFt !== null && altitudeFt < floorFt) {
+        return false;
+    }
+    if (ceilingFt !== null && altitudeFt > ceilingFt) {
+        return false;
+    }
+    return true;
+}
+/**
+ * Resolves an AltitudeBound to a feet MSL value for comparison, or null
+ * if the bound uses AGL reference and cannot be resolved without terrain data.
+ */
+function resolveAltitude(bound) {
+    switch (bound.reference) {
+        case 'SFC':
+            return 0;
+        case 'MSL':
+            return bound.valueFt;
+        case 'AGL':
+            return null;
+        default:
+            return null;
+    }
+}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@squawk/airspace",
+  "version": "0.2.0",
+  "type": "module",
+  "description": "Pure logic library for querying US airspace geometry by position and altitude",
+  "author": "Neil Cochran",
+  "license": "MIT",
+  "homepage": "https://github.com/neilcochran/squawk",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/neilcochran/squawk.git",
+    "directory": "packages/airspace"
+  },
+  "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": "*"
+  },
+  "devDependencies": {
+    "@squawk/airspace-data": "*",
+    "@types/node": "^25.5.2"
+  },
+  "keywords": [
+    "aviation",
+    "typescript",
+    "airspace",
+    "geojson",
+    "class-b",
+    "class-c",
+    "sua",
+    "faa",
+    "nasr"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}