# @11ways/socket.io-stream

> stream for socket.io

Latest version **0.9.2** (published 2021-08-10) · 0 weekly downloads

## Install

```sh
npm install @11ways/socket.io-stream
pnpm add @11ways/socket.io-stream
yarn add @11ways/socket.io-stream
bun add @11ways/socket.io-stream
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.9.2 |
| Published | 2021-08-10 |
| First published | 2021-08-10 |
| Weekly downloads | 0 |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 2 |
| Unpacked size | 239.7 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Author | Naoyuki Kanezawa |
| Maintainers | skerit |
| Keywords | stream, socket.io, binary, file, upload, download |

## Links

- npm: https://www.npmjs.com/package/@11ways/socket.io-stream
- Repository: https://github.com/11ways/socket.io-stream
- Homepage: https://github.com/11ways/socket.io-stream#readme
- Issues: https://github.com/11ways/socket.io-stream/issues
- npm.io page: https://npm.io/package/@11ways/socket.io-stream

## Dependencies (2)

- [debug](https://npm.io/package/debug.md) ~4.3.2
- [component-bind](https://npm.io/package/component-bind.md) ~1.0.0

## Alternatives

- [@opentelemetry/exporter-zipkin](https://npm.io/package/@opentelemetry/exporter-zipkin.md) — 14.8M weekly downloads
- [pusher-js](https://npm.io/package/pusher-js.md) — 2.0M weekly downloads
- [browserify](https://npm.io/package/browserify.md) — 1.7M weekly downloads
- [sqs-consumer](https://npm.io/package/sqs-consumer.md) — 1.7M weekly downloads
- [@sanity/eventsource](https://npm.io/package/@sanity/eventsource.md) — 930.8K weekly downloads

## Recent versions

- 0.9.2 (latest) — 2021-08-10

## README

# Socket.IO stream

This is the module for bidirectional binary data transfer with Stream API through [Socket.IO](https://github.com/socketio/socket.io).

This is a fork of nkzawa/socket.io-stream, mainly just to upgrade the aging dependencies. WIP.

## Installation

    npm install @11ways/socket.io-stream

## Usage

If you are not familiar with Stream API, be sure to check out [the docs](http://nodejs.org/api/stream.html).
I also recommend checking out the awesome [Stream Handbook](https://github.com/substack/stream-handbook).

For streaming between server and client, you will send stream instances first.
To receive streams, you just wrap `socket` with `socket.io-stream`, then listen any events as usual.

Server:

```js
var io = require('socket.io').listen(80);
var ss = require('@11ways/socket.io-stream');
var path = require('path');

io.of('/user').on('connection', function(socket) {
  ss(socket).on('profile-image', function(stream, data) {
    var filename = path.basename(data.name);
    stream.pipe(fs.createWriteStream(filename));
  });
});
```

`createStream()` returns a new stream which can be sent by `emit()`.

Client:

```js
var io = require('socket.io-client');
var ss = require('@11ways/socket.io-stream');

var socket = io.connect('http://example.com/user');
var stream = ss.createStream();
var filename = 'profile.jpg';

ss(socket).emit('profile-image', stream, {name: filename});
fs.createReadStream(filename).pipe(stream);
```

You can stream data from a client to server, and vice versa.

```js
// send data
ss(socket).on('file', function(stream) {
  fs.createReadStream('/path/to/file').pipe(stream);
});

// receive data
ss(socket).emit('file', stream);
stream.pipe(fs.createWriteStream('file.txt'));
```

### Browser

This module can be used on the browser. To do so, just copy a file to a public directory.

    $ cp node_modules/socket.io-stream/socket.io-stream.js somewhere/public/

You can also use [browserify](http://github.com/substack/node-browserify) to create your own bundle.

    $ npm install browserify -g
    $ cd node_modules/socket.io-stream
    $ browserify index.js -s ss > socket.io-stream.js

```html
<input id="file" type="file" />

<script src="/socket.io/socket.io.js"></script>
<script src="/js/socket.io-stream.js"></script>
<script src="/js/jquery.js"></script>
<script>
$(function() {
  var socket = io.connect('/foo');

  $('#file').change(function(e) {
    var file = e.target.files[0];
    var stream = ss.createStream();

    // upload a file to the server.
    ss(socket).emit('file', stream, {size: file.size});
    ss.createBlobReadStream(file).pipe(stream);
  });
});
</script>
```

#### Upload progress

You can track upload progress like the following:

```js
var blobStream = ss.createBlobReadStream(file);
var size = 0;

blobStream.on('data', function(chunk) {
  size += chunk.length;
  console.log(Math.floor(size / file.size * 100) + '%');
  // -> e.g. '42%'
});

blobStream.pipe(stream);
```

### Socket.IO v0.9 support

You have to set `forceBase64` option `true` when using the library with socket.io v0.9.x.

```js
ss.forceBase64 = true;
```


## Documentation

### ss(sio)

- sio `socket.io Socket` A socket of Socket.IO, both for client and server
- return `Socket`

Look up an existing `Socket` instance based on `sio` (a socket of Socket.IO), or create one if it doesn't exist.

### socket.emit(event, [arg1], [arg2], [...])

- event `String` The event name

Emit an `event` with variable number of arguments including at least a stream.

```js
ss(socket).emit('myevent', stream, {name: 'thefilename'}, function() { ... });

// send some streams at a time.
ss(socket).emit('multiple-streams', stream1, stream2);

// as members of array or object.
ss(socket).emit('flexible', [stream1, { foo: stream2 }]);

// get streams through the ack callback
ss(socket).emit('ack', function(stream1, stream2) { ... });
```

### socket.on(event, listener)

- event `String` The event name
- listener `Function` The event handler function

Add a `listener` for `event`. `listener` will take stream(s) with any data as arguments.

```js
ss(socket).on('myevent', function(stream, data, callback) { ... });

// access stream options
ss(socket).on('foo', function(stream) {
  if (stream.options && stream.options.highWaterMark > 1024) {
    console.error('Too big highWaterMark.');
    return;
  }
});
```

### ss.createStream([options])

- options `Object`
    - highWaterMark `Number`
    - encoding `String`
    - decodeStrings `Boolean`
    - objectMode `Boolean`
    - allowHalfOpen `Boolean` if `true`, then the stream won't automatically close when the other endpoint ends. Default to `false`.
- return `Duplex Stream`

Create a new duplex stream. See [the docs](http://nodejs.org/api/stream.html) for the details of stream and `options`.

```js
var stream = ss.createStream();

// with options
var stream = ss.createStream({
  highWaterMark: 1024,
  objectMode: true,
  allowHalfOpen: true
});
```

### ss.createBlobReadStream(blob, [options])

- options `Object`
    - highWaterMark `Number`
    - encoding `String`
    - objectMode `Boolean`
- return `Readable Stream`

Create a new readable stream for [Blob](https://developer.mozilla.org/en-US/docs/Web/API/Blob) and [File](https://developer.mozilla.org/en-US/docs/Web/API/File) on browser. See [the docs](http://nodejs.org/api/stream.html) for the details of stream and `options`.

```js
var stream = ss.createBlobReadStream(new Blob([1, 2, 3]));
```

### ss.Buffer

[Node Buffer](https://nodejs.org/api/buffer.html) class to use on browser, which is exposed for convenience. On Node environment, you should just use normal `Buffer`.

```js
var stream = ss.createStream();
stream.write(new ss.Buffer([0, 1, 2]));
```

## License

MIT

---
_Source: https://npm.io/package/@11ways/socket.io-stream · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._