quickmatch-js 0.2.1 → 0.3.1

package/README.md

@@ -18,5 +18,9 @@ A high-performance string matching library optimized for interactive search expe
 ## Installation
 
 ```bash
+# rust
 cargo add quickmatch
+
+# js
+npm install quickmatch-js
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "quickmatch-js",
-  "version": "0.2.1",
+  "version": "0.3.1",
   "description": "Lightning-fast fuzzy string matching",
   "type": "module",
   "main": "src/index.js",

package/src/index.js

@@ -1,33 +1,64 @@
-const DEFAULT_SEPARATORS = '_- ';
+const DEFAULT_SEPARATORS = "_- ";
 const DEFAULT_TRIGRAM_BUDGET = 6;
 const DEFAULT_LIMIT = 100;
 
+/**
+ * Configuration for QuickMatch.
+ */
 export class QuickMatchConfig {
+  /** @type {string} Characters used to split items into words */
   separators = DEFAULT_SEPARATORS;
+
+  /** @type {number} Maximum number of results to return */
   limit = DEFAULT_LIMIT;
+
+  /** @type {number} Number of trigram lookups for fuzzy matching (0-20) */
   trigramBudget = DEFAULT_TRIGRAM_BUDGET;
 
+  /**
+   * Set maximum number of results.
+   * @param {number} n
+   */
   withLimit(n) {
     this.limit = Math.max(1, n);
     return this;
   }
 
+  /**
+   * Set trigram budget for fuzzy matching.
+   * Higher values find more typos but cost more.
+   * @param {number} n - Budget (0-20, default: 6)
+   */
   withTrigramBudget(n) {
     this.trigramBudget = Math.max(0, Math.min(20, n));
     return this;
   }
 
+  /**
+   * Set word separator characters.
+   * @param {string} s - Separator characters (default: '_- ')
+   */
   withSeparators(s) {
     this.separators = s;
     return this;
   }
 }
 
+/**
+ * Fast fuzzy string matcher using word and trigram indexing.
+ */
 export class QuickMatch {
+  /**
+   * Create a new matcher.
+   * @param {string[]} items - Items to index (should be lowercase)
+   * @param {QuickMatchConfig} [config] - Optional configuration
+   */
   constructor(items, config = new QuickMatchConfig()) {
     this.config = config;
     this.items = items;
+    /** @type {Map<string, number[]>} */
     this.wordIndex = new Map();
+    /** @type {Map<string, number[]>} */
     this.trigramIndex = new Map();
 
     let maxWordLength = 0;
@@ -76,10 +107,19 @@ export class QuickMatch {
     this.maxWordCount = maxWordCount + 2;
   }
 
+  /**
+   * Find matching items. Returns items sorted by relevance.
+   * @param {string} query - Search query
+   */
   matches(query) {
     return this.matchesWith(query, this.config);
   }
 
+  /**
+   * Find matching items with custom config. Returns items sorted by relevance.
+   * @param {string} query - Search query
+   * @param {QuickMatchConfig} config - Configuration to use
+   */
   matchesWith(query, config) {
     const { limit, trigramBudget, separators } = config;
 
@@ -89,7 +129,11 @@ export class QuickMatch {
       return [];
     }
 
-    const queryWords = parseWords(normalizedQuery, separators, this.maxWordLength);
+    const queryWords = parseWords(
+      normalizedQuery,
+      separators,
+      this.maxWordLength,
+    );
 
     if (!queryWords.length || queryWords.length > this.maxWordCount) {
       return [];
@@ -127,7 +171,7 @@ export class QuickMatch {
 
     const minItemLength = Math.max(0, normalizedQuery.length - 3);
 
-    const trigramCount = this.scoreByTrigrams({
+    const hitCount = this.scoreByTrigrams({
       unknownWords,
       budget: trigramBudget,
       scores,
@@ -135,25 +179,35 @@ export class QuickMatch {
       minItemLength,
     });
 
-    const minScoreToInclude = Math.max(1, Math.ceil(trigramCount / 2));
+    const minScoreToInclude = Math.max(1, Math.ceil(hitCount / 2));
 
     return this.rankedResults(scores, minScoreToInclude, limit);
   }
 
-  scoreByTrigrams({ unknownWords, budget, scores, hasExactMatches, minItemLength }) {
+  /**
+   * @private
+   * @param {{unknownWords: string[], budget: number, scores: Map<number, number>, hasExactMatches: boolean, minItemLength: number}} args
+   */
+  scoreByTrigrams({
+    unknownWords,
+    budget,
+    scores,
+    hasExactMatches,
+    minItemLength,
+  }) {
     const visitedTrigrams = new Set();
     let budgetRemaining = budget;
     let hitCount = 0;
 
-    outer:
-    for (let round = 0; round < budget; round++) {
+    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];
+        const trigram =
+          word[position] + word[position + 1] + word[position + 2];
 
         if (visitedTrigrams.has(trigram)) continue;
         visitedTrigrams.add(trigram);
@@ -181,13 +235,24 @@ export class QuickMatch {
     return hitCount;
   }
 
+  /**
+   * @private
+   * @param {number[]} indices
+   * @param {number} limit
+   */
   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]);
+    return indices.map((i) => items[i]);
   }
 
+  /**
+   * @private
+   * @param {Map<number, number>} scores
+   * @param {number} minScore
+   * @param {number} limit
+   */
   rankedResults(scores, minScore, limit) {
     const { items } = this;
     const results = [];
@@ -205,12 +270,13 @@ export class QuickMatch {
 
     if (results.length > limit) results.length = limit;
 
-    return results.map(r => items[r.index]);
+    return results.map((r) => items[r.index]);
   }
 }
 
+/** @param {string} query */
 function normalizeQuery(query) {
-  let result = '';
+  let result = "";
   let start = 0;
   let end = query.length;
 
@@ -220,13 +286,20 @@ function normalizeQuery(query) {
   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];
+    result +=
+      code >= 65 && code <= 90 ? String.fromCharCode(code + 32) : query[i];
   }
 
   return result;
 }
 
+/**
+ * @param {string} text
+ * @param {string} separators
+ * @param {number} maxLength
+ */
 function parseWords(text, separators, maxLength) {
+  /** @type {string[]} */
   const words = [];
   let start = 0;
 
@@ -247,6 +320,11 @@ function parseWords(text, separators, maxLength) {
   return words;
 }
 
+/**
+ * @param {Map<string, number[]>} index
+ * @param {string} key
+ * @param {number} value
+ */
 function addToIndex(index, key, value) {
   const existing = index.get(key);
   if (existing) {
@@ -256,6 +334,11 @@ function addToIndex(index, key, value) {
   }
 }
 
+/**
+ * @param {Map<string, number[]>} index
+ * @param {string} word
+ * @param {number} itemIndex
+ */
 function addTrigramsToIndex(index, word, itemIndex) {
   if (word.length < 3) return;
 
@@ -271,6 +354,7 @@ function addTrigramsToIndex(index, word, itemIndex) {
   }
 }
 
+/** @param {number[][]} arrays */
 function intersectAll(arrays) {
   if (!arrays.length) return [];
 
@@ -298,6 +382,10 @@ function intersectAll(arrays) {
   return result;
 }
 
+/**
+ * @param {number[]} sortedArray
+ * @param {number} value
+ */
 function binarySearch(sortedArray, value) {
   let low = 0;
   let high = sortedArray.length - 1;
@@ -314,6 +402,10 @@ function binarySearch(sortedArray, value) {
   return false;
 }
 
+/**
+ * @param {number} wordLength
+ * @param {number} round
+ */
 function pickTrigramPosition(wordLength, round) {
   const maxPosition = wordLength - 3;
   if (maxPosition < 0) return -1;
@@ -325,7 +417,7 @@ function pickTrigramPosition(wordLength, round) {
 
   const middle = maxPosition >> 1;
   const offset = (round - 2) >> 1;
-  const position = (round & 1) ? Math.max(0, middle - offset) : middle + offset;
+  const position = round & 1 ? Math.max(0, middle - offset) : middle + offset;
 
   if (position === 0 || position >= maxPosition || position === middle) {
     return -1;