ts-ip2region2 1.1.2 → 1.2.1

package/README.md

@@ -69,6 +69,35 @@ new Ip2Region(dbPath: string, options?: Ip2RegionOptions)
 - `Ip2Region.verify(dbPath: string): boolean` - Verify xdb file
 - `Ip2Region.verifyDetailed(dbPath: string): VerifyResult` - Verify with detailed info
 
+## Performance Benchmark
+
+Benchmark results on Windows x64 with Node.js v22.14.0 (10,000 iterations):
+
+| Cache Strategy | Avg Time (μs/op) | QPS |
+|---------------|------------------|-----|
+| file | ~31 | ~32,000 |
+| vectorIndex | ~22 | ~45,000 |
+| content | ~1.3 | ~750,000 |
+
+**Performance Improvements:**
+- vectorIndex is ~40% faster than file mode
+- content is ~95% faster than vectorIndex mode
+- content is ~96% faster than file mode
+
+**Comparison with Native C:**
+- Native C (vectorIndex): ~5 μs/op
+- Node.js Addon (vectorIndex): ~22 μs/op
+- Overhead: ~4.4x (mainly from N-API call overhead)
+
+Despite the N-API overhead, the performance is still excellent for most use cases, achieving 45,000+ QPS with vectorIndex mode.
+
+**Recommendation:** Use `vectorIndex` for most scenarios as it provides excellent performance with moderate memory usage.
+
+Run benchmark yourself:
+```bash
+npm run benchmark
+```
+
 ## License
 
 Apache-2.0

package/addon.cpp

@@ -10,6 +10,33 @@ extern "C" {
 #include "ip2region/xdb_api.h"
 }
 
+#ifdef XDB_WINDOWS
+// Windows UTF-8 path support
+extern "C" {
+    __declspec(dllimport) int __stdcall MultiByteToWideChar(unsigned int, unsigned long, const char*, int, wchar_t*, int);
+}
+#define CP_UTF8 65001
+
+static FILE* fopen_utf8(const char* path, const char* mode) {
+    int path_len = MultiByteToWideChar(CP_UTF8, 0, path, -1, nullptr, 0);
+    if (path_len == 0) return nullptr;
+    
+    wchar_t* wpath = new wchar_t[path_len];
+    MultiByteToWideChar(CP_UTF8, 0, path, -1, wpath, path_len);
+    
+    int mode_len = MultiByteToWideChar(CP_UTF8, 0, mode, -1, nullptr, 0);
+    wchar_t* wmode = new wchar_t[mode_len];
+    MultiByteToWideChar(CP_UTF8, 0, mode, -1, wmode, mode_len);
+    
+    FILE* file = _wfopen(wpath, wmode);
+    delete[] wpath;
+    delete[] wmode;
+    return file;
+}
+#else
+#define fopen_utf8 fopen
+#endif
+
 class Ip2RegionSearcher : public Napi::ObjectWrap<Ip2RegionSearcher> {
 public:
     static Napi::Object Init(Napi::Env env, Napi::Object exports);
@@ -26,10 +53,59 @@ private:
     xdb_vector_index_t* v_index;
     xdb_content_t* c_buffer;
     bool is_initialized;
+    
+    static xdb_vector_index_t* load_vector_index_utf8(const char* path);
+    static xdb_content_t* load_content_utf8(const char* path);
+    static int new_with_file_only_utf8(xdb_version_t* version, xdb_searcher_t* searcher, const char* path);
+    static int new_with_vector_index_utf8(xdb_version_t* version, xdb_searcher_t* searcher, const char* path, const xdb_vector_index_t* v_index);
 };
 
 Napi::FunctionReference Ip2RegionSearcher::constructor;
 
