aviation-codes

Type-safe, tree-shakeable validation and lookup for IATA/ICAO airport and airline codes.

Features

• Elegant namespace API (airport.is(), airline.get())
• Auto-detection by code length (3-char IATA vs 4-char ICAO for airports)
• Tree-shakeable — import only what you need
• ESM and CommonJS dual exports
• Lightweight validation-only module (~50KB)
• 6,000+ IATA airport codes, 7,600+ ICAO airport codes
• 1,100+ IATA airline codes, 5,800+ ICAO airline codes

Installation

npm install aviation-codes
# or
pnpm add aviation-codes

Usage

Airports

import { airport } from "aviation-codes";

// Auto-detect by length (3=IATA, 4=ICAO)
airport.is("LAX");      // true
airport.is("KLAX");     // true
airport.get("JFK");     // Airport data
airport.get("KJFK");    // Airport data

// Explicit IATA
airport.iata.is("LAX");           // true
airport.iata.get("LAX");          // Airport data
airport.iata.isFormat("ABC");     // true (valid format)

// Explicit ICAO
airport.icao.is("EGLL");          // true
airport.icao.get("EGLL");         // Airport data

// Parse with result object
const result = airport.parse("LAX");
if (result.ok) {
  console.log(result.data.name);    // "Los Angeles International Airport"
  console.log(result.data.city);    // "Los Angeles"
  console.log(result.data.country); // "US"
  console.log(result.data.icao);    // "KLAX"
}

// Search
airport.search("Los Angeles");              // Array of airports
airport.search("US", { limit: 5 });         // Limit results

// Utilities
airport.iata.codes();   // All IATA codes
airport.iata.count();   // 6072
airport.icao.codes();   // All ICAO codes
airport.icao.count();   // 7692

Airlines

import { airline } from "aviation-codes";

// Auto-detect by length (2=IATA, 3=ICAO)
airline.is("AA");       // true
airline.is("AAL");      // true
airline.get("UA");      // Airline data
airline.get("UAL");     // Airline data

// Explicit IATA
airline.iata.is("AA");           // true
airline.iata.get("AA");          // Airline data

// Explicit ICAO
airline.icao.is("BAW");          // true
airline.icao.get("BAW");         // Airline data

// Parse with result object
const result = airline.parse("AA");
if (result.ok) {
  console.log(result.data.name);    // "American Airlines"
  console.log(result.data.icao);    // "AAL"
  console.log(result.data.country); // "US"
  console.log(result.data.active);  // true
}

// Search with options
airline.search("United", { limit: 5, activeOnly: true });

// Utilities
airline.iata.codes();   // All IATA codes
airline.iata.count();   // 1118
airline.icao.codes();   // All ICAO codes
airline.icao.count();   // 5852

Lightweight Validation

Import only the validation module for smaller bundles (~50KB vs ~4MB):

import { airport, airline } from "aviation-codes/validate";

airport.is("LAX");              // true (auto-detect)
airport.iata.is("LAX");         // true
airport.icao.is("KLAX");        // true
airport.iata.isFormat("ABC");   // true (format only)

airline.is("AA");               // true (auto-detect)
airline.iata.is("AA");          // true
airline.icao.is("AAL");         // true

API Reference

airport

| Method | Description | |--------|-------------| | airport.is(code) | Check if valid (auto-detects IATA/ICAO) | | airport.get(code) | Get data (auto-detects IATA/ICAO) | | airport.parse(code) | Parse and validate, returns { ok, data } | | airport.search(query, options?) | Search by name/city/country | | airport.iata.is(code) | Check if valid IATA code | | airport.iata.get(code) | Get by IATA code | | airport.iata.parse(code) | Parse IATA code | | airport.iata.isFormat(code) | Check format only (3 letters) | | airport.iata.codes() | All IATA codes | | airport.iata.count() | Count of IATA codes | | airport.icao.* | Same methods for ICAO |

airline

| Method | Description | |--------|-------------| | airline.is(code) | Check if valid (auto-detects IATA/ICAO) | | airline.get(code) | Get data (auto-detects IATA/ICAO) | | airline.parse(code) | Parse and validate, returns { ok, data } | | airline.search(query, options?) | Search by name/callsign/country | | airline.iata.is(code) | Check if valid IATA code | | airline.iata.get(code) | Get by IATA code | | airline.iata.parse(code) | Parse IATA code | | airline.iata.isFormat(code) | Check format only (2 alphanumeric) | | airline.iata.codes() | All IATA codes | | airline.iata.count() | Count of IATA codes | | airline.icao.* | Same methods for ICAO |

Types

type Airport = {
  iata: string;
  icao: string;
  name: string;
  city: string;
  country: string;    // ISO 3166-1 alpha-2 (e.g., "US", "GB")
  latitude: number;   // -90 to 90
  longitude: number;  // -180 to 180
  elevation: number;  // feet above sea level
  timezone: string;   // IANA timezone (e.g., "America/Los_Angeles")
};

type Airline = {
  iata: string;
  icao: string;
  name: string;
  callsign: string;
  country: string;    // ISO 3166-1 alpha-2 (e.g., "US", "GB")
  active: boolean;
};

type ParseResult<T> = { ok: true; data: T } | { ok: false };

Data Sources

• Airport data: OpenFlights airports.dat
• Airline data: OpenFlights airlines.dat

Updating Data

To refresh data from the source:

pnpm build:data
pnpm build

License

MIT