리뷰에서 나온 API 표면 개선점 모음. TODO.md의 기존 항목(grapheme 좌표계 은닉, 네이밍 정리)과 별개인 것만.
1. matchBest 4번째 positional boolean
matchBest(query, target, scoring?, strict?) — 호출부에서 matchBest(q, t, undefined, true)가 됩니다. matchBest(q, t, { scoring?, strict? }) 옵션 객체로 전환 (기존 시그니처는 deprecated 오버로드로 유지 가능).
2. 빈 쿼리 + limit 조합의 비결정 동작
빈 쿼리는 전 아이템을 score 0으로 반환하는데, limit > 0이면 min-heap 특성상 임의의 N개가 나옵니다. 팔레트 UX상 "빈 쿼리 = 원래 순서 상위 N"이 자연스러움. 빈 쿼리를 특수 처리(엔트리 순서 유지 + limit slice)하는 게 저렴한 수정.
3. 동점 시 tie-break 비결정성
heap 경로(limit > 0)에서 score 동률이면 limit 경계의 아이템이 스캔 순서/heap 내부 상태에 따라 달라질 수 있음. 엔트리 인덱스를 2차 정렬 키로 넣어 결정성 보장 권장. (no-limit 경로는 Array.sort 안정성으로 이미 입력 순서 유지.)
4. SearchResult.score? — 실제로는 항상 세팅됨
createSearcher 양쪽 경로 모두 score를 세팅하므로 optional일 이유가 없음. required로 바꾸면 caller의 ?? 0 노이즈 제거.
5. multi-key 검색 (확장성 핵심)
실전 팔레트 아이템은 label + aliases + keywords인데 현재 key는 단일 문자열. keys: (item) => string[]을 받아 아이템당 Target 여러 개 중 best score를 취하는 형태 제안. 기존 target 옵션과 대칭으로 targets도 고려. 동의어/한자 독음/영문 별칭 확장이 전부 caller 레벨에서 풀리게 하는 지렛대.
6. 소소
warnUnknownKeys 주석에 "첫 호출 시 한 번만 검사 후 캐시"라고 돼 있으나 캐싱 미구현 (매 search마다 실행) — 주석과 코드 중 하나를 맞추기defaultScore가 result.score(DP 결과)를 무시 — DP score 도입 이전 유물. deprecate 또는 "메타데이터 전용 간이 score"임을 JSDoc에 명시Searcher에 size/clear 부재, remove(predicate)만 있고 id 기반 제거 없음
리뷰에서 나온 API 표면 개선점 모음. TODO.md의 기존 항목(grapheme 좌표계 은닉, 네이밍 정리)과 별개인 것만.
1.
matchBest4번째 positional booleanmatchBest(query, target, scoring?, strict?)— 호출부에서matchBest(q, t, undefined, true)가 됩니다.matchBest(q, t, { scoring?, strict? })옵션 객체로 전환 (기존 시그니처는 deprecated 오버로드로 유지 가능).2. 빈 쿼리 + limit 조합의 비결정 동작
빈 쿼리는 전 아이템을 score 0으로 반환하는데,
limit > 0이면 min-heap 특성상 임의의 N개가 나옵니다. 팔레트 UX상 "빈 쿼리 = 원래 순서 상위 N"이 자연스러움. 빈 쿼리를 특수 처리(엔트리 순서 유지 + limit slice)하는 게 저렴한 수정.3. 동점 시 tie-break 비결정성
heap 경로(
limit > 0)에서 score 동률이면 limit 경계의 아이템이 스캔 순서/heap 내부 상태에 따라 달라질 수 있음. 엔트리 인덱스를 2차 정렬 키로 넣어 결정성 보장 권장. (no-limit 경로는Array.sort안정성으로 이미 입력 순서 유지.)4.
SearchResult.score?— 실제로는 항상 세팅됨createSearcher양쪽 경로 모두 score를 세팅하므로 optional일 이유가 없음. required로 바꾸면 caller의?? 0노이즈 제거.5. multi-key 검색 (확장성 핵심)
실전 팔레트 아이템은
label + aliases + keywords인데 현재key는 단일 문자열.keys: (item) => string[]을 받아 아이템당 Target 여러 개 중 best score를 취하는 형태 제안. 기존target옵션과 대칭으로targets도 고려. 동의어/한자 독음/영문 별칭 확장이 전부 caller 레벨에서 풀리게 하는 지렛대.6. 소소
warnUnknownKeys주석에 "첫 호출 시 한 번만 검사 후 캐시"라고 돼 있으나 캐싱 미구현 (매 search마다 실행) — 주석과 코드 중 하나를 맞추기defaultScore가result.score(DP 결과)를 무시 — DP score 도입 이전 유물. deprecate 또는 "메타데이터 전용 간이 score"임을 JSDoc에 명시Searcher에size/clear부재,remove(predicate)만 있고 id 기반 제거 없음