session.ts

Persistent analysis session — δ-shaped API over a ts.LanguageService.

Maps cleanly onto LSP and Vite/HMR consumers:

setFile / setFiles — additive ingest; transform-if-Svelte, lex specifiers, resolve imports (parallel), push content/virtual to the LS. Returns ingest-time diagnostics + a changed flag. Cache-hit no-op when content matches AND the mode-specific cache key matches (resolver identity for lex+resolve, dependency-snapshot equality for pre-resolved).
deleteFile — drop owned entry, evict from LS.
has / list — owned-set introspection (covers what consumers used to get from their own mirror caches).
query — sync analysis pass against the current owned set; returns analysis-pass diagnostics only (ingest diagnostics surface via the setFile/setFiles returns).
dispose — release LS resources.

The session owns a single Map<id, OwnedEntry> covering content, svelte virtuals, unfiltered deps, the mode-specific cache key (resolver identity or pre-resolved snapshot), and ingest-time diagnostics. svelte2tsx runs at most once per content change. Resolver work parallelizes across the batch in phase 2 of the three-phase setFiles pipeline; fully pre-resolved batches skip phase 2 (and the default-resolver construction) entirely.

@see analyze-core.ts for the two-phase analysis orchestrator @see dep-resolver.ts for the ImportResolver token contract

view source

Declarations
#

7 declarations

AnalysisSession
#

session.ts view source

also exported from index.ts

AnalysisSession import type {AnalysisSession} from 'svelte-docinfo/session.js';

Persistent analysis handle.

Concurrency: not safe across overlapping calls. Serialize externally (each caller awaits the previous setFile/setFiles before starting the next). The LS underneath is sync, but the resolver phase awaits I/O for async resolvers (Vite/Rollup), so the session does cross await boundaries.

Cache-hit semantics: per-entry, all-or-nothing. The implementation must not split the guarantee across separate caches (e.g. transform-cache hit + lex re-run). The match criterion is mode-discriminated:

lex+resolve mode: existing.content === incoming.content AND existing.resolverIdentity === incoming.resolverIdentity.
pre-resolved mode: existing.content === incoming.content AND arraysShallowEqual(existing.preResolvedDepsSnapshot, incoming.dependencies).

Mode flips (an entry previously ingested as lex+resolve now arrives with dependencies, or vice versa) always cache-miss.

Promise resolution: setFile / setFiles resolve only after the serial LS push (phase 3) completes for every file in the batch. Awaiting the returned promise is sufficient — no separate flush step.

`setFile`

Ingest one file's content into the session. Idempotent on cache hit.

type (file: SourceFileInfo, opts?: SetFileOptions | undefined): Promise<SetFileResult>

`file`

type SourceFileInfo

`opts?`

type SetFileOptions | undefined

optional

returns Promise<SetFileResult>

{changed, diagnostics} — changed: false indicates a cache-hit no-op where the cached ingest diagnostics are returned.

`setFiles`

Ingest a batch of files. Additive — never removes; use deleteFile for removal. Cache hits are folded into the result with changed: false.

type (files: readonly SourceFileInfo[], opts?: SetFileOptions | undefined): Promise<SetFilesResult>

`files`

type readonly SourceFileInfo[]

`opts?`

type SetFileOptions | undefined

optional

returns Promise<SetFilesResult>

`deleteFile`

Drop a file from the session and evict from the LS.

type (id: string): Promise<void>

`id`

type string

returns Promise<void>

`has`

Whether the given file ID is currently owned by the session.

type (id: string): boolean

`id`

type string

returns boolean

`list`

Snapshot of currently-owned file IDs (sort order is insertion order).

type (): readonly string[]

returns readonly string[]

`query`

Run a two-phase analysis pass against the current owned set.

type (opts?: QueryOptions | undefined): { modules: { path: string; declarations: ({ kind: "function"; parameters: { name: string; type: string; optional: boolean; rest: boolean; description?: string | undefined; defaultValue?: string | undefined; propertyDescriptions?: Record<...> | undefined; }[]; ... 17 more ...; sourceLine?: number | undefined; } | ... 7 more ... | { ...; })[]; ... 7 more ...; moduleComment?: string | undefined; }[]; diagnostics: ({ ...; } | ... 12 more ... | { ...; })[]; }

`opts?`

type QueryOptions | undefined

optional

returns

