Mulocal-socket NPM

mulocal-socket

Network socket emulation for mudb.

In mulocal-socket, no real network connections are established so no Web servers are needed, meaning any mudb applications using mulocal-socket can run entirely in a browser. This can be favorable to development in that

you can forget about restarting the server on changes
you can debug using the dev tools provided by browsers

example

var mudb = require('mudb')
var muLocalSocket = require('mulocal-socket')

var socketServer = muLocalSocket.createLocalSocketServer()
var muServer = new mudb.MuServer(socketServer)

muServer.start({ /* event handlers */ })

var socket = muLocalSocket.createLocalSocket()
var muClient = new mudb.MuClient(socket)

mClient.start({ /* event handlers */ })

1 install

npm i mulocal-socket

2 api

2.1 interfaces

Purely instructive types used to describe the API:

SessionId: string
Data: Uint8Array | string
SocketState: an enum consisting of three members
- SocketState.INIT
- SocketState.OPEN
- SocketState.CLOSED
SocketServerState: an enum consisting of three members
- SocketServerState.INIT
- SocketServerState.RUNNING
- SocketServerState.SHUTDOWN

2.2 `createLocalSocketServer()`

A factory returning a new instance of MuLocalSocketServer.

2.3 `createLocalSocket(spec)`

Spawns and associates two new instances of MuLocalSocket, then returns the client-side socket to be used to create a MuClient.

spec:object
- sessionId:SessionId: a unique session id used to identify a client
- server:MuLocalSocketServer: the socket server

Mostly you should only use the factory methods instead of the constructors.

2.4 `MuLocalSocketServer`

A MuLocalSocketServer is a pseudo socket server that can be used to create a MuServer. It does not create any server-side sockets and is only responsible for accumulating and closing sockets.

2.4.1 `state:SocketServerState`

A tri-valued field determining the availability of the socket server. It is initialized to SocketServerState.INIT.

2.4.2 `clients:MuLocalSocket[]`

Server-side sockets, one per client through which the server communicates with the client.

2.4.3 `start(spec)`

Hooks handlers and accumulates sockets. state is set to SocketServerState.RUNNING.

spec:object
- ready() called when the socket server is ready
- connection(socket:MuLocalSocket) called when a new server-side socket is added
- close(error?) called when the socket server is shut down

2.4.4 `close()`

Closes all sockets. state is set to SocketServerState.SHUTDOWN.

2.5 `MuLocalSocket(sessionId, server)`

A MuLocalSocket can either be a client-side or server-side socket and every two MuLocalSockets should be associated to form an exclusive pair. A MuLocalSocket can be used to create a MuClient when it is used as a client-side socket.

sessionId:SessionId: a unique session id used to identify a client
server:MuLocalSocketServer: the socket server

2.5.1 `sessionId:SessionId`

The unique session id identifying the client.

2.5.2 `state:SocketState`

A tri-valued field determining the availability of the socket. It is initialized to SocketState.INIT.

2.5.3 `open(spec)`

Hooks handlers and drains pending messages. state is set to SocketState.OPEN.

spec:object
- ready() called when the socket is ready to receive data
- message(data:Data, unreliable:boolean) called when receiving data
- close(error?) called when the socket is closed

2.5.4 `send(data, unreliable?)`

Sends data to the associated socket, which will be delivered either in order or out of order, depending on the value of unreliable.

data:Data data to be sent, can either be a JSON string or a Uint8Array
unreliable?:boolean optional, the data will be delivered out of order if set to true