postalcode-geocode 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mg-solutions
+
+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.

package/README.md

@@ -0,0 +1,78 @@
+# postalcode-geocode
+
+Resolve **global postal / ZIP codes** to latitude, longitude, and IANA timezone using [GeoNames](https://www.geonames.org/) data.
+
+The npm package is small. On first use (or `postalcode-geocode setup`) it downloads the GeoNames postal dump (~19 MB), builds a local SQLite cache, then works **offline**.
+
+## Install
+
+```bash
+npm install postalcode-geocode
+```
+
+Requires **Node.js ≥ 22.5** (uses built-in `node:sqlite`).
+
+## Setup
+
+```bash
+npx postalcode-geocode setup
+```
+
+Or the first `lookupPostalCode()` call will download automatically.
+
+Data directory:
+
+- Windows: `%LOCALAPPDATA%\postalcode-geocode\`
+- macOS/Linux: `~/.cache/postalcode-geocode/`
+- Override: `POSTALCODE_GEOCODE_DATA_DIR`
+
+## Usage
+
+```js
+import { lookupPostalCode, toHebcalLocation } from 'postalcode-geocode';
+
+const place = await lookupPostalCode('10952');
+// {
+//   postalCode: '10952',
+//   countryCode: 'US',
+//   placeName: 'Monsey',
+//   admin1: 'New York',
+//   latitude: 41.11…,
+//   longitude: -74.08…,
+//   tzid: 'America/New_York',
+//   accuracy: …
+// }
+
+// Optional: convert for @hebcal/core zmanim
+import '@hebcal/core'; // peer dependency
+const location = await toHebcalLocation(place);
+```
+
+### API
+
+| Function | Description |
+|----------|-------------|
+| `lookupPostalCode(code, countryCode?)` | Look up a postal/ZIP. US 5-digit codes work without country. |
+| `ensureData({ force? })` | Download + build cache |
+| `getDataPath()` / `dataReady()` | Cache location / readiness |
+| `toHebcalLocation(result)` | Build `@hebcal/core` `Location` (optional peer) |
+
+### CLI
+
+```bash
+postalcode-geocode setup
+postalcode-geocode lookup 10952
+postalcode-geocode lookup SW1A GB
+postalcode-geocode path
+```
+
+## Attribution
+
+Postal code data © [GeoNames](https://www.geonames.org/) under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/). Please credit GeoNames if you use this package.
+
+Timezone resolution via [`geo-tz`](https://www.npmjs.com/package/geo-tz).
+
+## Notes
+
+- UK / Canada / Netherlands entries in `allCountries.zip` may be outward codes only (not full unit-level postcodes). See the [GeoNames postal readme](https://download.geonames.org/export/zip/readme.txt).
+- Coordinates are estimates from GeoNames (accuracy field 1–6).

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "postalcode-geocode",
+  "version": "1.0.0",
+  "description": "Resolve global postal/ZIP codes to lat/lon/timezone using GeoNames (download-once local cache)",
+  "type": "module",
+  "main": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "bin": {
+    "postalcode-geocode": "./src/cli.js"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22.5.0"
+  },
+  "scripts": {
+    "setup": "node src/cli.js setup",
+    "test": "node --test test/*.test.js",
+    "prepublishOnly": "node --test test/*.test.js"
+  },
+  "keywords": [
+    "postal",
+    "zip",
+    "geocode",
+    "geonames",
+    "timezone",
+    "coordinates",
+    "hebcal"
+  ],
+  "author": "mg-solutions",
+  "license": "MIT",
+  "dependencies": {
+    "geo-tz": "^8.1.8",
+    "yauzl": "^3.2.0"
+  },
+  "peerDependencies": {
+    "@hebcal/core": ">=5.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@hebcal/core": {
+      "optional": true
+    }
+  }
+}

package/src/cli.js

@@ -0,0 +1,91 @@
+#!/usr/bin/env node
+import {
+  ensureData,
+  lookupPostalCode,
+  getDataPath,
+  getDbPath,
+  dataReady,
+} from './index.js';
+
+function printHelp() {
+  console.log(`postalcode-geocode — GeoNames postal/ZIP → lat/lon/timezone
+
+Usage:
+  postalcode-geocode setup              Download GeoNames data + build local cache
+  postalcode-geocode setup --force      Rebuild even if cache exists
+  postalcode-geocode lookup <code> [CC] Look up a postal code (CC = country, e.g. US)
+  postalcode-geocode path               Print data directory
+  postalcode-geocode help
+
+Examples:
+  postalcode-geocode setup
+  postalcode-geocode lookup 10952
+  postalcode-geocode lookup 10952 US
+  postalcode-geocode lookup SW1A GB
+`);
+}
+
+async function main(argv) {
+  const cmd = argv[0] || 'help';
+
+  if (cmd === 'help' || cmd === '--help' || cmd === '-h') {
+    printHelp();
+    return;
+  }
+
+  if (cmd === 'path') {
+    console.log(getDataPath());
+    console.log('db:', getDbPath());
+    console.log('ready:', dataReady());
+    return;
+  }
+
+  if (cmd === 'setup') {
+    const force = argv.includes('--force');
+    const result = await ensureData({
+      force,
+      onProgress: (event, info) => {
+        if (event === 'cache-hit') {
+          console.log('Cache already present:', info.path);
+        } else if (event === 'download-start') {
+          console.log('Downloading', info.url, '…');
+        } else if (event === 'download-done') {
+          console.log('Download complete.');
+        } else if (event === 'build-start') {
+          console.log('Building SQLite index…');
+        } else if (event === 'build-progress') {
+          console.log(`  … ${info.rows} rows`);
+        } else if (event === 'index-start') {
+          console.log(`Creating indexes (${info.rows} rows)…`);
+        } else if (event === 'done') {
+          console.log(`Done. ${info.rows} postal codes → ${info.path}`);
+        }
+      },
+    });
+    if (result.cached) {
+      console.log('Nothing to do.');
+    }
+    return;
+  }
+
+  if (cmd === 'lookup') {
+    const code = argv[1];
+    const country = argv[2];
+    if (!code) {
+      console.error('Usage: postalcode-geocode lookup <code> [countryCode]');
+      process.exit(1);
+    }
+    const result = await lookupPostalCode(code, country);
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+
+  console.error(`Unknown command: ${cmd}`);
+  printHelp();
+  process.exit(1);
+}
+
+main(process.argv.slice(2)).catch((err) => {
+  console.error(err.message || err);
+  process.exit(1);
+});

package/src/ensureData.js

@@ -0,0 +1,178 @@
+import fs from 'node:fs';
+import fsp from 'node:fs/promises';
+import path from 'node:path';
+import { createWriteStream } from 'node:fs';
+import { pipeline } from 'node:stream/promises';
+import { createInterface } from 'node:readline';
+import { Readable } from 'node:stream';
+import { DatabaseSync } from 'node:sqlite';
+import yauzl from 'yauzl';
+import { getDataPath, getDbPath, getMetaPath, dataReady } from './paths.js';
+
+export const GEONAMES_ZIP_URL =
+  'https://download.geonames.org/export/zip/allCountries.zip';
+
+const DATA_VERSION = 1;
+
+function openZip(filePath) {
+  return new Promise((resolve, reject) => {
+    yauzl.open(filePath, { lazyEntries: true }, (err, zipfile) => {
+      if (err) reject(err);
+      else resolve(zipfile);
+    });
+  });
+}
+
+function zipReadStream(zipfile, entry) {
+  return new Promise((resolve, reject) => {
+    zipfile.openReadStream(entry, (err, stream) => {
+      if (err) reject(err);
+      else resolve(stream);
+    });
+  });
+}
+
+async function downloadFile(url, destPath) {
+  const res = await fetch(url);
+  if (!res.ok) {
+    throw new Error(`Failed to download ${url} (HTTP ${res.status})`);
+  }
+  await pipeline(Readable.fromWeb(res.body), createWriteStream(destPath));
+}
+
+/**
+ * Download GeoNames postal dump and build a local SQLite cache.
+ * Safe to call repeatedly; rebuilds by default when force=true or missing.
+ */
+export async function ensureData({ force = false, onProgress } = {}) {
+  if (!force && dataReady()) {
+    onProgress?.('cache-hit', { path: getDbPath() });
+    return { path: getDbPath(), cached: true };
+  }
+
+  const dataDir = getDataPath();
+  await fsp.mkdir(dataDir, { recursive: true });
+
+  const zipPath = path.join(dataDir, 'allCountries.zip');
+  const dbPath = getDbPath();
+  const tmpDbPath = `${dbPath}.building`;
+
+  onProgress?.('download-start', { url: GEONAMES_ZIP_URL });
+  await downloadFile(GEONAMES_ZIP_URL, zipPath);
+  onProgress?.('download-done', { path: zipPath });
+
+  if (fs.existsSync(tmpDbPath)) await fsp.unlink(tmpDbPath);
+  if (fs.existsSync(dbPath)) await fsp.unlink(dbPath);
+
+  onProgress?.('build-start', {});
+  const db = new DatabaseSync(tmpDbPath);
+  db.exec(`
+    PRAGMA journal_mode = OFF;
+    PRAGMA synchronous = OFF;
+    CREATE TABLE postal_codes (
+      country_code TEXT NOT NULL,
+      postal_code TEXT NOT NULL,
+      place_name TEXT,
+      admin1 TEXT,
+      admin1_code TEXT,
+      admin2 TEXT,
+      latitude REAL NOT NULL,
+      longitude REAL NOT NULL,
+      accuracy INTEGER
+    );
+  `);
+
+  const insert = db.prepare(`
+    INSERT INTO postal_codes (
+      country_code, postal_code, place_name, admin1, admin1_code, admin2,
+      latitude, longitude, accuracy
+    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `);
+
+  const zipfile = await openZip(zipPath);
+  let rows = 0;
+
+  await new Promise((resolve, reject) => {
+    zipfile.on('error', reject);
+    zipfile.on('end', resolve);
+    zipfile.on('entry', async (entry) => {
+      try {
+        if (!/allCountries\.txt$/i.test(entry.fileName)) {
+          zipfile.readEntry();
+          return;
+        }
+
+        const stream = await zipReadStream(zipfile, entry);
+        const rl = createInterface({ input: stream, crlfDelay: Infinity });
+
+        db.exec('BEGIN');
+        for await (const line of rl) {
+          if (!line) continue;
+          const parts = line.split('\t');
+          if (parts.length < 12) continue;
+
+          const country = parts[0];
+          const postal = parts[1];
+          const place = parts[2] || null;
+          const admin1 = parts[3] || null;
+          const admin1Code = parts[4] || null;
+          const admin2 = parts[5] || null;
+          const lat = Number(parts[9]);
+          const lon = Number(parts[10]);
+          const accuracy = parts[11] ? Number(parts[11]) : null;
+
+          if (!country || !postal || Number.isNaN(lat) || Number.isNaN(lon)) continue;
+
+          insert.run(
+            country,
+            postal,
+            place,
+            admin1,
+            admin1Code,
+            admin2,
+            lat,
+            lon,
+            Number.isFinite(accuracy) ? accuracy : null,
+          );
+          rows += 1;
+          if (rows % 100000 === 0) {
+            onProgress?.('build-progress', { rows });
+          }
+        }
+        db.exec('COMMIT');
+        zipfile.readEntry();
+      } catch (err) {
+        reject(err);
+      }
+    });
+    zipfile.readEntry();
+  });
+
+  onProgress?.('index-start', { rows });
+  db.exec(`
+    CREATE INDEX idx_postal ON postal_codes (postal_code);
+    CREATE INDEX idx_country_postal ON postal_codes (country_code, postal_code);
+  `);
+  db.close();
+
+  await fsp.rename(tmpDbPath, dbPath);
+
+  const meta = {
+    version: DATA_VERSION,
+    source: GEONAMES_ZIP_URL,
+    attribution: 'GeoNames.org (CC BY 4.0)',
+    builtAt: new Date().toISOString(),
+    rows,
+  };
+  await fsp.writeFile(getMetaPath(), JSON.stringify(meta, null, 2));
+
+  // Keep zip for debugging/rebuild; optional cleanup
+  try {
+    await fsp.unlink(zipPath);
+  } catch {
+    // ignore
+  }
+
+  onProgress?.('done', { path: dbPath, rows });
+  return { path: dbPath, cached: false, rows };
+}

package/src/hebcal.js

@@ -0,0 +1,37 @@
+/**
+ * Convert a postalcode-geocode result into a @hebcal/core Location.
+ * Requires optional peer dependency `@hebcal/core`.
+ */
+export async function toHebcalLocation(result) {
+  let Location;
+  try {
+    ({ Location } = await import('@hebcal/core'));
+  } catch {
+    throw new Error(
+      'toHebcalLocation() requires peer dependency @hebcal/core. Install it with: npm install @hebcal/core',
+    );
+  }
+
+  const nameParts = [
+    result.placeName,
+    result.admin1Code || result.admin1,
+    result.postalCode,
+  ].filter(Boolean);
+  const cityName = nameParts.join(', ');
+  const il = result.countryCode === 'IL';
+
+  const loc = new Location(
+    result.latitude,
+    result.longitude,
+    il,
+    result.tzid,
+    cityName,
+    result.countryCode,
+    result.postalCode,
+  );
+  loc.geo = 'zip';
+  loc.zip = result.postalCode;
+  loc.admin1 = result.admin1Code || result.admin1;
+  loc.stateName = result.admin1;
+  return loc;
+}

package/src/index.js

@@ -0,0 +1,4 @@
+export { lookupPostalCode, closeDb } from './lookup.js';
+export { ensureData, GEONAMES_ZIP_URL } from './ensureData.js';
+export { getDataPath, getDbPath, getMetaPath, dataReady } from './paths.js';
+export { toHebcalLocation } from './hebcal.js';

package/src/lookup.js

@@ -0,0 +1,139 @@
+import { DatabaseSync } from 'node:sqlite';
+import { find as findTimezone } from 'geo-tz';
+import { ensureData } from './ensureData.js';
+import { getDbPath, dataReady } from './paths.js';
+
+let dbSingleton = null;
+
+function getDb() {
+  if (!dbSingleton) {
+    dbSingleton = new DatabaseSync(getDbPath(), { readOnly: true });
+  }
+  return dbSingleton;
+}
+
+/** Close the open DB handle (mainly for tests). */
+export function closeDb() {
+  if (dbSingleton) {
+    dbSingleton.close();
+    dbSingleton = null;
+  }
+}
+
+function normalizePostalCode(code) {
+  return String(code).trim().toUpperCase();
+}
+
+function normalizeCountry(cc) {
+  if (!cc) return null;
+  return String(cc).trim().toUpperCase();
+}
+
+function inferCountryFromCode(code) {
+  // Bare 5-digit (or ZIP+4) → assume US
+  if (/^\d{5}(-\d{4})?$/.test(code)) return 'US';
+  return null;
+}
+
+function rowToResult(row) {
+  const latitude = row.latitude;
+  const longitude = row.longitude;
+  const zones = findTimezone(latitude, longitude);
+  const tzid = zones?.[0];
+  if (!tzid) {
+    throw new Error(
+      `Could not resolve timezone for ${row.postal_code} at ${latitude},${longitude}`,
+    );
+  }
+
+  return {
+    postalCode: row.postal_code,
+    countryCode: row.country_code,
+    placeName: row.place_name || null,
+    admin1: row.admin1 || null,
+    admin1Code: row.admin1_code || null,
+    admin2: row.admin2 || null,
+    latitude,
+    longitude,
+    tzid,
+    accuracy: row.accuracy ?? null,
+  };
+}
+
+/**
+ * Look up a postal/ZIP code.
+ *
+ * @param {string} code Postal or ZIP code (e.g. "10952", "M5V 3L9")
+ * @param {string} [countryCode] ISO-3166 alpha-2 (e.g. "US", "CA"). Optional for US 5-digit ZIPs.
+ * @param {{ ensure?: boolean }} [options] ensure=true (default) downloads GeoNames data if missing
+ * @returns {Promise<object>}
+ */
+export async function lookupPostalCode(code, countryCode, options = {}) {
+  // Support lookupPostalCode(code, { ensure: false })
+  let opts = options;
+  let cc = countryCode;
+  if (cc && typeof cc === 'object' && !Array.isArray(cc)) {
+    opts = cc;
+    cc = undefined;
+  }
+
+  const { ensure = true } = opts;
+  const postal = normalizePostalCode(code);
+  if (!postal) {
+    throw new Error('postal code is required');
+  }
+
+  let country = normalizeCountry(cc) || inferCountryFromCode(postal);
+
+  // US ZIP+4 → use 5-digit prefix for GeoNames
+  let queryPostal = postal;
+  if (country === 'US' && /^\d{5}-\d{4}$/.test(postal)) {
+    queryPostal = postal.slice(0, 5);
+  }
+
+  if (ensure || !dataReady()) {
+    if (!dataReady()) {
+      await ensureData();
+    }
+  } else if (!dataReady()) {
+    throw new Error(
+      'Postal code data is not installed. Run `npx postalcode-geocode setup` first.',
+    );
+  }
+
+  const db = getDb();
+
+  let rows;
+  if (country) {
+    rows = db
+      .prepare(
+        `SELECT * FROM postal_codes
+         WHERE country_code = ? AND postal_code = ?
+         ORDER BY accuracy DESC NULLS LAST
+         LIMIT 5`,
+      )
+      .all(country, queryPostal);
+  } else {
+    rows = db
+      .prepare(
+        `SELECT * FROM postal_codes
+         WHERE postal_code = ?
+         ORDER BY accuracy DESC NULLS LAST
+         LIMIT 5`,
+      )
+      .all(queryPostal);
+  }
+
+  if (!rows.length) {
+    const where = country ? `${country} ${queryPostal}` : queryPostal;
+    throw new Error(`Unknown postal code: ${where}`);
+  }
+
+  // If multiple countries matched without country filter, prefer US then first
+  let chosen = rows[0];
+  if (!country && rows.length > 1) {
+    chosen = rows.find((r) => r.country_code === 'US') || rows[0];
+  }
+
+  return rowToResult(chosen);
+}

package/src/paths.js

@@ -0,0 +1,32 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const PACKAGE_DIR = 'postalcode-geocode';
+const DB_FILENAME = 'postalcodes.sqlite';
+const META_FILENAME = 'meta.json';
+
+/** Directory for the downloaded GeoNames SQLite cache. */
+export function getDataPath() {
+  if (process.env.POSTALCODE_GEOCODE_DATA_DIR) {
+    return path.resolve(process.env.POSTALCODE_GEOCODE_DATA_DIR);
+  }
+  if (process.platform === 'win32') {
+    const base = process.env.LOCALAPPDATA || path.join(os.homedir(), 'AppData', 'Local');
+    return path.join(base, PACKAGE_DIR);
+  }
+  const xdg = process.env.XDG_CACHE_HOME || path.join(os.homedir(), '.cache');
+  return path.join(xdg, PACKAGE_DIR);
+}
+
+export function getDbPath() {
+  return path.join(getDataPath(), DB_FILENAME);
+}
+
+export function getMetaPath() {
+  return path.join(getDataPath(), META_FILENAME);
+}
+
+export function dataReady() {
+  return fs.existsSync(getDbPath()) && fs.existsSync(getMetaPath());
+}