airport-utils 1.0.0

package/.github/dependabot.yml

@@ -0,0 +1,10 @@
+version: 2
+updates:
+  - package-ecosystem: "npm"
+    directory: "/"                         # Location of package.json
+    schedule:
+      interval: "daily"                   # Check every day
+    open-pull-requests-limit: 10          # Max 10 open PRs
+    labels:
+      - "dependencies"                    # Attach this label
+    versioning-strategy: "auto"           # Allow patch, minor & major bumps

package/.github/workflows/ci.yml

@@ -0,0 +1,13 @@
+name: CI
+on: [push, pull_request]
+jobs:
+  build-and-test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
+        with:
+          node-version: '20'
+      - run: npm ci
+      - run: npm run build
+      - run: npm test

package/.github/workflows/dependabot-automerge.yml

@@ -0,0 +1,30 @@
+name: "Auto-merge Dependabot updates"
+
+on:
+  pull_request_target:
+    types:
+      - opened
+      - labeled
+      - unlabeled
+      - synchronize
+      - ready_for_review
+    branches:
+      - main
+
+permissions:
+  pull-requests: write
+  contents: write
+
+jobs:
+  automerge:
+    if: >
+      github.actor == 'dependabot[bot]' &&
+      contains(github.event.pull_request.labels.*.name, 'dependencies')
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Enable auto-merge when CI passes
+        uses: peter-evans/enable-pull-request-automerge@v2
+        with:
+          pull-request-number: ${{ github.event.pull_request.number }}
+          merge-method: squash

package/.github/workflows/publish.yml

@@ -0,0 +1,45 @@
+name: Publish
+
+on:
+  schedule:
+    - cron: '0 2 * * *'   # daily at 02:00 UTC
+  workflow_dispatch:
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+
+    steps:
+      - name: Check out code
+        uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+          persist-credentials: true
+
+      - name: Write .npmrc for registry auth
+        run: |
+          # Public npm
+          echo "//registry.npmjs.org/:_authToken=${NPM_TOKEN}" > ~/.npmrc
+          # GitHub
+          echo "@elipeF:registry=https://npm.pkg.github.com" >> ~/.npmrc
+          echo "//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}" >> ~/.npmrc
+        env:
+          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build
+        run: npm run build
+
+      - name: Test
+        run: npm test
+
+      - name: Run semantic-release
+        env:
+          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: npx semantic-release

package/.github/workflows/update-mapping.yml

