geoip-lite2 2.3.0-alpha.0 → 3.0.0-alpha.0

package/README.md

@@ -16,7 +16,7 @@
 
 
 # 🚀 Improved GeoIP Module by [Sefinek](https://sefinek.net)
-A maintained and optimized fork of [geoip-lite](https://github.com/geoip-lite/node-geoip) originally created by [Philip Tellis](AUTHORS).
+Actively maintained and optimized fork of [geoip-lite](https://github.com/geoip-lite/node-geoip), originally created by [Philip Tellis](AUTHORS).
 Fully native JS implementation with synchronous, in-memory lookups for IPv4 and IPv6.
 Includes automated test coverage using [Jest](https://www.npmjs.com/package/jest).
 
@@ -37,7 +37,7 @@ Includes automated test coverage using [Jest](https://www.npmjs.com/package/jest
 npm install geoip-lite2
 ```
 
-### 2. Update the data files (recommended)
+### 2. Update the data files (required)
 Run `cd node_modules/geoip-lite2 && npm run updatedb license_key=YOUR_LICENSE_KEY` to update the data files. Replace `YOUR_LICENSE_KEY` with your license key obtained from [maxmind.com](https://support.maxmind.com/hc/en-us/articles/4407111582235-Generate-a-License-Key).
 
 ## 📝 Short Example
@@ -51,10 +51,9 @@ console.log(geoIp.lookup(ip));
 ### Output
 ```json
 {
-  "range": [ 2450746624, 2450746879 ],
   "country": "PL",
   "region": "14",
-  "eu": "1",
+  "isEu": true,
   "timezone": "Europe/Warsaw",
   "city": "Warsaw",
   "ll": [ 52.2296, 21.0067 ],
@@ -66,13 +65,14 @@ console.log(geoIp.lookup(ip));
 
 ## 🌐 Live Demo API
 You can see this module in action using my [official API](https://api.sefinek.net).
-- Specific IP: https://api.sefinek.net/api/v2/geoip/109.207.159.255 (should not be used in production)
+- Specific IP: https://api.sefinek.net/api/v2/geoip/109.207.159.255 (not for production use)
 - Client's IP: https://api.sefinek.net/api/v2/geoip/me
 - Documentation: https://api.sefinek.net/docs/v2
 
 
 ## 📚 Library API
-GeoIP-Lite2 is completely synchronous. It does not use callbacks. All blocking file I/O is performed at startup, so all runtime calls are executed in-memory and are fast.
+GeoIP-Lite2 performs lookups synchronously in memory (`lookup`). It also provides async data reload methods (`reloadData`) and file watcher callbacks (`startWatchingDataUpdate`).
+All blocking file I/O is performed at startup, so all runtime lookups are fast.
 Startup may take up to 200 ms while reading and indexing data files into memory.
 
 ### Looking up an IP address
@@ -83,17 +83,18 @@ pass it to the `lookup` method. Remember to remove any `[` and `]` around an IPv
 const geo = geoIp.lookup(ip);
 ```
 
+If `ip` is missing (`undefined` or `null`), `lookup` throws a `TypeError`.
+
 If the IP address was found, the `lookup` method returns an object with the following structure:
 
 ```js
 {
-   range: [ <low bound of IP block>, <high bound of IP block> ],
    country: 'CC',                 // 2 letter ISO-3166-1 country code
    region: 'RR',                  // Up to 3 alphanumeric characters as ISO 3166-2 code
                                   // For US states this is the 2 letter state
                                   // For the United Kingdom this could be ENG as a country like "England"
                                   // FIPS 10-4 subcountry code
-   eu: '0',                       // 1 if the country is a member state of the European Union, 0 otherwise.
+   isEu: true,                    // true if the country is a member state of the European Union, otherwise false.
    timezone: 'Country/Zone',      // Timezone from IANA Time Zone Database
    city: 'City name',             // Full city name
    ll: [<latitude>, <longitude>], // Latitude and longitude of the city
@@ -104,17 +105,6 @@ If the IP address was found, the `lookup` method returns an object with the foll
 
 If the IP address was not found, `lookup` returns `null`.
 
-### Pretty printing an IP address
-If you have a 32-bit unsigned integer or a number returned as part of the `range` array,
-you can use the `pretty` method to get a human-readable format.
-
-```js
-console.log('IP is %s', geoIp.pretty(ip));
-```
-
-The method returns a string if the input format is recognized, otherwise it returns the input itself.
-
-
 ## 🔄 Built-in Updater
 This package contains an update script that downloads files from MaxMind and handles CSV conversion.
 A npm script alias has been configured to simplify this process. Internet access is required and MaxMind download limits apply.
@@ -144,10 +134,13 @@ You can do it programmatically, calling after scheduled data updates
 // Synchronously
 geoIp.reloadDataSync();
 
-// Asynchronously
+// Asynchronously (callback)
 geoIp.reloadData(() => {
     console.log('Done');
 });
+
+// Asynchronously (Promise)
+await geoIp.reloadData();
 ```
 
 #### Automatic Start and stop watching for data updates
@@ -163,11 +156,11 @@ This tool can be used with `npm run updatedb` to periodically update geo data on
 The following environment variables can be set.
 
 ```bash
-# Override the default node_modules/geoip-lite/data dir
-GEOTMPDIR=/some/path
-
-# Override the default node_modules/geoip-lite/tmp dir
+# Override the default node_modules/geoip-lite2/data dir
 GEODATADIR=/some/path
+
+# Override the default node_modules/geoip-lite2/tmp dir
+GEOTMPDIR=/some/path
 ```
 
 
@@ -210,4 +203,4 @@ console.log(process.memoryUsage());
 
 
 ## 🔐 License
-There are two licenses for the code and data. See the [LICENSE](LICENSE) file for details.
+There are two licenses for the code and data. See the [LICENSE](LICENSE) file for details.

package/example/lookup-watch.js

@@ -0,0 +1,15 @@
+const geoIp = require('../index.js');
+
+geoIp.startWatchingDataUpdate(err => {
+	if (err) {
+		console.error('[geoip-lite2] GeoIP reload failed:', err);
+		return;
+	}
+	console.log('[geoip-lite2] Reloaded GeoIP database');
+});
+
+const ipv4 = '79.186.130.100';
+console.log(ipv4, geoIp.lookup(ipv4));
+
+const ipv6 = '2a01:11bf:4222:900a:99ae:285f:7432:8f8e';
+console.log(ipv6, geoIp.lookup(ipv6));

package/index.d.ts

@@ -1,8 +1,7 @@
 interface GeoIp2Location {
-    range: [number | null, number | null];
     country: string;
     region: string;
-    eu: '0' | '1' | '';
+    isEu: boolean;
     timezone: string;
     city: string;
     ll: [number | null, number | null];
@@ -11,10 +10,10 @@ interface GeoIp2Location {
 }
 
 export function lookup(ip: string | number): GeoIp2Location | null;
-export function pretty(n: string | number | any[]): string;
 export function reloadDataSync(): void;
-export function reloadData(callback?: (err?: Error | null) => void): Promise<void>;
-export function startWatchingDataUpdate(callback: () => void): void;
+export function reloadData(callback: (err?: Error | null) => void): void;
+export function reloadData(): Promise<void>;
+export function startWatchingDataUpdate(callback?: (err?: Error | null) => void): void;
 export function stopWatchingDataUpdate(): void;
 export function clear(): void;
-export const version: string;
+export const version: string;