Build your personal knowledge base with Trilium Notes
TypeScript electronelectron-appknowledge-baseknowledge-graphknowledge-managementknowledge-management-graphlocal-firstnote-managmentnote-takernote-takingnotebooknotesnotes-apppersonal-knowledge-basepersonal-wikiscriptableself-hostedself-hostingwiki
feat(docs): group the types of a TypeScript reference
Elian Doranf0174670c13f
diff --git a/apps/edit-docs/package.json b/apps/edit-docs/package.jsonindex 538fa1a1cb..036fac571c 100644--- a/apps/edit-docs/package.json+++ b/apps/edit-docs/package.json@@ -13,7 +13,8 @@"@triliumnext/commons": "workspace:*","@triliumnext/desktop": "workspace:*","electron": "44.9.0",- "typedoc": "0.28.20"+ "typedoc": "0.28.20",+ "typedoc-plugin-missing-exports": "4.1.4"},"scripts": {"build": "tsx scripts/build.ts",diff --git a/apps/edit-docs/src/typedoc_markdown.spec.ts b/apps/edit-docs/src/typedoc_markdown.spec.tsindex 4899f4ab4d..83f4d82a8f 100644--- a/apps/edit-docs/src/typedoc_markdown.spec.ts+++ b/apps/edit-docs/src/typedoc_markdown.spec.ts@@ -11,6 +11,7 @@ const FIXTURE = `** @packageDocumentation*/+import type { Audience } from "./audience";/** Options of {@link DemoWindowApi.resize}. */export interface ResizeOptions {@@ -27,11 +28,25 @@ export interface Unreached {flag: boolean;}+/** Which screen a window is on. */+export type Screen = "primary" | "secondary";+/** What became of a request. */+export type Outcome =+ /** It went through. */+ | "done"+ /** The user declined it. */+ | "declined";+/** Window controls. */export interface DemoWindowApi {/** Whether the window has the focus. */readonly focused: boolean;+ /** Where the window is. */+ screen: Screen;+ /** Who the window serves. */+ audience: Audience;+/*** Resizes the window.*@@ -45,6 +60,9 @@ export interface DemoWindowApi {/** @deprecated Use {@link resize}. */maximize(): void;++ /** Asks to close the window. */+ requestClose(audience: Audience): Promise<Outcome>;}/** The root of the API. */@@ -56,6 +74,11 @@ export interface DemoApi {}`;+const IMPORTED = `+/** Who a window serves. */+export type Audience = "user" | "guest";+`;+describe("typeDocToMarkdown", () => {let dir: string;let markdown: string;@@ -63,9 +86,10 @@ describe("typeDocToMarkdown", () => {beforeAll(async () => {dir = await mkdtemp(join(tmpdir(), "typedoc-markdown-"));await writeFile(join(dir, "api.ts"), FIXTURE);+ await writeFile(join(dir, "audience.ts"), IMPORTED);await writeFile(join(dir, "tsconfig.json"), JSON.stringify({compilerOptions: { strict: true, target: "ES2022", module: "ESNext", moduleResolution: "bundler" },- files: [ "api.ts" ]+ files: [ "api.ts", "audience.ts" ]}));markdown = typeDocToMarkdown(await runTypeDoc(join(dir, "api.ts"), join(dir, "tsconfig.json")), "DemoApi");}, 60_000);@@ -84,9 +108,13 @@ describe("typeDocToMarkdown", () => {it("opens with the package comment, then the root and what it reaches, in order of reference", () => {expect(markdown.startsWith("The demo API, exposed as `window.demoApi`.\n\n## `DemoApi`")).toBe(true);- const order = [ ...markdown.matchAll(/^## `(\w+)`/gm) ].map(([ , name ]) => name);- // Exports the root never reaches follow, in source order.- expect(order).toEqual([ "DemoApi", "DemoWindowApi", "ResizeOptions", "Size", "Unreached" ]);+ const headings = [ ...markdown.matchAll(/^(#+) `?(\w+)`?/gm) ].map(([ , level, name ]) => `${level} ${name}`);+ // The root and the interfaces with methods come first; the types they use follow under+ // "Types", then the exports the root never reaches, in source order.+ expect(headings).toEqual([+ "## DemoApi", "## DemoWindowApi", "## Types",+ "### Audience", "### ResizeOptions", "### Outcome", "### Size", "### Unreached"+ ]);});it("lists properties in a table, their type above their description", () => {@@ -146,7 +174,7 @@ describe("typeDocToMarkdown", () => {it("writes a type alias as its declaration", () => {expect(markdown).toContain([- "## `Size`",+ "### `Size`","","A size in pixels.","",@@ -155,4 +183,36 @@ describe("typeDocToMarkdown", () => {"```"].join("\n"));});++ it("inlines a union of literals that one member uses, with its description", () => {+ expect(markdown).not.toContain("Screen");+ expect(row("screen")).toContain(+ "<code>\"primary\" | \"secondary\"</code><br>Where the window is.<br>Which screen a window is on."); });++ it("keeps an entry for a union used more than once, even one another module declares", () => {+ expect(row("audience")).toContain("<code>Audience</code>");+ expect(row("requestClose")).toContain("requestClose(audience: Audience): Promise<Outcome>");+ expect(markdown).toContain([+ "### `Audience`",+ "",+ "Who a window serves.",+ "",+ "```ts",+ "type Audience = \"user\" | \"guest\"",+ "```"+ ].join("\n"));+ });++ it("lists the values of a union whose values are documented", () => {+ expect(markdown).toContain([+ "### `Outcome`",+ "",+ "What became of a request.",+ "",+ "| Value | Description |",+ "| --- | --- |",+ "| `\"done\"` | It went through. |",+ "| `\"declined\"` | The user declined it. |"+ ].join("\n"));+ });});diff --git a/apps/edit-docs/src/typedoc_markdown.ts b/apps/edit-docs/src/typedoc_markdown.tsindex e66b8479c7..622db9ab99 100644--- a/apps/edit-docs/src/typedoc_markdown.ts+++ b/apps/edit-docs/src/typedoc_markdown.ts@@ -4,7 +4,13 @@* `@packageDocumentation` comment rather than an H1.*/import { renderToHtml } from "@triliumnext/commons/src/lib/markdown_renderer.js";+import { execFile } from "child_process";+import { mkdtemp, readFile, rm } from "fs/promises";+import { createRequire } from "module";+import { tmpdir } from "os";+import { dirname, join } from "path";import type { JSONOutput } from "typedoc";+import { promisify } from "util";type Project = JSONOutput.ProjectReflection;type Declaration = JSONOutput.DeclarationReflection;@@ -12,41 +18,78 @@ type Signature = JSONOutput.SignatureReflection;type SomeType = JSONOutput.SomeType;type Comment = JSONOutput.Comment;-/** Runs TypeDoc on one entry point and returns its model, as `typedoc --json` writes it. */+/**+ * Runs TypeDoc on one entry point and returns its model, as `typedoc --json` writes it.+ *+ * TypeDoc runs in a process of its own because typedoc-plugin-missing-exports patches TypeDoc+ * and refuses to load a second time in one process.+ */export async function runTypeDoc(entryPoint: string, tsconfig: string): Promise<Project> {- const { Application, normalizePath } = await import("typedoc");- const app = await Application.bootstrap({- // Entry points are globs, which take `/` as the only separator.- entryPoints: [ entryPoint.replaceAll("\\", "/") ],- tsconfig,- skipErrorChecking: true,- sort: [ "source-order" ],- excludePrivate: true,- logLevel: "Error"- });- const project = await app.convert();- if (!project || app.logger.hasErrors()) {- throw new Error(`TypeDoc could not convert ${entryPoint}.`);+ const typeDoc = join(dirname(createRequire(import.meta.url).resolve("typedoc/package.json")), "bin", "typedoc");+ const dir = await mkdtemp(join(tmpdir(), "typedoc-"));+ const output = join(dir, "project.json");+ try {+ await promisify(execFile)(process.execPath, [+ typeDoc,+ // Entry points are globs, which take `/` as the only separator.+ "--entryPoints", entryPoint.replaceAll("\\", "/"),+ "--tsconfig", tsconfig,+ "--json", output,+ "--skipErrorChecking",+ "--sort", "source-order",+ "--excludePrivate",+ "--logLevel", "Error",+ // Declares the types the entry point imports from other modules in an `<internal>` module.+ "--plugin", "typedoc-plugin-missing-exports"+ ]);+ return JSON.parse(await readFile(output, "utf8"));+ } catch (error) {+ // TypeDoc logs its errors to stdout.+ const { stdout, stderr, message } = error as { stdout?: string; stderr?: string; message: string };+ const log = [ stdout, stderr ].map((text) => text?.trim()).filter(Boolean).join("\n") || message;+ throw new Error(`TypeDoc could not convert ${entryPoint}.\n${log}`);+ } finally {+ await rm(dir, { recursive: true, force: true });}-- return app.serializer.projectToObject(project, normalizePath(process.cwd()));}/*** Renders `root` first, then the declarations it reaches in order of first reference, then the* remaining exports in source order. Without `root`, the exports follow in source order.+ *+ * `root` and the interfaces with methods come first, each under a heading of its own; the types+ * they use follow under "Types". A union of literals that one place uses is written out there+ * instead of getting an entry.*/export function typeDocToMarkdown(project: Project, root?: string): string {- const blocks: string[] = [];- if (project.comment) {- blocks.push(renderComment(project.comment));- }+ const { declarations, inlined } = selectDeclarations(project);+ inlinedAliases = inlined;+ try {+ const blocks: string[] = [];+ if (project.comment) {+ blocks.push(renderComment(project.comment));+ }- for (const declaration of orderDeclarations(project.children ?? [], root)) {- blocks.push(...renderDeclaration(declaration));- }+ const ordered = orderDeclarations(declarations, root);+ const isApi = (declaration: Declaration) => declaration.name === root+ || !!declaration.children?.some((member) => member.kind === KIND.method);+ const apis = ordered.filter(isApi);+ const types = ordered.filter((declaration) => !isApi(declaration));+ for (const declaration of apis) {+ blocks.push(...renderDeclaration(declaration, "##"));+ }- return blocks.filter(Boolean).join("\n\n");+ if (apis.length && types.length) {+ blocks.push("## Types");+ }+ for (const declaration of types) {+ blocks.push(...renderDeclaration(declaration, apis.length ? "###" : "##"));+ }++ return blocks.filter(Boolean).join("\n\n");+ } finally {+ inlinedAliases = new Map();+ }}/** The `ReflectionKind` values this module renders. */@@ -58,6 +101,42 @@ const KIND = {accessor: 262144};+/** The aliases `typeToString()` writes out in place of their name, while a page renders. */+let inlinedAliases = new Map<string, Declaration>();++/**+ * The module's exports, and the types it imports from other modules that its exports use, except+ * the unions of literals used in one place, which are returned to be written out there.+ */+function selectDeclarations(project: Project) {+ const own = (project.children ?? []).filter((declaration) => declaration.name !== "<internal>");+ const imported = (project.children ?? [])+ .filter((declaration) => declaration.name === "<internal>")+ .flatMap((internal) => internal.children ?? [])+ .filter((declaration) => !declaration.sources?.some((source) => source.fileName.includes("node_modules/")));++ const uses = new Map<string, number>();+ for (const name of own.flatMap(referencedNames)) {+ uses.set(name, (uses.get(name) ?? 0) + 1);+ }++ const inlined = new Map([ ...own, ...imported ]+ .filter((declaration) => isLiteralUnion(declaration) && uses.get(declaration.name) === 1)+ .map((declaration) => [ declaration.name, declaration ]));+ return {+ declarations: [ ...own, ...imported.filter((declaration) => uses.has(declaration.name)) ]+ .filter((declaration) => !inlined.has(declaration.name)),+ inlined+ };+}++/** Whether a declaration is a type alias for a union of literals whose values have no comments. */+function isLiteralUnion(declaration: Declaration) {+ const type = declaration.type;+ return declaration.kind === KIND.typeAlias && type?.type === "union" && !type.elementSummaries+ && type.types.every((member) => member.type === "literal");+}+function orderDeclarations(declarations: Declaration[], root: string | undefined) {const byName = new Map(declarations.map((declaration) => [ declaration.name, declaration ]));const ordered = new Set<Declaration>();@@ -80,6 +159,9 @@ function orderDeclarations(declarations: Declaration[], root: string | undefinedreturn [ ...ordered ];}+/** Keys whose references a page does not show: comments, and the links between related types. */+const UNSHOWN_KEYS = new Set([ "comment", "extendedTypes", "extendedBy", "implementedTypes", "implementedBy", "inheritedFrom" ]);+/** The names of the types a declaration refers to, in the order they appear in it. */function referencedNames(declaration: Declaration) {const names: string[] = [];@@ -94,7 +176,7 @@ function referencedNames(declaration: Declaration) {names.push(node.name);}for (const [ key, child ] of Object.entries(node)) {- if (key !== "comment") {+ if (!UNSHOWN_KEYS.has(key)) {visit(child);}}@@ -104,14 +186,20 @@ function referencedNames(declaration: Declaration) {return names;}-function renderDeclaration(declaration: Declaration) {- const blocks = [ `## ${code(declaration.name)}` ];+function renderDeclaration(declaration: Declaration, heading: string) {+ const blocks = [ `${heading} ${code(declaration.name)}` ];if (declaration.comment) {blocks.push(renderComment(declaration.comment));}if (declaration.kind === KIND.typeAlias) {- blocks.push(fence(`type ${declaration.name} = ${typeToString(declaration.type)}`));+ const type = declaration.type;+ blocks.push(type?.type === "union" && type.elementSummaries+ ? table([ "Value", "Description" ], type.types.map((value, index) => [+ code(typeToString(value)),+ oneLine(partsToMarkdown(type.elementSummaries?.[index] ?? []))+ ]))+ : fence(`type ${declaration.name} = ${typeToString(type)}`));return blocks;}@@ -138,7 +226,15 @@ function renderDeclaration(declaration: Declaration) {}function propertyDetails(property: Declaration) {- return details(typeToString(property.type ?? property.getSignature?.type), property.comment);+ const type = typeToString(property.type ?? property.getSignature?.type);+ return details(type, [ property.comment, ...inlinedComments(property) ]);+}++/** The comments of the aliases a member's types write out, which their names no longer point to. */+function inlinedComments(member: Declaration) {+ return [ ...new Set(referencedNames(member)) ]+ .map((name) => inlinedAliases.get(name)?.comment)+ .filter((comment) => !!comment);}/**@@ -158,12 +254,13 @@ function methodDetails(method: Declaration) {if (signature.comment) {blocks.push(renderComment(signature.comment));}+ blocks.push(...inlinedComments(method).map(renderComment));const parameters = signature.parameters ?? [];if (parameters.some((parameter) => parameter.comment)) {blocks.push(table([ "Parameter", "Description" ], parameters.map((parameter) => [parameter.flags.isOptional ? `${code(parameter.name)}<br>*optional*` : code(parameter.name),- details(typeToString(parameter.type), parameter.comment)+ details(typeToString(parameter.type), [ parameter.comment ])])));}@@ -194,13 +291,19 @@ function blockTag(comment: Comment | undefined, tag: string) {/** Comment text as Markdown; a `{@link}` becomes its target's name as code. */function partsToMarkdown(parts: JSONOutput.CommentDisplayPart[]) {- return parts.map((part) => part.kind === "inline-tag" ? code(part.text) : part.text).join("").trim();+ return parts.map((part) => part.kind === "inline-tag" ? code(part.text) : part.text).join("")+ .replaceAll("\r\n", "\n")+ .trim();}-/** A table cell holding a type, with the description on the line below. */-function details(type: string, comment: Comment | undefined) {- const description = comment ? partsToMarkdown(comment.summary).replace(/\s*\n\s*/g, " ") : "";- return [ code(type), description ].filter(Boolean).join("<br>");+/** A table cell holding a type, with each description on a line below. */+function details(type: string, comments: (Comment | undefined)[]) {+ const descriptions = comments.map((comment) => comment ? oneLine(partsToMarkdown(comment.summary)) : "");+ return [ code(type), ...descriptions ].filter(Boolean).join("<br>");+}++function oneLine(text: string) {+ return text.replace(/\s*\n\s*/g, " ");}function signatureToString(signature: Signature) {@@ -226,6 +329,10 @@ function typeToString(type: SomeType | undefined): string {case "intrinsic":return type.name;case "reference": {+ const alias = !type.typeArguments && inlinedAliases.get(type.name);+ if (alias) {+ return typeToString(alias.type);+ }const args = type.typeArguments?.map(typeToString).join(", ");return args ? `${type.name}<${args}>` : type.name;}@@ -288,6 +395,9 @@ function reflectionToString(declaration: Declaration) {/** A type as an operand of `[]`, `&` or a type operator, in parentheses when it needs them. */function wrap(type: SomeType | undefined) {const text = typeToString(type);+ if (type?.type === "reference" && !type.typeArguments && inlinedAliases.has(type.name)) {+ type = inlinedAliases.get(type.name)?.type;+ }const needsParentheses = type?.type === "union" || type?.type === "intersection"|| (type?.type === "reflection" && !!type.declaration.signatures?.length);return needsParentheses ? `(${text})` : text;diff --git a/pnpm-lock.yaml b/pnpm-lock.yamlindex c3eb365052..2fb44ed00e 100644--- a/pnpm-lock.yaml+++ b/pnpm-lock.yaml@@ -558,6 +558,9 @@ importers:typedoc:specifier: 0.28.20version: 0.28.20([email protected])+ typedoc-plugin-missing-exports:+ specifier: 4.1.4+ version: 4.1.4([email protected]([email protected]))apps/icon-pack-builder:dependencies: