Norvell's Public Machinations
    Wondering what’s next for npm?Check out our public roadmap! »

    simple-websocket
    DefinitelyTyped icon, indicating that this package has TypeScript declarations provided by the separate @types/simple-websocket package

    9.1.0 • Public • Published

    simple-websocket travis npm downloads javascript style guide

    Simple, EventEmitter API for WebSockets

    Sauce Test Status

    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 package is used by WebTorrent.

    install

    npm install simple-websocket
    

    This package works in the browser with browserify. If you do not use a bundler, you can use the simplewebsocket.min.js standalone script directly in a <script> tag. This exports a SimpleWebsocket constructor on window. Wherever you see Socket in the examples below, substitute that with SimpleWebsocket.

    real-world applications that use simple-websocket

    • Virus Cafe - Make a friend in 2 minutes
    • WebTorrent - The streaming torrent app
    • StudyNotes - Helping students learn faster and better
    • bittorrent-tracker - Simple, robust, BitTorrent tracker (client & server) implementation
    • instant.io - Secure, anonymous, streaming file transfer
    • lxjs-chat - Omegle chat clone
    • Metastream - Watch streaming media with friends.
    • [ 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)
    })

    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.

    Install

    npm i simple-websocket

    DownloadsWeekly Downloads

    19,029

    Version

    9.1.0

    License

    MIT

    Unpacked Size

    99.9 kB

    Total Files

    6

    Last publish

    Collaborators

    • avatar