wip: tests and documentation

Author: Bas950

packages/ip-location-api/src/functions/lookup.ts

@@ -5,40 +5,149 @@ import { join } from 'node:path'
 import { binarySearch, getSmallMemoryFile, type IpLocationApiSettings, type LocalDatabase, number37ToString, parseIp, SAVED_SETTINGS } from '@iplookup/util'
 import { LOADED_DATA } from './reload.js'
 
+/**
+ * Represents geographical data for an IP address
+ */
 interface GeoData {
+  /**
+   * The approximate WGS84 latitude of the IP address
+   *
+   * @see https://en.wikipedia.org/wiki/World_Geodetic_System
+   */
   latitude?: number
+  /**
+   * The approximate WGS84 longitude of the IP address
+   *
+   * @see https://en.wikipedia.org/wiki/World_Geodetic_System
+   */
   longitude?: number
+  /**
+   * The region-specific postcode nearest to the IP address
+   */
   postcode?: string
+  /**
+   * The radius in kilometers of the specified location where the IP address is likely to be
+   */
   area?: number
+  /**
+   * The country of the IP address
+   * @example 'US'
+   * @see https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2
+   */
   country?: string
+  /**
+   * Whether the country is a member of the European Union
+   *
+   * @requires country
+   */
   eu?: boolean
+  /**
+   * The first region of the IP address
+   * @example 'NL-ZH' // (Netherlands, South Holland)
+   * @see https://en.wikipedia.org/wiki/ISO_3166-2
+   */
   region1?: string
+  /**
+   * The name of the first region of the IP address (Can be aquired in multiple languages using the `language` setting)
+   * @example 'South Holland'
+   */
   region1_name?: string
+  /**
+   * The second region of the IP address
+   * @example 'NL-ZH' // (Netherlands, South Holland)
+   * @see https://en.wikipedia.org/wiki/ISO_3166-2
+   */
   region2?: string
+  /**
+   * The name of the second region of the IP address (Can be aquired in multiple languages using the `language` setting)
+   * @example 'South Holland'
+   */
   region2_name?: string
+  /**
+   * The metropolitan area of the IP address (Google AdWords API)
+   * @example 1000
+   * @see https://developers.google.com/adwords/api/docs/appendix/cities-DMAregions
+   */
   metro?: number
+  /**
+   * The timezone of the IP address
+   * @example 'Europe/Amsterdam'
+   */
   timezone?: string
+  /**
+   * The city of the IP address
+   * @example 'Amsterdam'
+   */
   city?: string
+  /**
+   * The name of the country of the IP address (In English)
+   * @example 'Netherlands'
+   * @requires country
+   * @requires country-list (optional peer dependency)
+   */
   country_name?: string
+  /**
+   * The name of the country of the IP address (In the native language of the country)
+   * @example 'Nederland'
+   * @requires country
+   * @requires country-list (optional peer dependency)
+   */
   country_native?: string
+  /**
+   * The continent of the IP address (alpha-2 code)
+   * @example 'EU'
+   * @requires country
+   * @requires country-list (optional peer dependency)
+   */
   continent?: string
+  /**
+   * The name of the continent of the IP address (In English)
+   * @example 'Europe'
+   * @requires country
+   * @requires country-list (optional peer dependency)
+   */
   continent_name?: string
+  /**
+   * The capital of the country of the IP address (In English)
+   * @example 'Amsterdam'
+   * @requires country
+   * @requires country-list (optional peer dependency)
+   */
   capital?: string
+  /**
+   * The phone codes of the country of the IP address
+   * @example ['31']
+   * @requires country
+   * @requires country-list (optional peer dependency)
+   */
   phone?: number[]
+  /**
+   * The currency of the country of the IP address
+   * @example ['EUR']
+   * @requires country
+   * @requires country-list (optional peer dependency)
+   */
   currency?: string[]
+  /**
+   * The languages of the country of the IP address
+   * @example ['nl']
+   */
   languages?: string[]
 }
 
