Removed Response type, added service documentation

packages/langium/src/documents/document-builder.ts

@@ -19,20 +19,22 @@ import { AstNode } from '../syntax-tree';
 export interface DocumentBuilder {
     /**
      * Inserts the document into the index and rebuilds affected documents
+     *
      * @param document which should be built
      * @param cancelToken allows to cancel the current operation
-     * @throws `OperationCanceled` if a user action occurs during execution
+     * @throws `OperationCancelled` if cancellation is detected during execution
      */
     build(document: LangiumDocument, cancelToken?: CancellationToken): Promise<BuildResult>
     /**
      * This method is called when a document change is detected.
      * Implementation should updates the state of that `LangiumDocument` and make sure
      * that the index information of the affected documents are also updated.
+     *
      * @param uri of the document that was changed
      * @param cancelToken allows to cancel the current operation
      * @see IndexManager.update()
      * @see LangiumDocuments.invalidateDocument()
-     * @throws `OperationCanceled` if a user action occurs during execution
+     * @throws `OperationCancelled` if cancellation is detected during execution
      */
     documentChanged(uri: URI, cancelToken?: CancellationToken): Promise<void>;
 }

packages/langium/src/grammar/langium-grammar-code-actions.ts

@@ -9,12 +9,12 @@ import { CodeActionParams } from 'vscode-languageserver-protocol';
 import { Command, CodeAction } from 'vscode-languageserver-types';
 import { LangiumDocument } from '../documents/document';
 import { CodeActionProvider } from '../lsp/code-action';
