@leolee9086/string-metrics-dice/README.md

Sørensen-Dice 系数算法库

# String Metrics Dice

高性能 Sørensen-Dice 系数算法库，支持多种实现变体和竞争系统。



## 📦 安装

```bash
npm install string-metrics-dice
```

## 🚀 快速开始

### 基础使用

```javascript
import { computeDiceCoefficient } from 'string-metrics-dice';

// 计算两个字符串的 Dice 系数
const similarity = computeDiceCoefficient('hello', 'helo');
console.log(similarity); // 0.8571428571428571

// 使用选项
const similarity2 = computeDiceCoefficient('Hello', 'helo', {
  normalize: true
});
console.log(similarity2); // 0.8571428571428571
```

### WASM 高性能版本

```javascript
import { computeDiceCoefficientWasm } from 'string-metrics-dice/wasm';

// 异步初始化
await computeDiceCoefficientWasm.init();

// 高性能计算
const similarity = computeDiceCoefficientWasm.compute('hello', 'helo');
console.log(similarity); // 0.8571428571428571
```

## 📚 API 文档

### `computeDiceCoefficient(str1, str2, options?)`

计算两个字符串的 Sørensen-Dice 系数。

**参数:**
- `str1` (string): 第一个字符串
- `str2` (string): 第二个字符串
- `options` (object, 可选): 计算选项
  - `normalize` (boolean): 是否进行 Unicode 标准化，默认 `false`
  - `nGramSize` (number): n-gram 大小，默认 `2` (bigram)

**返回值:**
- `number`: Dice 系数，范围 [0, 1]，1 表示完全相同

### `computeDiceDistance(str1, str2, options?)`

计算两个字符串的 Dice 距离（1 - Dice 系数）。

**参数:** 同 `computeDiceCoefficient`

**返回值:**
- `number`: Dice 距离，范围 [0, 1]，0 表示完全相同

## 🏗️ 算法原理

Sørensen-Dice 系数基于字符 n-gram 的重叠度计算：

```
Dice = 2 * |A ∩ B| / (|A| + |B|)
```

其中：
- A, B 是两个字符串的 n-gram 集合
- |A ∩ B| 是交集大小
- |A|, |B| 是各自集合大小


## 🔧 开发

### 安装依赖

```bash
npm install
```

### 运行测试

```bash
npm test
```

### 运行基准测试

```bash
npm run bench
```

### 构建 WASM

```bash
npm run build:wasm
```

## 许可证

AGPL=3.0 License