docs: add upgrade guide for ESM release (#4098)

achingbrain · web-flow · commit 7165bf711561 · 2022-05-16T17:40:33.000+01:00
Adds upgrade guide and updates core-api docs with API changes
diff --git a/docs/MODULE.md b/docs/MODULE.md
@@ -377,14 +377,14 @@ Aside from the default export, `ipfs` exports various types and utilities that a
 - [`crypto`](https://www.npmjs.com/package/libp2p-crypto)
 - [`isIPFS`](https://www.npmjs.com/package/is-ipfs)
 - [`Buffer`](https://www.npmjs.com/package/buffer)
-- [`PeerId`](https://www.npmjs.com/package/peer-id)
+- [`PeerId`](https://docs.libp2p.io/concepts/peer-id/)
 - [`PeerInfo`](https://www.npmjs.com/package/peer-info)
 - [`multiaddr`](https://www.npmjs.com/package/multiaddr)
 - [`multibase`](https://www.npmjs.com/package/multibase)
 - [`multihash`](https://www.npmjs.com/package/multihashes)
 - [`multihashing`](https://www.npmjs.com/package/multihashing-async)
 - [`multicodec`](https://www.npmjs.com/package/multicodec)
-- [`CID`](https://www.npmjs.com/package/cids)
+- [`CID`](https://docs.ipfs.io/concepts/content-addressing)
 
 These can be accessed like this, for example:
 
diff --git a/docs/core-api/BITSWAP.md b/docs/core-api/BITSWAP.md
@@ -62,7 +62,7 @@ A great source of [examples][] can be found in the tests for this API.
 
 | Name | Type | Default | Description |
 | ---- | ---- | ------- | ----------- |
-| peerId | [PeerId][], [CID][], `String` or `Uint8Array` | A peer ID to return the wantlist for |
+| peerId | [PeerId][] | A peer ID to return the wantlist for |
 
 ### Options
 
@@ -159,7 +159,7 @@ The returned object contains the following keys:
 
 - `provideBufLen` is an integer.
 - `wantlist` (array of [CID][cid]s)
-- `peers` (array of peer IDs represented by strings)
+- `peers` (array of [PeerId][peerId]s)
 - `blocksReceived` is a [BigInt][1]
 - `dataReceived` is a [BigInt][1]
 - `blocksSent` is a [BigInt][1]
@@ -192,6 +192,6 @@ A great source of [examples][] can be found in the tests for this API.
 
 [1]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt
 [examples]: https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/src/bitswap
-[cid]: https://www.npmjs.com/package/cids
-[peerid]: https://www.npmjs.com/package/peer-id
+[cid]: https://docs.ipfs.io/concepts/content-addressing
+[peerid]: https://docs.libp2p.io/concepts/peer-id/
 [AbortSignal]: https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal
diff --git a/docs/core-api/BLOCK.md b/docs/core-api/BLOCK.md
@@ -226,4 +226,4 @@ A great source of [examples][] can be found in the tests for this API.
 [multihash]: https://github.com/multiformats/multihash
 [examples]: https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/src/block
 [AbortSignal]: https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal
-[cid]: https://www.npmjs.com/package/cids
+[cid]: https://docs.ipfs.io/concepts/content-addressing
diff --git a/docs/core-api/DAG.md b/docs/core-api/DAG.md
@@ -289,6 +289,6 @@ console.log(result)
 A great source of [examples][] can be found in the tests for this API.
 
 [examples]: https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/src/dag
-[cid]: https://www.npmjs.com/package/cids
+[cid]: https://docs.ipfs.io/concepts/content-addressing
 [AbortSignal]: https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal
 [CAR file]: https://ipld.io/specs/transport/car/
diff --git a/docs/core-api/DHT.md b/docs/core-api/DHT.md
@@ -39,7 +39,7 @@
 
 | Name | Type | Description |
 | ---- | ---- | ----------- |
-| peerId | [PeerID][] or [CID][] | The Peer ID of the node to find |
+| peerId | [PeerID][] | The Peer ID of the node to find |
 
 ### Options
 
@@ -61,7 +61,7 @@ An optional object which may have the following keys:
 ```JavaScript
 const info = await ipfs.dht.findPeer('QmcZf59bWwK5XFi76CZX8cbJ4BhTzzA3gU1ZjYZcYW3dwt')
 
-console.log(info.id)
+console.log(info.id.toString())
 /*
 QmcZf59bWwK5XFi76CZX8cbJ4BhTzzA3gU1ZjYZcYW3dwt
 */
@@ -191,15 +191,15 @@ Prints objects like:
 
 {
   extra: 'dial backoff',
-  id: 'QmWtewmnzJiQevJPSmG9s8aC7yRfK2WXTCdRc1pCbDFu6z',
+  id: PeerId('QmWtewmnzJiQevJPSmG9s8aC7yRfK2WXTCdRc1pCbDFu6z'),
   responses: [
     {
       addrs: [
         Multiaddr(/ip4/127.0.0.1/tcp/4001),
         Multiaddr(/ip4/172.20.0.3/tcp/4001),
         Multiaddr(/ip4/35.178.190.196/tcp/1024)
       ],
-      id: 'QmRz5Nth4jTFuJJKcjyb6uwvrhxWbruRvamKY2PJxwJKw8'
+      id: PeerId('QmRz5Nth4jTFuJJKcjyb6uwvrhxWbruRvamKY2PJxwJKw8')
     }
   ],
   type: 1
@@ -258,15 +258,15 @@ Prints objects like:
 
 {
   extra: 'dial backoff',
-  id: 'QmWtewmnzJiQevJPSmG9s8aC7yRfK2WXTCdRc1pCbDFu6z',
+  id: PeerId('QmWtewmnzJiQevJPSmG9s8aC7yRfK2WXTCdRc1pCbDFu6z'),
   responses: [
     {
       addrs: [
         Multiaddr(/ip4/127.0.0.1/tcp/4001),
         Multiaddr(/ip4/172.20.0.3/tcp/4001),
         Multiaddr(/ip4/35.178.190.196/tcp/1024)
       ],
-      id: 'QmRz5Nth4jTFuJJKcjyb6uwvrhxWbruRvamKY2PJxwJKw8'
+      id: PeerId('QmRz5Nth4jTFuJJKcjyb6uwvrhxWbruRvamKY2PJxwJKw8')
     }
   ],
   type: 1
@@ -288,7 +288,7 @@ A great source of [examples][] can be found in the tests for this API.
 
 ## `ipfs.dht.query(peerId, [options])`
 
-> Find the closest Peer IDs to a given Peer ID by querying the DHT.
+> Find the closest Peer IDs to a given Peer ID or CID by querying the DHT.
 
 ### Parameters
 
@@ -331,7 +331,7 @@ Prints objects like:
         Multiaddr(/ip4/172.20.0.3/tcp/4001),
         Multiaddr(/ip4/35.178.190.196/tcp/1024)
       ],
-      id: 'QmRz5Nth4jTFuJJKcjyb6uwvrhxWbruRvamKY2PJxwJKw8'
+      id: PeerId('QmRz5Nth4jTFuJJKcjyb6uwvrhxWbruRvamKY2PJxwJKw8')
     }
   ],
   type: 1
@@ -345,6 +345,6 @@ https://github.com/libp2p/go-libp2p-core/blob/6e566d10f4a5447317a66d64c7459954b9
 A great source of [examples][] can be found in the tests for this API.
 
 [examples]: https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/src/dht
-[peerid]: https://www.npmjs.com/package/peer-id
-[cid]: https://www.npmjs.com/package/cids
+[peerid]: https://docs.libp2p.io/concepts/peer-id/
+[cid]: https://docs.ipfs.io/concepts/content-addressing
 [AbortSignal]: https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal
diff --git a/docs/core-api/FILES.md b/docs/core-api/FILES.md
@@ -1024,7 +1024,7 @@ for await (const file of ipfs.files.ls('/screenshots')) {
 
 [b]: https://www.npmjs.com/package/buffer
 [file]: https://developer.mozilla.org/en-US/docs/Web/API/File
-[cid]: https://www.npmjs.com/package/cids
+[cid]: https://docs.ipfs.io/concepts/content-addressing
 [blob]: https://developer.mozilla.org/en-US/docs/Web/API/Blob
 [IPFS Path]: https://www.npmjs.com/package/is-ipfs#isipfspathpath
 [MFS Path]: https://docs.ipfs.io/guides/concepts/mfs/
diff --git a/docs/core-api/KEY.md b/docs/core-api/KEY.md
@@ -288,5 +288,5 @@ console.log(key)
 A great source of [examples][] can be found in the tests for this API.
 
 [examples]: https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/src/key
-[cid]: https://www.npmjs.com/package/cids
+[cid]: https://docs.ipfs.io/concepts/content-addressing
 [AbortSignal]: https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal
diff --git a/docs/core-api/MISCELLANEOUS.md b/docs/core-api/MISCELLANEOUS.md
@@ -300,5 +300,5 @@ A great source of [examples](https://github.com/ipfs/js-ipfs/blob/master/package
 [examples]: https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/src/miscellaneous
 [rs]: https://www.npmjs.com/package/readable-stream
 [ps]: https://www.npmjs.com/package/pull-stream
-[cid]: https://www.npmjs.com/package/cids
+[cid]: https://docs.ipfs.io/concepts/content-addressing
 [AbortSignal]: https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal
diff --git a/docs/core-api/NAME.md b/docs/core-api/NAME.md
@@ -226,7 +226,7 @@ A great source of [examples][examples-pubsub] can be found in the tests for this
 
 | Name | Type | Description |
 | ---- | ---- | ----------- |
-| value | `String` | An IPNS address such as `/ipns/ipfs.io` |
+| value | `PeerId` or `string` | An IPNS address such as `/ipns/ipfs.io` |
 
 ### Options
 
@@ -261,5 +261,5 @@ A great source of [examples][] can be found in the tests for this API.
 
 [examples]: https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/src/name
 [examples-pubsub]: https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/src/name-pubsub
-[cid]: https://www.npmjs.com/package/cids
+[cid]: https://docs.ipfs.io/concepts/content-addressing
 [AbortSignal]: https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal
diff --git a/docs/core-api/PIN.md b/docs/core-api/PIN.md
@@ -634,5 +634,5 @@ A great source of [examples][] can be found in the tests for this API.
 [Stat]: #stat
 [PinCount]: #pincount
 [examples]: https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/src/pin
-[cid]: https://www.npmjs.com/package/cids
+[cid]: https://docs.ipfs.io/concepts/content-addressing
 [AbortSignal]: https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal
diff --git a/docs/core-api/REFS.md b/docs/core-api/REFS.md
@@ -112,6 +112,6 @@ for await (const ref of ipfs.refs.local()) {
 
 [examples]: https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/src/files-regular
 [b]: https://www.npmjs.com/package/buffer
-[cid]: https://www.npmjs.com/package/cids
+[cid]: https://docs.ipfs.io/concepts/content-addressing
 [blob]: https://developer.mozilla.org/en-US/docs/Web/API/Blob
 [AbortSignal]: https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal
diff --git a/docs/core-api/REPO.md b/docs/core-api/REPO.md
@@ -136,5 +136,5 @@ console.log(version)
 ```
 
 [1]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt
-[cid]: https://www.npmjs.com/package/cids
+[cid]: https://docs.ipfs.io/concepts/content-addressing
 [AbortSignal]: https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal
diff --git a/docs/core-api/STATS.md b/docs/core-api/STATS.md
@@ -34,7 +34,7 @@ An optional object which may have the following keys:
 
 | Name | Type | Default | Description |
 | ---- | ---- | ------- | ----------- |
-| peer | [PeerId][], [CID][] or `String` | `undefined` | Specifies a peer to print bandwidth for |
+| peer | [PeerId][] | `undefined` | Specifies a peer to print bandwidth for |
 | proto | `String` | `undefined` | Specifies a protocol to print bandwidth for |
 | poll | `boolean` | `undefined` | Is used to yield bandwidth info at an interval |
 | interval | `Number` | `undefined` | The time interval to wait between updating output, if `poll` is `true` |
@@ -71,5 +71,5 @@ A great source of [examples][] can be found in the tests for this API.
 [bigNumber]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt
 [examples]: https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/src/stats
 [AbortSignal]: https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal
-[cid]: https://www.npmjs.com/package/cids
-[peerid]: https://www.npmjs.com/package/peer-id
+[cid]: https://docs.ipfs.io/concepts/content-addressing
+[peerid]: https://docs.libp2p.io/concepts/peer-id/
diff --git a/docs/core-api/SWARM.md b/docs/core-api/SWARM.md
@@ -83,7 +83,7 @@ A great source of [examples][] can be found in the tests for this API.
 
 | Name | Type | Description |
 | ---- | ---- | ----------- |
-| addr | [MultiAddr][] | The object to search for references |
+| addr | [MultiAddr][] or [PeerId][] | The PeerId or Multiaddr to connect to |
 
 ### Options
 
@@ -116,7 +116,7 @@ A great source of [examples][] can be found in the tests for this API.
 
 | Name | Type | Description |
 | ---- | ---- | ----------- |
-| addr | [MultiAddr][] | The object to search for references |
+| addr | [MultiAddr][] or [PeerId][] | The PeerId or Multiaddr to disconnect from |
 
 ### Options
 
@@ -228,3 +228,4 @@ A great source of [examples][] can be found in the tests for this API.
 [examples]: https://github.com/ipfs/js-ipfs/blob/master/packages/interface-ipfs-core/src/swarm
 [AbortSignal]: https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal
 [MultiAddr]: https://github.com/multiformats/js-multiaddr
+[peerid]: https://docs.libp2p.io/concepts/peer-id/
diff --git a/docs/upgrading/v0.62-v0.63.md b/docs/upgrading/v0.62-v0.63.md
@@ -0,0 +1,124 @@
+<!--Specify versions for migration below-->
+# Migrating to ipfs@0.63 and ipfs-core@0.15 <!-- omit in toc -->
+
+> A migration guide for refactoring your application code from `ipfs@0.63.x` to `ipfs@0.64.x`
+
+## Table of Contents <!-- omit in toc -->
+
+- [ESM](#esm)
+- [libp2p@0.37.x](#libp2p037x)
+- [PeerIds](#peerids)
+- [multiaddrs](#multiaddrs)
+
+## ESM
+
+The biggest change to `ipfs@0.63.x` is that the module is now [ESM-only](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c).
+
+ESM is the module system for JavaScript, it allows us to structure our code in separate files without polluting a global namespace.
+
+Other systems have tried to fill this gap, notably CommonJS, AMD, RequireJS and others, but ESM is [the official standard format](https://tc39.es/ecma262/#sec-modules) to package JavaScript code for reuse.
+
+If you see errors similar to `Error [ERR_PACKAGE_PATH_NOT_EXPORTED]: No "exports" main defined in node_modules/ipfs/package.json` you are likely trying to load ESM code from a CJS environment via `require`. This is not possible, instead it must be loaded using `import`.
+
+If your application is not yet ESM or you are not ready to port it to ESM, you can use the [dynamic `import` function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import) to load `ipfs` at runtime from a CJS module:
+
+```js
+async function loadIpfs () {
+  const { create } = await import('ipfs-core')
+
+  const node = await create({
+    // ... config here
+  })
+
+  return node
+}
+```
+
+## libp2p@0.37.x
+
+`ipfs@0.63.x` upgrades to `libp2p@0.37.x`.  This is a significant refactor that ports the entire stack to TypeScript and publishes all modules as ESM-only code.
+
+Please see the [libp2p 0.37.x` upgrade guide](https://github.com/libp2p/js-libp2p/blob/master/doc/migrations/v0.36-v.037.md) for how this may affect your application.
+
+## PeerIds
+
+The core `libp2p` module and all supporting modules have now been ported to TypeScript in a complete ground-up rewrite. We took this opportunity to solve a few long-standing problems with some of the data types, particularly in how they relate to use in the browser.
+
+One problem we have solved is that the `PeerId` objects used internally expose some cryptographic operations that require heavyweight libraries to be included in browser bundles due to there being no native web-crypto implementation of the algorithms used in those operations.
+
+With `libp2p@0.37.x` those operations have been encapsulated in the `@libp2p/crypto` module which means `PeerId` objects become a lot more lightweight and can now be exposed/accepted as core-api types so we can use them to differentiate between different data types instead of having to treat everything as strings.
+
+The affected methods are:
+
+```js
+// `peerId` must now be a `PeerId`, previously it was a `string`
+ipfs.bitswap.wantlistForPeer(peerId, options)
+
+// Bitswp peers are now returned as `PeerId[]` instead of `string[]`
+ipfs.bitswap.stat(options)
+
+// `peerId` must now be a `PeerId`
+ipfs.dht.findPeer(peerId, options)
+
+// `peerIdOrCid` must now be a `PeerId` or a `CID`, previously it was a `string` or a `CID`
+ipfs.dht.query(peerIdOrCid, options)
+
+// the following DHT events have their `from` field as `PeerId`, previously it was a `string`
+PeerResponseEvent
+ValueEvent
+DialingPeerEvent
+
+// the following DHT events have had their `from` property removed because it is not exposed by go-ipfs so causes incompatibilities
+QueryErrorEvent
+FinalPeerEvent
+
+// the folloing DHT events have had their `to` property removed because it is not exposed by go-ipfs so causes incompatibilities
+SendingQueryEvent
+
+// the `providers` and `closer` properties (where applicable) of the following events have the `peerId` property specified as a `PeerId`, previously it was a `string`
+PeerResponseEvent
+PeerResponseEvent
+
+// `value` can now be a string or a `PeerId`.  If a string is passed it will be interpreted as a DNS address.
+ipfs.name.resolve(value, options)
+
+// The return type of this method is now `Promise<PeerId[]>`, previously it was a `Promise<string[]>`
+ipfs.pubsub.peers(topic, options)
+
+// `peerId` must now be a `PeerId`, previously it was a `string`
+ipfs.ping(peerId, options)
+
+// the `peer` property of `options` must now be a `PeerId` when specified, previously it was a `string`
+ipfs.stats.bw(options)
+
+// `multiaddrOrPeerId` must be a `Multiaddr` or `PeerId`, previously it was a `Multiaddr` or `string`
+ipfs.swarm.connect(multiaddrOrPeerId, options)
+
+// `multiaddrOrPeerId` must be a `Multiaddr` or `PeerId`, previously it was a `Multiaddr` or `string`
+ipfs.swarm.disconnect(multiaddrOrPeerId, options)
+```
+
+`PeerId`s can be created from strings using the `@libp2p/peer-id` module:
+
+```js
+import { peerIdFromString } from '@libp2p/peer-id'
+
+const peerId = peerIdFromString('Qmfoo')
+```
+
+They can also be created using the `@libp2p/peer-id-factory` module:
+
+```js
+import { createEd25519PeerId } from '@libp2p/peer-id-factory'
+
+const peerId = await createEd25519PeerId()
+```
+
+## multiaddrs
+
+The `multiaddr` module has been ported to Typescript and is now published as ESM-only.
+
+It has been renamed to `@multiformats/multiaddr` so please update your dependencies and replace usage in your code.
+
+The API otherwise is compatible.
+
diff --git a/lerna.json b/lerna.json
@@ -14,8 +14,7 @@
       "message": "chore: publish",
       "createRelease": "github",
       "conventionalCommits": true,
-      "verifyAccess": false,
-      "contents": "dist"
+      "verifyAccess": false
     },
     "version": {
       "allowBranch": ["master", "release/*"],
