Class DefaultDocumentBuilder

Shared-service for building and updating LangiumDocuments.

Implements

DocumentBuilder

Constructors

constructor

new DefaultDocumentBuilder(
services: LangiumSharedCoreServices,
): DefaultDocumentBuilder
Parameters
- services: LangiumSharedCoreServices
Returns DefaultDocumentBuilder
- Defined in packages/langium/src/workspace/document-builder.ts:162

Properties

`Protected` `Readonly`buildPhaseListeners

buildPhaseListeners: MultiMap<DocumentState, DocumentBuildListener> = ...

`Protected` `Readonly`buildState

buildState: Map<string, DocumentBuildState> = ...

`Protected`currentState

currentState: DocumentState = DocumentState.Changed

`Protected` `Readonly`documentBuildWaiters

documentBuildWaiters: Map<string, Deferred<void>> = ...

`Protected` `Readonly`documentPhaseListeners

documentPhaseListeners: MultiMap<DocumentState, DocumentPhaseListener> = ...

`Protected` `Readonly`fileSystemProvider

fileSystemProvider: FileSystemProvider

`Protected` `Readonly`indexManager

indexManager: IndexManager

`Protected` `Readonly`langiumDocumentFactory

langiumDocumentFactory: LangiumDocumentFactory

`Protected` `Readonly`langiumDocuments

langiumDocuments: LangiumDocuments

`Protected` `Readonly`serviceRegistry

serviceRegistry: ServiceRegistry

`Protected` `Readonly`textDocuments

textDocuments: undefined | TextDocumentProvider

updateBuildOptions

updateBuildOptions: BuildOptions = ...

The options used for rebuilding documents after an update.

`Protected` `Readonly`updateListeners

updateListeners: DocumentUpdateListener[] = []

`Protected` `Readonly`workspaceManager

workspaceManager: () => WorkspaceManager

Methods

build

build<T extends AstNode>(
    documents: LangiumDocument<T>[],
    options?: BuildOptions,
    cancelToken?: Cancellation.CancellationToken,
): Promise<void>
Execute all necessary build steps for the given documents.
Type Parameters
- T extends AstNode
Parameters
- documents: LangiumDocument<T>[]
  Set of documents to be built.
- options: BuildOptions = {}
  Options for the document builder.
- cancelToken: Cancellation.CancellationToken = CancellationToken.None
  Indicates when to cancel the current operation.
Returns Promise<void>
Throws
OperationCanceled if a user action occurs during execution
Implementation of DocumentBuilder.build
- Defined in packages/langium/src/workspace/document-builder.ts:172

`Protected`buildDocuments

buildDocuments(
    documents: LangiumDocument<AstNode>[],
    options: BuildOptions,
    cancelToken: Cancellation.CancellationToken,
): Promise<void>
Build the given documents by stepping through all build phases. If a document's state indicates that a certain build phase is already done, the phase is skipped for that document.
Parameters
- documents: LangiumDocument<AstNode>[]
  The documents to build.
- options: BuildOptions
  the BuildOptions to use.
- cancelToken: Cancellation.CancellationToken
  A cancellation token that can be used to cancel the build.
Returns Promise<void>
A promise that resolves when the build is done.
- Defined in packages/langium/src/workspace/document-builder.ts:401

`Protected`emitUpdate

emitUpdate(changed: URI[], deleted: URI[]): Promise<void>
Parameters
- changed: URI[]
- deleted: URI[]
Returns Promise<void>
- Defined in packages/langium/src/workspace/document-builder.ts:288

`Protected`findChangedUris

findChangedUris(changed: URI): Promise<URI[]>
Parameters
- changed: URI
Returns Promise<URI[]>
- Defined in packages/langium/src/workspace/document-builder.ts:265

onBuildPhase

onBuildPhase(
targetState: DocumentState,
callback: DocumentBuildListener,
): Disposable
Notify the given callback when a set of documents has been built reaching the specified target state.
Parameters
- targetState: DocumentState
- callback: DocumentBuildListener
Returns Disposable
Implementation of DocumentBuilder.onBuildPhase
- Defined in packages/langium/src/workspace/document-builder.ts:493

onDocumentPhase

onDocumentPhase(
targetState: DocumentState,
callback: DocumentPhaseListener,
): Disposable
Notify the specified callback when a document has been built reaching the specified target state. Unlike onBuildPhase the listener is called for every single document.

There are two main advantages compared to onBuildPhase:
1. If the build is cancelled, onDocumentPhase will still fire for documents that have reached a specific state. Meanwhile, onBuildPhase won't fire for that state.
2. The DocumentBuilder ensures that all DocumentPhaseListener instances are called for a built document. Even if the build is cancelled before those listeners were called.
Parameters
- targetState: DocumentState
- callback: DocumentPhaseListener
Returns Disposable
Implementation of DocumentBuilder.onDocumentPhase
- Defined in packages/langium/src/workspace/document-builder.ts:500

