Class NotebookDocument

Represents a Jupyter notebook document in VS Code custom editor. Manages document lifecycle, content persistence, and edit tracking with support for both collaborative Datalayer notebooks and local file-based notebooks.

This class implements different behaviors based on the URI scheme:

datalayer:// URIs: Collaborative notebooks with real-time sync (read-only locally)
file:// URIs: Local notebooks with full edit tracking and persistence

Hierarchy (View Summary)

Disposable
- NotebookDocument

Implements

CustomDocument

Index

Properties

`Protected`_disposables

_disposables: Disposable[] = []

Collection of child disposables to clean up.

`Readonly`onDidChange

onDidChange: Event<{ label: string; redo(): void; undo(): void }> = ...

Event fired when an edit is made with undo/redo handlers. Enables VS Code's edit history functionality.

`Readonly`onDidChangeContent

onDidChangeContent: Event<
{ content?: Uint8Array; edits: readonly NotebookEdit[] },
> = ...

Event fired when the document content or edits change. Listeners receive the updated content and edit history.

`Readonly`onDidDispose

onDidDispose: Event<void> = ...

Event fired when the document is disposed. Used to clean up resources and listeners.

Accessors

documentData

get documentData(): Uint8Array
Gets the current notebook content as binary data.

Contains the serialized Jupyter notebook JSON structure. Updated automatically when edits are applied via makeEdit().

Returns Uint8Array
Binary representation of the notebook content.
- Defined in src/models/notebookDocument.ts:263

`Protected`isDisposed

get isDisposed(): boolean
Gets whether this instance has been disposed.

Returns boolean
True if disposed, false otherwise.
Inherited from Disposable.isDisposed
- Defined in src/utils/dispose.ts:72

uri

get uri(): Uri
Gets the notebook URI which determines collaborative vs local behavior.

The URI scheme determines the document's behavior:
- datalayer://: Collaborative notebook with real-time synchronization.
- file://: Local notebook with traditional file persistence.
- untitled:: New unsaved notebook.
Returns Uri
The VS Code URI for this notebook document.
Implementation of vscode.CustomDocument.uri
- Defined in src/models/notebookDocument.ts:251

Methods

`Protected`_register

_register<T extends Disposable>(value: T): T
Registers a disposable to be cleaned up when this instance is disposed.
Type Parameters
- T extends Disposable
Parameters
- value: T
  The disposable to register.
Returns T
The registered disposable.
Inherited from Disposable._register
- Defined in src/utils/dispose.ts:59

backup

backup(
destination: Uri,
cancellation: CancellationToken,
): Promise<CustomDocumentBackup>
Creates a backup of the notebook document.

Saves the current document state to a backup location and returns a backup descriptor for VS Code's backup/restore system.
Parameters
- destination: Uri
  URI for the backup location.
- cancellation: CancellationToken
  Cancellation token for the backup operation.
Returns Promise<CustomDocumentBackup>
Promise resolving to backup descriptor with cleanup function.
- Defined in src/models/notebookDocument.ts:418

dispose

dispose(): void
Disposes of the notebook document and releases all associated resources.

Fires disposal events and calls the parent disposable cleanup. Should be called when the document is no longer needed to prevent memory leaks.

Returns void
Implementation of vscode.CustomDocument.dispose
Overrides Disposable.dispose
- Defined in src/models/notebookDocument.ts:442

makeEdit

makeEdit(edit: NotebookEdit): void
Records an edit operation on the notebook document.

Behavior differs based on the URI scheme:
- Collaborative notebooks (datalayer://): Skips edit tracking since changes are managed by the Datalayer platform's real-time synchronization
- Local notebooks: Tracks edits for undo/redo functionality and dirty state
For local notebooks, updates the document content and fires change events with undo/redo handlers for VS Code's edit history.
Parameters
- edit: NotebookEdit
  The edit operation to apply.
Returns void
- Defined in src/models/notebookDocument.ts:281

revert

revert(_cancellation: CancellationToken): Promise<void>
Reverts the notebook document to its last saved state.

Reloads content from disk and restores the edit history to the last saved state. Fires document change events to notify the UI of the content restoration.
Parameters
- _cancellation: CancellationToken
  Cancellation token (currently unused).
Returns Promise<void>
- Defined in src/models/notebookDocument.ts:397

save

save(cancellation: CancellationToken): Promise<void>
Saves the notebook document to its original location.

Behavior differs based on the URI scheme:
- Collaborative notebooks (datalayer://): No-op since changes are automatically synchronized to the Datalayer platform.
- Local notebooks: Persists current content to the file system.
Parameters
- cancellation: CancellationToken
  Cancellation token for the save operation.
Returns Promise<void>
- Defined in src/models/notebookDocument.ts:336

saveAs

saveAs(targetResource: Uri, cancellation: CancellationToken): Promise<void>
Saves the notebook document to a specified location.

Handles different scenarios based on URI schemes and target locations:
- Collaborative to same location: No-op since changes are auto-synchronized.
- Collaborative to different location: Exports current content as local file.
- Local notebook: Retrieves fresh content from webview and saves to target.
Parameters
- targetResource: Uri
  URI where to save the notebook.
- cancellation: CancellationToken
  Cancellation token for the save operation.
Returns Promise<void>
- Defined in src/models/notebookDocument.ts:356

`Static`create

create(
    uri: Uri,
    backupId: string,
    delegate: NotebookDocumentDelegate,
): Promise<NotebookDocument>
Creates a new NotebookDocument instance from a URI.

Handles both regular notebook files and backup restoration scenarios. For backup restoration, the backupId parameter should contain the backup file URI. Supports both local file URIs and collaborative Datalayer URIs.
Parameters
- uri: Uri
  The notebook URI to open.
- backupId: string
  Optional backup ID for document restoration.
- delegate: NotebookDocumentDelegate
  Delegate for webview content retrieval and management.
Returns Promise<NotebookDocument>
Promise resolving to the created notebook document instance.
- Defined in src/models/notebookDocument.ts:87

Class NotebookDocument

Hierarchy (View Summary)

Implements

Index

Properties

Accessors

Methods

Properties

Protected_disposables

ReadonlyonDidChange

ReadonlyonDidChangeContent

ReadonlyonDidDispose

Accessors

documentData

Returns Uint8Array

ProtectedisDisposed

Returns boolean

uri

Returns Uri

Methods

Protected_register

Type Parameters

Parameters

Returns T

backup

Parameters

Returns Promise<CustomDocumentBackup>

dispose

Returns void

makeEdit

Parameters

Returns void

revert

Parameters

Returns Promise<void>

save

Parameters

Returns Promise<void>

saveAs

Parameters

Returns Promise<void>

Staticcreate

Parameters

Returns Promise<NotebookDocument>

Settings

On This Page

`Protected`_disposables

`Readonly`onDidChange

`Readonly`onDidChangeContent

`Readonly`onDidDispose

`Protected`isDisposed

`Protected`_register

`Static`create