@jupyter/docprovider 4.3.0 → 4.4.0-beta.0

package/lib/awareness.d.ts

@@ -1,7 +1,7 @@
-import { User } from '@jupyterlab/services';
-import { IDisposable } from '@lumino/disposable';
+import { WebsocketProvider as YWebsocketProvider } from 'y-websocket';
 import { IAwareness } from '@jupyter/ydoc';
-import { WebsocketProvider } from 'y-websocket';
+import { User } from '@jupyterlab/services';
+import { IAwarenessProvider } from './tokens';
 export interface IContent {
     type: string;
     body: string;
@@ -12,7 +12,7 @@ export interface IContent {
  * We specify custom messages that the server can interpret. For reference please look in yjs_ws_server.
  *
  */
-export declare class WebSocketAwarenessProvider extends WebsocketProvider implements IDisposable {
+export declare class WebSocketAwarenessProvider extends YWebsocketProvider implements IAwarenessProvider {
     /**
      * Construct a new WebSocketAwarenessProvider
      *
@@ -22,9 +22,9 @@ export declare class WebSocketAwarenessProvider extends WebsocketProvider implem
     get isDisposed(): boolean;
     dispose(): void;
     private _onUserChanged;
+    readonly awareness: IAwareness;
     private _isDisposed;
     private _user;
-    private _awareness;
 }
 /**
  * A namespace for WebSocketAwarenessProvider statics.

package/lib/awareness.js

@@ -1,15 +1,15 @@
-/* -----------------------------------------------------------------------------
-| Copyright (c) Jupyter Development Team.
-| Distributed under the terms of the Modified BSD License.
-|----------------------------------------------------------------------------*/
-import { WebsocketProvider } from 'y-websocket';
+/*
+ * Copyright (c) Jupyter Development Team.
+ * Distributed under the terms of the Modified BSD License.
+ */
+import { WebsocketProvider as YWebsocketProvider } from 'y-websocket';
 /**
  * A class to provide Yjs synchronization over WebSocket.
  *
  * We specify custom messages that the server can interpret. For reference please look in yjs_ws_server.
  *
  */
-export class WebSocketAwarenessProvider extends WebsocketProvider {
+export class WebSocketAwarenessProvider extends YWebsocketProvider {
     /**
      * Construct a new WebSocketAwarenessProvider
      *
@@ -20,7 +20,7 @@ export class WebSocketAwarenessProvider extends WebsocketProvider {
             awareness: options.awareness
         });
         this._isDisposed = false;
-        this._awareness = options.awareness;
+        this.awareness = options.awareness;
         this._user = options.user;
         this._user.ready
             .then(() => this._onUserChanged(this._user))
@@ -39,6 +39,6 @@ export class WebSocketAwarenessProvider extends WebsocketProvider {
         this.destroy();
     }
     _onUserChanged(user) {
-        this._awareness.setLocalStateField('user', user.identity);
+        this.awareness.setLocalStateField('user', user.identity);
     }
 }

package/lib/tokens.d.ts

@@ -1,3 +1,7 @@
+import { TranslationBundle } from '@jupyterlab/translation';
+import { ServerConnection, User, Contents } from '@jupyterlab/services';
+import { DocumentChange, YDocument, IAwareness } from '@jupyter/ydoc';
+import { IDocumentProvider } from '@jupyter/collaborative-drive';
 import { Token } from '@lumino/coreutils';
 import { IDisposable } from '@lumino/disposable';
 import { ISignal } from '@lumino/signaling';
@@ -101,6 +105,119 @@ export interface IForkManager extends IDisposable {
  * Token providing a fork manager instance.
  */
 export declare const IForkManagerToken: Token<IForkManager>;
+/**
+ * A factory for creating document providers.
+ */
+export interface IDocumentProviderFactory {
+    /**
+     * Create a new document provider.
+     *
+     * @param options - The instantiation options for a document provider.
+     * @returns The document provider.
+     */
+    create(options: IDocumentProviderFactory.IOptions): IDocumentProvider & IForkProvider;
+}
+/**
+ * A namespace for IDocumentProviderFactory.
+ */
+export declare namespace IDocumentProviderFactory {
+    /**
+     * The instantiation options for a document provider.
+     */
+    interface IOptions {
+        /**
+         * The server URL
+         */
+        url?: string;
+        /**
+         * The document file path
+         */
+        path: string;
+        /**
+         * Content type
+         */
+        contentType: string;
+        /**
+         * The source format
+         */
+        format: string;
+        /**
+         * The shared model
+         */
+        model: YDocument<DocumentChange>;
+        /**
+         * The user data
+         */
+        user: User.IManager;
+        /**
+         * The jupyterlab translator
+         */
+        translator: TranslationBundle;
+        /**
+         * The server settings.
+         */
+        serverSettings?: ServerConnection.ISettings;
+        /**
+         * The drive to use for loading and saving document content.
+         */
+        drive: Contents.IDrive;
+    }
+}
+/**
+ * Token providing a document provider factory instance.
+ */
+export declare const IDocumentProviderFactory: Token<IDocumentProviderFactory>;
+/**
+ * An interface for an awareness provider.
+ */
+export interface IAwarenessProvider extends IDisposable {
+    /**
+     * The awareness object.
+     */
+    readonly awareness: IAwareness;
+}
+/**
+ * A factory for creating awareness providers.
+ */
+export interface IAwarenessProviderFactory {
+    /**
+     * Create a new awareness provider.
+     *
+     * @param options - The instantiation options for an awareness provider.
+     * @returns The awareness provider.
+     */
+    create(options: IAwarenessProviderFactory.IOptions): IAwarenessProvider;
+}
+/**
+ * A namespace for IAwarenessProviderFactory.
+ */
+export declare namespace IAwarenessProviderFactory {
+    /**
+     * The instantiation options for an awareness provider.
+     */
+    interface IOptions {
+        /**
+         * The room ID
+         */
+        roomID: string;
+        /**
+         * The awareness object
+         */
+        awareness: IAwareness;
+        /**
+         * The user data
+         */
+        user: User.IManager;
+        /**
+         * The server settings.
+         */
+        serverSettings: ServerConnection.ISettings;
+    }
+}
+/**
+ * Token providing an awareness provider factory instance.
+ */
+export declare const IAwarenessProviderFactory: Token<IAwarenessProviderFactory>;
 export interface ISessionClosePayload {
     reason: 'unknown_session' | 'version_mismatch' | 'initialization_error';
     sessionId?: string;

package/lib/tokens.js

@@ -7,3 +7,11 @@ import { Token } from '@lumino/coreutils';
  * Token providing a fork manager instance.
  */
 export const IForkManagerToken = new Token('@jupyter/docprovider:IForkManagerToken');
+/**
+ * Token providing a document provider factory instance.
+ */
+export const IDocumentProviderFactory = new Token('@jupyter/docprovider:IDocumentProviderFactory');
+/**
+ * Token providing an awareness provider factory instance.
+ */
+export const IAwarenessProviderFactory = new Token('@jupyter/docprovider:IAwarenessProviderFactory');

package/lib/ydrive.d.ts

@@ -1,14 +1,17 @@
+import { IDocumentManager } from '@jupyterlab/docmanager';
+import { ISettingRegistry } from '@jupyterlab/settingregistry';
 import { TranslationBundle } from '@jupyterlab/translation';
 import { Contents, IContentProvider, ServerConnection, User } from '@jupyterlab/services';
 import { ISignal } from '@lumino/signaling';
 import { IDocumentProvider, ISharedModelFactory } from '@jupyter/collaborative-drive';
+import { IDocumentProviderFactory } from './tokens';
 import { Awareness } from 'y-protocols/awareness';
-import { ISettingRegistry } from '@jupyterlab/settingregistry';
 export interface IForkProvider {
     connectToForkDoc: (forkRoomId: string, sessionId: string) => Promise<void>;
     reconnect: () => Promise<void>;
     contentType: string;
     format: string;
+    save?: () => Promise<void>;
 }
 declare namespace RtcContentProvider {
     interface IOptions {
@@ -16,9 +19,17 @@ declare namespace RtcContentProvider {
         trans: TranslationBundle;
         globalAwareness: Awareness | null;
         serverSettings: ServerConnection.ISettings;
-        docmanagerSettings: ISettingRegistry.ISettings | null;
+        documentManager?: IDocumentManager | null;
         currentDrive: Contents.IDrive;
         fileChanged?: ISignal<Contents.IDrive, Contents.IChangedArgs>;
+        providerFactory: IDocumentProviderFactory;
+        /**
+         * @deprecated Pass `documentManager` instead. Used as a fallback when
+         * `documentManager` is not provided. Will be removed in a future major
+         * release.
+         * @see {@link IOptions.documentManager}
+         */
+        docmanagerSettings?: ISettingRegistry.ISettings | null;
     }
 }
 export declare class RtcContentProvider implements IContentProvider {
@@ -55,7 +66,6 @@ export declare class RtcContentProvider implements IContentProvider {
     get fileChanged(): ISignal<this, Contents.IChangedArgs>;
     private _onCreate;
     private _user;
-    private _saveCounter;
     private _currentDrive;
     private _trans;
     private _globalAwareness;
@@ -63,6 +73,8 @@ export declare class RtcContentProvider implements IContentProvider {
     private _providerFileChanged;
     private _driveFileChanged?;
     private _serverSettings;
+    private _documentManager;
     private _docmanagerSettings;
+    private _providerFactory;
 }
 export {};

package/lib/ydrive.js

@@ -1,45 +1,67 @@
 // Copyright (c) Jupyter Development Team.
 // Distributed under the terms of the Modified BSD License.
 import { PageConfig } from '@jupyterlab/coreutils';
-import { PromiseDelegate } from '@lumino/coreutils';
 import { Signal } from '@lumino/signaling';
-import { WebSocketProvider } from './yprovider';
-import * as decoding from 'lib0/decoding';
-import * as encoding from 'lib0/encoding';
 const DISABLE_RTC = PageConfig.getOption('disableRTC') === 'true' ? true : false;
-const RAW_MESSAGE_TYPE = 2;
 export class RtcContentProvider {
     constructor(options) {
+        var _a, _b;
         this._onCreate = (options, sharedModel) => {
-            var _a, _b, _c, _d, _e, _f, _g;
+            var _a, _b, _c;
             if (typeof options.format !== 'string') {
                 return;
             }
             // Set initial autosave value, used to determine backend autosave (default: true)
-            const autosave = (_c = (_b = (_a = this._docmanagerSettings) === null || _a === void 0 ? void 0 : _a.composite) === null || _b === void 0 ? void 0 : _b['autosave']) !== null && _c !== void 0 ? _c : true;
-            sharedModel.awareness.setLocalStateField('autosave', autosave);
-            // Watch for changes in settings
-            (_d = this._docmanagerSettings) === null || _d === void 0 ? void 0 : _d.changed.connect(() => {
-                var _a, _b, _c;
-                const newAutosave = (_c = (_b = (_a = this._docmanagerSettings) === null || _a === void 0 ? void 0 : _a.composite) === null || _b === void 0 ? void 0 : _b['autosave']) !== null && _c !== void 0 ? _c : true;
-                sharedModel.awareness.setLocalStateField('autosave', newAutosave);
-            });
+            const getAutosave = () => {
+                var _a, _b, _c, _d;
+                if (this._documentManager) {
+                    return (_a = this._documentManager.autosave) !== null && _a !== void 0 ? _a : true;
+                }
+                return ((_d = (_c = (_b = this._docmanagerSettings) === null || _b === void 0 ? void 0 : _b.composite) === null || _c === void 0 ? void 0 : _c['autosave']) !== null && _d !== void 0 ? _d : true);
+            };
+            sharedModel.awareness.setLocalStateField('autosave', getAutosave());
+            if (this._documentManager) {
+                // Watch for autosave changes on the document manager.
+                const handleStateChanged = (_, args) => {
+                    if (args.name === 'autosave') {
+                        sharedModel.awareness.setLocalStateField('autosave', getAutosave());
+                    }
+                };
+                this._documentManager.stateChanged.connect(handleStateChanged);
+                sharedModel.disposed.connect(() => {
+                    var _a;
+                    (_a = this._documentManager) === null || _a === void 0 ? void 0 : _a.stateChanged.disconnect(handleStateChanged);
+                });
+            }
+            else if (this._docmanagerSettings) {
+                // Fall back to watching the deprecated docmanager settings.
+                const handleSettingsChanged = () => {
+                    sharedModel.awareness.setLocalStateField('autosave', getAutosave());
+                };
+                this._docmanagerSettings.changed.connect(handleSettingsChanged);
+                sharedModel.disposed.connect(() => {
+                    var _a;
+                    (_a = this._docmanagerSettings) === null || _a === void 0 ? void 0 : _a.changed.disconnect(handleSettingsChanged);
+                });
+            }
             try {
-                const provider = new WebSocketProvider({
+                const providerOptions = {
                     path: options.path,
                     format: options.format,
                     contentType: options.contentType,
                     model: sharedModel,
                     user: this._user,
                     translator: this._trans,
-                    serverSettings: this._serverSettings
-                });
+                    serverSettings: this._serverSettings,
+                    drive: this._currentDrive
+                };
+                const provider = this._providerFactory.create(providerOptions);
                 // Add the document path in the list of opened ones for this user.
-                const state = ((_e = this._globalAwareness) === null || _e === void 0 ? void 0 : _e.getLocalState()) || {};
+                const state = ((_a = this._globalAwareness) === null || _a === void 0 ? void 0 : _a.getLocalState()) || {};
                 const documents = state.documents || [];
                 if (!documents.includes(options.path)) {
                     documents.push(options.path);
-                    (_f = this._globalAwareness) === null || _f === void 0 ? void 0 : _f.setLocalStateField('documents', documents);
+                    (_b = this._globalAwareness) === null || _b === void 0 ? void 0 : _b.setLocalStateField('documents', documents);
                 }
                 let path = options.path;
                 let key = `${options.format}:${options.contentType}:${path}`;
@@ -105,7 +127,7 @@ export class RtcContentProvider {
                         name: 'path'
                     });
                 };
-                (_g = this._driveFileChanged) === null || _g === void 0 ? void 0 : _g.connect(handleFileChangedSignal);
+                (_c = this._driveFileChanged) === null || _c === void 0 ? void 0 : _c.connect(handleFileChangedSignal);
                 sharedModel.changed.connect(async (_, change) => {
                     var _a;
                     if (!change.stateChange) {
@@ -161,7 +183,6 @@ export class RtcContentProvider {
                 console.error(`Failed to open websocket connection for ${options.path}.\n:${error}`);
             }
         };
-        this._saveCounter = 0;
         // This is for emitting signals to be proxied to `Drive.fileChanged`
         this._providerFileChanged = new Signal(this);
         this._user = options.user;
@@ -171,8 +192,10 @@ export class RtcContentProvider {
         this._currentDrive = options.currentDrive;
         this.sharedModelFactory = new SharedModelFactory(this._onCreate);
         this._providers = new Map();
-        this._docmanagerSettings = options.docmanagerSettings;
+        this._documentManager = (_a = options.documentManager) !== null && _a !== void 0 ? _a : null;
+        this._docmanagerSettings = (_b = options.docmanagerSettings) !== null && _b !== void 0 ? _b : null;
         this._driveFileChanged = options.fileChanged;
+        this._providerFactory = options.providerFactory;
     }
     get providers() {
         return this._providers;
@@ -233,62 +256,13 @@ export class RtcContentProvider {
      *   file is saved.
      */
     async save(localPath, options = {}) {
-        var _a;
         // Check that there is a provider - it won't e.g. if the document model is not collaborative.
         if (options.format && options.type) {
             const key = `${options.format}:${options.type}:${localPath}`;
             const provider = this._providers.get(key);
-            const saveId = ++this._saveCounter;
             if (provider) {
-                const ws = (_a = provider.wsProvider) === null || _a === void 0 ? void 0 : _a.ws;
-                if (ws) {
-                    const delegate = new PromiseDelegate();
-                    const handler = (event) => {
-                        const data = new Uint8Array(event.data);
-                        const decoder = decoding.createDecoder(data);
-                        try {
-                            const messageType = decoding.readVarUint(decoder);
-                            if (messageType !== RAW_MESSAGE_TYPE) {
-                                return;
-                            }
-                        }
-                        catch (_a) {
-                            return;
-                        }
-                        const rawReply = decoding.readVarString(decoder);
-                        let reply = null;
-                        try {
-                            reply = JSON.parse(rawReply);
-                        }
-                        catch (e) {
-                            console.debug('The raw reply received was not a JSON reply');
-                        }
-                        if (reply &&
-                            reply['type'] === 'save' &&
-                            reply['responseTo'] === saveId) {
-                            if (reply.status === 'success') {
-                                delegate.resolve();
-                            }
-                            else if (reply.status === 'failed') {
-                                delegate.reject('Saving failed');
-                            }
-                            else if (reply.status === 'skipped') {
-                                delegate.reject('Saving already in progress');
-                            }
-                            else {
-                                delegate.reject('Unrecognised save reply status');
-                            }
-                        }
-                    };
-                    ws.addEventListener('message', handler);
-                    const encoder = encoding.createEncoder();
-                    encoding.writeVarUint(encoder, RAW_MESSAGE_TYPE);
-                    encoding.writeVarString(encoder, 'save');
-                    encoding.writeVarUint(encoder, saveId);
-                    const saveMessage = encoding.toUint8Array(encoder);
-                    ws.send(saveMessage);
-                    await delegate.promise;
-                    ws.removeEventListener('message', handler);
+                if (provider.save) {
+                    await provider.save();
                 }
                 const fetchOptions = {
                     type: options.type,
@@ -359,6 +333,9 @@ class SharedModelFactory {
         }
         if (this.documentFactories.has(options.contentType)) {
             const factory = this.documentFactories.get(options.contentType);
+            if (!factory) {
+                return;
+            }
             const sharedModel = factory(options);
             this._onCreate(options, sharedModel);
             return sharedModel;

package/lib/yprovider.d.ts

@@ -1,8 +1,8 @@
+import { WebsocketProvider as YWebsocketProvider } from 'y-websocket';
+import { DocumentChange, YDocument } from '@jupyter/ydoc';
 import { IDocumentProvider } from '@jupyter/collaborative-drive';
 import { ServerConnection, User } from '@jupyterlab/services';
 import { TranslationBundle } from '@jupyterlab/translation';
-import { DocumentChange, YDocument } from '@jupyter/ydoc';
-import { WebsocketProvider as YWebsocketProvider } from 'y-websocket';
 import { IForkProvider } from './ydrive';
 /**
  * A class to provide Yjs synchronization over WebSocket.
@@ -32,6 +32,7 @@ export declare class WebSocketProvider implements IDocumentProvider, IForkProvid
      */
     dispose(): void;
     reconnect(): Promise<void>;
+    save(): Promise<void>;
     private get _serverUrl();
     private _connect;
     connectToForkDoc(forkRoomId: string, sessionId: string): Promise<void>;
@@ -54,6 +55,7 @@ export declare class WebSocketProvider implements IDocumentProvider, IForkProvid
     private _serverSettings;
     private _trans;
     private _hasSynced;
+    private _saveCounter;
 }
 /**
  * A namespace for WebSocketProvider statics.

package/lib/yprovider.js

@@ -1,18 +1,24 @@
-/* -----------------------------------------------------------------------------
-| Copyright (c) Jupyter Development Team.
-| Distributed under the terms of the Modified BSD License.
-|----------------------------------------------------------------------------*/
-import { Dialog, showDialog } from '@jupyterlab/apputils';
-import { ServerConnection } from '@jupyterlab/services';
-import { PromiseDelegate } from '@lumino/coreutils';
-import { Signal } from '@lumino/signaling';
+/*
+ * Copyright (c) Jupyter Development Team.
+ * Distributed under the terms of the Modified BSD License.
+ */
 import { WebsocketProvider as YWebsocketProvider } from 'y-websocket';
-import { requestDocSession } from './requests';
+import * as decoding from 'lib0/decoding';
+import * as encoding from 'lib0/encoding';
+import { Signal } from '@lumino/signaling';
+import { PromiseDelegate } from '@lumino/coreutils';
+import { ServerConnection } from '@jupyterlab/services';
 import { URLExt } from '@jupyterlab/coreutils';
+import { Dialog, showDialog } from '@jupyterlab/apputils';
+import { requestDocSession } from './requests';
 /**
  * The url for the default drive service.
  */
 const DOCUMENT_PROVIDER_URL = 'api/collaboration/room';
+/**
+ * The raw message type.
+ */
+const RAW_MESSAGE_TYPE = 2;
 /**
  * A class to provide Yjs synchronization over WebSocket.
  *
@@ -85,6 +91,7 @@ export class WebSocketProvider {
         };
         this._ready = new PromiseDelegate();
         this._hasSynced = false;
+        this._saveCounter = 0;
         this._isDisposed = false;
         this._path = options.path;
         this._contentType = options.contentType;
@@ -142,6 +149,64 @@ export class WebSocketProvider {
         this._disconnect();
         this._connect();
     }
+    async save() {
+        var _a;
+        const ws = (_a = this._yWebsocketProvider) === null || _a === void 0 ? void 0 : _a.ws;
+        if (ws) {
+            const saveId = ++this._saveCounter;
+            const delegate = new PromiseDelegate();
+            const handler = (event) => {
+                const data = new Uint8Array(event.data);
+                const decoder = decoding.createDecoder(data);
+                try {
+                    const messageType = decoding.readVarUint(decoder);
+                    if (messageType !== RAW_MESSAGE_TYPE) {
+                        return;
+                    }
+                }
+                catch (_a) {
+                    return;
+                }
+                const rawReply = decoding.readVarString(decoder);
+                let reply = null;
+                try {
+                    reply = JSON.parse(rawReply);
+                }
+                catch (e) {
+                    console.debug('The raw reply received was not a JSON reply');
+                }
+                if (reply &&
+                    reply['type'] === 'save' &&
+                    reply['responseTo'] === saveId) {
+                    if (reply.status === 'success') {
+                        delegate.resolve();
+                    }
+                    else if (reply.status === 'failed') {
+                        delegate.reject('Saving failed');
+                    }
+                    else if (reply.status === 'skipped') {
+                        delegate.reject('Saving already in progress');
+                    }
+                    else {
+                        delegate.reject('Unrecognised save reply status');
+                    }
+                }
+            };
+            ws.addEventListener('message', handler);
+            const encoder = encoding.createEncoder();
+            encoding.writeVarUint(encoder, RAW_MESSAGE_TYPE);
+            encoding.writeVarString(encoder, 'save');
+            encoding.writeVarUint(encoder, saveId);
+            const saveMessage = encoding.toUint8Array(encoder);
+            ws.send(saveMessage);
+            try {
+                await delegate.promise;
+            }
+            finally {
+                ws.removeEventListener('message', handler);
+            }
+        }
+    }
     get _serverUrl() {
         var _a;
         return ((_a = this._customServerUrl) !== null && _a !== void 0 ? _a : URLExt.join(this._serverSettings.wsUrl, DOCUMENT_PROVIDER_URL));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jupyter/docprovider",
-  "version": "4.3.0",
+  "version": "4.4.0-beta.0",
   "description": "JupyterLab - Document Provider",
   "homepage": "https://github.com/jupyterlab/jupyter-collaboration",
   "bugs": {
@@ -41,11 +41,12 @@
     "watch": "tsc -b --watch"
   },
   "dependencies": {
-    "@jupyter/collaborative-drive": "^4.3.0",
+    "@jupyter/collaborative-drive": "^4.4.0-beta.0",
     "@jupyter/ydoc": "^2.1.3 || ^3.0.0",
     "@jupyterlab/apputils": "^4.5.0",
     "@jupyterlab/cells": "^4.5.0",
     "@jupyterlab/coreutils": "^6.5.0",
+    "@jupyterlab/docmanager": "^4.5.0",
     "@jupyterlab/notebook": "^4.5.0",
     "@jupyterlab/services": "^7.5.0",
     "@jupyterlab/translation": "^4.5.0",
@@ -63,7 +64,7 @@
     "@types/jest": "^29.2.0",
     "jest": "^29.5.0",
     "rimraf": "^4.1.2",
-    "typescript": "~5.1.6"
+    "typescript": "~5.9.3"
   },
   "publishConfig": {
     "access": "public"