WIP: refactor to separate server and hocuspocus

[timoisik]

The following PR has breaking changes and is thus intended for a major release. Feedback is highly appreciated.

With this PR we moved the server logic into it's own server class (Server.ts). The server class then will use hocuspocus like you would mostly also use it as a library in other frameworks. This changes the way how you use hocuspocus though.

The goal is to make hocuspocus more flexible for further development. Without any server logic, hocuspocus could potentially run on edge services like cloudflare workers in the future. Also it is easier to extend the server with new functionalities such as additional APIs.

New usages

There are two ways on how you can use hocuspocus.

1. Usage within other frameworks like express (omitting most of express related stuff for better readability):

import { Logger } from '@hocuspocus/extension-logger'
import { Hocuspocus } from '@hocuspocus/server'

# ... other express stuff.
const { app } = expressWebsockets(express())

const hocuspocus = new Hocuspocus({
  extensions: [
    new Logger(),
  ],
})

app.ws('/:documentName', (websocket, request: any) => {
  const context = { user_id: 1234 }
  hocuspocus.handleConnection(websocket, request, context)
})

app.listen(1234, () => console.log('Listening on http://127.0.0.1:1234…'))

2. Usage with it's standalone server:

# Notice that you now import the Server and not Hocuspocus anymore.
import { Server } from '@hocuspocus/server'
import { Logger } from '@hocuspocus/extension-logger'

const server = new Server({
  port: 1234,
  extensions: [
    new Logger(),
  ],
})

server.listen()

We also changed the parameters of the .listen() method:

# Old:
async listen(
  portOrCallback: number | ((data: onListenPayload) => Promise<any>) | null = null,
  callback: any = null,
): Promise<Hocuspocus> { ... }

# New:
async listen(port?: number, callback: any = null): Promise<Hocuspocus> { ... }

This simplifies the usage of hocuspocus while you can still reach the same behavior as before. You are also still able to configure port and callbacks within the constructor of the Server.

Breaking

.configure() still exists on hocuspocus but not on the server. We also do not export instances anymore but only the classes. Thus, it is no longer possible to use hocuspocus like:

import { Server } from '@hocuspocus/server'

const server = Server.configure({...})

server.listen()

Because the .listen() method was removed from hocuspocus and moved to the server, you can no longer use it like:

import { Hocuspocus } from '@hocuspocus/server'

const server = new Hocuspocus({...})

server.listen()

TODO:

• Tests have to be updated for new usage.
• The configuration flow in the server is not optimal yet and should be improved.
• Perhaps server-specific configurations, such as port and address, can be removed from Hocuspocus configuration altogether and only kept in the server.
• Update documentation
• Write migration guide

[nperez0111]

This looks great to me, what do we need to get this merged?
We can put it in a branch to queue for next release if there are other breaking changes we want to make.

[sgehly]

Thanks so much for this @timoisik. Will be giving it a go shortly.

[Antoine4011]

Hey there, any news on this? Would love to deploy Hocuspocus on cloudflare :)