@jupyter/docprovider 3.0.1 → 3.1.0-beta.0

package/lib/forkManager.d.ts

@@ -0,0 +1,41 @@
+import { ICollaborativeDrive } from '@jupyter/collaborative-drive';
+import { Event } from '@jupyterlab/services';
+import { ISignal } from '@lumino/signaling';
+import { IAllForksResponse, IForkChangedEvent, IForkCreationResponse, IForkManager } from './tokens';
+import { IForkProvider } from './ydrive';
+export declare const JUPYTER_COLLABORATION_FORK_EVENTS_URI = "https://schema.jupyter.org/jupyter_collaboration/fork/v1";
+export declare class ForkManager implements IForkManager {
+    constructor(options: ForkManager.IOptions);
+    get isDisposed(): boolean;
+    get forkAdded(): ISignal<ForkManager, IForkChangedEvent>;
+    get forkDeleted(): ISignal<ForkManager, IForkChangedEvent>;
+    dispose(): void;
+    createFork(options: {
+        rootId: string;
+        synchronize: boolean;
+        title?: string;
+        description?: string;
+    }): Promise<IForkCreationResponse | undefined>;
+    getAllForks(rootId: string): Promise<IAllForksResponse>;
+    deleteFork(options: {
+        forkId: string;
+        merge: boolean;
+    }): Promise<void>;
+    getProvider(options: {
+        documentPath: string;
+        format: string;
+        type: string;
+    }): IForkProvider | undefined;
+    private _handleEvent;
+    private _disposed;
+    private _drive;
+    private _eventManager;
+    private _forkAddedSignal;
+    private _forkDeletedSignal;
+}
+export declare namespace ForkManager {
+    interface IOptions {
+        drive: ICollaborativeDrive;
+        eventManager: Event.IManager;
+    }
+}

package/lib/forkManager.js

@@ -0,0 +1,89 @@
+/*
+ * Copyright (c) Jupyter Development Team.
+ * Distributed under the terms of the Modified BSD License.
+ */
+import { URLExt } from '@jupyterlab/coreutils';
+import { Signal } from '@lumino/signaling';
+import { requestAPI, ROOM_FORK_URL } from './requests';
+export const JUPYTER_COLLABORATION_FORK_EVENTS_URI = 'https://schema.jupyter.org/jupyter_collaboration/fork/v1';
+export class ForkManager {
+    constructor(options) {
+        this._disposed = false;
+        this._forkAddedSignal = new Signal(this);
+        this._forkDeletedSignal = new Signal(this);
+        const { drive, eventManager } = options;
+        this._drive = drive;
+        this._eventManager = eventManager;
+        this._eventManager.stream.connect(this._handleEvent, this);
+    }
+    get isDisposed() {
+        return this._disposed;
+    }
+    get forkAdded() {
+        return this._forkAddedSignal;
+    }
+    get forkDeleted() {
+        return this._forkDeletedSignal;
+    }
+    dispose() {
+        var _a;
+        if (this._disposed) {
+            return;
+        }
+        (_a = this._eventManager) === null || _a === void 0 ? void 0 : _a.stream.disconnect(this._handleEvent);
+        this._disposed = true;
+    }
+    async createFork(options) {
+        const { rootId, title, description, synchronize } = options;
+        const init = {
+            method: 'PUT',
+            body: JSON.stringify({ title, description, synchronize })
+        };
+        const url = URLExt.join(ROOM_FORK_URL, rootId);
+        const response = await requestAPI(url, init);
+        return response;
+    }
+    async getAllForks(rootId) {
+        const url = URLExt.join(ROOM_FORK_URL, rootId);
+        const init = { method: 'GET' };
+        const response = await requestAPI(url, init);
+        return response;
+    }
+    async deleteFork(options) {
+        const { forkId, merge } = options;
+        const url = URLExt.join(ROOM_FORK_URL, forkId);
+        const query = URLExt.objectToQueryString({ merge });
+        const init = { method: 'DELETE' };
+        await requestAPI(`${url}${query}`, init);
+    }
+    getProvider(options) {
+        const { documentPath, format, type } = options;
+        const drive = this._drive;
+        if (drive) {
+            const driveName = drive.name;
+            let docPath = documentPath;
+            if (documentPath.startsWith(driveName)) {
+                docPath = documentPath.slice(driveName.length + 1);
+            }
+            const provider = drive.providers.get(`${format}:${type}:${docPath}`);
+            return provider;
+        }
+        return;
+    }
+    _handleEvent(_, emission) {
+        if (emission.schema_id === JUPYTER_COLLABORATION_FORK_EVENTS_URI) {
+            switch (emission.action) {
+                case 'create': {
+                    this._forkAddedSignal.emit(emission);
+                    break;
+                }
+                case 'delete': {
+                    this._forkDeletedSignal.emit(emission);
+                    break;
+                }
+                default:
+                    break;
+            }
+        }
+    }
+}