onUpdate

onUpdate(callback: DocumentUpdateListener): Disposable
Notify the given callback when a document update was triggered, but before any document is rebuilt. Listeners to this event should not perform any long-running task.
Parameters
- callback: DocumentUpdateListener
Returns Disposable
Implementation of DocumentBuilder.onUpdate
- Defined in packages/langium/src/workspace/document-builder.ts:336

`Protected`prepareBuild

prepareBuild(documents: LangiumDocument<AstNode>[], options: BuildOptions): void
Runs prior to beginning the build process to update the DocumentBuildState for each document
Parameters
- documents: LangiumDocument<AstNode>[]
  collection of documents to be built
- options: BuildOptions
  the BuildOptions to use
Returns void
- Defined in packages/langium/src/workspace/document-builder.ts:447

resetToState

resetToState<T extends AstNode>(
document: LangiumDocument<T>,
state: DocumentState,
): void
Reset the state of a document to the specified state, removing any derived data as needed.
Type Parameters
- T extends AstNode
Parameters
- document: LangiumDocument<T>
  The document to reset.
- state: DocumentState
  The state to reset the document to.
Returns void
Implementation of DocumentBuilder.resetToState
- Defined in packages/langium/src/workspace/document-builder.ts:346

`Protected`runCancelable

runCancelable(
    documents: LangiumDocument<AstNode>[],
    targetState: DocumentState,
    cancelToken: Cancellation.CancellationToken,
    callback: (document: LangiumDocument) => unknown,
): Promise<void>
Runs a cancelable operation on a set of documents to bring them to a specified DocumentState.
Parameters
- documents: LangiumDocument<AstNode>[]
  The array of documents to process.
- targetState: DocumentState
  The target DocumentState to bring the documents to.
- cancelToken: Cancellation.CancellationToken
  A token that can be used to cancel the operation.
- callback: (document: LangiumDocument) => unknown
  A function to be called for each document.
Returns Promise<void>
A promise that resolves when all documents have been processed or the operation is canceled.

Throws
Will throw OperationCancelled if the operation is canceled via a CancellationToken.
- Defined in packages/langium/src/workspace/document-builder.ts:474

`Protected`shouldLink

shouldLink(document: LangiumDocument): boolean
Determine whether the given document should be linked during a build. The default implementation checks the eagerLinking property of the build options. If it's set to true or undefined, the document is included in the linking phase. This also affects the references indexing phase, which depends on eager linking.
Parameters
- document: LangiumDocument
Returns boolean
- Defined in packages/langium/src/workspace/document-builder.ts:582

`Protected`shouldRelink

shouldRelink(document: LangiumDocument, changedUris: Set<string>): boolean
Check whether the given document should be relinked after changes were found in the given URIs.
Parameters
- document: LangiumDocument
- changedUris: Set<string>
Returns boolean
- Defined in packages/langium/src/workspace/document-builder.ts:327

`Protected`shouldValidate

shouldValidate(document: LangiumDocument): boolean
Determine whether the given document should be validated during a build. The default implementation checks the validation property of the build options. If it's set to true or a ValidationOptions object, the document is included in the validation phase.
Parameters
- document: LangiumDocument
Returns boolean
- Defined in packages/langium/src/workspace/document-builder.ts:591

`Protected`sortDocuments

sortDocuments(documents: LangiumDocument<AstNode>[]): LangiumDocument<AstNode>[]
Sort the given documents by priority. By default, documents with an open text document are prioritized. This is useful to ensure that visible documents show their diagnostics before all other documents.

This improves the responsiveness in large workspaces as users usually don't care about diagnostics in files that are currently not opened in the editor.
Parameters
- documents: LangiumDocument<AstNode>[]
Returns LangiumDocument<AstNode>[]
- Defined in packages/langium/src/workspace/document-builder.ts:299

update

update(
    changed: URI[],
    deleted: URI[],
    cancelToken?: Cancellation.CancellationToken,
): Promise<void>
This method is called when a document change is detected. It updates the state of all affected documents, including those with references to the changed ones, so they are rebuilt.
Parameters
- changed: URI[]
  URIs of changed or created documents
- deleted: URI[]
  URIs of deleted documents
- cancelToken: Cancellation.CancellationToken = CancellationToken.None
  allows to cancel the current operation
Returns Promise<void>
Throws
OperationCancelled if cancellation is detected during execution
Implementation of DocumentBuilder.update
- Defined in packages/langium/src/workspace/document-builder.ts:213

`Protected`validate

