From 64697600994a3c22a1deb21264e97c4b71f3cb67 Mon Sep 17 00:00:00 2001 From: David Dias Date: Wed, 31 Aug 2016 06:41:34 -0400 Subject: [PATCH] feat(readme): add pull-streams documentation --- README.md | 32 ++++++++++++++++++++++++++------ 1 file changed, 26 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index beca427..d0888c8 100644 --- a/README.md +++ b/README.md @@ -10,15 +10,11 @@ ![](https://raw.githubusercontent.com/libp2p/interface-connection/master/img/badge.png) ![](https://raw.githubusercontent.com/libp2p/interface-transport/master/img/badge.png) -> Node.js implementation of the TCP module that libp2p uses, which implements -> the [interface-connection](https://github.com/libp2p/interface-connection) -> interface for dial/listen. +> Node.js implementation of the TCP module that libp2p uses, which implements the [interface-connection](https://github.com/libp2p/interface-connection) interface for dial/listen. ## Description -`libp2p-tcp` in Node.js is a very thin shim that adds support for dialing to a -`multiaddr`. This small shim will enable libp2p to use other different -transports. +`libp2p-tcp` in Node.js is a very thin shim that adds support for dialing to a `multiaddr`. This small shim will enable libp2p to use other different transports. **Note:** This module uses [pull-streams](https://pull-stream.github.io) for all stream based interfaces. @@ -71,6 +67,30 @@ hello > npm i libp2p-tcp ``` +## 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 what took us to make this migration, 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 Node.js Stream using the module `pull-stream-to-stream`, giving you an instance of a Node.js Stream that is linked to the pull-stream. Example: + +``` +const pullToStream = require('pull-stream-to-stream') + +const nodeStreamInstance = pullToStream(pullStreamInstance) +// nodeStreamInstance is an istance of a Node.js Stream +``` + +To learn more about his utility, visit https://pull-stream.github.io/#pull-stream-to-stream + ## API [![](https://raw.githubusercontent.com/diasdavid/interface-transport/master/img/badge.png)](https://github.com/diasdavid/interface-transport)