feat(readme): pull-streams note

libp2p · Sep 6, 2016 · 5aafbe5 · 5aafbe5
1 parent bfcc8f0
commit 5aafbe5
Showing 1 changed file with 28 additions and 2 deletions.
diff --git a/README.md b/README.md
@@ -54,13 +54,13 @@ Loading this module through a script tag will make the `Lip2pSpdy` obj available
 **As a listener**
 
 ```JavaScript
-const listener = spdy(socket, true)
+const listener = spdy(conn, true)
 ```
 
 **As a dialer**
 
 ```JavaScript
-const dialer = spdy(socket, false)
+const dialer = spdy(conn, false)
 ```
 
 #### Opening a multiplex duplex stream
@@ -97,3 +97,29 @@ dialer.on('error', () => {})
 ```
 
 note: Works the same on the listener side
+
+### This module uses `pull-streams`
+
+We expose a streaming interface based on `pull-streams`, rather then on the Node.js core streams implementation (aka Node.js streams). `pull-streams` offers us a better mechanism for error handling and flow control guarantees. If you would like to know more about why we did this, see the discussion at this [issue](https://github.com/ipfs/js-ipfs/issues/362).
+
+You can learn more about pull-streams at:
+
+- [The history of Node.js streams, nodebp April 2014](https://www.youtube.com/watch?v=g5ewQEuXjsQ)
+- [The history of streams, 2016](http://dominictarr.com/post/145135293917/history-of-streams)
+- [pull-streams, the simple streaming primitive](http://dominictarr.com/post/149248845122/pull-streams-pull-streams-are-a-very-simple)
+- [pull-streams documentation](https://pull-stream.github.io/)
+
+#### Converting `pull-streams` to Node.js Streams
+
+If you are a Node.js streams user, you can convert a pull-stream to a Node.js stream using the module [`pull-stream-to-stream`](https://github.com/dominictarr/pull-stream-to-stream), giving you an instance of a Node.js stream that is linked to the pull-stream. For example:
+
+```js
+const pullToStream = require('pull-stream-to-stream')
+
+const nodeStreamInstance = pullToStream(pullStreamInstance)
+// nodeStreamInstance is an instance of a Node.js Stream
+```
+
+To learn more about this utility, visit https://pull-stream.github.io/#pull-stream-to-stream.
+
+