-import { Response } from '../lsp/lsp-util';
+import { MaybePromise } from '../utils/promise-util';
 import { IssueCodes } from './langium-grammar-validator';
 
 export class LangiumGrammarCodeActionProvider implements CodeActionProvider {
 
-    getCodeActions(document: LangiumDocument, params: CodeActionParams): Response<Array<Command | CodeAction>> {
+    getCodeActions(document: LangiumDocument, params: CodeActionParams): MaybePromise<Array<Command | CodeAction>> {
         const result: CodeAction[] = [];
         for (const diagnostic of params.context.diagnostics) {
             const codeAction = this.createCodeAction(diagnostic, document);

packages/langium/src/lsp/code-action.ts

@@ -4,10 +4,16 @@
  * terms of the MIT License, which is available in the project root.
  ******************************************************************************/
 
-import { CancellationToken, CodeAction, CodeActionParams, Command,  } from 'vscode-languageserver';
+import { CancellationToken, CodeAction, CodeActionParams, Command  } from 'vscode-languageserver';
 import { LangiumDocument } from '../documents/document';
-import { Response } from './lsp-util';
+import { MaybePromise } from '../utils/promise-util';
 
 export interface CodeActionProvider {
-    getCodeActions(document: LangiumDocument, params: CodeActionParams, cancelToken?: CancellationToken): Response<Array<Command | CodeAction> | undefined>;
+    /**
+     * Handle a code action request.
+     *
+     * @throws `OperationCancelled` if cancellation is detected during execution
+     * @throws `ResponseError` if an error is detected that should be sent as response to the client
+     */
+    getCodeActions(document: LangiumDocument, params: CodeActionParams, cancelToken?: CancellationToken): MaybePromise<Array<Command | CodeAction> | undefined>;
 }

packages/langium/src/lsp/completion/completion-provider.ts

@@ -6,7 +6,7 @@
 
 import { CancellationToken, CompletionItem, CompletionItemKind, CompletionList, CompletionParams } from 'vscode-languageserver';
 import { TextDocument, TextEdit } from 'vscode-languageserver-textdocument';
-import { LangiumDocument } from '../..';
+import { LangiumDocument } from '../../documents/document';
 import * as ast from '../../grammar/generated/ast';
 import { getTypeNameAtElement } from '../../grammar/grammar-util';
 import { isNamed } from '../../references/naming';
@@ -15,15 +15,21 @@ import { LangiumServices } from '../../services';
 import { AstNode, CstNode } from '../../syntax-tree';
 import { getContainerOfType, isAstNode, findLeafNodeAtOffset } from '../../utils/ast-util';
 import { findRelevantNode, flatten } from '../../utils/cst-util';
+import { MaybePromise } from '../../utils/promise-util';
 import { stream } from '../../utils/stream';
-import { Response } from '../lsp-util';
 import { findFirstFeatures, findNextFeatures } from './follow-element-computation';
 import { RuleInterpreter } from './rule-interpreter';
 
 export type CompletionAcceptor = (value: string | AstNode | AstNodeDescription, item?: Partial<CompletionItem>) => void
 
 export interface CompletionProvider {
-    getCompletion(document: LangiumDocument, offset: number, params: CompletionParams, cancelToken?: CancellationToken): Response<CompletionList>
+    /**
+     * Handle a completion request.
+     *
+     * @throws `OperationCancelled` if cancellation is detected during execution
+     * @throws `ResponseError` if an error is detected that should be sent as response to the client
+     */
+    getCompletion(document: LangiumDocument, offset: number, params: CompletionParams, cancelToken?: CancellationToken): MaybePromise<CompletionList>
 }
 
 export class DefaultCompletionProvider {
@@ -38,7 +44,7 @@ export class DefaultCompletionProvider {
         this.grammar = services.Grammar;
     }
 
-    getCompletion(document: LangiumDocument, offset: number): Response<CompletionList> {
+    getCompletion(document: LangiumDocument, offset: number): MaybePromise<CompletionList> {
         const root = document.parseResult.value;
         const cst = root.$cstNode;
         const items: CompletionItem[] = [];

packages/langium/src/lsp/document-highlighter.ts

@@ -12,10 +12,16 @@ import { LangiumServices } from '../services';
 import { AstNode, CstNode, Reference } from '../syntax-tree';
 import { findLeafNodeAtOffset, findLocalReferences, getDocument } from '../utils/ast-util';
 import { toRange } from '../utils/cst-util';
-import { Response } from './lsp-util';
+import { MaybePromise } from '../utils/promise-util';
 
 export interface DocumentHighlighter {
-    findHighlights(document: LangiumDocument, params: DocumentHighlightParams, cancelToken?: CancellationToken): Response<DocumentHighlight[] | undefined>;
+    /**
+     * Handle a document highlight request.
+     *
+     * @throws `OperationCancelled` if cancellation is detected during execution
+     * @throws `ResponseError` if an error is detected that should be sent as response to the client
+     */
+    findHighlights(document: LangiumDocument, params: DocumentHighlightParams, cancelToken?: CancellationToken): MaybePromise<DocumentHighlight[] | undefined>;
 }
 
 export class DefaultDocumentHighlighter implements DocumentHighlighter {
@@ -27,7 +33,7 @@ export class DefaultDocumentHighlighter implements DocumentHighlighter {
         this.nameProvider = services.references.NameProvider;
     }
 
-    findHighlights(document: LangiumDocument, params: DocumentHighlightParams): Response<DocumentHighlight[] | undefined> {
+    findHighlights(document: LangiumDocument, params: DocumentHighlightParams): MaybePromise<DocumentHighlight[] | undefined> {
         const rootNode = document.parseResult.value.$cstNode;
         if (!rootNode) {
             return undefined;

packages/langium/src/lsp/document-symbol-provider.ts

@@ -10,10 +10,16 @@ import { NameProvider } from '../references/naming';
 import { LangiumServices } from '../services';
 import { AstNode } from '../syntax-tree';
 import { streamContents } from '../utils/ast-util';
-import { Response } from './lsp-util';
+import { MaybePromise } from '../utils/promise-util';
 
 export interface DocumentSymbolProvider {
-    getSymbols(document: LangiumDocument, params: DocumentSymbolParams, cancelToken?: CancellationToken): Response<DocumentSymbol[]>;
+    /**
+     * Handle a document symbols request.
+     *
+     * @throws `OperationCancelled` if cancellation is detected during execution
+     * @throws `ResponseError` if an error is detected that should be sent as response to the client
+     */
+    getSymbols(document: LangiumDocument, params: DocumentSymbolParams, cancelToken?: CancellationToken): MaybePromise<DocumentSymbol[]>;
 }
 
 export class DefaultDocumentSymbolProvider implements DocumentSymbolProvider {
@@ -24,7 +30,7 @@ export class DefaultDocumentSymbolProvider implements DocumentSymbolProvider {
         this.nameProvider = services.references.NameProvider;
     }
 
-    getSymbols(document: LangiumDocument): Response<DocumentSymbol[]> {
+    getSymbols(document: LangiumDocument): MaybePromise<DocumentSymbol[]> {
         return this.getSymbol(document, document.parseResult.value);
     }
 

packages/langium/src/lsp/folding-range-provider.ts

@@ -11,10 +11,16 @@ import { LangiumServices } from '../services';
 import { AstNode, CstNode } from '../syntax-tree';
 import { AstNodeContent, streamAllContents } from '../utils/ast-util';
 import { streamCst } from '../utils/cst-util';
-import { Response } from './lsp-util';
+import { MaybePromise } from '../utils/promise-util';
 
 export interface FoldingRangeProvider {
-    getFoldingRanges(document: LangiumDocument, params: FoldingRangeParams, cancelToken?: CancellationToken): Response<FoldingRange[]>;
+    /**
+     * Handle a folding range request.
+     *
+     * @throws `OperationCancelled` if cancellation is detected during execution
+     * @throws `ResponseError` if an error is detected that should be sent as response to the client
+     */
+    getFoldingRanges(document: LangiumDocument, params: FoldingRangeParams, cancelToken?: CancellationToken): MaybePromise<FoldingRange[]>;
 }
 
 export type FoldingRangeAcceptor = (foldingRange: FoldingRange) => void;
@@ -27,7 +33,7 @@ export class DefaultFoldingRangeProvider implements FoldingRangeProvider {
         this.commentNames = services.parser.GrammarConfig.multilineCommentRules;
     }
 
-    getFoldingRanges(document: LangiumDocument): Response<FoldingRange[]> {
+    getFoldingRanges(document: LangiumDocument): MaybePromise<FoldingRange[]> {
         const foldings: FoldingRange[] = [];
         const acceptor: FoldingRangeAcceptor = (foldingRange) => foldings.push(foldingRange);
         this.collectFolding(document, acceptor);

packages/langium/src/lsp/goto.ts

@@ -12,10 +12,16 @@ import { LangiumServices } from '../services';
 import { CstNode } from '../syntax-tree';
 import { findLeafNodeAtOffset, getDocument } from '../utils/ast-util';
 import { toRange } from '../utils/cst-util';
-import { Response } from './lsp-util';
+import { MaybePromise } from '../utils/promise-util';
 
 export interface GoToResolver {
-    goToDefinition(document: LangiumDocument, params: DefinitionParams, cancelToken?: CancellationToken): Response<LocationLink[] | undefined>;
+    /**
+     * Handle a go to definition request.
+     *
+     * @throws `OperationCancelled` if cancellation is detected during execution
+     * @throws `ResponseError` if an error is detected that should be sent as response to the client
+     */
+    goToDefinition(document: LangiumDocument, params: DefinitionParams, cancelToken?: CancellationToken): MaybePromise<LocationLink[] | undefined>;
 }
 
 export class DefaultGoToResolverProvider implements GoToResolver {
@@ -28,7 +34,7 @@ export class DefaultGoToResolverProvider implements GoToResolver {
         this.references = services.references.References;
     }
 
-    goToDefinition(document: LangiumDocument, params: DefinitionParams): Response<LocationLink[] | undefined> {
+    goToDefinition(document: LangiumDocument, params: DefinitionParams): MaybePromise<LocationLink[] | undefined> {
         const rootNode = document.parseResult.value;
         const targetCstNodes: Array<{ source: CstNode, target: CstNode, targetDocument: LangiumDocument }> = [];
         if (rootNode.$cstNode) {

packages/langium/src/lsp/hover-provider.ts

@@ -12,10 +12,16 @@ import { LangiumServices } from '../services';
 import { AstNode } from '../syntax-tree';
 import { findLeafNodeAtOffset } from '../utils/ast-util';
 import { findCommentNode } from '../utils/cst-util';
-import { Response } from './lsp-util';
+import { MaybePromise } from '../utils/promise-util';
 
 export interface HoverProvider {
-    getHoverContent(document: LangiumDocument, params: HoverParams, cancelToken?: CancellationToken): Response<Hover | undefined>;
+    /**
+     * Handle a hover request.
+     *
+     * @throws `OperationCancelled` if cancellation is detected during execution
+     * @throws `ResponseError` if an error is detected that should be sent as response to the client
+     */
+    getHoverContent(document: LangiumDocument, params: HoverParams, cancelToken?: CancellationToken): MaybePromise<Hover | undefined>;
 }
 
 export abstract class AstNodeHoverProvider implements HoverProvider {
@@ -26,7 +32,7 @@ export abstract class AstNodeHoverProvider implements HoverProvider {
         this.references = services.references.References;
     }
 
-    getHoverContent(document: LangiumDocument, params: HoverParams): Response<Hover | undefined> {
+    getHoverContent(document: LangiumDocument, params: HoverParams): MaybePromise<Hover | undefined> {
         const rootNode = document.parseResult?.value?.$cstNode;
         if (rootNode) {
             const offset = document.textDocument.offsetAt(params.position);
@@ -41,7 +47,7 @@ export abstract class AstNodeHoverProvider implements HoverProvider {
         return undefined;
     }
 
-    protected abstract getAstNodeHoverContent(node: AstNode): Response<Hover | undefined>;
+    protected abstract getAstNodeHoverContent(node: AstNode): MaybePromise<Hover | undefined>;
 
 }
 
@@ -55,7 +61,7 @@ export class MultilineCommentHoverProvider extends AstNodeHoverProvider {
         this.grammarConfig = services.parser.GrammarConfig;
     }
 
-    protected getAstNodeHoverContent(node: AstNode): Response<Hover | undefined> {
+    protected getAstNodeHoverContent(node: AstNode): MaybePromise<Hover | undefined> {
         const lastNode = findCommentNode(node.$cstNode, this.grammarConfig.multilineCommentRules);
         let content: string | undefined;
         if (lastNode) {

packages/langium/src/lsp/language-server.ts

@@ -12,7 +12,7 @@ import { TextDocument } from 'vscode-languageserver-textdocument';
 import { URI } from 'vscode-uri';
 import { LangiumDocument } from '../documents/document';
 import { LangiumServices } from '../services';
-import { OperationCanceled as OperationCancelled, startCancelableOperation } from '../utils/promise-util';
+import { OperationCancelled, startCancelableOperation } from '../utils/promise-util';
 
 export function startLanguageServer(services: LangiumServices): void {
     const connection = services.lsp.Connection;
@@ -208,7 +208,9 @@ function paramsDocument(params: { textDocument: TextDocumentIdentifier }, servic
 function responseError<E = void>(err: unknown): ResponseError<E> {
     if (err === OperationCancelled) {
         return new ResponseError(LSPErrorCodes.RequestCancelled, 'The request has been cancelled.');
-    } else {
-        throw err;
     }
+    if (err instanceof ResponseError) {
+        return err;
+    }
+    throw err;
 }

packages/langium/src/lsp/reference-finder.ts

@@ -13,10 +13,16 @@ import { LangiumServices } from '../services';
 import { AstNode, CstNode } from '../syntax-tree';
 import { findLeafNodeAtOffset, getDocument, isReference } from '../utils/ast-util';
 import { flatten, toRange } from '../utils/cst-util';
-import { Response } from './lsp-util';
+import { MaybePromise } from '../utils/promise-util';
 
 export interface ReferenceFinder {
-    findReferences(document: LangiumDocument, params: ReferenceParams, cancelToken?: CancellationToken): Response<Location[]>;
+    /**
+     * Handle a find references request.
+     *
+     * @throws `OperationCancelled` if cancellation is detected during execution
+     * @throws `ResponseError` if an error is detected that should be sent as response to the client
+     */
+    findReferences(document: LangiumDocument, params: ReferenceParams, cancelToken?: CancellationToken): MaybePromise<Location[]>;
 }
 
 export class DefaultReferenceFinder implements ReferenceFinder {
@@ -28,7 +34,7 @@ export class DefaultReferenceFinder implements ReferenceFinder {
         this.references = services.references.References;
     }
 
-    findReferences(document: LangiumDocument, params: ReferenceParams): Response<Location[]> {
+    findReferences(document: LangiumDocument, params: ReferenceParams): MaybePromise<Location[]> {
         const rootNode = document.parseResult.value.$cstNode;
         if (!rootNode) {
             return [];

packages/langium/src/lsp/rename-refactoring.ts

@@ -13,12 +13,25 @@ import { LangiumServices } from '../services';
 import { CstNode } from '../syntax-tree';
 import { findLeafNodeAtOffset } from '../utils/ast-util';
 import { toRange } from '../utils/cst-util';
-import { AsyncResponse, Response } from './lsp-util';
+import { MaybePromise } from '../utils/promise-util';
 import { ReferenceFinder } from './reference-finder';
 
 export interface RenameHandler {
-    renameElement(document: LangiumDocument, params: RenameParams, cancelToken?: CancellationToken): Response<WorkspaceEdit | undefined>;
-    prepareRename(document: LangiumDocument, params: TextDocumentPositionParams, cancelToken?: CancellationToken): Response<Range | undefined>;
+    /**
+     * Handle a rename request.
+     *
+     * @throws `OperationCancelled` if cancellation is detected during execution
+     * @throws `ResponseError` if an error is detected that should be sent as response to the client
+     */
+    renameElement(document: LangiumDocument, params: RenameParams, cancelToken?: CancellationToken): MaybePromise<WorkspaceEdit | undefined>;
+
+    /**
+     * Handle a prepare rename request.
+     *
+     * @throws `OperationCancelled` if cancellation is detected during execution
+     * @throws `ResponseError` if an error is detected that should be sent as response to the client
+     */
+    prepareRename(document: LangiumDocument, params: TextDocumentPositionParams, cancelToken?: CancellationToken): MaybePromise<Range | undefined>;
 }
 
 export class DefaultRenameHandler implements RenameHandler {
@@ -33,7 +46,7 @@ export class DefaultRenameHandler implements RenameHandler {
         this.nameProvider = services.references.NameProvider;
     }
 
-    async renameElement(document: LangiumDocument, params: RenameParams): AsyncResponse<WorkspaceEdit | undefined> {
+    async renameElement(document: LangiumDocument, params: RenameParams): Promise<WorkspaceEdit | undefined> {
         const changes: Record<string, TextEdit[]> = {};
         const references = await this.referenceFinder.findReferences(document, { ...params, context: { includeDeclaration: true } });
         if (!Array.isArray(references)) {
@@ -50,7 +63,7 @@ export class DefaultRenameHandler implements RenameHandler {
         return { changes };
     }
 
-    prepareRename(document: LangiumDocument, params: TextDocumentPositionParams): Response<Range | undefined> {
+    prepareRename(document: LangiumDocument, params: TextDocumentPositionParams): MaybePromise<Range | undefined> {
         return this.renameNodeRange(document, params.position);
     }