airport-utils 1.0.0

package/dist/tests/converter.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tests/converter.test.js

@@ -0,0 +1,56 @@
+import dayjs from 'dayjs';
+import { convertToUTC, convertLocalToUTCByZone } from '../src/converter';
+import { UnknownAirportError, InvalidTimestampError, UnknownTimezoneError } from '../src/errors';
+import { timezones } from '../src/mapping/timezones';
+// Dynamically find the first 3-letter code not in our mapping
+function getInvalidIata() {
+    const existing = new Set(Object.keys(timezones));
+    for (let a = 65; a <= 90; a++) {
+        for (let b = 65; b <= 90; b++) {
+            for (let c = 65; c <= 90; c++) {
+                const code = String.fromCharCode(a, b, c);
+                if (!existing.has(code))
+                    return code;
+            }
+        }
+    }
+    throw new Error('All 3-letter codes are taken?!');
+}
+const invalidIata = getInvalidIata();
+describe('convertToUTC (Day.js)', () => {
+    it('converts JFK local time (UTC–4 in May) correctly', () => {
+        expect(convertToUTC('2025-05-02T14:30', 'JFK'))
+            .toBe('2025-05-02T18:30:00Z');
+    });
+    it('throws UnknownAirportError for bad IATA', () => {
+        expect(() => convertToUTC('2025-05-02T14:30', invalidIata))
+            .toThrow(UnknownAirportError);
+    });
+    it('throws InvalidTimestampError for malformed timestamp', () => {
+        expect(() => convertToUTC('invalid-format', 'JFK'))
+            .toThrow(InvalidTimestampError);
+    });
+    it('throws InvalidTimestampError if dayjs.tz unexpectedly throws', () => {
+        const orig = dayjs.tz;
+        dayjs.tz = () => { throw new Error(); };
+        try {
+            expect(() => convertToUTC('2025-05-02T14:30', 'JFK'))
+                .toThrow(InvalidTimestampError);
+        }
+        finally {
+            dayjs.tz = orig;
+        }
+    });
+});
+describe('convertLocalToUTCByZone', () => {
+    it('converts London local time to UTC', () => {
+        expect(convertLocalToUTCByZone('2025-05-02T14:30:00', 'Europe/London'))
+            .toBe('2025-05-02T13:30:00Z');
+    });
+    it('throws UnknownTimezoneError for invalid tz', () => {
+        expect(() => convertLocalToUTCByZone('2025-05-02T14:30:00', 'Invalid/Zone')).toThrow(UnknownTimezoneError);
+    });
+    it('throws InvalidTimestampError for malformed timestamp', () => {
+        expect(() => convertLocalToUTCByZone('bad-format', 'Europe/London')).toThrow(InvalidTimestampError);
+    });
+});

package/dist/tests/info.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tests/info.test.js

@@ -0,0 +1,34 @@
+import { getAirportInfo } from '../src/info';
+import { UnknownAirportError } from '../src/errors';
+import { timezones } from '../src/mapping/timezones';
+import { geo } from '../src/mapping/geo';
+// Dynamically find the first 3-letter code not in our mapping
+function getInvalidIata() {
+    const existing = new Set(Object.keys(timezones));
+    for (let a = 65; a <= 90; a++) {
+        for (let b = 65; b <= 90; b++) {
+            for (let c = 65; c <= 90; c++) {
+                const code = String.fromCharCode(a, b, c);
+                if (!existing.has(code))
+                    return code;
+            }
+        }
+    }
+    throw new Error('All 3-letter codes are taken?!');
+}
+const invalidIata = getInvalidIata();
+describe('getAirportInfo', () => {
+    const validCodes = Object.keys(timezones).filter(i => geo[i]);
+    const sample = validCodes.length > 0 ? validCodes[0] : 'JFK';
+    it('returns full info for a valid IATA', () => {
+        const info = getAirportInfo(sample);
+        expect(info).toEqual({
+            timezone: timezones[sample],
+            ...geo[sample]
+        });
+    });
+    it('throws UnknownAirportError for missing IATA', () => {
+        expect(() => getAirportInfo(invalidIata))
+            .toThrow(UnknownAirportError);
+    });
+});

package/jest.config.js

