@hocuspocus/provider 2.14.0 → 2.15.1-rc.0

package/dist/packages/provider/src/TiptapCollabProvider.d.ts

@@ -2,7 +2,7 @@ import type { AbstractType, YArrayEvent } from 'yjs';
 import * as Y from 'yjs';
 import { HocuspocusProvider, HocuspocusProviderConfiguration } from './HocuspocusProvider.js';
 import { TiptapCollabProviderWebsocket } from './TiptapCollabProviderWebsocket.js';
-import type { DeleteCommentOptions, TCollabComment, TCollabThread, THistoryVersion } from './types.js';
+import { type DeleteCommentOptions, type DeleteThreadOptions, type GetThreadsOptions, type TCollabComment, type TCollabThread, type THistoryVersion } from './types.js';
 export type TiptapCollabProviderConfiguration = Required<Pick<HocuspocusProviderConfiguration, 'name'>> & Partial<HocuspocusProviderConfiguration> & (Required<Pick<AdditionalTiptapCollabProviderConfiguration, 'websocketProvider'>> | Required<Pick<AdditionalTiptapCollabProviderConfiguration, 'appId'>> | Required<Pick<AdditionalTiptapCollabProviderConfiguration, 'baseUrl'>>) & Pick<AdditionalTiptapCollabProviderConfiguration, 'user'> & {
     /**
      * Pass `true` if you want to delete a thread when the first comment is deleted.
@@ -55,9 +55,10 @@ export declare class TiptapCollabProvider extends HocuspocusProvider {
     private getYThreads;
     /**
      * 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<Data, CommentData>(): TCollabThread<Data, CommentData>[];
+    getThreads<Data, CommentData>(options?: GetThreadsOptions): TCollabThread<Data, CommentData>[];
     /**
      * Find the index of a thread by its id
      * @param id The thread id
@@ -81,7 +82,7 @@ export declare class TiptapCollabProvider extends HocuspocusProvider {
      * @param data The thread data
      * @returns The created thread
      */
-    createThread(data: Omit<TCollabThread, 'id' | 'createdAt' | 'updatedAt' | 'comments' | 'deletedComments'>): TCollabThread;
+    createThread(data: Omit<TCollabThread, 'id' | 'createdAt' | 'updatedAt' | 'deletedAt' | 'comments' | 'deletedComments'>): TCollabThread;
     /**
      * Update a specific thread
      * @param id The thread id
@@ -92,11 +93,21 @@ export declare class TiptapCollabProvider extends HocuspocusProvider {
         resolvedAt: TCollabThread['resolvedAt'] | null;
     }>): TCollabThread;
     /**
-     * Delete a specific thread and all its comments
+     * 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: TCollabThread['id'], options?: DeleteThreadOptions): TCollabThread | null | undefined;
+    /**
+     * Tries to restore a deleted thread
      * @param id The thread id
-     * @returns void
+     * @returns The restored thread or null if the thread is not found
      */
-    deleteThread(id: TCollabThread['id']): void;
+    restoreThread(id: TCollabThread['id']): TCollabThread | null;
     /**
      * Returns comments from a thread, either deleted or not
      * @param threadId The thread id

package/dist/packages/provider/src/types.d.ts

@@ -88,6 +88,7 @@ export type TCollabThread<Data = any, CommentData = any> = {
     id: string;
     createdAt: number;
     updatedAt: number;
+    deletedAt: number | null;
     resolvedAt?: string;
     comments: TCollabComment<CommentData>[];
     deletedComments: TCollabComment<CommentData>[];
@@ -156,3 +157,30 @@ export type DeleteCommentOptions = {
      */
     deleteContent?: boolean;
 };
+export type DeleteThreadOptions = {
+    /**
+     * If `true`, will remove the comments on the thread,
+     * otherwise will only mark the thread as deleted
+     * and keep the comments
+     * @default false
+     */
+    deleteComments?: boolean;
+    /**
+     * If `true`, will forcefully remove the thread and all comments,
+     * otherwise will only mark the thread as deleted
+     * and keep the comments
+     * @default false
+     */
+    force?: boolean;
+};
+/**
+ * The type of thread
+ */
+export type ThreadType = 'archived' | 'unarchived';
+export type GetThreadsOptions = {
+    /**
+     * The types of threads to get
+     * @default ['unarchived']
+     */
+    types?: Array<ThreadType>;
+};