validate(
document: LangiumDocument,
cancelToken: Cancellation.CancellationToken,
): Promise<void>
Run validation checks on the given document and store the resulting diagnostics in the document. If the document already contains diagnostics, the new ones are added to the list.
Parameters
- document: LangiumDocument
- cancelToken: Cancellation.CancellationToken
Returns Promise<void>
- Defined in packages/langium/src/workspace/document-builder.ts:599

waitUntil

waitUntil(
state: DocumentState,
cancelToken?: Cancellation.CancellationToken,
): Promise<void>
Wait until the workspace has reached the specified state for all documents.
Parameters
- state: DocumentState
  The desired state. The promise won't resolve until all documents have reached this state
- OptionalcancelToken: Cancellation.CancellationToken
  Optionally allows to cancel the wait operation, disposing any listeners in the process
Returns Promise<void>
Throws
OperationCancelled if cancellation has been requested before the state has been reached
Implementation of DocumentBuilder.waitUntil
- Defined in packages/langium/src/workspace/document-builder.ts:507
waitUntil(
    state: DocumentState,
    uri?: URI,
    cancelToken?: Cancellation.CancellationToken,
): Promise<undefined | URI>
Wait until the document specified by the uri has reached the specified state.
Parameters
- state: DocumentState
  The desired state. The promise won't resolve until the document has reached this state.
- Optionaluri: URI
  The specified URI that points to the document. If the URI does not exist, the promise will resolve once the workspace has reached the specified state.
- OptionalcancelToken: Cancellation.CancellationToken
  Optionally allows to cancel the wait operation, disposing any listeners in the process.
Returns Promise<undefined | URI>
The URI of the document that has reached the desired state, or undefined if the document does not exist.

Throws
OperationCancelled if cancellation has been requested before the state has been reached
Implementation of DocumentBuilder.waitUntil
- Defined in packages/langium/src/workspace/document-builder.ts:508

Class DefaultDocumentBuilder

Implements

Index

Constructors

Properties

Methods

Constructors

constructor

Parameters

Returns DefaultDocumentBuilder

Properties

Protected ReadonlybuildPhaseListeners

Protected ReadonlybuildState

ProtectedcurrentState

Protected ReadonlydocumentBuildWaiters

Protected ReadonlydocumentPhaseListeners

Protected ReadonlyfileSystemProvider

Protected ReadonlyindexManager

Protected ReadonlylangiumDocumentFactory

Protected ReadonlylangiumDocuments

Protected ReadonlyserviceRegistry

Protected ReadonlytextDocuments

updateBuildOptions

Protected ReadonlyupdateListeners

Protected ReadonlyworkspaceManager

Methods

build

Type Parameters

Parameters

Returns Promise<void>

Throws

ProtectedbuildDocuments

Parameters

Returns Promise<void>

ProtectedemitUpdate

Parameters

Returns Promise<void>

ProtectedfindChangedUris

Parameters

Returns Promise<URI[]>

ProtectedgetBuildOptions

Parameters

Returns BuildOptions

ProtectednotifyBuildPhase

Parameters

Returns Promise<void>

ProtectednotifyDocumentPhase

Parameters

Returns Promise<void>

onBuildPhase

Parameters

Returns Disposable

onDocumentPhase

Parameters

Returns Disposable

onUpdate

Parameters

Returns Disposable

ProtectedprepareBuild

Parameters

Returns void

resetToState

Type Parameters

Parameters

Returns void

ProtectedrunCancelable

Parameters

Returns Promise<void>

Throws

ProtectedshouldLink

Parameters

Returns boolean

ProtectedshouldRelink

Parameters

Returns boolean

ProtectedshouldValidate

Parameters

Returns boolean

ProtectedsortDocuments

Parameters

`Protected` `Readonly`buildPhaseListeners

`Protected` `Readonly`buildState

`Protected`currentState

`Protected` `Readonly`documentBuildWaiters

`Protected` `Readonly`documentPhaseListeners

`Protected` `Readonly`fileSystemProvider

`Protected` `Readonly`indexManager

`Protected` `Readonly`langiumDocumentFactory

`Protected` `Readonly`langiumDocuments

`Protected` `Readonly`serviceRegistry

`Protected` `Readonly`textDocuments

`Protected` `Readonly`updateListeners

`Protected` `Readonly`workspaceManager

`Protected`buildDocuments

`Protected`emitUpdate

`Protected`findChangedUris

`Protected`getBuildOptions

`Protected`notifyBuildPhase

`Protected`notifyDocumentPhase

`Protected`prepareBuild

`Protected`runCancelable

`Protected`shouldLink

`Protected`shouldRelink

`Protected`shouldValidate

`Protected`sortDocuments

`Protected`validate