quickmatch-js 0.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 quickmatch
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,22 @@
+# quickmatch
+
+**Lightning-fast fuzzy string matching for Rust.**
+
+A high-performance string matching library optimized for interactive search experiences like autocomplete, command palettes, and search-as-you-type interfaces.
+
+[![Crates.io](https://img.shields.io/crates/v/quickmatch.svg)](https://crates.io/crates/quickmatch)
+[![Documentation](https://docs.rs/quickmatch/badge.svg)](https://docs.rs/quickmatch)
+
+## Features
+
+- **Blazing fast** - Optimized for sub-millisecond search times
+- **Hybrid matching** - Word-level matching with trigram-based fuzzy fallback
+- **Memory efficient** - Zero-copy string storage with pointer-based indexing
+- **Ranked results** - Intelligent scoring based on match quality
+- **Zero external dependencies** - Only uses `rustc-hash` for fast hashing
+
+## Installation
+
+```bash
+cargo add quickmatch
+```

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "quickmatch-js",
+  "version": "0.2.1",
+  "description": "Lightning-fast fuzzy string matching",
+  "type": "module",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "files": [
+    "src"
+  ],
+  "keywords": [
+    "fuzzy",
+    "search",
+    "autocomplete",
+    "trigram",
+    "matching"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nym21/quickmatch.git"
+  }
+}

package/src/config.rs

@@ -0,0 +1,68 @@
+const DEFAULT_SEPARATORS: &[char] = &['_', '-', ' '];
+const DEFAULT_TRIGRAM_BUDGET: usize = 6;
+const DEFAULT_LIMIT: usize = 100;
+
+pub struct QuickMatchConfig {
+    /// Separators used to split words.
+    ///
+    /// Default: ['_', '-', ' ']
+    separators: &'static [char],
+    /// Maximum number of results to return.
+    ///
+    /// Default: 100
+    /// - Min: 1
+    /// - Max: No hard limit (but large values may impact performance)
+    limit: usize,
+    /// Budget of trigrams to process from unknown words.
+    /// This budget is distributed fairly across all unknown words.
+    ///
+    /// Default: 6 (recommended: 3-9)
+    /// - 0: Disable trigram matching (only exact word matches)
+    /// - Low (3-6): Faster, less accurate fuzzy matching
+    /// - High (9-15): Slower, more accurate fuzzy matching
+    /// - Max: 20
+    trigram_budget: usize,
+}
+
+impl Default for QuickMatchConfig {
+    fn default() -> Self {
+        Self {
+            separators: DEFAULT_SEPARATORS,
+            limit: DEFAULT_LIMIT,
+            trigram_budget: DEFAULT_TRIGRAM_BUDGET,
+        }
+    }
+}
+
+impl QuickMatchConfig {
+    pub fn new() -> Self {
+        Self::default()
+    }
+
+    pub fn with_limit(mut self, limit: usize) -> Self {
+        self.limit = limit.max(1);
+        self
+    }
+
+    pub fn with_trigram_budget(mut self, trigram_budget: usize) -> Self {
+        self.trigram_budget = trigram_budget.clamp(0, 20);
+        self
+    }
+
+    pub fn with_separators(mut self, separators: &'static [char]) -> Self {
+        self.separators = separators;
+        self
+    }
+
+    pub fn limit(&self) -> usize {
+        self.limit
+    }
+
+    pub fn trigram_budget(&self) -> usize {
+        self.trigram_budget
+    }
+
+    pub fn separators(&self) -> &[char] {
+        self.separators
+    }
+}

package/src/index.js

@@ -0,0 +1,335 @@
+const DEFAULT_SEPARATORS = '_- ';
+const DEFAULT_TRIGRAM_BUDGET = 6;
+const DEFAULT_LIMIT = 100;
+
+export class QuickMatchConfig {
+  separators = DEFAULT_SEPARATORS;
+  limit = DEFAULT_LIMIT;
+  trigramBudget = DEFAULT_TRIGRAM_BUDGET;
+
+  withLimit(n) {
+    this.limit = Math.max(1, n);
+    return this;
+  }
+
+  withTrigramBudget(n) {
+    this.trigramBudget = Math.max(0, Math.min(20, n));
+    return this;
+  }
+
+  withSeparators(s) {
+    this.separators = s;
+    return this;
+  }
+}
+
+export class QuickMatch {
+  constructor(items, config = new QuickMatchConfig()) {
+    this.config = config;
+    this.items = items;
+    this.wordIndex = new Map();
+    this.trigramIndex = new Map();
+
+    let maxWordLength = 0;
+    let maxQueryLength = 0;
+    let maxWordCount = 0;
+
+    const { separators } = config;
+
+    for (let itemIndex = 0; itemIndex < items.length; itemIndex++) {
+      const item = items[itemIndex];
+
+      if (item.length > maxQueryLength) {
+        maxQueryLength = item.length;
+      }
+
+      let wordCount = 0;
+      let wordStart = 0;
+
+      for (let i = 0; i <= item.length; i++) {
+        const isEndOfWord = i === item.length || separators.includes(item[i]);
+
+        if (isEndOfWord && i > wordStart) {
+          wordCount++;
+          const word = item.slice(wordStart, i);
+
+          if (word.length > maxWordLength) {
+            maxWordLength = word.length;
+          }
+
+          addToIndex(this.wordIndex, word, itemIndex);
+          addTrigramsToIndex(this.trigramIndex, word, itemIndex);
+
+          wordStart = i + 1;
+        } else if (isEndOfWord) {
+          wordStart = i + 1;
+        }
+      }
+
+      if (wordCount > maxWordCount) {
+        maxWordCount = wordCount;
+      }
+    }
+
+    this.maxWordLength = maxWordLength + 4;
+    this.maxQueryLength = maxQueryLength + 6;
+    this.maxWordCount = maxWordCount + 2;
+  }
+
+  matches(query) {
+    return this.matchesWith(query, this.config);
+  }
+
+  matchesWith(query, config) {
+    const { limit, trigramBudget, separators } = config;
+
+    const normalizedQuery = normalizeQuery(query);
+
+    if (!normalizedQuery || normalizedQuery.length > this.maxQueryLength) {
+      return [];
+    }
+
+    const queryWords = parseWords(normalizedQuery, separators, this.maxWordLength);
+
+    if (!queryWords.length || queryWords.length > this.maxWordCount) {
+      return [];
+    }
+
+    const knownWords = [];
+    const unknownWords = [];
+
+    for (const word of queryWords) {
+      const matchingItems = this.wordIndex.get(word);
+
+      if (matchingItems) {
+        knownWords.push(matchingItems);
+      } else if (word.length >= 3 && unknownWords.length < trigramBudget) {
+        unknownWords.push(word);
+      }
+    }
+
+    const exactMatches = intersectAll(knownWords);
+    const hasExactMatches = exactMatches.length > 0;
+    const needsFuzzyMatching = unknownWords.length > 0 && trigramBudget > 0;
+
+    if (!needsFuzzyMatching) {
+      if (!hasExactMatches) return [];
+      return this.sortedByLength(exactMatches, limit);
+    }
+
+    const scores = new Map();
+
+    if (hasExactMatches) {
+      for (const index of exactMatches) {
+        scores.set(index, 1);
+      }
+    }
+
+    const minItemLength = Math.max(0, normalizedQuery.length - 3);
+
+    const trigramCount = this.scoreByTrigrams({
+      unknownWords,
+      budget: trigramBudget,
+      scores,
+      hasExactMatches,
+      minItemLength,
+    });
+
+    const minScoreToInclude = Math.max(1, Math.ceil(trigramCount / 2));
+
+    return this.rankedResults(scores, minScoreToInclude, limit);
+  }
+
+  scoreByTrigrams({ unknownWords, budget, scores, hasExactMatches, minItemLength }) {
+    const visitedTrigrams = new Set();
+    let budgetRemaining = budget;
+    let hitCount = 0;
+
+    outer:
+    for (let round = 0; round < budget; round++) {
+      for (const word of unknownWords) {
+        if (budgetRemaining <= 0) break outer;
+
+        const position = pickTrigramPosition(word.length, round);
+        if (position < 0) continue;
+
+        const trigram = word[position] + word[position + 1] + word[position + 2];
+
+        if (visitedTrigrams.has(trigram)) continue;
+        visitedTrigrams.add(trigram);
+
+        budgetRemaining--;
+
+        const matchingItems = this.trigramIndex.get(trigram);
+        if (!matchingItems) continue;
+
+        hitCount++;
+
+        for (const itemIndex of matchingItems) {
+          if (hasExactMatches) {
+            const currentScore = scores.get(itemIndex);
+            if (currentScore !== undefined) {
+              scores.set(itemIndex, currentScore + 1);
+            }
+          } else if (this.items[itemIndex].length >= minItemLength) {
+            scores.set(itemIndex, (scores.get(itemIndex) || 0) + 1);
+          }
+        }
+      }
+    }
+
+    return hitCount;
+  }
+
+  sortedByLength(indices, limit) {
+    const { items } = this;
+    indices.sort((a, b) => items[a].length - items[b].length);
+    if (indices.length > limit) indices.length = limit;
+    return indices.map(i => items[i]);
+  }
+
+  rankedResults(scores, minScore, limit) {
+    const { items } = this;
+    const results = [];
+
+    for (const [index, score] of scores) {
+      if (score >= minScore) {
+        results.push({ index, score });
+      }
+    }
+
+    results.sort((a, b) => {
+      if (b.score !== a.score) return b.score - a.score;
+      return items[a.index].length - items[b.index].length;
+    });
+
+    if (results.length > limit) results.length = limit;
+
+    return results.map(r => items[r.index]);
+  }
+}
+
+function normalizeQuery(query) {
+  let result = '';
+  let start = 0;
+  let end = query.length;
+
+  while (start < end && query.charCodeAt(start) <= 32) start++;
+  while (end > start && query.charCodeAt(end - 1) <= 32) end--;
+
+  for (let i = start; i < end; i++) {
+    const code = query.charCodeAt(i);
+    if (code >= 128) continue;
+    result += code >= 65 && code <= 90 ? String.fromCharCode(code + 32) : query[i];
+  }
+
+  return result;
+}
+
+function parseWords(text, separators, maxLength) {
+  const words = [];
+  let start = 0;
+
+  for (let i = 0; i <= text.length; i++) {
+    const isEnd = i === text.length || separators.includes(text[i]);
+
+    if (isEnd && i > start) {
+      const word = text.slice(start, i);
+      if (word.length <= maxLength && !words.includes(word)) {
+        words.push(word);
+      }
+      start = i + 1;
+    } else if (isEnd) {
+      start = i + 1;
+    }
+  }
+
+  return words;
+}
+
+function addToIndex(index, key, value) {
+  const existing = index.get(key);
+  if (existing) {
+    existing.push(value);
+  } else {
+    index.set(key, [value]);
+  }
+}
+
+function addTrigramsToIndex(index, word, itemIndex) {
+  if (word.length < 3) return;
+
+  for (let i = 0; i <= word.length - 3; i++) {
+    const trigram = word[i] + word[i + 1] + word[i + 2];
+    const existing = index.get(trigram);
+
+    if (!existing) {
+      index.set(trigram, [itemIndex]);
+    } else if (existing[existing.length - 1] !== itemIndex) {
+      existing.push(itemIndex);
+    }
+  }
+}
+
+function intersectAll(arrays) {
+  if (!arrays.length) return [];
+
+  let smallestIndex = 0;
+  for (let i = 1; i < arrays.length; i++) {
+    if (arrays[i].length < arrays[smallestIndex].length) {
+      smallestIndex = i;
+    }
+  }
+
+  const result = arrays[smallestIndex].slice();
+
+  for (let i = 0; i < arrays.length && result.length > 0; i++) {
+    if (i === smallestIndex) continue;
+
+    let writeIndex = 0;
+    for (let j = 0; j < result.length; j++) {
+      if (binarySearch(arrays[i], result[j])) {
+        result[writeIndex++] = result[j];
+      }
+    }
+    result.length = writeIndex;
+  }
+
+  return result;
+}
+
+function binarySearch(sortedArray, value) {
+  let low = 0;
+  let high = sortedArray.length - 1;
+
+  while (low <= high) {
+    const mid = (low + high) >> 1;
+    const midValue = sortedArray[mid];
+
+    if (midValue === value) return true;
+    if (midValue < value) low = mid + 1;
+    else high = mid - 1;
+  }
+
+  return false;
+}
+
+function pickTrigramPosition(wordLength, round) {
+  const maxPosition = wordLength - 3;
+  if (maxPosition < 0) return -1;
+
+  if (round === 0) return 0;
+  if (round === 1 && maxPosition > 0) return maxPosition;
+  if (round === 2 && maxPosition > 1) return maxPosition >> 1;
+  if (maxPosition <= 2) return -1;
+
+  const middle = maxPosition >> 1;
+  const offset = (round - 2) >> 1;
+  const position = (round & 1) ? Math.max(0, middle - offset) : middle + offset;
+
+  if (position === 0 || position >= maxPosition || position === middle) {
+    return -1;
+  }
+
+  return position;
+}

package/src/lib.rs

@@ -0,0 +1,257 @@
+use std::{marker::PhantomData, ptr};
+
+use rustc_hash::{FxHashMap, FxHashSet};
+
+mod config;
+
+pub use config::*;
+
+pub struct QuickMatch<'a> {
+    config: QuickMatchConfig,
+    max_word_count: usize,
+    max_word_len: usize,
+    max_query_len: usize,
+    word_index: FxHashMap<String, FxHashSet<*const str>>,
+    trigram_index: FxHashMap<[char; 3], FxHashSet<*const str>>,
+    _phantom: PhantomData<&'a str>,
+}
+
+unsafe impl<'a> Send for QuickMatch<'a> {}
+unsafe impl<'a> Sync for QuickMatch<'a> {}
+
+impl<'a> QuickMatch<'a> {
+    /// Expect the items to be pre-formatted (lowercase)
+    pub fn new(items: &[&'a str]) -> Self {
+        Self::new_with(items, QuickMatchConfig::default())
+    }
+
+    /// Expect the items to be pre-formatted (lowercase)
+    pub fn new_with(items: &[&'a str], config: QuickMatchConfig) -> Self {
+        let mut word_index: FxHashMap<String, FxHashSet<*const str>> = FxHashMap::default();
+        let mut trigram_index: FxHashMap<[char; 3], FxHashSet<*const str>> = FxHashMap::default();
+        let mut max_word_len = 0;
+        let mut max_query_len = 0;
+        let mut max_words = 0;
+        let separators = config.separators();
+
+        for &item in items {
+            max_query_len = max_query_len.max(item.len());
+            let mut word_count = 0;
+            for word in item.split(separators) {
+                word_count += 1;
+                if word.is_empty() {
+                    continue;
+                }
+
+                max_word_len = max_word_len.max(item.len());
+
+                word_index.entry(word.to_string()).or_default().insert(item);
+
+                if word.len() >= 3 {
+                    let chars = word.chars().collect::<Vec<_>>();
+                    for window in chars.windows(3) {
+                        trigram_index
+                            .entry(unsafe { ptr::read(window.as_ptr() as *const [char; 3]) })
+                            .or_default()
+                            .insert(item);
+                    }
+                }
+            }
+            max_words = max_words.max(word_count);
+        }
+
+        Self {
+            max_query_len: max_query_len + 6,
+            max_word_len: max_word_len + 4,
+            max_word_count: max_word_len + 2,
+            word_index,
+            trigram_index,
+            config,
+            _phantom: PhantomData,
+        }
+    }
+
+    ///
+    /// `limit`: max number of returned matches
+    ///
+    /// `max_trigrams`: max number of processed trigrams in unknown words (0-10 recommended)
+    ///
+    pub fn matches(&self, query: &str) -> Vec<&'a str> {
+        self.matches_with(query, &self.config)
+    }
+
+    ///
+    /// `limit`: max number of returned matches
+    ///
+    /// `max_trigrams`: max number of processed trigrams in unknown words (0-10 recommended)
+    ///
+    pub fn matches_with(&self, query: &str, config: &QuickMatchConfig) -> Vec<&'a str> {
+        let limit = config.limit();
+        let trigram_budget = config.trigram_budget();
+        let query_len = query.len();
+
+        if query.is_empty() || query_len > self.max_query_len {
+            return vec![];
+        }
+
+        let query = query
+            .trim()
+            .chars()
+            .filter(|c| c.is_ascii())
+            .collect::<String>()
+            .to_ascii_lowercase();
+
+        let words = query
+            .split(config.separators())
+            .filter(|w| !w.is_empty() && w.len() <= self.max_word_len)
+            .collect::<FxHashSet<_>>();
+
+        if words.is_empty() || words.len() > self.max_word_count {
+            return vec![];
+        }
+
+        let min_len = query_len.saturating_sub(3);
+
+        let mut pool: Option<FxHashSet<*const str>> = None;
+        let mut unknown_words = Vec::new();
+
+        let mut words_to_intersect = vec![];
+        for word in words {
+            if let Some(items) = self.word_index.get(word) {
+                words_to_intersect.push(items)
+            } else if word.len() >= 3 && unknown_words.len() < trigram_budget {
+                unknown_words.push(word.chars().collect::<Vec<_>>())
+            }
+        }
+
+        if !words_to_intersect.is_empty() {
+            words_to_intersect.sort_unstable_by_key(|set| -(set.len() as i64));
+
+            let mut intersect = words_to_intersect.pop().cloned().unwrap();
+
+            for other_set in words_to_intersect.iter().rev() {
+                intersect.retain(|ptr| other_set.contains(ptr));
+                if intersect.is_empty() {
+                    break;
+                }
+            }
+
+            pool = Some(intersect);
+        }
+        let some_pool = pool.is_some();
+
+        if unknown_words.is_empty() || trigram_budget == 0 {
+            let mut results: Vec<_> = pool
+                .unwrap_or_default()
+                .into_iter()
+                .map(|item| unsafe { &*item as &str })
+                .collect();
+
+            if results.len() > limit {
+                results.select_nth_unstable_by_key(limit, |item| item.len());
+                results.truncate(limit);
+            }
+
+            results.sort_unstable_by_key(|item| item.len());
+
+            return results;
+        }
+
+        let mut scores: FxHashMap<*const str, usize> = FxHashMap::default();
+        scores.reserve(256);
+        if let Some(pool) = &pool {
+            for &item in pool {
+                scores.insert(item, 1);
+            }
+        }
+
+        let mut budget = trigram_budget;
+        let mut hit_count: usize = 0;
+        let mut visited: FxHashSet<[char; 3]> = FxHashSet::default();
+
+        'outer: for round in 0..trigram_budget {
+            for chars in &unknown_words {
+                if budget == 0 {
+                    break 'outer;
+                }
+
+                let len = chars.len();
+                let max_pos = len - 3;
+
+                let pos = if round == 0 {
+                    0
+                } else if round == 1 && max_pos > 0 {
+                    max_pos
+                } else if round == 2 && max_pos > 1 {
+                    max_pos / 2
+                } else if max_pos > 2 {
+                    let mid = max_pos / 2;
+                    let offset = (round - 2) >> 1;
+                    let p = if (round & 1) == 1 {
+                        mid.saturating_sub(offset)
+                    } else {
+                        mid + offset
+                    };
+
+                    if p == 0 || p >= max_pos || p == mid {
+                        continue;
+                    }
+                    p
+                } else {
+                    continue;
+                };
+
+                let trigram = [chars[pos], chars[pos + 1], chars[pos + 2]];
+
+                if !visited.insert(trigram) {
+                    continue;
+                }
+
+                budget -= 1;
+
+                let Some(items) = self.trigram_index.get(&trigram) else {
+                    continue;
+                };
+
+                hit_count += 1;
+
+                if some_pool {
+                    for &item in items {
+                        if let Some(score) = scores.get_mut(&item) {
+                            *score += 1;
+                        }
+                    }
+                } else {
+                    for &item in items {
+                        let len = unsafe { &*item }.len();
+                        if len >= min_len {
+                            *scores.entry(item).or_default() += 1;
+                        }
+                    }
+                }
+            }
+        }
+
+        let min_score = hit_count.div_ceil(2).max(1);
+        let mut results: Vec<_> = scores
+            .into_iter()
+            .filter(|(_, s)| *s >= min_score)
+            .map(|(item, score)| (unsafe { &*item as &str }, score))
+            .collect();
+
+        if results.len() > limit {
+            results.select_nth_unstable_by(limit, |a, b| {
+                b.1.cmp(&a.1).then_with(|| a.0.len().cmp(&b.0.len()))
+            });
+            results.truncate(limit);
+        }
+
+        results.sort_unstable_by(|a, b| b.1.cmp(&a.1).then_with(|| a.0.len().cmp(&b.0.len())));
+
+        results
+            .into_iter()
+            .take(limit)
+            .map(|(item, _)| item)
+            .collect()
+    }
+}