docs: update addressBook get and getMultiaddrsForPeer return values

MIGRATION_TEMPLATE.md

@@ -0,0 +1,45 @@
+<!--Specify versions for migration below-->
+# Migrating to libp2p@__
+
+A migration guide for refactoring your application code from libp2p v__ to v__.
+
+## Table of Contents
+
+- [API](#api)
+- [Module Updates](#module-updates)
+
+## API
+
+<!--Describe breaking APIs with examples for Before and After
+Example:
+
+### Peer Discovery
+
+__Describe__
+
+**Before**
+
+```js
+
+```
+
+**After**
+
+```js
+
+```
+
+-->
+
+## Module Updates
+
+With this release you should update the following libp2p modules if you are relying on them:
+
+<!--Specify module versions in JSON for migration below.
+It's recommended to check package.json changes for this: 
+`git diff <release> <prev> -- package.json`
+-->
+
+```json
+
+```

doc/API.md

@@ -760,7 +760,7 @@ Get the known [`Addresses`][address] of a provided peer.
 
 | Type | Description |
 |------|-------------|
-| `Array<Address>` | Array of peer's [`Addresses`][address] containing the multiaddr and its metadata |
+| `Array<Address>|undefined` | Array of peer's [`Addresses`][address] containing the multiaddr and its metadata if available, otherwise undefined |
 
 #### Example
 
@@ -797,7 +797,7 @@ Get the known `Multiaddr` of a provided peer. All returned multiaddrs will inclu
 
 | Type | Description |
 |------|-------------|
-| `Array<Multiaddr>` | Array of peer's multiaddr |
+| `Array<Multiaddr>|undefined` | Array of peer's multiaddr if available, otherwise undefined |
 
 #### Example
 

doc/CONFIGURATION.md

@@ -304,7 +304,7 @@ const node = await Libp2p.create({
   },
   config: {
     peerDiscovery: {
-      webRTCStar: {
+      [WebRTCStar.tag]: {
         enabled: true
       }
     }

src/dialer/index.js

@@ -112,7 +112,7 @@ class Dialer {
       this.peerStore.addressBook.add(id, multiaddrs)
     }
 
-    let addrs = this.peerStore.addressBook.getMultiaddrsForPeer(id)
+    let addrs = this.peerStore.addressBook.getMultiaddrsForPeer(id) || []
 
     // If received a multiaddr to dial, it should be the first to use
     // But, if we know other multiaddrs for the peer, we should try them too.

src/peer-store/address-book.js

@@ -168,8 +168,9 @@ class AddressBook extends Book {
   /**
    * Get the known multiaddrs for a given peer. All returned multiaddrs
    * will include the encapsulated `PeerId` of the peer.
+   * Returns `undefined` if there are no known multiaddrs for the given peer.
    * @param {PeerId} peerId
-   * @returns {Array<Multiaddr>}
+   * @returns {Array<Multiaddr>|undefined}
    */
   getMultiaddrsForPeer (peerId) {
     if (!PeerId.isPeerId(peerId)) {

src/peer-store/book.js

@@ -77,8 +77,9 @@ class Book {
 
   /**
    * Get the known data of a provided peer.
+   * Returns `undefined` if there is no available data for the given peer.
    * @param {PeerId} peerId
-   * @returns {Array<Data>}
+   * @returns {Array<Data>|undefined}
    */
   get (peerId) {
     if (!PeerId.isPeerId(peerId)) {

test/dialing/direct.node.js

@@ -96,6 +96,15 @@ describe('Dialing (direct, TCP)', () => {
       .and.to.have.nested.property('._errors[0].code', ErrorCodes.ERR_TRANSPORT_UNAVAILABLE)
   })
 
+  it('should fail to connect if peer has no known addresses', async () => {
+    const dialer = new Dialer({ transportManager: localTM, peerStore })
+    const peerId = await PeerId.createFromJSON(Peers[1])
+
+    await expect(dialer.connectToPeer(peerId))
+      .to.eventually.be.rejectedWith(Error)
+      .and.to.have.nested.property('.code', ErrorCodes.ERR_NO_VALID_ADDRESSES)
+  })
+
   it('should be able to connect to a given peer id', async () => {
     const peerStore = new PeerStore()
     const dialer = new Dialer({