diff --git a/README.md b/README.md index 0b9379f..37d6c2a 100644 --- a/README.md +++ b/README.md @@ -6,13 +6,13 @@ interface-connection ![](https://img.shields.io/badge/npm-%3E%3D3.0.0-orange.svg?style=flat-square) ![](https://img.shields.io/badge/Node.js-%3E%3D4.0.0-orange.svg?style=flat-square) -This is a test suite and interface you can use to implement a connection. A connection is understood as something that offers mechanism for writing and reading data, back pressure, half and full duplex streams. This module and test suite were heavily inspired by abstract-blob-store and interface-stream-muxer. +This is a test suite and interface you can use to implement a connection. A connection is understood as something that offers a mechanism for writing and reading data, back pressure, half and full duplex streams. This module and test suite were heavily inspired by abstract-blob-store and interface-stream-muxer. The primary goal of this module is to enable developers to pick, swap or upgrade their connection without losing the same API expectations and mechanisms such as back pressure and the ability to half close a connection. Publishing a test suite as a module lets multiple modules all ensure compatibility since they use the same test suite. -The API is presented with both Node.js and Go primitives, however there is no actual limitations for it to be extended to any other language, pushing forward the cross compatibility and interop through diferent stacks. +The API is presented with both JS and Go primitives, however there is no actual limitations for it to be extended to any other language, pushing forward the cross compatibility and interop through diferent stacks. ## Lead Maintainer @@ -31,30 +31,29 @@ The API is presented with both Node.js and Go primitives, however there is no ac # Badge -Include this badge in your readme if you make a module that is compatible with the interface-connection API. You can validate this by running the tests. +Include this badge in your readme if you make a module that is compatible with the `interface-connection` API. You can validate this by running the tests. ![](https://raw.githubusercontent.com/diasdavid/interface-connection/master/img/badge.png) # How to use the battery of tests -## Node.js +## JS -``` -var tape = require('tape') -var tests = require('interface-connection/tests') -var YourConnectionHandler = require('../src') - -var common = { - setup: function (transport) { - // create a pair of connections using the received transport for both endpoints - return ConnectionsPair +```js +const test = require('interface-connection/test') +const YourConnection = require('../src') + +const common = { + setup: function () { + return YourConnection }, teardown: function () { - // clean up any resources created by setup() + // cleanup any resources created by setup() + return new Promise() } } -tests(tape, common) +test(common) ``` ## Go @@ -72,13 +71,15 @@ A valid connection (one that follows this abstraction), must implement the follo - `conn.getObservedAddrs()` - `Promise conn.getPeerInfo()` - `conn.setPeerInfo(peerInfo)` + - `conn.source()` + - `conn.sink()` - `Promise<> conn.close()` ### Creating a connection instance - `JavaScript` - `const conn = new Connection(connection, wrappedConnection)` -Creates a new Connection instance. `connection` is the object responsible for allowing to read or write data through the connection, while `wrappedConnection` consists on another connection that may be wrapped into the first one. +Creates a new Connection instance. `connection` is a streaming iterables duplex object responsible for allowing to read or write data through the connection, while `wrappedConnection` consists on another connection that may be wrapped into the first one. ### Get the Observed Addresses of the peer in the other end @@ -104,6 +105,18 @@ This method stores a reference to the peerInfo Object, which contains informatio It receives `peerInfo`, which is an object of type [Peer Info](https://github.com/libp2p/js-peer-info) +### Get a connection Source + +- `JavaScript` - `conn.source()` + +This getter returns the reference to the connection "source", which is an iterable object that can be consumed. + +### Get a connection data collector + +- `JavaScript` - `conn.sink()` + +This getter returns the reference to the connection "sink", which is an iterator that consumes (or drains) a source. + ### Close connection - `JavaScript` - `conn.close()` diff --git a/package.json b/package.json index 784e906..f0eb2f2 100644 --- a/package.json +++ b/package.json @@ -32,8 +32,7 @@ }, "homepage": "https://github.com/libp2p/interface-connection", "dependencies": { - "err-code": "^1.1.2", - "pull-defer": "~0.2.3" + "err-code": "^1.1.2" }, "devDependencies": { "aegir": "^17.1.1",