@hocuspocus/provider 2.13.7 → 2.15.0

package/dist/hocuspocus-provider.cjs

@@ -2475,6 +2475,8 @@ class HocuspocusProvider extends EventEmitter {
             forceSync: null,
         };
         this.isConnected = true;
+        this.boundDocumentUpdateHandler = this.documentUpdateHandler.bind(this);
+        this.boundAwarenessUpdateHandler = this.awarenessUpdateHandler.bind(this);
         this.boundBroadcastChannelSubscriber = this.broadcastChannelSubscriber.bind(this);
         this.boundPageHide = this.pageHide.bind(this);
         this.boundOnOpen = this.onOpen.bind(this);
@@ -2516,8 +2518,8 @@ class HocuspocusProvider extends EventEmitter {
         (_b = this.awareness) === null || _b === void 0 ? void 0 : _b.on('change', () => {
             this.emit('awarenessChange', { states: common.awarenessStatesToArray(this.awareness.getStates()) });
         });
-        this.document.on('update', this.documentUpdateHandler.bind(this));
-        (_c = this.awareness) === null || _c === void 0 ? void 0 : _c.on('update', this.awarenessUpdateHandler.bind(this));
+        this.document.on('update', this.boundDocumentUpdateHandler);
+        (_c = this.awareness) === null || _c === void 0 ? void 0 : _c.on('update', this.boundAwarenessUpdateHandler);
         this.registerEventListeners();
         if (this.configuration.forceSyncInterval
             && typeof this.configuration.forceSyncInterval === 'number') {
@@ -2708,10 +2710,10 @@ class HocuspocusProvider extends EventEmitter {
         }
         if (this.awareness) {
             removeAwarenessStates(this.awareness, [this.document.clientID], 'provider destroy');
-            this.awareness.off('update', this.awarenessUpdateHandler);
+            this.awareness.off('update', this.boundAwarenessUpdateHandler);
             this.awareness.destroy();
         }
-        this.document.off('update', this.documentUpdateHandler);
+        this.document.off('update', this.boundDocumentUpdateHandler);
         this.removeAllListeners();
         this.configuration.websocketProvider.off('connect', this.configuration.onConnect);
         this.configuration.websocketProvider.off('connect', this.forwardConnect);
@@ -2842,6 +2844,17 @@ class TiptapCollabProviderWebsocket extends HocuspocusProviderWebsocket {
     }
 }
 
+const defaultDeleteCommentOptions = {
+    deleteContent: false,
+    deleteThread: false,
+};
+const defaultGetThreadsOptions = {
+    types: ['unarchived'],
+};
+const defaultDeleteThreadOptions = {
+    deleteComments: false,
+    force: false,
+};
 class TiptapCollabProvider extends HocuspocusProvider {
     constructor(configuration) {
         if (!configuration.websocketProvider) {
@@ -2898,17 +2911,44 @@ class TiptapCollabProvider extends HocuspocusProvider {
     disableAutoVersioning() {
         return this.configuration.document.getMap(`${this.tiptapCollabConfigurationPrefix}config`).set('autoVersioning', 0);
     }
+    /**
+     * Returns all users in the document as Y.Map objects
+     * @returns An array of Y.Map objects
+     */
     getYThreads() {
         return this.configuration.document.getArray(`${this.tiptapCollabConfigurationPrefix}threads`);
     }
-    getThreads() {
-        return this.getYThreads().toJSON();
+    /**
+     * Finds all threads in the document and returns them as JSON objects
+     * @options Options to control the output of the threads (e.g. include deleted threads)
+     * @returns An array of threads as JSON objects
+     */
+    getThreads(options) {
+        const { types } = { ...defaultGetThreadsOptions, ...options };
+        const threads = this.getYThreads().toJSON();
+        if ((types === null || types === void 0 ? void 0 : types.includes('archived')) && (types === null || types === void 0 ? void 0 : types.includes('unarchived'))) {
+            return threads;
+        }
+        return threads.filter(currentThead => {
+            if ((types === null || types === void 0 ? void 0 : types.includes('archived')) && currentThead.deletedAt) {
+                return true;
+            }
+            if ((types === null || types === void 0 ? void 0 : types.includes('unarchived')) && !currentThead.deletedAt) {
+                return true;
+            }
+            return false;
+        });
     }
+    /**
+     * Find the index of a thread by its id
+     * @param id The thread id
+     * @returns The index of the thread or null if not found
+     */
     getThreadIndex(id) {
         let index = null;
         let i = 0;
         // eslint-disable-next-line no-restricted-syntax
-        for (const thread of this.getThreads()) {
+        for (const thread of this.getThreads({ types: ['archived', 'unarchived'] })) {
             if (thread.id === id) {
                 index = i;
                 break;
@@ -2917,6 +2957,11 @@ class TiptapCollabProvider extends HocuspocusProvider {
         }
         return index;
     }
+    /**
+     * Gets a single thread by its id
+     * @param id The thread id
+     * @returns The thread as a JSON object or null if not found
+     */
     getThread(id) {
         const index = this.getThreadIndex(id);
         if (index === null) {
@@ -2924,6 +2969,11 @@ class TiptapCollabProvider extends HocuspocusProvider {
         }
         return this.getYThreads().get(index).toJSON();
     }
+    /**
+     * Gets a single thread by its id as a Y.Map object
+     * @param id The thread id
+     * @returns The thread as a Y.Map object or null if not found
+     */
     getYThread(id) {
         const index = this.getThreadIndex(id);
         if (index === null) {
@@ -2931,6 +2981,11 @@ class TiptapCollabProvider extends HocuspocusProvider {
         }
         return this.getYThreads().get(index);
     }
+    /**
+     * Create a new thread
+     * @param data The thread data
+     * @returns The created thread
+     */
     createThread(data) {
         let createdThread = {};
         this.document.transact(() => {
@@ -2938,11 +2993,19 @@ class TiptapCollabProvider extends HocuspocusProvider {
             thread.set('id', uuidv4());
             thread.set('createdAt', (new Date()).toISOString());
             thread.set('comments', new Y__namespace.Array());
+            thread.set('deletedComments', new Y__namespace.Array());
+            thread.set('deletedAt', null);
             this.getYThreads().push([thread]);
             createdThread = this.updateThread(String(thread.get('id')), data);
         });
         return createdThread;
     }
+    /**
+     * Update a specific thread
+     * @param id The thread id
+     * @param data New data for the thread
+     * @returns The updated thread or null if the thread is not found
+     */
     updateThread(id, data) {
         let updatedThread = {};
         this.document.transact(() => {
@@ -2961,29 +3024,87 @@ class TiptapCollabProvider extends HocuspocusProvider {
         });
         return updatedThread;
     }
-    deleteThread(id) {
+    /**
+     * Handle the deletion of a thread. By default, the thread and it's comments are not deleted, but marked as deleted
+     * via the `deletedAt` property. Forceful deletion can be enabled by setting the `force` option to `true`.
+     *
+     * If you only want to delete the comments of a thread, you can set the `deleteComments` option to `true`.
+     * @param id The thread id
+     * @param options A set of options that control how the thread is deleted
+     * @returns The deleted thread or null if the thread is not found
+     */
+    deleteThread(id, options) {
+        const { deleteComments, force } = { ...defaultDeleteThreadOptions, ...options };
         const index = this.getThreadIndex(id);
         if (index === null) {
+            return null;
+        }
+        if (force) {
+            this.getYThreads().delete(index, 1);
             return;
         }
-        this.getYThreads().delete(index, 1);
+        const thread = this.getYThreads().get(index);
+        thread.set('deletedAt', (new Date()).toISOString());
+        if (deleteComments) {
+            thread.set('comments', new Y__namespace.Array());
+            thread.set('deletedComments', new Y__namespace.Array());
+        }
+        return thread.toJSON();
+    }
+    /**
+     * Tries to restore a deleted thread
+     * @param id The thread id
+     * @returns The restored thread or null if the thread is not found
+     */
+    restoreThread(id) {
+        const index = this.getThreadIndex(id);
+        if (index === null) {
+            return null;
+        }
+        const thread = this.getYThreads().get(index);
+        thread.set('deletedAt', null);
+        return thread.toJSON();
     }
-    getThreadComments(threadId) {
-        var _a, _b;
+    /**
+     * Returns comments from a thread, either deleted or not
+     * @param threadId The thread id
+     * @param includeDeleted If you want to include deleted comments, defaults to `false`
+     * @returns The comments or null if the thread is not found
+     */
+    getThreadComments(threadId, includeDeleted) {
+        var _a, _b, _c;
         const index = this.getThreadIndex(threadId);
         if (index === null) {
             return null;
         }
-        return (_b = (_a = this.getThread(threadId)) === null || _a === void 0 ? void 0 : _a.comments) !== null && _b !== void 0 ? _b : [];
+        const comments = !includeDeleted ? (_a = this.getThread(threadId)) === null || _a === void 0 ? void 0 : _a.comments : [...(((_b = this.getThread(threadId)) === null || _b === void 0 ? void 0 : _b.comments) || []), ...(((_c = this.getThread(threadId)) === null || _c === void 0 ? void 0 : _c.deletedComments) || [])].sort((a, b) => {
+            return a.createdAt.localeCompare(b.createdAt);
+        });
+        return comments !== null && comments !== void 0 ? comments : [];
     }
-    getThreadComment(threadId, commentId) {
-        var _a, _b;
+    /**
+     * Get a single comment from a specific thread
+     * @param threadId The thread id
+     * @param commentId The comment id
+     * @param includeDeleted If you want to include deleted comments in the search
+     * @returns The comment or null if not found
+     */
+    getThreadComment(threadId, commentId, includeDeleted) {
+        var _a;
         const index = this.getThreadIndex(threadId);
         if (index === null) {
             return null;
         }
-        return (_b = (_a = this.getThread(threadId)) === null || _a === void 0 ? void 0 : _a.comments.find(comment => comment.id === commentId)) !== null && _b !== void 0 ? _b : null;
+        const comments = this.getThreadComments(threadId, includeDeleted);
+        return (_a = comments === null || comments === void 0 ? void 0 : comments.find(comment => comment.id === commentId)) !== null && _a !== void 0 ? _a : null;
     }
+    /**
+     * Adds a comment to a thread
+     * @param threadId The thread id
+     * @param data The comment data
+     * @returns The updated thread or null if the thread is not found
+     * @example addComment('123', { content: 'Hello world', data: { author: 'Maria Doe' } })
+     */
     addComment(threadId, data) {
         let updatedThread = {};
         this.document.transact(() => {
@@ -2999,6 +3120,14 @@ class TiptapCollabProvider extends HocuspocusProvider {
         });
         return updatedThread;
     }
+    /**
+     * Update a comment in a thread
+     * @param threadId The thread id
+     * @param commentId The comment id
+     * @param data The new comment data
+     * @returns The updated thread or null if the thread or comment is not found
+     * @example updateComment('123', { content: 'The new content', data: { attachments: ['file1.jpg'] }})
+     */
     updateComment(threadId, commentId, data) {
         let updatedThread = {};
         this.document.transact(() => {
@@ -3026,7 +3155,15 @@ class TiptapCollabProvider extends HocuspocusProvider {
         });
         return updatedThread;
     }
-    deleteComment(threadId, commentId) {
+    /**
+     * Deletes a comment from a thread
+     * @param threadId The thread id
+     * @param commentId The comment id
+     * @param options A set of options that control how the comment is deleted
+     * @returns The updated thread or null if the thread or comment is not found
+     */
+    deleteComment(threadId, commentId, options) {
+        const { deleteContent, deleteThread } = { ...defaultDeleteCommentOptions, ...options };
         const thread = this.getYThread(threadId);
         if (thread === null)
             return null;
@@ -3040,18 +3177,33 @@ class TiptapCollabProvider extends HocuspocusProvider {
         }
         // if the first comment of a thread is deleted we also
         // delete the thread itself as the source comment is gone
-        if (commentIndex === 0) {
+        if (commentIndex === 0 && (deleteThread || this.configuration.deleteThreadOnFirstCommentDelete)) {
             this.deleteThread(threadId);
             return;
         }
-        if (commentIndex > 0) {
-            thread.get('comments').delete(commentIndex);
-        }
+        const comment = thread.get('comments').get(commentIndex);
+        const newComment = new Y__namespace.Map();
+        newComment.set('id', comment.get('id'));
+        newComment.set('createdAt', comment.get('createdAt'));
+        newComment.set('updatedAt', (new Date()).toISOString());
+        newComment.set('deletedAt', (new Date()).toISOString());
+        newComment.set('data', comment.get('data'));
+        newComment.set('content', deleteContent ? null : comment.get('content'));
+        thread.get('deletedComments').push([newComment]);
+        thread.get('comments').delete(commentIndex);
         return thread.toJSON();
     }
+    /**
+     * Start watching threads for changes
+     * @param callback The callback function to be called when a thread changes
+     */
     watchThreads(callback) {
         this.getYThreads().observeDeep(callback);
     }
+    /**
+     * Stop watching threads for changes
+     * @param callback The callback function to be removed
+     */
     unwatchThreads(callback) {
         this.getYThreads().unobserveDeep(callback);
     }