diff --git a/README.md b/README.md index 471eaea..5e2e71e 100644 --- a/README.md +++ b/README.md @@ -40,6 +40,36 @@ const ma = ipAndPortToMultiaddr('127.0.0.1', 9000) ## API +### arrayEquals(a, b) + +Verify if two arrays of non primitive types with the "equals" function are equal. +Compatible with multiaddr, peer-id and others. + +#### Parameters + +| Name | Type | Description | +|------|------|-------------| +| a | `Array<*>` | First array to verify | +| b | `Array<*>` | Second array to verify | + +#### Returns + +| Type | Description | +|------|-------------| +| `boolean` | returns true if arrays are equal, false otherwise | + +#### Example + +```js +const PeerId = require('peer-id') +const arrayEquals = require('libp2p-utils/src/multiaddr/array-equals') + +const peerId1 = await PeerId.create() +const peerId2 = await PeerId.create() + +const equals = arrayEquals([peerId1], [peerId2]) +``` + ### multiaddr `.isLoopback(ma)` Check if a given multiaddr is a loopback address. @@ -92,6 +122,71 @@ const ma = multiaddr('/ip4/10.0.0.1/tcp/1000') isMultiaddrPrivateAddrs = isPrivate(ma) ``` +### ipPortToMultiaddr(ip, port) + +Transform an IP, Port pair into a multiaddr with tcp transport. + +#### Parameters + +| Name | Type | Description | +|------|------|-------------| +| ip | `string` | ip for multiaddr | +| port | `number|string` | port for multiaddr | + +#### Returns + +| Type | Description | +|------|-------------| +| `Multiaddr` | returns created multiaddr | + +#### Example + +```js +const ipPortPairToMultiaddr = require('libp2p-utils/src/multiaddr/ip-port-to-multiaddr') +const ip = '127.0.0.1' +const port = '9090' + +const ma = ipPortPairToMultiaddr(ma) +``` + +### streamToMaConnection(streamProperties, options) + +Convert a duplex stream into a [MultiaddrConnection](https://github.com/libp2p/interface-transport#multiaddrconnection). + +#### Parameters + +| Name | Type | Description | +|------|------|-------------| +| streamProperties | `object` | duplex stream properties | +| streamProperties.stream | [`DuplexStream`](https://github.com/libp2p/js-libp2p/blob/master/doc/STREAMING_ITERABLES.md#duplex) | duplex stream | +| streamProperties.remoteAddr | `Multiaddr` | stream remote address | +| streamProperties.localAddr | `Multiaddr` | stream local address | +| [options] | `object` | options | +| [options.signal] | `AbortSignal` | abort signal | + +#### Returns + +| Type | Description | +|------|-------------| +| `Connection` | returns a multiaddr [Connection](https://github.com/libp2p/js-libp2p-interfaces/tree/master/src/connection) | + +#### Example + +```js +const streamToMaConnection = require('libp2p-utils/src/stream-to-ma-conn') + +const stream = { + sink: async source => {/* ... */}, + source: { [Symbol.asyncIterator] () {/* ... */} } +} + +const conn = streamToMaConnection({ + stream, + remoteAddr: /* ... */ + localAddr; /* ... */ +}) +``` + ## Contribute Contributions welcome. Please check out [the issues](https://github.com/libp2p/js-libp2p-utils/issues). diff --git a/src/array-equals.js b/src/array-equals.js index 4679e27..bb9f91c 100644 --- a/src/array-equals.js +++ b/src/array-equals.js @@ -2,7 +2,7 @@ /** * Verify if two arrays of non primitive types with the "equals" function are equal. - * Compatible with multiaddr, peer-id and Buffer. + * Compatible with multiaddr, peer-id and others. * * @param {Array<*>} a * @param {Array<*>} b diff --git a/src/ip-port-to-multiaddr.js b/src/ip-port-to-multiaddr.js index 2d6b5ef..f928b60 100644 --- a/src/ip-port-to-multiaddr.js +++ b/src/ip-port-to-multiaddr.js @@ -10,7 +10,13 @@ const errors = { ERR_INVALID_IP: 'ERR_INVALID_IP' } -module.exports = (ip, port) => { +/** + * Transform an IP, Port pair into a multiaddr + * + * @param {string} ip + * @param {number|string} port + */ +function ipPortToMultiaddr (ip, port) { if (typeof ip !== 'string') { throw errCode(new Error(`invalid ip provided: ${ip}`), errors.ERR_INVALID_IP_PARAMETER) } @@ -36,4 +42,6 @@ module.exports = (ip, port) => { throw errCode(new Error(`invalid ip:port for creating a multiaddr: ${ip}:${port}`), errors.ERR_INVALID_IP) } +module.exports = ipPortToMultiaddr + module.exports.Errors = errors diff --git a/src/stream-to-ma-conn.js b/src/stream-to-ma-conn.js index d19e960..91a3f4b 100644 --- a/src/stream-to-ma-conn.js +++ b/src/stream-to-ma-conn.js @@ -3,9 +3,18 @@ const abortable = require('abortable-iterator') const log = require('debug')('libp2p:stream:converter') -// Convert a duplex iterable into a MultiaddrConnection -// https://github.com/libp2p/interface-transport#multiaddrconnection -module.exports = ({ stream, remoteAddr, localAddr }, options = {}) => { +/** + * Convert a duplex iterable into a MultiaddrConnection. + * https://github.com/libp2p/interface-transport#multiaddrconnection + * + * @param {object} streamProperties + * @param {DuplexStream} streamProperties.stream + * @param {Multiaddr} streamProperties.remoteAddr + * @param {Multiaddr} streamProperties.localAddr + * @param {object} [options] + * @param {AbortSignal} [options.signal] + */ +function streamToMaConnection ({ stream, remoteAddr, localAddr }, options = {}) { const { sink, source } = stream const maConn = { async sink (source) { @@ -47,3 +56,5 @@ module.exports = ({ stream, remoteAddr, localAddr }, options = {}) => { return maConn } + +module.exports = streamToMaConnection