+/**
+ * Looks up geographical data for a given IP address
+ * @param ip - The IP address to look up
+ * @returns A Promise that resolves to GeoData or null if not found
+ */
 export async function lookup(ip: string): Promise<GeoData | null> {
   //* We don't use net.isIP(ip) as it is slow for ipv6
   const { version, ip: ipNumber } = parseIp(ip)
 
   const settings = SAVED_SETTINGS
   const db = version === 4 ? settings.v4 : settings.v6
 
-  if (!db.loadedData)
-    return null
-  if (!(ipNumber >= db.loadedData.firstIp))
+  if (!db.loadedData || !(ipNumber >= db.loadedData.firstIp))
     return null
   const list = db.loadedData.startIps
   const line = binarySearch(list, ipNumber)
@@ -71,6 +180,13 @@ export async function lookup(ip: string): Promise<GeoData | null> {
   return setCityInfo(db.loadedData.mainBuffer!, line * db.recordSize, settings)
 }
 
+/**
+ * Reads a specific line from a file in the database
+ * @param line - The line number to read
+ * @param db - The database object
+ * @param settings - The API settings
+ * @returns A Promise that resolves to a Buffer containing the line data
+ */
 async function lineToFile(line: number, db: LocalDatabase, settings: IpLocationApiSettings): Promise<Buffer> {
   const [dir, file, offset] = getSmallMemoryFile(line, db)
   const fd = await open(join(settings.fieldDir, dir, file), 'r')
@@ -82,13 +198,24 @@ async function lineToFile(line: number, db: LocalDatabase, settings: IpLocationA
   return buffer
 }
 
+/**
+ * Extracts city information from a buffer
+ * @param buffer - The buffer containing city data
+ * @param offset - The starting offset in the buffer
+ * @param settings - The API settings
+ * @returns A Promise that resolves to GeoData
+ */
 function setCityInfo(buffer: Buffer, offset: number, settings: IpLocationApiSettings): Promise<GeoData> {
   let locationId: number | undefined
   const geodata: GeoData = {}
+
+  //* Read location ID if location file is available
   if (settings.locationFile) {
     locationId = buffer.readUInt32LE(offset)
     offset += 4
   }
+
+  //* Read latitude and longitude if included in fields
   if (settings.fields.includes('latitude')) {
     geodata.latitude = buffer.readInt32LE(offset) / 10000
     offset += 4
@@ -97,6 +224,8 @@ function setCityInfo(buffer: Buffer, offset: number, settings: IpLocationApiSett
     geodata.longitude = buffer.readInt32LE(offset) / 10000
     offset += 4
   }
+
+  //* Read and decode postcode if included in fields
   if (settings.fields.includes('postcode')) {
     const postcodeLength = buffer.readUInt32LE(offset)
     const postcodeValue = buffer.readInt8(offset + 4)
@@ -128,6 +257,8 @@ function setCityInfo(buffer: Buffer, offset: number, settings: IpLocationApiSett
     }
     offset += 5
   }
+
+  //* Read area if included in fields
   if (settings.fields.includes('area')) {
     const areaMap = LOADED_DATA.sub?.area
     if (areaMap) {
@@ -136,6 +267,7 @@ function setCityInfo(buffer: Buffer, offset: number, settings: IpLocationApiSett
     // offset += 1
   }
 
+  //* Process location data if locationId is available
   if (locationId) {
     let locationOffset = (locationId - 1) * settings.locationRecordSize
     const locationBuffer = LOADED_DATA.location
@@ -207,16 +339,30 @@ function setCityInfo(buffer: Buffer, offset: number, settings: IpLocationApiSett
   return setCountryInfo(geodata, settings)
 }
 
+/**
+ * Pads a string with leading zeros
+ * @param text - The text to pad
+ * @param length - The desired length of the padded string
+ * @returns The zero-padded string
+ */
 function getZeroFill(text: string, length: number) {
   return '0'.repeat(length - text.length) + text
 }
 
+/**
+ * Adds additional country information to the GeoData object
+ * @param geodata - The GeoData object to enhance
+ * @param settings - The API settings
+ * @returns A Promise that resolves to the enhanced GeoData
+ */
 async function setCountryInfo(geodata: GeoData, settings: IpLocationApiSettings): Promise<GeoData> {
   if (settings.addCountryInfo && geodata.country) {
     //* Import the countries-list package (optional peer dependency)
     try {
       const { countries, continents } = await import('countries-list')
       const country = countries[geodata.country as keyof typeof countries] as ICountry | undefined
+
+      //* Enhance geodata with additional country information
       geodata.country_name = country?.name
       geodata.country_native = country?.native
       geodata.continent = country?.continent ? continents[country.continent] : undefined

packages/ip-location-api/src/functions/reload.ts

@@ -18,15 +18,15 @@ export const LOADED_DATA: {
   }
 } = {}
 
+/**
+ * Reloads the IP location data based on the provided settings.
+ * @param inputSettings - Optional input settings to override the default settings.
+ */
 export async function reload(inputSettings?: IpLocationApiInputSettings): Promise<void> {
   const settings = getSettings(inputSettings)
 
-  let directoryToFind = settings.dataDir
-  if (settings.smallMemory) {
-    directoryToFind = join(settings.dataDir, 'v4')
-  }
-
-  if (!existsSync(directoryToFind)) {
+  //* If the data directory doesn't exist, update the database
+  if (!existsSync(join(settings.fieldDir, '4-1.dat'))) {
     await update(settings)
   }
 
@@ -45,11 +45,14 @@ export async function reload(inputSettings?: IpLocationApiInputSettings): Promis
     city: undefined as Buffer | undefined,
     sub: undefined as Buffer | undefined,
   }
+
+  //* Create an array of promises to read all necessary files
   const promises: Promise<void>[] = [
     readFile(join(settings.fieldDir, '4-1.dat')).then((buffer) => { buffers.v4.dat1 = buffer }),
     readFile(join(settings.fieldDir, '6-1.dat')).then((buffer) => { buffers.v6.dat1 = buffer }),
   ]
 
+  //* Add additional file reading promises if not in small memory mode
   if (!settings.smallMemory) {
     promises.push(
       readFile(join(settings.fieldDir, '4-2.dat')).then((buffer) => { buffers.v4.dat2 = buffer }),
@@ -59,6 +62,7 @@ export async function reload(inputSettings?: IpLocationApiInputSettings): Promis
     )
   }
 
+  //* Add location-related file reading promises based on settings
   if (settings.locationFile) {
     promises.push(
       readFile(join(settings.fieldDir, 'location.dat')).then((buffer) => { buffers.location = buffer }),
@@ -77,14 +81,17 @@ export async function reload(inputSettings?: IpLocationApiInputSettings): Promis
     }
   }
 
+  //* Wait for all file reading operations to complete
   await Promise.all(promises)
 
   const v4 = settings.v4
   const v6 = settings.v6
 
+  //* Create typed arrays from the loaded buffer data
   const v4StartIps = new Uint32Array(buffers.v4.dat1!.buffer, 0, buffers.v4.dat1!.byteLength >> 2)
   const v6StartIps = new BigUint64Array(buffers.v6.dat1!.buffer, 0, buffers.v6.dat1!.byteLength >> 3)
 
+  //* Set up v4 loaded data
   v4.loadedData = {
     startIps: v4StartIps,
     endIps: buffers.v4.dat2 ? new Uint32Array(buffers.v4.dat2.buffer, 0, buffers.v4.dat2.byteLength >> 2) : undefined,
@@ -93,6 +100,7 @@ export async function reload(inputSettings?: IpLocationApiInputSettings): Promis
     firstIp: v4StartIps[0]!,
   }
 
+  //* Set up v6 loaded data
   v6.loadedData = {
     startIps: v6StartIps,
     endIps: buffers.v6.dat2 ? new BigUint64Array(buffers.v6.dat2.buffer, 0, buffers.v6.dat2.byteLength >> 3) : undefined,
@@ -101,6 +109,7 @@ export async function reload(inputSettings?: IpLocationApiInputSettings): Promis
     firstIp: v6StartIps[0]!,
   }
 
+  //* Load additional data for City dataType
   if (settings.dataType === 'City') {
     LOADED_DATA.location = buffers.location
     LOADED_DATA.city = buffers.city
@@ -117,7 +126,10 @@ export async function reload(inputSettings?: IpLocationApiInputSettings): Promis
   }
 }
 
-export function clear() {
+/**
+ * Clears the loaded IP location data from memory.
+ */
+export function clear(): void {
   const settings = SAVED_SETTINGS
   settings.v4.loadedData = undefined
   settings.v6.loadedData = undefined