diff --git a/docs/MODULE.md b/docs/MODULE.md index 12681bfd99..67de596e13 100644 --- 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 index 8c4eb0c62f..41cc548399 100644 --- 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 index b59c009126..f4d2d8d518 100644 --- 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 index 81d186f240..92dc51220e 100644 --- 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 index 1b707d90e2..fef01450f4 100644 --- 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,7 +191,7 @@ Prints objects like: { extra: 'dial backoff', - id: 'QmWtewmnzJiQevJPSmG9s8aC7yRfK2WXTCdRc1pCbDFu6z', + id: PeerId('QmWtewmnzJiQevJPSmG9s8aC7yRfK2WXTCdRc1pCbDFu6z'), responses: [ { addrs: [ @@ -199,7 +199,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 @@ -258,7 +258,7 @@ Prints objects like: { extra: 'dial backoff', - id: 'QmWtewmnzJiQevJPSmG9s8aC7yRfK2WXTCdRc1pCbDFu6z', + id: PeerId('QmWtewmnzJiQevJPSmG9s8aC7yRfK2WXTCdRc1pCbDFu6z'), responses: [ { addrs: [ @@ -266,7 +266,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 @@ -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 index 9ff6af02bc..9828c324f3 100644 --- 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 index f28d13c9b2..8a91e2fcaa 100644 --- 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 index 61b74fab61..93055266ad 100644 --- 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 index 5069d45f24..e7126b15e2 100644 --- 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 index ff7cfb6278..7c6723d24e 100644 --- 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 index 8a302fece3..5168998a96 100644 --- 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 index 834599a289..432ceae43b 100644 --- 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 index 22296b1cec..da2de54e01 100644 --- 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 index c9db832628..60c9b7b2f3 100644 --- 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 new file mode 100644 index 0000000000..731e953f91 --- /dev/null +++ b/docs/upgrading/v0.62-v0.63.md @@ -0,0 +1,124 @@ + +# Migrating to ipfs@0.63 and ipfs-core@0.15 + +> A migration guide for refactoring your application code from `ipfs@0.63.x` to `ipfs@0.64.x` + +## Table of Contents + +- [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`, previously it was a `Promise` +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 index 1d4a4c5d75..2b32098657 100644 --- 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/*"],