session #

createAnalysisSession returns a persistent analysis handle backed by a TypeScript LanguageService, for re-analyzing the same files as they change (the Vite plugin, watchers, editor tools). It reuses parsed ASTs, svelte2tsx output, and the dependency graph across queries. To analyze once, use the one-shot analyze or analyzeFromFiles (see JS API), which wrap single-use sessions. The full types are in session.ts.

Construction
#

import {createAnalysisSession, createSourceOptions} from 'svelte-docinfo'; const session = createAnalysisSession({ sourceOptions: createSourceOptions(process.cwd()), // Optional: session-default ImportResolver (or a bare resolve function). // Defaults to TypeScript module resolution with your tsconfig. // resolveImport: myResolver, // Optional (default true): also ingest the in-project files your inputs // import that you didn't supply, as non-emitting context. // contextClosure: true, // Optional: a tsconfig path relative to the project root, or false to // analyze without one. Default: 'tsconfig.json'. // tsconfig: 'tsconfig.lib.json', // Optional: the program's root files, in place of the tsconfig's. // rootFileNames: declarationFileRoots, // from 'svelte-docinfo/typescript-program.js' // Optional: logger for session-level messages. // log: console, });

AnalysisSessionOptions requires complete ModuleSourceOptions; build them with createSourceOptions, which merges your overrides with DEFAULT_SOURCE_OPTIONS. The session applies no further defaults.

The tsconfig is parsed once, at construction, so a later edit to it needs a new session. The tsconfig, compilerOptions, and rootFileNames options work as source files describes.

Lifecycle
#

The session owns a source set that you add to, update, and remove from:

MethodPurpose
setFile(file, opts?)Ingest one file's content; a no-op on cache hit. Returns SetFileResult
setFiles(files, opts?)Ingest a batch. Additive; never removes. Returns SetFilesResult with aggregate and per-file views
deleteFile(id)Remove a file from the session
has(id)Whether the given absolute path is currently owned
list()Snapshot of owned file IDs (insertion order), context files included
query(opts?)Analyze the owned set. Files outside sourcePaths, matching exclude, or held as context inform type resolution but emit no module. Returns AnalyzeResultJson
allIngestDiagnostics()Cumulative ingest-time diagnostics across every owned entry
getProgram()The underlying ts.Program, for your own checker work. It goes stale after any setFile, setFiles, or deleteFile that changes the session, so call it again afterward
dispose()Release resources and clear the owned set. Don't use the session afterward

Concurrency. The session isn't safe for overlapping calls, so serialize them. setFile, setFiles, and deleteFile are async (resolvers may await I/O); query is sync and reads the current owned set, so await pending ingests first.

Cache-hit semantics
#

Re-ingesting a file either reuses everything cached for it or recomputes everything. What counts as a hit depends on the mode:

  • lex+resolve (default): identical content and the same ImportResolver identity.
  • pre-resolved (caller supplies SourceFileInfo.dependencies): identical content and an element-wise equal array. A fresh array with the same elements hits, so [...filer.deps.keys()] per call works; any length, element, or order difference misses. The dependencies are trusted unchecked; see trust contract.

Switching a file between modes always misses.

Unresolved imports are the exception: a file's edges can change without re-ingesting it. When a setFile / setFiles call adds files, the session retries specifiers that previously resolved to null in lex+resolve files (with the same resolver), updates their edges, and clears stale resolver_failed diagnostics. It also calls the resolver's optional invalidate() before the next batch whenever files were added or removed since it last ran, so cached failed lookups don't stick. Pre-resolved files are untouched.

On a hit, SetFileResult.changed is false and the cached ingest diagnostics are returned without doing any work, unless the call changes the file's role (context), which reports changed: true since the emitted set moves.

ImportResolver and identity
#

ImportResolver is {resolve, identity, invalidate?}. identity is a stable opaque token (string or symbol) that keys the cache alongside content; invalidate() clears any cached failed lookups when files are added or removed.

import type {ImportResolver} from 'svelte-docinfo'; const myResolver: ImportResolver = { identity: 'vite-plugin-container', resolve: (specifier, fromFile) => { // return absolute path, or null for externals return null; }, };

identity is required because function references make poor cache keys: callers often wrap a resolver in a fresh closure per call (a common Vite/Rollup pattern), which would defeat caching. Reuse the same token as long as resolution behaves the same, and change it when it doesn't.

resolveImport also accepts a bare resolve function. The session-level one is wrapped once at construction, so its identity is stable; a bare function passed per call gets a fresh identity every call, and so never cache-hits.

When neither AnalysisSessionOptions.resolveImport nor a per-call SetFileOptions.resolveImport is supplied, the session builds a default from TypeScript module resolution and the merged compiler options on first use. It sees files that exist only in the session, even in directories absent from disk; a custom resolver must handle in-memory files itself to get dependency edges for them.

Context files
#

By default a session also ingests the in-project files its sources import that you didn't supply (transitively, skipping node_modules and dot-directories), so edits to them, like internal/ modules, stay live instead of being read from disk once. These context files emit no modules and add no edges. Their imports always go through lex+resolve, so when the closure finds files, even a fully pre-resolved session builds the default resolver (unless you supply resolveImport). analyze() turns the closure off; analyzeFromFiles keeps it on.

That includes source files, such as a component left out of package.json exports, or the rest of the project when you hand over one component. The type checker can only read a component through its transformed form, so without the ingest every type drawn from that component would be any. Such a file still emits no module until you supply it yourself. Each setFile/setFiles call sets the role of its files: they're inputs by default, so to forward an edit to a context file without turning it into a module, pass {context: true}. With the closure off, as in analyze(), pass every component the checker needs.

Diagnostics: ingest-time vs query-time
#

Diagnostic kinds have two lifecycles:

  • Ingest-time (transform_failed, source_map_failed, import_parse_failed, resolver_failed): returned from setFile / setFiles and kept with the file until it is re-ingested or deleted. A resolver_failed also clears once a later batch resolves its specifier.
  • Query-time (the rest): recomputed and returned by every query call.

query() does not include ingest diagnostics, and setFile / setFiles return only those for the files you passed (not context-closure files). allIngestDiagnostics() returns the complete set for every owned file:

const queryResult = session.query(); const fullDiagnostics = [ ...session.allIngestDiagnostics(), ...queryResult.diagnostics, ];

It's cheap, so long-lived consumers can republish the full picture every cycle without tracking per-batch returns. The Vite plugin does this on every dev re-analysis.

Discovery-time diagnostics (module_unreadable) are a third category. Sessions don't run discovery, so if you do, keep those diagnostics yourself and merge them into what you publish (see discoverSourceFiles).

Worked example: incremental loop
#

An LSP-style edit/query loop. Each setFile updates one file; query reanalyzes, reusing parsed ASTs and svelte2tsx output for unchanged files.

import {createAnalysisSession, createSourceOptions, hasErrors} from 'svelte-docinfo'; const session = createAnalysisSession({ sourceOptions: createSourceOptions(process.cwd()), }); // Initial population. await session.setFiles([ {id: '/abs/src/lib/a.ts', content: '...'}, {id: '/abs/src/lib/b.ts', content: '...'}, ]); // Edit: one file changed. const {changed} = await session.setFile({ id: '/abs/src/lib/a.ts', content: '... new content ...', }); if (changed) { const {modules, diagnostics: pass} = session.query(); const all = [...session.allIngestDiagnostics(), ...pass]; if (hasErrors(all)) { // surface to the editor } } // Tear down. session.dispose();

For HMR and file watchers, pass all changed files to one setFiles call rather than looping setFile: a batch resolves imports in parallel.