davidwindham.com
forked from
npmx.dev/npmx.dev
[READ-ONLY]
a fast, modern browser for the npm registry
1/**
2 * API Documentation Generator
3 *
4 * Generates TypeScript API documentation for npm packages.
5 * Uses esm.sh to resolve package types, which handles @types/* packages automatically.
6 * Uses @deno/doc (WASM build of deno_doc) for documentation generation.
7 *
8 * @module server/utils/docs
9 */
10
11import type { DocsGenerationResult } from '#shared/types/deno-doc'
12import { getDocNodes } from './client'
13import { buildSymbolLookup, flattenNamespaces, mergeOverloads } from './processing'
14import { renderDocNodes, renderToc } from './render'
15
16/**
17 * Generate API documentation for an npm package.
18 *
19 * Uses @deno/doc (WASM build of deno_doc) with esm.sh URLs to extract
20 * TypeScript type information and JSDoc comments, then renders them as HTML.
21 *
22 * @param packageName - The npm package name (e.g., "react", "@types/lodash")
23 * @param version - The package version (e.g., "19.2.3")
24 * @returns Generated documentation or null if no types are available
25 *
26 * @example
27 * ```ts
28 * const docs = await generateDocsWithDeno('ufo', '1.5.0')
29 * if (docs) {
30 * console.log(docs.html)
31 * }
32 * ```
33 */
34export async function generateDocsWithDeno(
35 packageName: string,
36 version: string,
37): Promise<DocsGenerationResult | null> {
38 // Get doc nodes using @deno/doc WASM
39 const result = await getDocNodes(packageName, version)
40
41 if (!result.nodes || result.nodes.length === 0) {
42 return null
43 }
44
45 // Process nodes: flatten namespaces, merge overloads, and build lookup
46 const flattenedNodes = flattenNamespaces(result.nodes)
47 const mergedSymbols = mergeOverloads(flattenedNodes)
48 const symbolLookup = buildSymbolLookup(flattenedNodes)
49
50 // Render HTML and TOC from pre-computed merged symbols
51 const html = await renderDocNodes(mergedSymbols, symbolLookup)
52 const toc = renderToc(mergedSymbols)
53
54 return { html, toc, nodes: flattenedNodes }
55}