@forwardslashns/fws-geo-location-api 1.0.0 → 1.0.1

package/dist/client/geo-location.client.d.ts

@@ -9,6 +9,10 @@ export declare class GeoLocationClient {
     private readonly restrictions;
     /** In-memory cache: ISO2 countryCode → Country. Populated on first full country fetch. */
     private readonly countryCache;
+    /** True once the full country list has been fetched and cached — avoids re-fetching on every getCountries() call. */
+    private countriesFullyCached;
+    /** In-memory cache: ISO2 countryCode → full sorted PostalCode[]. Populated by getAllPostalCodes(). */
+    private readonly postalCodeCache;
     constructor(options: GeoLocationClientOptions);
     /**
      * Returns a list of countries.
@@ -61,10 +65,10 @@ export declare class GeoLocationClient {
      *
      * Because GeoNames requires at least one search term, a bare country-only
      * query always returns status 15. This method works around that constraint
-     * transparently: it fires one request per character prefix (up to 36), each
-     * with `postalcode_startsWith=<char>`, and pages through results in chunks
-     * of 1 000 until the bucket is exhausted. Prefixes that yield no results
-     * (status 15 or empty page) are skipped automatically.
+     * transparently: it fires all 36 prefix bucket requests in **parallel**,
+     * each with `postalcode_startsWith=<char>`. Within each bucket, pages are
+     * fetched sequentially until exhausted. This cuts total wall-clock time from
+     * `sum(bucket times)` down to `max(bucket time)`.
      *
      * The results are deduplicated and returned as a single flat array sorted by
      * postal code.
@@ -72,11 +76,16 @@ export declare class GeoLocationClient {
      * **API credit cost**: roughly 1 request per 1 000 postal codes in the
      * country, spread across up to 36 prefix buckets. For small countries
      * (< 5 000 codes) expect 10–20 requests; for large ones (US ~43 000) expect
-     * ~80 requests.
+     * ~80 requests — all fired concurrently.
      *
      * @param countryCode - ISO 3166-1 alpha-2 country code, e.g. `"US"`.
      */
     getAllPostalCodes(countryCode: string, options?: GetAllPostalCodesOptions): Promise<PostalCode[]>;
+    /**
+     * Fetches all postal codes for a single alphanumeric prefix bucket,
+     * paginating until exhausted.
+     */
+    private fetchAllForPrefix;
     /**
      * Returns one page of postal codes for a country, working around the GeoNames
      * per-country query limit that prevents retrieving all codes for large
@@ -113,7 +122,6 @@ export declare class GeoLocationClient {
      */
     findPostalCode(postalCode: string, countryCode: string): Promise<PostalCode | null>;
     private fetchAllCountries;
-    private fetchCountriesByContinent;
     private cacheCountries;
     private resolveCountryName;
     private assertNonEmptyCountryCode;

package/dist/client/geo-location.client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"geo-location.client.d.ts","sourceRoot":"","sources":["../../src/client/geo-location.client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,wBAAwB,EAExB,mBAAmB,EACnB,iBAAiB,EACjB,gBAAgB,EAChB,qBAAqB,EACrB,wBAAwB,EACxB,wBAAwB,EACxB,cAAc,EACf,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAChE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,2BAA2B,CAAC;AACzD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,0BAA0B,CAAC;AACvD,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,wBAAwB,CAAC;AACnD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,+BAA+B,CAAC;AAuBhE,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAc;IAC1C,OAAO,CAAC,QAAQ,CAAC,YAAY,CAA0B;IACvD,0FAA0F;IAC1F,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAmC;gBAE7C,OAAO,EAAE,wBAAwB;IASpD;;;;;OAKG;IACU,YAAY,CAAC,OAAO,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;IAyB5E;;;;;;OAMG;IACU,UAAU,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,eAAe,CAAC,MAAM,CAAC,CAAC;IAsC3G;;;;;;OAMG;IACU,SAAS,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,EAAE,OAAO,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,eAAe,CAAC,IAAI,CAAC,CAAC;IA+C/G;;;;;;;;;;;;;;;;;;;;OAoBG;IACU,cAAc,CACzB,WAAW,EAAE,MAAM,EACnB,OAAO,CAAC,EAAE,qBAAqB,GAC9B,OAAO,CAAC,eAAe,CAAC,UAAU,CAAC,CAAC;IAuDvC;;;;;;;;;;;;;;;;;;;;OAoBG;IACU,iBAAiB,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,wBAAwB,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;IAoD9G;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACU,kBAAkB,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,wBAAwB,GAAG,OAAO,CAAC,cAAc,CAAC;IAmEjH;;;;;;OAMG;IACU,cAAc,CAAC,UAAU,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;YA8BlF,iBAAiB;YAUjB,yBAAyB;IAUvC,OAAO,CAAC,cAAc;YAMR,kBAAkB;IAUhC,OAAO,CAAC,yBAAyB;CAKlC"}
+{"version":3,"file":"geo-location.client.d.ts","sourceRoot":"","sources":["../../src/client/geo-location.client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,wBAAwB,EAExB,mBAAmB,EACnB,iBAAiB,EACjB,gBAAgB,EAChB,qBAAqB,EACrB,wBAAwB,EACxB,wBAAwB,EACxB,cAAc,EACf,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAChE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,2BAA2B,CAAC;AACzD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,0BAA0B,CAAC;AACvD,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,wBAAwB,CAAC;AACnD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,+BAA+B,CAAC;AAsBhE,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAc;IAC1C,OAAO,CAAC,QAAQ,CAAC,YAAY,CAA0B;IACvD,0FAA0F;IAC1F,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAmC;IAChE,qHAAqH;IACrH,OAAO,CAAC,oBAAoB,CAAS;IACrC,sGAAsG;IACtG,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAwC;gBAErD,OAAO,EAAE,wBAAwB;IASpD;;;;;OAKG;IACU,YAAY,CAAC,OAAO,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;IAyB5E;;;;;;OAMG;IACU,UAAU,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,eAAe,CAAC,MAAM,CAAC,CAAC;IAsC3G;;;;;;OAMG;IACU,SAAS,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,EAAE,OAAO,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,eAAe,CAAC,IAAI,CAAC,CAAC;IA+C/G;;;;;;;;;;;;;;;;;;;;OAoBG;IACU,cAAc,CACzB,WAAW,EAAE,MAAM,EACnB,OAAO,CAAC,EAAE,qBAAqB,GAC9B,OAAO,CAAC,eAAe,CAAC,UAAU,CAAC,CAAC;IAuDvC;;;;;;;;;;;;;;;;;;;;OAoBG;IACU,iBAAiB,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,wBAAwB,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;IAwE9G;;;OAGG;YACW,iBAAiB;IA6B/B;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACU,kBAAkB,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,wBAAwB,GAAG,OAAO,CAAC,cAAc,CAAC;IAmEjH;;;;;;OAMG;IACU,cAAc,CAAC,UAAU,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;YA8BlF,iBAAiB;IAc/B,OAAO,CAAC,cAAc;YAMR,kBAAkB;IAUhC,OAAO,CAAC,yBAAyB;CAKlC"}

package/dist/client/geo-location.client.js

@@ -14,6 +14,10 @@ class GeoLocationClient {
     restrictions;
     /** In-memory cache: ISO2 countryCode → Country. Populated on first full country fetch. */
     countryCache = new Map();
+    /** True once the full country list has been fetched and cached — avoids re-fetching on every getCountries() call. */
+    countriesFullyCached = false;
+    /** In-memory cache: ISO2 countryCode → full sorted PostalCode[]. Populated by getAllPostalCodes(). */
+    postalCodeCache = new Map();
     constructor(options) {
         this.httpService = new http_service_js_1.HttpService(options.usernames);
         this.restrictions = options.restrictions ?? {};
@@ -30,13 +34,12 @@ class GeoLocationClient {
     async getCountries(options) {
         const continents = options?.continents ?? this.restrictions.continents;
         const countryCodes = options?.countryCodes ?? this.restrictions.countries;
-        let countries;
+        // Always fetch the full list (single request, result is cached).
+        // Client-side continent filtering is more reliable than depending on GeoNames
+        // honouring the `continent` query parameter for countryInfoJSON.
+        let countries = await this.fetchAllCountries();
         if (continents && continents.length > 0) {
-            const results = await Promise.all(continents.map((continent) => this.fetchCountriesByContinent(continent)));
-            countries = results.flat();
-        }
-        else {
-            countries = await this.fetchAllCountries();
+            countries = countries.filter((c) => continents.includes(c.continent));
         }
         if (countryCodes && countryCodes.length > 0) {
             const upper = countryCodes.map((c) => c.toUpperCase());
@@ -193,10 +196,10 @@ class GeoLocationClient {
      *
      * Because GeoNames requires at least one search term, a bare country-only
      * query always returns status 15. This method works around that constraint
-     * transparently: it fires one request per character prefix (up to 36), each
-     * with `postalcode_startsWith=<char>`, and pages through results in chunks
-     * of 1 000 until the bucket is exhausted. Prefixes that yield no results
-     * (status 15 or empty page) are skipped automatically.
+     * transparently: it fires all 36 prefix bucket requests in **parallel**,
+     * each with `postalcode_startsWith=<char>`. Within each bucket, pages are
+     * fetched sequentially until exhausted. This cuts total wall-clock time from
+     * `sum(bucket times)` down to `max(bucket time)`.
      *
      * The results are deduplicated and returned as a single flat array sorted by
      * postal code.
@@ -204,51 +207,97 @@ class GeoLocationClient {
      * **API credit cost**: roughly 1 request per 1 000 postal codes in the
      * country, spread across up to 36 prefix buckets. For small countries
      * (< 5 000 codes) expect 10–20 requests; for large ones (US ~43 000) expect
-     * ~80 requests.
+     * ~80 requests — all fired concurrently.
      *
      * @param countryCode - ISO 3166-1 alpha-2 country code, e.g. `"US"`.
      */
     async getAllPostalCodes(countryCode, options) {
         this.assertNonEmptyCountryCode(countryCode);
         const upper = countryCode.toUpperCase();
+        // Return cached result immediately — zero API requests on repeat calls.
+        if (this.postalCodeCache.has(upper)) {
+            const cached = this.postalCodeCache.get(upper);
+            if (options?.onProgress)
+                options.onProgress(cached.slice());
+            return cached.slice();
+        }
         const countryName = await this.resolveCountryName(upper);
+        // ── Fast path: try a single unfiltered request first ──────────────────────
+        // GeoNames accepts bare country queries for countries with small datasets
+        // (roughly < 1 000 postal codes). When the response is smaller than
+        // MAX_ROWS_LIMIT we have the complete set in one request instead of 36.
+        // For large countries GeoNames returns status 15 — we fall through to the
+        // parallel prefix-bucket strategy in that case.
+        try {
+            const raw = await this.httpService.get(`${api_constants_js_1.GEONAMES_BASE_URL}${api_constants_js_1.GEONAMES_ENDPOINTS.POSTAL_CODE_SEARCH}`, { country: upper, maxRows: feature_constants_js_1.MAX_ROWS_LIMIT });
+            if (raw.postalCodes.length < feature_constants_js_1.MAX_ROWS_LIMIT) {
+                // Got the complete set in a single request.
+                const result = raw.postalCodes.map((pc) => (0, postal_code_mapper_js_1.mapPostalCode)(pc, countryName));
+                result.sort((a, b) => a.postalCode.localeCompare(b.postalCode, undefined, { numeric: true }));
+                this.postalCodeCache.set(upper, result);
+                if (options?.onProgress)
+                    options.onProgress(result.slice());
+                return result.slice();
+            }
+            // Exactly MAX_ROWS_LIMIT results — dataset is larger than one page.
+            // Fall through to prefix iteration.
+        }
+        catch (err) {
+            if (!(err instanceof geo_location_error_js_1.GeoLocationError && err.code === api_constants_js_1.GEONAMES_ERROR_CODES.NO_RESULT_FOUND)) {
+                throw err; // unexpected error
+            }
+            // status 15: country dataset is too large for bare query — use prefix iteration.
+        }
+        // ── Slow path: parallel prefix-bucket iteration ───────────────────────────
         const PREFIXES = '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ'.split('');
         const seen = new Set();
         const all = [];
-        for (const prefix of PREFIXES) {
-            let startRow = 0;
-            while (true) {
-                let page;
-                try {
-                    const raw = await this.httpService.get(`${api_constants_js_1.GEONAMES_BASE_URL}${api_constants_js_1.GEONAMES_ENDPOINTS.POSTAL_CODE_SEARCH}`, { country: upper, postalcode_startsWith: prefix, maxRows: feature_constants_js_1.MAX_ROWS_LIMIT, startRow });
-                    page = raw.postalCodes.map((pc) => (0, postal_code_mapper_js_1.mapPostalCode)(pc, countryName));
+        // Fire all prefix buckets in parallel. Each bucket handles its own pagination.
+        // onProgress is called (in completion order) as each bucket resolves.
+        const bucketPromises = PREFIXES.map((prefix) => this.fetchAllForPrefix(upper, prefix, countryName).then((bucket) => {
+            for (const pc of bucket) {
+                const key = `${pc.postalCode}|${pc.placeName}|${pc.adminName1}`;
+                if (!seen.has(key)) {
+                    seen.add(key);
+                    all.push(pc);
                 }
-                catch (err) {
-                    if (err instanceof geo_location_error_js_1.GeoLocationError && err.code === api_constants_js_1.GEONAMES_ERROR_CODES.NO_RESULT_FOUND) {
-                        break; // this prefix has no results — move on
-                    }
-                    throw err;
-                }
-                for (const pc of page) {
-                    const key = `${pc.postalCode}|${pc.placeName}|${pc.adminName1}`;
-                    if (!seen.has(key)) {
-                        seen.add(key);
-                        all.push(pc);
-                    }
-                }
-                if (page.length < feature_constants_js_1.MAX_ROWS_LIMIT)
-                    break; // last page for this prefix
-                startRow += feature_constants_js_1.MAX_ROWS_LIMIT;
             }
-            // Notify caller of progress after each prefix bucket
             if (options?.onProgress && all.length > 0) {
                 all.sort((a, b) => a.postalCode.localeCompare(b.postalCode, undefined, { numeric: true }));
                 options.onProgress(all.slice());
             }
-        }
+        }));
+        await Promise.all(bucketPromises);
         all.sort((a, b) => a.postalCode.localeCompare(b.postalCode, undefined, { numeric: true }));
+        this.postalCodeCache.set(upper, all);
         return all;
     }
+    /**
+     * Fetches all postal codes for a single alphanumeric prefix bucket,
+     * paginating until exhausted.
+     */
+    async fetchAllForPrefix(countryCode, prefix, countryName) {
+        const bucket = [];
+        let startRow = 0;
+        while (true) {
+            let page;
+            try {
+                const raw = await this.httpService.get(`${api_constants_js_1.GEONAMES_BASE_URL}${api_constants_js_1.GEONAMES_ENDPOINTS.POSTAL_CODE_SEARCH}`, { country: countryCode, postalcode_startsWith: prefix, maxRows: feature_constants_js_1.MAX_ROWS_LIMIT, startRow });
+                page = raw.postalCodes.map((pc) => (0, postal_code_mapper_js_1.mapPostalCode)(pc, countryName));
+            }
+            catch (err) {
+                if (err instanceof geo_location_error_js_1.GeoLocationError && err.code === api_constants_js_1.GEONAMES_ERROR_CODES.NO_RESULT_FOUND) {
+                    break; // this prefix has no results — done
+                }
+                throw err;
+            }
+            bucket.push(...page);
+            if (page.length < feature_constants_js_1.MAX_ROWS_LIMIT)
+                break; // last page for this prefix
+            startRow += feature_constants_js_1.MAX_ROWS_LIMIT;
+        }
+        return bucket;
+    }
     /**
      * Returns one page of postal codes for a country, working around the GeoNames
      * per-country query limit that prevents retrieving all codes for large
@@ -356,15 +405,13 @@ class GeoLocationClient {
     // Private helpers
     // ---------------------------------------------------------------------------
     async fetchAllCountries() {
+        if (this.countriesFullyCached) {
+            return Array.from(this.countryCache.values());
+        }
         const raw = await this.httpService.get(`${api_constants_js_1.GEONAMES_BASE_URL}${api_constants_js_1.GEONAMES_ENDPOINTS.COUNTRY_INFO}`, {});
         const countries = raw.geonames.map(country_mapper_js_1.mapCountry);
         this.cacheCountries(countries);
-        return countries;
-    }
-    async fetchCountriesByContinent(continent) {
-        const raw = await this.httpService.get(`${api_constants_js_1.GEONAMES_BASE_URL}${api_constants_js_1.GEONAMES_ENDPOINTS.COUNTRY_INFO}`, { continent });
-        const countries = raw.geonames.map(country_mapper_js_1.mapCountry);
-        this.cacheCountries(countries);
+        this.countriesFullyCached = true;
         return countries;
     }
     cacheCountries(countries) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forwardslashns/fws-geo-location-api",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "FWS company dedicated TypeScript wrapper around the GeoNames geolocation API. Provides countries, regions, cities, and postal codes with username rotation and restriction support.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",