Optimize DefaultDocumentBuilder to Rebuild Linked Documents Only on Save (Performance Improvement for Large Workspaces)

[we-wake-act21]

Hi team,

I'm currently exploring ways to optimize the document build process for large workspaces and wanted to get some feedback or suggestions on the approach I’m taking.

Background

In Langium, the update method of the DefaultDocumentBuilder is triggered on every file content change.
By default, this method:

1. Calculates the linked documents associated with the changed LangiumDocument.
2. Passes those rebuilt documents through the LangiumDocument build lifecycle.

This behavior works fine for small workspaces. However, in large workspaces, every update triggers a costly rebuild process, as all linked documents go through the entire lifecycle even for minor changes.

Goal

I want to limit the rebuild of linked documents only when a document is saved, rather than on every content change.
This should significantly improve performance for large projects by reducing unnecessary rebuilds during typing or editing.

Current Approach

I’ve implemented a custom DocumentBuilder that modifies this behavior:

1. Override shouldRelink
   I modified shouldRelink to return false, ensuring that only the modified document is rebuilt during normal updates.

2. Listen to onDidSave events
   I’ve added an event listener on TextDocuments.onDidSave to trigger a full rebuild of linked documents when a document is saved:

    `services.workspace.TextDocuments.onDidSave(async _ => {
        const listener = this.onUpdate((changed, deleted) => {
            this.unlinkedDocuments(changed, deleted);
            listener.dispose();
        });
    });`
   

This ensures that:

• During normal edits (onUpdate), only the active document is rebuilt.
• On save, all linked documents are recalculated and passed through the build cycle.

Question

Is this a correct and recommended approach to achieve the desired optimization?
Or is there a more appropriate or built-in mechanism in Langium to control when linked documents are rebuilt (e.g., hooks, configuration options, or lifecycle events)?

I’d appreciate any insights on:

• Potential side effects or lifecycle implications of modifying shouldRelink.
• Whether this might cause inconsistencies in references or cross-file validations before save.
• Suggestions for a more idiomatic or maintainable approach.

[msujew]

Hey @we-wake-act21,

I modified shouldRelink to return false, ensuring that only the modified document is rebuilt during normal updates.

This is a perfect use case for overriding shouldRelink 👍

Whether this might cause inconsistencies in references or cross-file validations before save.

Well, the fact that the individual documents run out-of-sync can be seen as a inconsistency in itself. The main issue is that references from other documents (that are yet to be rebuilt) to the documents that already have been reparsed are completely stale. Meaning that you are targeting AST nodes that longer exist in the given document. This in itself isn't that problematic, you just need to be aware of it in case you run something like a cyclic dependency resolution between files where file A (rebuilt) targets B (not-yet-rebuilt), which again targets A (stale).

Suggestions for a more idiomatic or maintainable approach.

The framework offers a DocumentUpdateHandler with a didSaveDocument callback. That way you don't need to use the TextDocuments.onDidSave callback yourself. But those are completely interchangeable.

[we-wake-act21]

Hi @msujew,
Thanks a lot for the clarification and suggestions!
Based on your feedback, I’ve refined my initial approach to handle open and content-change events more explicitly.
Here’s what I’ve added:

  this.services.workspace.TextDocuments.onDidOpen(() => (this.isOpenOrUpdateOperation = true));
  this.services.workspace.TextDocuments.onDidChangeContent(() => (this.isOpenOrUpdateOperation = true));

And I’ve overridden the update and shouldRelink methods like this:

            override async update(changed: URI[], deleted: URI[], cancelToken = CancellationToken.None): Promise<void> {
                await super.update(changed, deleted, cancelToken);
                this.isOpenOrUpdateOperation = false;
            }
            
            protected override shouldRelink(document: LangiumDocument, changedUris: Set<string>): boolean {
                // During open/update operations, only relink the changed document
                if (this.isOpenOrUpdateOperation) {
                    return false;
                }
                return super.shouldRelink(document, changedUris);
            }

The idea is to ensure that during document open or content updates, only the changed document is rebuilt, while still allowing a full relink when a document is saved.

Does this seem like a valid or safe approach?
Are there any lifecycle or state-consistency concerns I should keep in mind with this pattern (e.g., around incremental parsing or cross-file dependency tracking)?