js-zip-code-locator 1.0.0

package/test/index.js

@@ -0,0 +1,308 @@
+'use strict';
+
+const { describe, it } = require('node:test');
+const assert = require('node:assert');
+const path = require('path');
+const createZipLocator = require('..');
+
+const dataPath = path.join(__dirname, '..', 'zip-codes.json');
+
+describe('createZipLocator', () => {
+  const locator = createZipLocator({ dataPath });
+  const locatorKm = createZipLocator({ dataPath, useMiles: false });
+
+  describe('getZipData(zipCode)', () => {
+    it('returns full data (state, city, lat & lng) for a zip code', () => {
+      const data = locator.getZipData('35004');
+      assert.ok(data);
+      assert.strictEqual(data.zip, '35004');
+      assert.strictEqual(data.state, 'AL');
+      assert.strictEqual(data.city, 'Moody');
+      assert.strictEqual(typeof data.latitude, 'number');
+      assert.strictEqual(typeof data.longitude, 'number');
+      assert.strictEqual(data.full, 'Alabama');
+    });
+
+    it('returns only one entry per zip code', () => {
+      const data = locator.getZipData(35007);
+      assert.ok(data);
+      assert.strictEqual(data.zip, '35007');
+      const data2 = locator.getZipData('35007');
+      assert.deepStrictEqual(data, data2);
+    });
+
+    it('normalizes zip to 5 characters (zero-padded)', () => {
+      const data = locator.getZipData(1001);
+      assert.ok(data);
+      assert.strictEqual(data.zip, '01001');
+    });
+
+    it('returns undefined for unknown zip', () => {
+      assert.strictEqual(locator.getZipData('99999'), undefined);
+    });
+  });
+
+  describe('getZipCoordinates(zipCode)', () => {
+    it('returns latitude and longitude for a zip code', () => {
+      const coords = locator.getZipCoordinates('35004');
+      assert.ok(coords);
+      assert.strictEqual(typeof coords.latitude, 'number');
+      assert.strictEqual(typeof coords.longitude, 'number');
+      assert.strictEqual(coords.latitude, 33.606379);
+      assert.strictEqual(coords.longitude, -86.50249);
+    });
+
+    it('returns undefined for unknown zip', () => {
+      assert.strictEqual(locator.getZipCoordinates('00000'), undefined);
+    });
+  });
+
+  describe('getZipCodes(city, state)', () => {
+    it('returns all zip codes and coordinates for city and state (can be multiple)', () => {
+      const zips = locator.getZipCodes('Moody', 'AL');
+      assert.ok(Array.isArray(zips));
+      assert.ok(zips.length >= 1);
+      zips.forEach((r) => {
+        assert.strictEqual(r.city, 'Moody');
+        assert.strictEqual(r.state, 'AL');
+        assert.ok(r.zip);
+        assert.ok(typeof r.latitude === 'number' && typeof r.longitude === 'number');
+      });
+    });
+
+    it('is case-insensitive for city and state', () => {
+      const zips1 = locator.getZipCodes('moody', 'al');
+      const zips2 = locator.getZipCodes('Moody', 'AL');
+      assert.strictEqual(zips1.length, zips2.length);
+    });
+
+    it('returns empty array when no match', () => {
+      const zips = locator.getZipCodes('NoSuchCity', 'XX');
+      assert.deepStrictEqual(zips, []);
+    });
+  });
+
+  describe('getClosestByZipCode(zipCode, radius, useMiles)', () => {
+    it('returns zips within radius (default miles)', () => {
+      const results = locator.getClosestByZipCode('35004', 10);
+      assert.ok(Array.isArray(results));
+      assert.ok(results.length >= 1);
+      results.forEach((r) => {
+        assert.ok(r.distance >= 0 && r.distance <= 10);
+        assert.ok(r.zip && r.latitude != null && r.longitude != null);
+      });
+      const sorted = [...results].sort((a, b) => a.distance - b.distance);
+      assert.deepStrictEqual(results, sorted);
+    });
+
+    it('accepts useMiles false for kilometers', () => {
+      const resultsKm = locator.getClosestByZipCode('35004', 16, false); // ~10 mi in km
+      assert.ok(Array.isArray(resultsKm));
+      resultsKm.forEach((r) => {
+        assert.ok(r.distance <= 16);
+      });
+    });
+
+    it('returns empty array for unknown zip', () => {
+      assert.deepStrictEqual(locator.getClosestByZipCode('99999', 5), []);
+    });
+  });
+
+  describe('getDataByCoordinates(lat, lng, options)', () => {
+    it('returns zip records with distance, default sort by distance', () => {
+      const results = locator.getDataByCoordinates(33.6, -86.5);
+      assert.ok(Array.isArray(results));
+      assert.ok(results.length >= 1);
+      results.forEach((r) => {
+        assert.ok(typeof r.distance === 'number');
+        assert.ok(r.zip && r.latitude != null && r.longitude != null);
+      });
+      const sorted = [...results].sort((a, b) => a.distance - b.distance);
+      assert.deepStrictEqual(results, sorted);
+    });
+
+    it('supports sort by zip', () => {
+      const results = locator.getDataByCoordinates(33.6, -86.5, { sort: 'zip' });
+      const sorted = [...results].sort((a, b) => a.zip.localeCompare(b.zip));
+      assert.deepStrictEqual(results, sorted);
+    });
+
+    it('supports sort by city', () => {
+      const results = locator.getDataByCoordinates(33.6, -86.5, { sort: 'city' });
+      const sorted = [...results].sort(
+        (a, b) => a.city.localeCompare(b.city) || a.state.localeCompare(b.state)
+      );
+      assert.deepStrictEqual(results, sorted);
+    });
+
+    it('uses instance distance unit (km when useMiles false)', () => {
+      const results = locatorKm.getDataByCoordinates(33.6, -86.5);
+      assert.ok(results.length >= 1);
+      assert.ok(typeof results[0].distance === 'number');
+      assert.ok(results[0].distance > 0);
+    });
+  });
+
+  describe('getDistanceBetweenZipCodes(zip1, zip2, useMiles)', () => {
+    it('returns distance between two zips (default miles)', () => {
+      const d = locator.getDistanceBetweenZipCodes('35004', '35007');
+      assert.ok(typeof d === 'number');
+      assert.ok(d >= 0);
+    });
+
+    it('returns distance in km when useMiles is false', () => {
+      const dMiles = locator.getDistanceBetweenZipCodes('35004', '35007', true);
+      const dKm = locator.getDistanceBetweenZipCodes('35004', '35007', false);
+      assert.ok(dKm > 0);
+      assert.ok(Math.abs(dKm / dMiles - 1.60934) < 0.1);
+    });
+
+    it('returns undefined if either zip not found', () => {
+      assert.strictEqual(locator.getDistanceBetweenZipCodes('99999', '35004'), undefined);
+      assert.strictEqual(locator.getDistanceBetweenZipCodes('35004', '00000'), undefined);
+    });
+
+    it('returns 0 for same zip', () => {
+      assert.strictEqual(locator.getDistanceBetweenZipCodes('35004', '35004'), 0);
+    });
+  });
+
+  describe('getZipsInState(state)', () => {
+    it('returns all zips in the state', () => {
+      const zips = locator.getZipsInState('AL');
+      assert.ok(Array.isArray(zips));
+      assert.ok(zips.length >= 1);
+      zips.forEach((r) => {
+        assert.strictEqual(r.state, 'AL');
+        assert.ok(r.zip && r.latitude != null && r.longitude != null && r.city);
+      });
+    });
+
+    it('accepts lowercase state', () => {
+      const zipsAl = locator.getZipsInState('al');
+      const zipsAL = locator.getZipsInState('AL');
+      assert.strictEqual(zipsAl.length, zipsAL.length);
+    });
+
+    it('returns empty array for unknown state', () => {
+      assert.deepStrictEqual(locator.getZipsInState('XX'), []);
+    });
+  });
+
+  describe('getCitiesInState(state)', () => {
+    it('returns unique city names sorted', () => {
+      const cities = locator.getCitiesInState('AL');
+      assert.ok(Array.isArray(cities));
+      assert.ok(cities.length >= 1);
+      const unique = [...new Set(cities)];
+      assert.strictEqual(cities.length, unique.length);
+      const sorted = [...cities].sort((a, b) => a.localeCompare(b));
+      assert.deepStrictEqual(cities, sorted);
+    });
+
+    it('includes known city from state', () => {
+      const cities = locator.getCitiesInState('AL');
+      assert.ok(cities.includes('Moody'));
+    });
+  });
+
+  describe('isValidZip(zipCode)', () => {
+    it('returns true for existing zip', () => {
+      assert.strictEqual(locator.isValidZip('35004'), true);
+      assert.strictEqual(locator.isValidZip(35007), true);
+    });
+
+    it('returns false for unknown zip', () => {
+      assert.strictEqual(locator.isValidZip('99999'), false);
+      assert.strictEqual(locator.isValidZip('00000'), false);
+    });
+  });
+
+  describe('searchZipPrefix(prefix)', () => {
+    it('returns zips starting with prefix', () => {
+      const results = locator.searchZipPrefix('350');
+      assert.ok(Array.isArray(results));
+      results.forEach((r) => assert.ok(r.zip.startsWith('350')));
+    });
+
+    it('returns empty array for empty prefix', () => {
+      assert.deepStrictEqual(locator.searchZipPrefix(''), []);
+      assert.deepStrictEqual(locator.searchZipPrefix('   '), []);
+    });
+  });
+
+  describe('getZipsInBoundingBox(minLat, maxLat, minLng, maxLng)', () => {
+    it('returns zips inside the box', () => {
+      const results = locator.getZipsInBoundingBox(33.5, 34, -87, -86);
+      assert.ok(Array.isArray(results));
+      results.forEach((r) => {
+        assert.ok(r.latitude >= 33.5 && r.latitude <= 34);
+        assert.ok(r.longitude >= -87 && r.longitude <= -86);
+      });
+    });
+
+    it('accepts min/max in either order', () => {
+      const r1 = locator.getZipsInBoundingBox(33.5, 34, -87, -86);
+      const r2 = locator.getZipsInBoundingBox(34, 33.5, -86, -87);
+      assert.strictEqual(r1.length, r2.length);
+    });
+  });
+
+  describe('getDistancesFromZip(originZip, zipCodes, useMiles?)', () => {
+    it('returns distances for each target zip', () => {
+      const results = locator.getDistancesFromZip('35004', ['35007', '35005']);
+      assert.strictEqual(results.length, 2);
+      results.forEach((r) => assert.ok('zip' in r && 'distance' in r));
+      assert.ok(typeof results[0].distance === 'number');
+      assert.ok(typeof results[1].distance === 'number');
+    });
+
+    it('returns undefined distance for unknown target zip', () => {
+      const results = locator.getDistancesFromZip('35004', ['35007', '99999']);
+      assert.strictEqual(results[1].zip, '99999');
+      assert.strictEqual(results[1].distance, undefined);
+    });
+
+    it('returns empty array when origin zip unknown', () => {
+      const results = locator.getDistancesFromZip('99999', ['35004', '35007']);
+      assert.strictEqual(results.length, 2);
+      assert.strictEqual(results[0].distance, undefined);
+      assert.strictEqual(results[1].distance, undefined);
+    });
+  });
+
+  describe('getCityState(zipCode)', () => {
+    it('returns city, state, and formatted string', () => {
+      const result = locator.getCityState('35004');
+      assert.ok(result);
+      assert.strictEqual(result.city, 'Moody');
+      assert.strictEqual(result.state, 'AL');
+      assert.strictEqual(result.formatted, 'Moody, AL');
+    });
+
+    it('returns undefined for unknown zip', () => {
+      assert.strictEqual(locator.getCityState('99999'), undefined);
+    });
+  });
+
+  describe('getFullStateName(stateAbbr)', () => {
+    it('returns full state name for abbreviation', () => {
+      assert.strictEqual(locator.getFullStateName('AL'), 'Alabama');
+      assert.strictEqual(locator.getFullStateName('al'), 'Alabama');
+    });
+
+    it('returns undefined for unknown state', () => {
+      assert.strictEqual(locator.getFullStateName('XX'), undefined);
+    });
+  });
+});
+
+describe('module default export', () => {
+  const locator = require('..');
+  it('exposes getZipData as default instance', () => {
+    assert.strictEqual(typeof locator.getZipData, 'function');
+    const data = locator.getZipData('35004');
+    assert.ok(data);
+    assert.strictEqual(data.zip, '35004');
+  });
+});