Fuse

KO | EN

gitlite — search

#javascript #python #hacktoberfest #react #ai #typescript #llm #go #golang #android #machine-learning #rust #deep-learning #linux

★ 20,444 Open GitHub ↗

JavaScript로 구현된 경량 퍼지 검색(fuzzy-search)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Fuse.js
![Node.js CI](https://github.com/krisk/Fuse/workflows/Node.js%20CI/badge.svg)
[![Version](https://img.shields.io/npm/v/fuse.js.svg)](https://www.npmjs.com/package/fuse.js)
[![Downloads](https://img.shields.io/npm/dm/fuse.js.svg)](https://npmcharts.com/compare/fuse.js?minimal=tru)
[![code style: prettier](https://img.shields.io/badge/code\_style-prettier-ff69b4.svg?style=flat-square)](https://github.com/prettier/prettier)
[![Contributors](https://img.shields.io/github/contributors/krisk/fuse.svg)](https://github.com/krisk/Fuse/graphs/contributors)
![License](https://img.shields.io/npm/l/fuse.js.svg)
Fuse.js는 TypeScript로 작성된 가볍고 의존성이 없는 퍼지 검색(fuzzy-search) 라이브러리입니다. 브라우저와 서버 모두에서 동작하며, 전용 검색 백엔드를 사용할 수 없는 클라이언트 측 환경에서 중소규모 데이터셋을 검색하도록 설계되었습니다.

## ✨ 새로운 기능: 토큰 검색 (Token Search)
관련성 순위가 포함된 다중 단어 퍼지 검색입니다. `"javascrpt paterns"`를 입력하면 오타 허용, 다중 단어, 스마트 순위 지정을 통해 한 번에 `"JavaScript Patterns"`를 찾아냅니다.

```js
const fuse = new Fuse(docs, {
useTokenSearch: true,
keys: ['title', 'author', 'description']
})
fuse.search('javascrpt paterns')
// → [{ item: { title: 'JavaScript Patterns', ... } }]
```

자세한 내용은 아래의 [Token Search](#token-search)를 참조하세요.

## Web Workers
UI를 멈추게 하지 않고 대용량 데이터셋을 검색하세요. `FuseWorker`는 데이터를 여러 Web Workers에 분산시키고 병렬로 검색하므로 10만 개의 문서에서 약 5배 더 빠르게 동작합니다.

```js
import { FuseWorker } from 'fuse.js/worker'
const fuse = new FuseWorker(docs, {
keys: ['title', 'author', 'description']
})
const results = await fuse.search('query')
fuse.terminate()
```

`Fuse`와 동일한 옵션 및 결과를 제공하며 단지 비동기로 작동합니다. 함수 형태의 옵션(`sortFn`, `getFn`, `keys[].getFn`)은 함수를 워커로 전송할 수 없으므로 지원되지 않으며, 그 외의 기능은 모두 그대로 유지됩니다. 인터랙티브 데모와 전체 API는 [Web Workers docs](https://fusejs.io/web-workers.html)를 참조하세요.

## 설치 (Installation)

```bash
npm install fuse.js
```

```bash
yarn add fuse.js
```

또는 CDN을 통해 직접 포함할 수 있습니다:

```html
```

## 빠른 시작 (Quick Start)

```js
import Fuse from 'fuse.js'
const books = [
{ title: "Old Man's War", author: 'John Scalzi' },
{ title: 'The Lock Artist', author: 'Steve Hamilton' },
{ title: 'HTML5', author: 'Remy Sharp' },
{ title: 'JavaScript: The Good Parts', author: 'Douglas Crockford' }
]
const fuse = new Fuse(books, {
keys: ['title', 'author']
})
fuse.search('javscript')
// → [{ item: { title: 'JavaScript: The Good Parts', ... }, ... }]
```

## 주요 기능 (Features)

### 퍼지 검색 (Fuzzy Search)
Fuse.js의 핵심 기능입니다. 대략적인 문자열 매칭을 위해 [Bitap algorithm](https://en.wikipedia.org/wiki/Bitap\_algorithm)을 사용하여 오타, 철자 오류, 부분 일치를 기본으로 처리합니다.

```js
fuse.search('javscript')
// → [{ item: { title: 'JavaScript: The Good Parts', author: 'Douglas Crockford' } }]
```

### 가중치 키 (Weighted Keys)
중요도가 다른 여러 필드를 동시에 검색할 수 있습니다. 제목 일치가 설명 일치보다 더 높은 순위를 가질 수 있습니다.

```js
const fuse = new Fuse(docs, {
keys: [
{ name: 'title', weight: 2 },
{ name: 'description', weight: 1 }
]
})
```

### 확장 검색 (Extended Search)
정확한 제어를 위해 연산자를 사용하세요: 정확한 일치(`=`), 접두사(`^`), 접미사(`!`) 등. `useExtendedSearch: true`로 활성화할 수 있습니다.

```js
const fuse = new Fuse(list, {
useExtendedSearch: true,
keys: ['title']
})
fuse.search('=exact match') // 정확히 일치
fuse.search('^prefix') // 다음으로 시작
fuse.search('!term') // 포함하지 않음
```

### 객체 쿼리 구문 (Object Query Syntax)
특수 기호 대신 구조화되고 자체 문서화된 대안을 선호하시나요? 동일한 연산자를 객체 형태로 표현하세요. 문자열 형식과 달리 이 방식은 **`useExtendedSearch` 플래그가 필요 없으며**(연산자가 명확함), TypeScript에서 자동 완성 기능을 지원하고 따옴표나 이스케이프 처리가 필요하지 않습니다.

```js
const fuse = new Fuse(list, { keys: ['title', 'author'] })
fuse.search({ title: { $startsWith: 'old' }, author: { $eq: 'Kay' } })
```

각 연산자는 문자열 대응물과 매핑됩니다.

valent:
| Object | String | Matches when the field |
| ------------- | ------- | ----------------------------- |
| `$fuzzy` | `term` | 퍼지 매칭 (오타 허용) |
| `$eq` | `=term` | 값이 일치함 |
| `$contains` | `'term` | 값을 포함함 |
| `$startsWith` | `^term` | 값으로 시작함 |
| `$endsWith` | `term$` | 값으로 끝남 |
`$not`을 사용하여 부정할 수 있으며, 이는 `$contains`, `$startsWith`, `$endsWith` 중 정확히 하나를 감쌉니다:
```js
fuse.search({ title: { $not: { $contains: 'draft' } } }) // === '!draft'
fuse.search({ title: { $not: { $startsWith: 'old' } } }) // === '!^old'
fuse.search({ title: { $not: { $endsWith: '.go' } } }) // === '!.go$'
```
하나의 필드에 여러 연산자를 사용하면 AND 조건이 적용됩니다. 더 복잡한 조건을 원할 때는 필드 로컬 `$and` / `$or`를 사용하고, [논리 검색(#logical-search)](#logical-search)을 통해 필드 간 조합을 할 수 있습니다:
```js
// "old"로 시작하고 "draft"를 포함하지 않음
fuse.search({ title: { $startsWith: 'old', $not: { $contains: 'draft' } } })
// title이 "old"로 시작하거나 "war"로 끝남
fuse.search({ title: { $or: [{ $startsWith: 'old' }, { $endsWith: 'war' }] } })
```
객체 쿼리는 동등한 문자열 쿼리와 동일한 결과를 반환하며, 엄격하게 검증됩니다. 알 수 없는 연산자, 비어 있거나 문자열이 아닌 값, 잘못된 중첩은 퍼지 검색으로 조용히 대체되는 대신 에러를 발생시킵니다. 전체 빌드에서 사용할 수 있습니다. 전체 문법은 [Extended Search 문서](https://fusejs.io/extended-search#object-syntax)를 참고하세요.
### 토큰 검색 (Token Search)
여러 단어로 이루어진 쿼리를 개별 텀으로 분리하고, 각각을 독립적으로 퍼지 매칭한 뒤, BM25 스타일의 IDF 가중치를 사용하여 결과 순위를 매깁니다. `useTokenSearch: true`로 활성화할 수 있습니다.
```js
const fuse = new Fuse(docs, {
useTokenSearch: true,
keys: ['title', 'body']
})
fuse.search('express midleware rout')
// 오타가 있어도 "Express Middleware"와 "Express Routing Guide"를 찾음
```
- \*\*단어별 오타 허용\*\* — 각 텀이 독립적으로 퍼지 매칭됩니다.
- \*\*관련성 순위 지정\*\* — 흔치 않은 텀에 흔한 텀보다 더 높은 가중치가 부여됩니다.
- \*\*단어 순서 무관\*\* — `"patterns javascript"`와 `"javascript patterns"`는 동일한 결과를 반환합니다.
- \*\*쿼리 길이 제한 없음\*\* — 각 텀이 별도로 검색되므로 긴 다중 단어 쿼리도 자연스럽게 작동합니다.
- \*\*AND 또는 OR\*\* — `tokenMatch: 'all'`은 \_모든\_ 단어와 일치하는 레코드만 반환하며(필터링); 기본값인 `'any'`는 어떤 단어든 일치하는 것을 반환합니다.
- \*\*커스텀 토크나이저\*\* — 내부 구두점이 있는 토큰(`node.js`, `c++`)을 위해 `tokenize`를 통해 정규식이나 함수를 전달하거나, CJK / 태국어 단어 분리를 위해 `Intl.Segmenter`를 사용하세요. 기본적으로 유니코드를 인식합니다.
전체 빌드에서 사용할 수 있습니다. 자세한 내용과 성능 벤치마크는 [Token Search 문서](https://fusejs.io/token-search)를 참고하세요.
### 논리 검색 (Logical Search)
복잡한 쿼리를 위해 `$and`와 `$or`로 조건을 결합합니다. 전체 빌드에서 사용할 수 있습니다.
```js
fuse.search({
$and: [{ title: 'javascript' }, { author: 'crockford' }]
})
```
### 일치 항목 하이라이팅 (Match Highlighting)
UI에서 검색 결과를 하이라이팅하기 위해 문자열 수준의 일치 인덱스를 가져옵니다.
```js
const fuse = new Fuse(list, {
includeMatches: true,
keys: ['title']
})
const result = fuse.search('javscript')
// result[0].matches[0].indices → [[0, 9]]
```
### 단일 문자열 매칭 (Single String Matching)
인덱스를 생성하지 않고 패턴을 단일 문자열과 퍼지 매칭하려면 `Fuse.match()`를 사용하세요. 일회성 비교나 커스텀 필터링에 유용합니다.
```js
const result = Fuse.match('javscript', 'JavaScript: The Good Parts')
// → { isMatch: true, score: 0.04, indices: [[0, 9]] }
```
`Fuse.match()`는 `useTokenSearch`를 지원하지 \*\*않습니다\*\* — 토큰 검색에는 일회성 문자열 비교로는 제공할 수 없는 코퍼스 수준의 통계(`df`, `fieldCount`)가 필요하기 때문입니다. `useTokenSearch: true`를 전달하면 명시적인 에러가 발생합니다. 토큰 검색 동작을 사용하려면 `new Fuse(docs, { useTokenSearch: true }).search(query)`를 사용하세요.
### 동적 컬렉션 (Dynamic Collections)
인덱스를 다시 빌드하지 않고 실시간 인덱스에 문서를 추가하고 제거할 수 있습니다.
```js
fuse.add({ title: 'New Book', author: 'New Author' })
fuse.remove((doc) => doc.title === 'Old Book')
```
## 빌드 (Builds)
Fuse.js는 두 가지 버전으로 제공됩니다:
| Bui

| 빌드 | 포함된 기능 | Min + gzip |
| --------- | ----------------------------------------- | ---------- |
| \*\*Full\*\* | 퍼지(Fuzzy) + 확장(Extended) + 논리(Logical) + 토큰 검색 | ~8.6 kB |
| \*\*Basic\*\* | 퍼지 검색 전용 | ~6.8 kB |

퍼지 검색만 필요하고 번들 크기를 최소화하려면 basic 빌드를 사용하세요.

## 문서
전체 API 레퍼런스, 설정 옵션, 스코어링 이론 및 인터랙티브 데모는 \*\*[fusejs.io](https://fusejs.io)\*\*에서 확인하세요.

## 공식 포트
- \*\*[fuse-swift](https://github.com/krisk/fuse-swift)\*\*: iOS, macOS, tvOS, watchOS, visionOS 및 Linux용 Swift 포트입니다. 바이트 단위로 일치하는 결과와 관용적인 Swift API를 제공하며, 업스트림 릴리스마다 동기화됩니다. 현재 2.0.0-rc.1 버전입니다.

## Fuse.js 후원하기
- [\*\*GitHub\*\*에서 후원자 또는 스폰서 되기](https://github.com/sponsors/krisk)
- [\*\*Patreon\*\*에서 후원자 또는 스폰서 되기](https://patreon.com/fusejs)
- [\*\*PayPal\*\*을 통한 일회성 기부](https://www.paypal.me/kirorisk)

## 개발
설치, 스크립트 및 프로젝트 구조에 대해서는 [DEVELOPERS.md](DEVELOPERS.md)를 참고하세요.

## 기여
이슈 및 풀 리퀘스트 가이드라인은 [CONTRIBUTING.md](CONTRIBUTING.md)를 참고하세요.

Fuse

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README