feat: support fuzzy matching, closes #504 (#505)

weareoutman · web-flow · commit c8310f39c05f · 2025-03-12T10:17:17.000+08:00
diff --git a/README.md b/README.md
@@ -42,7 +42,7 @@ yarn add @easyops-cn/docusaurus-search-local
 
 Add `@easyops-cn/docusaurus-search-local` into your docusaurus themes.
 
-````js
+```js
 // In your `docusaurus.config.js`:
 module.exports = {
   // ... Your other configurations.
@@ -65,7 +65,7 @@ module.exports = {
     ],
   ],
 };
-````
+```
 
 > Notice: We present this as a theme instead of plugin now, see [this comment](https://github.com/facebook/docusaurus/issues/6488#issuecomment-1024124096).
 
@@ -100,6 +100,7 @@ module.exports = {
 | hideSearchBarWithNoSearchContext  | boolean                                                                     | `false`   | Whether to hide the search bar when no search context was matched. By default, if `searchContextByPaths` is set, pages which are not matched with it will be considered as with a search context of ROOT. By setting `hideSearchBarWithNoSearchContext: true`, these pages will be considered as with NO search context, and the search bar will be hidden. |
 | useAllContextsWithNoSearchContext | boolean                                                                     | `false`   | Whether to show results from all the contexts if no context is provided. This option should not be used with `hideSearchBarWithNoSearchContext: true` as this would show results when there is no search context. This will duplicate indexes and might have a performance cost depending on the index sizes.                                               |
 | `forceIgnoreNoIndex`              | boolean                                                                     | `false`   | Force enable search index even if `noIndex: true` is set, this also affects unlisted articles.                                                                                                                                                                                                                                                              |
+| `fuzzyMatchingDistance`           | number                                                                      | `1`       | Set the edit distance for fuzzy matching during searches.                                                                                                                                                                                                                                                                                                   |
 
 ### I18N
 
@@ -136,22 +137,22 @@ Note that `*_plural` can be omitted if it is the same as singular.
 
 This theme is shipped with polished styles just like the Algolia Search on the Docusaurus v2 website. Feel free to override these css custom properties (css variables) below.
 
-| Var                              | Default (light)                                                        | Default (dark)                                          |
-| -------------------------------- | ---------------------------------------------------------------------- | ------------------------------------------------------- |
-| --search-local-modal-background  | `#f5f6f7`                                                              | `var(--ifm-background-color)`                           |
-| --search-local-modal-shadow      | `inset 1px 1px 0 0 hsla(0, 0%, 100%, 0.5),`<br />`0 3px 8px 0 #555a64` | `inset 1px 1px 0 0 #2c2e40,`<br />`0 3px 8px 0 #000309` |
-| --search-local-modal-width       | `560px`                                                                | -                                                       |
-| --search-local-modal-width-sm    | `340px`                                                                | -                                                       |
-| --search-local-spacing           | `12px`                                                                 | -                                                       |
-| --search-local-hit-background    | `#fff`                                                                 | `var(--ifm-color-emphasis-100)`                         |
-| --search-local-hit-shadow        | `0 1px 3px 0 #d4d9e1`                                                  | `none`                                                  |
-| --search-local-hit-color         | `#444950`                                                              | `var(--ifm-font-color-base)`                            |
-| --search-local-hit-height        | `56px`                                                                 | -                                                       |
-| --search-local-highlight-color   | `var(--ifm-color-primary)`                                             | -                                                       |
-| --search-local-muted-color       | `#969faf`                                                              | `var(--ifm-color-secondary-darkest)`                    |
-| --search-local-icon-stroke-width | `1.4`                                                                  | -                                                       |
-| --search-local-hit-active-color  | `var(--ifm-color-white)`                                               | -                                                       |
-| --search-local-input-active-border-color  | `var(--ifm-color-primary)`   | -              | 
+| Var                                      | Default (light)                                                        | Default (dark)                                          |
+| ---------------------------------------- | ---------------------------------------------------------------------- | ------------------------------------------------------- |
+| --search-local-modal-background          | `#f5f6f7`                                                              | `var(--ifm-background-color)`                           |
+| --search-local-modal-shadow              | `inset 1px 1px 0 0 hsla(0, 0%, 100%, 0.5),`<br />`0 3px 8px 0 #555a64` | `inset 1px 1px 0 0 #2c2e40,`<br />`0 3px 8px 0 #000309` |
+| --search-local-modal-width               | `560px`                                                                | -                                                       |
+| --search-local-modal-width-sm            | `340px`                                                                | -                                                       |
+| --search-local-spacing                   | `12px`                                                                 | -                                                       |
+| --search-local-hit-background            | `#fff`                                                                 | `var(--ifm-color-emphasis-100)`                         |
+| --search-local-hit-shadow                | `0 1px 3px 0 #d4d9e1`                                                  | `none`                                                  |
+| --search-local-hit-color                 | `#444950`                                                              | `var(--ifm-font-color-base)`                            |
+| --search-local-hit-height                | `56px`                                                                 | -                                                       |
+| --search-local-highlight-color           | `var(--ifm-color-primary)`                                             | -                                                       |
+| --search-local-muted-color               | `#969faf`                                                              | `var(--ifm-color-secondary-darkest)`                    |
+| --search-local-icon-stroke-width         | `1.4`                                                                  | -                                                       |
+| --search-local-hit-active-color          | `var(--ifm-color-white)`                                               | -                                                       |
+| --search-local-input-active-border-color | `var(--ifm-color-primary)`                                             | -                                                       |
 
 E.g.:
 
diff --git a/docusaurus-search-local/src/client/theme/worker.ts b/docusaurus-search-local/src/client/theme/worker.ts
@@ -74,6 +74,9 @@ export class SearchWorker {
                 query.term(item.value, {
                   wildcard: item.wildcard,
                   presence: item.presence,
+                  ...(item.editDistance
+                    ? { editDistance: item.editDistance }
+                    : null),
                 });
               }
             })
