@mailwoman/un-locode-lookup 4.15.1

package/README.md

@@ -0,0 +1,38 @@
+# @mailwoman/un-locode-lookup
+
+Place → **UN/LOCODE** (the UNECE Code for Trade and Transport Locations — `US NYC`, `NL RTM`). Look up
+by country + place name, or by nearest coordinate. `node:sqlite` over the UNECE code list. An
+[`@mailwoman/annotations`](../annotations) `Annotator`.
+
+## Build the DB
+
+```bash
+# from the UNECE code list (e.g. datasets/un-locode code-list.csv)
+npx @mailwoman/un-locode-lookup build --csv code-list.csv --out un-locode.db
+```
+
+## Look up
+
+```bash
+npx @mailwoman/un-locode-lookup --db un-locode.db --country NL --name "Rotterdam"
+# {"unLocode":"NL RTM"}
+
+npx @mailwoman/un-locode-lookup --db un-locode.db --near 40.7128 -74.0060
+# {"unLocode":"US NYC"}
+```
+
+## Library
+
+```ts
+import { UnLocodeLookup, makeUnLocodeAnnotator } from "@mailwoman/un-locode-lookup"
+
+const lookup = new UnLocodeLookup({ databasePath: "un-locode.db" })
+lookup.byName("US", "New York") // "US NYC"
+lookup.nearest(51.92, 4.48) // "NL RTM"
+
+const annotator = makeUnLocodeAnnotator(lookup) // fills AnnotationSet.unLocode
+```
+
+Name matching is diacritic-folded and case-insensitive. ~80% of UN/LOCODE entries carry coordinates
+(93k of 116k), so `nearest` is broadly useful; `byName` is exact. Data: UNECE UN/LOCODE (public domain
+code list).

package/out/build.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Build the UN/LOCODE lookup DB from the UNECE code list CSV (datasets/un-locode `code-list.csv`:
+ *   columns Change, Country, Location, Name, NameWoDiacritics, Subdivision, Status, Function, Date,
+ *   IATA, Coordinates, Remarks). One row per assigned location; coordinates parsed where present.
+ */
+/** Read the code-list CSV at `csvPath` and write the lookup DB to `dbPath`. */
+export declare function buildUnLocodeDb(csvPath: string, dbPath: string): {
+    rows: number;
+    withCoords: number;
+};
+//# sourceMappingURL=build.d.ts.map

package/out/build.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build.d.ts","sourceRoot":"","sources":["../build.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAeH,+EAA+E;AAC/E,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,CA2BrG"}

package/out/build.js

@@ -0,0 +1,42 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Build the UN/LOCODE lookup DB from the UNECE code list CSV (datasets/un-locode `code-list.csv`:
+ *   columns Change, Country, Location, Name, NameWoDiacritics, Subdivision, Status, Function, Date,
+ *   IATA, Coordinates, Remarks). One row per assigned location; coordinates parsed where present.
+ */
+import { parse } from "csv-parse/sync";
+import { readFileSync } from "node:fs";
+import { DatabaseSync } from "node:sqlite";
+import { foldName, parseUnLocodeCoords } from "./index.js";
+/** Read the code-list CSV at `csvPath` and write the lookup DB to `dbPath`. */
+export function buildUnLocodeDb(csvPath, dbPath) {
+    const records = parse(readFileSync(csvPath), {
+        columns: true,
+        skip_empty_lines: true,
+        relax_quotes: true,
+    });
+    const db = new DatabaseSync(dbPath);
+    db.exec("DROP TABLE IF EXISTS un_locode");
+    db.exec("CREATE TABLE un_locode (country TEXT NOT NULL, location TEXT NOT NULL, name TEXT, nameNorm TEXT, lat REAL, lon REAL)");
+    const insert = db.prepare("INSERT INTO un_locode (country, location, name, nameNorm, lat, lon) VALUES (?,?,?,?,?,?)");
+    let withCoords = 0;
+    db.exec("BEGIN");
+    for (const r of records) {
+        if (!r.Country || !r.Location)
+            continue; // header/country rows carry no Location
+        const coords = r.Coordinates ? parseUnLocodeCoords(r.Coordinates) : null;
+        if (coords)
+            withCoords++;
+        const name = r.NameWoDiacritics || r.Name || "";
+        insert.run(r.Country, r.Location, r.Name || name, foldName(name), coords?.lat ?? null, coords?.lon ?? null);
+    }
+    db.exec("COMMIT");
+    db.exec("CREATE INDEX idx_locode_name ON un_locode (country, nameNorm)");
+    db.exec("CREATE INDEX idx_locode_bbox ON un_locode (lat, lon)");
+    db.close();
+    return { rows: records.length, withCoords };
+}
+//# sourceMappingURL=build.js.map

