diff --git a/README.md b/README.md index 1324e831..2a37fe75 100644 --- a/README.md +++ b/README.md @@ -63,9 +63,9 @@ the global namespace. ```js $ node -> const multiaddr = require('multiaddr') +> const Multiaddr = require('multiaddr') -> const addr = multiaddr("/ip4/127.0.0.1/udp/1234") +> const addr = new Multiaddr("/ip4/127.0.0.1/udp/1234") > addr.bytes @@ -102,10 +102,10 @@ https://multiformats.github.io/js-multiaddr/ To provide multiaddr resolvers you can do: ```js -const multiaddr = require('multiaddr') +const Multiaddr = require('multiaddr') const resolvers = require('multiaddr/src/resolvers') -multiaddr.resolvers.set('dnsaddr', resolvers.dnsaddrResolver) +Multiaddr.resolvers.set('dnsaddr', resolvers.dnsaddrResolver) ``` The available resolvers are: diff --git a/src/index.js b/src/index.js index 9cac08e3..d57166d4 100644 --- a/src/index.js +++ b/src/index.js @@ -11,6 +11,10 @@ const uint8ArrayEquals = require('uint8arrays/equals') const resolvers = new Map() const symbol = Symbol.for('@multiformats/js-multiaddr/multiaddr') +/** + * @typedef {import('./types').Protocol}Protocol + */ + /** * Creates a [multiaddr](https://github.com/multiformats/multiaddr) from * a Uint8Array, String or another Multiaddr instance @@ -22,7 +26,7 @@ class Multiaddr { * to the address format of a [multiaddr](https://github.com/multiformats/multiaddr#string-format) * @example * ```js - * Multiaddr('/ip4/127.0.0.1/tcp/4001') + * new Multiaddr('/ip4/127.0.0.1/tcp/4001') * // * ``` */ @@ -57,7 +61,7 @@ class Multiaddr { * @returns {string} * @example * ```js - * Multiaddr('/ip4/127.0.0.1/tcp/4001').toString() + * new Multiaddr('/ip4/127.0.0.1/tcp/4001').toString() * // '/ip4/127.0.0.1/tcp/4001' * ``` */ @@ -71,7 +75,7 @@ class Multiaddr { * @returns {string} * @example * ```js - * JSON.stringify(Multiaddr('/ip4/127.0.0.1/tcp/4001')) + * JSON.stringify(new Multiaddr('/ip4/127.0.0.1/tcp/4001')) * // '/ip4/127.0.0.1/tcp/4001' * ``` */ @@ -85,7 +89,7 @@ class Multiaddr { * @returns {{family: string, host: string, transport: string, port: number}} * @example * ```js - * Multiaddr('/ip4/127.0.0.1/tcp/4001').toOptions() + * new Multiaddr('/ip4/127.0.0.1/tcp/4001').toOptions() * // { family: 'ipv4', host: '127.0.0.1', transport: 'tcp', port: 4001 } * ``` */ @@ -107,7 +111,7 @@ class Multiaddr { * @returns {string} * @example * ```js - * Multiaddr('/ip4/127.0.0.1/tcp/4001').inspect() + * new Multiaddr('/ip4/127.0.0.1/tcp/4001').inspect() * // '' * ``` */ @@ -129,10 +133,10 @@ class Multiaddr { * and the size of its address space in bits. * [See list of protocols](https://github.com/multiformats/multiaddr/blob/master/protocols.csv) * - * @returns {import('./types').Protocol[]} protocols - All the protocols the address is composed of + * @returns {Protocol[]} protocols - All the protocols the address is composed of * @example * ```js - * Multiaddr('/ip4/127.0.0.1/tcp/4001').protos() + * new Multiaddr('/ip4/127.0.0.1/tcp/4001').protos() * // [ { code: 4, size: 32, name: 'ip4' }, * // { code: 6, size: 16, name: 'tcp' } ] * ``` @@ -148,7 +152,7 @@ class Multiaddr { * @returns {Array} protocol codes * @example * ```js - * Multiaddr('/ip4/127.0.0.1/tcp/4001').protoCodes() + * new Multiaddr('/ip4/127.0.0.1/tcp/4001').protoCodes() * // [ 4, 6 ] * ``` */ @@ -177,7 +181,7 @@ class Multiaddr { * @returns {Array.} protocol names * @example * ```js - * Multiaddr('/ip4/127.0.0.1/tcp/4001').protoNames() + * new Multiaddr('/ip4/127.0.0.1/tcp/4001').protoNames() * // [ 'ip4', 'tcp' ] * ``` */ @@ -191,7 +195,7 @@ class Multiaddr { * @returns {[number, (Uint8Array | undefined)?][]} tuples * @example * ```js - * Multiaddr("/ip4/127.0.0.1/tcp/4001").tuples() + * new Multiaddr("/ip4/127.0.0.1/tcp/4001").tuples() * // [ [ 4, ], [ 6, ] ] * ``` */ @@ -207,7 +211,7 @@ class Multiaddr { * @returns {[number, string?][]} tuples * @example * ```js - * Multiaddr("/ip4/127.0.0.1/tcp/4001").stringTuples() + * new Multiaddr("/ip4/127.0.0.1/tcp/4001").stringTuples() * // [ [ 4, '127.0.0.1' ], [ 6, '4001' ] ] * ``` */ @@ -223,10 +227,10 @@ class Multiaddr { * @returns {Multiaddr} * @example * ```js - * const mh1 = Multiaddr('/ip4/8.8.8.8/tcp/1080') + * const mh1 = new Multiaddr('/ip4/8.8.8.8/tcp/1080') * // * - * const mh2 = Multiaddr('/ip4/127.0.0.1/tcp/4001') + * const mh2 = new Multiaddr('/ip4/127.0.0.1/tcp/4001') * // * * const mh3 = mh1.encapsulate(mh2) @@ -248,10 +252,10 @@ class Multiaddr { * @returns {Multiaddr} * @example * ```js - * const mh1 = Multiaddr('/ip4/8.8.8.8/tcp/1080') + * const mh1 = new Multiaddr('/ip4/8.8.8.8/tcp/1080') * // * - * const mh2 = Multiaddr('/ip4/127.0.0.1/tcp/4001') + * const mh2 = new Multiaddr('/ip4/127.0.0.1/tcp/4001') * // * * const mh3 = mh1.encapsulate(mh2) @@ -281,13 +285,13 @@ class Multiaddr { * @returns {Multiaddr} * @example * ```js - * const addr = Multiaddr('/ip4/0.0.0.0/tcp/8080/p2p/QmcgpsyWgH8Y8ajJz1Cu72KnS5uo2Aa2LpzU7kinSupNKC') + * const addr = new Multiaddr('/ip4/0.0.0.0/tcp/8080/p2p/QmcgpsyWgH8Y8ajJz1Cu72KnS5uo2Aa2LpzU7kinSupNKC') * // * * addr.decapsulateCode(421).toString() * // '/ip4/0.0.0.0/tcp/8080' * - * Multiaddr('/ip4/127.0.0.1/tcp/8080').decapsulateCode(421).toString() + * new Multiaddr('/ip4/127.0.0.1/tcp/8080').decapsulateCode(421).toString() * // '/ip4/127.0.0.1/tcp/8080' * ``` */ @@ -307,7 +311,7 @@ class Multiaddr { * @returns {string | null} peerId - The id of the peer or null if invalid or missing from the ma * @example * ```js - * const mh1 = Multiaddr('/ip4/8.8.8.8/tcp/1080/ipfs/QmValidBase58string') + * const mh1 = new Multiaddr('/ip4/8.8.8.8/tcp/1080/ipfs/QmValidBase58string') * // * * // should return QmValidBase58string or null if the id is missing or invalid @@ -341,7 +345,7 @@ class Multiaddr { * @returns {string | null} path - The path of the multiaddr, or null if no path protocol is present * @example * ```js - * const mh1 = Multiaddr('/ip4/8.8.8.8/tcp/1080/unix/tmp/p2p.sock') + * const mh1 = new Multiaddr('/ip4/8.8.8.8/tcp/1080/unix/tmp/p2p.sock') * // * * // should return utf8 string or null if the id is missing or invalid @@ -375,10 +379,10 @@ class Multiaddr { * @returns {boolean} * @example * ```js - * const mh1 = Multiaddr('/ip4/8.8.8.8/tcp/1080') + * const mh1 = new Multiaddr('/ip4/8.8.8.8/tcp/1080') * // * - * const mh2 = Multiaddr('/ip4/127.0.0.1/tcp/4001') + * const mh2 = new Multiaddr('/ip4/127.0.0.1/tcp/4001') * // * * mh1.equals(mh1) @@ -399,7 +403,7 @@ class Multiaddr { * @example * ```js * Multiaddr.resolvers.set('dnsaddr', resolverFunction) - * const mh1 = Multiaddr('/dnsaddr/bootstrap.libp2p.io/p2p/QmbLHAnMoJPWSCR5Zhtx6BHJX9KiKNN6tpvbUcqanj75Nb') + * const mh1 = new Multiaddr('/dnsaddr/bootstrap.libp2p.io/p2p/QmbLHAnMoJPWSCR5Zhtx6BHJX9KiKNN6tpvbUcqanj75Nb') * const resolvedMultiaddrs = await mh1.resolve() * // [ * // , @@ -437,7 +441,7 @@ class Multiaddr { * @example * * ```js - * Multiaddr('/ip4/127.0.0.1/tcp/4001').nodeAddress() + * new Multiaddr('/ip4/127.0.0.1/tcp/4001').nodeAddress() * // {family: 4, address: '127.0.0.1', port: '4001'} * ``` * @@ -462,7 +466,6 @@ class Multiaddr { } } - // TODO find a better example, not sure about it's good enough /** * Returns if a Multiaddr is a Thin Waist address or not. * @@ -474,18 +477,22 @@ class Multiaddr { * @returns {boolean} isThinWaistAddress * @example * ```js - * const mh1 = Multiaddr('/ip4/127.0.0.1/tcp/4001') + * const mh1 = new Multiaddr('/ip4/127.0.0.1/tcp/4001') * // - * const mh2 = Multiaddr('/ip4/192.168.2.1/tcp/5001') + * const mh2 = new Multiaddr('/ip4/192.168.2.1/tcp/5001') * // * const mh3 = mh1.encapsulate(mh2) * // + * const mh4 = new Multiaddr('/ip4/127.0.0.1/tcp/2000/wss/p2p-webrtc-star/p2p/QmcgpsyWgH8Y8ajJz1Cu72KnS5uo2Aa2LpzU7kinSooo2a') + * // * mh1.isThinWaistAddress() * // true * mh2.isThinWaistAddress() * // true * mh3.isThinWaistAddress() * // false + * mh4.isThinWaistAddress() + * // false * ``` */ isThinWaistAddress (addr) { @@ -559,32 +566,20 @@ class Multiaddr { static isMultiaddr (value) { return value instanceof Multiaddr || Boolean(value && value[symbol]) } + + /** + * Static factory method + * + * @param {string | Uint8Array | Multiaddr | null} [addr] - If String or Uint8Array, needs to adhere + * to the address format of a [multiaddr](https://github.com/multiformats/multiaddr#string-format) + */ + static multiaddr (addr) { + return new Multiaddr(addr) + } } Multiaddr.protocols = protocols Multiaddr.resolvers = resolvers -/** - * Callable Multiaddr factory function - * - * @param {string | Uint8Array | Multiaddr | null} [addr] - If String or Uint8Array, needs to adhere - * to the address format of a [multiaddr](https://github.com/multiformats/multiaddr#string-format) - * @example - * ```js - * Multiaddr('/ip4/127.0.0.1/tcp/4001') - * // - * ``` - */ -const MultiaddrFactory = (addr) => { - return new Multiaddr(addr) -} - -MultiaddrFactory.protocols = protocols -MultiaddrFactory.resolvers = resolvers -MultiaddrFactory.Multiaddr = Multiaddr -MultiaddrFactory.isMultiaddr = Multiaddr.isMultiaddr -MultiaddrFactory.isName = Multiaddr.isName -MultiaddrFactory.fromNodeAddress = Multiaddr.fromNodeAddress - -module.exports = MultiaddrFactory +module.exports = Multiaddr diff --git a/test/index.spec.js b/test/index.spec.js index c01f0df9..aa0aeccc 100644 --- a/test/index.spec.js +++ b/test/index.spec.js @@ -2,16 +2,18 @@ /* eslint-env mocha */ 'use strict' -const multiaddr = require('../src') +const Multiaddr = require('../src') const { expect } = require('aegir/utils/chai') const uint8ArrayFromString = require('uint8arrays/from-string') +const multiaddr = Multiaddr.multiaddr + describe('construction', () => { let udpAddr it('create multiaddr', () => { udpAddr = multiaddr('/ip4/127.0.0.1/udp/1234') - expect(udpAddr instanceof multiaddr.Multiaddr).to.equal(true) + expect(udpAddr instanceof Multiaddr).to.equal(true) }) it('clone multiaddr', () => { @@ -77,7 +79,7 @@ describe('requiring varint', () => { it('create multiaddr', () => { uTPAddr = multiaddr('/ip4/127.0.0.1/udp/1234/utp') - expect(uTPAddr instanceof multiaddr.Multiaddr).to.equal(true) + expect(uTPAddr instanceof Multiaddr).to.equal(true) }) it('clone multiaddr', () => { @@ -116,8 +118,8 @@ describe('manipulation', () => { expect(udpAddr.protoCodes()).to.deep.equal([4, 273]) expect(udpAddr.protoNames()).to.deep.equal(['ip4', 'udp']) - expect(udpAddr.protos()).to.deep.equal([multiaddr.protocols.codes[4], multiaddr.protocols.codes[273]]) - expect(udpAddr.protos()[0] === multiaddr.protocols.codes[4]).to.equal(false) + expect(udpAddr.protos()).to.deep.equal([Multiaddr.protocols.codes[4], Multiaddr.protocols.codes[273]]) + expect(udpAddr.protos()[0] === Multiaddr.protocols.codes[4]).to.equal(false) const udpAddrbytes2 = udpAddr.encapsulate(multiaddr('/udp/5678')) expect(udpAddrbytes2.toString()).to.equal('/ip4/127.0.0.1/udp/1234/udp/5678') @@ -725,7 +727,7 @@ describe('helpers', () => { it('throws on missing address object', () => { expect( // @ts-ignore - () => multiaddr.fromNodeAddress() + () => Multiaddr.fromNodeAddress() ).to.throw( /requires node address/ ) @@ -734,7 +736,7 @@ describe('helpers', () => { it('throws on missing transport', () => { expect( // @ts-ignore - () => multiaddr.fromNodeAddress({ address: '0.0.0.0' }) + () => Multiaddr.fromNodeAddress({ address: '0.0.0.0' }) ).to.throw( /requires transport protocol/ ) @@ -742,7 +744,7 @@ describe('helpers', () => { it('parses a node address', () => { expect( - multiaddr.fromNodeAddress({ + Multiaddr.fromNodeAddress({ address: '192.168.0.1', family: 'IPv4', port: '1234' @@ -857,11 +859,11 @@ describe('helpers', () => { describe('multiaddr.isMultiaddr', () => { it('handles different inputs', () => { - expect(multiaddr.isMultiaddr(multiaddr('/'))).to.be.eql(true) - expect(multiaddr.isMultiaddr('/')).to.be.eql(false) - expect(multiaddr.isMultiaddr(123)).to.be.eql(false) + expect(Multiaddr.isMultiaddr(multiaddr('/'))).to.be.eql(true) + expect(Multiaddr.isMultiaddr('/')).to.be.eql(false) + expect(Multiaddr.isMultiaddr(123)).to.be.eql(false) - expect(multiaddr.isMultiaddr(uint8ArrayFromString('/hello'))).to.be.eql(false) + expect(Multiaddr.isMultiaddr(uint8ArrayFromString('/hello'))).to.be.eql(false) }) }) @@ -870,31 +872,31 @@ describe('helpers', () => { it('valid name dns', () => { const str = '/dns/ipfs.io' const addr = multiaddr(str) - expect(multiaddr.isName(addr)).to.equal(true) + expect(Multiaddr.isName(addr)).to.equal(true) }) it('valid name dnsaddr', () => { const str = '/dnsaddr/ipfs.io' const addr = multiaddr(str) - expect(multiaddr.isName(addr)).to.equal(true) + expect(Multiaddr.isName(addr)).to.equal(true) }) it('valid name dns4', () => { const str = '/dns4/ipfs.io' const addr = multiaddr(str) - expect(multiaddr.isName(addr)).to.equal(true) + expect(Multiaddr.isName(addr)).to.equal(true) }) it('valid name dns6', () => { const str = '/dns6/ipfs.io' const addr = multiaddr(str) - expect(multiaddr.isName(addr)).to.equal(true) + expect(Multiaddr.isName(addr)).to.equal(true) }) it('invalid name', () => { const str = '/ip4/127.0.0.1' const addr = multiaddr(str) - expect(multiaddr.isName(addr)).to.equal(false) + expect(Multiaddr.isName(addr)).to.equal(false) }) }) }) diff --git a/test/resolvers.spec.js b/test/resolvers.spec.js index 1967979b..5ac692e6 100644 --- a/test/resolvers.spec.js +++ b/test/resolvers.spec.js @@ -4,9 +4,10 @@ const { expect } = require('aegir/utils/chai') const sinon = require('sinon') -const multiaddr = require('../src') +const Multiaddr = require('../src') const resolvers = require('../src/resolvers') const Resolver = require('../src/resolvers/dns') +const multiaddr = Multiaddr.multiaddr const dnsaddrStub1 = [ ['dnsaddr=/dnsaddr/ams-1.bootstrap.libp2p.io/p2p/QmSoLer265NRgSp2LA3dPaeykiS1J6DifTC88f5uVQKNAd'], @@ -28,7 +29,7 @@ const dnsaddrStub2 = [ describe('multiaddr resolve', () => { it('should throw if no resolver is available', async () => { - const ma = multiaddr('/dnsaddr/bootstrap.libp2p.io') + const ma = new Multiaddr('/dnsaddr/bootstrap.libp2p.io') // Resolve await expect(ma.resolve()).to.eventually.be.rejected() @@ -38,7 +39,7 @@ describe('multiaddr resolve', () => { describe('dnsaddr', () => { before(() => { // Set resolvers - multiaddr.resolvers.set('dnsaddr', resolvers.dnsaddrResolver) + Multiaddr.resolvers.set('dnsaddr', resolvers.dnsaddrResolver) }) afterEach(() => {