package/lib/index.d.ts

@@ -8,3 +8,5 @@ export * from './requests';
 export * from './ydrive';
 export * from './yprovider';
 export * from './TimelineSlider';
+export * from './tokens';
+export * from './forkManager';

package/lib/index.js

@@ -12,3 +12,5 @@ export * from './requests';
 export * from './ydrive';
 export * from './yprovider';
 export * from './TimelineSlider';
+export * from './tokens';
+export * from './forkManager';

package/lib/requests.d.ts

@@ -1,4 +1,5 @@
 import { Contents } from '@jupyterlab/services';
+export declare const ROOM_FORK_URL = "api/collaboration/fork";
 /**
  * Document session model
  */
@@ -20,6 +21,14 @@ export interface ISessionModel {
      */
     sessionId: string;
 }
+/**
+ * Call the API extension
+ *
+ * @param endPoint API REST end point for the extension
+ * @param init Initial values for the request
+ * @returns The response body interpreted as JSON
+ */
+export declare function requestAPI<T = any>(endPoint?: string, init?: RequestInit): Promise<T>;
 export declare function requestDocSession(format: string, type: string, path: string): Promise<ISessionModel>;
 export declare function requestDocumentTimeline(format: string, type: string, path: string): Promise<any>;
 export declare function requestUndoRedo(roomid: string, action: 'undo' | 'redo' | 'restore', steps: number, forkRoom: string): Promise<any>;

package/lib/requests.js

@@ -11,6 +11,39 @@ import { ServerConnection } from '@jupyterlab/services';
 const DOC_SESSION_URL = 'api/collaboration/session';
 const DOC_FORK_URL = 'api/collaboration/undo_redo';
 const TIMELINE_URL = 'api/collaboration/timeline';
