typescript-program.ts

TypeScript program and language-service creation.

Two entry points sharing host configuration (tsconfig parsing, virtual file plumbing, .svelte module resolution):

- createAnalysisProgram — one-shot ts.Program from a ts.CompilerHost. Lower-level escape hatch for power users + dependency resolution. Does not support incremental updates. - createAnalysisLanguageService — persistent ts.LanguageService with versioned IScriptSnapshots. Incremental: subsequent getProgram() calls reuse parsed ASTs and checker state for unchanged files. Used by createAnalysisSession (in session.ts).

@see typescript-exports.ts for analyzeExports, analyzeDeclaration @see typescript-extract-*.ts for the per-declaration extractors @see session.ts for createAnalysisSession, the high-level incremental API

Declarations
#

9 declarations

view source

AnalysisLanguageService
#

typescript-program.ts view source

AnalysisLanguageService

Persistent language-service handle that drives a ts.Program incrementally.

Owns the LS, document registry, and a Map<path, {content, version}> of "owned" files (real source files + virtuals pushed via setFile). Files not in the owned map are read from disk on demand by the LS host.

Each setFile(path, content) bumps the version when content differs from cache, so the next getProgram() reparses only the changed file. Calling getProgram() with no version bumps returns the same ts.Program as the previous call (reference-stable when nothing changed).

see also

  • ``createAnalysisSession`` in session.ts for the high-level API that wraps this with content cache + svelte virtual cache + analysis pipeline.

AnalysisLanguageServiceOptions
#

typescript-program.ts view source

AnalysisLanguageServiceOptions

inheritance

documentRegistry

Optional document registry for AST sharing across services.

Pass an explicit registry to share parsed source files when running multiple language services (e.g., LSP integration). Defaults to a fresh registry per service when omitted.

type ts.DocumentRegistry

AnalysisProgramOptions
#

typescript-program.ts view source

AnalysisProgramOptions

inheritance

virtualFiles

Virtual files to seed the program (maps virtual path to content).

Used to include svelte2tsx transformed outputs alongside real source files, enabling full type resolution for Svelte components via the checker.

On a LanguageService, virtuals can also be added/replaced/removed after construction via setFile / deleteFile.

type Map<string, string>

createAnalysisLanguageService
#

typescript-program.ts view source

(options?: AnalysisLanguageServiceOptions | undefined, log?: AnalysisLog | undefined): AnalysisLanguageService

Create a persistent language service for incremental analysis.

The LS owns parsed source ASTs and checker state across calls. Use the returned handle to push file-content updates (setFile / deleteFile) between analysis passes; subsequent getProgram() calls return either the same ts.Program (no changes since last call) or a fresh one that reuses unchanged files via the document registry.

options?

configuration options

type AnalysisLanguageServiceOptions | undefined
optional

log?

optional logger for info messages

type AnalysisLog | undefined
optional

returns

AnalysisLanguageService

the language service handle

throws

  • Error - if tsconfig.json is not found

examples

const ls = createAnalysisLanguageService({projectRoot}); ls.setFile('/abs/path/to/foo.ts', 'export const x = 1;'); const program = ls.getProgram(); // ... use program ... ls.setFile('/abs/path/to/foo.ts', 'export const x = 2;'); // bumps version const program2 = ls.getProgram(); // fresh program, foo.ts reparsed ls.dispose();

createAnalysisProgram
#

typescript-program.ts view source

(options?: AnalysisProgramOptions | undefined, log?: AnalysisLog | undefined): Program

Create TypeScript program for one-shot analysis.

Use createAnalysisLanguageService instead when you need to analyze the same source set multiple times — the LS path reuses parsed ASTs and checker state across calls.

options?

configuration options for program creation

type AnalysisProgramOptions | undefined
optional

log?

optional logger for info messages

type AnalysisLog | undefined
optional

returns

Program

the TypeScript program

throws

  • Error - if tsconfig.json is not found

examples

const program = createAnalysisProgram({projectRoot: process.cwd()});

createIsExternalFile
#

typescript-program.ts view source

(options: ModuleSourceOptions): IsExternalFile

Create an IsExternalFile predicate from ModuleSourceOptions.

A file is external if it is: - Outside the project root - Inside node_modules/ - A .d.ts declaration file outside the source root (catches framework-generated declarations like .svelte-kit/non-ambient.d.ts while keeping user .d.ts files in the source tree)

options

type ModuleSourceOptions

returns

IsExternalFile

IsExternalFile
#

typescript-program.ts view source

IsExternalFile

Predicate for determining whether a TypeScript source file is external to the project. Used by intersection type filtering to separate user-authored properties from library/framework properties.

Constructed from ModuleSourceOptions at analysis entry points — files under the source root (e.g., src/lib/) are internal, everything else is external.

loadTsconfig
#

typescript-program.ts view source

(options?: LoadTsconfigOptions | undefined, log?: AnalysisLog | undefined): { compilerOptions: CompilerOptions; rootFileNames: string[]; }

Load and parse tsconfig.json into compiler options + initial file list.

Shared by createAnalysisProgram and createAnalysisLanguageService so tsconfig-resolution behavior stays identical across the two paths. Also useful directly when a caller needs only CompilerOptions (e.g., import resolution via ts.resolveModuleName) without the cost of building a full ts.Program.

options?

type LoadTsconfigOptions | undefined
optional

log?

type AnalysisLog | undefined
optional

returns

{ compilerOptions: CompilerOptions; rootFileNames: string[]; }

throws

  • Error - if tsconfig.json (or the requested `tsconfigName`) is not found.

LoadTsconfigOptions
#

typescript-program.ts view source

LoadTsconfigOptions

Base configuration shared by every entry point in this module.

projectRoot + tsconfig + compilerOptions together drive loadTsconfig, which is also exposed publicly. AnalysisProgramOptions and AnalysisLanguageServiceOptions extend this with their own fields.

projectRoot

Absolute path to project root directory.

type string

tsconfig

Path to tsconfig.json (relative to projectRoot).

type string

compilerOptions

Compiler options merged on top of those parsed from tsconfig.json (per-key override; user-supplied keys win). Does not bypass the tsconfig.json file requirement — loadTsconfig still throws when no config file is found.

type ts.CompilerOptions

Depends on
#

Imported by
#