refactor: export types and utilities statically (#1908)

Allows users to access these additional types and utilities without having to create an instance first.

BREAKING CHANGE: `ipfs.util.isIPFS` and `ipfs.util.crypto` have moved to static exports and should be accessed via `const { isIPFS, crypto } = require('ipfs')`.

The modules available under `ipfs.types.*` have also become static exports.

License: MIT
Signed-off-by: Alan Shaw <alan.shaw@protocol.ai>

README.md

@@ -68,8 +68,7 @@ You can check the development status at the [Kanban Board](https://waffle.io/ipf
       - [Crypto and Key Management](#crypto-and-key-management)
       - [Network](#network)
       - [Node Management](#node-management)
-      - [Domain data types](#domain-data-types)
-      - [Util](#util)
+    - [Static types and utils](#static-types-and-utils)
 - [FAQ](#faq)
 - [Running js-ipfs with Docker](#running-js-ipfs-with-docker)
 - [Packages](#packages)
@@ -654,26 +653,27 @@ The core API is grouped into several areas:
   - [`ipfs.config.set(key, value, [callback])`](https://github.com/ipfs/interface-ipfs-core/tree/master/SPEC/CONFIG.md#configset)
   - [`ipfs.config.replace(config, [callback])`](https://github.com/ipfs/interface-ipfs-core/tree/master/SPEC/CONFIG.md#configreplace)
 
-#### Domain data types
+#### Static types and utils
 
-A set of data types are exposed directly from the IPFS instance under `ipfs.types`. That way you're not required to import/require the following.
+Aside from the default export, `ipfs` exports various types and utilities that are included in the bundle:
 
-- [`ipfs.types.Buffer`](https://www.npmjs.com/package/buffer)
-- [`ipfs.types.PeerId`](https://github.com/libp2p/js-peer-id)
-- [`ipfs.types.PeerInfo`](https://github.com/libp2p/js-peer-info)
-- [`ipfs.types.multiaddr`](https://github.com/multiformats/js-multiaddr)
-- [`ipfs.types.multibase`](https://github.com/multiformats/js-multibase)
-- [`ipfs.types.multihash`](https://github.com/multiformats/js-multihash)
-- [`ipfs.types.CID`](https://github.com/ipld/js-cid)
-- [`ipfs.types.dagPB`](https://github.com/ipld/js-ipld-dag-pb)
-- [`ipfs.types.dagCBOR`](https://github.com/ipld/js-ipld-dag-cbor)
+- [`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)
+- [`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/multihash)
+- [`CID`](https://www.npmjs.com/package/cids)
 
-#### Util
+These can be accessed like this, for example:
 
-A set of utils are exposed directly from the IPFS instance under `ipfs.util`. That way you're not required to import/require the following:
-
-- [`ipfs.util.crypto`](https://github.com/libp2p/js-libp2p-crypto)
-- [`ipfs.util.isIPFS`](https://github.com/ipfs-shipyard/is-ipfs)
+```js
+const { CID } = require('ipfs')
+// ...or from an es-module:
+import { CID } from 'ipfs'
+```
 
 ## FAQ
 

examples/browser-add-readable-stream/index.js

@@ -5,6 +5,7 @@
 
 const repoPath = `ipfs-${Math.random()}`
 const ipfs = new Ipfs({ repo: repoPath })
+const { Buffer } = Ipfs
 
 ipfs.on('ready', () => {
   const directory = 'directory'
@@ -41,13 +42,13 @@ const createFiles = (directory) => {
     path: `${directory}/file1.txt`,
 
     // content could be a stream, a url etc
-    content: ipfs.types.Buffer.from('one', 'utf8')
+    content: Buffer.from('one', 'utf8')
   }, {
     path: `${directory}/file2.txt`,
-    content: ipfs.types.Buffer.from('two', 'utf8')
+    content: Buffer.from('two', 'utf8')
   }, {
     path: `${directory}/file3.txt`,
-    content: ipfs.types.Buffer.from('three', 'utf8')
+    content: Buffer.from('three', 'utf8')
   }]
 }
 

examples/browser-readablestream/utils.js

@@ -1,5 +1,7 @@
 'use strict'
 
+const { Buffer } = require('../../')
+
 const log = (line) => {
   const output = document.getElementById('output')
   let message
@@ -40,7 +42,7 @@ const dragDrop = (ipfs) => {
         reader.onload = (event) => {
           ipfs.add({
             path: file.name,
-            content: ipfs.types.Buffer.from(event.target.result)
+            content: Buffer.from(event.target.result)
           }, {
             progress: (addedBytes) => {
               progress.textContent = `IPFS: Adding ${file.name} ${parseInt((addedBytes / file.size) * 100)}%\r\n`

src/core/index.js

@@ -98,17 +98,6 @@ class IPFS extends EventEmitter {
     this.log = debug('jsipfs')
     this.log.err = debug('jsipfs:err')
 
-    // IPFS types
-    this.types = {
-      Buffer: Buffer,
-      PeerId: PeerId,
-      PeerInfo: PeerInfo,
-      multiaddr: multiaddr,
-      multibase: multibase,
-      multihash: multihash,
-      CID: CID
-    }
-
     // IPFS Core Internals
     // this._repo - assigned above
     this._peerInfoBook = new PeerBook()
@@ -180,18 +169,14 @@ class IPFS extends EventEmitter {
 
     this.state = require('./state')(this)
 
-    // ipfs.util
-    this.util = {
-      crypto,
-      isIPFS
-    }
-
     boot(this)
   }
 }
 
-exports = module.exports = IPFS
+module.exports = IPFS
+
+Object.assign(module.exports, { crypto, isIPFS, Buffer, CID, multiaddr, multibase, multihash, PeerId, PeerInfo })
 
-exports.createNode = (options) => {
+module.exports.createNode = (options) => {
   return new IPFS(options)
 }

test/core/exports.spec.js

@@ -0,0 +1,31 @@
+/* eslint-env mocha */
+'use strict'
+
+const crypto = require('libp2p-crypto')
+const isIPFS = require('is-ipfs')
+const CID = require('cids')
+const multiaddr = require('multiaddr')
+const multibase = require('multibase')
+const multihash = require('multihashes')
+const PeerId = require('peer-id')
+const PeerInfo = require('peer-info')
+const chai = require('chai')
+const dirtyChai = require('dirty-chai')
+const expect = chai.expect
+chai.use(dirtyChai)
+
+const Ipfs = require('../../')
+
+describe('exports', () => {
+  it('should export the expected types and utilities', () => {
+    expect(Ipfs.crypto).to.equal(crypto)
+    expect(Ipfs.isIPFS).to.equal(isIPFS)
+    expect(Ipfs.Buffer).to.equal(Buffer)
+    expect(Ipfs.CID).to.equal(CID)
+    expect(Ipfs.multiaddr).to.equal(multiaddr)
+    expect(Ipfs.multibase).to.equal(multibase)
+    expect(Ipfs.multihash).to.equal(multihash)
+    expect(Ipfs.PeerId).to.equal(PeerId)
+    expect(Ipfs.PeerInfo).to.equal(PeerInfo)
+  })
+})

test/core/init.spec.js

@@ -8,8 +8,6 @@ const expect = chai.expect
 chai.use(dirtyChai)
 const isNode = require('detect-node')
 const hat = require('hat')
-const crypto = require('libp2p-crypto')
-const isIPFS = require('is-ipfs')
 const IPFS = require('../../src/core')
 
 const privateKey = 'CAASqAkwggSkAgEAAoIBAQChVmiObYo6pkKrMSd3OzW1cTL+RDmX1rkETYGKWV9TPXMNgElFTYoYHqT9QZomj5RI8iUmHccjzqr4J0mV+E0NpvHHOLlmDZ82lAw2Zx7saUkeQWvC0S9Z0o3aTx2sSubZV53rSomkZgQH4fYTs4RERejV4ltzLFdzQQBwWrBvlagpPHUCxKDUCnE5oIzdbD26ltWViPBWr7TfotzC8Lyi/tceqCpHMUJGMbsVgypnlgpey07MBvs71dVh5LcRen/ztsQO6Yju4D3QgWoyD0SIUdJFvBzEwL9bSiA3QjUc/fkGd7EcdN5bebYOqAi4ZIiAMLp3i4+B8Tzq/acull43AgMBAAECggEBAIDgZE75o4SsEO9tKWht7L5OeXxxBUyMImkUfJkGQUZd/MzZIC5y/Q+9UvBW+gs5gCsw+onTGaM50Iq/32Ej4nE4XURVxIuH8BmJ86N1hlc010qK2cjajqeCsPulXT+m6XbOLYCpnv+q2idt0cL1EH/1FEPeOEztK8ION4qIdw36SoykfTx/RqtkKHtS01AwN82EOPbWk7huyQT5R5MsCZmRJXBFkpNtiL+8619BH2aVlghHO4NouF9wQjdz/ysVuyYg+3rX2cpGjuHDTZ6hVQiJD1lF6D+dua7UPyHYAG2iRQiKZmCjitt9ywzPxiRaYF/aZ02FEMWckZulR09axskCgYEAzjl6ER8WwxYHn4tHse+CrIIF2z5cscdrh7KSwd3Rse9hIIBDJ/0KkvoYd1IcWrS8ywLrRfSLIjEU9u7IN1m+IRVWJ61fXNqOHm9clAu6qNhCN6W2+JfxDkUygTwmsq0v3huO+qkiMQz+a4nAXJe8Utd36ywgPhVGxFa/7x1v1N0CgYEAyEdiYRFf1aQZcO7+B2FH+tkGJsB30VIBhcpG9EukuQUUulLHhScc/KRj+EFAACLdkTqlVI0xVYIWaaCXwoQCWKixjZ5mYPC+bBLgn4IoDS6XTdHtR7Vn3UUvGTKsM0/z4e8/0eSzGNCHoYez9IoBlPNic0sQuST4jzgS2RYnFCMCgYASWSzSLyjwTJp7CIJlg4Dl5l+tBRxsOOkJVssV8q2AnmLO6HqRKUNylkvs+eJJ88DEc0sJm1txvFo4KkCoJBT1jpduyk8szMlOTew3w99kvHEP0G+6KJKrCV8X/okW5q/WnC8ZgEjpglV0rfnugxWfbUpfIzrvKydzuqAzHzRfBQKBgQDANtKSeoxRjEbmfljLWHAure8bbgkQmfXgI7xpZdfXwqqcECpw/pLxXgycDHOSLeQcJ/7Y4RGCEXHVOk2sX+mokW6mjmmPjD4VlyCBtfcef6KzC1EBS3c9g9KqCln+fTOBmY7UsPu6SxiAzK7HeVP/Un8gS+Dm8DalrZlZQ8uJpQKBgF6mL/Xo/XUOiz2jAD18l8Y6s49bA9H2CoLpBGTV1LfY5yTFxRy4R3qnX/IzsKy567sbtkEFKJxplc/RzCQfrgbdj7k26SbKtHR3yERaFGRYq8UeAHeYC1/N19LF5BMQL4y5R4PJ1SFPeJCL/wXiMqs1maTqvKqtc4bbegNdwlxn'
@@ -105,11 +103,4 @@ describe('init', () => {
       })
     })
   })
-
-  it('util', () => {
-    expect(ipfs.util).to.be.deep.equal({
-      crypto: crypto,
-      isIPFS: isIPFS
-    })
-  })
 })

test/core/interface.spec.js

@@ -198,8 +198,4 @@ describe('interface-ipfs-core tests', function () {
       }
     }
   }), { skip: !isNode })
-
-  tests.types(defaultCommonFactory)
-
-  tests.util(defaultCommonFactory, { skip: { reason: 'FIXME: currently failing' } })
 })

test/http-api/interface.js

@@ -128,8 +128,4 @@ describe('interface-ipfs-core over ipfs-http-client tests', () => {
       }
     }
   }))
-
-  tests.types(defaultCommonFactory, { skip: { reason: 'FIXME: currently failing' } })
-
-  tests.util(defaultCommonFactory, { skip: { reason: 'FIXME: currently failing' } })
 })