czdb/README_CN.md

A javascript library for searching IP address-related data in a CZDB database

# czdb-search-node

[![npm version][npm-version-src]][npm-version-href]
[![npm downloads][npm-downloads-src]][npm-downloads-href]

### 一个提供纯真离线社区版 IP 地址库`czdb`新格式数据查询的 nodejs 包。它支持两种类型的搜索算法：内存搜索（MEMORY）和 B 树搜索（BTREE）。数据库类型（IPv4 或 IPv6）和查询类型（MEMORY、BTREE）在运行时确定。

## 支持 IPv4 和 IPv6

czdb-search 支持 IPv4 和 IPv6 地址的查询。在创建 DbSearcher 实例时，你需要提供相应的数据库文件和密钥。

数据库文件和密钥可以从 [www.cz88.net](https://cz88.net/geo-public) 获取。

## 安装

### 请使用  **Node.js v8.0.0**  或者更高版本以取得 ES6 支持.

#### npm

```bash
npm install czdb
```

#### yarn

```bash
yarn add czdb
```

#### pnpm

```bash
pnpm add czdb
```

## 使用

### 注意：czdb 已经更改为了 ESM 包，因此在使用 `import` 引入时请在项目的 `package.json` 中设置`"type": "module"`，详见 [Pure ESM](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c)

```typescript
// 引入DbSearcher
import DbSearcher, { QueryType } from "czdb";

// CommonJS 使用 require 引入:
// const { default: DbSearcher, QueryType } = require('czdb');

// 准备好你的.czdb文件与密钥
const IPV4_DB_PATH = "YOUR_IPV4_DB_PATH";
const IPV4_IP = "1.64.219.93";
const KEY = "YOUR_KEY_HERE";

// 创建查询实例
const searcher = new DbSearcher(IPV4_DB_PATH, QueryType.BTREE, KEY);

// 使用 search 方法来根据提供的 IP 地址在数据库中搜索数据
const region = searcher.search(IPV4_IP);

// 返回的字符串格式为 "国家–省份–城市–区域 ISP" (区域与ISP之间使用"\t"分割)。如果搜索失败，它将返回 null。
console.log(region); // 中国–香港  电讯盈科有限公司

// 获取数据库版本
const version = searcher.getVersion();

console.log(version); // 20250103
```

## 使用样例

你可以在 example 文件夹下找到一个简单的使用样例，在填入路径与密钥后，运行以下命令以进行测试：

```bash
npm run test
```

## 查询类型

DbSearcher 支持 2 种查询类型：`MEMORY` 和 `BTREE`。

`MEMORY`：此模式是线程安全的，将数据存储在内存中。
`BTREE`：此模式使用 `B-tree` 数据结构进行查询。
你可以在创建 `DbSearcher` 实例时选择查询类型。

```typescript
const searcher = new DbSearcher("YOUR_DB_PATH", QueryType.BTREE, "YOUR_KEY");
```

## 关闭数据库

当查询结束且不再使用时，你应该关闭数据库。

```typescript
searcher.close();
```

这将释放所有使用的资源，并关闭对数据库文件的访问。

[npm-version-src]: https://img.shields.io/npm/v/czdb?style=flat-square
[npm-version-href]: https://npmjs.com/package/czdb
[npm-downloads-src]: https://img.shields.io/npm/dm/czdb?style=flat-square
[npm-downloads-href]: https://npmjs.com/package/czdb