TypeDoc now supports a browser bundle

Resolves #2528

Author: Gerrit0

.vscode/settings.json

@@ -45,6 +45,7 @@
         "Combinatorially",
         "deconfliction",
         "deserializers",
+        "dprint",
         "frontmatter",
         "githubprivate",
         "hideconstructor",

CHANGELOG.md

@@ -23,11 +23,10 @@ title: Changelog
 - File name references in `intentionallyNotExported` now use a package name/package relative path instead of an absolute path for matching.
 - Introduced `packagesRequiringDocumentation` option for `validation.notDocumented`, TypeDoc will expect comments to be present for symbols in the specified packages.
 - TypeDoc's `--entryPointStrategy merge` mode now requires JSON from at least version 0.28.0.
+- TypeDoc now exports a `typedoc/browser` entrypoint for parsing and using serialized JSON files, #2528.
 
 TODO:
 
-- Generate locale bundles for strings used in models/utils-common/serializer/deserializer
-- Finish supporting models/serde as browser import
 - Clean up Internationalization class, it probably doesn't make sense anymore.
 
 ## Unreleased

package.json

@@ -9,6 +9,8 @@
         "./tsdoc.json": "./tsdoc.json",
         "./package.json": "./package.json",
         "./models": "./dist/lib/models/index.js",
+        "./browser": "./dist/browser-utils.js",
+        "./browser/*": "./dist/browser-locales/*.js",
         "./debug": "./dist/lib/debug/index.js",
         "./debug/*": "./dist/lib/debug/*.js"
     },
@@ -75,10 +77,11 @@
         "example": "cd example && node ../bin/typedoc",
         "test:full": "c8 -r lcov -r text-summary mocha --config .config/mocha.full.json",
         "rebuild_specs": "node scripts/rebuild_specs.js",
-        "build": "npm run build:tsc && npm run build:themes",
+        "build": "npm run build:tsc && npm run build:locales && npm run build:themes",
         "build:tsc": "tsc --project .",
         "build:themes": "node scripts/build_themes.js",
-        "build:prod": "npm run build:prod:tsc && npm run build:themes",
+        "build:locales": "tsx scripts/build_browser_translations.js",
+        "build:prod": "npm run build:prod:tsc && npm run build:locales && npm run build:themes",
         "build:prod:tsc": "tsc --project . --sourceMap false --declarationMap false",
         "lint": "eslint . --max-warnings 0 && dprint check",
         "prepack": "node scripts/set_strict.js false && npm run build:prod",

scripts/build_browser_translations.ts

@@ -0,0 +1,116 @@
+// Expects to be run with tsx
+// @ts-check
+
+import ts from "typescript";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { Logger, Options, TSConfigReader } from "typedoc";
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { ok } from "node:assert";
+
+const browserBundleFolders = [
+    "/utils-common/",
+    "/models/",
+    "/serialization/",
+];
+
+const localesDir = join(
+    fileURLToPath(import.meta.url),
+    "../../src/lib/internationalization/locales",
+);
+
+const distDir = join(
+    fileURLToPath(import.meta.url),
+    "../../dist/browser-locales",
+);
+
+const options = new Options();
+const tsconfigReader = new TSConfigReader();
+tsconfigReader.read(options, new Logger(), process.cwd());
+
+/** @type {ts.LanguageServiceHost} */
+const host = {
+    getScriptFileNames: () => options.getFileNames().slice(),
+    getScriptVersion: () => "unused",
+    getScriptSnapshot: (fileName) => {
+        if (!existsSync(fileName)) return undefined;
+        return ts.ScriptSnapshot.fromString(
+            readFileSync(fileName, "utf-8"),
+        );
+    },
+    getCurrentDirectory: () => process.cwd(),
+    getCompilationSettings: () => options.getCompilerOptions(),
+    getDefaultLibFileName: (opts) => ts.getDefaultLibFilePath(opts),
+    fileExists: ts.sys.fileExists,
+    readFile: ts.sys.readFile,
+    readDirectory: ts.sys.readDirectory,
+    directoryExists: ts.sys.directoryExists,
+    getDirectories: ts.sys.getDirectories,
+};
+
+const service = ts.createLanguageService(
+    host,
+    ts.createDocumentRegistry(),
+);
+
+const program = service.getProgram();
+ok(program, "Failed to get program for i18n analysis");
+
+const sf = program.getSourceFile(join(localesDir, "en.cts"));
+ok(sf, "Failed to get source file");
+
+const moduleSymbol = program.getTypeChecker().getSymbolAtLocation(sf);
+const translatable = moduleSymbol?.exports?.get(
+    "export=" as ts.__String,
+);
+ok(translatable, "Failed to get translatable symbol");
+
+ok(translatable.valueDeclaration && ts.isExportAssignment(translatable.valueDeclaration));
+ok(ts.isAsExpression(translatable.valueDeclaration.expression));
+ok(
+    ts.isObjectLiteralExpression(
+        translatable.valueDeclaration.expression.expression,
+    ),
+);
+const translatableObj = translatable.valueDeclaration.expression.expression;
+
+const bundleUsedTranslationKeys: string[] = [];
+
+translatableObj.forEachChild((child) => {
+    ok(ts.isPropertyAssignment(child));
+    const refs = service.getReferencesAtPosition(
+        sf.fileName,
+        child.getStart(),
+    );
+
+    if (refs?.some(ref => browserBundleFolders.some(f => ref.fileName.includes(f)))) {
+        bundleUsedTranslationKeys.push(child.name.getText());
+    }
+});
+
+service.dispose();
+
+const enLocale = (await import(join(localesDir, "en.cts"))).default;
+
+rmSync(distDir, { recursive: true, force: true });
+mkdirSync(distDir, { recursive: true });
+
+for (const locale of readdirSync(localesDir)) {
+    console.log(`Processing ${locale}`);
+
+    const browserTranslations = {};
+    const translations = (await import(join(localesDir, locale))).default;
+    for (const key of bundleUsedTranslationKeys) {
+        browserTranslations[key] = translations[key] || enLocale[key];
+    }
+
+    writeFileSync(
+        join(distDir, locale.replace(".cts", ".js")),
+        `export default ${JSON.stringify(browserTranslations, null, 4)}\n`,
+    );
+
+    writeFileSync(
+        join(distDir, locale.replace(".cts", ".d.ts")),
+        `const translations: Record<string, string>;\nexport default translations;\n`,
+    );
+}

