ws-socket-stream

A fast, reliable and bidirectional stream interface based on ws

Usage no npm install needed!

<script type="module">
  import wsSocketStream from 'https://cdn.skypack.dev/ws-socket-stream';
</script>

README

ws-socket-stream

ws-socket-stream is a npm package for streaming data between clients and servers. To be precise, one can view ws-socket-stream as an extension of the ws library with the capability of transmitting large files efficiently via Node.js streams. The SocketStreamClient and SocketStreamServer classes extend from ws and ws.Server, respectively, but with additional streaming functionalities.

Installation

npm install ws-socket-stream

API Reference

Class: SocketStreamClient

  • extends WebSocket
  • socketstreamclient.socketStream()
    • Return a Node.js Transform stream instance which is both readable and writable. In uploading cases, this stream reads data from a readable source (such as fs.createReadStream) and writes data to server through the web socket. In downloading cases, this stream receives data from the web socket and should be piped to a writable destination (such as fs.createWriteStream).

Class: SocketStreamServer

  • extends WebSocket.Server
  • socketstreamserver.socketStream(ws)
    • ws: a WebSocket instance representing connection from a client-side web socket process.
    • Return a Node.js Transform stream instance which is both readable and writable. In uploading cases, this stream reads data from client through the web socket and should be piped to a writable destination (such as fs.createWriteStream). In downloading cases, this stream reads data from a readable source (such as fs.createReadStream) and writes data to client through the web socket.

Usage Examples

  • Upload File
    • Server Side
      const fs = require('fs');
      const { SocketStreamServer } = require('ws-socket-stream');
      
      // initialize SocketStreamServer
      const sss = new SocketStreamServer({
        port: 7501,
      });
      
      // when receiving connection from a client, save stream data to `bar.txt`
      sss.on('connection', (cws) => {
        sss.socketStream(cws).pipe(fs.createWriteStream('bar.txt'));
      });
      
    • Client Side
      const fs = require('fs');
      const { SocketStreamClient } = require('ws-socket-stream');
      
      // initialize SocketStreamClient
      const ssc = new SocketStreamClient('http://SERVER_IP:7501/');
      
      // when connection started, send content of `foo.txt` to server
      ssc.on('open', () => {
        fs.createReadStream('foo.txt').pipe(ssc.socketStream());
      });
      
  • Download File
    • Server Side
      const fs = require('fs');
      const { SocketStreamServer } = require('ws-socket-stream');
      
      // initialize SocketStreamServer
      const sss = new SocketStreamServer({
        port: 7501,
      });
      
      // when receiving a `DOWNLOAD` message from a client, send content of `foo.txt` to it
      sss.on('connection', (cws) => {
        cws.on('message', (message) => {
          if (message === 'DOWNLOAD') {
            fs.createReadStream('foo.txt').pipe(sss.socketStream(cws));
          }
        });
      });
      
    • Client Side
      const fs = require('fs');
      const { SocketStreamClient } = require('ws-socket-stream');
      
      // initialize SocketStreamClient
      const ssc = new SocketStreamClient('http://SERVER_IP:7501/');
      
      // when connection started, send downloading prompt and pipe content to `bar.txt`
      ssc.on('open', () => {
        ssc.send('DOWNLOAD');
        ssc.socketStream().pipe(fs.createWriteStream('bar.txt'));
      });