docs(api): first pass

As `loadash.contains` is deprecated.

.gitignore

@@ -26,5 +26,4 @@ build/Release
 # https://www.npmjs.org/doc/misc/npm-faq.html#should-i-check-my-node_modules-folder-into-git
 node_modules
 
-lib
+docs
-dist

.npmignore

@@ -27,3 +27,4 @@ build/Release
 node_modules
 
 test
+docs

.travis.yml

@@ -1,9 +1,13 @@
 sudo: false
 language: node_js
-node_js:
+matrix:
-  - 4
+  include:
-  - 5
+  - node_js: 4
-  - stable
+    env: CXX=g++-4.8
+  - node_js: 6
+    env: CXX=g++-4.8
+  - node_js: stable
+    env: CXX=g++-4.8
 
 # Make sure we have new NPM.
 before_install:
@@ -14,12 +18,16 @@ script:
   - npm test
   - npm run coverage
 
-addons:
-  firefox: 'latest'
-
 before_script:
   - export DISPLAY=:99.0
   - sh -e /etc/init.d/xvfb start
 
 after_success:
   - npm run coverage-publish
+
+addons:
+  apt:
+    sources:
+      - ubuntu-toolchain-r-test
+    packages:
+      - g++-4.8

LICENSE

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2015 David Dias
+Copyright (c) 2015-2016 David Dias
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -3,22 +3,44 @@
 [![](https://img.shields.io/badge/made%20by-Protocol%20Labs-blue.svg?style=flat-square)](http://ipn.io)
 [![](https://img.shields.io/badge/freenode-%23ipfs-blue.svg?style=flat-square)](http://webchat.freenode.net/?channels=%23ipfs)
 [![Build Status](https://travis-ci.org/libp2p/js-libp2p-tcp.svg?style=flat-square)](https://travis-ci.org/libp2p/js-libp2p-tcp)
-![](https://img.shields.io/badge/coverage-%3F-yellow.svg?style=flat-square)
+[![Coverage Status](https://coveralls.io/repos/github/libp2p/js-libp2p-tcp/badge.svg?branch=master)](https://coveralls.io/github/libp2p/js-libp2p-tcp?branch=master)
 [![Dependency Status](https://david-dm.org/libp2p/js-libp2p-tcp.svg?style=flat-square)](https://david-dm.org/libp2p/js-libp2p-tcp)
 [![js-standard-style](https://img.shields.io/badge/code%20style-standard-brightgreen.svg?style=flat-square)](https://github.com/feross/standard)
+![](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)
 
 ![](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.
 
-## 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.
 
 **Note:** This module uses [pull-streams](https://pull-stream.github.io) for all stream based interfaces.
 
-## Example
+## Table of Contents
+
+- [Install](#install)
+  - [npm](#npm)
+- [Usage](#usage)
+  - [Example](#example)
+  - [This module uses `pull-streams`](#this-module-uses-pull-streams)
+    - [Converting `pull-streams` to Node.js Streams](#converting-pull-streams-to-nodejs-streams)
+- [API](#api)
+- [Contribute](#contribute)
+- [License](#license)
+
+## Install
+
+### npm
+
+```sh
+> npm i libp2p-tcp
+```
+
+## Usage
+
+### Example
 
 ```js
 const TCP = require('libp2p-tcp')
@@ -51,25 +73,17 @@ listener.listen(() => {
 })
 ```
 
-outputs
+Outputs:
 
-```
+```sh
 listening
 new connection opened
 hello
 ```
 
-## Installation
+### This module uses `pull-streams`
 
-### npm
+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).
-
-```sh
-> 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:
 
@@ -78,22 +92,22 @@ You can learn more about pull-streams at:
 - [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
+#### 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:
+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 his utility, visit https://pull-stream.github.io/#pull-stream-to-stream
+To learn more about this 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)
+[![](https://raw.githubusercontent.com/libp2p/interface-transport/master/img/badge.png)](https://github.com/libp2p/interface-transport)
 
 `libp2p-tcp` accepts TCP addresses both IPFS and non IPFS encapsulated addresses, i.e:
 
@@ -102,6 +116,18 @@ To learn more about his utility, visit https://pull-stream.github.io/#pull-strea
 
 Both for dialing and listening.
 
+## Contribute
+
+Contributions are welcome! The libp2p implementation in JavaScript is a work in progress. As such, there's a few things you can do right now to help out:
+
+- [Check out the existing issues](//github.com/libp2p/js-libp2p-tcp/issues).
+- **Perform code reviews**.
+- **Add tests**. There can never be enough tests.
+
+Please be aware that all interactions related to libp2p are subject to the IPFS [Code of Conduct](https://github.com/ipfs/community/blob/master/code-of-conduct.md).
+
+Small note: If editing the README, please conform to the [standard-readme](https://github.com/RichardLitt/standard-readme) specification.
+
 ## License
 
-MIT
+[MIT](LICENSE) © 2015-2016 David Dias

package.json

@@ -1,16 +1,15 @@
 {
   "name": "libp2p-tcp",
-  "version": "0.8.0",
+  "version": "0.9.1",
   "description": "Node.js implementation of the TCP module that libp2p uses, which implements the interface-connection and interface-transport interfaces",
-  "main": "lib/index.js",
+  "main": "src/index.js",
-  "jsnext:main": "src/index.js",
   "scripts": {
     "lint": "aegir-lint",
-    "build": "aegir-build --env node",
     "test": "aegir-test --env node",
-    "release": "aegir-release --env node",
+    "docs": "aegir-docs",
-    "release-minor": "aegir-release --type minor --env node",
+    "release": "aegir-release --env no-build --docs",
-    "release-major": "aegir-release --type major --env node",
+    "release-minor": "aegir-release --type minor --env no-build --docs",
+    "release-major": "aegir-release --type major --env no-build --docs",
     "coverage": "aegir-coverage",
     "coverage-publish": "aegir-coverage publish"
   },
@@ -20,7 +19,7 @@
   ],
   "repository": {
     "type": "git",
-    "url": "https://github.com/diasdavid/js-libp2p-tcp.git"
+    "url": "https://github.com/libp2p/js-libp2p-tcp.git"
   },
   "keywords": [
     "IPFS"
@@ -28,32 +27,35 @@
   "author": "David Dias <daviddias@ipfs.io>",
   "license": "MIT",
   "bugs": {
-    "url": "https://github.com/diasdavid/js-libp2p-tcp/issues"
+    "url": "https://github.com/libp2p/js-libp2p-tcp/issues"
+  },
+  "homepage": "https://github.com/libp2p/js-libp2p-tcp",
+  "engines": {
+    "node": ">=4.0.0"
   },
-  "homepage": "https://github.com/diasdavid/js-libp2p-tcp",
   "devDependencies": {
-    "aegir": "^6.0.1",
+    "aegir": "^9.2.0",
     "chai": "^3.5.0",
     "interface-transport": "^0.3.3",
     "lodash.isfunction": "^3.0.8",
-    "pre-commit": "^1.1.2"
+    "pre-commit": "^1.1.3",
+    "pull-stream": "^3.5.0"
   },
   "dependencies": {
-    "interface-connection": "0.2.1",
+    "interface-connection": "0.3.0",
-    "ip-address": "^5.8.0",
+    "ip-address": "^5.8.2",
-    "lodash.contains": "^2.4.3",
+    "lodash.includes": "^4.3.0",
     "mafmt": "^2.1.2",
-    "multiaddr": "^2.0.2",
+    "multiaddr": "^2.1.1",
-    "pull": "^2.1.1",
+    "stream-to-pull-stream": "^1.7.2"
-    "stream-to-pull-stream": "^1.7.0"
   },
   "contributors": [
     "David Dias <daviddias.p@gmail.com>",
     "Evan Schwartz <evan.mark.schwartz@gmail.com>",
+    "Friedel Ziegelmayer <dignifiedquire@gmail.com>",
     "João Antunes <j.goncalo.antunes@gmail.com>",
     "Richard Littauer <richard.littauer@gmail.com>",
     "Stephen Whitmore <stephen.whitmore@gmail.com>",
-    "dignifiedquire <dignifiedquire@gmail.com>",
     "greenkeeperio-bot <support@greenkeeper.io>"
   ]
 }

src/index.js

@@ -3,7 +3,7 @@
 const net = require('net')
 const toPull = require('stream-to-pull-stream')
 const mafmt = require('mafmt')
-const contains = require('lodash.contains')
+const includes = require('lodash.includes')
 const isFunction = require('lodash.isfunction')
 const Connection = require('interface-connection').Connection
 const debug = require('debug')
@@ -11,21 +11,32 @@ const log = debug('libp2p:tcp:dial')
 
 const createListener = require('./listener')
 
-module.exports = class TCP {
+/**
-  dial (ma, options, cb) {
+ *
+ */
+class TCP {
+  /**
+   * Dial to another peer.
+   *
+   * @param {Multiaddr} ma - The address of the peer we want to dial to.
+   * @param {Object} [options={}]
+   * @param {function(Error?, Array<Multiaddr>?)} [callback]
+   * @returns {Connection}
+   */
+  dial (ma, options, callback) {
     if (isFunction(options)) {
-      cb = options
+      callback = options
       options = {}
     }
 
-    if (!cb) {
+    if (!callback) {
-      cb = () => {}
+      callback = () => {}
     }
 
     const cOpts = ma.toOptions()
     log('Connecting to %s %s', cOpts.port, cOpts.host)
 
-    const rawSocket = net.connect(cOpts, cb)
+    const rawSocket = net.connect(cOpts, callback)
 
     rawSocket.once('timeout', () => {
       log('timeout')
@@ -43,6 +54,13 @@ module.exports = class TCP {
     return conn
   }
 
+  /**
+   * Listen for incoming `TCP` connetions.
+   *
+   * @param {Object} [options={}]
+   * @param {function(Connection)} [handler] - Called with newly incomin connections.
+   * @returns {Listener}
+   */
   createListener (options, handler) {
     if (isFunction(options)) {
       handler = options
@@ -54,15 +72,24 @@ module.exports = class TCP {
     return createListener(handler)
   }
 
+  /**
+   * Filter a list of multiaddrs for those which contain
+   * valid `TCP` addresses.
+   *
+   * @param {Multiaddr|Array<Multiaddr>} multiaddrs
+   * @returns {Array<Multiaddr>}
+   */
   filter (multiaddrs) {
     if (!Array.isArray(multiaddrs)) {
       multiaddrs = [multiaddrs]
     }
     return multiaddrs.filter((ma) => {
-      if (contains(ma.protoNames(), 'ipfs')) {
+      if (includes(ma.protoNames(), 'ipfs')) {
         ma = ma.decapsulate('ipfs')
       }
       return mafmt.TCP.matches(ma)
     })
   }
 }
+
+module.exports = TCP

src/listener.js

@@ -3,7 +3,7 @@
 const multiaddr = require('multiaddr')
 const Connection = require('interface-connection').Connection
 const os = require('os')
-const contains = require('lodash.contains')
+const includes = require('lodash.includes')
 const net = require('net')
 const toPull = require('stream-to-pull-stream')
 const EventEmitter = require('events').EventEmitter
@@ -15,7 +15,49 @@ const getMultiaddr = require('./get-multiaddr')
 const IPFS_CODE = 421
 const CLOSE_TIMEOUT = 2000
 
+/**
+ * Listening for incoming connections.
+ *
+ * @event listening
+ * @instance
+ * @memberof Listener
+ */
+
+/**
+ * The server closes.
+ *
+ * @event close
+ * @instance
+ * @memberof Listener
+ */
+
+/**
+ * New connection established.
+ *
+ * @event connection
+ * @instance
+ * @type {Connection}
+ * @memberof Listener
+ */
+
+/**
+ * The underlying server encountered an error.
+ *
+ * @event error
+ * @instance
+ * @type {Error}
+ * @memberof Listener
+ */
+
 module.exports = (handler) => {
+  /**
+   * @alias Listener
+   * @type {Eventemitter}
+   * @fires Listener#listening
+   * @fires Listener#close
+   * @fires Listener#connection
+   * @fires Listener#error
+   */
   const listener = new EventEmitter()
 
   const server = net.createServer((socket) => {
@@ -78,7 +120,7 @@ module.exports = (handler) => {
 
   listener.listen = (ma, cb) => {
     listeningAddr = ma
-    if (contains(ma.protoNames(), 'ipfs')) {
+    if (includes(ma.protoNames(), 'ipfs')) {
       ipfsId = getIpfsId(ma)
       listeningAddr = ma.decapsulate('ipfs')
     }