diff --git a/docusaurus-search-local/src/client/utils/__mocks__/proxiedGeneratedConstants.ts b/docusaurus-search-local/src/client/utils/__mocks__/proxiedGeneratedConstants.ts
@@ -2,6 +2,7 @@ export let language = ["en", "zh"];
 export let removeDefaultStopWordFilter = false;
 export const searchIndexUrl = "search-index{dir}.json?_=abc";
 export const searchResultLimits = 8;
+export let fuzzyMatchingDistance = 0;
 
 export function __setLanguage(value: string[]): void {
   language = value;
@@ -10,3 +11,7 @@ export function __setLanguage(value: string[]): void {
 export function __setRemoveDefaultStopWordFilter(value: boolean): void {
   removeDefaultStopWordFilter = value;
 }
+
+export function __setFuzzyMatchingDistance(value: number): void {
+  fuzzyMatchingDistance = value;
+}
diff --git a/docusaurus-search-local/src/client/utils/smartQueries.spec.ts b/docusaurus-search-local/src/client/utils/smartQueries.spec.ts
@@ -3,6 +3,7 @@ import { smartQueries } from "./smartQueries";
 import {
   __setLanguage,
   __setRemoveDefaultStopWordFilter,
+  __setFuzzyMatchingDistance,
 } from "./proxiedGeneratedConstants";
 import { SmartQuery } from "../../shared/interfaces";
 
@@ -259,6 +260,53 @@ describe("smartQueries with no stop words filter", () => {
   });
 });
 
