Feat/expose ipfs utils

README.md

@@ -94,6 +94,7 @@ You can check the development status at:
       - [Files API](#files-api)
       - [Swarm API](#swarm-api)
       - [libp2p API](#libp2p-api)
+      - [Domain data types](#domain-data-types)
 - [Packages](#packages)
 - [Development](#development)
   - [Clone](#clone)
@@ -193,6 +194,8 @@ The HTTP-API exposed by the js-ipfs daemon follows the [`http-api-spec`](https:/
 
 #### Create a IPFS node instance
 
+The basic startup flow involves (optionally) creating a Repo, creating an IPFS node, `init`-ing it so it can generate its keys, `load`-ing its configuration, and putting it online with `goOnline`. Here is a structural example:
+
 ```JavaScript
 // IPFS will need a repo, it can create one for you or you can pass
 // it a repo instance of the type IPFS Repo
@@ -229,6 +232,8 @@ node.init({ emptyRepo: true, bits: 2048 }, (err) => {
 
 > We are working on making this init process better, see https://github.com/ipfs/js-ipfs/issues/556 for the discussion.
 
+More examples can be found in the [examples folder](./examples)
+
 ### [Tutorials and Examples](/examples)
 
 You can find some examples and tutorials in the [examples](/examples) folder, these exist to help you get started using `js-ipfs`.
@@ -252,6 +257,17 @@ Every IPFS instance also exposes the libp2p API at `ipfs.libp2p`. The formal int
 - [libp2p-ipfs-nodejs](https://github.com/ipfs/js-libp2p-ipfs-nodejs)
 - [libp2p-ipfs-browser](https://github.com/ipfs/js-libp2p-ipfs-browser)
 
+#### Domain data types
+
+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.
+
+* [`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.multihash`](https://github.com/multiformats/js-multihash)
+* [`ipfs.types.CID`](https://github.com/ipld/js-cid)
+
 ## Packages
 
 | Package | Version | Deps | DevDeps |
@@ -287,8 +303,6 @@ Every IPFS instance also exposes the libp2p API at `ipfs.libp2p`. The formal int
 | [`multihashing`](//github.com/multiformats/js-multihashing) | [![npm](https://img.shields.io/npm/v/multihashing.svg?maxAge=86400&style=flat-square)](//github.com/multiformats/js-multihashing/releases) | [![Dep Status](https://david-dm.org/multiformats/js-multihashing.svg?style=flat-square)](https://david-dm.org/multiformats/js-multihashing) | [![devDep Status](https://david-dm.org/multiformats/js-multihashing/dev-status.svg?style=flat-square)](https://david-dm.org/multiformats/js-multihashing?type=dev) |
 | [`mafmt`](//github.com/whyrusleeping/js-mafmt) | [![npm](https://img.shields.io/npm/v/mafmt.svg?maxAge=86400&style=flat-square)](//github.com/whyrusleeping/js-mafmt/releases) | [![Dep Status](https://david-dm.org/whyrusleeping/js-mafmt.svg?style=flat-square)](https://david-dm.org/whyrusleeping/js-mafmt) | [![devDep Status](https://david-dm.org/whyrusleeping/js-mafmt/dev-status.svg?style=flat-square)](https://david-dm.org/whyrusleeping/js-mafmt?type=dev) |
 
-
-
 ## Development
 
 ### Clone and install dependencies

examples/README.md

@@ -9,6 +9,8 @@ Let us know if you find any issue or if you want to contribute and add a new tut
 - [js-ipfs basic, how to spawn a node and add a file to IPFS](./basics)
 - [How to bundle js-ipfs with Browserify](./bundle-browserify)
 - [How to bundle js-ipfs with WebPack](./bundle-webpack)
+- [How to use js-ipfs with a script tag](./browser-script-tag)
 - [Use IPFS to explore the Ethereum BlockChain](./explore-ethereum)
+- [How to use WebRTC star](./how-to-use-webrtc-star)
 
 ## Tutorials

examples/browser-script-tag/README.md

@@ -0,0 +1,11 @@
+# Use IPFS in the browser with `<script>` tags
+
+You can use IPFS in your in-browser JavaScript code with just a `<script>` tag.
+
+```
+<script src="https://unpkg.com/ipfs/dist/index.min.js"></script>
+```
+
+This exposes a global `Ipfs`; you can get a node by making a `new Ipfs()`.
+
+See `index.html` for a working example.

examples/browser-script-tag/index.html

@@ -0,0 +1,101 @@
+<!doctype html>
+<html>
+<head>
+  <title>IPFS in the Browser</title>
+  <script src="https://unpkg.com/ipfs/dist/index.min.js"></script>
+  <script type="text/javascript">
+    // We provide a hosted signalling endpoint that you can use to discover
+    // and dial to other nodes. It is hosted at `star-signal.cloud.ipfs.team`
+    // If you run your own signalling, you can change this multiaddr.
+    const SIGNALING_SERVER = '/libp2p-webrtc-star/dns4/star-signal.cloud.ipfs.team/wss/ipfs/'
+
+    const repoPath = 'ipfs-' + Math.random()
+
+    // Create an IPFS node
+    const node = new Ipfs({
+      repo: repoPath
+    })
+
+    // Init the node
+    node.init(handleInit)
+
+    function handleInit (err) {
+      if (!err) { // The repo was initialized for the first time, we need to configure it
+        addWebRTCMultiaddr()
+      } else if (err && err.message !== 'repo already exists') { // The repo already existed, let's just load it
+        loadRepo()
+      } else {
+        throw err
+      }
+    }
+
+    function addWebRTCMultiaddr() {
+      // Addj the WebrTCStar Multiaddr to your node
+      node.config.get(function (err, config) {
+        if (err) {
+          throw err
+        }
+
+        const starAddr = (SIGNALING_SERVER + config.Identity.PeerID)
+
+        node.config.set('Addresses.Swarm[1]', starAddr, loadRepo)
+      })
+    }
+
+    function loadRepo() {
+      node.load(() => node.goOnline(() => {
+        console.log('Online status: ', node.isOnline() ? 'online' : 'offline')
+
+        document.getElementById("status").innerHTML= 'Node status: ' + (node.isOnline() ? 'online' : 'offline')
+
+        // \o/ Now you have an IPFS node using WebRTC to find other nodes!
+        // You can write more code here to use it. Use methods like 
+        // node.files.add, node.files.get. See the API docs here:
+        // https://github.com/ipfs/interface-ipfs-core/tree/master/API
+      }))
+    }
+  </script>
+</head>
+<body>
+  <h1>IPFS in the Browser</h1>
+  <p>This page creates an IPFS node in your browser and drops it into the global Javascript namespace as <b><em style="background-color:#d7d6d6">node</em></b>. Open the console to play around with it.</p>
+  <p>Note that opening two tabs of this page in the same browser won't work well, because they will share node configuration. You'll end up trying to run two instances of the same node, with the same private key and identity, which is a Bad Idea.</p>
+  <div id="status">Node status: offline</div>
+
+  <h2>Some suggestions</h2>
+
+  <p>Try adding a new file:</p>
+
+  <code style="display:block; white-space:pre-wrap; background-color:#d7d6d6">
+    node.files.add(new node.types.Buffer('Hello world!'), function (err, res) {
+      if (err || !res) {
+        return console.error('Error - ipfs files add', err, res)
+      }
+
+      res.forEach(function (file) {
+        console.log('successfully stored', file)
+      })
+    })
+  </code>
+
+  <p>You can cat that same file. If you used the exact same string as above ('Hello world!') you should have an hash like this: 'QmQzCQn4puG4qu8PVysxZmscmQ5vT1ZXpqo7f58Uh9QfyY'</p>
+
+  <code style="display:block; white-space:pre-wrap; background-color:#d7d6d6">
+    node.files.cat('QmQzCQn4puG4qu8PVysxZmscmQ5vT1ZXpqo7f58Uh9QfyY', function (err, stream) {
+      var res = ''
+
+      stream.on('data', function (chunk) {
+        res += chunk.toString()
+      })
+
+      stream.on('error', function (err) {
+        console.error('Error - ipfs files cat ', err)
+      })
+
+      stream.on('end', function () {
+        console.log('Got:', res)
+      })
+    })
+  </code>
+</body>
+</html>

package.json

@@ -93,6 +93,7 @@
     "async": "^2.1.4",
     "bl": "^1.2.0",
     "boom": "^4.2.0",
+    "cids": "^0.4.1",
     "debug": "^2.6.1",
     "fs-pull-blob-store": "~0.4.1",
     "glob": "^7.1.1",
@@ -178,4 +179,4 @@
     "npmcdn-to-unpkg-bot <[email protected]>",
     "ᴠɪᴄᴛᴏʀ ʙᴊᴇʟᴋʜᴏʟᴍ <[email protected]>"
   ]
-}
+}

src/core/index.js

@@ -2,7 +2,12 @@
 
 const BlockService = require('ipfs-block-service')
 const IPLDResolver = require('ipld-resolver')
+const PeerId = require('peer-id')
+const PeerInfo = require('peer-info')
+const multiaddr = require('multiaddr')
+const multihash = require('multihashes')
 const PeerBook = require('peer-book')
+const CID = require('cids')
 const debug = require('debug')
 
 const defaultRepo = require('./default-repo')
@@ -24,7 +29,12 @@ class IPFS {
 
     // IPFS utils
     this.types = {
-      Buffer: Buffer
+      Buffer,
+      PeerId,
+      PeerInfo,
+      multiaddr,
+      multihash,
+      CID
     }
     this.log = debug('jsipfs')
     this.log.err = debug('jsipfs:err')

test/core/init.spec.js

@@ -4,6 +4,11 @@
 
 const expect = require('chai').expect
 const isNode = require('detect-node')
+const PeerId = require('peer-id')
+const PeerInfo = require('peer-info')
+const multiaddr = require('multiaddr')
+const multihash = require('multihashes')
+const CID = require('cids')
 const IPFS = require('../../src/core')
 
 // This gets replaced by require('../utils/create-repo-browser.js')
@@ -83,4 +88,15 @@ describe('init', () => {
       })
     })
   })
+
+  it('data types', () => {
+    expect(ipfs.types).to.be.deep.equal({
+      Buffer,
+      PeerId,
+      PeerInfo,
+      multiaddr,
+      multihash,
+      CID
+    })
+  })
 })