package/out/build.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"build.js","sourceRoot":"","sources":["../build.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAA;AACtC,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA;AACtC,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAC1C,OAAO,EAAE,QAAQ,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAA;AAU1D,+EAA+E;AAC/E,MAAM,UAAU,eAAe,CAAC,OAAe,EAAE,MAAc;IAC9D,MAAM,OAAO,GAAG,KAAK,CAAC,YAAY,CAAC,OAAO,CAAC,EAAE;QAC5C,OAAO,EAAE,IAAI;QACb,gBAAgB,EAAE,IAAI;QACtB,YAAY,EAAE,IAAI;KAClB,CAAa,CAAA;IACd,MAAM,EAAE,GAAG,IAAI,YAAY,CAAC,MAAM,CAAC,CAAA;IACnC,EAAE,CAAC,IAAI,CAAC,gCAAgC,CAAC,CAAA;IACzC,EAAE,CAAC,IAAI,CACN,sHAAsH,CACtH,CAAA;IACD,MAAM,MAAM,GAAG,EAAE,CAAC,OAAO,CAAC,0FAA0F,CAAC,CAAA;IAErH,IAAI,UAAU,GAAG,CAAC,CAAA;IAClB,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,CAAA;IAChB,KAAK,MAAM,CAAC,IAAI,OAAO,EAAE,CAAC;QACzB,IAAI,CAAC,CAAC,CAAC,OAAO,IAAI,CAAC,CAAC,CAAC,QAAQ;YAAE,SAAQ,CAAC,wCAAwC;QAChF,MAAM,MAAM,GAAG,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,mBAAmB,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,IAAI,CAAA;QACxE,IAAI,MAAM;YAAE,UAAU,EAAE,CAAA;QACxB,MAAM,IAAI,GAAG,CAAC,CAAC,gBAAgB,IAAI,CAAC,CAAC,IAAI,IAAI,EAAE,CAAA;QAC/C,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC,IAAI,IAAI,IAAI,EAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,IAAI,EAAE,MAAM,EAAE,GAAG,IAAI,IAAI,CAAC,CAAA;IAC5G,CAAC;IACD,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAA;IACjB,EAAE,CAAC,IAAI,CAAC,+DAA+D,CAAC,CAAA;IACxE,EAAE,CAAC,IAAI,CAAC,sDAAsD,CAAC,CAAA;IAC/D,EAAE,CAAC,KAAK,EAAE,CAAA;IACV,OAAO,EAAE,IAAI,EAAE,OAAO,CAAC,MAAM,EAAE,UAAU,EAAE,CAAA;AAC5C,CAAC"}

package/out/cli.d.ts

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `mailwoman-un-locode` — build the lookup DB, or look up a UN/LOCODE by name or coordinate.
+ *
+ *   Mailwoman-un-locode build --csv code-list.csv --out un-locode.db mailwoman-un-locode --db
+ *   un-locode.db --country US --name "New York" mailwoman-un-locode --db un-locode.db --near
+ *   40.7128 -74.0060
+ */
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/out/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../cli.ts"],"names":[],"mappings":";AACA;;;;;;;;;;GAUG"}

package/out/cli.js

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `mailwoman-un-locode` — build the lookup DB, or look up a UN/LOCODE by name or coordinate.
+ *
+ *   Mailwoman-un-locode build --csv code-list.csv --out un-locode.db mailwoman-un-locode --db
+ *   un-locode.db --country US --name "New York" mailwoman-un-locode --db un-locode.db --near
+ *   40.7128 -74.0060
+ */
+import { parseArgs } from "node:util";
+import { buildUnLocodeDb } from "./build.js";
+import { UnLocodeLookup } from "./index.js";
+if (process.argv[2] === "build") {
+    const { values } = parseArgs({
+        args: process.argv.slice(3),
+        options: { csv: { type: "string" }, out: { type: "string" } },
+    });
+    if (!values.csv || !values.out) {
+        console.error("Usage: mailwoman-un-locode build --csv <code-list.csv> --out <db>");
+        process.exit(1);
+    }
+    const { rows, withCoords } = buildUnLocodeDb(values.csv, values.out);
+    console.error(`built ${values.out} (${rows} rows, ${withCoords} with coordinates)`);
+}
+else {
+    // Hand-parse so negative coordinates work as positionals.
+    const args = process.argv.slice(2);
+    let databasePath;
+    let country;
+    let name;
+    const near = [];
+    for (let i = 0; i < args.length; i++) {
+        if (args[i] === "--db")
+            databasePath = args[++i];
+        else if (args[i] === "--country")
+            country = args[++i];
+        else if (args[i] === "--name")
+            name = args[++i];
+        else if (args[i] === "--near")
+            continue;
+        else {
+            const n = Number(args[i]);
+            if (Number.isFinite(n))
+                near.push(n);
+        }
+    }
+    if (!databasePath) {
+        console.error("Usage: mailwoman-un-locode --db <db> (--country CC --name NAME | --near <lat> <lon>)");
+        process.exit(1);
+    }
+    const lookup = new UnLocodeLookup({ databasePath });
+    let code = null;
+    if (country && name)
+        code = lookup.byName(country, name);
+    else if (near.length === 2)
+        code = lookup.nearest(near[0], near[1]);
+    console.log(JSON.stringify({ unLocode: code }));
+    lookup.close();
+}
+//# sourceMappingURL=cli.js.map

