vscode: stub onWillSaveNotebookDocument (eclipse-theia#12614)

Contributed on behalf of STMicroelectronics

Signed-off-by: Remi Schnekenburger <[email protected]>

Author: rschnekenbu

packages/plugin-ext/src/plugin/plugin-context.ts

@@ -633,6 +633,9 @@ export function createAPIFactory(
             onDidChangeNotebookDocument(listener, thisArg?, disposables?) {
                 return Disposable.NULL;
             },
+            onWillSaveNotebookDocument(listener, thisArg?, disposables?) {
+                return Disposable.NULL;
+            },
             onDidSaveNotebookDocument(listener, thisArg?, disposables?) {
                 return Disposable.NULL;
             },

packages/plugin/src/theia.d.ts

@@ -7167,6 +7167,22 @@ export module '@theia/plugin' {
          */
         export const onDidChangeNotebookDocument: Event<NotebookDocumentChangeEvent>;
 
+        /**
+         * An event that is emitted when a {@link NotebookDocument notebook document} will be saved to disk.
+         *
+         * *Note 1:* Subscribers can delay saving by registering asynchronous work. For the sake of data integrity the editor
+         * might save without firing this event. For instance when shutting down with dirty files.
+         *
+         * *Note 2:* Subscribers are called sequentially and they can {@link NotebookDocumentWillSaveEvent.waitUntil delay} saving
+         * by registering asynchronous work. Protection against misbehaving listeners is implemented as such:
+         *  * there is an overall time budget that all listeners share and if that is exhausted no further listener is called
+         *  * listeners that take a long time or produce errors frequently will not be called anymore
+         *
+         * The current thresholds are 1.5 seconds as overall time budget and a listener can misbehave 3 times before being ignored.
+         * @stubbed
+         */
+        export const onWillSaveNotebookDocument: Event<NotebookDocumentWillSaveEvent>;
+
         /**
          * An event that is emitted when files are being created.
          *
@@ -14714,6 +14730,66 @@ export module '@theia/plugin' {
         readonly cellChanges: readonly NotebookDocumentCellChange[];
     }
 
+    /**
+     * An event that is fired when a {@link NotebookDocument notebook document} will be saved.
+     *
+     * To make modifications to the document before it is being saved, call the
+     * {@linkcode NotebookDocumentWillSaveEvent.waitUntil waitUntil}-function with a thenable
+     * that resolves to a {@link WorkspaceEdit workspace edit}.
+     */
+    export interface NotebookDocumentWillSaveEvent {
+        /**
+         * A cancellation token.
+         * @stubbed
+         */
+        readonly token: CancellationToken;
+
+        /**
+         * The {@link NotebookDocument notebook document} that will be saved.
+         * @stubbed
+         */
+        readonly notebook: NotebookDocument;
+
+        /**
+         * The reason why save was triggered.
+         * @stubbed
+         */
+        readonly reason: TextDocumentSaveReason;
+
+        /**
+         * Allows to pause the event loop and to apply {@link WorkspaceEdit workspace edit}.
+         * Edits of subsequent calls to this function will be applied in order. The
+         * edits will be *ignored* if concurrent modifications of the notebook document happened.
+         *
+         * *Note:* This function can only be called during event dispatch and not
+         * in an asynchronous manner:
+         *
+         * ```ts
+         * workspace.onWillSaveNotebookDocument(event => {
+         * // async, will *throw* an error
+         * setTimeout(() => event.waitUntil(promise));
+         *
+         * // sync, OK
+         * event.waitUntil(promise);
+         * })
+         * ```
+         *
+         * @param thenable A thenable that resolves to {@link WorkspaceEdit workspace edit}.
+         * @stubbed
+         */
+        waitUntil(thenable: Thenable<WorkspaceEdit>): void;
+
+        /**
+         * Allows to pause the event loop until the provided thenable resolved.
+         *
+         * *Note:* This function can only be called during event dispatch.
+         *
+         * @param thenable A thenable that delays saving.
+         * @stubbed
+         */
+        waitUntil(thenable: Thenable<any>): void;
+    }
+
     /**
      * The summary of a notebook cell execution.
      */