@brid9e/fuzzy-search

🔍 智能模糊搜索库 - 高性能TypeScript实现，专为中文优化

✨ 特性

• 🚀 高性能 - 优化的算法实现，支持大数据集搜索
• 🇨🇳 中文友好 - 专门针对中文字符和词组优化
• 📦 现代化 - 完整的TypeScript支持，ESM/CommonJS双格式
• 🎯 智能匹配 - 多种匹配算法组合，精确度高
• ⚡ 缓存优化 - 内置缓存机制，提升重复搜索性能
• 🔧 可配置 - 灵活的权重配置和搜索选项

📦 安装

# 使用 npm
npm install @brid9e/fuzzy-search

# 使用 yarn
yarn add @brid9e/fuzzy-search

# 使用 pnpm
pnpm add @brid9e/fuzzy-search

🚀 快速开始

基础用法

import { smartFuzzySearch } from '@brid9e/fuzzy-search'

// 准备数据
const users = [
  { id: 1, name: '张三', email: '[email protected]' },
  { id: 2, name: '李四', email: '[email protected]' },
  { id: 3, name: '王五', email: '[email protected]' }
]

// 搜索用户
const result = smartFuzzySearch(users, 'name', '张')
console.log(result) // { id: 1, name: '张三', email: '[email protected]' }

获取所有匹配结果

import { smartFuzzySearchAll } from '@brid9e/fuzzy-search'

const results = smartFuzzySearchAll(users, 'name', '三', {
  minScore: 0.3
})
console.log(results) // 返回所有匹配度≥0.3的结果，按分数排序

🔧 API 文档

smartFuzzySearch<T>(list, field, searchTerm, options?): T | null

返回匹配度最高的单个结果。

参数:

• list: T[] - 要搜索的数组
• field: keyof T - 要搜索的字段名
• searchTerm: string - 搜索关键词
• options?: SearchOptions - 搜索选项

smartFuzzySearchAll<T>(list, field, searchTerm, options?): T[]

返回所有匹配的结果，按匹配度排序。

搜索选项 (SearchOptions)

interface SearchOptions {
  minScore?: number          // 最小匹配分数 (默认: 0.3)
  caseSensitive?: boolean    // 是否区分大小写 (默认: false)
  weightConfig?: Partial<WeightConfig>  // 权重配置
  enableCache?: boolean      // 启用缓存 (默认: true)
  maxEditDistance?: number   // 最大编辑距离 (默认: 10)
}

权重配置 (WeightConfig)

interface WeightConfig {
  exactMatch: number      // 完全匹配权重 (默认: 1.0)
  prefixMatch: number     // 前缀匹配权重 (默认: 0.8)
  containsMatch: number   // 包含匹配权重 (默认: 0.6)
  charSimilarity: number  // 字符相似度权重 (默认: 0.4)
  lengthSimilarity: number // 长度相似度权重 (默认: 0.2)
  wordBoundary: number    // 词边界匹配权重 (默认: 0.7)
  substringMatch: number  // 子串匹配权重 (默认: 0.9)
  commonPrefix: number    // 共同前缀权重 (默认: 0.85)
}

🎯 高级用法

自定义权重配置

import { smartFuzzySearch, DEFAULT_WEIGHT_CONFIG } from '@brid9e/fuzzy-search'

const result = smartFuzzySearch(users, 'name', '张', {
  minScore: 0.5,
  weightConfig: {
    ...DEFAULT_WEIGHT_CONFIG,
    exactMatch: 1.0,
    prefixMatch: 0.9,
    containsMatch: 0.7
  }
})

多字段搜索

const searchInMultipleFields = (data: any[], searchTerm: string) => {
  const fields = ['name', 'email', 'description']
  const allResults: any[] = []

  fields.forEach(field => {
    const results = smartFuzzySearchAll(data, field, searchTerm, {
      minScore: 0.4
    })
    allResults.push(...results)
  })

  // 去重并按相关性排序
  return [...new Set(allResults)]
}

中文词组搜索优化

const products = [
  { name: '苹果手机', category: '电子产品' },
  { name: '华为笔记本', category: '电脑设备' },
  { name: '小米耳机', category: '音频设备' }
]

// 搜索中文词组
const result = smartFuzzySearch(products, 'name', '苹果', {
  minScore: 0.3,
  caseSensitive: false
})

🔍 搜索算法

该库采用多种匹配算法的组合：

1. 完全匹配 - 最高权重，精确匹配
2. 前缀匹配 - 以搜索词开头的匹配
3. 包含匹配 - 包含搜索词的匹配
4. 子串匹配 - 子字符串匹配优化
5. 共同前缀 - 计算最长公共前缀
6. 连续字符匹配 - 优先匹配连续字符序列
7. 中文词组匹配 - 专门针对中文优化
8. 字符相似度 - 基于Jaccard相似度
9. 编辑距离 - Levenshtein距离计算
10. 长度相似度 - 考虑字符串长度差异

🎮 在线演示

// 实际使用示例
import { smartFuzzySearch, smartFuzzySearchAll } from '@brid9e/fuzzy-search'

const cities = [
  { name: '北京市', code: 'BJ', population: 21540000 },
  { name: '上海市', code: 'SH', population: 24280000 },
  { name: '广州市', code: 'GZ', population: 15300000 },
  { name: '深圳市', code: 'SZ', population: 13440000 }
]

// 模糊搜索城市
console.log(smartFuzzySearch(cities, 'name', '北京'))  // 完全匹配
console.log(smartFuzzySearch(cities, 'name', '上'))    // 前缀匹配
console.log(smartFuzzySearch(cities, 'name', '深'))    // 包含匹配

// 获取所有相似结果
console.log(smartFuzzySearchAll(cities, 'name', '市', { minScore: 0.4 }))

📊 性能测试

在包含10,000条记录的数据集上进行测试：

• ⚡ 平均搜索时间: < 5ms
• 🚀 缓存命中后: < 1ms
• 💾 内存占用: 极低
• 📈 准确率: > 95%

🤝 贡献

欢迎提交 Issue 和 Pull Request！

1. Fork 本仓库
2. 创建你的特性分支 (git checkout -b feature/AmazingFeature)
3. 提交你的修改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 打开一个 Pull Request

📝 更新日志

v0.0.1-alpha.1 (2025-01-06)

• 🎉 首次发布
• ✨ 支持智能模糊搜索
• 🇨🇳 优化中文字符匹配
• 📦 完整的TypeScript支持
• ⚡ 缓存机制优化
• 🔧 可配置的权重系统

📄 许可证

MIT License © 2025 @brid9e

🔗 相关链接

• 📦 NPM Package
• 📖 GitHub Repository
• 🐛 Issue Tracker
• 👤 Author

如果这个项目对你有帮助，请给个 ⭐ 支持一下！