multiaddr - npm Package Compare versions
Comparing version 2.1.1 to 2.1.3
| { | ||
| "name": "multiaddr", | ||
| "version": "2.1.1", | ||
| "version": "2.1.3", | ||
| "description": "multiaddr implementation (binary + string representation of network addresses)", | ||
@@ -16,3 +16,4 @@ "main": "src/index.js", | ||
| "coverage": "aegir-coverage", | ||
| "coverage-publish": "aegir-coverage publish" | ||
| "coverage-publish": "aegir-coverage publish", | ||
| "docs": "aegir-docs" | ||
| }, | ||
@@ -48,3 +49,3 @@ "pre-commit": [ | ||
| "devDependencies": { | ||
| "aegir": "^9.1.2", | ||
| "aegir": "^9.3.0", | ||
| "buffer-loader": "0.0.1", | ||
@@ -51,0 +52,0 @@ "chai": "^3.5.0", |
152
README.md
@@ -5,8 +5,9 @@ js-multiaddr | ||
| [](http://ipn.io) | ||
| [](http://github.com/multiformats/multiformats) | ||
| [](http://webchat.freenode.net/?channels=%23ipfs) | ||
| [](https://github.com/multiformats/multiformats) | ||
| [](https://webchat.freenode.net/?channels=%23ipfs) | ||
| [](https://coveralls.io/github/multiformats/js-multiaddr?branch=master) | ||
| [](https://travis-ci.org/multiformats/js-multiaddr) | ||
| [](https://travis-ci.org/multiformats/js-multiaddr) | ||
| [](https://circleci.com/gh/multiformats/js-multiaddr) | ||
| [](https://david-dm.org/multiformats/js-multiaddr) [](https://github.com/feross/standard) | ||
| [](https://github.com/RichardLitt/standard-readme) | ||
@@ -122,143 +123,4 @@ > JavaScript implementation of [multiaddr](https://github.com/multiformats/multiaddr). | ||
| ```js | ||
| const multiaddr = require('multiaddr') | ||
| ``` | ||
| https://multiformats.github.io/js-multiaddr/ | ||
| ### Create | ||
| #### const addr = multiaddr(str) | ||
| Creates a multiaddress from a string (e.g. `/ip4/127.0.0.1/udp/1234`). | ||
| #### const addr = multiaddr(buf) | ||
| Creates a multiaddress from another multiaddress' raw bytes. | ||
| #### addr.buffer | ||
| The raw bytes representing this multiaddress. | ||
| #### addr.toString() | ||
| The multiaddress in string format (e.g. `/ip4/127.0.0.1/udp/1234`). | ||
| ### Protocols | ||
| #### addr.protoCodes() | ||
| Returns the codes of the protocols in the multiaddress, in left-to-right order. | ||
| ```js | ||
| addr.protoCodes() | ||
| // [4, 6] | ||
| ``` | ||
| #### addr.protoNames() | ||
| Returns the names of the protocols in the multiaddress, in left-to-right order. | ||
| ```js | ||
| addr.protoNames() | ||
| // ['ip4', 'tcp'] | ||
| ``` | ||
| #### addr.protos() | ||
| Returns description objects of the protocols in the multiaddress, in left-to-right order. | ||
| ```js | ||
| addr.protos() | ||
| // [ | ||
| // { code: 4, name: 'ip4', size: 32}, | ||
| // { code: 17, name: 'udp', size: 16} | ||
| // ] | ||
| ``` | ||
| Each object contains the protocol code, protocol name, and the size of its | ||
| address space in bits. | ||
| ### Node-Friendly Addresses | ||
| Utility functions for getting NodeJS-friendly address information from a | ||
| multiaddress. | ||
| #### addr.nodeAddress() | ||
| Returns a NodeJS-friendly object describing the left-most address in the | ||
| multiaddress. | ||
| ```js | ||
| addr.nodeAddress() | ||
| // { family: "IPv4", port:1234, address: "127.0.0.1" } | ||
| ``` | ||
| Note that protocol information is left out: in Node (and most network systems) | ||
| the protocol is unknowable given only the address. | ||
| #### addr.fromNodeAddress(addr) | ||
| Constructs a multiaddress, given a NodeJS-friendly address object and a protocol. | ||
| ```js | ||
| addr.fromNodeAddress({family: "IPv4", port:1234, address: "127.0.0.1"}, 'udp') | ||
| // <Multiaddr /ip4/127.0.0.1/udp/1234> | ||
| ``` | ||
| #### addr.fromStupidString(str) | ||
| Returns a multiaddress, given a URI in the format `<proto><IPv>://<IP | ||
| Addr>[:<proto port>]` | ||
| ```js | ||
| addr = multiaddr.fromStupidString("udp4://127.0.0.1:1234") | ||
| // <Multiaddr /ip4/127.0.0.1/udp/1234> | ||
| ``` | ||
| *NOT IMPLEMENTED* | ||
| #### addr.toStupidString() | ||
| *NOT IMPLEMENTED* | ||
| ### En/decapsulate | ||
| #### addr.encapsulate(str) | ||
| Returns a new multiaddress that encapsulates `addr` in a new protocol string, | ||
| `str`. | ||
| ```js | ||
| addr.encapsulate('/sctp/5678') | ||
| // <Multiaddr /ip4/127.0.0.1/udp/1234/sctp/5678> | ||
| ``` | ||
| #### addr.decapsulate(str) | ||
| Returns a new multiaddress with the right-most protocol string `str` removed. | ||
| ```js | ||
| multiaddress('/ip4/127.0.0.1/udp/1234').decapsulate('/udp') | ||
| // <Multiaddr /ip4/127.0.0.1> | ||
| ``` | ||
| ### Tunneling | ||
| Given these encapsulation/decapsulate tools, multiaddresses lend | ||
| themselves to expressing tunnels very nicely: | ||
| ```js | ||
| const printer = multiaddr('/ip4/192.168.0.13/tcp/80') | ||
| const proxy = multiaddr('/ip4/10.20.30.40/tcp/443') | ||
| const printerOverProxy = proxy.encapsulate(printer) | ||
| // <Multiaddr /ip4/10.20.30.40/tcp/443/ip4/192.168.0.13/tcp/80> | ||
| ``` | ||
| ### Misc | ||
| #### `multiaddr.isMultiaddr(addr)` | ||
| Returns `true` if the passed in `addr` is a valid `multiaddr`. | ||
| ## Maintainers | ||
@@ -274,6 +136,6 @@ | ||
| Small note: If editing the Readme, please conform to the [standard-readme](https://github.com/RichardLitt/standard-readme) specification. | ||
| Small note: If editing the README, please conform to the [standard-readme](https://github.com/RichardLitt/standard-readme) specification. | ||
| ## License | ||
| [MIT](LICENSE) © Protocol Labs Inc. | ||
| [MIT](LICENSE) © 2016 Protocol Labs Inc. |
247
src/index.js
@@ -12,2 +12,13 @@ 'use strict' | ||
| /** | ||
| * Creates a [multiaddr](https://github.com/multiformats/multiaddr) from | ||
| * a Buffer, String or another Multiaddr instance | ||
| * public key. | ||
| * @class Multiaddr | ||
| * @param {(String|Buffer|Multiaddr)} addr - If String or Buffer, needs to adhere | ||
| * to the address format of a [multiaddr](https://github.com/multiformats/multiaddr#string-format) | ||
| * @example | ||
| * Multiaddr('/ip4/127.0.0.1/tcp/4001') | ||
| * // <Multiaddr 047f000001060fa1 - /ip4/127.0.0.1/tcp/4001> | ||
| */ | ||
| function Multiaddr (addr) { | ||
@@ -24,2 +35,5 @@ if (!(this instanceof Multiaddr)) { | ||
| if (addr instanceof Buffer) { | ||
| /** | ||
| * @type {Buffer} - The raw bytes representing this multiaddress | ||
| */ | ||
| this.buffer = codec.fromBuffer(addr) | ||
@@ -35,3 +49,10 @@ } else if (typeof (addr) === 'string' || addr instanceof String) { | ||
| // get the multiaddr protocols | ||
| /** | ||
| * Returns Multiaddr as a String | ||
| * | ||
| * @returns {String} | ||
| * @example | ||
| * Multiaddr('/ip4/127.0.0.1/tcp/4001').toString() | ||
| * // '/ip4/127.0.0.1/tcp/4001' | ||
| */ | ||
| Multiaddr.prototype.toString = function toString () { | ||
@@ -41,3 +62,10 @@ return codec.bufferToString(this.buffer) | ||
| // get the multiaddr as a convinent options object to be dropped in net.createConnection | ||
| /** | ||
| * Returns Multiaddr as a convinient options object to be used with net.createConnection | ||
| * | ||
| * @returns {{family: String, host: String, transport: String, port: String}} | ||
| * @example | ||
| * Multiaddr('/ip4/127.0.0.1/tcp/4001').toOptions() | ||
| * // { family: 'ipv4', host: '127.0.0.1', transport: 'tcp', port: '4001' } | ||
| */ | ||
| Multiaddr.prototype.toOptions = function toOptions () { | ||
@@ -53,3 +81,10 @@ var opts = {} | ||
| // get the multiaddr protocols | ||
| /** | ||
| * Returns Multiaddr as a human-readable string | ||
| * | ||
| * @returns {String} | ||
| * @example | ||
| * Multiaddr('/ip4/127.0.0.1/tcp/4001').inspect() | ||
| * // '<Multiaddr 047f000001060fa1 - /ip4/127.0.0.1/tcp/4001>' | ||
| */ | ||
| Multiaddr.prototype.inspect = function inspect () { | ||
@@ -61,3 +96,17 @@ return '<Multiaddr ' + | ||
| // get the multiaddr protocols | ||
| /** | ||
| * Returns the protocols the Multiaddr is defined with, as an array of objects, in | ||
| * left-to-right order. Each object contains the protocol code, protocol name, | ||
| * and the size of its address space in bits. | ||
| * [See list of protocols](https://github.com/multiformats/multiaddr/blob/master/protocols.csv) | ||
| * | ||
| * @returns {Array.<Object>} protocols - All the protocols the address is composed of | ||
| * @returns {Number} protocols[].code | ||
| * @returns {Number} protocols[].size | ||
| * @returns {String} protocols[].name | ||
| * @example | ||
| * Multiaddr('/ip4/127.0.0.1/tcp/4001').protos() | ||
| * // [ { code: 4, size: 32, name: 'ip4' }, | ||
| * // { code: 6, size: 16, name: 'tcp' } ] | ||
| */ | ||
| Multiaddr.prototype.protos = function protos () { | ||
@@ -70,3 +119,11 @@ return map(this.protoCodes(), function (code) { | ||
| // get the multiaddr protocol codes | ||
| /** | ||
| * Returns the codes of the protocols in left-to-right order. | ||
| * [See list of protocols](https://github.com/multiformats/multiaddr/blob/master/protocols.csv) | ||
| * | ||
| * @returns {Array.<Number>} protocol codes | ||
| * @example | ||
| * Multiaddr('/ip4/127.0.0.1/tcp/4001').protoCodes() | ||
| * // [ 4, 6 ] | ||
| */ | ||
| Multiaddr.prototype.protoCodes = function protoCodes () { | ||
@@ -90,3 +147,11 @@ const codes = [] | ||
| // get the multiaddr protocol string names | ||
| /** | ||
| * Returns the names of the protocols in left-to-right order. | ||
| * [See list of protocols](https://github.com/multiformats/multiaddr/blob/master/protocols.csv) | ||
| * | ||
| * @return {Array.<String>} protocol names | ||
| * @example | ||
| * Multiaddr('/ip4/127.0.0.1/tcp/4001').protoNames() | ||
| * // [ 'ip4', 'tcp' ] | ||
| */ | ||
| Multiaddr.prototype.protoNames = function protoNames () { | ||
@@ -98,3 +163,12 @@ return map(this.protos(), function (proto) { | ||
| // Returns a tuple of parts: | ||
| /** | ||
| * Returns a tuple of parts | ||
| * | ||
| * @return {Array.<Array>} tuples | ||
| * @return {Number} tuples[].0 code of protocol | ||
| * @return {Buffer} tuples[].1 contents of address | ||
| * @example | ||
| * Multiaddr("/ip4/127.0.0.1/tcp/4001").tuples() | ||
| * // [ [ 4, <Buffer 7f 00 00 01> ], [ 6, <Buffer 0f a1> ] ] | ||
| */ | ||
| Multiaddr.prototype.tuples = function tuples () { | ||
@@ -104,3 +178,12 @@ return codec.bufferToTuples(this.buffer) | ||
| // Returns a tuple of string parts: | ||
| /** | ||
| * Returns a tuple of string/number parts | ||
| * | ||
| * @return {Array.<Array>} tuples | ||
| * @return {Number} tuples[].0 code of protocol | ||
| * @return {(String|Number)} tuples[].1 contents of address | ||
| * @example | ||
| * Multiaddr("/ip4/127.0.0.1/tcp/4001").stringTuples() | ||
| * // [ [ 4, '127.0.0.1' ], [ 6, 4001 ] ] | ||
| */ | ||
| Multiaddr.prototype.stringTuples = function stringTuples () { | ||
@@ -111,2 +194,20 @@ var t = codec.bufferToTuples(this.buffer) | ||
| /** | ||
| * Encapsulates a Multiaddr in another Multiaddr | ||
| * | ||
| * @param {Multiaddr} addr - Multiaddr to add into this Multiaddr | ||
| * @return {Multiaddr} | ||
| * @example | ||
| * var mh1 = Multiaddr('/ip4/8.8.8.8/tcp/1080') | ||
| * // <Multiaddr 0408080808060438 - /ip4/8.8.8.8/tcp/1080> | ||
| * | ||
| * var mh2 = Multiaddr('/ip4/127.0.0.1/tcp/4001') | ||
| * // <Multiaddr 047f000001060fa1 - /ip4/127.0.0.1/tcp/4001> | ||
| * | ||
| * var mh3 = mh1.encapsulate(mh2) | ||
| * // <Multiaddr 0408080808060438047f000001060fa1 - /ip4/8.8.8.8/tcp/1080/ip4/127.0.0.1/tcp/4001> | ||
| * | ||
| * mh3.toString() | ||
| * // '/ip4/8.8.8.8/tcp/1080/ip4/127.0.0.1/tcp/4001' | ||
| */ | ||
| Multiaddr.prototype.encapsulate = function encapsulate (addr) { | ||
@@ -117,2 +218,20 @@ addr = Multiaddr(addr) | ||
| /** | ||
| * Decapsulates a Multiaddr from another Multiaddr | ||
| * | ||
| * @param {Multiaddr} addr - Multiaddr to remove from this Multiaddr | ||
| * @return {Multiaddr} | ||
| * @example | ||
| * var mh1 = Multiaddr('/ip4/8.8.8.8/tcp/1080') | ||
| * // <Multiaddr 0408080808060438 - /ip4/8.8.8.8/tcp/1080> | ||
| * | ||
| * var mh2 = Multiaddr('/ip4/127.0.0.1/tcp/4001') | ||
| * // <Multiaddr 047f000001060fa1 - /ip4/127.0.0.1/tcp/4001> | ||
| * | ||
| * var mh3 = mh1.encapsulate(mh2) | ||
| * // <Multiaddr 0408080808060438047f000001060fa1 - /ip4/8.8.8.8/tcp/1080/ip4/127.0.0.1/tcp/4001> | ||
| * | ||
| * mh3.decapsulate(mh2).toString() | ||
| * // '/ip4/8.8.8.8/tcp/1080' | ||
| */ | ||
| Multiaddr.prototype.decapsulate = function decapsulate (addr) { | ||
@@ -128,2 +247,20 @@ addr = addr.toString() | ||
| /** | ||
| * Checks if two Multiaddrs are the same | ||
| * | ||
| * @param {Multiaddr} addr | ||
| * @return {Bool} | ||
| * @example | ||
| * var mh1 = Multiaddr('/ip4/8.8.8.8/tcp/1080') | ||
| * // <Multiaddr 0408080808060438 - /ip4/8.8.8.8/tcp/1080> | ||
| * | ||
| * var mh2 = Multiaddr('/ip4/127.0.0.1/tcp/4001') | ||
| * // <Multiaddr 047f000001060fa1 - /ip4/127.0.0.1/tcp/4001> | ||
| * | ||
| * mh1.equals(mh1) | ||
| * // true | ||
| * | ||
| * mh1.equals(mh2) | ||
| * // false | ||
| */ | ||
| Multiaddr.prototype.equals = function equals (addr) { | ||
@@ -133,3 +270,15 @@ return this.buffer.equals(addr.buffer) | ||
| // get a node friendly address object | ||
| /** | ||
| * Gets a Multiaddrs node-friendly address object. Note that protocol information | ||
| * is left out: in Node (and most network systems) the protocol is unknowable | ||
| * given only the address. | ||
| * | ||
| * Has to be a ThinWaist Address, otherwise throws error | ||
| * | ||
| * @returns {{family: String, address: String, port: String}} | ||
| * @throws {Error} Throws error if Multiaddr is not a Thin Waist address | ||
| * @example | ||
| * Multiaddr('/ip4/127.0.0.1/tcp/4001').nodeAddress() | ||
| * // {family: 'IPv4', address: '127.0.0.1', port: '4001'} | ||
| */ | ||
| Multiaddr.prototype.nodeAddress = function nodeAddress () { | ||
@@ -149,3 +298,14 @@ if (!this.isThinWaistAddress()) { | ||
| // from a node friendly address object | ||
| /** | ||
| * Creates a Multiaddr from a node-friendly address object | ||
| * | ||
| * @param {String} addr | ||
| * @param {String} transport | ||
| * @returns {Multiaddr} multiaddr | ||
| * @throws {Error} Throws error if addr is not truthy | ||
| * @throws {Error} Throws error if transport is not truthy | ||
| * @example | ||
| * Multiaddr.fromNodeAddress({address: '127.0.0.1', port: '4001'}, 'tcp') | ||
| * // <Multiaddr 047f000001060fa1 - /ip4/127.0.0.1/tcp/4001> | ||
| */ | ||
| Multiaddr.fromNodeAddress = function fromNodeAddress (addr, transport) { | ||
@@ -158,4 +318,26 @@ if (!addr) throw new Error('requires node address object') | ||
| // returns whether this address is a standard combination: | ||
| // /{IPv4, IPv6}/{TCP, UDP} | ||
| // TODO find a better example, not sure about it's good enough | ||
| /** | ||
| * Returns if a Multiaddr is a Thin Waist address or not. | ||
| * | ||
| * Thin Waist is if a Multiaddr adheres to the standard combination of: | ||
| * | ||
| * `{IPv4, IPv6}/{TCP, UDP}` | ||
| * | ||
| * @param {Multiaddr} [addr] - Defaults to using `this` instance | ||
| * @returns {Boolean} isThinWaistAddress | ||
| * @example | ||
| * const mh1 = Multiaddr('/ip4/127.0.0.1/tcp/4001') | ||
| * // <Multiaddr 047f000001060fa1 - /ip4/127.0.0.1/tcp/4001> | ||
| * const mh2 = Multiaddr('/ip4/192.168.2.1/tcp/5001') | ||
| * // <Multiaddr 04c0a80201061389 - /ip4/192.168.2.1/tcp/5001> | ||
| * const mh3 = mh1.encapsulate(mh2) | ||
| * // <Multiaddr 047f000001060fa104c0a80201061389 - /ip4/127.0.0.1/tcp/4001/ip4/192.168.2.1/tcp/5001> | ||
| * mh1.isThinWaistAddress() | ||
| * // true | ||
| * mh2.isThinWaistAddress() | ||
| * // true | ||
| * mh3.isThinWaistAddress() | ||
| * // false | ||
| */ | ||
| Multiaddr.prototype.isThinWaistAddress = function isThinWaistAddress (addr) { | ||
@@ -177,5 +359,17 @@ var protos = (addr || this).protos() | ||
| // parses the "stupid string" format: | ||
| // <proto><IPv>://<IP Addr>[:<proto port>] | ||
| // udp4://1.2.3.4:5678 | ||
| // TODO rename this to something else than "stupid string" | ||
| /** | ||
| * Converts a "stupid string" into a Multiaddr. | ||
| * | ||
| * Stupid string format: | ||
| * ``` | ||
| * <proto><IPv>://<IP Addr>[:<proto port>] | ||
| * udp4://1.2.3.4:5678 | ||
| * ``` | ||
| * | ||
| * @param {String} [str] - String in the "stupid" format | ||
| * @throws {NotImplemented} | ||
| * @returns {undefined} | ||
| * @todo Not Implemented yet | ||
| */ | ||
| Multiaddr.prototype.fromStupidString = function fromStupidString (str) { | ||
@@ -185,5 +379,26 @@ throw NotImplemented | ||
| // patch this in | ||
| /** | ||
| * Object containing table, names and codes of all supported protocols. | ||
| * To get the protocol values from a Multiaddr, you can use | ||
| * [`.protos()`](#multiaddrprotos), | ||
| * [`.protoCodes()`](#multiaddrprotocodes) or | ||
| * [`.protoNames()`](#multiaddrprotonames) | ||
| * | ||
| * @instance | ||
| * @returns {{table: Array, names: Object, codes: Object}} | ||
| * | ||
| */ | ||
| Multiaddr.protocols = protocols | ||
| /** | ||
| * Returns if something is a Multiaddr or not | ||
| * | ||
| * @param {Multiaddr} addr | ||
| * @return {Bool} isMultiaddr | ||
| * @example | ||
| * Multiaddr.isMultiaddr(Multiaddr('/ip4/127.0.0.1/tcp/4001')) | ||
| * // true | ||
| * Multiaddr.isMultiaddr('/ip4/127.0.0.1/tcp/4001') | ||
| * // false | ||
| */ | ||
| Multiaddr.isMultiaddr = function isMultiaddr (addr) { | ||
@@ -190,0 +405,0 @@ if (addr.constructor && addr.constructor.name) { |
@@ -45,3 +45,4 @@ 'use strict' | ||
| [477, 0, 'ws'], | ||
| [275, 0, 'libp2p-webrtc-star'] | ||
| [275, 0, 'libp2p-webrtc-star'], | ||
| [276, 0, 'libp2p-webrtc-direct'] | ||
| ] | ||
@@ -48,0 +49,0 @@ |
Sorry, the diff of this file is not supported yet
Sorry, the diff of this file is too big to display
Sorry, the diff of this file is not supported yet
Sorry, the diff of this file is too big to display
New alerts
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
Fixed alerts
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
Improved metrics
- Total package byte prevSize
- increased by3.48%
632648
- Number of package files
- increased by6.67%
16
- Lines of code
- increased by5.34%
8483
Worsened metrics
- Number of lines in readme file
- decreased by-49.82%
139
No dependency changes