@hocuspocus/extension-database 1.0.0-alpha.2 → 1.0.0-alpha.21

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

@@ -1,18 +1,26 @@
 import { Awareness } from 'y-protocols/awareness';
 import * as Y from 'yjs';
 import { Encoder } from 'lib0/encoding';
+import type { Event, CloseEvent, MessageEvent } from 'ws';
 import { AuthenticationMessage } from './OutgoingMessages/AuthenticationMessage';
 import { AwarenessMessage } from './OutgoingMessages/AwarenessMessage';
 import { QueryAwarenessMessage } from './OutgoingMessages/QueryAwarenessMessage';
 import { SyncStepOneMessage } from './OutgoingMessages/SyncStepOneMessage';
 import { SyncStepTwoMessage } from './OutgoingMessages/SyncStepTwoMessage';
 import { UpdateMessage } from './OutgoingMessages/UpdateMessage';
+import { IncomingMessage } from './IncomingMessage';
+import { OutgoingMessage } from './OutgoingMessage';
 export declare enum MessageType {
     Sync = 0,
     Awareness = 1,
     Auth = 2,
     QueryAwareness = 3
 }
+export declare enum WebSocketStatus {
+    Connecting = "connecting",
+    Connected = "connected",
+    Disconnected = "disconnected"
+}
 export interface OutgoingMessageInterface {
     encoder: Encoder;
     type?: MessageType;
@@ -32,3 +40,38 @@ export interface Constructable<T> {
     new (...args: any): T;
 }
 export declare type ConstructableOutgoingMessage = Constructable<AuthenticationMessage> | Constructable<AwarenessMessage> | Constructable<QueryAwarenessMessage> | Constructable<SyncStepOneMessage> | Constructable<SyncStepTwoMessage> | Constructable<UpdateMessage>;
+export declare type onAuthenticationFailedParameters = {
+    reason: string;
+};
+export declare type onOpenParameters = {
+    event: Event;
+};
+export declare type onMessageParameters = {
+    event: MessageEvent;
+    message: IncomingMessage;
+};
+export declare type onOutgoingMessageParameters = {
+    message: OutgoingMessage;
+};
+export declare type onStatusParameters = {
+    status: WebSocketStatus;
+};
+export declare type onSyncedParameters = {
+    state: boolean;
+};
+export declare type onDisconnectParameters = {
+    event: CloseEvent;
+};
+export declare type onCloseParameters = {
+    event: CloseEvent;
+};
+export declare type onAwarenessUpdateParameters = {
+    states: StatesArray;
+};
+export declare type onAwarenessChangeParameters = {
+    states: StatesArray;
+};
+export declare type StatesArray = {
+    clientId: number;
+    [key: string | number]: any;
+}[];

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

@@ -2,10 +2,10 @@
 import AsyncLock from 'async-lock';
 import WebSocket from 'ws';
 import { IncomingMessage as HTTPIncomingMessage } from 'http';
+import { CloseEvent } from '@hocuspocus/common';
 import Document from './Document';
-import { CloseEvent } from './types';
-import { MessageLogger } from './Debugger';
-declare class Connection {
+import { Debugger } from './Debugger';
+export declare class Connection {
     webSocket: WebSocket;
     context: any;
     document: Document;
@@ -17,15 +17,19 @@ declare class Connection {
     socketId: string;
     lock: AsyncLock;
     readOnly: Boolean;
-    debugger: MessageLogger;
+    logger: Debugger;
     /**
      * Constructor.
      */
-    constructor(connection: WebSocket, request: HTTPIncomingMessage, document: Document, timeout: number, socketId: string, context: any, readOnly?: boolean);
+    constructor(connection: WebSocket, request: HTTPIncomingMessage, document: Document, timeout: number, socketId: string, context: any, readOnly: boolean | undefined, logger: Debugger);
     /**
      * Set a callback that will be triggered when the connection is closed
      */
     onClose(callback: (document: Document) => void): Connection;
+    /**
+     * Set a callback that will be triggered before an message is handled
+     */
+    beforeHandleMessage(callback: (payload: Document, update: Uint8Array) => Promise<any>): Connection;
     /**
      * Send the given message
      */
@@ -49,6 +53,13 @@ declare class Connection {
      * @private
      */
     private handleMessage;
+    /**
+     * Handle a ws instance error, which is required to prevent
+     * the server from crashing when one happens
+     * See https://github.com/websockets/ws/issues/1777#issuecomment-660803472
+     * @private
+     */
+    private handleError;
     /**
      * Get the underlying connection instance
      * @deprecated

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

@@ -1,4 +1,4 @@
-export declare class MessageLogger {
+export declare class Debugger {
     logs: any[];
     listen: boolean;
     output: boolean;
@@ -12,4 +12,3 @@ export declare class MessageLogger {
         logs: any[];
     };
 }
-export declare const Debugger: MessageLogger;

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

@@ -3,20 +3,24 @@ import { Awareness } from 'y-protocols/awareness';
 import { Doc } from 'yjs';
 import { mutex } from 'lib0/mutex.js';
 import Connection from './Connection';
-import { MessageLogger } from './Debugger';
-declare class Document extends Doc {
+import { Debugger } from './Debugger';
+export declare class Document extends Doc {
     awareness: Awareness;
     callbacks: {
         onUpdate: (document: Document, connection: Connection, update: Uint8Array) => void;
     };
-    connections: Map<any, any>;
+    connections: Map<WebSocket, {
+        clients: Set<any>;
+        connection: Connection;
+    }>;
     name: string;
     mux: mutex;
-    debugger: MessageLogger;
+    logger: Debugger;
+    isLoading: boolean;
     /**
      * Constructor.
      */
-    constructor(name: string);
+    constructor(name: string, logger: Debugger, yDocOptions: {});
     /**
      * Check if the Document is empty
      */

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

@@ -1,24 +1,32 @@
 /// <reference types="node" />
-import WebSocket, { WebSocketServer } from 'ws';
+import WebSocket, { AddressInfo, WebSocketServer } from 'ws';
 import { IncomingMessage, Server as HTTPServer } from 'http';
-import { Configuration, Hook } from './types';
-import { MessageLogger } from './Debugger';
+import { Configuration, HookName, HookPayload } from './types';
+import Document from './Document';
+import { Debugger } from './Debugger';
 import { onListenPayload } from '.';
 export declare const defaultConfiguration: {
     name: null;
     port: number;
     timeout: number;
+    debounce: number;
+    maxDebounce: number;
     quiet: boolean;
+    yDocOptions: {
+        gc: boolean;
+        gcFilter: () => boolean;
+    };
 };
 /**
  * Hocuspocus Server
  */
 export declare class Hocuspocus {
     configuration: Configuration;
-    documents: Map<any, any>;
+    documents: Map<string, Document>;
     httpServer?: HTTPServer;
     webSocketServer?: WebSocketServer;
-    debugger: MessageLogger;
+    debugger: Debugger;
+    constructor(configuration?: Partial<Configuration>);
     /**
      * Configure the server
      */
@@ -27,7 +35,11 @@ export declare class Hocuspocus {
     /**
      * Start the server
      */
-    listen(portOrCallback?: number | ((data: onListenPayload) => Promise<any>) | null, callback?: any): Promise<void>;
+    listen(portOrCallback?: number | ((data: onListenPayload) => Promise<any>) | null, callback?: any): Promise<Hocuspocus>;
+    get address(): AddressInfo;
+    get URL(): string;
+    get webSocketURL(): string;
+    get httpURL(): string;
     private showStartScreen;
     /**
      * Get the total number of active documents
@@ -46,37 +58,47 @@ export declare class Hocuspocus {
      */
     destroy(): Promise<any>;
     /**
-     * Handle the incoming WebSocket connection
+     * The `handleConnection` method receives incoming WebSocket connections,
+     * runs all hooks:
+     *
+     *  - onConnect for all connections
+     *  - onAuthenticate only if required
+     *
+     * … and if nothings fails it’ll fully establish the connection and
+     * load the Document then.
      */
     handleConnection(incoming: WebSocket, request: IncomingMessage, documentName: string, context?: any): void;
     /**
      * Handle update of the given document
-     * @private
      */
     private handleDocumentUpdate;
+    timers: Map<string, {
+        timeout: NodeJS.Timeout;
+        start: number;
+    }>;
+    /**
+     * debounce the given function, using the given identifier
+     */
+    debounce(id: string, func: Function, immediately?: boolean): void;
     /**
      * Create a new document by the given request
-     * @private
      */
     private createDocument;
     /**
      * Create a new connection by the given request and document
-     * @private
      */
     private createConnection;
     /**
-     * Run the given hook on all configured extensions
-     * Runs the given callback after each hook
+     * Run the given hook on all configured extensions.
+     * Runs the given callback after each hook.
      */
-    hooks(name: Hook, payload: any, callback?: Function | null): Promise<any>;
+    hooks(name: HookName, payload: HookPayload, callback?: Function | null): Promise<any>;
     /**
      * Get parameters by the given request
-     * @private
      */
     private static getParameters;
     /**
      * Get document name by the given request
-     * @private
      */
     private getDocumentNameFromRequest;
     enableDebugging(): void;

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

@@ -1,10 +1,13 @@
+import { Awareness } from 'y-protocols/awareness';
 import Connection from './Connection';
 import { IncomingMessage } from './IncomingMessage';
-import { MessageLogger } from './Debugger';
+import { Debugger } from './Debugger';
+import Document from './Document';
 export declare class MessageReceiver {
     message: IncomingMessage;
-    debugger: MessageLogger;
-    constructor(message: IncomingMessage);
-    apply(connection: Connection): void;
-    readSyncMessage(message: IncomingMessage, connection: Connection): 0 | 1 | 2;
+    logger: Debugger;
+    constructor(message: IncomingMessage, logger: Debugger);
+    apply(document: Document, connection?: Connection, reply?: (message: Uint8Array) => void): void;
+    readSyncMessage(message: IncomingMessage, document: Document, connection?: Connection, reply?: (message: Uint8Array) => void, requestFirstSync?: boolean): 0 | 2 | 1;
+    applyQueryAwarenessMessage(awareness: Awareness, reply?: (message: Uint8Array) => void): void;
 }

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

@@ -7,7 +7,9 @@ export declare class OutgoingMessage {
     category?: string;
     constructor();
     createSyncMessage(): OutgoingMessage;
+    createSyncReplyMessage(): OutgoingMessage;
     createAwarenessUpdateMessage(awareness: Awareness, changedClients?: Array<any>): OutgoingMessage;
+    writeQueryAwareness(): OutgoingMessage;
     writeAuthenticated(): OutgoingMessage;
     writePermissionDenied(reason: string): OutgoingMessage;
     writeFirstSyncStepFor(document: Document): OutgoingMessage;

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

@@ -1,2 +1,8 @@
+export * from './Connection';
+export * from './Debugger';
+export * from './Document';
 export * from './Hocuspocus';
+export * from './IncomingMessage';
+export * from './MessageReceiver';
+export * from './OutgoingMessage';
 export * from './types';

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

@@ -1,56 +1,56 @@
 /// <reference types="node" />
 import { IncomingHttpHeaders, IncomingMessage, ServerResponse } from 'http';
 import { URLSearchParams } from 'url';
-import { Socket } from 'net';
+import { Awareness } from 'y-protocols/awareness';
 import Document from './Document';
 import { Hocuspocus } from './Hocuspocus';
 export declare enum MessageType {
     Unknown = -1,
     Sync = 0,
     Awareness = 1,
-    Auth = 2
-}
-/**
- * State of the WebSocket connection.
- * https://developer.mozilla.org/de/docs/Web/API/WebSocket/readyState
- */
-export declare enum WsReadyStates {
-    Connecting = 0,
-    Open = 1,
-    Closing = 2,
-    Closed = 3
+    Auth = 2,
+    QueryAwareness = 3,
+    SyncReply = 4
 }
 export interface AwarenessUpdate {
     added: Array<any>;
     updated: Array<any>;
     removed: Array<any>;
 }
-export interface ConnectionConfig {
+export interface ConnectionConfiguration {
     readOnly: boolean;
     requiresAuthentication: boolean;
     isAuthenticated: boolean;
 }
 export interface Extension {
-    onAuthenticate?(data: onAuthenticatePayload): Promise<any>;
-    onChange?(data: onChangePayload): Promise<any>;
-    onConnect?(data: onConnectPayload): Promise<any>;
+    priority?: number;
     onConfigure?(data: onConfigurePayload): Promise<any>;
+    onListen?(data: onListenPayload): Promise<any>;
+    onUpgrade?(data: onUpgradePayload): Promise<any>;
+    onConnect?(data: onConnectPayload): Promise<any>;
+    connected?(data: connectedPayload): Promise<any>;
+    onAuthenticate?(data: onAuthenticatePayload): Promise<any>;
     /**
      * @deprecated onCreateDocument is deprecated, use onLoadDocument instead
      */
     onCreateDocument?(data: onLoadDocumentPayload): Promise<any>;
     onLoadDocument?(data: onLoadDocumentPayload): Promise<any>;
-    onDestroy?(data: onDestroyPayload): Promise<any>;
-    onDisconnect?(data: onDisconnectPayload): Promise<any>;
-    onListen?(data: onListenPayload): Promise<any>;
+    afterLoadDocument?(data: onLoadDocumentPayload): Promise<any>;
+    beforeHandleMessage?(data: beforeHandleMessagePayload): Promise<any>;
+    onChange?(data: onChangePayload): Promise<any>;
+    onStoreDocument?(data: onStoreDocumentPayload): Promise<any>;
+    afterStoreDocument?(data: afterStoreDocumentPayload): Promise<any>;
+    onAwarenessUpdate?(data: onAwarenessUpdatePayload): Promise<any>;
     onRequest?(data: onRequestPayload): Promise<any>;
-    onUpgrade?(data: onUpgradePayload): Promise<any>;
+    onDisconnect?(data: onDisconnectPayload): Promise<any>;
+    onDestroy?(data: onDestroyPayload): Promise<any>;
 }
-export declare type Hook = 'onAuthenticate' | 'onChange' | 'onConnect' | 'onConfigure' | 
+export declare type HookName = 'onConfigure' | 'onListen' | 'onUpgrade' | 'onConnect' | 'connected' | 'onAuthenticate' | 
 /**
  * @deprecated onCreateDocument is deprecated, use onLoadDocument instead
  */
-'onCreateDocument' | 'onLoadDocument' | 'onDestroy' | 'onDisconnect' | 'onListen' | 'onRequest' | 'onUpgrade';
+'onCreateDocument' | 'onLoadDocument' | 'afterLoadDocument' | 'beforeHandleMessage' | 'onChange' | 'onStoreDocument' | 'afterStoreDocument' | 'onAwarenessUpdate' | 'onRequest' | 'onDisconnect' | 'onDestroy';
+export declare type HookPayload = onConfigurePayload | onListenPayload | onUpgradePayload | onConnectPayload | connectedPayload | onAuthenticatePayload | onLoadDocumentPayload | onChangePayload | onStoreDocumentPayload | afterStoreDocumentPayload | onAwarenessUpdatePayload | onRequestPayload | onDisconnectPayload | onDestroyPayload;
 export interface Configuration extends Extension {
     /**
      * A name for the instance, used for logging.
@@ -68,18 +68,35 @@ export interface Configuration extends Extension {
      * Defines in which interval the server sends a ping, and closes the connection when no pong is sent back.
      */
     timeout: number;
+    /**
+     * Debounces the call of the `onStoreDocument` hook for the given amount of time in ms.
+     * Otherwise every single update would be persisted.
+     */
+    debounce: number;
+    /**
+     * Makes sure to call `onStoreDocument` at least in the given amount of time (ms).
+     */
+    maxDebounce: number;
     /**
      * By default, the servers show a start screen. If passed false, the server will start quietly.
      */
     quiet: boolean;
+    /**
+     * options to pass to the ydoc document
+     */
+    yDocOptions: {
+        gc: boolean;
+        gcFilter: () => boolean;
+    };
     /**
      * Function which returns the (customized) document name based on the request
      */
-    getDocumentName?(data: {
-        documentName: string;
-        request: IncomingMessage;
-        requestParameters: URLSearchParams;
-    }): string | Promise<string>;
+    getDocumentName?(data: getDocumentNamePayload): string | Promise<string>;
+}
+export interface getDocumentNamePayload {
+    documentName: string;
+    request: IncomingMessage;
+    requestParameters: URLSearchParams;
 }
 export interface onAuthenticatePayload {
     documentName: string;
@@ -88,7 +105,7 @@ export interface onAuthenticatePayload {
     requestParameters: URLSearchParams;
     socketId: string;
     token: string;
-    connection: ConnectionConfig;
+    connection: ConnectionConfiguration;
 }
 export interface onConnectPayload {
     documentName: string;
@@ -97,7 +114,16 @@ export interface onConnectPayload {
     requestHeaders: IncomingHttpHeaders;
     requestParameters: URLSearchParams;
     socketId: string;
-    connection: ConnectionConfig;
+    connection: ConnectionConfiguration;
+}
+export interface connectedPayload {
+    documentName: string;
+    instance: Hocuspocus;
+    request: IncomingMessage;
+    requestHeaders: IncomingHttpHeaders;
+    requestParameters: URLSearchParams;
+    socketId: string;
+    connection: ConnectionConfiguration;
 }
 export interface onLoadDocumentPayload {
     context: any;
@@ -107,7 +133,17 @@ export interface onLoadDocumentPayload {
     requestHeaders: IncomingHttpHeaders;
     requestParameters: URLSearchParams;
     socketId: string;
-    connection: ConnectionConfig;
+    connection: ConnectionConfiguration;
+}
+export interface afterLoadDocumentPayload {
+    context: any;
+    document: Document;
+    documentName: string;
+    instance: Hocuspocus;
+    requestHeaders: IncomingHttpHeaders;
+    requestParameters: URLSearchParams;
+    socketId: string;
+    connection: ConnectionConfiguration;
 }
 export interface onChangePayload {
     clientsCount: number;
@@ -120,6 +156,62 @@ export interface onChangePayload {
     update: Uint8Array;
     socketId: string;
 }
+export interface beforeHandleMessagePayload {
+    clientsCount: number;
+    context: any;
+    document: Document;
+    documentName: string;
+    instance: Hocuspocus;
+    requestHeaders: IncomingHttpHeaders;
+    requestParameters: URLSearchParams;
+    update: Uint8Array;
+    socketId: string;
+}
+export interface onStoreDocumentPayload {
+    clientsCount: number;
+    context: any;
+    document: Document;
+    documentName: string;
+    instance: Hocuspocus;
+    requestHeaders: IncomingHttpHeaders;
+    requestParameters: URLSearchParams;
+    socketId: string;
+}
+export interface afterStoreDocumentPayload extends onStoreDocumentPayload {
+}
+export interface onAwarenessUpdatePayload {
+    clientsCount: number;
+    context: any;
+    document: Document;
+    documentName: string;
+    instance: Hocuspocus;
+    requestHeaders: IncomingHttpHeaders;
+    requestParameters: URLSearchParams;
+    update: Uint8Array;
+    socketId: string;
+    added: number[];
+    updated: number[];
+    removed: number[];
+    awareness: Awareness;
+    states: StatesArray;
+}
+export declare type StatesArray = {
+    clientId: number;
+    [key: string | number]: any;
+}[];
+export interface fetchPayload {
+    context: any;
+    document: Document;
+    documentName: string;
+    instance: Hocuspocus;
+    requestHeaders: IncomingHttpHeaders;
+    requestParameters: URLSearchParams;
+    socketId: string;
+    connection: ConnectionConfiguration;
+}
+export interface storePayload extends onStoreDocumentPayload {
+    state: Buffer;
+}
 export interface onDisconnectPayload {
     clientsCount: number;
     context: any;
@@ -136,24 +228,21 @@ export interface onRequestPayload {
     instance: Hocuspocus;
 }
 export interface onUpgradePayload {
-    head: any;
     request: IncomingMessage;
-    socket: Socket;
+    socket: any;
+    head: any;
     instance: Hocuspocus;
 }
 export interface onListenPayload {
+    instance: Hocuspocus;
+    configuration: Configuration;
     port: number;
 }
 export interface onDestroyPayload {
     instance: Hocuspocus;
 }
 export interface onConfigurePayload {
+    instance: Hocuspocus;
     configuration: Configuration;
     version: string;
-    yjsVersion: string;
-    instance: Hocuspocus;
-}
-export interface CloseEvent {
-    code: number;
-    reason: string;
 }

package/dist/tests/extension-database/fetch.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tests/extension-logger/onListen.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tests/extension-redis/closeConnections.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tests/extension-redis/getConnectionCount.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tests/extension-redis/getDocumentsCount.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tests/extension-redis/onAwarenessChange.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tests/extension-redis/onChange.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tests/extension-redis/onStoreDocument.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tests/extension-throttle/configuration.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tests/provider/configuration.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tests/provider/observe.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tests/provider/observeDeep.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tests/provider/onAuthenticated.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tests/provider/onAuthenticationFailed.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tests/provider/onAwarenessChange.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tests/provider/onAwarenessUpdate.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tests/provider/onClose.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tests/provider/onConnect.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tests/provider/onDisconnect.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tests/provider/onMessage.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tests/provider/onOpen.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tests/provider/onSynced.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tests/server/address.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tests/server/afterStoreDocument.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tests/server/beforeHandleMessage.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tests/server/closeConnections.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tests/server/getConnectionsCount.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tests/server/getDocumentName.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tests/server/getDocumentsCount.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tests/server/getMessageLogs.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tests/server/listen.d.ts

@@ -0,0 +1 @@
+export {};