@@ -0,0 +1,11 @@
+export default {
+  preset: 'ts-jest',
+  testEnvironment: 'node',
+  roots: ['<rootDir>/tests'],
+  collectCoverage: true,
+  coverageThreshold: {
+    global: { branches: 100, functions: 100, lines: 100, statements: 100 }
+  },
+  moduleFileExtensions: ['ts', 'js', 'json'],
+  transform: { '^.+\\.ts$': 'ts-jest' }
+};

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "airport-utils",
+  "version": "1.0.0",
+  "description": "Convert local ISO 8601 timestamps to UTC using airport IATA codes, with airport geo-data",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "type": "module",
+  "scripts": {
+    "build": "tsc",
+    "test": "jest --coverage",
+    "prepublishOnly": "npm run build",
+    "update:mapping": "node --loader ts-node/esm scripts/generateMapping.ts"
+  },
+  "keywords": [
+    "amadeus",
+    "timezone",
+    "iata",
+    "iso8601",
+    "utc",
+    "airport",
+    "geo"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "dayjs": "^1.11.7"
+  },
+  "devDependencies": {
+    "@semantic-release/commit-analyzer": "^13.0.1",
+    "@semantic-release/github": "^11.0.2",
+    "@semantic-release/npm": "^12.0.1",
+    "@semantic-release/release-notes-generator": "^14.0.3",
+    "@types/jest": "^29.0.0",
+    "@types/node-fetch": "^2.6.12",
+    "conventional-changelog-conventionalcommits": "^8.0.0",
+    "jest": "^29.0.0",
+    "node-fetch": "^3.3.2",
+    "semantic-release": "^24.2.3",
+    "ts-jest": "^29.0.0",
+    "ts-node": "^10.9.1",
+    "typescript": "^5.0.0"
+  }
+}

package/scripts/generateMapping.ts

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+import fetch from 'node-fetch';
+import fs from 'fs';
+import path from 'path';
+
+async function generateMapping() {
+  const url =
+    'https://raw.githubusercontent.com/opentraveldata/opentraveldata/master/opentraveldata/optd_por_public.csv';
+  const res = await fetch(url);
+  if (!res.ok) throw new Error(`Fetch failed: ${res.statusText}`);
+  const text = await res.text();
+
+  const lines = text.split('\n').filter(l => l.trim());
+  const header = lines[0].split('^');
+  const idx = {
+    iata: header.indexOf('iata_code'),
+    tz: header.indexOf('timezone'),
+    lat: header.indexOf('latitude'),
+    lon: header.indexOf('longitude'),
+    name: header.indexOf('name'),
+    city: header.indexOf('city_name_list'),
+    country: header.indexOf('country_code')
+  };
+  if (Object.values(idx).some(i => i < 0)) {
+    throw new Error('Missing required OPTD columns');
+  }
+
+  const timezonesMap: Record<string, string> = {};
+  const geoMap: Record<string, {
+    latitude: number;
+    longitude: number;
+    name: string;
+    city: string;
+    country: string;
+  }> = {};
+
+  for (let i = 1; i < lines.length; i++) {
+    const cols = lines[i].split('^');
+    const code = cols[idx.iata];
+    if (!code || code.length !== 3) continue;
+    const tz = cols[idx.tz];
+    if (tz) timezonesMap[code] = tz;
+
+    const lat = parseFloat(cols[idx.lat]);
+    const lon = parseFloat(cols[idx.lon]);
+    const name = cols[idx.name];
+    const city = cols[idx.city].split(',')[0].trim();
+    const country = cols[idx.country];
+    if (!isNaN(lat) && !isNaN(lon) && name && city && country) {
+      geoMap[code] = { latitude: lat, longitude: lon, name, city, country };
+    }
+  }
+
+  const sortedCodes = Object.keys(timezonesMap).sort();
+  const sortedTz = Object.fromEntries(sortedCodes.map(c => [c, timezonesMap[c]]));
+  const sortedGeo = Object.fromEntries(
+    sortedCodes.filter(c => geoMap[c]).map(c => [c, geoMap[c]])
+  );
+
+  const dir = path.resolve(path.dirname(import.meta.url.replace('file://', '')), '../src/mapping');
+  fs.mkdirSync(dir, { recursive: true });
+
+  // Write TypeScript modules
+  const tzTs = [
+    '// generated — do not edit',
+    'export const timezones: Record<string, string> = ',
+    JSON.stringify(sortedTz, null, 2) + ';',
+  ].join('\n');
+  fs.writeFileSync(path.join(dir, 'timezones.ts'), tzTs + '\n');
+
+  const geoEntries = Object.entries(sortedGeo)
+    .map(([code, g]) => `  "${code}": ${JSON.stringify(g)}`)
+    .join(',\n');
+  const geoTs = [
+    '// generated — do not edit',
+    'export interface GeoEntry {',
+    '  latitude: number;',
+    '  longitude: number;',
+    '  name: string;', 
+    '  city: string;',
+    '  country: string;',
+    '}', '',
+    'export const geo: Record<string, GeoEntry> = {',
+    geoEntries,
+    '};',
+  ].join('\n');
+  fs.writeFileSync(path.join(dir, 'geo.ts'), geoTs + '\n');
+
+  console.log(`✅ Mappings: ${sortedCodes.length} timezones, ${Object.keys(sortedGeo).length} geo entries`);
+}
+
+generateMapping().catch(err => {
+  console.error(err);
+  process.exit(1);
+});

