JS API #
Three functions run the analysis, each returning the same AnalyzeResultJson. Pick by what your code already has:
| Function | Use when |
|---|---|
| analyzeFromFiles | you have a project on disk: it finds, reads, and analyzes the files in one call |
| analyze | you already hold the file contents, like a bundler plugin |
| createAnalysisSession | you re-analyze the same files as they change, like a watcher or editor tool |
The Vite plugin runs a session and the CLI runs analyzeFromFiles, so their options map
onto these.
analyzeFromFiles #
import {analyzeFromFiles} from 'svelte-docinfo';
const {modules, diagnostics} = await analyzeFromFiles({
projectRoot: process.cwd(),
// the rest are optional:
// discovery: 'auto' | 'exports' | 'glob',
// include: ['src/**/*.ts'],
// exclude: (defaults) => [...defaults, '**/*.gen.ts'],
// sourceOptions: {sourcePaths: ['src/lib']},
// tsconfig: 'tsconfig.json', // or false
// onDuplicates: 'diagnostic' | 'warn' | 'throw',
}); It discovers the files to document from package.json exports,
falling back to globs under src/lib, as source files explains
along with the options that change it. AnalyzeFromFilesOptions lists every option.
analyze #
import {analyze, createSourceOptions} from 'svelte-docinfo';
const {modules, diagnostics} = await analyze({
sourceFiles: [{id: '/project/src/lib/a.ts', content: '...'}],
sourceOptions: createSourceOptions('/project'),
}); Each SourceFileInfo is an absolute id and its content. Files outside the source paths (default src/lib) inform
types but emit no module. TS files you leave out are read from disk for their types, but a
component you leave out types as any, so pass every component the analyzed code
imports. build tools covers pre-resolved dependencies and custom import
resolution.
createAnalysisSession #
import {createAnalysisSession, createSourceOptions} from 'svelte-docinfo';
const session = createAnalysisSession({sourceOptions: createSourceOptions(process.cwd())});
await session.setFiles(files); // again on every change; unchanged files are cache hits
const {modules, diagnostics} = session.query();
// ingest diagnostics (like transform_failed) aren't in query(): see allIngestDiagnostics()
session.dispose(); A session keeps parsed files and svelte2tsx output between queries. See the session guide.
Results #
The functions return the result with every default filled in. Serialize it compactly with compactReplacer, as the CLI and Vite plugin do, and read compact JSON back with parseAnalyzeResult, which restores the defaults and validates the shape (see compact JSON):
import {compactReplacer, parseAnalyzeResult} from 'svelte-docinfo';
const json = JSON.stringify(result, compactReplacer);
const {modules, diagnostics} = parseAnalyzeResult(JSON.parse(json)); Problems in the analyzed code land in diagnostics; bad setup, like a missing
tsconfig or invalid options, throws. See diagnostics.
Imports #
The svelte-docinfo entry exports the common API and loads the TypeScript
compiler. Every module is also importable on its own as svelte-docinfo/<module>.js, and a few are light enough for a browser
bundle, for rendering data the analysis produced:
svelte-docinfo/types.js: the output schemas and parseModuleJson, the browser's stand-in forparseAnalyzeResult, which loads the compilersvelte-docinfo/declaration-helpers.js: typeJsonToTokens, generateImport, getDisplayNamesvelte-docinfo/diagnostics.js: parseDiagnostics and the read helperssvelte-docinfo/postprocess.js: resolveExportSurface
The API examples show more patterns, and the API reference lists everything.