How to optimize or defer project-wide document invalidation to prevent update timeouts during update() method execution?

[we-wake-act21]

Context

I'm working on a language server implementation that uses a custom ProjectManager and a modified scope-provider. I have an update<T> method that handles document updates and uses a timeout mechanism to reject any update that takes more than 5000ms.

You can find the full update method here:
🔗 [ModelService.update](https://github.com/CrossBreezeNL/crossmodel/blob/ee40293212688b2eca96820dc68b0bc44ce63b34/extensions/crossmodel-lang/src/model-server/model-service.ts#L134)

In some scenarios—especially when editing a file like Project.json—this timeout is triggered even though the update would eventually succeed if given more time.

---

Root Cause Analysis

After some profiling, I narrowed the cause down to two main contributors:

1. Custom Scope Provider
   Initially contained inefficient recursive logic, which has since been optimized. This resolved a portion of the slowness.
2. Custom Project Manager
   Currently designed to invalidate all documents associated with a project when certain project files (like Project.json) are updated. This leads to a flood of rebuilds.

Here's a simplified version of the ProjectManager logic responsible for this:

protected async onBuildUpdate(changed: URI[], deleted: URI[]): Promise<void> {
   const affectedProjects: string[] = [];
   const changedProjects = getAndRemoveProjectUris(changed);
   for (const changedProject of changedProjects) {
      this.projectDependecies.clear();
      affectedProjects.push(...(await this.updateProject(changedProject)));
   }

   const deletedProjects = getAndRemoveProjectUris(deleted);
   for (const deletedProject of deletedProjects) {
      this.projectDependecies.clear();
      affectedProjects.push(...this.deleteProject(deletedProject));
   }

   if (affectedProjects.length > 0) {
      this.idToProject
         .values()
         .filter(info => affectedProjects.some(affected => info.dependencies.includes(affected)))
         .forEach(info => affectedProjects.push(info.id));

      this.langiumDocuments.all
         .filter(doc => affectedProjects.includes(this.getProjectIdByDocument(doc)))
         .forEach(doc => {
            this.langiumDocuments.invalidateDocument(doc.uri);
            changed.push(doc.uri);
         });
   }
}

This is invoked during documentManager.onUpdate() and has a major impact when a project file is edited, especially with ~108 files involved.

---

Problem

Since the invalidation and rebuilds are synchronous and aggressive, it frequently causes the update() method (linked above) to exceed its 5000ms timeout window, especially under large project loads.

---

My Questions

1. How can I refactor or defer the project-wide document invalidation to avoid blocking critical paths like update()?
2. Would it be viable to split project invalidation into smaller batches, or execute it after the document update completes?
3. Is there any supported or recommended mechanism in Langium (or LSP in general) to prioritize the document being actively updated before triggering a full rebuild?
4. Is there an approach to restructure onBuildUpdate to make it more incremental, lazy, or event-driven rather than invalidating all documents upfront?

---

Additional Notes

• Documents being invalidated aren't always semantically related to the one being updated.
• Sometimes, a small edit to a Project.json results in all 100+ documents being rebuilt, which is not ideal for responsiveness.
• Open to using async queues, prioritization, or staged rebuilds if that aligns with best practices.

---

Any advice or examples from similar setups (Langium or otherwise) would be greatly appreciated. Thanks in advance!

[msujew]

Hey @we-wake-act21,

How can I refactor or defer the project-wide document invalidation to avoid blocking critical paths like update()?

Large changes simply need more time to update the workspace state. This is kind of expected. Having a static timeout will always lead to issues somehow (i.e. multiple file changes at the same time on large workspaces). I would think you could dynamically adjust the timeout length based on the type of change (i.e. config change vs document change).

Would it be viable to split project invalidation into smaller batches, or execute it after the document update completes?

Maybe? But I wouldn't go down that route, see below for better recommendations.

Is there any supported or recommended mechanism in Langium (or LSP in general) to prioritize the document being actively updated before triggering a full rebuild?

Since the document in question usually relies on other files in the workspace to successfully go through the lifecycle stages (especially linking, which usually requires all other documents to have arrived at the ComputedScopes stage), it's not possible to send a document through the lifecycle on its own and arriving at a valid state - all the other changed documents also need to go through the lifecycle with them.

Is there an approach to restructure onBuildUpdate to make it more incremental, lazy, or event-driven rather than invalidating all documents upfront?

Yes, definitely. And this is likely where you would be able to get most of your performance benefits. Calling invalidateDocument really completely invalidates the document and forces the document builder to build the document from scratch. However, this isn't necessary:

1. I would assume that your project config settings has no influence on the parsing process (correct me, if I'm wrong). This means that discarding the AST & CST is likely unnecessary and will only lead to CPU cycles being wasted in order to reparse the whole AST.
2. Does your project config influence which elements are being exported from a document during the scope computation phase? If not, you can also skip that phase.

In case the project config neither changes how you parse your code nor how elements are being exported, you can simply adjust the isAffected method of the IndexManager to ensure that the documents affected by a config change are included in the build update of the DocumentBuilder. This is more efficient, as the documents aren't completely invalidated, but only re-linked and re-validated. I would assume that's all you need to do in case your document changes. This should probably save you 50% of work, more if you optimize your scoping.

Sometimes, a small edit to a Project.json results in all 100+ documents being rebuilt, which is not ideal for responsiveness.

Ideally, you would create a delta of the previous config vs the new config and perform less intrusive changes in case the delta doesn't affect the documents.