Support document forking

javascript/package.json

@@ -41,6 +41,7 @@
         "watch": "tsc -b --watch"
     },
     "dependencies": {
+        "@jupyterlab/application": "^4.0.0",
         "@jupyterlab/nbformat": "^3.0.0 || ^4.0.0-alpha.21 || ^4.0.0",
         "@lumino/coreutils": "^1.11.0 || ^2.0.0",
         "@lumino/disposable": "^1.10.0 || ^2.0.0",

javascript/src/api.ts

@@ -20,7 +20,7 @@ import type {
   JSONValue,
   PartialJSONValue
 } from '@lumino/coreutils';
-import type { IObservableDisposable } from '@lumino/disposable';
+import type { IDisposable, IObservableDisposable } from '@lumino/disposable';
 import type { ISignal } from '@lumino/signaling';
 import * as Y from 'yjs';
 
@@ -81,6 +81,26 @@ export interface ISharedBase extends IObservableDisposable {
   transact(f: () => void, undoable?: boolean, origin?: any): void;
 }
 
+/**
+ * An interface for a document provider.
+ */
+export interface IDocumentProvider extends IDisposable {
+  /**
+   * Returns a Promise that resolves when the document provider is ready.
+   */
+  readonly ready: Promise<void>;
+
+  /**
+   * Request to fork the room in the backend, returns the fork ID.
+   */
+  fork(): Promise<string>;
+
+  /**
+   * Connect the shared document to a room with given ID (disconnect from previous room).
+   */
+  connect(roomId: string, merge?: boolean): void;
+}
+
 /**
  * Implement an API for Context information on the shared information.
  * This is used by, for example, docregistry to share the file-path of the edited content.
@@ -115,6 +135,28 @@ interface ISharedDocumentNoSource extends ISharedBase {
    * The changed signal.
    */
   readonly changed: ISignal<this, DocumentChange>;
+
+  /**
+   * The document's provider.
+   */
+  provider: IDocumentProvider;
+
+  /**
+   * Add a fork ID to the document's ystate, as a new key 'fork_{forkId}'
+   *
+   * @param forkId The fork ID to add to the document
+   */
+  addFork(forkId: string): void;
+
+  /**
+   * The document root room ID
+   */
+  rootRoomId: string;
+
+  /**
+   * The document current room ID
+   */
+  currentRoomId: string;
 }
 
 /**

javascript/src/ydocument.ts

@@ -7,7 +7,12 @@ import { JSONExt, JSONObject, JSONValue } from '@lumino/coreutils';
 import { ISignal, Signal } from '@lumino/signaling';
 import { Awareness } from 'y-protocols/awareness';
 import * as Y from 'yjs';
-import type { DocumentChange, ISharedDocument, StateChange } from './api.js';
+import type {
+  DocumentChange,
+  IDocumentProvider,
+  ISharedDocument,
+  StateChange
+} from './api.js';
 
 /**
  * Generic shareable document.
@@ -17,6 +22,8 @@ export abstract class YDocument<T extends DocumentChange>
 {
   constructor(options?: YDocument.IOptions) {
     this._ydoc = options?.ydoc ?? new Y.Doc();
+    this.rootRoomId = options?.rootRoomId ?? '';
+    this.currentRoomId = options?.currentRoomId ?? '';
 
     this._ystate = this._ydoc.getMap('state');
 
@@ -35,6 +42,21 @@ export abstract class YDocument<T extends DocumentChange>
    */
   abstract readonly version: string;
 
+  addFork(forkId: string) {
+    this.ystate.set(`fork_${forkId}`, 'new');
+  }
+
+  get provider(): IDocumentProvider {
+    if (this._provider === undefined) {
+      throw new Error('YDocument has no provider');
+    }
+    return this._provider;
+  }
+
+  set provider(provider: IDocumentProvider) {
+    this._provider = provider;
+  }
+
   /**
    * YJS document.
    */
@@ -232,6 +254,9 @@ export abstract class YDocument<T extends DocumentChange>
   private _awareness: Awareness;
   private _isDisposed = false;
   private _disposed = new Signal<this, void>(this);
+  private _provider: IDocumentProvider;
+  public rootRoomId: string;
+  public currentRoomId: string;
 }
 
 /**
@@ -246,5 +271,15 @@ export namespace YDocument {
      * The optional YJS document for YDocument.
      */
     ydoc?: Y.Doc;
+
+    /**
+     * The document root room ID, defaults to ''.
+     */
+    rootRoomId?: string;
+
+    /**
+     * The document current room ID, defaults to ''.
+     */
+    currentRoomId?: string;
   }
 }