airport-utils

airport-utils

Convert local ISO 8601 timestamps to UTC using airport IATA codes, with airport geo-data.

Features

• Local → UTC conversion only (ISO 8601 in, ISO 8601 UTC out)
• Built-in IATA→IANA timezone mapping (OPTD)
• Built-in airport geo-data: latitude, longitude, name, city, country, country name
• TypeScript support, Node 22+
• Synchronous API with custom error classes
• @date-fns/tz under the hood
• Daily auto-updated mapping via GitHub Actions
• Jest tests with 100% coverage
• Automated releases via semantic-release

Installation

npm install airport-utils

Usage

import {
  convertToUTC,
  convertLocalToUTCByZone,
  getAirportInfo,
  UnknownAirportError,
  InvalidTimestampError,
  UnknownTimezoneError
} from 'airport-utils';

// Convert local time to UTC
try {
  const utc = convertToUTC('2025-05-02T14:30', 'JFK');
  console.log(utc); // "2025-05-02T18:30:00Z"
} catch (err) {
  // handle UnknownAirportError or InvalidTimestampError
  // InvalidTimestampError is also thrown for nonexistent or ambiguous DST wall-clock times
}

// Convert local time by zone
try {
  const utc2 = convertLocalToUTCByZone('2025-05-02T14:30:00', 'Europe/London');
  console.log(utc2); // "2025-05-02T13:30:00Z"
} catch (err) {
  // handle UnknownTimezoneError or InvalidTimestampError
  // InvalidTimestampError is also thrown for nonexistent or ambiguous DST wall-clock times
}

// Get full airport info
try {
  const info = getAirportInfo('JFK');
  console.log(info);
  // {
  //   timezone: 'America/New_York',
  //   latitude: 40.6413,
  //   longitude: -73.7781,
  //   name: 'John F. Kennedy International Airport',
  //   city: 'New York',
  //   country: 'US',
  //   countryName: 'United States',
  //   continent: 'North America'
  // }
} catch (err) {
  // handle UnknownAirportError
}

// Get all airports
import { getAllAirports } from 'airport-utils';
const airports = getAllAirports();
console.log(airports.length); // > 8000

API

export function convertToUTC(
  localIso: string,
  iata: string
): string;

export function convertLocalToUTCByZone(
  localIso: string,
  timeZone: string
): string;

export function getAirportInfo(iata: string): {
  timezone: string;
  latitude: number;
  longitude: number;
  name: string;
  city: string;
  country: string;
  countryName: string;
  continent: string;
};

export function getAllAirports(): {
  iata: string;
  timezone: string;
  latitude: number;
  longitude: number;
  name: string;
  city: string;
  country: string;
  countryName: string;
  continent: string;
}[];

export class UnknownAirportError extends Error {}
export class InvalidTimestampError extends Error {}
export class UnknownTimezoneError extends Error {}

Updating Mappings

npm run update:mapping

Runs scripts/generateMapping.ts to fetch OPTD CSV and regenerate:

• src/mapping/timezones.ts
• src/mapping/geo.ts

Development

npm ci
npm run build
npm test
npm run update:mapping

CI & Release

• ci.yml: build & test on push/PR
• update-mapping.yml: daily at 00:00 UTC, updates mapping, builds & tests, auto-commit
• publish.yml: daily at 02:00 UTC, builds, tests, and runs semantic-release
• Semantic-release uses default commit-analyzer rules and publishes to npm via NPM_TOKEN

License

MIT