+describe("smartQueries with fuzzy matching", () => {
+  beforeEach(() => {
+    __setFuzzyMatchingDistance(1);
+  });
+
+  test.each<[string[], TestQuery[]]>([
+    [
+      ["a", "hello"],
+      [
+        {
+          tokens: ["a", "hello"],
+          keyword: "+a +hello",
+        },
+        {
+          tokens: ["a", "hello"],
+          keyword: "+a +hello*",
+        },
+        {
+          tokens: ["a", "hello"],
+          keyword: "+a +hello~1",
+        },
+        {
+          tokens: ["a", "hello"],
+          keyword: "+a +hello*~1",
+        },
+      ],
+    ],
+    [
+      ["a", "b"],
+      [
+        {
+          tokens: ["a", "b"],
+          keyword: "+a +b",
+        },
+        {
+          tokens: ["a", "b"],
+          keyword: "+a +b*",
+        },
+      ],
+    ],
+  ])("smartQueries(%j, zhDictionary) should work", (tokens, queries) => {
+    expect(smartQueries(tokens, zhDictionary).map(transformQuery)).toEqual(
+      queries
+    );
+  });
+});
+
 function transformQuery(query: SmartQuery): TestQuery {
   return {
     tokens: query.tokens,
@@ -275,6 +323,10 @@ function transformQuery(query: SmartQuery): TestQuery {
             lunr.Query.wildcard.TRAILING
               ? "*"
               : ""
+          }${
+            typeof item.editDistance === "number" && item.editDistance > 0
+              ? `~${item.editDistance}`
+              : ""
           }`
       )
       .join(" "),
diff --git a/docusaurus-search-local/src/client/utils/smartQueries.ts b/docusaurus-search-local/src/client/utils/smartQueries.ts
@@ -1,7 +1,11 @@
 import lunr from "lunr";
 import { SmartQuery, SmartTerm } from "../../shared/interfaces";
 import { smartTerms } from "./smartTerms";
-import { language, removeDefaultStopWordFilter } from "./proxiedGeneratedConstants";
+import {
+  language,
+  removeDefaultStopWordFilter,
+  fuzzyMatchingDistance,
+} from "./proxiedGeneratedConstants";
 
 /**
  * Get all possible queries for a list of tokens consists of words mixed English and Chinese,
@@ -93,39 +97,65 @@ export function smartQueries(
     }
   }
 
-  return getQueriesMaybeTyping(terms).concat(getQueriesMaybeTyping(extraTerms));
+  return getQueriesMaybeTyping(terms).concat(
+    fuzzyMatchingDistance > 0
+      ? getQueriesMaybeTyping(terms, fuzzyMatchingDistance)
+      : [],
+    getQueriesMaybeTyping(extraTerms),
+    fuzzyMatchingDistance > 0
+      ? getQueriesMaybeTyping(extraTerms, fuzzyMatchingDistance)
+      : []
+  );
 }
 
-function getQueriesMaybeTyping(terms: SmartTerm[]): SmartQuery[] {
-  return termsToQueries(terms).concat(
+function getQueriesMaybeTyping(
+  terms: SmartTerm[],
+  editDistance?: number
+): SmartQuery[] {
+  return termsToQueries(terms, false, editDistance).concat(
     termsToQueries(
       // Ignore terms whose last token already has a trailing wildcard,
       // or the last token is not `maybeTyping`.
       terms.filter((term) => {
         const token = term[term.length - 1];
         return !token.trailing && token.maybeTyping;
       }),
-      true
+      true,
+      editDistance
     )
   );
 }
 
 function termsToQueries(
   terms: SmartTerm[],
-  maybeTyping?: boolean
+  maybeTyping?: boolean,
+  editDistance?: number
 ): SmartQuery[] {
-  return terms.map((term) => ({
-    tokens: term.map((item) => item.value),
-    term: term.map((item) => ({
-      value: item.value,
-      presence: lunr.Query.presence.REQUIRED,
-      // The last token of a term maybe incomplete while user is typing.
-      // So append more queries with trailing wildcard added.
-      wildcard: (
-        maybeTyping ? item.trailing || item.maybeTyping : item.trailing
-      )
-        ? lunr.Query.wildcard.TRAILING
-        : lunr.Query.wildcard.NONE,
-    })),
-  }));
+  return terms.flatMap((term) => {
+    const query = {
+      tokens: term.map((item) => item.value),
+      term: term.map((item) => ({
+        value: item.value,
+        presence: lunr.Query.presence.REQUIRED,
+        // The last token of a term maybe incomplete while user is typing.
+        // So append more queries with trailing wildcard added.
+        wildcard: (
+          maybeTyping ? item.trailing || item.maybeTyping : item.trailing
+        )
+          ? lunr.Query.wildcard.TRAILING
+          : lunr.Query.wildcard.NONE,
+        editDistance:
+          editDistance && item.value.length > editDistance
+            ? editDistance
+            : undefined,
+      })),
+    };
+
+    // Ignore queries that all terms ignored edit distance due to too short tokens.
+    if (editDistance && query.term.every((item) => !item.editDistance)) {
+      return [];
+    }
+
+    return query;
+  });
 }
diff --git a/docusaurus-search-local/src/declarations.ts b/docusaurus-search-local/src/declarations.ts
@@ -30,6 +30,7 @@ declare module "*/generated-constants.js" {
   export const language: string[];
   export const searchIndexUrl: string;
   export const searchResultLimits: number;
+  export const fuzzyMatchingDistance: number;
   // These below are for mocking only.
   export const __setLanguage: (value: string[]) => void;
   export const __setRemoveDefaultStopWordFilter: (value: boolean) => void;
diff --git a/docusaurus-search-local/src/index.ts b/docusaurus-search-local/src/index.ts
@@ -199,4 +199,12 @@ export interface PluginOptions {
    * @default false
    */
   forceIgnoreNoIndex?: boolean;
+
+  /**
+   * Set the edit distance for fuzzy matching during searches. Lower values will result in stricter matches,
+   * while higher values will allow for more lenient matches. Set 0 to disable fuzzy matching.
+   *
+   * @default 1
+   */
+  fuzzyMatchingDistance?: number;
 }
diff --git a/docusaurus-search-local/src/server/utils/generate.spec.ts b/docusaurus-search-local/src/server/utils/generate.spec.ts
@@ -233,9 +233,25 @@ describe("generate", () => {
 
     expect(mockWriteFileSync).toBeCalledWith(
       expect.toMatchPath("/tmp/generated.js"),
-      expect.stringContaining(
-        'export const Mark = null;'
-      )
+      expect.stringContaining("export const Mark = null;")
+    );
+  });
+
+  test("fuzzy matching distance", () => {
+    generate(
+      {
+        language: ["en"],
+        removeDefaultStopWordFilter: false,
+        searchResultLimits: 8,
+        searchResultContextMaxLength: 50,
+        fuzzyMatchingDistance: 2,
+      } as ProcessedPluginOptions,
+      "/tmp"
+    );
+
+    expect(mockWriteFileSync).toBeCalledWith(
+      expect.toMatchPath("/tmp/generated-constants.js"),
+      expect.stringContaining("export const fuzzyMatchingDistance = 2;")
     );
   });
 });
diff --git a/docusaurus-search-local/src/server/utils/generate.ts b/docusaurus-search-local/src/server/utils/generate.ts
@@ -20,6 +20,7 @@ export function generate(config: ProcessedPluginOptions, dir: string): string {
     searchContextByPaths,
     hideSearchBarWithNoSearchContext,
     useAllContextsWithNoSearchContext,
+    fuzzyMatchingDistance,
   } = config;
   const indexHash = getIndexHash(config);
   const contents: string[] = [];
@@ -148,8 +149,14 @@ export function generate(config: ProcessedPluginOptions, dir: string): string {
   constantContents.push(
     `export const searchIndexUrl = ${JSON.stringify(searchIndexUrl)};`,
     `export const searchResultLimits = ${JSON.stringify(searchResultLimits)};`,
+    `export const fuzzyMatchingDistance = ${JSON.stringify(
+      fuzzyMatchingDistance
+    )};`
+  );
+  fs.writeFileSync(
+    path.join(dir, "generated-constants.js"),
+    constantContents.join("\n")
   );
-  fs.writeFileSync(path.join(dir, "generated-constants.js"), constantContents.join("\n"));
 
   return searchIndexFilename;
 }
diff --git a/docusaurus-search-local/src/server/utils/validateOptions.spec.ts b/docusaurus-search-local/src/server/utils/validateOptions.spec.ts
diff --git a/docusaurus-search-local/src/server/utils/validateOptions.ts b/docusaurus-search-local/src/server/utils/validateOptions.ts
diff --git a/docusaurus-search-local/src/shared/interfaces.ts b/docusaurus-search-local/src/shared/interfaces.ts
