ipdb
Version:
IP lookup using IPIP.net database (Node.js & Browser)
161 lines (144 loc) • 3.33 kB
TypeScript
declare module 'ipdb' {
/**
* IPDB constructor options
*/
export interface IPDBOptions {
/**
* Array of patch functions to transform result data
*/
patches?: Array<(data: Record<string, any>) => void>
}
/**
* Find query options
*/
export interface FindOptions {
/**
* Language code (e.g., 'CN', 'EN')
*/
language?: string
/**
* Query-specific patch functions
*/
patches?: Array<(data: Record<string, any>) => void>
}
/**
* Find result
*/
export interface FindResult {
/**
* Status code: 0 = success, -1 = error
*/
code: number
/**
* Geolocation data (only when code is 0)
*/
data?: Record<string, any>
/**
* Error message (only when code is -1)
*/
message?: string
}
/**
* IPDB database metadata
*/
export interface IPDBMetadata {
/**
* IP version support: 0x01 (IPv4), 0x02 (IPv6)
*/
ip_version: number
/**
* Number of nodes
*/
node_count: number
/**
* Language offset mapping
*/
languages: Record<string, number>
/**
* Field names array
*/
fields: string[]
/**
* IPv4 starting node index
*/
v4node?: number
}
/**
* IPDB IP database query class
*/
export default class IPDB {
/**
* Database metadata
*/
meta: IPDBMetadata
/**
* Binary data
*/
data: Uint8Array | Buffer
/**
* Global patch functions
*/
patches?: Array<(data: Record<string, any>) => void>
/**
* Create an IPDB instance
*
* @param data - Data source
* - Node.js: File path (string) or Buffer
* - Browser: ArrayBuffer or Uint8Array (loaded via Fetch/File API)
* @param options - Constructor options
*
* @example Node.js - file path
* ```typescript
* const ipdb = new IPDB('./data/ipipfree.ipdb')
* ```
*
* @example Node.js - Buffer
* ```typescript
* const fs = require('fs')
* const buffer = fs.readFileSync('./data/ipipfree.ipdb')
* const ipdb = new IPDB(buffer)
* ```
*
* @example Browser - Fetch API
* ```typescript
* const response = await fetch('/data/ipipfree.ipdb')
* const arrayBuffer = await response.arrayBuffer()
* const ipdb = new IPDB(arrayBuffer)
* ```
*
* @example Browser - File API
* ```typescript
* const file = event.target.files[0]
* const arrayBuffer = await file.arrayBuffer()
* const ipdb = new IPDB(arrayBuffer)
* ```
*/
constructor(
data: string | Buffer | ArrayBuffer | Uint8Array,
options?: IPDBOptions
)
/**
* Query IP address geolocation information
*
* @param ip - IPv4 or IPv6 address string
* @param options - Query options
* @returns Query result object
*
* @example
* ```typescript
* const result = ipdb.find('8.8.8.8')
* if (result.code === 0) {
* console.log(result.data.country_name) // Country name
* console.log(result.data.city_name) // City name
* } else {
* console.error(result.message)
* }
* ```
*/
find(ip: string, options?: FindOptions): FindResult
}
/**
* Named export
*/
export { IPDB }
}