js-zip-code-locator 1.0.0

package/PUBLISH.md

@@ -0,0 +1,27 @@
+# Publishing js-zip-code-locator to npm
+
+Same flow as [git-config-parser](https://www.npmjs.com/package/git-config-parser): unscoped package, standard publish.
+
+## Commands (from package root)
+
+```bash
+# 1. Go to the package folder
+cd "/Users/fred/DEVELOPMENT/OPEN SOURCE/js-zip-code-locator"
+
+# 2. Log in to npm (if you aren’t already)
+npm login
+
+# 3. Run tests
+npm test
+
+# 4. Publish
+npm publish
+```
+
+That’s it. The package will be at **https://www.npmjs.com/package/js-zip-code-locator**.
+
+## Updating after changes
+
+1. Bump version in `package.json` (e.g. `1.0.0` → `1.0.1` or `1.1.0`).
+2. Run `npm test`.
+3. Run `npm publish` again.

package/README.md

@@ -0,0 +1,200 @@
+# js-zip-code-locator
+
+Node.js module for US ZIP code lookups: full data, coordinates, lookup by city/state, closest zips by radius, data by coordinates, distance between zips, state/city discovery, validation, bounding box, and more. Distances can be in **miles** (default) or **kilometers**.
+
+Installable as a dependency in other projects.
+
+## Install
+
+```bash
+npm install js-zip-code-locator
+```
+
+## Usage
+
+The module initializes with an optional unit: **miles** (default) or **kilometers**.
+
+```js
+const createZipLocator = require('js-zip-code-locator');
+
+// Default: distances in miles
+const locator = createZipLocator();
+
+// Distances in kilometers
+const locatorKm = createZipLocator({ useMiles: false });
+```
+
+You can also use the default instance without calling the factory:
+
+```js
+const zipLocator = require('js-zip-code-locator');
+zipLocator.getZipData('10001');
+```
+
+---
+
+## API Reference
+
+### Lookup by ZIP
+
+| Method | Description |
+|--------|-------------|
+| **`getZipData(zipCode)`** | Full record: state, city, lat, lng, and full state name. One object or `undefined`. |
+| **`getZipCoordinates(zipCode)`** | `{ latitude, longitude }` or `undefined`. |
+| **`getCityState(zipCode)`** | `{ city, state, formatted: "City, ST" }` or `undefined`. For labels. |
+| **`isValidZip(zipCode)`** | `true` if the zip exists in the dataset, `false` otherwise. |
+
+### Lookup by city / state
+
+| Method | Description |
+|--------|-------------|
+| **`getZipCodes(city, state)`** | All zip codes (with coordinates) for a city and state. Array; can be multiple. |
+| **`getZipsInState(state)`** | All zip codes (with coordinates) in a state. |
+| **`getCitiesInState(state)`** | Unique city names in a state, sorted. |
+| **`getFullStateName(stateAbbr)`** | Full state name for abbreviation (e.g. `'AL'` → `'Alabama'`). |
+
+### Search and filters
+
+| Method | Description |
+|--------|-------------|
+| **`searchZipPrefix(prefix)`** | Zips whose code starts with `prefix` (e.g. `'100'` for NYC area). |
+| **`getZipsInBoundingBox(minLat, maxLat, minLng, maxLng)`** | All zips inside the given rectangle (e.g. map viewport). |
+
+### Distance and radius
+
+| Method | Description |
+|--------|-------------|
+| **`getClosestByZipCode(zipCode, radius, useMiles?)`** | Zips within `radius` of a zip, with distance. Unit: instance default or override. |
+| **`getDataByCoordinates(lat, lng, options?)`** | All zips with distance from `(lat, lng)`. Options: `{ sort: 'distance' \| 'zip' \| 'city' }`. |
+| **`getDistanceBetweenZipCodes(zip1, zip2, useMiles?)`** | Distance between two zips. `undefined` if either zip not found. |
+| **`getDistancesFromZip(originZip, zipCodes, useMiles?)`** | Distances from one origin zip to many zips in one call. |
+
+---
+
+## Examples
+
+### By ZIP code
+
+```js
+const locator = createZipLocator();
+
+locator.getZipData('35004');
+// { zip: '35004', latitude: 33.606379, longitude: -86.50249, city: 'Moody', state: 'AL', full: 'Alabama' }
+
+locator.getZipCoordinates('35004');
+// { latitude: 33.606379, longitude: -86.50249 }
+
+locator.getCityState('35004');
+// { city: 'Moody', state: 'AL', formatted: 'Moody, AL' }
+
+locator.isValidZip('35004');   // true
+locator.isValidZip('99999');   // false
+```
+
+### By city and state
+
+```js
+locator.getZipCodes('Moody', 'AL');
+// [ { zip: '35004', latitude: ..., longitude: ..., city: 'Moody', state: 'AL', full: 'Alabama' }, ... ]
+
+locator.getZipsInState('AL');
+// [ { zip: '35004', ... }, { zip: '35005', ... }, ... ]  (all zips in Alabama)
+
+locator.getCitiesInState('AL');
+// [ 'Adamsville', 'Adger', 'Alabaster', 'Alexander City', ... ]
+
+locator.getFullStateName('AL');   // 'Alabama'
+locator.getFullStateName('al');   // 'Alabama'
+```
+
+### Search and bounding box
+
+```js
+locator.searchZipPrefix('100');
+// [ { zip: '10001', ... }, { zip: '10002', ... }, ... ]  (NYC area)
+
+locator.getZipsInBoundingBox(33.5, 34, -87, -86);
+// [ { zip: '35004', ... }, ... ]  (zips inside the lat/lng rectangle)
+```
+
+### Distance and radius
+
+```js
+locator.getClosestByZipCode('35004', 10);
+// [ { zip: '35004', ..., distance: 0 }, { zip: '35005', ..., distance: 5.2 }, ... ]
+
+locator.getClosestByZipCode('35004', 16, false);  // radius and distance in km
+
+locator.getDataByCoordinates(33.6, -86.5, { sort: 'distance' });
+// [ { zip: '...', ..., distance: 2.1 }, ... ]
+
+locator.getDataByCoordinates(33.6, -86.5, { sort: 'zip' });   // sort by zip
+locator.getDataByCoordinates(33.6, -86.5, { sort: 'city' });  // sort by city
+
+locator.getDistanceBetweenZipCodes('35004', '35007');
+// 12.34 (miles)
+
+locator.getDistanceBetweenZipCodes('35004', '35007', false);
+// 19.86 (km)
+
+locator.getDistancesFromZip('35004', ['35007', '35005', '99999']);
+// [ { zip: '35007', distance: 12.34 }, { zip: '35005', distance: 5.2 }, { zip: '99999', distance: undefined } ]
+```
+
+### Custom data file
+
+```js
+const locator = createZipLocator({ dataPath: '/path/to/zip-codes.json' });
+```
+
+Expected JSON format: array of objects with `zip`, `latitude`, `longitude`, `city`, `state`, and optional `full`.
+
+---
+
+## Testing this project locally
+
+1. **Clone and install** (if not already):
+
+   ```bash
+   cd js-zip-code-locator
+   npm install
+   ```
+
+2. **Run the test suite**:
+
+   ```bash
+   npm test
+   ```
+
+   This runs Node’s built-in test runner (`node --test`) on the files in `test/`. No extra test framework is required.
+
+3. **Run a single test file** (optional):
+
+   ```bash
+   node --test test/index.js
+   ```
+
+4. **Try the API in Node** (optional):
+
+   ```bash
+   node -e "
+   const createZipLocator = require('.');
+   const locator = createZipLocator();
+   console.log(locator.getZipData('35004'));
+   console.log(locator.getCityState('35004'));
+   console.log(locator.getFullStateName('AL'));
+   console.log(locator.getDistanceBetweenZipCodes('35004', '35007'));
+   "
+   ```
+
+## Contributing
+
+Contributions are welcome. Anyone can contribute.
+
+- Open an issue to discuss changes or report bugs
+- Submit pull requests for fixes or new features
+- Ensure tests pass with `npm test` before submitting
+
+## License
+
+MIT

package/index.js

@@ -0,0 +1,349 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const EARTH_RADIUS_MILES = 3958;
+const EARTH_RADIUS_KM = 6371;
+const DEFAULT_DATA_PATH = path.join(__dirname, 'zip-codes.json');
+
+/**
+ * Normalize zip to 5-character string (zero-padded).
+ * @param {string|number} zip
+ * @returns {string}
+ */
+function normalizeZip(zip) {
+  const s = String(zip).trim();
+  return s.length <= 5 ? s.padStart(5, '0') : s.slice(0, 5);
+}
+
+/**
+ * Haversine distance between two lat/lng points.
+ * @param {number} lat1
+ * @param {number} lng1
+ * @param {number} lat2
+ * @param {number} lng2
+ * @param {boolean} [useMiles=true]
+ * @returns {number}
+ */
+function haversineDistance(lat1, lng1, lat2, lng2, useMiles = true) {
+  const toRad = (x) => (x * Math.PI) / 180;
+  const R = useMiles ? EARTH_RADIUS_MILES : EARTH_RADIUS_KM;
+  const dLat = toRad(lat2 - lat1);
+  const dLng = toRad(lng2 - lng1);
+  const a =
+    Math.sin(dLat / 2) * Math.sin(dLat / 2) +
+    Math.cos(toRad(lat1)) * Math.cos(toRad(lat2)) * Math.sin(dLng / 2) * Math.sin(dLng / 2);
+  const c = 2 * Math.atan2(Math.sqrt(a), Math.sqrt(1 - a));
+  return R * c;
+}
+
+/** @deprecated Use haversineDistance(..., useMiles) */
+function distanceMiles(lat1, lng1, lat2, lng2) {
+  return haversineDistance(lat1, lng1, lat2, lng2, true);
+}
+
+/**
+ * Normalize city/state for index key (lowercase, trimmed).
+ * @param {string} city
+ * @param {string} state
+ * @returns {string}
+ */
+function cityStateKey(city, state) {
+  return `${String(city).toLowerCase().trim()}|${String(state).toLowerCase().trim()}`;
+}
+
+/**
+ * Normalize state to 2-char uppercase for indexing.
+ * @param {string} state
+ * @returns {string}
+ */
+function normalizeState(state) {
+  return String(state).toUpperCase().trim().slice(0, 2);
+}
+
+/**
+ * Load and index zip data from a JSON file.
+ * Expected format: array of { zip, latitude, longitude, city, state, full }.
+ *
+ * @param {string} [dataPath] - Path to zip-codes.json.
+ * @returns {object} Internal indexed data (byZip, byCityState, list).
+ */
+function loadZipData(dataPath = DEFAULT_DATA_PATH) {
+  const raw = JSON.parse(fs.readFileSync(dataPath, 'utf8'));
+  if (!Array.isArray(raw)) {
+    throw new Error('Zip data must be an array of objects');
+  }
+
+  const list = raw.map((r) => ({
+    zip: normalizeZip(r.zip),
+    latitude: Number(r.latitude),
+    longitude: Number(r.longitude),
+    city: String(r.city ?? '').trim(),
+    state: String(r.state ?? '').trim(),
+    full: String(r.full ?? '').trim(),
+  }));
+
+  const byZip = new Map();
+  for (const r of list) {
+    if (!byZip.has(r.zip)) byZip.set(r.zip, r);
+  }
+
+  const byCityState = new Map();
+  for (const r of list) {
+    const key = cityStateKey(r.city, r.state);
+    if (!byCityState.has(key)) byCityState.set(key, []);
+    byCityState.get(key).push(r);
+  }
+
+  const byState = new Map();
+  for (const r of list) {
+    const key = normalizeState(r.state);
+    if (!byState.has(key)) byState.set(key, []);
+    byState.get(key).push(r);
+  }
+
+  const byStateAbbr = new Map();
+  for (const r of list) {
+    const key = normalizeState(r.state);
+    if (!byStateAbbr.has(key)) byStateAbbr.set(key, r.full);
+  }
+
+  return { list, byZip, byCityState, byState, byStateAbbr };
+}
+
+/**
+ * Create a zip locator API. Module initializes with optional system of counting (miles or kilometers; default is miles).
+ *
+ * @param {object} [options]
+ * @param {boolean} [options.useMiles=true] - If true, distances are in miles; if false, in kilometers.
+ * @param {string} [options.dataPath] - Path to zip-codes.json. Defaults to bundled zip-codes.json.
+ * @returns {object} API with getZipData, getZipCoordinates, getZipCodes, getClosestByZipCode, getDataByCoordinates, getDistanceBetweenZipCodes
+ */
+function createZipLocator(options = {}) {
+  const useMiles = options.useMiles !== false;
+  const dataPath = options.dataPath ?? DEFAULT_DATA_PATH;
+  const { list, byZip, byCityState, byState, byStateAbbr } = loadZipData(dataPath);
+
+  return {
+    /**
+     * Returns full data for a zip code (state, city, lat & lng). Returns only one entry per zip.
+     * @param {string|number} zipCode
+     * @returns {object|undefined} { zip, latitude, longitude, city, state, full } or undefined
+     */
+    getZipData(zipCode) {
+      const zip = normalizeZip(zipCode);
+      return byZip.get(zip);
+    },
+
+    /**
+     * Returns coordinates (lat & lng) for a zip code.
+     * @param {string|number} zipCode
+     * @returns {{ latitude: number, longitude: number }|undefined}
+     */
+    getZipCoordinates(zipCode) {
+      const r = byZip.get(normalizeZip(zipCode));
+      return r == null ? undefined : { latitude: r.latitude, longitude: r.longitude };
+    },
+
+    /**
+     * Returns all zip codes and coordinates for a city and state (can return multiple entries).
+     * @param {string} city
+     * @param {string} state
+     * @returns {Array<{ zip, latitude, longitude, city, state, full }>}
+     */
+    getZipCodes(city, state) {
+      const key = cityStateKey(city, state);
+      return byCityState.get(key) ?? [];
+    },
+
+    /**
+     * Returns zips within radius of the given zip, with distance. Radius and returned distance use miles or km based on useMiles.
+     * @param {string|number} zipCode - Center zip
+     * @param {number} radius - Radius in miles (if useMiles true) or kilometers (if false)
+     * @param {boolean} [useMilesOverride] - Override instance default for this call (true = miles, false = km)
+     * @returns {Array<{ zip, latitude, longitude, city, state, full, distance }>} distance in miles or km
+     */
+    getClosestByZipCode(zipCode, radius, useMilesOverride) {
+      const inMiles = useMilesOverride !== undefined ? useMilesOverride : useMiles;
+      const center = byZip.get(normalizeZip(zipCode));
+      if (!center) return [];
+      const results = [];
+      for (const r of list) {
+        const d = haversineDistance(center.latitude, center.longitude, r.latitude, r.longitude, inMiles);
+        if (d <= radius) results.push({ ...r, distance: d });
+      }
+      results.sort((a, b) => a.distance - b.distance);
+      return results;
+    },
+
+    /**
+     * Returns zip records with distance from (lat, lng), sorted by option. Distance unit follows instance setting.
+     * @param {number} lat - Latitude
+     * @param {number} lng - Longitude
+     * @param {object} [options] - { sort: 'distance' | 'zip' | 'city' } (default: 'distance')
+     * @returns {Array<{ zip, latitude, longitude, city, state, full, distance }>}
+     */
+    getDataByCoordinates(lat, lng, options = {}) {
+      const sort = options.sort ?? 'distance';
+      const withDistance = list.map((r) => ({
+        ...r,
+        distance: haversineDistance(lat, lng, r.latitude, r.longitude, useMiles),
+      }));
+      if (sort === 'distance') {
+        withDistance.sort((a, b) => a.distance - b.distance);
+      } else if (sort === 'zip') {
+        withDistance.sort((a, b) => a.zip.localeCompare(b.zip));
+      } else if (sort === 'city') {
+        withDistance.sort((a, b) =>
+          a.city.localeCompare(b.city) || a.state.localeCompare(b.state)
+        );
+      }
+      return withDistance;
+    },
+
+    /**
+     * Returns distance between two zip codes.
+     * @param {string|number} zip1
+     * @param {string|number} zip2
+     * @param {boolean} [useMilesOverride] - true = miles, false = km (default: use instance setting)
+     * @returns {number|undefined} Distance in miles or km, or undefined if either zip not found
+     */
+    getDistanceBetweenZipCodes(zip1, zip2, useMilesOverride) {
+      const inMiles = useMilesOverride !== undefined ? useMilesOverride : useMiles;
+      const a = byZip.get(normalizeZip(zip1));
+      const b = byZip.get(normalizeZip(zip2));
+      if (!a || !b) return undefined;
+      return haversineDistance(a.latitude, a.longitude, b.latitude, b.longitude, inMiles);
+    },
+
+    /**
+     * Returns all zip codes (with coordinates) in a state.
+     * @param {string} state - Two-letter state abbreviation (e.g. 'AL', 'NY')
+     * @returns {Array<{ zip, latitude, longitude, city, state, full }>}
+     */
+    getZipsInState(state) {
+      const key = normalizeState(state);
+      return byState.get(key) ?? [];
+    },
+
+    /**
+     * Returns unique city names in a state (sorted).
+     * @param {string} state - Two-letter state abbreviation
+     * @returns {string[]}
+     */
+    getCitiesInState(state) {
+      const key = normalizeState(state);
+      const records = byState.get(key) ?? [];
+      const cities = [...new Set(records.map((r) => r.city).filter(Boolean))];
+      return cities.sort((a, b) => a.localeCompare(b));
+    },
+
+    /**
+     * Returns true if the zip code exists in the dataset.
+     * @param {string|number} zipCode
+     * @returns {boolean}
+     */
+    isValidZip(zipCode) {
+      return byZip.has(normalizeZip(zipCode));
+    },
+
+    /**
+     * Returns zip records whose zip code starts with the given prefix (e.g. '100' for NYC area).
+     * @param {string} prefix - Zip prefix (e.g. '100', '350')
+     * @returns {Array<{ zip, latitude, longitude, city, state, full }>}
+     */
+    searchZipPrefix(prefix) {
+      const p = String(prefix).trim();
+      if (!p) return [];
+      return list.filter((r) => r.zip.startsWith(p));
+    },
+
+    /**
+     * Returns zip records inside the given bounding box (inclusive).
+     * @param {number} minLat - Minimum latitude
+     * @param {number} maxLat - Maximum latitude
+     * @param {number} minLng - Minimum longitude
+     * @param {number} maxLng - Maximum longitude
+     * @returns {Array<{ zip, latitude, longitude, city, state, full }>}
+     */
+    getZipsInBoundingBox(minLat, maxLat, minLng, maxLng) {
+      const latMin = Math.min(minLat, maxLat);
+      const latMax = Math.max(minLat, maxLat);
+      const lngMin = Math.min(minLng, maxLng);
+      const lngMax = Math.max(minLng, maxLng);
+      return list.filter(
+        (r) =>
+          r.latitude >= latMin &&
+          r.latitude <= latMax &&
+          r.longitude >= lngMin &&
+          r.longitude <= lngMax
+      );
+    },
+
+    /**
+     * Returns distances from an origin zip to multiple target zips in one call.
+     * @param {string|number} originZip - Origin zip code
+     * @param {Array<string|number>} zipCodes - Target zip codes
+     * @param {boolean} [useMilesOverride] - true = miles, false = km (default: instance setting)
+     * @returns {Array<{ zip: string, distance: number|undefined }>} Same order as zipCodes; distance undefined if zip not found
+     */
+    getDistancesFromZip(originZip, zipCodes, useMilesOverride) {
+      const inMiles = useMilesOverride !== undefined ? useMilesOverride : useMiles;
+      const origin = byZip.get(normalizeZip(originZip));
+      if (!origin) return zipCodes.map((z) => ({ zip: normalizeZip(z), distance: undefined }));
+      return zipCodes.map((z) => {
+        const zip = normalizeZip(z);
+        const target = byZip.get(zip);
+        const distance =
+          target == null
+            ? undefined
+            : haversineDistance(
+                origin.latitude,
+                origin.longitude,
+                target.latitude,
+                target.longitude,
+                inMiles
+              );
+        return { zip, distance };
+      });
+    },
+
+    /**
+     * Returns city and state for a zip code (for display).
+     * @param {string|number} zipCode
+     * @returns {{ city: string, state: string, formatted: string }|undefined} formatted is "City, ST"
+     */
+    getCityState(zipCode) {
+      const r = byZip.get(normalizeZip(zipCode));
+      if (!r) return undefined;
+      return {
+        city: r.city,
+        state: r.state,
+        formatted: `${r.city}, ${r.state}`,
+      };
+    },
+
+    /**
+     * Returns full state name for a two-letter abbreviation (e.g. 'AL' -> 'Alabama').
+     * @param {string} stateAbbr - Two-letter state code
+     * @returns {string|undefined}
+     */
+    getFullStateName(stateAbbr) {
+      const key = normalizeState(stateAbbr);
+      return byStateAbbr.get(key);
+    },
+  };
+}
+
+// Default instance (miles) for backward compatibility and simple use
+const defaultInstance = createZipLocator();
+
+module.exports = createZipLocator;
+module.exports.createZipLocator = createZipLocator;
+module.exports.loadZipData = loadZipData;
+module.exports.normalizeZip = normalizeZip;
+module.exports.distanceMiles = distanceMiles;
+module.exports.haversineDistance = haversineDistance;
+// Attach default API to module for require('js-zip-code-locator').getZipData(...)
+Object.assign(module.exports, defaultInstance);

package/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "js-zip-code-locator",
+  "version": "1.0.0",
+  "description": "Node.js module for ZIP code lookups: data, coordinates, by city/state, closest by radius, by coordinates",
+  "main": "index.js",
+  "scripts": {
+    "test": "node --test test/"
+  },
+  "keywords": ["zip", "zipcode", "coordinates", "geolocation", "usa"],
+  "license": "MIT"
+}