precompute category boosts

Author: shmax

example/src/classes/Customer.ts

@@ -2,6 +2,8 @@
  * An abstract base class for the customer entity in our application.
  *
  * Notice how TypeDoc shows the inheritance hierarchy for our class.
+ *
+ * @category Model
  */
 export abstract class Customer {
     /** A public readonly property. */

example/src/reactComponents.tsx

@@ -36,6 +36,8 @@ export interface CardAProps {
  * This is our recommended way to define React components as it makes your code
  * more readable. The minor drawback is you must click the `CardAProps` link to
  * see the component's props.
+ *
+ * @category Component
  */
 export function CardA({ children, variant = "primary" }: PropsWithChildren<CardAProps>): ReactElement {
     return <div className={`card card-${variant}`}>{children}</div>;
@@ -66,6 +68,8 @@ export function CardA({ children, variant = "primary" }: PropsWithChildren<CardA
  *
  * This can make the TypeDoc documentation a bit cleaner for very simple components,
  * but it makes your code less readable.
+ *
+ * @category Component
  */
 export function CardB({
     children,
@@ -245,6 +249,7 @@ export interface EasyFormDialogProps {
  *     )
  * }
  * ```
+ * @category Component
  */
 export function EasyFormDialog(props: PropsWithChildren<EasyFormDialogProps>): ReactElement {
     return <div />;

example/typedoc.json

@@ -3,14 +3,16 @@
     "entryPoints": ["./src"],
     "sort": ["source-order"],
     "media": "media",
+    "categorizeByGroup": false,
     "search": {
         "numResults": 12,
         "boosts": {
             "byKind": {
                 "class": 1.2
             },
             "byCategory": {
-                "Lang": 10
+                "Component": 2,
+                "Model": 1.2
             }
         }
     }

src/lib/converter/context.ts

@@ -14,6 +14,7 @@ import type { Converter } from "./converter";
 import { isNamedNode } from "./utils/nodes";
 import { ConverterEvents } from "./converter-events";
 import { resolveAliasedSymbol } from "./utils/symbols";
+import type { SearchConfig } from "../utils/options/declaration";
 
 /**
  * The context describes the current state the converter is in.
@@ -118,6 +119,12 @@ export class Context {
         return this.converter.application.options.getCompilerOptions();
     }
 
+    getSearchOptions(): SearchConfig {
+        return this.converter.application.options.getValue(
+            "search"
+        ) as SearchConfig;
+    }
+
     /**
      * Return the type declaration of the given node.
      *

src/lib/converter/plugins/CategoryPlugin.ts

@@ -4,12 +4,12 @@ import {
     DeclarationReflection,
     CommentTag,
 } from "../../models";
-import { ReflectionCategory } from "../../models/ReflectionCategory";
+import { ReflectionCategory } from "../../models";
 import { Component, ConverterComponent } from "../components";
 import { Converter } from "../converter";
 import type { Context } from "../context";
 import { BindOption } from "../../utils";
-import type { Comment } from "../../models/comments/index";
+import type { Comment } from "../../models";
 
 /**
  * A handler that sorts and categorizes the found reflections in the resolving phase.
@@ -66,9 +66,12 @@ export class CategoryPlugin extends ConverterComponent {
      * @param context  The context object describing the current state the converter is in.
      * @param reflection  The reflection that is currently resolved.
      */
-    private onResolve(_context: Context, reflection: Reflection) {
+    private onResolve(context: Context, reflection: Reflection) {
         if (reflection instanceof ContainerReflection) {
-            this.categorize(reflection);
+            this.categorize(
+                reflection,
+                context.getSearchOptions().boosts?.byCategory ?? {}
+            );
         }
     }
 
@@ -79,26 +82,36 @@ export class CategoryPlugin extends ConverterComponent {
      */
     private onEndResolve(context: Context) {
         const project = context.project;
-        this.categorize(project);
+        this.categorize(
+            project,
+            context.getSearchOptions().boosts?.byCategory ?? {}
+        );
     }
 
-    private categorize(obj: ContainerReflection) {
+    private categorize(
+        obj: ContainerReflection,
+        categorySearchBoosts: { [key: string]: number }
+    ) {
         if (this.categorizeByGroup) {
-            this.groupCategorize(obj);
+            this.groupCategorize(obj, categorySearchBoosts);
         } else {
-            this.lumpCategorize(obj);
+            CategoryPlugin.lumpCategorize(obj, categorySearchBoosts);
         }
     }
 
-    private groupCategorize(obj: ContainerReflection) {
+    private groupCategorize(
+        obj: ContainerReflection,
+        categorySearchBoosts: { [key: string]: number }
+    ) {
         if (!obj.groups || obj.groups.length === 0) {
             return;
         }
         obj.groups.forEach((group) => {
             if (group.categories) return;
 
             group.categories = CategoryPlugin.getReflectionCategories(
-                group.children
+                group.children,
+                categorySearchBoosts
             );
             if (group.categories && group.categories.length > 1) {
                 group.categories.sort(CategoryPlugin.sortCatCallback);
@@ -112,11 +125,17 @@ export class CategoryPlugin extends ConverterComponent {
         });
     }
 
-    private lumpCategorize(obj: ContainerReflection) {
+    static lumpCategorize(
+        obj: ContainerReflection,
+        categorySearchBoosts: { [key: string]: number }
+    ) {
         if (!obj.children || obj.children.length === 0 || obj.categories) {
             return;
         }
-        obj.categories = CategoryPlugin.getReflectionCategories(obj.children);
+        obj.categories = CategoryPlugin.getReflectionCategories(
+            obj.children,
+            categorySearchBoosts
+        );
         if (obj.categories && obj.categories.length > 1) {
             obj.categories.sort(CategoryPlugin.sortCatCallback);
         } else if (
@@ -132,10 +151,13 @@ export class CategoryPlugin extends ConverterComponent {
      * Create a categorized representation of the given list of reflections.
      *
      * @param reflections  The reflections that should be categorized.
+     * @param categorySearchBoosts A user-supplied map of category titles, for computing a
+     *   relevance boost to be used when searching
      * @returns An array containing all children of the given reflection categorized
      */
     static getReflectionCategories(
-        reflections: DeclarationReflection[]
+        reflections: DeclarationReflection[],
+        categorySearchBoosts: { [key: string]: number }
     ): ReflectionCategory[] {
         const categories: ReflectionCategory[] = [];
         let defaultCat: ReflectionCategory | undefined;
@@ -154,11 +176,17 @@ export class CategoryPlugin extends ConverterComponent {
                         categories.push(defaultCat);
                     }
                 }
+
                 defaultCat.children.push(child);
                 return;
             }
             for (const childCat of childCategories) {
                 let category = categories.find((cat) => cat.title === childCat);
+
+                const catBoost = categorySearchBoosts[category?.title ?? -1];
+                if (catBoost != undefined) {
+                    child.categoryBoost = catBoost;
+                }
                 if (category) {
                     category.children.push(child);
                     continue;

src/lib/models/reflections/container.ts

@@ -20,6 +20,12 @@ export class ContainerReflection extends Reflection {
      */
     categories?: ReflectionCategory[];
 
+    /**
+     * A precomputed boost derived from the searchCategoryBoosts typedoc.json setting, to be used when
+     * boosting search relevance scores at runtime.
+     */
+    categoryBoost?: number;
+
     /**
      * Return a list of all children of a certain kind.
      *

src/lib/output/plugins/JavascriptIndexPlugin.ts

@@ -70,9 +70,7 @@ export class JavascriptIndexPlugin extends RendererComponent {
                 name: reflection.name,
                 url: reflection.url,
                 classes: reflection.cssClasses,
-                categories: (reflection.categories ?? []).map(
-                    (category) => category.title
-                ),
+                categoryBoost: reflection.categoryBoost,
             };
 
             if (parent) {

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

@@ -1,7 +1,7 @@
 import { debounce } from "../utils/debounce";
 import { Index } from "lunr";
 import type { SearchConfig } from "../../../../../../utils/options/declaration";
-import { ReflectionKind } from "../../../../../../models/reflections/kind";
+import { ReflectionKind } from "../../../../../../models";
 
 export interface IDocument {
     id: number;
@@ -10,7 +10,7 @@ export interface IDocument {
     url: string;
     classes?: string;
     parent?: string;
-    categories: Array<string>;
+    categoryBoost?: number;
 }
 
 interface IData {
@@ -174,10 +174,8 @@ function updateResults(
         let boost = 1;
 
         // boost by exact match on name
-        if(row.name
-            .toLowerCase()
-            .startsWith(searchText.toLowerCase())) {
-            boost *= (1 / Math.abs(row.name.length - searchText.length) * 10)
+        if (row.name.toLowerCase().startsWith(searchText.toLowerCase())) {
+            boost *= 1 / (Math.abs(row.name.length - searchText.length) * 10);
         }
 
         // boost by kind
@@ -197,12 +195,7 @@ function updateResults(
         }
 
         // boost by category
-        for (let categoryTitle in searchConfig.boosts?.byCategory ?? []) {
-            if (row.categories.indexOf(categoryTitle) > -1) {
-                boost *=
-                    searchConfig.boosts?.byCategory?.[categoryTitle] ?? 1;
-            }
-        }
+        boost *= row.categoryBoost ?? 1;
 
         item.score *= boost;
     }
@@ -226,7 +219,7 @@ function updateResults(
         }
 
         const item = document.createElement("li");
-         item.classList.value = row.classes ?? '';
+        item.classList.value = row.classes ?? "";
 
         const anchor = document.createElement("a");
         anchor.href = state.base + row.url;