Client guide ​

Installation ​

npm install @jcbuisson/express-x socket.io-client

Example ​

import { io } from 'socket.io-client'
import { createClient } from '@jcbuisson/express-x/client'

const socket = io('http://localhost:8000', { transports: ['websocket'] })

const app = createClient(socket)

const user = await app.service('user').findUnique({ where: { id: 22 } })

app.service('user').on('create', (user) => {
   console.log('CREATE USER event', user)
})
...

app.service(name).call(action, ...args) is available for remote method names that collide with local proxy methods, such as toString or constructor.

Configuration ​

createClient(socket, options) ​

Options passed to createClient:

Socket.io connection options (path, reconnection delays, extra headers, etc.) are passed directly to io():

const socket = io('http://localhost:8000', {
   path: '/myapp-socket.io/',
   transports: ['websocket'],
   reconnectionDelay: 1000,
   reconnectionDelayMax: 10000,
   extraHeaders: {
      'bearer-token': 'mytoken'
   },
})

Service options ​

Options can be passed per-service to app.service(name, options):

timeout (integer) ​

An exception is thrown if a service request doesn't get an answer after timeout ms. Default: 20000

app.service('mail', { timeout: 10000 }).send(...)

volatile (boolean) ​

When volatile is set, a service request is not buffered if the connection is down — it will simply not be emitted. Default: false

Connection lifecycle ​

// called when socket connects or reconnects
app.addConnectListener((socket) => { ... })
app.removeConnectListener(func)

// called when socket disconnects
app.addDisconnectListener((socket) => { ... })
app.removeDisconnectListener(func)

// called on connection error
app.addErrorListener((socket) => { ... })
app.removeErrorListener(func)

Handling exceptions ​

When an exception occurs during a service method execution on the server, the error is serialized and sent back to the client so that it can be caught:

try {
   const { userId } = await app.service('auth').login(email, password)
   ...
} catch(err) {
   if (err.code === 'wrong-credentials') {
      ...
   }
}

Use EXError on the server to attach a structured code to errors.

Publish-subscribe ​

Service events callbacks ​

When a service event is sent by the server, the client can set a callback. In the following example, the callback is executed when the client receives a 'create' event from the 'user' service. Its only argument is the data returned by the method called — here the created user.

app.service('user').on('create', (createdUser) => {
   ...
})

Application event callbacks ​

When an application event is sent by the server, the client can set a callback with app.on(). In the following example, the callback is executed whenever the application-wide event 'expireAt' is sent to the client:

app.on('expireAt', (date) => {
   ...
})