Visión general de la API

Antes de continuar, hagamos un recorrido rápido por la API proporcionada por Socket.IO:

API común

Los siguientes métodos están disponibles tanto para el cliente como para el servidor.

Emit básico

Como vimos en el paso #4, puedes enviar cualquier dato al otro lado con socket.emit():

Del cliente al servidor

Cliente

socket.emit('hello', 'world');

Servidor

io.on('connection', (socket) => {
  socket.on('hello', (arg) => {
    console.log(arg); // 'world'
  });
});

Del servidor al cliente

Servidor

io.on('connection', (socket) => {
  socket.emit('hello', 'world');
});

Cliente

socket.on('hello', (arg) => {
  console.log(arg); // 'world'
});

Puedes enviar cualquier número de argumentos, y todas las estructuras de datos serializables son soportadas, incluyendo objetos binarios como ArrayBuffer, TypedArray o Buffer (solo Node.js):

Del cliente al servidor

Cliente

socket.emit('hello', 1, '2', { 3: '4', 5: Uint8Array.from([6]) });

Servidor

io.on('connection', (socket) => {
  socket.on('hello', (arg1, arg2, arg3) => {
    console.log(arg1); // 1
    console.log(arg2); // '2'
    console.log(arg3); // { 3: '4', 5: <Buffer 06> }
  });
});

Del servidor al cliente

Servidor

io.on('connection', (socket) => {
  socket.emit('hello', 1, '2', { 3: '4', 5: Buffer.from([6]) });
});

Cliente

socket.on('hello', (arg1, arg2, arg3) => {
  console.log(arg1); // 1
  console.log(arg2); // '2'
  console.log(arg3); // { 3: '4', 5: ArrayBuffer (1) [ 6 ] }
});

consejo

No es necesario llamar JSON.stringify() en objetos:

// MAL
socket.emit('hello', JSON.stringify({ name: 'John' }));

// BIEN
socket.emit('hello', { name: 'John' });

Acknowledgements

Los eventos son geniales, pero en algunos casos puedes querer una API de solicitud-respuesta más clásica. En Socket.IO, esta característica se llama "acknowledgements".

Viene en dos sabores:

Con una función callback

Puedes añadir un callback como el último argumento del emit(), y este callback será llamado una vez que el otro lado haya reconocido el evento:

Del cliente al servidor

Cliente

socket.timeout(5000).emit('request', { foo: 'bar' }, 'baz', (err, response) => {
  if (err) {
    // el servidor no reconoció el evento en el tiempo dado
  } else {
    console.log(response.status); // 'ok'
  }
});

Servidor

io.on('connection', (socket) => {
  socket.on('request', (arg1, arg2, callback) => {
    console.log(arg1); // { foo: 'bar' }
    console.log(arg2); // 'baz'
    callback({
      status: 'ok'
    });
  });
});

Del servidor al cliente

Servidor

io.on('connection', (socket) => {
  socket.timeout(5000).emit('request', { foo: 'bar' }, 'baz', (err, response) => {
    if (err) {
      // el cliente no reconoció el evento en el tiempo dado
    } else {
      console.log(response.status); // 'ok'
    }
  });
});

Cliente

socket.on('request', (arg1, arg2, callback) => {
  console.log(arg1); // { foo: 'bar' }
  console.log(arg2); // 'baz'
  callback({
    status: 'ok'
  });
});

Con una Promise

El método emitWithAck() proporciona la misma funcionalidad, pero devuelve una Promise que se resolverá una vez que el otro lado reconozca el evento:

Del cliente al servidor

Cliente

try {
  const response = await socket.timeout(5000).emitWithAck('request', { foo: 'bar' }, 'baz');
  console.log(response.status); // 'ok'
} catch (e) {
  // el servidor no reconoció el evento en el tiempo dado
}

Servidor

io.on('connection', (socket) => {
  socket.on('request', (arg1, arg2, callback) => {
    console.log(arg1); // { foo: 'bar' }
    console.log(arg2); // 'baz'
    callback({
      status: 'ok'
    });
  });
});

Del servidor al cliente

Servidor

io.on('connection', async (socket) => {
  try {
    const response = await socket.timeout(5000).emitWithAck('request', { foo: 'bar' }, 'baz');
    console.log(response.status); // 'ok'
  } catch (e) {
    // el cliente no reconoció el evento en el tiempo dado
  }
});

Cliente

socket.on('request', (arg1, arg2, callback) => {
  console.log(arg1); // { foo: 'bar' }
  console.log(arg2); // 'baz'
  callback({
    status: 'ok'
  });
});

precaución

Los entornos que no soportan Promises (como Internet Explorer) necesitarán añadir un polyfill o usar un compilador como babel para usar esta característica (pero esto está fuera del alcance de este tutorial).

Listeners catch-all

Un listener catch-all es un listener que será llamado para cualquier evento entrante. Esto es útil para depurar tu aplicación:

Emisor

socket.emit('hello', 1, '2', { 3: '4', 5: Uint8Array.from([6]) });

Receptor

socket.onAny((eventName, ...args) => {
  console.log(eventName); // 'hello'
  console.log(args); // [ 1, '2', { 3: '4', 5: ArrayBuffer (1) [ 6 ] } ]
});

De manera similar, para paquetes salientes:

socket.onAnyOutgoing((eventName, ...args) => {
  console.log(eventName); // 'hello'
  console.log(args); // [ 1, '2', { 3: '4', 5: ArrayBuffer (1) [ 6 ] } ]
});

API del servidor

Broadcasting

Como vimos en el paso #5, puedes difundir un evento a todos los clientes conectados con io.emit():

io.emit('hello', 'world');

Rooms

En la jerga de Socket.IO, una room es un canal arbitrario al que los sockets pueden unirse y abandonar. Se puede usar para difundir eventos a un subconjunto de clientes conectados:

io.on('connection', (socket) => {
  // unirse a la sala llamada 'some room'
  socket.join('some room');
  
  // difundir a todos los clientes conectados en la sala
  io.to('some room').emit('hello', 'world');

  // difundir a todos los clientes conectados excepto los de la sala
  io.except('some room').emit('hello', 'world');

  // abandonar la sala
  socket.leave('some room');
});

¡Eso es básicamente todo! Para referencia futura, la API completa se puede encontrar aquí (servidor) y aquí (cliente).