@hocuspocus/extension-throttle 2.13.7 → 2.14.0

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

@@ -88,6 +88,8 @@ export declare class HocuspocusProvider extends EventEmitter {
     intervals: any;
     isConnected: boolean;
     constructor(configuration: HocuspocusProviderConfiguration);
+    boundDocumentUpdateHandler: (update: Uint8Array, origin: any) => void;
+    boundAwarenessUpdateHandler: ({ added, updated, removed }: any, origin: any) => void;
     boundBroadcastChannelSubscriber: (data: ArrayBuffer) => void;
     boundPageHide: () => void;
     boundOnOpen: (event: Event) => Promise<void>;

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

@@ -2,8 +2,13 @@ import type { AbstractType, YArrayEvent } from 'yjs';
 import * as Y from 'yjs';
 import { HocuspocusProvider, HocuspocusProviderConfiguration } from './HocuspocusProvider.js';
 import { TiptapCollabProviderWebsocket } from './TiptapCollabProviderWebsocket.js';
-import type { TCollabComment, TCollabThread, 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'>;
+import type { DeleteCommentOptions, TCollabComment, TCollabThread, 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.
+     */
+    deleteThreadOnFirstCommentDelete?: boolean;
+};
 export interface AdditionalTiptapCollabProviderConfiguration {
     /**
      * A Hocuspocus Cloud App ID, get one here: https://cloud.tiptap.dev
@@ -43,21 +48,103 @@ export declare class TiptapCollabProvider extends HocuspocusProvider {
     isAutoVersioning(): boolean;
     enableAutoVersioning(): 1;
     disableAutoVersioning(): 0;
+    /**
+     * Returns all users in the document as Y.Map objects
+     * @returns An array of Y.Map objects
+     */
     private getYThreads;
+    /**
+     * Finds all threads in the document and returns them as JSON objects
+     * @returns An array of threads as JSON objects
+     */
     getThreads<Data, CommentData>(): TCollabThread<Data, CommentData>[];
+    /**
+     * 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
+     */
     private getThreadIndex;
+    /**
+     * 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<Data, CommentData>(id: string): TCollabThread<Data, CommentData> | null;
+    /**
+     * 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
+     */
     private getYThread;
-    createThread(data: Omit<TCollabThread, 'id' | 'createdAt' | 'updatedAt' | 'comments'>): TCollabThread;
+    /**
+     * Create a new thread
+     * @param data The thread data
+     * @returns The created thread
+     */
+    createThread(data: Omit<TCollabThread, 'id' | 'createdAt' | 'updatedAt' | 'comments' | 'deletedComments'>): TCollabThread;
+    /**
+     * 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: TCollabThread['id'], data: Partial<Pick<TCollabThread, 'data'> & {
         resolvedAt: TCollabThread['resolvedAt'] | null;
     }>): TCollabThread;
+    /**
+     * Delete a specific thread and all its comments
+     * @param id The thread id
+     * @returns void
+     */
     deleteThread(id: TCollabThread['id']): void;
-    getThreadComments(threadId: TCollabThread['id']): TCollabComment[] | null;
-    getThreadComment(threadId: TCollabThread['id'], commentId: TCollabComment['id']): TCollabComment | null;
+    /**
+     * 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: TCollabThread['id'], includeDeleted?: boolean): TCollabComment[] | null;
+    /**
+     * 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: TCollabThread['id'], commentId: TCollabComment['id'], includeDeleted?: boolean): TCollabComment | 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: TCollabThread['id'], data: Omit<TCollabComment, 'id' | 'updatedAt' | 'createdAt'>): TCollabThread;
+    /**
+     * 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: TCollabThread['id'], commentId: TCollabComment['id'], data: Partial<Pick<TCollabComment, 'data' | 'content'>>): TCollabThread;
-    deleteComment(threadId: TCollabThread['id'], commentId: TCollabComment['id']): TCollabThread | null | undefined;
+    /**
+     * 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: TCollabThread['id'], commentId: TCollabComment['id'], options: DeleteCommentOptions): TCollabThread | null | undefined;
+    /**
+     * Start watching threads for changes
+     * @param callback The callback function to be called when a thread changes
+     */
     watchThreads(callback: () => void): void;
+    /**
+     * Stop watching threads for changes
+     * @param callback The callback function to be removed
+     */
     unwatchThreads(callback: () => void): void;
 }

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

@@ -90,12 +90,14 @@ export type TCollabThread<Data = any, CommentData = any> = {
     updatedAt: number;
     resolvedAt?: string;
     comments: TCollabComment<CommentData>[];
+    deletedComments: TCollabComment<CommentData>[];
     data: Data;
 };
 export type TCollabComment<Data = any> = {
     id: string;
-    createdAt: number;
-    updatedAt: number;
+    createdAt: string;
+    updatedAt: string;
+    deletedAt?: string;
     data: Data;
     content: any;
 };
@@ -144,3 +146,13 @@ export type THistoryDocumentRevertedEvent = {
     event: 'document.reverted';
     version: number;
 };
+export type DeleteCommentOptions = {
+    /**
+     * If `true`, the thread will also be deleted if the deleted comment was the first comment in the thread.
+     */
+    deleteThread?: boolean;
+    /**
+     * If `true`, will remove the content of the deleted comment
+     */
+    deleteContent?: boolean;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hocuspocus/extension-throttle",
-  "version": "2.13.7",
+  "version": "2.14.0",
   "description": "hocuspocus throttle extension",
   "homepage": "https://hocuspocus.dev",
   "keywords": [
@@ -28,7 +28,7 @@
     "dist"
   ],
   "dependencies": {
-    "@hocuspocus/server": "^2.13.7"
+    "@hocuspocus/server": "^2.14.0"
   },
   "gitHead": "b3454a4ca289a84ddfb7fa5607a2d4b8d5c37e9d"
 }