package/dist/packages/server/src/Hocuspocus.d.ts

@@ -95,7 +95,7 @@ export declare class Hocuspocus {
      * Runs the given callback after each hook.
      */
     hooks<T extends HookName>(name: T, payload: HookPayloadByName[T], callback?: Function | null): Promise<any>;
-    unloadDocument(document: Document): void;
+    unloadDocument(document: Document): Promise<any>;
     enableDebugging(): void;
     enableMessageLogging(): void;
     disableLogging(): void;

package/dist/tests/utils/newHocuspocusProvider.d.ts

@@ -1,3 +1,3 @@
-import { HocuspocusProvider, HocuspocusProviderConfiguration, HocuspocusProviderWebsocketConfiguration } from '@hocuspocus/provider';
+import { HocuspocusProvider, HocuspocusProviderConfiguration, HocuspocusProviderWebsocket, HocuspocusProviderWebsocketConfiguration } from '@hocuspocus/provider';
 import { Hocuspocus } from '@hocuspocus/server';
-export declare const newHocuspocusProvider: (server: Hocuspocus, options?: Partial<HocuspocusProviderConfiguration>, websocketOptions?: Partial<HocuspocusProviderWebsocketConfiguration>) => HocuspocusProvider;
+export declare const newHocuspocusProvider: (server: Hocuspocus, options?: Partial<HocuspocusProviderConfiguration>, websocketOptions?: Partial<HocuspocusProviderWebsocketConfiguration>, websocketProvider?: HocuspocusProviderWebsocket) => HocuspocusProvider;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hocuspocus/provider",
-  "version": "2.14.0",
+  "version": "2.15.1-rc.0",
   "description": "hocuspocus provider",
   "homepage": "https://hocuspocus.dev",
   "keywords": [
@@ -29,7 +29,7 @@
     "dist"
   ],
   "dependencies": {
-    "@hocuspocus/common": "^2.14.0",
+    "@hocuspocus/common": "^2.15.1-rc.0",
     "@lifeomic/attempt": "^3.0.2",
     "lib0": "^0.2.87",
     "ws": "^8.17.1"

package/src/TiptapCollabProvider.ts

@@ -7,9 +7,11 @@ import {
 } from './HocuspocusProvider.js'
 
 import { TiptapCollabProviderWebsocket } from './TiptapCollabProviderWebsocket.js'
-import type {
-  DeleteCommentOptions,
-  TCollabComment, TCollabThread, THistoryVersion,
+import {
+  type DeleteCommentOptions,
+  type DeleteThreadOptions,
+  type GetThreadsOptions,
+  type TCollabComment, type TCollabThread, type THistoryVersion,
 } from './types.js'
 
 const defaultDeleteCommentOptions: DeleteCommentOptions = {
@@ -17,6 +19,15 @@ const defaultDeleteCommentOptions: DeleteCommentOptions = {
   deleteThread: false,
 }
 
+const defaultGetThreadsOptions: GetThreadsOptions = {
+  types: ['unarchived'],
+}
+
+const defaultDeleteThreadOptions: DeleteThreadOptions = {
+  deleteComments: false,
+  force: false,
+}
+
 export type TiptapCollabProviderConfiguration =
   Required<Pick<HocuspocusProviderConfiguration, 'name'>> &
   Partial<HocuspocusProviderConfiguration> &
@@ -128,10 +139,29 @@ export class TiptapCollabProvider extends HocuspocusProvider {
 
   /**
    * 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<Data, CommentData>(): TCollabThread<Data, CommentData>[] {
-    return this.getYThreads().toJSON() as TCollabThread<Data, CommentData>[]
+  getThreads<Data, CommentData>(options?: GetThreadsOptions): TCollabThread<Data, CommentData>[] {
+    const { types } = { ...defaultGetThreadsOptions, ...options } as GetThreadsOptions
+
+    const threads = this.getYThreads().toJSON() as TCollabThread<Data, CommentData>[]
+
+    if (types?.includes('archived') && types?.includes('unarchived')) {
+      return threads
+    }
+
+    return threads.filter(currentThead => {
+      if (types?.includes('archived') && currentThead.deletedAt) {
+        return true
+      }
+
+      if (types?.includes('unarchived') && !currentThead.deletedAt) {
+        return true
+      }
+
+      return false
+    })
   }
 
   /**
@@ -144,7 +174,7 @@ export class TiptapCollabProvider extends HocuspocusProvider {
 
     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
@@ -190,7 +220,7 @@ export class TiptapCollabProvider extends HocuspocusProvider {
    * @param data The thread data
    * @returns The created thread
    */
-  createThread(data: Omit<TCollabThread, 'id' | 'createdAt' | 'updatedAt' | 'comments' | 'deletedComments'>) {
+  createThread(data: Omit<TCollabThread, 'id' | 'createdAt' | 'updatedAt' | 'deletedAt' | 'comments' | 'deletedComments'>) {
     let createdThread: TCollabThread = {} as TCollabThread
 
     this.document.transact(() => {
@@ -199,6 +229,7 @@ export class TiptapCollabProvider extends HocuspocusProvider {
       thread.set('createdAt', (new Date()).toISOString())
       thread.set('comments', new Y.Array())
       thread.set('deletedComments', new Y.Array())
+      thread.set('deletedAt', null)
 
       this.getYThreads().push([thread])
       createdThread = this.updateThread(String(thread.get('id')), data)
@@ -242,18 +273,57 @@ export class TiptapCollabProvider extends HocuspocusProvider {
   }
 
   /**
-   * Delete a specific thread and all its comments
+   * 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
-   * @returns void
+   * @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: TCollabThread['id']) {
+  deleteThread(id: TCollabThread['id'], options?: DeleteThreadOptions) {
+    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.Array())
+      thread.set('deletedComments', new Y.Array())
+    }
+
+    return thread.toJSON() as TCollabThread
+  }
+
+  /**
+   * 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: TCollabThread['id']) {
+    const index = this.getThreadIndex(id)
+
+    if (index === null) {
+      return null
+    }
+
+    const thread = this.getYThreads().get(index)
+
+    thread.set('deletedAt', null)
+
+    return thread.toJSON() as TCollabThread
   }
 
   /**
@@ -406,7 +476,11 @@ export class TiptapCollabProvider extends HocuspocusProvider {
     newComment.set('data', comment.get('data'))
     newComment.set('content', deleteContent ? null : comment.get('content'))
 
+    if (!thread.get('deletedComments')) {
+      thread.set('deletedComments', new Y.Array())
+    }
     thread.get('deletedComments').push([newComment])
+
     thread.get('comments').delete(commentIndex)
 
     return thread.toJSON() as TCollabThread

package/src/types.ts

@@ -110,6 +110,7 @@ export type TCollabThread<Data = any, CommentData = any> = {
   id: string;
   createdAt: number;
   updatedAt: number;
+  deletedAt: number | null;
   resolvedAt?: string; // (new Date()).toISOString()
   comments: TCollabComment<CommentData>[];
   deletedComments: TCollabComment<CommentData>[];
@@ -197,3 +198,34 @@ export type DeleteCommentOptions = {
    */
   deleteContent?: boolean
 }
+
+export type DeleteThreadOptions = {
+  /**
+   * If `true`, will remove the comments on the thread,
+   * otherwise will only mark the thread as deleted
+   * and keep the comments
+   * @default false
+   */
+  deleteComments?: boolean
+
+  /**
+   * If `true`, will forcefully remove the thread and all comments,
+   * otherwise will only mark the thread as deleted
+   * and keep the comments
+   * @default false
+   */
+  force?: boolean,
+}
+
+/**
+ * The type of thread
+ */
+export type ThreadType = 'archived' | 'unarchived'
+
+export type GetThreadsOptions = {
+  /**
+   * The types of threads to get
+   * @default ['unarchived']
+   */
+  types?: Array<ThreadType>
+}