test: add tests and docs

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

README.md

@@ -102,12 +102,10 @@ To create an IPFS node programmatically:
 
 ```js
 const IPFS = require('ipfs')
-const node = new IPFS()
+const node = await IPFS.create()
 
-node.on('ready', () => {
-  // Ready to use!
-  // See https://github.com/ipfs/js-ipfs#core-api
-})
+// Ready to use!
+// See https://github.com/ipfs/js-ipfs#core-api
 ```
 
 ### Through command line tool
@@ -124,8 +122,7 @@ The CLI is available by using the command `jsipfs` in your terminal. This is ali
 
 Learn how to bundle with browserify and webpack in the [`examples`](https://github.com/ipfs/js-ipfs/tree/master/examples) folder.
 
-
-You can also load it using a `<script>` using the [unpkg](https://unpkg.com) CDN **or** the [jsDelivr](https://www.jsdelivr.com/package/npm/ipfs) CDN. Inserting one of the following lines will make a `Ipfs` object available in the global namespace.
+You can also load it using a `<script>` using the [unpkg](https://unpkg.com) CDN **or** the [jsDelivr](https://www.jsdelivr.com/package/npm/ipfs) CDN. Inserting one of the following lines will make an `Ipfs` object available in the global namespace.
 
 ```html
 <!-- loading the minified version using unpkg -->
@@ -148,20 +145,20 @@ Inserting one of the above lines will make an `Ipfs` object available in the glo
 
 ```html
 <script>
-const node = new window.Ipfs()
-
-node.on('ready', () => {
+async function main () {
+  const node = await window.Ipfs.create()
   // Ready to use!
   // See https://github.com/ipfs/js-ipfs#core-api
-})
+}
+main()
 </script>
 ```
 
 ## Usage
 
 ### IPFS CLI
 
-The `jsipfs` CLI, available when `js-ipfs` is installed globally, follows(should, it is a WIP) the same interface defined by `go-ipfs`, you can always use the `help` command for help menus.
+The `jsipfs` CLI, available when `js-ipfs` is installed globally, follows (should, it is a WIP) the same interface defined by `go-ipfs`, you can always use the `help` command for help menus.
 
 ```sh
 # Install js-ipfs globally
@@ -191,20 +188,14 @@ If you want a programmatic way to spawn a IPFS Daemon using JavaScript, check ou
 
 ### IPFS Module
 
-Use the IPFS Module as a dependency of a project to __spawn in process instances of IPFS__. Create an instance by calling `new IPFS()` and waiting for its `ready` event:
+Use the IPFS Module as a dependency of a project to __spawn in process instances of IPFS__. Create an instance by calling `await IPFS.create()`:
 
 ```js
 // Create the IPFS node instance
-const node = new IPFS()
-
-node.on('ready', () => {
-  // Your node is now ready to use \o/
-
-  // stopping a node
-  node.stop(() => {
-    // node is now 'offline'
-  })
-})
+const node = await IPFS.create()
+// Your node is now ready to use \o/
+await node.stop()
+// node is now 'offline'
 ```
 
 ### [Tutorials and Examples](/examples)
@@ -216,12 +207,11 @@ You can find some examples and tutorials in the [examples](/examples) folder, th
 #### IPFS Constructor
 
 ```js
-const node = new IPFS([options])
+const node = await IPFS.create([options])
 ```
 
 Creates and returns an instance of an IPFS node. Use the `options` argument to specify advanced configuration. It is an object with any of these properties:
 
-
 ##### `options.repo`
 
 | Type | Default |
@@ -234,7 +224,7 @@ Example:
 
 ```js
 // Store data outside your user directory
-const node = new IPFS({ repo: '/var/ipfs/data' })
+const node = await IPFS.create({ repo: '/var/ipfs/data' })
 ```
 
 ##### `options.init`

src/core/index.js

@@ -142,13 +142,14 @@ class IPFS extends EventEmitter {
     this.state = require('./state')(this)
 
     boot(this)
-    this.once('ready', () => { this.__ready = true })
+    this.once('ready', () => { this._ready = true })
   }
+
   get ready () {
     return new Promise((resolve, reject) => {
-      if (this.__ready) return resolve(this)
-      this.on('ready', () => resolve(this))
-      this.on('error', reject)
+      if (this._ready) return resolve(this)
+      this.once('ready', () => resolve(this))
+      this.once('error', reject)
     })
   }
 }
@@ -163,7 +164,6 @@ module.exports.createNode = (options) => {
   return new IPFS(options)
 }
 
-exports.create = (options) => {
-  let node = new IPFS(options)
-  return node.ready
+module.exports.create = (options) => {
+  return new IPFS(options).ready
 }

test/core/create-node.spec.js

@@ -107,6 +107,88 @@ describe('create node', function () {
     })
   })
 
+  it('should resolve ready promise when initialized not started', async () => {
+    const ipfs = new IPFS({
+      init: true,
+      start: false,
+      repo: tempRepo,
+      config: { Addresses: { Swarm: [] } }
+    })
+
+    expect(ipfs.isOnline()).to.be.false()
+    await ipfs.ready
+    expect(ipfs.isOnline()).to.be.false()
+  })
+
+  it('should resolve ready promise when not initialized and not started', async () => {
+    const ipfs = new IPFS({
+      init: false,
+      start: false,
+      repo: tempRepo,
+      config: { Addresses: { Swarm: [] } }
+    })
+
+    expect(ipfs.isOnline()).to.be.false()
+    await ipfs.ready
+    expect(ipfs.isOnline()).to.be.false()
+  })
+
+  it('should resolve ready promise when initialized and started', async () => {
+    const ipfs = new IPFS({
+      init: true,
+      start: true,
+      repo: tempRepo,
+      config: { Addresses: { Swarm: [] } }
+    })
+
+    expect(ipfs.isOnline()).to.be.false()
+    await ipfs.ready
+    expect(ipfs.isOnline()).to.be.true()
+    await ipfs.stop()
+  })
+
+  it('should resolve ready promise when already ready', async () => {
+    const ipfs = new IPFS({
+      repo: tempRepo,
+      config: { Addresses: { Swarm: [] } }
+    })
+
+    expect(ipfs.isOnline()).to.be.false()
+    await ipfs.ready
+    expect(ipfs.isOnline()).to.be.true()
+    await ipfs.ready
+    expect(ipfs.isOnline()).to.be.true()
+    await ipfs.stop()
+  })
+
+  it('should reject ready promise on boot error', async () => {
+    const ipfs = new IPFS({
+      repo: tempRepo,
+      init: { bits: 1 }, // Too few bits will cause error on boot
+      config: { Addresses: { Swarm: [] } }
+    })
+
+    expect(ipfs.isOnline()).to.be.false()
+
+    try {
+      await ipfs.ready
+    } catch (err) {
+      return expect(ipfs.isOnline()).to.be.false()
+    }
+
+    throw new Error('ready promise did not reject')
+  })
+
+  it('should create a ready node with IPFS.create', async () => {
+    const ipfs = await IPFS.create({
+      repo: tempRepo,
+      config: { Addresses: { Swarm: [] } }
+    })
+
+    expect(ipfs.isOnline()).to.be.true()
+    await ipfs.stop()
+  })
+
   it('init: { bits: 1024 }', function (done) {
     this.timeout(80 * 1000)