bpmux - npm Package Compare versions

Comparing version 8.0.4 to 8.0.5

index.js

@@ -15,2 +15,3 @@ /**
   - Browser unit tests using [webpack](http://webpack.github.io/) and [nwjs](http://nwjs.io/).
+- **See the [errors](#errors) section for information on why multiplexed streams error when their carrier streams closes before they do.**
 
@@ -239,3 +240,3 @@ The API is described [here](#api).
 
-BPMux doesn't suffer from this problem since backpressure is exerted on each
+bpmux doesn't suffer from this problem since backpressure is exerted on each
 stream separately. Here's the same test:
@@ -291,2 +292,29 @@
 
+## Errors
+
+bpmux will emit `error` events on multiplexed streams if their underlying
+(carrier) stream closes before they have closed. The error message will be one
+of these two strings:
+
+```
+carrier stream finished before duplex finished
+carrier stream ended before end message received
+```
+
+As this is an `error` event, you must register an event listener on multiplexed
+streams [if you don't want the Node process to exit](https://nodejs.org/dist/latest-v13.x/docs/api/events.html#events_error_events).
+
+The reasoning behind emitting `error` events on open multiplexed streams when
+their carrier closes is:
+
+- If you're reading from a stream and it hasn't ended before the carrier closes then there may be some data that you'll never receive. This is an error state.
+
+- If you're writing to a stream and it hasn't finished before the carrier closes then your application should be informed about it straight away. If it's performing some heavy calculation, for example, then it has a chance to cancel it before writing the result to the stream.
+
+If you do register `error` event listeners, make sure you do so for streams
+you multiplex using [`multiplex()`](#bpmuxprototypemultiplexoptions) _and_
+for streams you receive using the [`handshake`](#bpmuxeventshandshakeduplex-handshake_data-delay_handshake) or [`peer_multiplex`](#bpmuxeventspeer_multiplexduplex) events.
+
+`BPMux` objects will also re-emit any `error` events their carrier stream emits.
+
 ## Installation
@@ -293,0 +321,0 @@

package.json

 {
   "name": "bpmux",
   "description": "Node stream multiplexing with back-pressure on each stream",
-  "version": "8.0.4",
+  "version": "8.0.5",
   "homepage": "https://github.com/davedoesdev/bpmux",
@@ -6,0 +6,0 @@ "author": {

README.md

@@ -14,2 +14,3 @@ # bpmux   [![Build Status](https://travis-ci.org/davedoesdev/bpmux.png)](https://travis-ci.org/davedoesdev/bpmux) [![Coverage Status](https://coveralls.io/repos/davedoesdev/bpmux/badge.png?branch=master&service=github)](https://coveralls.io/r/davedoesdev/bpmux?branch=master) [![NPM version](https://badge.fury.io/js/bpmux.png)](http://badge.fury.io/js/bpmux)
   - Browser unit tests using [webpack](http://webpack.github.io/) and [nwjs](http://nwjs.io/).
+- **See the [errors](#errors) section for information on why multiplexed streams error when their carrier streams closes before they do.**
 
@@ -238,3 +239,3 @@ The API is described [here](#api).
 
-[BPMux](#bpmuxcarrier-options) doesn't suffer from this problem since backpressure is exerted on each
+bpmux doesn't suffer from this problem since backpressure is exerted on each
 stream separately. Here's the same test:
@@ -290,2 +291,29 @@
 
+## Errors
+
+bpmux will emit `error` events on multiplexed streams if their underlying
+(carrier) stream closes before they have closed. The error message will be one
+of these two strings:
+
+```
+carrier stream finished before duplex finished
+carrier stream ended before end message received
+```
+
+As this is an `error` event, you must register an event listener on multiplexed
+streams [if you don't want the Node process to exit](https://nodejs.org/dist/latest-v13.x/docs/api/events.html#events_error_events).
+
+The reasoning behind emitting `error` events on open multiplexed streams when
+their carrier closes is:
+
+- If you're reading from a stream and it hasn't ended before the carrier closes then there may be some data that you'll never receive. This is an error state.
+
+- If you're writing to a stream and it hasn't finished before the carrier closes then your application should be informed about it straight away. If it's performing some heavy calculation, for example, then it has a chance to cancel it before writing the result to the stream.
+
+If you do register `error` event listeners, make sure you do so for streams
+you multiplex using [`multiplex()`](#bpmuxprototypemultiplexoptions) _and_
+for streams you receive using the [`handshake`](#bpmuxeventshandshakeduplex-handshake_data-delay_handshake) or [`peer_multiplex`](#bpmuxeventspeer_multiplexduplex) events.
+
+`BPMux` objects will also re-emit any `error` events their carrier stream emits.
+
 ## Installation
@@ -292,0 +320,0 @@

No alert changes

Improved metrics

Total package byte prevSize

534622

1.44%

Lines of code

5092

0.37%

Number of lines in readme file

544

5.43%

No dependency changes