Search boosts

example/typedoc.json

@@ -2,5 +2,17 @@
     "$schema": "https://typedoc.org/schema.json",
     "entryPoints": ["./src"],
     "sort": ["source-order"],
-    "media": "media"
+    "media": "media",
+    "search": {
+        "numResults": 12,
+        "boosts": {
+            "exactMatch": 2,
+            "byKind": {
+                "class": 1.2
+            },
+            "byCategory": {
+                "Lang": 10
+            }
+        }
+    }
 }

src/lib/output/plugins/JavascriptIndexPlugin.ts

@@ -5,12 +5,13 @@ import {
     DeclarationReflection,
     ProjectReflection,
     ReflectionKind,
-} from "../../models/reflections/index";
-import { GroupPlugin } from "../../converter/plugins/GroupPlugin";
+} from "../../models";
+import { GroupPlugin } from "../../converter/plugins";
 import { Component, RendererComponent } from "../components";
 import { RendererEvent } from "../events";
 import { writeFileSync } from "../../utils";
 import { DefaultTheme } from "../themes/default/DefaultTheme";
+import type { IDocument } from "../themes/default/assets/typedoc/components/Search";
 
 /**
  * A plugin that exports an index of the project to a javascript file.
@@ -63,12 +64,15 @@ export class JavascriptIndexPlugin extends RendererComponent {
                 parent = undefined;
             }
 
-            const row: any = {
+            const row: IDocument = {
                 id: rows.length,
                 kind: reflection.kind,
                 name: reflection.name,
                 url: reflection.url,
-                classes: reflection.cssClasses,
+                classes: reflection.cssClasses ?? "",
+                categories: (reflection.categories ?? []).map(
+                    (category) => category.title
+                ),
             };
 
             if (parent) {
@@ -100,7 +104,11 @@ export class JavascriptIndexPlugin extends RendererComponent {
             "assets",
             "search.js"
         );
+
+        const searchConfig = this.application.options.getValue("search");
+
         const jsonData = JSON.stringify({
+            searchConfig,
             kinds,
             rows,
             index,

src/lib/output/themes/default/assets/typedoc/components/Search.ts

@@ -1,19 +1,23 @@
 import { debounce } from "../utils/debounce";
 import { Index } from "lunr";
+import type { SearchConfig } from "../../../../../../utils/options/declaration";
+import { ReflectionKind } from "../../../../../../models/reflections/kind";
 
-interface IDocument {
+export interface IDocument {
     id: number;
     kind: number;
     name: string;
     url: string;
     classes: string;
     parent?: string;
+    categories: Array<string>;
 }
 
 interface IData {
     kinds: { [kind: number]: string };
     rows: IDocument[];
     index: object;
+    searchConfig: SearchConfig;
 }
 
 declare global {
@@ -78,19 +82,26 @@ export function initSearch() {
         base: searchEl.dataset["base"] + "/",
     };
 
-    bindEvents(searchEl, results, field, state);
+    bindEvents(
+        searchEl,
+        results,
+        field,
+        state,
+        window?.searchData?.searchConfig ?? {}
+    );
 }
 
 function bindEvents(
     searchEl: HTMLElement,
     results: HTMLElement,
     field: HTMLInputElement,
-    state: SearchState
+    state: SearchState,
+    searchConfig: SearchConfig
 ) {
     field.addEventListener(
         "input",
         debounce(() => {
-            updateResults(searchEl, results, field, state);
+            updateResults(searchEl, results, field, state, searchConfig);
         }, 200)
     );
 
@@ -140,7 +151,8 @@ function updateResults(
     searchEl: HTMLElement,
     results: HTMLElement,
     query: HTMLInputElement,
-    state: SearchState
+    state: SearchState,
+    searchConfig: SearchConfig
 ) {
     checkIndex(state, searchEl);
     // Don't clear results if loading state is not ready,
@@ -154,9 +166,57 @@ function updateResults(
     // Perform a wildcard search
     // Set empty `res` to prevent getting random results with wildcard search
     // when the `searchText` is empty.
-    const res = searchText ? state.index.search(`*${searchText}*`) : [];
+    let res = searchText ? state.index.search(`*${searchText}*`) : [];
+
+    if (searchConfig.boosts != undefined) {
+        for (let i = 0; i < res.length; i++) {
+            const item = res[i];
+            const row = state.data.rows[Number(item.ref)];
+            let boost = 1;
+
+            // boost by exact match on name
+            if (
+                searchConfig.boosts.exactMatch &&
+                row.name.toLowerCase() === searchText.toLowerCase()
+            ) {
+                boost *= searchConfig.boosts.exactMatch;
+            }
+
+            // boost by kind
+            for (let kindName in searchConfig.boosts.byKind ?? {}) {
+                const kind: ReflectionKind = parseInt(
+                    Object.keys(ReflectionKind).find(
+                        (key: string) =>
+                            ReflectionKind[key as keyof typeof ReflectionKind]
+                                .toString()
+                                .toLowerCase() === kindName.toLowerCase()
+                    ) ?? "",
+                    10
+                );
+                if (row.kind == kind) {
+                    boost *= searchConfig?.boosts?.byKind?.[kindName] ?? 1;
+                }
+            }
+
+            // boost by category
+            for (let categoryTitle in searchConfig.boosts?.byCategory ?? []) {
+                if (row.categories.indexOf(categoryTitle) > -1) {
+                    boost *=
+                        searchConfig.boosts.byCategory?.[categoryTitle] ?? 1;
+                }
+            }
+
+            item.score *= boost;
+        }
+
+        res.sort((a, b) => b.score - a.score);
+    }
 
-    for (let i = 0, c = Math.min(10, res.length); i < c; i++) {
+    for (
+        let i = 0, c = Math.min(searchConfig.numResults ?? 10, res.length);
+        i < c;
+        i++
+    ) {
         const row = state.data.rows[Number(res[i].ref)];
 
         // Bold the matched part of the query in the search results
@@ -199,11 +259,11 @@ function setCurrentResult(results: HTMLElement, dir: number) {
         // current with the arrow keys.
         if (dir === 1) {
             do {
-                rel = rel.nextElementSibling;
+                rel = rel.nextElementSibling ?? undefined;
             } while (rel instanceof HTMLElement && rel.offsetParent == null);
         } else {
             do {
-                rel = rel.previousElementSibling;
+                rel = rel.previousElementSibling ?? undefined;
             } while (rel instanceof HTMLElement && rel.offsetParent == null);
         }
 

src/lib/utils/options/declaration.ts

@@ -3,7 +3,7 @@ import type { LogLevel } from "../loggers";
 import type { SortStrategy } from "../sort";
 import { isAbsolute, join, resolve } from "path";
 import type { EntryPointStrategy } from "../entry-point";
-import type { ReflectionKind } from "../../models/reflections/kind";
+import { ReflectionKind } from "../../models/reflections/kind";
 
 export const EmitStrategy = {
     true: true, // Alias for both, for backwards compatibility until 0.23
@@ -50,6 +50,16 @@ export type TypeDocOptionValues = {
         : TypeDocOptionMap[K][keyof TypeDocOptionMap[K]];
 };
 
+const Kinds = Object.values(ReflectionKind);
+export interface SearchConfig {
+    numResults?: number;
+    boosts?: {
+        exactMatch?: number;
+        byKind?: { [key: typeof Kinds[number]]: number };
+        byCategory?: { [key: string]: number };
+    };
+}
+
 /**
  * Describes all TypeDoc options. Used internally to provide better types when fetching options.
  * External consumers should likely use {@link TypeDocOptions} instead.
@@ -107,6 +117,7 @@ export interface TypeDocOptionMap {
     version: boolean;
     showConfig: boolean;
     plugin: string[];
+    search: unknown;
     logger: unknown; // string | Function
     logLevel: typeof LogLevel;
     markedOptions: unknown;

src/lib/utils/options/sources/typedoc.ts

@@ -70,6 +70,11 @@ export function addTypeDocOptions(options: Pick<Options, "addDeclaration">) {
         help: "Ignore protected variables and methods.",
         type: ParameterType.Boolean,
     });
+    options.addDeclaration({
+        name: "search",
+        help: "Configure search behavior",
+        type: ParameterType.Mixed,
+    });
     options.addDeclaration({
         name: "disableSources",
         help: "Disable setting the source of a reflection when documenting it.",

tsconfig.json

@@ -1,44 +1,41 @@
 {
     "compilerOptions": {
         "module": "CommonJS",
-        "lib": ["es2019", "es2020.promise", "es2020.bigint", "es2020.string"],
+        "lib": [
+            "es2019",
+            "es2020.promise",
+            "es2020.bigint",
+            "es2020.string",
+            "dom"
+        ],
         "target": "es2019",
-
         // Add our `ts` internal types
         "typeRoots": ["node_modules/@types", "src/lib/types"],
         "types": ["node", "glob", "lunr", "marked", "minimatch", "mocha"],
-
         // Speed up dev compilation time
         "incremental": true,
         "tsBuildInfoFile": "node_modules/.cache/.tsbuildinfo",
-
         "experimentalDecorators": true,
-
         "strict": true,
         "alwaysStrict": true,
-
         // For tests
         "resolveJsonModule": true,
-
         // Linting
         "noUnusedLocals": true,
         "noUnusedParameters": true,
         "forceConsistentCasingInFileNames": true,
         "importsNotUsedAsValues": "error",
-
         // Library
         "preserveConstEnums": true,
         "declaration": true,
         "sourceMap": true,
         "isolatedModules": true,
         "noImplicitOverride": true,
         "noPropertyAccessFromIndexSignature": true,
-
         // Output
         "outDir": "dist/",
         "rootDir": "src/",
         "newLine": "LF",
-
         "jsx": "react",
         "jsxFactory": "JSX.createElement",
         "jsxFragmentFactory": "JSX.Fragment"