@hocuspocus/provider 3.4.4 → 3.4.5-rc.0

package/dist/index.d.ts

@@ -0,0 +1,558 @@
+import { CloseEvent } from "@hocuspocus/common";
+import * as Y from "yjs";
+import { Event, MessageEvent } from "ws";
+
+//#region node_modules/lib0/observable.d.ts
+/**
+ * Handles named events.
+ *
+ * @deprecated
+ * @template N
+ */
+declare class Observable<N> {
+  /**
+   * Some desc.
+   * @type {Map<N, any>}
+   */
+  _observers: Map<N, any>;
+  /**
+   * @param {N} name
+   * @param {function} f
+   */
+  on(name: N, f: Function): void;
+  /**
+   * @param {N} name
+   * @param {function} f
+   */
+  once(name: N, f: Function): void;
+  /**
+   * @param {N} name
+   * @param {function} f
+   */
+  off(name: N, f: Function): void;
+  /**
+   * Emit a named event. All registered event listeners that listen to the
+   * specified name will receive the event.
+   *
+   * @todo This should catch exceptions
+   *
+   * @param {N} name The event name.
+   * @param {Array<any>} args The arguments that are applied to the event listener.
+   */
+  emit(name: N, args: Array<any>): void;
+  destroy(): void;
+}
+//#endregion
+//#region node_modules/y-protocols/awareness.d.ts
+/**
+ * @typedef {Object} MetaClientState
+ * @property {number} MetaClientState.clock
+ * @property {number} MetaClientState.lastUpdated unix timestamp
+ */
+/**
+ * The Awareness class implements a simple shared state protocol that can be used for non-persistent data like awareness information
+ * (cursor, username, status, ..). Each client can update its own local state and listen to state changes of
+ * remote clients. Every client may set a state of a remote peer to `null` to mark the client as offline.
+ *
+ * Each client is identified by a unique client id (something we borrow from `doc.clientID`). A client can override
+ * its own state by propagating a message with an increasing timestamp (`clock`). If such a message is received, it is
+ * applied if the known state of that client is older than the new state (`clock < newClock`). If a client thinks that
+ * a remote client is offline, it may propagate a message with
+ * `{ clock: currentClientClock, state: null, client: remoteClient }`. If such a
+ * message is received, and the known clock of that client equals the received clock, it will override the state with `null`.
+ *
+ * Before a client disconnects, it should propagate a `null` state with an updated clock.
+ *
+ * Awareness states must be updated every 30 seconds. Otherwise the Awareness instance will delete the client state.
+ *
+ * @extends {Observable<string>}
+ */
+declare class Awareness extends Observable<string> {
+  /**
+   * @param {Y.Doc} doc
+   */
+  constructor(doc: Y.Doc);
+  doc: Y.Doc;
+  /**
+   * @type {number}
+   */
+  clientID: number;
+  /**
+   * Maps from client id to client state
+   * @type {Map<number, Object<string, any>>}
+   */
+  states: Map<number, {
+    [x: string]: any;
+  }>;
+  /**
+   * @type {Map<number, MetaClientState>}
+   */
+  meta: Map<number, MetaClientState>;
+  _checkInterval: any;
+  /**
+   * @return {Object<string,any>|null}
+   */
+  getLocalState(): {
+    [x: string]: any;
+  } | null;
+  /**
+   * @param {Object<string,any>|null} state
+   */
+  setLocalState(state: {
+    [x: string]: any;
+  } | null): void;
+  /**
+   * @param {string} field
+   * @param {any} value
+   */
+  setLocalStateField(field: string, value: any): void;
+  /**
+   * @return {Map<number,Object<string,any>>}
+   */
+  getStates(): Map<number, {
+    [x: string]: any;
+  }>;
+}
+type MetaClientState = {
+  clock: number;
+  /**
+   * unix timestamp
+   */
+  lastUpdated: number;
+};
+//#endregion
+//#region packages/provider/src/EventEmitter.d.ts
+declare class EventEmitter {
+  callbacks: {
+    [key: string]: Function[];
+  };
+  on(event: string, fn: Function): this;
+  protected emit(event: string, ...args: any): this;
+  off(event: string, fn?: Function): this;
+  removeAllListeners(): void;
+}
+//#endregion
+//#region node_modules/lib0/encoding.d.ts
+/**
+ * A BinaryEncoder handles the encoding to an Uint8Array.
+ */
+declare class Encoder {
+  cpos: number;
+  cbuf: Uint8Array;
+  /**
+   * @type {Array<Uint8Array>}
+   */
+  bufs: Array<Uint8Array>;
+}
+//#endregion
+//#region node_modules/lib0/decoding.d.ts
+/**
+ * A Decoder handles the decoding of an Uint8Array.
+ */
+declare class Decoder {
+  /**
+   * @param {Uint8Array} uint8Array Binary data to decode
+   */
+  constructor(uint8Array: Uint8Array);
+  /**
+   * Decoding target.
+   *
+   * @type {Uint8Array}
+   */
+  arr: Uint8Array;
+  /**
+   * Current decoding position.
+   *
+   * @type {number}
+   */
+  pos: number;
+}
+//#endregion
+//#region packages/provider/src/IncomingMessage.d.ts
+declare class IncomingMessage {
+  data: any;
+  encoder: Encoder;
+  decoder: Decoder;
+  constructor(data: any);
+  peekVarString(): string;
+  readVarUint(): MessageType;
+  readVarString(): string;
+  readVarUint8Array(): Uint8Array<ArrayBufferLike>;
+  writeVarUint(type: MessageType): void;
+  writeVarString(string: string): void;
+  writeVarUint8Array(data: Uint8Array): void;
+  length(): number;
+}
+//#endregion
+//#region packages/provider/src/OutgoingMessage.d.ts
+declare class OutgoingMessage implements OutgoingMessageInterface {
+  encoder: Encoder;
+  type?: MessageType;
+  constructor();
+  get(args: Partial<OutgoingMessageArguments>): Encoder | undefined;
+  toUint8Array(): Uint8Array<ArrayBufferLike>;
+}
+//#endregion
+//#region packages/provider/src/OutgoingMessages/AuthenticationMessage.d.ts
+declare class AuthenticationMessage extends OutgoingMessage {
+  type: MessageType;
+  description: string;
+  get(args: Partial<OutgoingMessageArguments>): Encoder;
+}
+//#endregion
+//#region packages/provider/src/OutgoingMessages/AwarenessMessage.d.ts
+declare class AwarenessMessage extends OutgoingMessage {
+  type: MessageType;
+  description: string;
+  get(args: Partial<OutgoingMessageArguments>): Encoder;
+}
+//#endregion
+//#region packages/provider/src/OutgoingMessages/QueryAwarenessMessage.d.ts
+declare class QueryAwarenessMessage extends OutgoingMessage {
+  type: MessageType;
+  description: string;
+  get(args: Partial<OutgoingMessageArguments>): Encoder;
+}
+//#endregion
+//#region packages/provider/src/OutgoingMessages/SyncStepOneMessage.d.ts
+declare class SyncStepOneMessage extends OutgoingMessage {
+  type: MessageType;
+  description: string;
+  get(args: Partial<OutgoingMessageArguments>): Encoder;
+}
+//#endregion
+//#region packages/provider/src/OutgoingMessages/SyncStepTwoMessage.d.ts
+declare class SyncStepTwoMessage extends OutgoingMessage {
+  type: MessageType;
+  description: string;
+  get(args: Partial<OutgoingMessageArguments>): Encoder;
+}
+//#endregion
+//#region packages/provider/src/OutgoingMessages/UpdateMessage.d.ts
+declare class UpdateMessage extends OutgoingMessage {
+  type: MessageType;
+  description: string;
+  get(args: Partial<OutgoingMessageArguments>): Encoder;
+}
+//#endregion
+//#region packages/provider/src/types.d.ts
+declare enum MessageType {
+  Sync = 0,
+  Awareness = 1,
+  Auth = 2,
+  QueryAwareness = 3,
+  Stateless = 5,
+  CLOSE = 7,
+  SyncStatus = 8
+}
+declare enum WebSocketStatus {
+  Connecting = "connecting",
+  Connected = "connected",
+  Disconnected = "disconnected"
+}
+type AuthorizedScope = "read-write" | "readonly";
+interface OutgoingMessageInterface {
+  encoder: Encoder;
+  type?: MessageType;
+}
+interface OutgoingMessageArguments {
+  documentName: string;
+  token: string;
+  document: Y.Doc;
+  awareness: Awareness;
+  clients: number[];
+  states: Map<number, {
+    [key: string]: any;
+  }>;
+  update: any;
+  payload: string;
+  encoder: Encoder;
+}
+interface Constructable<T> {
+  new (...args: any): T;
+}
+type ConstructableOutgoingMessage = Constructable<AuthenticationMessage> | Constructable<AwarenessMessage> | Constructable<QueryAwarenessMessage> | Constructable<SyncStepOneMessage> | Constructable<SyncStepTwoMessage> | Constructable<UpdateMessage>;
+type onAuthenticationFailedParameters = {
+  reason: string;
+};
+type onAuthenticatedParameters = {
+  scope: AuthorizedScope;
+};
+type onOpenParameters = {
+  event: Event;
+};
+type onMessageParameters = {
+  event: MessageEvent;
+  message: IncomingMessage;
+};
+type onOutgoingMessageParameters = {
+  message: OutgoingMessage;
+};
+type onStatusParameters = {
+  status: WebSocketStatus;
+};
+type onSyncedParameters = {
+  state: boolean;
+};
+type onUnsyncedChangesParameters = {
+  number: number;
+};
+type onDisconnectParameters = {
+  event: CloseEvent;
+};
+type onCloseParameters = {
+  event: CloseEvent;
+};
+type onAwarenessUpdateParameters = {
+  states: StatesArray;
+};
+type onAwarenessChangeParameters = {
+  states: StatesArray;
+};
+type onStatelessParameters = {
+  payload: string;
+};
+type StatesArray = {
+  clientId: number;
+  [key: string | number]: any;
+}[];
+//#endregion
+//#region packages/provider/src/HocuspocusProviderWebsocket.d.ts
+type HocuspocusWebSocket = WebSocket & {
+  identifier: string;
+};
+type HocusPocusWebSocket = HocuspocusWebSocket;
+type HocuspocusProviderWebsocketConfiguration = Required<Pick<CompleteHocuspocusProviderWebsocketConfiguration, "url">> & Partial<CompleteHocuspocusProviderWebsocketConfiguration>;
+interface CompleteHocuspocusProviderWebsocketConfiguration {
+  /**
+   * Whether to connect automatically when creating the provider instance. Default=true
+   */
+  autoConnect: boolean;
+  /**
+   * URL of your @hocuspocus/server instance
+   */
+  url: string;
+  /**
+   * By default, trailing slashes are removed from the URL. Set this to true
+   * to preserve trailing slashes if your server configuration requires them.
+   */
+  preserveTrailingSlash: boolean;
+  /**
+   * An optional WebSocket polyfill, for example for Node.js
+   */
+  WebSocketPolyfill: any;
+  /**
+   * Disconnect when no message is received for the defined amount of milliseconds.
+   */
+  messageReconnectTimeout: number;
+  /**
+   * The delay between each attempt in milliseconds. You can provide a factor to have the delay grow exponentially.
+   */
+  delay: number;
+  /**
+   * The initialDelay is the amount of time to wait before making the first attempt. This option should typically be 0 since you typically want the first attempt to happen immediately.
+   */
+  initialDelay: number;
+  /**
+   * The factor option is used to grow the delay exponentially.
+   */
+  factor: number;
+  /**
+   * The maximum number of attempts or 0 if there is no limit on number of attempts.
+   */
+  maxAttempts: number;
+  /**
+   * minDelay is used to set a lower bound of delay when jitter is enabled. This property has no effect if jitter is disabled.
+   */
+  minDelay: number;
+  /**
+   * The maxDelay option is used to set an upper bound for the delay when factor is enabled. A value of 0 can be provided if there should be no upper bound when calculating delay.
+   */
+  maxDelay: number;
+  /**
+   * If jitter is true then the calculated delay will be a random integer value between minDelay and the calculated delay for the current iteration.
+   */
+  jitter: boolean;
+  /**
+   * A timeout in milliseconds. If timeout is non-zero then a timer is set using setTimeout. If the timeout is triggered then future attempts will be aborted.
+   */
+  timeout: number;
+  handleTimeout: (() => Promise<unknown>) | null;
+  onOpen: (data: onOpenParameters) => void;
+  onConnect: () => void;
+  onMessage: (data: onMessageParameters) => void;
+  onOutgoingMessage: (data: onOutgoingMessageParameters) => void;
+  onStatus: (data: onStatusParameters) => void;
+  onDisconnect: (data: onDisconnectParameters) => void;
+  onClose: (data: onCloseParameters) => void;
+  onDestroy: () => void;
+  onAwarenessUpdate: (data: onAwarenessUpdateParameters) => void;
+  onAwarenessChange: (data: onAwarenessChangeParameters) => void;
+  /**
+   * Map of attached providers keyed by documentName.
+   */
+  providerMap: Map<string, HocuspocusProvider>;
+}
+declare class HocuspocusProviderWebsocket extends EventEmitter {
+  private messageQueue;
+  configuration: CompleteHocuspocusProviderWebsocketConfiguration;
+  webSocket: HocusPocusWebSocket | null;
+  webSocketHandlers: {
+    [key: string]: any;
+  };
+  shouldConnect: boolean;
+  status: WebSocketStatus;
+  lastMessageReceived: number;
+  identifier: number;
+  intervals: any;
+  connectionAttempt: {
+    resolve: (value?: any) => void;
+    reject: (reason?: any) => void;
+  } | null;
+  constructor(configuration: HocuspocusProviderWebsocketConfiguration);
+  receivedOnOpenPayload?: Event | undefined;
+  onOpen(event: Event): Promise<void>;
+  attach(provider: HocuspocusProvider): void;
+  detach(provider: HocuspocusProvider): void;
+  setConfiguration(configuration?: Partial<HocuspocusProviderWebsocketConfiguration>): void;
+  cancelWebsocketRetry?: () => void;
+  connect(): Promise<unknown>;
+  attachWebSocketListeners(ws: HocusPocusWebSocket, reject: Function): void;
+  cleanupWebSocket(): void;
+  createWebSocketConnection(): Promise<unknown>;
+  onMessage(event: MessageEvent): void;
+  resolveConnectionAttempt(): void;
+  stopConnectionAttempt(): void;
+  rejectConnectionAttempt(): void;
+  closeTries: number;
+  checkConnection(): void;
+  get serverUrl(): string;
+  get url(): string;
+  disconnect(): void;
+  send(message: any): void;
+  onClose({
+    event
+  }: onCloseParameters): void;
+  destroy(): void;
+}
+//#endregion
+//#region packages/provider/src/HocuspocusProvider.d.ts
+type HocuspocusProviderConfiguration = Required<Pick<CompleteHocuspocusProviderConfiguration, "name">> & Partial<CompleteHocuspocusProviderConfiguration> & ((Required<Pick<CompleteHocuspocusProviderWebsocketConfiguration, "url">> & Partial<Pick<CompleteHocuspocusProviderWebsocketConfiguration, "preserveTrailingSlash">>) | Required<Pick<CompleteHocuspocusProviderConfiguration, "websocketProvider">>);
+interface CompleteHocuspocusProviderConfiguration {
+  /**
+   * The identifier/name of your document
+   */
+  name: string;
+  /**
+   * The actual Y.js document
+   */
+  document: Y.Doc;
+  /**
+   * An Awareness instance to keep the presence state of all clients.
+   *
+   * You can disable sharing awareness information by passing `null`.
+   * Note that having no awareness information shared across all connections will break our ping checks
+   * and thus trigger reconnects. You should always have at least one Provider with enabled awareness per
+   * socket connection, or ensure that the Provider receives messages before running into `HocuspocusProviderWebsocket.messageReconnectTimeout`.
+   */
+  awareness: Awareness | null;
+  /**
+   * A token that’s sent to the backend for authentication purposes.
+   */
+  token: string | (() => string) | (() => Promise<string>) | null;
+  /**
+   * Hocuspocus websocket provider
+   */
+  websocketProvider: HocuspocusProviderWebsocket;
+  /**
+   * Force syncing the document in the defined interval.
+   */
+  forceSyncInterval: false | number;
+  onAuthenticated: (data: onAuthenticatedParameters) => void;
+  onAuthenticationFailed: (data: onAuthenticationFailedParameters) => void;
+  onOpen: (data: onOpenParameters) => void;
+  onConnect: () => void;
+  onStatus: (data: onStatusParameters) => void;
+  onMessage: (data: onMessageParameters) => void;
+  onOutgoingMessage: (data: onOutgoingMessageParameters) => void;
+  onSynced: (data: onSyncedParameters) => void;
+  onDisconnect: (data: onDisconnectParameters) => void;
+  onClose: (data: onCloseParameters) => void;
+  onDestroy: () => void;
+  onAwarenessUpdate: (data: onAwarenessUpdateParameters) => void;
+  onAwarenessChange: (data: onAwarenessChangeParameters) => void;
+  onStateless: (data: onStatelessParameters) => void;
+  onUnsyncedChanges: (data: onUnsyncedChangesParameters) => void;
+}
+declare class AwarenessError extends Error {
+  code: number;
+}
+declare class HocuspocusProvider extends EventEmitter {
+  configuration: CompleteHocuspocusProviderConfiguration;
+  isSynced: boolean;
+  unsyncedChanges: number;
+  isAuthenticated: boolean;
+  authorizedScope: AuthorizedScope | undefined;
+  manageSocket: boolean;
+  private _isAttached;
+  intervals: any;
+  constructor(configuration: HocuspocusProviderConfiguration);
+  boundDocumentUpdateHandler: (update: Uint8Array, origin: any) => void;
+  boundAwarenessUpdateHandler: ({
+    added,
+    updated,
+    removed
+  }: any, origin: any) => void;
+  boundPageHide: () => void;
+  boundOnOpen: (event: Event) => Promise<void>;
+  boundOnClose: () => void;
+  forwardConnect: () => this;
+  forwardStatus: (e: onStatusParameters) => this;
+  forwardClose: (e: onCloseParameters) => this;
+  forwardDisconnect: (e: onDisconnectParameters) => this;
+  forwardDestroy: () => this;
+  setConfiguration(configuration?: Partial<HocuspocusProviderConfiguration>): void;
+  get document(): Y.Doc;
+  get isAttached(): boolean;
+  get awareness(): Awareness | null;
+  get hasUnsyncedChanges(): boolean;
+  private resetUnsyncedChanges;
+  incrementUnsyncedChanges(): void;
+  decrementUnsyncedChanges(): void;
+  forceSync(): void;
+  pageHide(): void;
+  registerEventListeners(): void;
+  sendStateless(payload: string): void;
+  sendToken(): Promise<void>;
+  documentUpdateHandler(update: Uint8Array, origin: any): void;
+  awarenessUpdateHandler({
+    added,
+    updated,
+    removed
+  }: any, origin: any): void;
+  /**
+   * Indicates whether a first handshake with the server has been established
+   *
+   * Note: this does not mean all updates from the client have been persisted to the backend. For this,
+   * use `hasUnsyncedChanges`.
+   */
+  get synced(): boolean;
+  set synced(state: boolean);
+  receiveStateless(payload: string): void;
+  connect(): Promise<unknown>;
+  disconnect(): void;
+  onOpen(event: Event): Promise<void>;
+  getToken(): Promise<string | null>;
+  startSync(): void;
+  send(message: ConstructableOutgoingMessage, args: any): void;
+  onMessage(event: MessageEvent): void;
+  onClose(): void;
+  destroy(): void;
+  detach(): void;
+  attach(): void;
+  permissionDeniedHandler(reason: string): void;
+  authenticatedHandler(scope: string): void;
+  setAwarenessField(key: string, value: any): void;
+}
+//#endregion
+export { AuthorizedScope, AwarenessError, CompleteHocuspocusProviderConfiguration, CompleteHocuspocusProviderWebsocketConfiguration, Constructable, ConstructableOutgoingMessage, HocusPocusWebSocket, HocuspocusProvider, HocuspocusProviderConfiguration, HocuspocusProviderWebsocket, HocuspocusProviderWebsocketConfiguration, HocuspocusWebSocket, MessageType, OutgoingMessageArguments, OutgoingMessageInterface, StatesArray, WebSocketStatus, onAuthenticatedParameters, onAuthenticationFailedParameters, onAwarenessChangeParameters, onAwarenessUpdateParameters, onCloseParameters, onDisconnectParameters, onMessageParameters, onOpenParameters, onOutgoingMessageParameters, onStatelessParameters, onStatusParameters, onSyncedParameters, onUnsyncedChangesParameters };