@@ -0,0 +1,36 @@
+name: Update IATA→Timezone & Geo Mapping
+
+on:
+  schedule:
+    - cron: '0 0 * * *'   # every day at 00:00 UTC
+  workflow_dispatch:
+
+jobs:
+  refresh-mapping:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repo
+        uses: actions/checkout@v3
+      - name: Setup Node.js
+        uses: actions/setup-node@v3
+        with:
+          node-version: '20'
+      - name: Install dependencies
+        run: npm ci
+      - name: Generate updated mapping
+        run: npm run update:mapping
+      - name: Build
+        run: npm run build
+      - name: Test
+        run: npm test
+      - name: Commit & push if changed
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add src/mapping/*
+          if ! git diff --cached --quiet; then
+            git commit -m "chore: daily update of mapping files"
+            git push
+          else
+            echo "No changes in mapping files"
+          fi

package/.nvmrc

@@ -0,0 +1 @@
+20

package/.releaserc.json

@@ -0,0 +1,27 @@
+{
+  "branches": ["main"],
+  "repositoryUrl": "https://github.com/elipeF/airport-utils.git",
+  "plugins": [
+    [
+      "@semantic-release/commit-analyzer",
+      {
+        "preset": "conventionalcommits",
+        "releaseRules": [
+          { "type": "chore",    "release": "patch" },
+          { "type": "docs",     "release": "patch" },
+          { "type": "style",    "release": "patch" },
+          { "type": "refactor", "release": "patch" },
+          { "type": "perf",     "release": "patch" },
+          { "type": "test",     "release": "patch" },
+          { "type": "merge",    "release": "patch" }
+        ],
+        "parserOpts": {
+          "noteKeywords": ["BREAKING CHANGE", "BREAKING CHANGES"]
+        }
+      }
+    ],
+    "@semantic-release/release-notes-generator",
+    "@semantic-release/npm",
+    "@semantic-release/github"
+  ]
+}

package/README.md

@@ -0,0 +1,123 @@
+# 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
+- TypeScript support, Node 20+
+- Synchronous API with custom error classes
+- Day.js (UTC & Timezone plugins) under the hood
+- Daily auto-updated mapping via GitHub Actions
+- Jest tests with 100% coverage
+- Automated releases via semantic-release
+
+## Installation
+
+```bash
+npm install airport-utils
+```
+
+## Usage
+
+```ts
+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
+}
+
+// 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
+}
+
+// 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'
+  // }
+} catch (err) {
+  // handle UnknownAirportError
+}
+```
+
+### API
+
+```ts
+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;
+};
+
+export class UnknownAirportError extends Error {}
+export class InvalidTimestampError extends Error {}
+export class UnknownTimezoneError extends Error {}
+```
+
+## Updating Mappings
+
+```bash
+npm run update:mapping
+```
+
+Runs `scripts/generateMapping.ts` to fetch OPTD CSV and regenerate:
+- `src/mapping/timezones.ts`
+- `src/mapping/geo.ts`
+
+## Development
+
+```bash
+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

package/dist/scripts/generateMapping.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/scripts/generateMapping.js

@@ -0,0 +1,78 @@
+#!/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 = {};
+    const geoMap = {};
+    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/dist/src/converter.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Convert local ISO 8601 (YYYY-MM-DDTHH:mm) at an airport into UTC ISO string.
+ * @throws UnknownAirportError | InvalidTimestampError
+ */
+export declare function convertToUTC(localIso: string, iata: string): string;
+/**
+ * Convert local ISO 8601 string in any IANA timezone to UTC ISO string.
+ * @throws UnknownTimezoneError | InvalidTimestampError
+ */
+export declare function convertLocalToUTCByZone(localIso: string, timeZone: string): string;

package/dist/src/converter.js

@@ -0,0 +1,50 @@
+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, iata) {
+    const tz = timezones[iata];
+    if (!tz)
+        throw new UnknownAirportError(iata);
+    // 1) Pre-validate timestamp
+    const localDt = dayjs(localIso);
+    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, timeZone) {
+    // 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/dist/src/errors.d.ts

@@ -0,0 +1,9 @@
+export declare class UnknownAirportError extends Error {
+    constructor(iata: string);
+}
+export declare class InvalidTimestampError extends Error {
+    constructor(ts: string);
+}
+export declare class UnknownTimezoneError extends Error {
+    constructor(tz: string);
+}

package/dist/src/errors.js

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

package/dist/src/index.d.ts

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

package/dist/src/index.js

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

package/dist/src/info.d.ts

@@ -0,0 +1,10 @@
+export interface AirportInfo {
+    timezone: string;
+    latitude: number;
+    longitude: number;
+    name: string;
+    city: string;
+    country: string;
+}
+/** @throws UnknownAirportError */
+export declare function getAirportInfo(iata: string): AirportInfo;

package/dist/src/info.js

@@ -0,0 +1,11 @@
+import { timezones } from './mapping/timezones';
+import { geo } from './mapping/geo';
+import { UnknownAirportError } from './errors';
+/** @throws UnknownAirportError */
+export function getAirportInfo(iata) {
+    const tz = timezones[iata];
+    const g = geo[iata];
+    if (!tz || !g)
+        throw new UnknownAirportError(iata);
+    return { timezone: tz, ...g };
+}

package/dist/src/mapping/geo.d.ts

@@ -0,0 +1,8 @@
+export interface GeoEntry {
+    latitude: number;
+    longitude: number;
+    name: string;
+    city: string;
+    country: string;
+}
+export declare const geo: Record<string, GeoEntry>;