package/out/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../cli.ts"],"names":[],"mappings":"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"}

package/out/index.d.ts

@@ -0,0 +1,42 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `@mailwoman/un-locode-lookup` — place → UN/LOCODE (UNECE Code for Trade and Transport Locations).
+ *   Two ways in: by country + place name (exact, diacritic-folded), or by nearest coordinate (for
+ *   the ~⅓ of entries that carry one). Backed by a `node:sqlite` table built from the UNECE code
+ *   list. An `@mailwoman/annotations` `Annotator`.
+ */
+import type { Annotator } from "@mailwoman/annotations";
+import { DatabaseSync } from "node:sqlite";
+/** Fold a place name to its match key: strip diacritics, lowercase, collapse whitespace. */
+export declare function foldName(name: string): string;
+/** Parse a UN/LOCODE coordinate (`"4923N 01522E"`) to decimal degrees, or null if absent/malformed. */
+export declare function parseUnLocodeCoords(raw: string): {
+    lat: number;
+    lon: number;
+} | null;
+/** A UN/LOCODE lookup over a built `node:sqlite` table. */
+export declare class UnLocodeLookup {
+    #private;
+    constructor(opts: {
+        databasePath: string;
+    } | {
+        database: DatabaseSync;
+    });
+    /** The UN/LOCODE (`"US NYC"`) for a country + place name, or null. */
+    byName(country: string, name: string): string | null;
+    /** The nearest coordinate-bearing UN/LOCODE within `maxKm`, or null. */
+    nearest(lat: number, lon: number, maxKm?: number): string | null;
+    close(): void;
+}
+/**
+ * Build an `Annotator` filling `AnnotationSet.unLocode`. Prefers a country + place-name match (when
+ * the resolver supplies them via `countryCode` / `placeName`), and falls back to the nearest
+ * coordinate.
+ */
+export declare function makeUnLocodeAnnotator(lookup: UnLocodeLookup, opts?: {
+    maxKm?: number;
+}): Annotator;
+//# sourceMappingURL=index.d.ts.map

package/out/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAiB,SAAS,EAAE,MAAM,wBAAwB,CAAA;AACtE,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAE1C,4FAA4F;AAC5F,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE7C;AAED,uGAAuG;AACvG,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAMpF;AAYD,2DAA2D;AAC3D,qBAAa,cAAc;;gBAKd,IAAI,EAAE;QAAE,YAAY,EAAE,MAAM,CAAA;KAAE,GAAG;QAAE,QAAQ,EAAE,YAAY,CAAA;KAAE;IAUvE,sEAAsE;IACtE,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAOpD,wEAAwE;IACxE,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,SAAK,GAAG,MAAM,GAAG,IAAI;IAiB5D,KAAK,IAAI,IAAI;CAGb;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,cAAc,EAAE,IAAI,GAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,SAAS,CAMtG"}

package/out/index.js

