simple-websocket

What is simple-websocket?

The simple-websocket npm package provides a straightforward API for creating WebSocket clients and servers. It is designed to be easy to use and lightweight, making it suitable for simple WebSocket communication tasks.

What are simple-websocket's main functionalities?

Creating a WebSocket Client

This code demonstrates how to create a WebSocket client using the simple-websocket package. It connects to a WebSocket server, sends a message upon connection, and listens for incoming messages and connection closure.

const SimpleWebSocket = require('simple-websocket');
const ws = new SimpleWebSocket('ws://example.com');

ws.on('connect', () => {
  console.log('Connected to server');
  ws.send('Hello, server!');
});

ws.on('data', (data) => {
  console.log('Received message:', data);
});

ws.on('close', () => {
  console.log('Connection closed');
});

Creating a WebSocket Server

This code demonstrates how to create a WebSocket server using the simple-websocket package. The server listens for new client connections, sends a welcome message to each client, and handles incoming messages and disconnections.

const SimpleWebSocketServer = require('simple-websocket/server');
const server = new SimpleWebSocketServer({ port: 3000 });

server.on('connection', (socket) => {
  console.log('New client connected');
  socket.send('Welcome, client!');

  socket.on('data', (data) => {
    console.log('Received message from client:', data);
  });

  socket.on('close', () => {
    console.log('Client disconnected');
  });
});

Other packages similar to simple-websocket

ws

The ws package is a popular WebSocket implementation for Node.js. It provides a comprehensive set of features for both WebSocket clients and servers, including support for extensions and subprotocols. Compared to simple-websocket, ws offers more advanced features and greater flexibility, but it may be more complex to use for simple tasks.

socket.io

Socket.io is a library that enables real-time, bidirectional, and event-based communication between web clients and servers. It abstracts WebSocket communication and provides fallbacks for older browsers. While it offers more features and robustness compared to simple-websocket, it is also heavier and more complex.

README

simple-websocket

Simple, EventEmitter API for WebSockets

features

• super simple API for working with WebSockets in the browser
• supports text and binary data
• node.js duplex stream interface
• client & server implementations

This module works in the browser with browserify, and it's used by WebTorrent!

install

npm install simple-websocket

real-world applications that use simple-websocket

• StudyNotes - Helping students learn faster and better
• WebTorrent - The streaming torrent app
• bittorrent-tracker - Simple, robust, BitTorrent tracker (client & server) implementation
• instant.io - Secure, anonymous, streaming file transfer
• lxjs-chat - Omegle chat clone
• [ your application here - send a PR ]

usage

var Socket = require('simple-websocket')

var socket = new Socket('wss://echo.websocket.org')
socket.on('connect', function () {
  // socket is connected!
  socket.send('sup!')
})

socket.on('data', function (data) {
  console.log('got message: ' + data)
})

Note: If you're NOT using browserify, then use the included standalone file simplewebsocket.min.js. This exports a SimpleWebsocket constructor on window. Wherever you see Socket in the examples below, substitute that with SimpleWebsocket.

api

socket = new Socket(url)

Create a new WebSocket connection to the server at url. This usage is a shorthand for socket = new Socket({ url: url })

socket = new Socket(opts)

If opts.url is specified as a string, then a WebSocket connection will be created to the server at opts.url.

If opts.socket is specified as an instance of a raw WebSocket object, then the given WebSocket object will be used and one will not be automatically be created internally. (This is for advanced users.)

Other properties on opts will be passed through to the underlying superclass, stream.Duplex.

socket.send(data)

Send text/binary data to the WebSocket server. data can be any of several types: String, Buffer (see buffer), TypedArrayView (Uint8Array, etc.), ArrayBuffer, or Blob (in browsers that support it).

Note: If this method is called before the socket.on('connect') event has fired, then data will be buffered.

socket.destroy([err])

Destroy and cleanup this websocket connection.

If the optional err parameter is passed, then it will be emitted as an 'error' event on the stream.

Socket.WEBSOCKET_SUPPORT

Detect WebSocket support in the javascript environment.

var Socket = require('simple-websocket')

if (Socket.WEBSOCKET_SUPPORT) {
  // websocket support!
} else {
  // fallback
}

events

socket.on('connect', function () {})

Fired when the websocket connection is ready to use.

socket.on('data', function (data) {})

Received a message from the websocket server.

data will be either a String or a Buffer/Uint8Array (see buffer). JSON strings will be parsed and the resulting Object emitted.

socket.on('close', function () {})

Called when the websocket connection has closed.

socket.on('error', function (err) {})

err is an Error object.

Fired when a fatal error occurs.

server

The server implementation is basically ws but the 'connection' event provides sockets that are instances of simple-websocket, i.e. they are duplex streams.

var Server = require('simple-websocket/server')

var server = new Server({ port: port }) // see `ws` docs for other options

server.on('connection', function (socket) {
  socket.write('pong')
  socket.on('data', function (data) {})
  socket.on('close', function () {})
  socket.on('error', function (err) {})
})

server.close()

license

MIT. Copyright (c) Feross Aboukhadijeh.