site/overview.md

@@ -72,3 +72,41 @@ if (project) {
     await app.generateJson(project, outputDir + "/docs.json");
 }
 ```
+
+## Browser Bundle
+
+TypeDoc exports a limited portion of its API surface for users who want to process
+serialized JSON from TypeDoc within a browser via `typedoc/browser`. The browser
+entry point includes the following components:
+
+- TypeDoc's models
+- `Serializer` and `Deserializer` classes
+- A small set of utility functions
+
+```ts
+import {
+    ConsoleLogger,
+    Deserializer,
+    FileRegistry,
+    setTranslations,
+} from "typedoc/browser";
+
+// Similar paths are available for ja, ko, zh
+import translations from "typedoc/browser/en";
+
+// Before doing anything with TypeDoc, it should be configured with translations
+setTranslations(translations);
+
+const projectJson = await fetch("...").then(r => r.json());
+
+const logger = new ConsoleLogger();
+const deserializer = new Deserializer(logger);
+const project = deserializer.reviveProject("API Docs", projectJson, {
+    projectRoot: "/",
+    registry: new FileRegistry(),
+});
+
+// Now we can use TypeDoc's models to more easily analyze the json
+console.log(project.getChildByName("SomeClass.property"));
+console.log(project.getChildByName("SomeClass.property").type.toString());
+```

src/browser-utils.ts

@@ -0,0 +1,29 @@
+export * from "#models";
+
+export {
+    type ComponentPath,
+    ConsoleLogger,
+    type DeclarationReference,
+    type EnumKeys,
+    Logger,
+    LogLevel,
+    type Meaning,
+    type MinimalNode,
+    MinimalSourceFile,
+    type NormalizedPath,
+    setTranslations,
+    type SymbolReference,
+    type TranslatedString,
+    translateTagName,
+} from "#utils";
+
+export {
+    type Deserializable,
+    Deserializer,
+    type DeserializerComponent,
+    JSONOutput,
+    SerializeEvent,
+    Serializer,
+    type SerializerComponent,
+    type SerializerEvents,
+} from "#serialization";

src/lib/converter/comments/parser.ts

@@ -2,7 +2,7 @@ import assert, { ok } from "assert";
 import { parseDocument as parseYamlDoc } from "yaml";
 import type { CommentParserConfig } from "./index.js";
 import { Comment, type CommentDisplayPart, CommentTag, type InlineTagDisplayPart } from "../../models/index.js";
-import type { MinimalSourceFile } from "../../utils-common/minimalSourceFile.js";
+import type { MinimalSourceFile } from "#utils";
 import { nicePath } from "../../utils/paths.js";
 import { type Token, TokenSyntaxKind } from "./lexer.js";
 import { extractTagName } from "./tagName.js";

src/lib/converter/comments/textParser.ts

@@ -8,10 +8,11 @@
 import type { TranslatedString, TranslationProxy } from "../../internationalization/index.js";
 import type { CommentDisplayPart, RelativeLinkDisplayPart } from "../../models/index.js";
 import type { FileRegistry } from "../../models/FileRegistry.js";
-import { HtmlAttributeParser, type NormalizedPath, ParserState } from "#utils";
+import { HtmlAttributeParser, ParserState } from "#node-utils";
 import { type Token, TokenSyntaxKind } from "./lexer.js";
 
 import MarkdownIt from "markdown-it";
+import type { NormalizedPath } from "#utils";
 const MdHelpers = new MarkdownIt().helpers;
 
 interface TextParserData {

src/lib/converter/plugins/IncludePlugin.ts

@@ -4,7 +4,7 @@ import fs from "fs";
 import { ConverterComponent } from "../components.js";
 import { ConverterEvents } from "../converter-events.js";
 import type { CommentDisplayPart, Reflection } from "../../models/index.js";
-import { MinimalSourceFile } from "../../utils-common/minimalSourceFile.js";
+import { MinimalSourceFile } from "#utils";
 import type { Converter } from "../converter.js";
 import { isFile } from "../../utils/fs.js";
 import { dedent, escapeRegExp, i18n } from "#utils";

src/lib/models/ProjectReflection.ts

@@ -95,7 +95,7 @@ export class ProjectReflection extends ContainerReflection {
      * Registers the given reflection so that it can be quickly looked up by helper methods.
      * Should be called for *every* reflection added to the project.
      *
-     * Note: During conversion, {@link Context.registerReflection} should be used instead so
+     * Note: During conversion, `Context.registerReflection` should be used instead so
      * that symbols can be saved for later use.
      */
     registerReflection(