+xdb_vector_index_t* Ip2RegionSearcher::load_vector_index_utf8(const char* path) {
+    FILE* file = fopen_utf8(path, "rb");
+    if (!file) return nullptr;
+    xdb_vector_index_t* v_index = xdb_load_vector_index(file);
+    fclose(file);
+    return v_index;
+}
+
+xdb_content_t* Ip2RegionSearcher::load_content_utf8(const char* path) {
+    FILE* file = fopen_utf8(path, "rb");
+    if (!file) return nullptr;
+    xdb_content_t* content = xdb_load_content(file);
+    fclose(file);
+    return content;
+}
+
+int Ip2RegionSearcher::new_with_file_only_utf8(xdb_version_t* version, xdb_searcher_t* searcher, const char* path) {
+    FILE* file = fopen_utf8(path, "rb");
+    if (!file) return -1;
+    
+    memset(searcher, 0, sizeof(xdb_searcher_t));
+    searcher->version = version;
+    searcher->handle = file;
+    searcher->v_index = nullptr;
+    searcher->content = nullptr;
+    searcher->io_count = 0;
+    
+    return 0;
+}
+
+int Ip2RegionSearcher::new_with_vector_index_utf8(xdb_version_t* version, xdb_searcher_t* searcher, const char* path, const xdb_vector_index_t* v_index) {
+    FILE* file = fopen_utf8(path, "rb");
+    if (!file) return -1;
+    
+    memset(searcher, 0, sizeof(xdb_searcher_t));
+    searcher->version = version;
+    searcher->handle = file;
+    searcher->v_index = v_index;
+    searcher->content = nullptr;
+    searcher->io_count = 0;
+    
+    return 0;
+}
+
 Napi::Object Ip2RegionSearcher::Init(Napi::Env env, Napi::Object exports) {
     Napi::HandleScope scope(env);
 
@@ -91,17 +167,17 @@ Ip2RegionSearcher::Ip2RegionSearcher(const Napi::CallbackInfo& info)
 
     // Initialize searcher based on cache strategy
     if (cache_policy == "file") {
-        err = xdb_new_with_file_only(version, &searcher, db_path.c_str());
+        err = new_with_file_only_utf8(version, &searcher, db_path.c_str());
     } else if (cache_policy == "vectorIndex") {
-        v_index = xdb_load_vector_index_from_file(db_path.c_str());
+        v_index = load_vector_index_utf8(db_path.c_str());
         if (!v_index) {
             xdb_clean_winsock();
             Napi::Error::New(env, "Failed to load vector index from database file").ThrowAsJavaScriptException();
             return;
         }
-        err = xdb_new_with_vector_index(version, &searcher, db_path.c_str(), v_index);
+        err = new_with_vector_index_utf8(version, &searcher, db_path.c_str(), v_index);
     } else if (cache_policy == "content") {
-        c_buffer = xdb_load_content_from_file(db_path.c_str());
+        c_buffer = load_content_utf8(db_path.c_str());
         if (!c_buffer) {
             xdb_clean_winsock();
             Napi::Error::New(env, "Failed to load database content into memory").ThrowAsJavaScriptException();
@@ -213,19 +289,11 @@ Napi::Value VerifyXdb(const Napi::CallbackInfo& info) {
     
     const std::string db_path = info[0].As<Napi::String>().Utf8Value();
     
-    int error_code = 0;
-    FILE* file_handle = std::fopen(db_path.c_str(), "rb");
-    
-    if (!file_handle) {
-        error_code = -1; // File not found or cannot be opened
-    } else {
-        xdb_header_t* header = xdb_load_header(file_handle);
-        if (!header) {
-            error_code = 1; // Invalid file format
-        } else {
-            xdb_free_header(header);
-        }
-        std::fclose(file_handle);
+    FILE* file = fopen_utf8(db_path.c_str(), "rb");
+    int error_code = -1;
+    if (file) {
+        error_code = xdb_verify(file);
+        fclose(file);
     }
     
     Napi::Object result = Napi::Object::New(env);

package/ip2region/ReadMe.md

@@ -0,0 +1,353 @@
+# ip2region xdb c 查询客户端实现
+
+
+# 使用方式
+
+### 关于查询 API
+查询 API 的原型如下：
+```c
+// 通过字符串 IP 进行查询
+int xdb_search_by_string(xdb_searcher_t *, const string_ip_t *, xdb_region_buffer_t *);
+// 通过 xdb_parse_ip 返回的二进制 IP 进行查询
+int xdb_search(xdb_searcher_t *, const bytes_ip_t *, int, xdb_region_buffer_t *);
+```
+如果查询失败将会返回非 `0` 的错误代码，如果查询成功 xdb_region_buffer_t 可以获取到字符串的 `region` 信息，如果输入的 IP 找不到相关的信息，xdb_region_buffer_t 将会得到一个空的字符串 `""`。
+
+### 关于 IPv4 和 IPv6
+该 xdb 查询客户端实现同时支持对 IPv4 和 IPv6 的查询，使用方式如下：
+```c
+#include "xdb_api.h";
+
+// 如果是 IPv4: 设置 xdb 路径为 v4 的 xdb 文件，IP版本指定为 IPv4
+const char *db_path  = "../../data/ip2region_v4.xdb";  // 或者你的 ipv4 xdb 的路径
+xdb_version_t *version = XDB_IPv4;
+
+// 如果是 IPv6: 设置 xdb 路径为 v6 的 xdb 文件，IP版本指定为 IPv6
+const char *db_path  = "../../data/ip2region_v6.xdb";  // 或者你的 ipv6 xdb 路径
+xdb_version_t *version = XDB_IPv6;
+
+// db_path 指定的 xdb 的 IP 版本必须和 version 指定的一致，不然查询执行的时候会报错
+// 备注：以下演示直接使用 db_path 和 version 变量
+```
+
+### XDB 文件验证
+建议您主动去验证 xdb 文件的适用性，因为后期的一些新功能可能会导致目前的 Searcher 版本无法适用你使用的 xdb 文件，验证可以避免运行过程中的一些不可预测的错误。 你不需要每次都去验证，例如在服务启动的时候，或者手动调用命令验证确认版本匹配即可，不要在每次创建的 Searcher 的时候运行验证，这样会影响查询的响应速度，尤其是高并发的使用场景。
+```c
+#include "xdb_api.h";
+
+int errcode = xdb_verify(db_path);
+if ($err != 0) {
+    // 适用性验证失败！！！
+    // 当前查询客户端实现不适用于 db_path 指定的 xdb 文件的查询.
+    // 应该停止启动服务，使用合适的 xdb 文件或者升级到适合 db_path 的 Searcher 实现。
+    printf("failed to verify xdb file `%s`, errcode: %d\n", db_path, errcode);
+    return;
+}
+
+// 验证通过，当前使用的 Searcher 可以安全的用于对 dbPath 指向的 xdb 的查询操作
+```
+
+### 完全基于文件的查询
+
+```c
+#include <stdio.h>
+#include "xdb_api.h"
+
+int main(int argc, char *argv[]) {
+    xdb_searcher_t searcher;
+    char region_buffer[512] = {'\0'};
+    xdb_region_buffer_t region;
+
+    // 使用栈空间的 region_buffer 初始化 region_buffer_t
+    int err = xdb_region_buffer_init(&region, region_buffer, sizeof(region_buffer));
+    if (err != 0) {
+        printf("failed to init the region buffer with errcode=%d\n", err);
+        return 1;
+    }
+
+    // 在服务启动的时候初始化 winsock，不需要重复调用，只需要在 windows 系统下调用
+    err = xdb_init_winsock();
+    if (err != 0) {
+        printf("failed to init the winsock with errno=%d\n", err);
+        return 1;
+    }
+
+    // 1、从 db_path 初始化 xdb 查询对象.
+    // @Note: 使用顶部描述的 db_path 和 version 来创建 searcher
+    err = xdb_new_with_file_only(version, &searcher, db_path);
+    if (err != 0) {
+        printf("failed to create xdb searcher from `%s` with errno=%d\n", db_path, err);
+        return 1;
+    }
+
+    // 2、调用 search API 查询，IPv4 和 IPv6 都支持.
+    const char *ip_string = "1.2.3.4";
+    // ip_string = "2001:4:112:ffff:ffff:ffff:ffff:ffff"; // IPv6
+
+    long cost_time = 0, s_time = xdb_now();
+    err = xdb_search_by_string(&searcher, ip_string, &region);
+    cost_time = (int) (xdb_now() - s_time);
+    if (err != 0) {
+        printf("failed search(%s) with errno=%d\n", ip_string, err);
+    } else {
+        printf("{region: %s, took: %d μs}", region.value, cost_time);
+    }
+
+    // 清理 region 信息的内存资源，每次 search 之后都得调用
+    xdb_region_buffer_free(&region);
+
+    // 备注：并发使用，每一个线程需要单独定义并且初始化一个 searcher 查询对象。
+
+    // 3、关闭 xdb 查询器
+    xdb_close(&searcher);
+    xdb_clean_winsock();    // windows 下调用
+    return 0;
+}
+```
+
+### 缓存 `VectorIndex` 索引
+
+我们可以提前从 xdb 文件中加载出来 VectorIndex 数据，然后全局缓存，每次创建 Searcher 对象的时候使用全局的 VectorIndex 缓存可以减少一次固定的 IO 操作，从而加速查询，减少 IO 压力。
+```c
+#include <stdio.h>
+#include "xdb_api.h"
+
+int main(int argc, char *argv[]) {
+    xdb_vector_index_t *v_index;
+    xdb_searcher_t searcher;
+    xdb_region_buffer_t region;
+
+    // 使用 NULL 初始化 region_buffer，让其自动管理内存的分配
+    int err = xdb_region_buffer_init(&region, NULL, 0);
+    if (err != 0) {
+        printf("failed to init the region buffer with errcode=%d\n", err);
+        return 0;
+    }
+
+    // 在服务启动的时候初始化 winsock，不需要重复调用，只需要在 windows 系统下调用
+    err = xdb_init_winsock();
+    if (err != 0) {
+        printf("failed to init the winsock with errno=%d\n", err);
+        return 1;
+    }
+
+    // 1、从顶部描述的 db_path 加载 VectorIndex 索引。
+    // 得到 v_index 做成全局缓存，便于后续反复使用。
+    // 注意：v_index 不需要每次都加载，建议在服务启动的时候加载一次，然后做成全局资源。
+    v_index = xdb_load_vector_index_from_file(db_path);
+    if (v_index == NULL) {
+        printf("failed to load vector index from `%s`\n", db_path);
+        return 1;
+    }
+
+    // 2、使用全局的 VectorIndex 变量创建带 VectorIndex 缓存的 xdb 查询对象.
+    // @Note: 使用顶部描述的 db_path 和 version 来创建 searcher
+    err = xdb_new_with_vector_index(version, &searcher, db_path, v_index);
+    if (err != 0) {
+        printf("failed to create vector index cached searcher with errcode=%d\n", err);
+        return 2;
+    }
+
+
+    // 3、调用 search API 查询，IPv4 和 IPv6 都支持
+    const char *ip_string = "1.2.3.4";
+    // ip_string = "2001:4:112:ffff:ffff:ffff:ffff:ffff"; // IPv6
+
+    long cost_time = 0, s_time = xdb_now();
+    err = xdb_search_by_string(&searcher, ip_string, &region);
+    cost_time = (int) (xdb_now() - s_time);
+    if (err != 0) {
+        printf("failed search(%s) with errno=%d\n", ip_string, err);
+    } else {
+        printf("{region: %s, took: %d μs}", region.value, cost_time);
+    }
+
+    // 清理 region 信息的内存资源，每次 search 之后都得调用
+    xdb_region_buffer_free(&region);
+
+
+    // 备注：并发使用，每一个线程需要单独定义并且初始化一个 searcher 查询对象。
+
+    // 4、关闭 xdb 查询器，如果是要关闭服务，也需要释放 v_index 的内存。
+    xdb_close(&searcher);
+    xdb_close_vector_index(v_index);
+    xdb_clean_winsock();
+    return 0;
+}
+```
+
+### 缓存整个 `xdb` 数据
+
+我们也可以预先加载整个 xdb 文件到内存，然后基于这个数据创建查询对象来实现完全基于内存的查询，类似之前的 memory search。
+```c
+#include <stdio.h>
+#include "xdb_api.h"
+
+int main(int argc, char *argv[]) {
+    xdb_content_t *c_buffer;
+    xdb_searcher_t searcher;
+    xdb_region_buffer_t region;
+
+    // 使用 NULL 初始化 region_buffer，让其自动管理内存的分配
+    int err = xdb_region_buffer_init(&region, NULL, 0);
+    if (err != 0) {
+        printf("failed to init the region buffer with errcode=%d\n", err);
+        return 0;
+    }
+
+
+    // 在服务启动的时候初始化 winsock，不需要重复调用，只需要在 windows 系统下调用
+    err = xdb_init_winsock();
+    if (err != 0) {
+        printf("failed to init the winsock with errno=%d\n", err);
+        return 1;
+    }
+
+    // 1、从 顶部描述的 db_path 加载整个 xdb 的数据。
+    c_buffer = xdb_load_content_from_file(db_path);
+    if (v_index == NULL) {
+        printf("failed to load xdb content from `%s`\n", db_path);
+        return 1;
+    }
+
+    // 2、使用全局的 c_buffer 变量创建一个完全基于内存的 xdb 查询对象.
+    // @Note: 使用顶部描述的 version 来创建 searcher.
+    err = xdb_new_with_buffer(version, &searcher, c_buffer);
+    if (err != 0) {
+        printf("failed to create content cached searcher with errcode=%d\n", err);
+        return 2;
+    }
+
+    // 3、调用 search API 查询，IPv4 和 IPv6 都支持
+    const char *ip_string = "1.2.3.4";
+    // ip_string = "2001:4:112:ffff:ffff:ffff:ffff:ffff"; // IPv6
+
+    long cost_time = 0, s_time = xdb_now();
+    err = xdb_search_by_string(&searcher, ip_string, &region);
+    cost_time = (int) (xdb_now() - s_time);
+    if (err != 0) {
+        printf("failed search(%s) with errno=%d\n", ip_string, err);
+    } else {
+        printf("{region: %s, took: %d μs}", region.value, cost_time);
+    }
+
+    // 清理 region 信息的内存资源，每次 search 之后都得调用
+    xdb_region_buffer_free(&region);
+
+
+    // 备注：并发使用，使用这种方式创建的 xdb 查询对象可以安全用于并发。
+    // 建议在服务启动的时候创建好，然后一直安全并发使用，直到服务关闭。
+
+    // 4、关闭 xdb 查询器，关闭服务的时候需要释放 c_buffer 的内存。
+    xdb_close(&searcher);
+    xdb_close_content(c_buffer);
+    xdb_clean_winsock();
+    return 0;
+}
+```
+
+### 关于定位信息的存储
+在旧版本的实现中，search相关的函数都是依靠指定一个 `region_buffer` 内存来用于存储地域信息，这种方式还是有很大的局限性。
+新的实现提供了一个 `xdb_region_buffer_t` 对象来管理这些内存的分配，你依然可以指定一个固定的 `region_buffer` 来创建 region 的内存管理，这个情况适合当你的地域信息的最大长度是可知的，这种方式可以减少运行过程中内存的碎片堆积。如果地域信息的长度不确定或者你的程序不适合提前分配一块内存来管理，你可以通过指定 NULL 的方式来初始化 `xdb_region_buffer_t`，这样对象会自动管理内存的分配，也适合任意长度的地域信息的存储，不过这种方式在长期的运行过程中肯定会增加内存碎片的堆积。
+```c
+// 1, 通过指定一块内存来创建 region_buffer
+char buffer[512];
+xdb_region_buffer_t region;
+int err = xdb_region_buffer_init(&region, buffer, sizeof(buffer));
+if (err != 0) {
+    // 初始化失败
+    printf("failed to init region buffer width errcode=%d", err);
+    return;
+}
+
+// 2，通过指定 NULL 来创建 region_buffer，让其自动按需分配内存
+xdb_region_buffer_t region;
+int err = xdb_region_buffer_init(&region, NULL, 0);
+if (err != 0) {
+    // 初始化失败
+    printf("failed to init region buffer width errcode=%d", err);
+    return;
+}
+
+
+// 备注：在每次调用 search 完成 IP 定位信息的查询后，你需要手动调用函数来释放内存 .
+// search 函数使用未经清理的 region 信息会报错。
+xdb_region_buffer_free(&region);
+```
+
+
+# 测试程序编译
+
+通过如下方式编译得到 xdb_searcher 可执行程序：
+```bash
+# cd 到 c binding 根目录
+➜  c git:(fr_c_ipv6) ✗ make
+gcc -O2 -I./ xdb_util.c xdb_searcher.c main.c -o xdb_searcher
+gcc -O2 -I./ xdb_util.c test_util.c -o test_util
+```
+
+
+# 查询测试
+
+通过 `xdb_searcher search` 命令来测试对 xdb 的查询：
+```bash
+➜  c git:(fr_c_ipv6) ✗ ./xdb_searcher search
+./xdb_searcher search [command options]
+options:
+ --db string              ip2region binary xdb file path
+ --cache-policy string    cache policy: file/vectorIndex/content
+```
+
+例如：使用默认的 data/ip2region_v4.xdb 进行 IPv4 查询测试：
+```bash
+➜  c git:(fr_c_ipv6) ✗ ./xdb_searcher search --db=../../data/ip2region_v4.xdb
+ip2region xdb searcher test program
+source xdb: ../../data/ip2region_v4.xdb (IPv4, vectorIndex)
+type 'quit' to exit
+ip2region>> 120.229.45.2
+{region: 中国|广东省|深圳市|移动, io_count: 3, took: 29 μs}
+```
+
+例如：使用默认的 data/ip2region_v6.xdb 进行 IPv6 查询测试：
+```bash
+➜  c git:(fr_c_ipv6) ✗ ./xdb_searcher search --db=../../data/ip2region_v6.xdb
+ip2region xdb searcher test program
+source xdb: ../../data/ip2region_v6.xdb (IPv6, vectorIndex)
+type 'quit' to exit
+ip2region>> ::
+{region: , io_count: 1, took: 38 μs}
+ip2region>> 2604:bc80:8001:11a4:ffff:ffff:ffff:ffff
+{region: 美国|特拉华州|刘易斯|数据中心, io_count: 14, took: 77 μs}
+ip2region>> 240e:3b7:3272:d8d0:db09:c067:8d59:539e
+{region: 中国|广东省|深圳市|家庭宽带, io_count: 8, took: 46 μs}
+```
+
+输入 ip 即可进行查询，输入 quit 即可退出测试程序。也可以分别设置 `cache-policy` 为 file/vectorIndex/content 来测试三种不同的缓存实现的效率。
+
+
+
+# bench 测试
+
+通过 `xdb_searcher bench` 命令来进行 bench 测试，一方面确保查询程序和 `xdb` 文件没有错误，另一方面可以通过大量的查询得到评价的查询性能：
+```bash
+➜  c git:(fr_c_ipv6) ✗ ./xdb_searcher bench                                  
+./xdb_searcher bench [command options]
+options:
+ --db string              ip2region binary xdb file path
+ --src string             source ip text file path
+ --cache-policy string    cache policy: file/vectorIndex/content
+```
+
+例如：通过默认的 data/ip2region_v4.xdb 和 data/ipv4_source.txt 来进行 IPv4 的 bench 测试：
+```bash
+➜  c git:(fr_c_ipv6) ✗ ./xdb_searcher bench --db=../../data/ip2region_v4.xdb --src=../../data/ipv4_source.txt
+Bench finished, {cache_policy: vectorIndex, total: 1367686, took: 7.640s, cost: 5 μs/op}
+```
+
+例如：通过默认的 data/ip2region_v6.xdb 和 data/ipv6_source.txt 来进行 IPv6 的 bench 测试：
+```bash
+➜  c git:(fr_c_ipv6) ✗ ./xdb_searcher bench --db=../../data/ip2region_v6.xdb --src=../../data/ipv6_source.txt
+Bench finished, {cache_policy: vectorIndex, total: 34159862, took: 857.750s, cost: 24 μs/op}
+```
+
+可以设置 `cache-policy` 参数来分别测试 file/vectorIndex/content 不同缓存实现机制的效率。 @Note：请注意 bench 使用的 src 文件需要是生成对应的 xdb 文件相同的源文件。

package/ip2region/xdb_api.h

@@ -24,13 +24,16 @@
 #include <ws2tcpip.h>
 #include <windows.h>
 #pragma comment(lib, "ws2_32.lib")
-#elif ( defined(linux) || defined(_UNIX) || defined(__APPLE__) )
+#elif (defined(linux) || defined(_UNIX) || defined(__APPLE__) || defined(unix) || defined(__unix) || defined(__unix__) || defined(__linux__) || defined(linux) || defined(__linux))
 #   define XDB_PUBLIC(type)    extern type
 #   define XDB_PRIVATE(type)   static inline type
 #   define XDB_LINUX
 #include <sys/socket.h>
 #include <netinet/in.h>
 #include <arpa/inet.h>
+#else
+#   define XDB_PUBLIC(type) type
+#   define XDB_PRIVATE(type) static type
 #endif
 
 #define xdb_calloc( _blocks, _bytes )  calloc( _blocks, _bytes )
@@ -224,6 +227,10 @@ XDB_PUBLIC(int) xdb_region_buffer_init(xdb_region_buffer_t *, char *, size_t);
 // returns: 0 for ok or failed
 XDB_PUBLIC(int) xdb_region_buffer_alloc(xdb_region_buffer_t *, int);
 
+// empty alloc - empty string
+// returns:  0 - always
+XDB_PUBLIC(int) xdb_region_buffer_empty(xdb_region_buffer_t *);
+
 XDB_PUBLIC(void) xdb_region_buffer_free(xdb_region_buffer_t *);
 
 // xdb searcher structure
@@ -269,4 +276,4 @@ XDB_PUBLIC(int) xdb_get_io_count(xdb_searcher_t *);
 
 // --- END xdb searcher api
 
-#endif // C_IP2REGION_XDB_H
+#endif // C_IP2REGION_XDB_H

package/ip2region/xdb_searcher.c

@@ -57,9 +57,38 @@ XDB_PUBLIC(int) xdb_region_buffer_alloc(xdb_region_buffer_t *region, int length)
     return 0;
 }
 
+// fixed internal empty string ptr
+static char * _empty_region_string = "\0";
+
+XDB_PUBLIC(int) xdb_region_buffer_empty(xdb_region_buffer_t *region) {
+    // no allocation supports for the buffer wapper
+    if (region->type == xdb_region_buffer_wrapper) {
+        region->value[0] = '\0';
+        return 0;
+    }
+
+    // ensure that the value were freed
+    // by calling #xdb_region_buffer_free
+    if (region->value != NULL) {
+        return 3;
+    }
+
+    region->value  = _empty_region_string;
+    region->length = 0;
+    return 0;
+}
+
 XDB_PUBLIC(void) xdb_region_buffer_free(xdb_region_buffer_t *region) {
     if (region->type == xdb_region_buffer_auto) {
-        xdb_free(region->value);
+        // empty string interception
+        if (region->length == 0 
+            || region->value == _empty_region_string) {
+            // do nothing for empty string
+        } else {
+            xdb_free(region->value);
+        }
+
+        // reset the value
         region->value = NULL;
     }
 }
@@ -196,7 +225,9 @@ XDB_PUBLIC(int) xdb_search(xdb_searcher_t *xdb, const bytes_ip_t *ip_bytes, int
 
     // printf("data_len=%u, data_ptr=%u\n", data_len, data_ptr);
     if (data_len == 0) {
-        return 100;
+        // return 100;
+        xdb_region_buffer_empty(region);
+        return err;
     }
 
     // buffer alloc checking
@@ -239,4 +270,4 @@ XDB_PUBLIC(xdb_version_t *) xdb_get_version(xdb_searcher_t *xdb) {
 
 XDB_PUBLIC(int) xdb_get_io_count(xdb_searcher_t *xdb) {
     return xdb->io_count;
-}
+}

package/ip2region/xdb_util.c

@@ -245,9 +245,14 @@ XDB_PUBLIC(int) xdb_verify_from_header(FILE *handle, xdb_header_t *header) {
     }
 
     long int fileBytes = ftell(handle);
-    long int maxFilePtr = (1L << (runtime_ptr_bytes * 8)) - 1;
-    // printf("fileBytes: %ld, maxFilePtr: %ld\n", fileBytes, maxFilePtr);
-    if (fileBytes > maxFilePtr) {
+    if (fileBytes < 0) {
+        return 3;
+    }
+    
+    // Use unsigned long long for maxFilePtr to avoid overflow
+    unsigned long long maxFilePtr = (1ULL << (runtime_ptr_bytes * 8)) - 1;
+    // printf("fileBytes: %ld, maxFilePtr: %llu\n", fileBytes, maxFilePtr);
+    if ((unsigned long long)fileBytes > maxFilePtr) {
         return 4;
     }
 
@@ -392,10 +397,12 @@ XDB_PUBLIC(int) xdb_le_get_uint16(const char *buffer, int offset) {
 }
 
 XDB_PUBLIC(xdb_version_t *) xdb_parse_ip(const string_ip_t *ip_string, bytes_ip_t *buffer, size_t length) {
+    char *d_ptr = strchr(ip_string, '.');
+    char *c_ptr = strchr(ip_string, ':');
     // version check
-    if (strchr(ip_string, '.') != NULL && strchr(ip_string, ':') == NULL) {
+    if (d_ptr != NULL && c_ptr == NULL) {
         return xdb_parse_v4_ip(ip_string, buffer, length);
-    } else if (strchr(ip_string, ':') != NULL) {
+    } else if (c_ptr != NULL) {
         return xdb_parse_v6_ip(ip_string, buffer, length);
     }
 
@@ -493,4 +500,4 @@ XDB_PUBLIC(int) xdb_ip_sub_compare(const bytes_ip_t *ip1, int bytes, const char
         }
     }
     return 0;
-}
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ts-ip2region2",
-  "version": "1.1.2",
+  "version": "1.2.1",
   "description": "TypeScript-first ip2region implementation with native Node.js addon. Ultra-fast IPv4/IPv6 geolocation queries.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -11,6 +11,7 @@
     "rebuild": "node-gyp rebuild",
     "clean": "node-gyp clean",
     "test": "npm run build:all && node test.js",
+    "benchmark": "node benchmark.js",
     "example": "npm run build:all && node example.js",
     "prepublishOnly": "npm run build:all"
   },