geodata-kit-postal 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,24 @@
+MIT License
+
+Copyright (c) 2026 geodata-kit contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+The code is MIT-licensed. The bundled data keeps the licences of its sources;
+see NOTICE.

package/NOTICE

@@ -0,0 +1,91 @@
+geodata-kit — third-party data notices
+======================================
+
+The code of geodata-kit is MIT-licensed (see LICENSE). The data shipped in
+the packages was generated from the sources below and keeps their licences.
+Every source, its download URL, size, SHA-256 and download date is listed in
+data/meta.json of the repository.
+
+GeoNames
+  Countries, subdivisions, cities, localities, alternate names, airports,
+  timezones per place and postal codes. Data from GeoNames (https://www.geonames.org),
+  licensed under Creative Commons Attribution 4.0 (CC BY 4.0,
+  https://creativecommons.org/licenses/by/4.0/). Modified: filtered,
+  re-keyed and combined with the other sources listed here.
+
+Unicode CLDR
+  Country, language and subdivision names, currencies with dates, retired
+  codes, UN M49 regions, languages per country, likely locales, week and
+  measurement data. Copyright © 1991-2025 Unicode, Inc. Licensed under the
+  Unicode License v3 (https://www.unicode.org/license.txt):
+
+    UNICODE LICENSE V3
+    COPYRIGHT AND PERMISSION NOTICE
+    Copyright © 1991-2025 Unicode, Inc.
+    NOTICE TO USER: Carefully read the following legal agreement. BY
+    DOWNLOADING, INSTALLING, COPYING OR OTHERWISE USING DATA FILES, AND/OR
+    SOFTWARE, YOU UNEQUIVOCALLY ACCEPT, AND AGREE TO BE BOUND BY, ALL OF THE
+    TERMS AND CONDITIONS OF THIS AGREEMENT. IF YOU DO NOT AGREE, DO NOT
+    DOWNLOAD, INSTALL, COPY, DISTRIBUTE OR USE THE DATA FILES OR SOFTWARE.
+    Permission is hereby granted, free of charge, to any person obtaining a
+    copy of data files and any associated documentation (the "Data Files") or
+    software and any associated documentation (the "Software") to deal in the
+    Data Files or Software without restriction, including without limitation
+    the rights to use, copy, modify, merge, publish, distribute, and/or sell
+    copies of the Data Files or Software, and to permit persons to whom the
+    Data Files or Software are furnished to do so, provided that either (a)
+    this copyright and permission notice appear with all copies of the Data
+    Files or Software, or (b) this copyright and permission notice appear in
+    associated Documentation.
+    THE DATA FILES AND SOFTWARE ARE PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
+    KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+    MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OF
+    THIRD PARTY RIGHTS. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR HOLDERS
+    INCLUDED IN THIS NOTICE BE LIABLE FOR ANY CLAIM, OR ANY SPECIAL INDIRECT
+    OR CONSEQUENTIAL DAMAGES, OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF
+    USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+    OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+    PERFORMANCE OF THE DATA FILES OR SOFTWARE.
+    Except as contained in this notice, the name of a copyright holder shall
+    not be used in advertising or otherwise to promote the sale, use or other
+    dealings in these Data Files or Software without prior written
+    authorization of the copyright holder.
+
+IANA Time Zone Database
+  Timezone names, zones per country and legacy aliases, from the IANA Time
+  Zone Database (https://www.iana.org/time-zones), which is in the public domain.
+
+Wikidata
+  Subdivision ISO 3166-2 ↔ GeoNames mapping, official languages of countries
+  and subdivisions, demonyms, calling codes, driving side. From Wikidata
+  (https://www.wikidata.org), dedicated to the public domain under CC0 1.0.
+
+Natural Earth
+  Country and first-level subdivision polygons. Made with Natural Earth.
+  Free vector and raster map data @ naturalearthdata.com (public domain).
+
+libphonenumber
+  Phone-number metadata, converted from PhoneNumberMetadata.xml.
+  Copyright (C) The Libphonenumber Authors. Licensed under the Apache
+  License, Version 2.0 (https://www.apache.org/licenses/LICENSE-2.0).
+  You may not use this data except in compliance with that License. Unless
+  required by applicable law or agreed to in writing, it is distributed on
+  an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND.
+
+Google address metadata (libaddressinput)
+  Address formats, required fields, postal-code patterns and region lists.
+  Data from Google's libaddressinput project
+  (https://github.com/google/libaddressinput), licensed under CC BY 4.0.
+  Modified: merged with GeoNames postal formats.
+
+European Union / EFTA
+  EU, Eurozone, Schengen, EEA and EFTA membership dates, compiled from
+  europa.eu (© European Union, CC BY 4.0) and efta.int. Modified.
+
+geodata-kit-tz only
+  Timezone polygons from timezone-boundary-builder
+  (https://github.com/evansiroky/timezone-boundary-builder), based on data
+  © OpenStreetMap contributors, licensed under the Open Database License
+  (ODbL) 1.0 (https://opendatacommons.org/licenses/odbl/1-0/). The ODbL
+  applies to that data, not to the rest of geodata-kit. See LICENSE-DATA in
+  that package.

package/README.md

@@ -1,3 +1,31 @@
-# Temporary Holding Version
+# geodata-kit-postal
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Postal code → place, and place → postal codes, for 124 countries. Node.js only.
+
+```bash
+npm install geodata-kit-postal
+```
+
+```ts
+import { findPlacesByPostalCode, findPostalCodes } from 'geodata-kit-postal';
+
+await findPlacesByPostalCode('80331', 'DE');               // [{ name: 'München', … }]
+await findPostalCodes({ city: 'Unterhaching', country: 'DE' }); // ['82008']
+```
+
+Installed next to [geodata-kit-address](https://www.npmjs.com/package/geodata-kit-address), it
+also lets `parseAddress` check the city against the postal code and fix typos.
+For the UK, Canada and the Netherlands only the first part of the code is
+known ("SW1A", "K1A", "1234").
+
+## API
+
+| Function | Returns |
+|---|---|
+| `findPlacesByPostalCode(code, country)` | async; places `{ postalCode, name, subdivisionName, subdivisionCode, subdivision2Name, subdivision3Name, lat, lng }`. Prefixes such as `D-` and spacing are ignored |
+| `findPostalCodes({ city, country, subdivision? })` | async; postal codes of a place |
+| `isKnownPostalCode(code, country)` | async; `true` / `false` |
+| `listPostalCountries()` | the 124 countries with data |
+| `foldName(text)` | the name folding used for matching |
+
+MIT. Data from GeoNames (CC BY 4.0); see `NOTICE`.

package/dist/index.cjs

@@ -0,0 +1,123 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var src_exports = {};
+__export(src_exports, {
+  findPlacesByPostalCode: () => findPlacesByPostalCode,
+  findPostalCodes: () => findPostalCodes,
+  foldName: () => foldName,
+  isKnownPostalCode: () => isKnownPostalCode,
+  listPostalCountries: () => listPostalCountries
+});
+module.exports = __toCommonJS(src_exports);
+
+// ../../node_modules/tsup/assets/cjs_shims.js
+var getImportMetaUrl = () => typeof document === "undefined" ? new URL(`file:${__filename}`).href : document.currentScript && document.currentScript.tagName.toUpperCase() === "SCRIPT" ? document.currentScript.src : new URL("main.js", document.baseURI).href;
+var importMetaUrl = /* @__PURE__ */ getImportMetaUrl();
+
+// src/index.ts
+var import_node_fs = require("fs");
+var import_promises = require("fs/promises");
+var import_node_zlib = require("zlib");
+var DATA_DIR = new URL("../data/", importMetaUrl);
+var cache = /* @__PURE__ */ new Map();
+var compact = (code) => code.toUpperCase().replace(/[\s-]/g, "");
+function foldName(text) {
+  const special = { "\xDF": "ss", "\u0142": "l", "\u0111": "d", "\xF0": "d", "\xF8": "o", "\xE6": "ae", "\u0153": "oe", "\xFE": "th", "\u0131": "i" };
+  let plain = "";
+  for (const character of text.replace(/['’ʻʼ`´]/g, "").normalize("NFKD").replace(/\p{M}/gu, "").toLowerCase()) {
+    plain += special[character] ?? character;
+  }
+  return plain.replace(/[^\p{L}\p{N}]+/gu, " ").trim().split(" ").filter(Boolean).map((word) => word === "saint" ? "st" : word === "sainte" ? "ste" : word).join(" ");
+}
+function load(country) {
+  const code = country.trim().toUpperCase();
+  let promise = cache.get(code);
+  if (!promise) {
+    promise = (async () => {
+      const file = new URL(`${code}.json.gz`, DATA_DIR);
+      if (!/^[A-Z]{2}$/.test(code) || !(0, import_node_fs.existsSync)(file)) return null;
+      const data = JSON.parse((0, import_node_zlib.gunzipSync)(await (0, import_promises.readFile)(file)).toString("utf8"));
+      const places = data.rows.map((row) => ({
+        postalCode: row[0],
+        name: row[1],
+        subdivisionName: row[2],
+        subdivisionCode: row[3],
+        subdivision2Name: row[4],
+        subdivision3Name: row[5],
+        lat: row[6],
+        lng: row[7]
+      }));
+      const byCode = /* @__PURE__ */ new Map();
+      for (const place of places) {
+        const key = compact(place.postalCode);
+        const list = byCode.get(key);
+        if (list) list.push(place);
+        else byCode.set(key, [place]);
+      }
+      return { places, byCode, codeLengths: [...new Set([...byCode.keys()].map((key) => key.length))].sort((a, b) => b - a) };
+    })();
+    cache.set(code, promise);
+  }
+  return promise;
+}
+function lookup(data, code) {
+  const key = compact(code.trim().replace(/^[A-Z]{1,3}-(?=\d)/i, "").replace(/^〒/, ""));
+  const exact = data.byCode.get(key);
+  if (exact) return exact;
+  for (const length of data.codeLengths) {
+    if (length >= key.length) continue;
+    const partial = data.byCode.get(key.slice(0, length));
+    if (partial) return partial;
+  }
+  return [];
+}
+async function findPlacesByPostalCode(code, country) {
+  const data = await load(country);
+  return data ? lookup(data, code).map((place) => ({ ...place })) : [];
+}
+async function isKnownPostalCode(code, country) {
+  return (await findPlacesByPostalCode(code, country)).length > 0;
+}
+async function findPostalCodes(options) {
+  const data = await load(options.country);
+  if (!data) return [];
+  const key = foldName(options.city);
+  const subdivision = options.subdivision ? foldName(options.subdivision) : null;
+  const codes = /* @__PURE__ */ new Set();
+  for (const place of data.places) {
+    if (foldName(place.name) !== key) continue;
+    if (subdivision && foldName(place.subdivisionName) !== subdivision && foldName(place.subdivisionCode) !== subdivision) continue;
+    codes.add(place.postalCode);
+  }
+  return [...codes].sort();
+}
+function listPostalCountries() {
+  if (!(0, import_node_fs.existsSync)(DATA_DIR)) return [];
+  return (0, import_node_fs.readdirSync)(DATA_DIR).filter((file) => file.endsWith(".json.gz")).map((file) => file.slice(0, 2)).sort();
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  findPlacesByPostalCode,
+  findPostalCodes,
+  foldName,
+  isKnownPostalCode,
+  listPostalCountries
+});

package/dist/index.d.cts

@@ -0,0 +1,32 @@
+interface PostalPlace {
+    postalCode: string;
+    /** Place name as published by the postal service. */
+    name: string;
+    /** First-level subdivision name and code as used by the postal data (the code may differ from ISO 3166-2). */
+    subdivisionName: string;
+    subdivisionCode: string;
+    /** County / district names, where given. */
+    subdivision2Name: string;
+    subdivision3Name: string;
+    lat: number;
+    lng: number;
+}
+/**
+ * Same folding as geodata-kit's fold() (kept identical; a test checks it):
+ * lower case, no accents, no punctuation, "saint" → "st".
+ */
+declare function foldName(text: string): string;
+/** Places with this postal code: ("80331", "DE") → München. Prefixes and spacing are ignored. */
+declare function findPlacesByPostalCode(code: string, country: string): Promise<PostalPlace[]>;
+/** True if the postal code exists in the country's data. */
+declare function isKnownPostalCode(code: string, country: string): Promise<boolean>;
+/** Postal codes of a place: ({ city: 'Unterhaching', country: 'DE' }) → ["82008"]. */
+declare function findPostalCodes(options: {
+    city: string;
+    country: string;
+    subdivision?: string;
+}): Promise<string[]>;
+/** Countries with postal data. */
+declare function listPostalCountries(): string[];
+
+export { type PostalPlace, findPlacesByPostalCode, findPostalCodes, foldName, isKnownPostalCode, listPostalCountries };

package/dist/index.d.ts

@@ -0,0 +1,32 @@
+interface PostalPlace {
+    postalCode: string;
+    /** Place name as published by the postal service. */
+    name: string;
+    /** First-level subdivision name and code as used by the postal data (the code may differ from ISO 3166-2). */
+    subdivisionName: string;
+    subdivisionCode: string;
+    /** County / district names, where given. */
+    subdivision2Name: string;
+    subdivision3Name: string;
+    lat: number;
+    lng: number;
+}
+/**
+ * Same folding as geodata-kit's fold() (kept identical; a test checks it):
+ * lower case, no accents, no punctuation, "saint" → "st".
+ */
+declare function foldName(text: string): string;
+/** Places with this postal code: ("80331", "DE") → München. Prefixes and spacing are ignored. */
+declare function findPlacesByPostalCode(code: string, country: string): Promise<PostalPlace[]>;
+/** True if the postal code exists in the country's data. */
+declare function isKnownPostalCode(code: string, country: string): Promise<boolean>;
+/** Postal codes of a place: ({ city: 'Unterhaching', country: 'DE' }) → ["82008"]. */
+declare function findPostalCodes(options: {
+    city: string;
+    country: string;
+    subdivision?: string;
+}): Promise<string[]>;
+/** Countries with postal data. */
+declare function listPostalCountries(): string[];
+
+export { type PostalPlace, findPlacesByPostalCode, findPostalCodes, foldName, isKnownPostalCode, listPostalCountries };

package/dist/index.js

@@ -0,0 +1,88 @@
+// src/index.ts
+import { existsSync, readdirSync } from "fs";
+import { readFile } from "fs/promises";
+import { gunzipSync } from "zlib";
+var DATA_DIR = new URL("../data/", import.meta.url);
+var cache = /* @__PURE__ */ new Map();
+var compact = (code) => code.toUpperCase().replace(/[\s-]/g, "");
+function foldName(text) {
+  const special = { "\xDF": "ss", "\u0142": "l", "\u0111": "d", "\xF0": "d", "\xF8": "o", "\xE6": "ae", "\u0153": "oe", "\xFE": "th", "\u0131": "i" };
+  let plain = "";
+  for (const character of text.replace(/['’ʻʼ`´]/g, "").normalize("NFKD").replace(/\p{M}/gu, "").toLowerCase()) {
+    plain += special[character] ?? character;
+  }
+  return plain.replace(/[^\p{L}\p{N}]+/gu, " ").trim().split(" ").filter(Boolean).map((word) => word === "saint" ? "st" : word === "sainte" ? "ste" : word).join(" ");
+}
+function load(country) {
+  const code = country.trim().toUpperCase();
+  let promise = cache.get(code);
+  if (!promise) {
+    promise = (async () => {
+      const file = new URL(`${code}.json.gz`, DATA_DIR);
+      if (!/^[A-Z]{2}$/.test(code) || !existsSync(file)) return null;
+      const data = JSON.parse(gunzipSync(await readFile(file)).toString("utf8"));
+      const places = data.rows.map((row) => ({
+        postalCode: row[0],
+        name: row[1],
+        subdivisionName: row[2],
+        subdivisionCode: row[3],
+        subdivision2Name: row[4],
+        subdivision3Name: row[5],
+        lat: row[6],
+        lng: row[7]
+      }));
+      const byCode = /* @__PURE__ */ new Map();
+      for (const place of places) {
+        const key = compact(place.postalCode);
+        const list = byCode.get(key);
+        if (list) list.push(place);
+        else byCode.set(key, [place]);
+      }
+      return { places, byCode, codeLengths: [...new Set([...byCode.keys()].map((key) => key.length))].sort((a, b) => b - a) };
+    })();
+    cache.set(code, promise);
+  }
+  return promise;
+}
+function lookup(data, code) {
+  const key = compact(code.trim().replace(/^[A-Z]{1,3}-(?=\d)/i, "").replace(/^〒/, ""));
+  const exact = data.byCode.get(key);
+  if (exact) return exact;
+  for (const length of data.codeLengths) {
+    if (length >= key.length) continue;
+    const partial = data.byCode.get(key.slice(0, length));
+    if (partial) return partial;
+  }
+  return [];
+}
+async function findPlacesByPostalCode(code, country) {
+  const data = await load(country);
+  return data ? lookup(data, code).map((place) => ({ ...place })) : [];
+}
+async function isKnownPostalCode(code, country) {
+  return (await findPlacesByPostalCode(code, country)).length > 0;
+}
+async function findPostalCodes(options) {
+  const data = await load(options.country);
+  if (!data) return [];
+  const key = foldName(options.city);
+  const subdivision = options.subdivision ? foldName(options.subdivision) : null;
+  const codes = /* @__PURE__ */ new Set();
+  for (const place of data.places) {
+    if (foldName(place.name) !== key) continue;
+    if (subdivision && foldName(place.subdivisionName) !== subdivision && foldName(place.subdivisionCode) !== subdivision) continue;
+    codes.add(place.postalCode);
+  }
+  return [...codes].sort();
+}
+function listPostalCountries() {
+  if (!existsSync(DATA_DIR)) return [];
+  return readdirSync(DATA_DIR).filter((file) => file.endsWith(".json.gz")).map((file) => file.slice(0, 2)).sort();
+}
+export {
+  findPlacesByPostalCode,
+  findPostalCodes,
+  foldName,
+  isKnownPostalCode,
+  listPostalCountries
+};

package/package.json

@@ -1,6 +1,53 @@
 {
   "name": "geodata-kit-postal",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Optional data for geodata-kit: postal code → place and place → postal codes for 124 countries (GeoNames, 1.8 million codes). Node.js only.",
+  "keywords": [
+    "postal-code",
+    "zip-code",
+    "postcode",
+    "geonames",
+    "geodata-kit"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/greta-devhub/geodata-kit.git",
+    "directory": "packages/geodata-kit-postal"
+  },
+  "homepage": "https://github.com/greta-devhub/geodata-kit/tree/main/packages/geodata-kit-postal#readme",
+  "bugs": {
+    "url": "https://github.com/greta-devhub/geodata-kit/issues"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "data",
+    "NOTICE",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup"
+  }
+}