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

view source

Declarations
#

9 declarations

AnalysisLanguageService
#

typescript-program.ts view source

AnalysisLanguageService import type {AnalysisLanguageService} from 'svelte-docinfo/typescript-program.js';

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.

getProgram

Get the current ts.Program.

Returns the same reference as the previous call when no setFile / deleteFile invalidated state in between. Returns a fresh ts.Program (sharing parsed ASTs for unchanged files via the document registry) when versions changed.

type (): Program

returns Program

throws

  • Error - if the underlying LS returned undefined (should not happen

setFile

Set or replace a file's content (real path or virtual path).

  • New file: added to the owned map with version 1.
  • Existing file with identical content: no-op (version unchanged).
  • Existing file with new content: version bumped.

type (path: string, content: string): boolean

path

type string

content

type string
returns boolean

true when the file was added or its version bumped, false on no-op.

deleteFile

Remove a file from the owned set.

type (path: string): boolean

path

type string
returns boolean

true when the file was tracked, false when it was unknown.

hasFile

Whether the given path is currently tracked.

type (path: string): boolean

path

type string
returns boolean

dispose

Release LS resources.

Calls ts.LanguageService.dispose() and clears the owned map. The service must not be used after disposal.

type (): void

returns void

AnalysisLanguageServiceOptions
#

typescript-program.ts view source

AnalysisLanguageServiceOptions import type {AnalysisLanguageServiceOptions} from 'svelte-docinfo/typescript-program.js';

inheritance

extends: AnalysisProgramOptions

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 import type {AnalysisProgramOptions} from 'svelte-docinfo/typescript-program.js';

inheritance

extends: LoadTsconfigOptions

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 import {createAnalysisLanguageService} from 'svelte-docinfo/typescript-program.js';

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 import {createAnalysisProgram} from 'svelte-docinfo/typescript-program.js';

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 import {createIsExternalFile} from 'svelte-docinfo/typescript-program.js';

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 import type {IsExternalFile} from 'svelte-docinfo/typescript-program.js';

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.

(call)

type (sourceFile: SourceFile): boolean

sourceFile

type SourceFile
returns boolean

loadTsconfig
#

typescript-program.ts view source

(options?: LoadTsconfigOptions | undefined, log?: AnalysisLog | undefined): { compilerOptions: CompilerOptions; rootFileNames: string[]; } import {loadTsconfig} from 'svelte-docinfo/typescript-program.js';

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 import type {LoadTsconfigOptions} from 'svelte-docinfo/typescript-program.js';

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

default process.cwd()

tsconfig?

Path to tsconfig.json (relative to projectRoot).

type string

default 'tsconfig.json'

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
#