Improve workspace API for Notebook lifecycle to support (at least) saving events

[francisco-perez-sorrosal]

There are certain VSCode extensions that are devoted to allow users to define shell commands that are executed when files are saved. These include, among others, the following:

1. Run on Save
2. VSCode Run on Save
3. Save and Run

The extensions above rely on events currently available in the VSCode workspace API such as onWillSaveTextDocument and onDidSaveTextDocument.

In the recently added native support for notebooks in VSCode, it looks like notebooks are treated in a different way than text documents. The new workspace API has included some events specifically targeted to the notebook lifecycle, such as onDidOpenNotebookDocument and onDidCloseNotebookDocument. However, the API currently lacks other useful notebook lifecycle events such as onWillSaveNotebookDocument and onDidSaveNotebookDocument, so the extensions above can't work properly when save-related events happen on notebooks.

Would it be possible to extend the workspace API with at least onWillSaveNotebookDocument and onDidSaveNotebookDocument (and other useful methods for the notebook lifecycle if possible)?

Thanks in advance!!!

Note: I've just stumbled upon a similar request for those APIs in an issue related to LiveShare: #102503

[reggi]

Is there any workaround for this? I currently can easily see if a text file has been saved, but not have an event to tap into when a notebook has been saved. 😤😭

vscode.workspace.onDidSaveTextDocument(e => {
  vscode.window.showInformationMessage('did' + e.fileName)
})

vscode.workspace.onWillSaveTextDocument(e => {
    vscode.window.showInformationMessage('will' + e.document.fileName)
})

[rebornix]

Re #157844

[rebornix]

We introduced a proposed api onWillSaveNotebookDocument this month and plan to finalize the API in April. It would be great if you can give that a try and provide feedbacks. To test proposed api, you can follow https://code.visualstudio.com/api/advanced-topics/using-proposed-api . The shape of onWillSaveNotebookDocument is as below

	export interface NotebookDocumentWillSaveEvent {
		/**
		 * A cancellation token.
		 */
		readonly token: CancellationToken;

		/**
		 * The document that will be saved.
		 */
		readonly document: NotebookDocument;

		/**
		 * The reason why save was triggered.
		 */
		readonly reason: NotebookDocumentSaveReason;

		waitUntil(thenable: Thenable<readonly WorkspaceEdit[]>): void;

		waitUntil(thenable: Thenable<any>): void;
	}

Additional edits before save can be returned through waitUntil. cc @francisco-perez-sorrosal @reggi

[rebornix]

We already have onDidSaveNotebookDocument and we are finalizing onWillSaveNotebookDocument API in #157844, thus closing this issue.

[rebornix]

@francisco-perez-sorrosal @reggi you can follow #157844 on where we are with the onWillSaveNotebookDocument API, thanks!

[rebornix]

This can be now tested against VS Code Insiders using the latest vscode.d.ts file from main branch. A sample extension with following content can help you test this feature:

import * as vscode from 'vscode';

export function activate(context: vscode.ExtensionContext) {
	vscode.workspace.onWillSaveNotebookDocument(event => {
		if (event.reason === vscode.TextDocumentSaveReason.Manual) {
			event.waitUntil(new Promise((resolve) => {
				const notebookEdit = new vscode.NotebookEdit(new vscode.NotebookRange(0, 0), [new vscode.NotebookCellData(vscode.NotebookCellKind.Code, 'print(1)', 'python')]);
				const edit = new vscode.WorkspaceEdit();
				edit.set(event.notebook.uri, [notebookEdit]);
				resolve(edit);
			}));
		}
	});
}
export function deactivate() {}

With this extension

• enable notebook.formatOnSave.enabled
• try open an ipynb notebook, edit and save
• a new cell should be added at the top of the document