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 7 support, Node 22+
• Synchronous API with custom error classes
• @date-fns/tz under the hood
• Daily auto-updated mapping via GitHub Actions
• Vitest 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

For conversion-only applications, use the lightweight subpath so the geographic dataset is not loaded:

import { convertToUTC } from 'airport-utils/converter';

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 typecheck
npm run lint
npm run format:check
npm test
npm run update:mapping

The development toolchain uses TypeScript 7 for native type-checking. Rolldown, Oxlint, and Oxfmt provide the Rust-backed build, lint, and formatting layers.

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: after successful main CI, builds, tests, and runs semantic-release
• Semantic-release publishes through npm trusted publishing with GitHub Actions OIDC

The npm package must trust the elipeF/airport-utils repository and publish.yml workflow in its Trusted Publisher settings. No long-lived npm publish token is required.

License

The software is available under the MIT License.

The bundled airport and timezone mappings are transformed from Open Travel Data (OPTD), whose curated and generated datasets are provided under CC BY. See NOTICE for attribution and transformation details.