@codingame/monaco-vscode-api 1.67.7 → 1.67.8-dev.0

package/README.md

@@ -1,20 +1,47 @@
 # @codingame/monaco-vscode-api · [![monthly downloads](https://img.shields.io/npm/dm/@codingame/monaco-vscode-api)](https://www.npmjs.com/package/@codingame/monaco-vscode-api) [![npm version](https://img.shields.io/npm/v/@codingame/monaco-vscode-api.svg?style=flat)](https://www.npmjs.com/package/@codingame/monaco-vscode-api) [![PRs welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/codingame/monaco-vscode-api/pulls)
 
-[NPM module](https://www.npmjs.com/) that respects the vscode api and redirect calls to monaco editor.
+[NPM module](https://www.npmjs.com/) that implements the VSCode api and redirects calls to Monaco editor.
 
-Some features not supported by monaco (type hierarchy, call hierarchy...) can be implemented by hands:
+The VSCode api is composed of:
+
+- A lot of classes and tools, which are exported the same way as in VSCode.
+- Some features that are supported by Monaco (Language feature registrations...) which are just forwarded to it (with some transformations)
+- Some features that are not supported by Monaco, and in such case:
+  - If it's an important feature: we let the user implement it as they wish.
+  - If it's some advanced features that don't make a lot of sense on Monaco (debug, tests...), it just throws an error when you try to use it.
+
+
+To implement by hands the optional features (file system, workspace folders, file...), you can use the `Services` namespace from `vscode/services`:
 ```typescript
 import { Services } from 'vscode/services'
 Services.install({
-   languages: {
-       registerTypeHierarchyProvider (documentSelector, provider) {
-           ...
-       }
-   }
+  workspace: {
+    workspaceFolders: ...,
+    createFileSystemWatcher (documentSelector, provider) {
+      ...
+    },
+    onDidSaveTextDocument
+  },
+  window: {
+    withProgress: ...
+  }
 })
 ```
 
+Also, monaco-editor use `standalone` versions or the vscode services, which are much simpler.
+
+You may want to provide your custom implementations of them, especially for: `textModelService`, `codeEditorService` and `notificationService`. Do do so, you can give them as the third parameter while creating your first editor.
+This library allows you to use a more convenient way using `StandaloneService.initialize`.
+Also, monaco-editor doesn't provide good type for them, so this library does it.
 
+Example:
+```
+import { StandaloneService, INotificationService } from 'vscode/services'
+
+StandaloneService.initialize({
+  textModelService: class MyCustomNotificationService implements INotificationService { ... }
+})
+```
 
 ### Installation
 
@@ -25,7 +52,7 @@ npm install -D @types/vscode
 
 ### Usage
 
-Just import it as if you were in a vscode extensions:
+Just import it as if you were in a vscode extension:
 
 ```typescript
 import * as vscode from 'vscode'
@@ -34,3 +61,25 @@ const range = new new vscode.Range(...)
 vscode.languages.registerCompletionItemProvider(...)
 ```
 
+### History
+
+This project was mainly created to make the implementation of [monaco-languageclient](https://github.com/TypeFox/monaco-languageclient) more robust and maintainable.
+
+monaco-languageclient uses [vscode-languageclient](https://www.npmjs.com/package/vscode-languageclient) which was built to run inside a VSCode extension. VSCode extensions communicate with the editor via an [API](https://www.npmjs.com/package/@types/vscode) they can import into their code.
+
+[The VSCode api](https://code.visualstudio.com/api/references/vscode-api) exports:
+- Some functions to interact with the IDE ([language feature registrations](https://code.visualstudio.com/api/references/vscode-api#languages), [command execution](https://code.visualstudio.com/api/references/vscode-api#commands)...)
+- A lot of utility classes (Range, Position...)
+
+The first implementations of [monaco-languageclient](https://github.com/TypeFox/monaco-languageclient) were using a fake VSCode api implementation. The vscode-languageclient was hacked so the VSCode<->protocol object converters were mainly bypassed, so the fake VSCode api was receiving [Language Server Protocol](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/) objects. Then the objects were transformed using custom transformers into [Monaco](https://www.npmjs.com/package/monaco-editor) objects to communicate with the monaco api.
+
+This approach has some disadvantages:
+- There is a lot of code to transform LSP objects into Monaco objects
+- It's hard to follow the updates of VSCode and the language server protocol
+- It doesn't behave exactly the same as in VSCode
+
+With this library, it would be possible to plug vscode-languageclient directly on top of monaco, monaco-languageclient still helps to do so by:
+- Adding some tweaks to the VSCode LanguageClient (Removing unsupported features...)
+- Providing a default implementations of the required fallback services (`vscode/services`)
+- Providing some examples on how to build an app using it
+- Adding some tools (DisposableCollection)