@codingame/monaco-vscode-api 1.67.8 → 1.67.11

package/README.md

@@ -11,19 +11,61 @@ The VSCode api is composed of:
   - 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 (type hierarchy, call hierarchy...), you can use the `Services` namespace from `vscode/services`:
+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`. To do so, you can provide 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:
+```typescript
+import { StandaloneService, INotificationService } from 'vscode/services'
+
+class MyCustomNotificationService implements INotificationService { ... }
+StandaloneService.initialize({
+  get [INotificationService.toString()] () {
+    return new MyCustomNotificationService(...)
+  }
+})
+```
+
+Additionally, this library exposes 2 modules that include the vscode version of some services (with some glue to make it work with monaco):
+- Notification / Dialog: `vscode/service-override/messages`
+- Model / Editor: `vscode/service-override/modelEditor`
+
+Usage:
+```typescript
+import { StandaloneService } from 'vscode/services'
+import getModelEditorServiceOverride from 'vscode/service-override/modelEditor'
+import getMessageServiceOverride from 'vscode/service-override/messages'
+
+StandaloneServices.initialize({
+  ...getModelEditorServiceOverride((model, input, sideBySide) => {
+    // Open a new editor here and return it
+    // It will be called when for instance the user ctrl+click on an import
+  }),
+  ...getMessageServiceOverride(document.body)
+})
+```
+
+Note: using `vscode/service-override/modelEditor`, you'll be able to use the `vscode.workspace.registerTextDocumentContentProvider` api
 
 ### Installation
 
@@ -42,3 +84,26 @@ import * as vscode from 'vscode'
 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)