package/src/converter.ts

@@ -0,0 +1,60 @@
+import dayjs from 'dayjs';
+import utc from 'dayjs/plugin/utc';
+import timezone from 'dayjs/plugin/timezone';
+import { timezones } from './mapping/timezones';
+import {
+  UnknownAirportError,
+  InvalidTimestampError,
+  UnknownTimezoneError
+} from './errors';
+
+// Initialize plugins
+dayjs.extend(utc);
+dayjs.extend(timezone);
+
+/**
+ * Convert local ISO 8601 (YYYY-MM-DDTHH:mm) at an airport into UTC ISO string.
+ * @throws UnknownAirportError | InvalidTimestampError
+ */
+export function convertToUTC(localIso: string, iata: string): string {
+  const tz = timezones[iata];
+  if (!tz) throw new UnknownAirportError(iata);
+
+  // 1) Pre-validate timestamp
+  const localDt = dayjs(localIso, /* no format, ISO parse */);
+  if (!localDt.isValid()) throw new InvalidTimestampError(localIso);
+
+  // 2) Then apply timezone conversion
+  let dt;
+  try {
+    dt = dayjs.tz(localIso, tz);
+  } catch {
+    // Shouldn't happen for valid tz, but just in case:
+    throw new InvalidTimestampError(localIso);
+  }
+
+  return dt.utc().format(); // "YYYY-MM-DDTHH:mm:ssZ"
+}
+
+/**
+ * Convert local ISO 8601 string in any IANA timezone to UTC ISO string.
+ * @throws UnknownTimezoneError | InvalidTimestampError
+ */
+export function convertLocalToUTCByZone(
+    localIso: string,
+    timeZone: string
+): string {
+  // 1) Validate timestamp first
+  const localDt = dayjs(localIso);
+  if (!localDt.isValid()) throw new InvalidTimestampError(localIso);
+
+  // 2) Apply timezone, catching only invalid timezone errors
+  let dt;
+  try {
+    dt = dayjs.tz(localIso, timeZone);
+  } catch {
+    throw new UnknownTimezoneError(timeZone);
+  }
+
+  return dt.utc().format();
+}

package/src/errors.ts

@@ -0,0 +1,18 @@
+export class UnknownAirportError extends Error {
+  constructor(iata: string) {
+    super(`Unknown airport IATA code: ${iata}`);
+    this.name = 'UnknownAirportError';
+  }
+}
+export class InvalidTimestampError extends Error {
+  constructor(ts: string) {
+    super(`Invalid ISO 8601 timestamp: ${ts}`);
+    this.name = 'InvalidTimestampError';
+  }
+}
+export class UnknownTimezoneError extends Error {
+  constructor(tz: string) {
+    super(`Unknown timezone: ${tz}`);
+    this.name = 'UnknownTimezoneError';
+  }
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+export { convertToUTC, convertLocalToUTCByZone } from './converter';
+export { getAirportInfo, AirportInfo } from './info';
+export { UnknownAirportError, InvalidTimestampError, UnknownTimezoneError } from './errors';

package/src/info.ts

@@ -0,0 +1,20 @@
+import { timezones } from './mapping/timezones';
+import { geo, GeoEntry } from './mapping/geo';
+import { UnknownAirportError } from './errors';
+
+export interface AirportInfo {
+  timezone: string;
+  latitude: number;
+  longitude: number;
+  name: string;
+  city: string;
+  country: string;
+}
+
+/** @throws UnknownAirportError */
+export function getAirportInfo(iata: string): AirportInfo {
+  const tz = timezones[iata];
+  const g = geo[iata];
+  if (!tz || !g) throw new UnknownAirportError(iata);
+  return { timezone: tz, ...g };
+}