diff --git a/packages/langium/src/lsp/completion/completion-provider.ts b/packages/langium/src/lsp/completion/completion-provider.ts index f4cc9e1d6..07a34aaaf 100644 --- a/packages/langium/src/lsp/completion/completion-provider.ts +++ b/packages/langium/src/lsp/completion/completion-provider.ts @@ -107,6 +107,10 @@ export interface CompletionProvider { /** * Handle a completion request. * + * @param document - the document for which the completion request was triggered + * @param params - the completion parameters + * @param cancelToken - a token that can be used to cancel the 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 */ @@ -131,6 +135,7 @@ export class DefaultCompletionProvider implements CompletionProvider { protected readonly fuzzyMatcher: FuzzyMatcher; protected readonly grammarConfig: GrammarConfig; protected readonly astReflection: AstReflection; + readonly completionOptions?: CompletionProviderOptions; constructor(services: LangiumServices) { this.scopeProvider = services.references.ScopeProvider; @@ -145,7 +150,7 @@ export class DefaultCompletionProvider implements CompletionProvider { this.documentationProvider = services.documentation.DocumentationProvider; } - async getCompletion(document: LangiumDocument, params: CompletionParams): Promise { + async getCompletion(document: LangiumDocument, params: CompletionParams, _cancelToken?: CancellationToken): Promise { const items: CompletionItem[] = []; const contexts = this.buildContexts(document, params.position); diff --git a/packages/langium/src/lsp/definition-provider.ts b/packages/langium/src/lsp/definition-provider.ts index a9edab761..603bc0ffd 100644 --- a/packages/langium/src/lsp/definition-provider.ts +++ b/packages/langium/src/lsp/definition-provider.ts @@ -24,6 +24,11 @@ export interface DefinitionProvider { /** * Handle a go to definition request. * + * @param document The document in which the request was triggered. + * @param params The parameters of the request. + * @param cancelToken A cancellation token that can be used to cancel the request. + * @returns A list of location links to the definition(s) of the symbol at the given position. + * * @throws `OperationCancelled` if cancellation is detected during execution * @throws `ResponseError` if an error is detected that should be sent as response to the client */ @@ -48,7 +53,7 @@ export class DefaultDefinitionProvider implements DefinitionProvider { this.grammarConfig = services.parser.GrammarConfig; } - getDefinition(document: LangiumDocument, params: DefinitionParams): MaybePromise { + getDefinition(document: LangiumDocument, params: DefinitionParams, _cancelToken?: CancellationToken): MaybePromise { const rootNode = document.parseResult.value; if (rootNode.$cstNode) { const cst = rootNode.$cstNode; diff --git a/packages/langium/src/lsp/document-highlight-provider.ts b/packages/langium/src/lsp/document-highlight-provider.ts index 13859cd33..d666dfeb2 100644 --- a/packages/langium/src/lsp/document-highlight-provider.ts +++ b/packages/langium/src/lsp/document-highlight-provider.ts @@ -25,6 +25,10 @@ export interface DocumentHighlightProvider { /** * Handle a document highlight request. * + * @param document The document in which the request was received. + * @param params The parameters of the document highlight request. + * @param cancelToken A cancellation token that can be used to cancel the request. + * @returns The document highlights or `undefined` if no highlights are available. * @throws `OperationCancelled` if cancellation is detected during execution * @throws `ResponseError` if an error is detected that should be sent as response to the client */ @@ -42,7 +46,7 @@ export class DefaultDocumentHighlightProvider implements DocumentHighlightProvid this.grammarConfig = services.parser.GrammarConfig; } - getDocumentHighlight(document: LangiumDocument, params: DocumentHighlightParams): MaybePromise { + getDocumentHighlight(document: LangiumDocument, params: DocumentHighlightParams, _cancelToken?: CancellationToken): MaybePromise { const rootNode = document.parseResult.value.$cstNode; if (!rootNode) { return undefined; diff --git a/packages/langium/src/lsp/document-symbol-provider.ts b/packages/langium/src/lsp/document-symbol-provider.ts index 247a3f952..f84698e71 100644 --- a/packages/langium/src/lsp/document-symbol-provider.ts +++ b/packages/langium/src/lsp/document-symbol-provider.ts @@ -21,6 +21,11 @@ export interface DocumentSymbolProvider { /** * Handle a document symbols request. * + * @param document The document in the workspace. + * @param params The parameters of the request. + * @param cancelToken A cancellation token that migh be used to cancel the request. + * @returns The symbols for the given document. + * * @throws `OperationCancelled` if cancellation is detected during execution * @throws `ResponseError` if an error is detected that should be sent as response to the client */ @@ -37,7 +42,7 @@ export class DefaultDocumentSymbolProvider implements DocumentSymbolProvider { this.nodeKindProvider = services.shared.lsp.NodeKindProvider; } - getSymbols(document: LangiumDocument): MaybePromise { + getSymbols(document: LangiumDocument, _params: DocumentSymbolParams, _cancelToken?: CancellationToken): MaybePromise { return this.getSymbol(document, document.parseResult.value); } diff --git a/packages/langium/src/lsp/document-update-handler.ts b/packages/langium/src/lsp/document-update-handler.ts index fc951e431..e158cc9f0 100644 --- a/packages/langium/src/lsp/document-update-handler.ts +++ b/packages/langium/src/lsp/document-update-handler.ts @@ -21,23 +21,46 @@ import type { MaybePromise } from '../utils/promise-utils.js'; */ export interface DocumentUpdateHandler { + /** + * A document open event was triggered by the `TextDocuments` service. + * @param event The document change event. + */ didOpenDocument?(event: TextDocumentChangeEvent): void; /** * A content change event was triggered by the `TextDocuments` service. + * @param event The document change event. */ didChangeContent?(event: TextDocumentChangeEvent): void; + /** + * A document save event (initiated) was triggered by the `TextDocuments` service. + * @param event The document change event. + */ willSaveDocument?(event: TextDocumentWillSaveEvent): void; + /** + * A document save event (initiated) was triggered by the `TextDocuments` service. + * @param event The document change event. + * @returns An array of text edits which will be applied to the document before it is saved. + */ willSaveDocumentWaitUntil?(event: TextDocumentWillSaveEvent): MaybePromise; + /** + * A document save event (completed) was triggered by the `TextDocuments` service. + * @param event The document change event. + */ didSaveDocument?(event: TextDocumentChangeEvent): void; + /** + * A document close event was triggered by the `TextDocuments` service. + * @param event The document change event. + */ didCloseDocument?(event: TextDocumentChangeEvent): void; /** * The client detected changes to files and folders watched by the language client. + * @param params The files/folders change event. */ didChangeWatchedFiles?(params: DidChangeWatchedFilesParams): void; @@ -118,5 +141,4 @@ export class DefaultDocumentUpdateHandler implements DocumentUpdateHandler { .toArray(); this.fireDocumentUpdate(changedUris, deletedUris); } - } diff --git a/packages/langium/src/lsp/folding-range-provider.ts b/packages/langium/src/lsp/folding-range-provider.ts index 139bb46d3..5f916072c 100644 --- a/packages/langium/src/lsp/folding-range-provider.ts +++ b/packages/langium/src/lsp/folding-range-provider.ts @@ -21,6 +21,11 @@ export interface FoldingRangeProvider { /** * Handle a folding range request. * + * @param document The document to compute folding ranges for + * @param params The folding range parameters + * @param cancelToken A cancellation token that can be used to cancel the request + * @returns The computed folding ranges + * * @throws `OperationCancelled` if cancellation is detected during execution * @throws `ResponseError` if an error is detected that should be sent as response to the client */ @@ -37,7 +42,7 @@ export class DefaultFoldingRangeProvider implements FoldingRangeProvider { this.commentNames = services.parser.GrammarConfig.multilineCommentRules; } - getFoldingRanges(document: LangiumDocument): MaybePromise { + getFoldingRanges(document: LangiumDocument, _params: FoldingRangeParams, _cancelToken?: CancellationToken): MaybePromise { const foldings: FoldingRange[] = []; const acceptor: FoldingRangeAcceptor = (foldingRange) => foldings.push(foldingRange); this.collectFolding(document, acceptor); @@ -73,8 +78,7 @@ export class DefaultFoldingRangeProvider implements FoldingRangeProvider { * Returns true by default for all nodes. Returning false only ignores the specified node and not its content. * To ignore the content of a node use `shouldProcessContent`. */ - // eslint-disable-next-line @typescript-eslint/no-unused-vars - protected shouldProcess(node: AstNode): boolean { + protected shouldProcess(_node: AstNode): boolean { return true; } @@ -83,8 +87,7 @@ export class DefaultFoldingRangeProvider implements FoldingRangeProvider { * Returns true by default for all nodes. Returning false ignores _all_ content of this node, even transitive ones. * For more precise control over foldings use the `shouldProcess` method. */ - // eslint-disable-next-line @typescript-eslint/no-unused-vars - protected shouldProcessContent(node: AstNode): boolean { + protected shouldProcessContent(_node: AstNode): boolean { return true; } diff --git a/packages/langium/src/lsp/references-provider.ts b/packages/langium/src/lsp/references-provider.ts index 0e4ca3eef..19a91d36a 100644 --- a/packages/langium/src/lsp/references-provider.ts +++ b/packages/langium/src/lsp/references-provider.ts @@ -23,6 +23,11 @@ export interface ReferencesProvider { /** * Handle a find references request. * + * @param document The document in which to search for references. + * @param params The parameters of the find references request. + * @param cancelToken A cancellation token that can be used to cancel the request. + * @returns The locations of the references. + * * @throws `OperationCancelled` if cancellation is detected during execution * @throws `ResponseError` if an error is detected that should be sent as response to the client */ @@ -40,7 +45,7 @@ export class DefaultReferencesProvider implements ReferencesProvider { this.grammarConfig = services.parser.GrammarConfig; } - findReferences(document: LangiumDocument, params: ReferenceParams): MaybePromise { + findReferences(document: LangiumDocument, params: ReferenceParams, _cancelToken?: CancellationToken): MaybePromise { const rootNode = document.parseResult.value.$cstNode; if (!rootNode) { return []; diff --git a/packages/langium/src/lsp/rename-provider.ts b/packages/langium/src/lsp/rename-provider.ts index 1bb9b3f4e..54aa888fc 100644 --- a/packages/langium/src/lsp/rename-provider.ts +++ b/packages/langium/src/lsp/rename-provider.ts @@ -24,6 +24,11 @@ export interface RenameProvider { /** * Handle a rename request. * + * @param document The document in which the rename request was triggered. + * @param params The rename parameters. + * @param cancelToken A cancellation token that can be used to cancel the request. + * @returns A workspace edit that describes the changes to be applied to the workspace. + * * @throws `OperationCancelled` if cancellation is detected during execution * @throws `ResponseError` if an error is detected that should be sent as response to the client */ @@ -32,6 +37,11 @@ export interface RenameProvider { /** * Handle a prepare rename request. * + * @param document The document in which the prepare rename request was triggered. + * @param params The prepare rename parameters. + * @param cancelToken A cancellation token that can be used to cancel the request. + * @returns A range that describes the range of the symbol to be renamed. + * * @throws `OperationCancelled` if cancellation is detected during execution * @throws `ResponseError` if an error is detected that should be sent as response to the client */ @@ -50,7 +60,7 @@ export class DefaultRenameProvider implements RenameProvider { this.grammarConfig = services.parser.GrammarConfig; } - async rename(document: LangiumDocument, params: RenameParams): Promise { + async rename(document: LangiumDocument, params: RenameParams, _cancelToken?: CancellationToken): Promise { const changes: Record = {}; const rootNode = document.parseResult.value.$cstNode; if (!rootNode) return undefined; @@ -73,7 +83,7 @@ export class DefaultRenameProvider implements RenameProvider { return { changes }; } - prepareRename(document: LangiumDocument, params: TextDocumentPositionParams): MaybePromise { + prepareRename(document: LangiumDocument, params: TextDocumentPositionParams, _cancelToken?: CancellationToken): MaybePromise { return this.renameNodeRange(document, params.position); } diff --git a/packages/langium/src/lsp/workspace-symbol-provider.ts b/packages/langium/src/lsp/workspace-symbol-provider.ts index 742c65c04..01ca50b56 100644 --- a/packages/langium/src/lsp/workspace-symbol-provider.ts +++ b/packages/langium/src/lsp/workspace-symbol-provider.ts @@ -21,6 +21,10 @@ export interface WorkspaceSymbolProvider { /** * Handle a workspace symbols request. * + * @param params workspaces symbols request parameters + * @param cancelToken a cancellation token tha can be used to cancel the request + * @returns a list of workspace symbols + * * @throws `OperationCancelled` if cancellation is detected during execution * @throws `ResponseError` if an error is detected that should be sent as response to the client */ @@ -28,6 +32,10 @@ export interface WorkspaceSymbolProvider { /** * Handle a resolve request for a workspace symbol. * + * @param symbol the workspace symbol to resolve + * @param cancelToken a cancellation token tha can be used to cancel the request + * @returns the resolved workspace symbol + * * @throws `OperationCancelled` if cancellation is detected during execution * @throws `ResponseError` if an error is detected that should be sent as response to the client */ diff --git a/packages/langium/src/parser/async-parser.ts b/packages/langium/src/parser/async-parser.ts index 87bb8a464..494b41fbc 100644 --- a/packages/langium/src/parser/async-parser.ts +++ b/packages/langium/src/parser/async-parser.ts @@ -14,20 +14,28 @@ import { Deferred, OperationCancelled } from '../utils/promise-utils.js'; import { Emitter } from '../utils/event.js'; /** - * Async parser that allows to cancel the current parsing process. - * The sync parser implementation is blocking the event loop, which can become quite problematic for large files. + * Async parser that allows cancellation of the current parsing process. * - * Note that the default implementation is not actually async. It just wraps the sync parser in a promise. - * A real implementation would create worker threads or web workers to offload the parsing work. + * @remark The sync parser implementation is blocking the event loop, which can become quite problematic for large files. + * @remark The default implementation is not actually async. It just wraps the sync parser in a promise. A real implementation would create worker threads or web workers to offload the parsing work. */ export interface AsyncParser { + /** + * Parses the given text and returns the parse result. + * + * @param text The text to parse. + * @param cancelToken A cancellation token that can be used to cancel the parsing process. + * @returns A promise that resolves to the parse result. + * + * @throw `OperationCancelled` if the parsing process is cancelled. + */ parse(text: string, cancelToken: CancellationToken): Promise>; } /** - * Default implementation of the async parser. This implementation only wraps the sync parser in a promise. + * Default implementation of the async parser which simply wraps the sync parser in a promise. * - * A real implementation would create worker threads or web workers to offload the parsing work. + * @remark A real implementation would create worker threads or web workers to offload the parsing work. */ export class DefaultAsyncParser implements AsyncParser { @@ -37,7 +45,7 @@ export class DefaultAsyncParser implements AsyncParser { this.syncParser = services.parser.LangiumParser; } - parse(text: string): Promise> { + parse(text: string, _cancelToken: CancellationToken): Promise> { return Promise.resolve(this.syncParser.parse(text)); } } diff --git a/packages/langium/src/references/linker.ts b/packages/langium/src/references/linker.ts index 8ec2cf0db..d5cb303a5 100644 --- a/packages/langium/src/references/linker.ts +++ b/packages/langium/src/references/linker.ts @@ -27,6 +27,8 @@ export interface Linker { * * @param document A LangiumDocument that shall be linked. * @param cancelToken A token for cancelling the operation. + * + * @throws `OperationCancelled` if a cancellation event is detected */ link(document: LangiumDocument, cancelToken?: CancellationToken): Promise; diff --git a/packages/langium/src/serializer/json-serializer.ts b/packages/langium/src/serializer/json-serializer.ts index 00373bc95..4a92b4742 100644 --- a/packages/langium/src/serializer/json-serializer.ts +++ b/packages/langium/src/serializer/json-serializer.ts @@ -126,9 +126,10 @@ export class DefaultJsonSerializer implements JsonSerializer { this.commentProvider = services.documentation.CommentProvider; } - serialize(node: AstNode, options: JsonSerializeOptions = {}): string { + serialize(node: AstNode, options?: JsonSerializeOptions): string { + const serializeOptions = options ?? {}; const specificReplacer = options?.replacer; - const defaultReplacer = (key: string, value: unknown) => this.replacer(key, value, options); + const defaultReplacer = (key: string, value: unknown) => this.replacer(key, value, serializeOptions); const replacer = specificReplacer ? (key: string, value: unknown) => specificReplacer(key, value, defaultReplacer) : defaultReplacer; try { @@ -139,9 +140,10 @@ export class DefaultJsonSerializer implements JsonSerializer { } } - deserialize(content: string, options: JsonDeserializeOptions = {}): T { + deserialize(content: string, options?: JsonDeserializeOptions): T { + const deserializeOptions = options ?? {}; const root = JSON.parse(content); - this.linkNode(root, root, options); + this.linkNode(root, root, deserializeOptions); return root; } diff --git a/packages/langium/src/workspace/ast-descriptions.ts b/packages/langium/src/workspace/ast-descriptions.ts index 277238d11..46a3743d8 100644 --- a/packages/langium/src/workspace/ast-descriptions.ts +++ b/packages/langium/src/workspace/ast-descriptions.ts @@ -46,7 +46,8 @@ export class DefaultAstNodeDescriptionProvider implements AstNodeDescriptionProv this.nameProvider = services.references.NameProvider; } - createDescription(node: AstNode, name: string | undefined, document: LangiumDocument = getDocument(node)): AstNodeDescription { + createDescription(node: AstNode, name: string | undefined, document?: LangiumDocument): AstNodeDescription { + const doc = document ?? getDocument(node); name ??= this.nameProvider.getName(node); const path = this.astNodeLocator.getAstNodePath(node); if (!name) { @@ -62,7 +63,7 @@ export class DefaultAstNodeDescriptionProvider implements AstNodeDescriptionProv }, selectionSegment: toDocumentSegment(node.$cstNode), type: node.$type, - documentUri: document.uri, + documentUri: doc.uri, path }; } diff --git a/packages/langium/src/workspace/workspace-lock.ts b/packages/langium/src/workspace/workspace-lock.ts index 795de45c5..846d9722e 100644 --- a/packages/langium/src/workspace/workspace-lock.ts +++ b/packages/langium/src/workspace/workspace-lock.ts @@ -63,12 +63,12 @@ export class DefaultWorkspaceLock implements WorkspaceLock { return this.enqueue(this.readQueue, action); } - private enqueue(queue: LockEntry[], action: LockAction, cancellationToken?: CancellationToken): Promise { + private enqueue(queue: LockEntry[], action: LockAction, cancellationToken = CancellationToken.None): Promise { const deferred = new Deferred(); const entry: LockEntry = { action, deferred, - cancellationToken: cancellationToken ?? CancellationToken.None + cancellationToken }; queue.push(entry); this.performNextOperation(); diff --git a/packages/langium/src/workspace/workspace-manager.ts b/packages/langium/src/workspace/workspace-manager.ts index dcaedd528..c9619f61d 100644 --- a/packages/langium/src/workspace/workspace-manager.ts +++ b/packages/langium/src/workspace/workspace-manager.ts @@ -53,6 +53,9 @@ export interface WorkspaceManager { * each language file and stores it locally. * * @param folders The set of workspace folders to be indexed. + * @param cancelToken A cancellation token that can be used to cancel the operation. + * + * @throws OperationCancelled if a cancellation event has been detected */ initializeWorkspace(folders: WorkspaceFolder[], cancelToken?: CancellationToken): Promise;