@@ -0,0 +1,77 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `@mailwoman/un-locode-lookup` — place → UN/LOCODE (UNECE Code for Trade and Transport Locations).
+ *   Two ways in: by country + place name (exact, diacritic-folded), or by nearest coordinate (for
+ *   the ~⅓ of entries that carry one). Backed by a `node:sqlite` table built from the UNECE code
+ *   list. An `@mailwoman/annotations` `Annotator`.
+ */
+import { DatabaseSync } from "node:sqlite";
+/** Fold a place name to its match key: strip diacritics, lowercase, collapse whitespace. */
+export function foldName(name) {
+    return name.normalize("NFD").replace(/[̀-ͯ]/g, "").toLowerCase().trim().replace(/\s+/g, " ");
+}
+/** Parse a UN/LOCODE coordinate (`"4923N 01522E"`) to decimal degrees, or null if absent/malformed. */
+export function parseUnLocodeCoords(raw) {
+    const m = raw.trim().match(/^(\d{2})(\d{2})([NS])\s+(\d{3})(\d{2})([EW])$/);
+    if (!m)
+        return null;
+    const lat = (Number(m[1]) + Number(m[2]) / 60) * (m[3] === "S" ? -1 : 1);
+    const lon = (Number(m[4]) + Number(m[5]) / 60) * (m[6] === "W" ? -1 : 1);
+    return { lat, lon };
+}
+const EARTH_R_KM = 6371;
+function haversineKm(aLat, aLon, bLat, bLon) {
+    const dLat = ((bLat - aLat) * Math.PI) / 180;
+    const dLon = ((bLon - aLon) * Math.PI) / 180;
+    const s = Math.sin(dLat / 2) ** 2 +
+        Math.cos((aLat * Math.PI) / 180) * Math.cos((bLat * Math.PI) / 180) * Math.sin(dLon / 2) ** 2;
+    return 2 * EARTH_R_KM * Math.asin(Math.sqrt(s));
+}
+/** A UN/LOCODE lookup over a built `node:sqlite` table. */
+export class UnLocodeLookup {
+    #db;
+    #byName;
+    #byBox;
+    constructor(opts) {
+        this.#db = "database" in opts ? opts.database : new DatabaseSync(opts.databasePath, { readOnly: true });
+        this.#byName = this.#db.prepare("SELECT country, location FROM un_locode WHERE country = ? AND nameNorm = ? LIMIT 1");
+        this.#byBox = this.#db.prepare("SELECT location, country, lat, lon FROM un_locode WHERE lat BETWEEN ? AND ? AND lon BETWEEN ? AND ?");
+    }
+    /** The UN/LOCODE (`"US NYC"`) for a country + place name, or null. */
+    byName(country, name) {
+        const row = this.#byName.get(country.toUpperCase(), foldName(name));
+        return row ? `${row.country} ${row.location}` : null;
+    }
+    /** The nearest coordinate-bearing UN/LOCODE within `maxKm`, or null. */
+    nearest(lat, lon, maxKm = 25) {
+        const dLat = maxKm / 111;
+        const dLon = maxKm / (111 * Math.max(0.01, Math.cos((lat * Math.PI) / 180)));
+        const rows = this.#byBox.all(lat - dLat, lat + dLat, lon - dLon, lon + dLon);
+        let best = null;
+        for (const r of rows) {
+            const km = haversineKm(lat, lon, r.lat, r.lon);
+            if (km <= maxKm && (!best || km < best.km))
+                best = { code: `${r.country} ${r.location}`, km };
+        }
+        return best?.code ?? null;
+    }
+    close() {
+        this.#db.close();
+    }
+}
+/**
+ * Build an `Annotator` filling `AnnotationSet.unLocode`. Prefers a country + place-name match (when
+ * the resolver supplies them via `countryCode` / `placeName`), and falls back to the nearest
+ * coordinate.
+ */
+export function makeUnLocodeAnnotator(lookup, opts = {}) {
+    return ({ lat, lon, countryCode, placeName }) => {
+        const byName = countryCode && placeName ? lookup.byName(countryCode, placeName) : null;
+        const code = byName ?? lookup.nearest(lat, lon, opts.maxKm);
+        return code ? { unLocode: code } : {};
+    };
+}
+//# sourceMappingURL=index.js.map

package/out/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@mailwoman/un-locode-lookup",
+  "version": "4.15.1",
+  "description": "Place → UN/LOCODE (UNECE Code for Trade and Transport Locations), by country + name or nearest coordinate. node:sqlite over the UNECE code list. An @mailwoman/annotations Annotator.",
+  "license": "AGPL-3.0-only",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/sister-software/mailwoman.git",
+    "directory": "un-locode-lookup"
+  },
+  "type": "module",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": "./out/index.js",
+    "./build": "./out/build.js"
+  },
+  "dependencies": {
+    "@mailwoman/annotations": "4.15.1",
+    "csv-parse": "^5.6.0"
+  },
+  "files": [
+    "out/**/*.js",
+    "out/**/*.js.map",
+    "out/**/*.d.ts",
+    "out/**/*.d.ts.map",
+    "README.md"
+  ],
+  "bin": "./out/cli.js",
+  "publishConfig": {
+    "access": "public"
+  }
+}