README
socket.io-as-promised
Socket.IO middleware for supporting returning promises from handlers
Introduction
Allows you to more easily respond to your user's events by employing promises instead of callbacks. Supports Node >= 16.
It also helps with error handling, which is important since Socket.IO does not serialize Error
objects.
Install
$ npm install --save socket.io-as-promised
Usage
// server.js
const io = require('socket.io')();
const socketAsPromised = require('socket.io-as-promised');
io.attach(5000);
// on the main '/' namespare
io.use(socketAsPromised());
// on a custom namespace
io.of('/foo').use(socketAsPromised);
io.on('connection', socket => {
// Client will get a response with the string 'returned a promise'
socket.on('returns promise', () => Promise.resolve('returned a promise'));
// Client will get a response with the string 'returned from async function'
socket.on('returns from async', async () => 'returned from async function');
// Handles errors
socket.on('throws exception', () => Promise.reject({ error: 'thrown exception' }));
socket.on('throws from async', async () => { throw { error: 'thrown exception'; } });
// Error objects get turned into '{}' objects by socket io, so they need serializing
// use the handleError option documented in the API to handle this case
socket.on('throws error exception', () => Promise.reject(new Error('thrown exception')));
});
// client.js
const io = require('socket.io-client');
const client = io.connect('http://0.0.0.0:5000');
client.emit('returns promise', (err, res) => console.log(res)); // 'returned a promise'
client.emit('returns from async', (err, res) => console.log(res)); // 'returned from async'
client.emit('throws exception', err => console.log(err)); // { error: 'thrown exception' }
client.emit('throws from async', err => console.log(err)); // { error: 'thrown exception' }
client.emit('throws error exception', err => console.log(err)); // {}
API
socketAsPromised({ handleError } = {})
Type: function
Returns Socket.IO middleware. Monkeypatches socket.on
to wrap the handler function and support returned promises
handleError(err, event)
Type: function
, default: null
Optional argument, helps in case you want to ignore certain errors, or serialize other errors.
io.use(socketAsPromised({
handleError(err, event) {
return Promise.reject({ name: err.name, message: err.message });
// or:
throw { name: err.name, message: err.message };
// more fancy usage, filter out certain errors, return a
// generic error instead useful in case of errors like database
// connectivity that you don't want to reach the end user
const genericError = { name: 'GenericError', message: 'Something went wrong' };
if (isKnownError(err.name)) {
return Promise.reject({ name: err.name, message: err.message });
}
return Promise.reject(genericError);
}
}))
Tests
npm test
You can customize the port under which the test server runs (by default 8090):
TEST_PORT=4444 npm test
License
See the LICENSE file for license rights and limitations (MIT).