+export const ROOM_FORK_URL = 'api/collaboration/fork';
+/**
+ * Call the API extension
+ *
+ * @param endPoint API REST end point for the extension
+ * @param init Initial values for the request
+ * @returns The response body interpreted as JSON
+ */
+export async function requestAPI(endPoint = '', init = {}) {
+    // Make request to Jupyter API
+    const settings = ServerConnection.makeSettings();
+    const requestUrl = URLExt.join(settings.baseUrl, endPoint);
+    let response;
+    try {
+        response = await ServerConnection.makeRequest(requestUrl, init, settings);
+    }
+    catch (error) {
+        throw new ServerConnection.NetworkError(error);
+    }
+    let data = await response.text();
+    if (data.length > 0) {
+        try {
+            data = JSON.parse(data);
+        }
+        catch (error) {
+            console.error('Not a JSON response body.', response);
+        }
+    }
+    if (!response.ok) {
+        throw new ServerConnection.ResponseError(response, data.message || data);
+    }
+    return data;
+}
 export async function requestDocSession(format, type, path) {
     const settings = ServerConnection.makeSettings();
     const url = URLExt.join(settings.baseUrl, DOC_SESSION_URL, encodeURIComponent(path));

package/lib/tokens.d.ts

@@ -0,0 +1,103 @@
+import { Token } from '@lumino/coreutils';
+import { IDisposable } from '@lumino/disposable';
+import { ISignal } from '@lumino/signaling';
+import { IForkProvider } from './ydrive';
+export interface IForkInfo {
+    description?: string;
+    root_roomid: string;
+    synchronize: boolean;
+    title?: string;
+}
+export interface IForkCreationResponse {
+    fork_info: IForkInfo;
+    fork_roomid: string;
+    sessionId: string;
+}
+export interface IAllForksResponse {
+    [forkId: string]: IForkInfo;
+}
+export interface IForkChangedEvent {
+    fork_info: IForkInfo;
+    fork_roomid: string;
+    username?: string;
+}
+/**
+ * Interface representing a Fork Manager that manages forked documents and
+ * provides signals for fork-related events.
+ *
+ * @interface IForkManager
+ * @extends IDisposable
+ */
+export interface IForkManager extends IDisposable {
+    /**
+     * Get the fork provider of a given document.
+     *
+     * @param options.documentPath - The document path including the
+     * drive prefix.
+     * @param options.format - Format of the document.
+     * @param options.type - Content type of the document.
+     * @returns The fork provider of the document.
+     */
+    getProvider(options: {
+        documentPath: string;
+        format: string;
+        type: string;
+    }): IForkProvider | undefined;
+    /**
+     * Creates a new fork for a given document.
+     *
+     * @param options.rootId - The ID of the root document to fork.
+     * @param options.synchronize - A flag indicating whether the fork should be kept
+     * synchronized with the root document.
+     * @param options.title - An optional label for the fork.
+     * @param options.description - An optional description for the fork.
+     *
+     * @returns A promise that resolves to an `IForkCreationResponse` if the fork
+     * is created successfully, or `undefined` if the creation fails.
+     */
+    createFork(options: {
+        rootId: string;
+        synchronize: boolean;
+        title?: string;
+        description?: string;
+    }): Promise<IForkCreationResponse | undefined>;
+    /**
+     * Retrieves all forks associated with a specific document.
+     *
+     * @param documentId - The ID of the document for which forks are to be retrieved.
+     *
+     * @returns A promise that resolves to an `IAllForksResponse` containing information about all forks.
+     */
+    getAllForks(documentId: string): Promise<IAllForksResponse>;
+    /**
+     * Deletes a specified fork and optionally merges its changes.
+     *
+     * @param options - Options for deleting the fork.
+     * @param options.forkId - The ID of the fork to be deleted.
+     * @param options.merge - A flag indicating whether changes from the fork should be merged back into the root document.
+     *
+     * @returns A promise that resolves when the fork is successfully deleted.
+     */
+    deleteFork(options: {
+        forkId: string;
+        merge: boolean;
+    }): Promise<void>;
+    /**
+     * Signal emitted when a new fork is added.
+     *
+     * @event forkAdded
+     * @type ISignal<IForkManager, IForkChangedEvent>
+     */
+    forkAdded: ISignal<IForkManager, IForkChangedEvent>;
+    /**
+     * Signal emitted when a fork is deleted.
+     *
+     * @event forkDeleted
+     * @type ISignal<IForkManager, IForkChangedEvent>
+     */
+    forkDeleted: ISignal<IForkManager, IForkChangedEvent>;
+}
+/**
+ * Token providing a fork manager instance.
+ */
+export declare const IForkManagerToken: Token<IForkManager>;

package/lib/tokens.js

@@ -0,0 +1,9 @@
+/*
+ * Copyright (c) Jupyter Development Team.
+ * Distributed under the terms of the Modified BSD License.
+ */
+import { Token } from '@lumino/coreutils';
+/**
+ * Token providing a fork manager instance.
+ */
+export const IForkManagerToken = new Token('@jupyter/docprovider:IForkManagerToken');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jupyter/docprovider",
-  "version": "3.0.1",
+  "version": "3.1.0-beta.0",
   "description": "JupyterLab - Document Provider",
   "homepage": "https://github.com/jupyterlab/jupyter-collaboration",
   "bugs": {
@@ -41,7 +41,7 @@
     "watch": "tsc -b --watch"
   },
   "dependencies": {
-    "@jupyter/collaborative-drive": "^3.0.1",
+    "@jupyter/collaborative-drive": "^3.1.0-beta.0",
     "@jupyter/ydoc": "^2.0.0 || ^3.0.0",
     "@jupyterlab/apputils": "^4.2.0",
     "@jupyterlab/cells": "^4.2.0",