{ modules: { path: string; declarations: ({ kind: "function"; parameters: { name: string; type: string; optional: boolean; rest: boolean; description?: string | undefined; defaultValue?: string | undefined; propertyDescriptions?: Record<...> | undefined; }[]; ... 17 more ...; sourceLine?: number | undefined; } | ......

analyzed modules and analysis-pass diagnostics. Ingest diagnostics from prior setFile/setFiles calls are NOT included here — concat with those returns for the full picture.

throws

Error - if `onDuplicates: 'throw'` and duplicates exist

`allIngestDiagnostics`

Concatenated ingest-time diagnostics across every owned entry — the cumulative view of every setFile/setFiles return, kept current as entries are added/replaced/deleted.

Lets long-lived consumers (Vite plugin, LSP) publish the full ingest picture without tracking per-batch returns themselves. Cheap: walks the owned map.

type (): ({ symbolName: string; file: string; message: string; severity: "error" | "warning"; kind: "type_extraction_failed"; line?: number | undefined; column?: number | undefined; } | { functionName: string; ... 5 more ...; column?: number | undefined; } | ... 11 more ... | { ...; })[]

returns

({ symbolName: string; file: string; message: string; severity: "error" | "warning"; kind: "type_extraction_failed"; line?: number | undefined; column?: number | undefined; } | { functionName: string; ... 5 more ...; column?: number | undefined; } | ... 11 more ... | { ...; })[]

`dispose`

Release LS resources and clear the owned set. The session must not be used after disposal.

type (): void

returns void

AnalysisSessionOptions
#

session.ts view source

also exported from index.ts

AnalysisSessionOptions import type {AnalysisSessionOptions} from 'svelte-docinfo/session.js';

Options for createAnalysisSession.

documentRegistry flows through to the underlying LanguageService only. tsconfig and compilerOptions flow to both the LS *and* the lazy default ImportResolver (getDefaultResolver re-invokes loadTsconfig with them to produce a merged ts.CompilerOptions for module resolution). The two paths share the same merge semantics — user-supplied compilerOptions override parsed tsconfig keys, but never bypass the tsconfig.json file requirement.

projectRoot and virtualFiles from the LS options shape are excluded — the session derives projectRoot from sourceOptions and manages svelte2tsx virtuals internally per file.

inheritance

extends:

Omit<
	AnalysisLanguageServiceOptions,
	'projectRoot' | 'virtualFiles'
>

`sourceOptions`

Module source options for path extraction and source filtering.

Must be a fully-constructed ModuleSourceOptions — the session re-runs normalizeSourceOptions (idempotent) but does not apply any defaults. Pass through createSourceOptions(projectRoot, overrides?) to merge with DEFAULT_SOURCE_OPTIONS. (The Partial<SourceOptionsDefaults> ergonomic shape exists only on AnalyzeFromFilesOptions.sourceOptions, where the defaults merge happens inside analyzeFromFiles.)

type ModuleSourceOptions

`resolveImport?`

Session-default custom import resolver used when no per-call override is supplied — a bare ResolveImportFn or a token-paired ImportResolver (see ResolveImport). A bare function is normalized once at construction, so its synthesized identity is stable for the session's lifetime (cache reuse works). When omitted, the session lazily constructs the TS+tsconfig default on first use.

type ResolveImport

`log?`

Optional logger for session-level messages.

type AnalysisLog

createAnalysisSession
#

session.ts view source

also exported from index.ts

(options: AnalysisSessionOptions): AnalysisSession import {createAnalysisSession} from 'svelte-docinfo/session.js';

Create a persistent analysis session.

`options`

type AnalysisSessionOptions

returns

AnalysisSession

examples

Vite plugin integration

const session = createAnalysisSession({sourceOptions, resolveImport, log});
await session.setFiles(initialFiles);
const result = session.query();
// on watcher events:
await session.setFile({id, content});
await session.deleteFile(removedId);
const next = session.query();
// on shutdown:
session.dispose();

One-shot via the public wrapper

// Equivalent to `analyze(...)` — the wrapper goes through a session internally.
const session = createAnalysisSession({sourceOptions});
try {
await session.setFiles(sourceFiles);
return session.query({onDuplicates: 'throw'});
} finally {
session.dispose();
}

QueryOptions
#

session.ts view source

also exported from index.ts

QueryOptions import type {QueryOptions} from 'svelte-docinfo/session.js';

Per-call input to query.

`onDuplicates?`

Behavior when duplicate declaration names are found across modules.

type OnDuplicates

`log?`

Per-call logger override (defaults to the session-level logger).

type AnalysisLog

SetFileOptions
#

session.ts view source

also exported from index.ts

SetFileOptions import type {SetFileOptions} from 'svelte-docinfo/session.js';

Options for a per-file or per-batch resolver override.

Identity is required (not optional) — silently coalescing missing identities to a function reference would destroy cache reuse when the same logical resolver is wrapped in fresh closures across calls.

`resolveImport?`

Per-call override of the session-default resolver — a bare ResolveImportFn or a token-paired ImportResolver (see ResolveImport).

A bare function is normalized with a fresh identity on each call, so the files touched by this call re-resolve rather than cache-hitting — the expected behavior for a deliberate one-off override. To reuse the resolve cache across calls, pass an ImportResolver with a stable identity.

type ResolveImport

SetFileResult
#

session.ts view source

also exported from index.ts

SetFileResult import type {SetFileResult} from 'svelte-docinfo/session.js';

Result of setFile (single-file ingest).

changed is true when content or the mode-specific cache key (resolver identity for lex+resolve; dependency snapshot for pre-resolved) differed from the cached entry — the owned entry was rewritten. An LS push accompanies the entry write only when the file is TS/JS or has a successful Svelte virtual; CSS/JSON and transform-failed Svelte rewrite the entry without touching the LS. false indicates a cache-hit no-op: the cached ingestDiagnostics are returned but no work ran.

`changed`

Whether content or the mode-specific cache key differed from the cached entry.

type boolean

`diagnostics`

Ingest-time diagnostics for this file (durable on the entry).

type Array<Diagnostic>

SetFilesResult
#

session.ts view source

also exported from index.ts

SetFilesResult import type {SetFilesResult} from 'svelte-docinfo/session.js';

Result of setFiles (batch ingest).

Carries both aggregate views (changedIds, pre-flattened diagnostics) and a structured perFile map. HMR-style consumers want changedIds.size > 0 as the hot check; LSP-style consumers want per-file diagnostic association via perFile. Both are populated in the same single-pass walk over the batch — no extra cost.

`changedIds`

IDs whose content or mode-specific cache key differed from the cached entry — the subset of input file IDs that actually triggered work. Empty when every file was a cache-hit no-op.

type ReadonlySet<string>

`diagnostics`

Pre-flattened union of every file's ingestDiagnostics. Consumers can group by Diagnostic.file for per-file publish.

type Array<Diagnostic>

`perFile`

Per-file SetFileResult keyed by input file ID. Use this when the grouping Diagnostic.file would do isn't enough — e.g., LSP wanting to publish empty-diagnostic-list updates for files that ingested cleanly.

type ReadonlyMap<string, SetFileResult>