@ycookiey/yfuzzy 0.1.0 → 0.1.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +164 -144
  2. package/package.json +54 -54
package/README.md CHANGED
@@ -1,144 +1,164 @@
1
- # yfuzzy
2
-
3
- 日本語特化のあいまい検索ライブラリ。ローマ字混じり入力・訓令式/ヘボン式の並列照合・子音（頭文字）マッチ・誤字許容を 1 パッケージに統合。依存ゼロ・ESM・TypeScript 型付き。
4
-
5
- ```
6
- shinjuku / sinjuku / しんじゅく / シンジュク → すべて「シンジュク」にヒット
7
- kmnr → 「カミナリ」にヒット（頭文字）
8
- カナリ → 「カミナリ」にヒット（飛び石）
9
- センタイ → 「センダイ」にヒット（誤字）
10
- ```
11
-
12
- ## インストール
13
-
14
- ```sh
15
- npm install @ycookiey/yfuzzy
16
- ```
17
-
18
- Node 18+ / ESM 専用。
19
-
20
- ## クイックスタート
21
-
22
- ```ts
23
- import { search } from '@ycookiey/yfuzzy';
24
-
25
- const stations = ['トウキョウ', 'シンジュク', 'シブヤ', 'シナガワ'];
26
-
27
- search('sinjuku', stations);
28
- // → [{ item: 'シンジュク', refIndex: 1, score: 1, tier: 1 }]
29
- ```
30
-
31
- オブジェクト配列は `getText` で検索対象文字列を取り出す:
32
-
33
- ```ts
34
- const items = [
35
- { id: 1, yomi: 'トウキョウ' },
36
- { id: 2, yomi: 'シンジュク' },
37
- ];
38
-
39
- search('しんじゅく', items, { getText: (x) => x.yomi });
40
- // → [{ item: { id: 2, yomi: 'シンジュク' }, refIndex: 1, score: 1, tier: 1 }]
41
- ```
42
-
43
- 同じデータを繰り返し検索するなら `createIndex` で事前構築する（単発 `search` と結果は同一）:
44
-
45
- ```ts
46
- import { createIndex } from '@ycookiey/yfuzzy';
47
-
48
- const index = createIndex(stations);
49
- index.search('しぶ'); // → シブヤ
50
- index.search('しな', { limit: 5 });
51
- ```
52
-
53
- ## 漢字について
54
-
55
- yfuzzy は**漢字を読みに変換しない**（リテラル一致のみ）。読みで検索させたい場合は、読み仮名を別途用意して `getText` で返す（読みの付与は利用者責務）。
56
-
57
- ```ts
58
- const items = [{ label: '東京', yomi: 'トウキョウ' }];
59
- search('toukyou', items, { getText: (x) => x.yomi }); // ヒット
60
- search('toukyou', items, { getText: (x) => x.label }); // ヒットしない（漢字はそのまま）
61
- ```
62
-
63
- ## マッチの仕組み（4 層）
64
-
65
- クエリは tier 昇順で評価され、最初に一致した層で確定する。`score` は 0–1（高いほど良い）で、層ごとにレンジが分離する。
66
-
67
- | tier | 層 | 例 | score 帯 |
68
- |---|---|---|---|
69
- | 1 | 完全一致（かな/ローマ字の前方・部分一致） | `シンジュク`→`シンジュク` | (0.75, 1] |
70
- | 2 | 柔軟（subsequence・境界/連続ボーナス・頭文字） | `kmnr`→`カミナリ` | (0.5, 0.75) |
71
- | 3 | 誤字許容（編集距離、中間の置換/挿入/削除/転置） | `センタイ`→`センダイ` | (0.25, 0.5) |
72
- | 4 | 構造類似（Tversky bigram、デフォルト無効） | 大きく崩れた入力 | (0, 0.25] |
73
-
74
- `score` 帯が重ならないため、利用者は閾値だけで「確実なヒット」と「もしかして」を分離できる。
75
-
76
- ## ハイライト（matches）
77
-
78
- `includeMatches: true` で、**元文字列上**の一致区間 `[start, end)`（半開・昇順・マージ済み）を返す（tier 1/2 のみ）。
79
-
80
- ```ts
81
- const r = search('keki', ['ケーキ'], { includeMatches: true });
82
- // r[0].matches → [[0, 3]] ← 長音「ー」を含めて穴なし
83
-
84
- function highlight(text: string, ranges: readonly [number, number][]): string {
85
- let out = '';
86
- let last = 0;
87
- for (const [s, e] of ranges) {
88
- out += text.slice(last, s) + '<mark>' + text.slice(s, e) + '</mark>';
89
- last = e;
90
- }
91
- return out + text.slice(last);
92
- }
93
- ```
94
-
95
- ## API
96
-
97
- ### `search(query, items, options?)`
98
-
99
- 単発検索。`createIndex(items, options).search(query)` と等価。
100
-
101
- ### `createIndex(items, options?) → SearchIndex`
102
-
103
- 事前構築した索引を返す。`index.search(query, searchOptions?)` で per-call の検索オプションを上書きできる。`index.size` で件数。
104
-
105
- ### オプション
106
-
107
- 構築時オプション（`createIndex` / `search` の `options`）:
108
-
109
- | 名前 | 型 | 既定 | 説明 |
110
- |---|---|---|---|
111
- | `getText` | `(item: T) => string` | — | オブジェクト配列で検索対象文字列を取り出す（`T[]` のとき必須） |
112
- | `romaji` | `'hepburn' \| 'kunrei' \| 'both' \| false` | `'both'` | ローマ字照合の方式。`false` でかな空間のみ |
113
- | `separatorExpansion` | `boolean \| string[]` | `false` | 区切り文字を「除去」「境界」両経路で展開（`true` で `['-', ' ', '・', '_']`） |
114
-
115
- 検索時オプション（`index.search` で上書き可）:
116
-
117
- | 名前 | 型 | 既定 | 説明 |
118
- |---|---|---|---|
119
- | `limit` | `number` | 無制限 | 返却件数の上限 |
120
- | `maxTier` | `1 \| 2 \| 3 \| 4` | `3` | 実行する層の上限（`4` で構造類似層を有効化） |
121
- | `minScore` | `number` | `0` | この score 未満を除外 |
122
- | `includeMatches` | `boolean` | `false` | `matches` を含める |
123
-
124
- ### 結果 `SearchResult<T>`
125
-
126
- ```ts
127
- type SearchResult<T> = {
128
- item: T;
129
- refIndex: number; // items 内の位置
130
- score: number; // 0–1、高いほど良い
131
- tier: 1 | 2 | 3 | 4;
132
- matches?: readonly [number, number][]; // includeMatches 時、tier 1/2 のみ
133
- };
134
- ```
135
-
136
- 結果は `score` 降順（同点は `refIndex` 昇順で安定）。
137
-
138
- ## 性能
139
-
140
- 短い文字列の索引向け（数百〜数十万件）。文字集合プレフィルタと tier 打ち切りにより、1 クエリの実測は概ね 千件 ~1.5ms / 1 万件 ~10ms / 10 万件 ~90ms（環境依存）。同条件で fuse.js より高速。`maxTier` を下げる / `romaji: 'kunrei'` で片方式に絞ると更に軽くなる。索引構築は 10 万件で ~0.7s（一度きり）。
141
-
142
- ## ライセンス
143
-
144
- MIT。ローマ字→かな変換に [WanaKana](https://github.com/WaniKani/WanaKana)（MIT）のコードを改変同梱している。詳細は [`THIRD_PARTY_NOTICES.md`](./THIRD_PARTY_NOTICES.md)。
1
+ # yfuzzy
2
+
3
+ [![npm](https://img.shields.io/npm/v/@ycookiey/yfuzzy)](https://www.npmjs.com/package/@ycookiey/yfuzzy)
4
+ [![types](https://img.shields.io/npm/types/@ycookiey/yfuzzy)](https://www.npmjs.com/package/@ycookiey/yfuzzy)
5
+ [![minzipped](https://badgen.net/bundlephobia/minzip/@ycookiey/yfuzzy)](https://bundlephobia.com/package/@ycookiey/yfuzzy)
6
+ [![license](https://img.shields.io/npm/l/@ycookiey/yfuzzy)](./LICENSE)
7
+
8
+ 日本語特化のあいまい検索ライブラリ。ローマ字混じり入力・ヘボン式/訓令式の同時照合・子音だけのマッチ・誤字許容を 1 パッケージに統合。依存ゼロ・ESM・TypeScript 型付き。
9
+
10
+ ```
11
+ shinjuku / sinjuku / しんじゅく / シンジュク → すべて「シンジュク」にヒット
12
+ kmnr → 「カミナリ」にヒット（子音だけ）
13
+ カナリ → 「カミナリ」にヒット（とびとび一致）
14
+ センタイ → 「センダイ」にヒット（誤字）
15
+ ```
16
+
17
+ ## なぜ yfuzzy か
18
+
19
+ 既存のあいまい検索ライブラリ（fuse.js / fuzzysort / MiniSearch / uFuzzy / match-sorter など）はラテン文字圏を前提に設計されており、diacritics（発音区別符号）の除去や Unicode 正規化には対応するものの、**ローマ字とかなの変換や、ヘボン式・訓令式の違いを扱わない**。
20
+
21
+ 日本語 UI では、利用者はローマ字・部分的なかな・子音だけ（上の例）で打つ一方、データはひらがな・カタカナ・漢字（の読み）で保持されている。yfuzzy はこの表記のずれを埋めることに特化している。
22
+
23
+ ## スコープ
24
+
25
+ **向いている**: 日本語の読み（かな）を索引にした短い文字列の検索。駅名・地名・商品名・人名などの読みに対する、逐次検索（type-ahead）やオートコンプリート。
26
+
27
+ **向いていない**:
28
+
29
+ - **漢字をそのまま検索**: yfuzzy は漢字を読みに変換しない（文字どおりの一致のみ）。読みで当てたいなら読み仮名を用意し `getText` で返す（[使い方](#使い方)参照）。
30
+ - **ラテン文字の汎用あいまい検索 / 全文検索**（複数フィールド・トークン化・TF-IDF）: fuse.js / MiniSearch 等が成熟している。用途で使い分けるとよい。
31
+
32
+ ## 類似パッケージとの比較
33
+
34
+ | 機能 | yfuzzy | [fuse.js](https://www.fusejs.io/) | [fuzzysort](https://github.com/farzher/fuzzysort) | [MiniSearch](https://github.com/lucaong/minisearch) | [uFuzzy](https://github.com/leeoniya/uFuzzy) | [match-sorter](https://github.com/kentcdodds/match-sorter) |
35
+ |---|:--:|:--:|:--:|:--:|:--:|:--:|
36
+ | 日本語入力（ローマ字↔かな・ヘボン/訓令・かな正規化） | ✅ | ➖ | ➖ | ➖ | ➖ | ➖ |
37
+ | 子音だけのマッチ | ✅ | ➖ | 🔸 | ➖ | 🔸 | 🔸 |
38
+ | とびとび一致（subsequence） | ✅ | 🔸 | ✅ | ➖ | ✅ | 🔸 |
39
+ | 誤字許容（編集距離） | ✅ | ✅ | ➖ | ✅ | 🔸 | ➖ |
40
+ | ハイライト位置の返却 | ✅ | ✅ | ✅ | 🔸 | ✅ | ➖ |
41
+ | 索引の事前構築 | ✅ | ✅ | ✅ | ✅ | ➖ | ➖ |
42
+ | 全文検索（複数フィールド/トークン） | ➖ | ✅ | 🔸 | ✅ | ➖ | 🔸 |
43
+ | ラテン文字の diacritics 除去 | ➖ | ✅ | ➖ | 🔸 | ✅ | ✅ |
44
+ | 依存ゼロ | ✅ | ✅ | ✅ | ✅ | ✅ | ➖ |
45
+
46
+ 凡例: ✅ 組み込み / 🔸 部分的・間接的（または要カスタム） / ➖ なし。各ライブラリの調査時点の既定挙動を基準とした。多くはカスタム関数で拡張できる。本表は「日本語入力対応＋主要なあいまいマッチ機能」に観点を絞ったもの。
47
+
48
+ ## インストール
49
+
50
+ ```sh
51
+ npm install @ycookiey/yfuzzy
52
+ ```
53
+
54
+ Node 18+ / ESM 専用。
55
+
56
+ ## 使い方
57
+
58
+ ### 文字列配列
59
+
60
+ ```ts
61
+ import { search } from '@ycookiey/yfuzzy';
62
+
63
+ const stations = ['トウキョウ', 'シンジュク', 'シブヤ', 'シナガワ'];
64
+
65
+ search('sinjuku', stations);
66
+ // → [{ item: 'シンジュク', refIndex: 1, score: 1, tier: 1 }]
67
+ ```
68
+
69
+ ### オブジェクト配列（getText）
70
+
71
+ `getText` で検索対象の文字列を取り出す。漢字を読みで当てたい場合も、読み仮名を返せばよい（読みは利用者側で用意する）。
72
+
73
+ ```ts
74
+ const items = [
75
+ { label: '東京', yomi: 'トウキョウ' },
76
+ { label: '新宿', yomi: 'シンジュク' },
77
+ ];
78
+
79
+ search('しんじゅく', items, { getText: (x) => x.yomi });
80
+ // → [{ item: { label: '新宿', … }, refIndex: 1, score: 1, tier: 1 }]
81
+ ```
82
+
83
+ ### 索引の再利用（createIndex）
84
+
85
+ 同じデータを繰り返し検索するなら事前構築する。単発 `search` と結果は同一。
86
+
87
+ ```ts
88
+ import { createIndex } from '@ycookiey/yfuzzy';
89
+
90
+ const index = createIndex(stations);
91
+ index.search('しぶ'); // → 先頭は シブヤ（短い語なので tier3 候補も続く）
92
+ index.search('しな', { limit: 5 }); // 呼び出しごとに検索オプションを上書き
93
+ ```
94
+
95
+ ### ハイライト（includeMatches）
96
+
97
+ `includeMatches: true` で、**元文字列上**の一致区間 `[start, end)`（半開・昇順、隣接や重複は統合済み）を返す（後述の tier 1・2 でのみ）。各区間を `text.slice` で切り出して囲めばハイライトになる。
98
+
99
+ ```ts
100
+ const r = search('keki', ['ケーキ'], { includeMatches: true });
101
+ // r[0].matches → [[0, 3]] ← 長音「ー」も含めて隙間なく連続
102
+ ```
103
+
104
+ ## マッチの仕組み
105
+
106
+ クエリは tier 1 から順に評価され、最初に一致した tier で確定する（既定は tier 1〜3。`maxTier: 4` で tier 4 も有効化）。`score` は 0〜1 で、上の tier ほど高い。
107
+
108
+ | tier | 内容 | 例 | score の範囲（目安） |
109
+ |---|---|---|---|
110
+ | 1 | 直接一致（かな/ローマ字が前方・部分一致） | `シンジュク`→`シンジュク` | 0.75〜1.0 |
111
+ | 2 | 柔軟一致（とびとびでも可。語頭・連続を優遇、子音だけの入力も可） | `kmnr`→`カミナリ` | 0.5〜0.75 |
112
+ | 3 | 誤字許容（編集距離、中間の置換/挿入/削除/入れ替え） | `センタイ`→`センダイ` | 0.25〜0.5 |
113
+ | 4 | 構造類似（2 文字単位の重なりによる類似〔Tversky 係数〕、既定で無効） | 大きく崩れた入力 | 0〜0.25 |
114
+
115
+ 各 tier は幅およそ 0.25 の帯に収まり、スコアが tier 間の境界（0.25 / 0.5 / 0.75）ちょうどになることはない。そのため閾値ひとつで「確実なヒット」と「あいまいな候補（『もしかして』表示向け）」を分離できる。結果は `score` 降順（同点は `refIndex` 昇順で安定）。
116
+
117
+ ## API
118
+
119
+ ### `search(query, items, options?)`
120
+
121
+ 単発検索。`createIndex(items, options).search(query)` と等価。
122
+
123
+ ### `createIndex(items, options?) → SearchIndex`
124
+
125
+ 事前構築した索引を返す。`index.search(query, searchOptions?)` で呼び出しごとに検索オプションを上書きできる。`index.size` で件数。
126
+
127
+ ### オプション
128
+
129
+ 構築時オプション（`createIndex` / `search` の `options`）:
130
+
131
+ | 名前 | 型 | 既定 | 説明 |
132
+ |---|---|---|---|
133
+ | `getText` | `(item: T) => string` | なし | オブジェクト配列で検索対象文字列を取り出す（`T[]` のとき必須） |
134
+ | `romaji` | `'hepburn' \| 'kunrei' \| 'both' \| false` | `'both'` | ローマ字照合の方式。`false` でローマ字照合せず、かなのみで照合 |
135
+ | `separatorExpansion` | `boolean \| string[]` | `false` | 区切り文字を、取り除いた形と区切りとして扱う形の両方で照合（`true` で `['-', ' ', '・', '_']`） |
136
+
137
+ 検索時オプション（`index.search` で上書き可）:
138
+
139
+ | 名前 | 型 | 既定 | 説明 |
140
+ |---|---|---|---|
141
+ | `limit` | `number` | 無制限 | 返却件数の上限 |
142
+ | `maxTier` | `1 \| 2 \| 3 \| 4` | `3` | 実行する tier の上限（`4` で構造類似の tier を有効化） |
143
+ | `minScore` | `number` | `0` | この score 未満を除外 |
144
+ | `includeMatches` | `boolean` | `false` | `matches` を含める |
145
+
146
+ ### 結果 `SearchResult<T>`
147
+
148
+ ```ts
149
+ type SearchResult<T> = {
150
+ item: T;
151
+ refIndex: number; // items 内の位置
152
+ score: number; // 0〜1、高いほど良い
153
+ tier: 1 | 2 | 3 | 4;
154
+ matches?: readonly [number, number][]; // includeMatches 時、tier 1/2 のみ
155
+ };
156
+ ```
157
+
158
+ ## 性能
159
+
160
+ 短い文字列の索引向け（数百〜数十万件）。内部の前段フィルタと早期打ち切りにより、1 クエリの実測値は千件で約 1.5ms、1 万件で約 10ms、10 万件で約 90ms（環境依存）。同条件で fuse.js より高速。`maxTier` を下げる、または `romaji` を一方の方式だけに絞ると更に軽くなる。索引構築は 10 万件で約 0.7 秒（一度きり）。
161
+
162
+ ## ライセンス
163
+
164
+ MIT。ローマ字→かな変換に [WanaKana](https://github.com/WaniKani/WanaKana)（MIT）のコードを改変のうえ同梱している。詳細は [`THIRD_PARTY_NOTICES.md`](./THIRD_PARTY_NOTICES.md)。
package/package.json CHANGED
@@ -1,54 +1,54 @@
1
- {
2
- "name": "@ycookiey/yfuzzy",
3
- "version": "0.1.0",
4
- "description": "Japanese-aware fuzzy search library",
5
- "license": "MIT",
6
- "publishConfig": {
7
- "access": "public"
8
- },
9
- "author": "ycookiey",
10
- "keywords": [
11
- "fuzzy",
12
- "fuzzy-search",
13
- "search",
14
- "japanese",
15
- "kana",
16
- "romaji",
17
- "katakana",
18
- "hiragana",
19
- "typeahead",
20
- "autocomplete"
21
- ],
22
- "type": "module",
23
- "main": "./dist/index.js",
24
- "types": "./dist/index.d.ts",
25
- "exports": {
26
- ".": {
27
- "types": "./dist/index.d.ts",
28
- "import": "./dist/index.js"
29
- }
30
- },
31
- "files": [
32
- "dist",
33
- "README.md",
34
- "LICENSE",
35
- "THIRD_PARTY_NOTICES.md"
36
- ],
37
- "scripts": {
38
- "build": "tsc -p tsconfig.build.json",
39
- "typecheck": "tsc -p tsconfig.json",
40
- "test": "vitest run",
41
- "test:watch": "vitest",
42
- "bench": "npm run build && node bench/run.js",
43
- "prepublishOnly": "npm run build"
44
- },
45
- "devDependencies": {
46
- "fuse.js": "^7.4.2",
47
- "fuzzysort": "^3.1.0",
48
- "typescript": "^6.0.3",
49
- "vitest": "^4.1.8"
50
- },
51
- "engines": {
52
- "node": ">=18"
53
- }
54
- }
1
+ {
2
+ "name": "@ycookiey/yfuzzy",
3
+ "version": "0.1.2",
4
+ "description": "Japanese-aware fuzzy search library",
5
+ "license": "MIT",
6
+ "publishConfig": {
7
+ "access": "public"
8
+ },
9
+ "author": "ycookiey",
10
+ "keywords": [
11
+ "fuzzy",
12
+ "fuzzy-search",
13
+ "search",
14
+ "japanese",
15
+ "kana",
16
+ "romaji",
17
+ "katakana",
18
+ "hiragana",
19
+ "typeahead",
20
+ "autocomplete"
21
+ ],
22
+ "type": "module",
23
+ "main": "./dist/index.js",
24
+ "types": "./dist/index.d.ts",
25
+ "exports": {
26
+ ".": {
27
+ "types": "./dist/index.d.ts",
28
+ "import": "./dist/index.js"
29
+ }
30
+ },
31
+ "files": [
32
+ "dist",
33
+ "README.md",
34
+ "LICENSE",
35
+ "THIRD_PARTY_NOTICES.md"
36
+ ],
37
+ "scripts": {
38
+ "build": "tsc -p tsconfig.build.json",
39
+ "typecheck": "tsc -p tsconfig.json",
40
+ "test": "vitest run",
41
+ "test:watch": "vitest",
42
+ "bench": "npm run build && node bench/run.js",
43
+ "prepublishOnly": "npm run build"
44
+ },
45
+ "devDependencies": {
46
+ "fuse.js": "^7.4.2",
47
+ "fuzzysort": "^3.1.0",
48
+ "typescript": "^6.0.3",
49
+ "vitest": "^4.1.8"
50
+ },
51
+ "engines": {
52
+ "node": ">=18"
53
+ }
54
+ }