Merge pull request #27 from ipfs/awesome-ipld

awesome IPLD endeavour

Author: daviddias

API.md

@@ -72,14 +72,17 @@ var repo = new IPFSRepo('example', { stores: Store })
 // create a block
 const block = new Block('hello world')
 console.log(block.data)
-console.log(block.key)
+console.log(block.key())
 
 // create a service
 const bs = new BlockService(repo)
 
 // add the block, then retrieve it
-bs.put(block, function (err) {
-  bs.get(block.key, function (err, b) {
+bs.put({
+  block: block,
+  cid: cid,
+}, function (err) {
+  bs.get(cid, function (err, b) {
     console.log(block.data.toString() === b.data.toString())
   })
 })
@@ -118,10 +121,70 @@ the global namespace.
 <script src="https://unpkg.com/ipfs-block-service/dist/index.js"></script>
 ```
 
-You can find the [API documentation here](API.md)
+# API
 
-[ipfs]: https://ipfs.io
-[bitswap]: https://github.com/ipfs/specs/tree/master/bitswap
+```js
+const BlockService = require('ipfs-block-service')
+```
+
+### `new BlockService(repo)`
+
+- `repo: Repo`
+
+Creates a new block service backed by [IPFS Repo][repo] `repo` for storage.
+
+### `goOnline(bitswap)`
+
+- `bitswap: Bitswap`
+
+Add a bitswap instance that communicates with the network to retreive blocks
+that are not in the local store.
+
+If the node is online all requests for blocks first check locally and
+afterwards ask the network for the blocks.
+
+### `goOffline()`
+
+Remove the bitswap instance and fall back to offline mode.
+
+### `isOnline()`
+
+Returns a `Boolean` indicating if the block service is online or not.
+
+### `put(blockAndCID, callback)`
+
+- `blockAndCID: { block: block, cid: cid }`
+- `callback: Function`
+
+Asynchronously adds a block instance to the underlying repo.
+
+### `putStream()`
+
+Returns a through pull-stream, which `blockAndCID`s can be written to, and
+that emits the meta data about the written block.
+
+### `get(cid [, extension], callback)`
+
+- `cid: CID`
+- `extension: String`, defaults to 'data'
+- `callback: Function`
+
+Asynchronously returns the block whose content multihash matches `multihash`.
+
+### `getStream(cid [, extension])`
+
+- `cid: CID`
+- `extension: String`, defaults to 'data'
+
+Returns a source pull-stream, which emits the requested block.
+
+### `delete(cids, [, extension], callback)`
+
+- `cids: CID | []CID`
+- `extension: String`, defaults to 'data' - `extension: String`, defaults to 'data'
+- `callback: Function`
+
+Deletes all blocks referenced by multihashes.
 
 ## Contribute
 
@@ -134,3 +197,9 @@ This repository falls under the IPFS [Code of Conduct](https://github.com/ipfs/c
 ## License
 
 [MIT](LICENSE)
+
+[ipfs]: https://ipfs.io
+[bitswap]: https://github.com/ipfs/specs/tree/master/bitswap
+[repo]: https://github.com/ipfs/specs/tree/master/repo
+
+

README.md

@@ -37,20 +37,21 @@
   },
   "homepage": "https://github.com/ipfs/js-ipfs-block-service#readme",
   "devDependencies": {
-    "aegir": "^8.0.0",
+    "aegir": "^8.1.2",
     "buffer-loader": "0.0.1",
     "chai": "^3.5.0",
     "fs-pull-blob-store": "^0.3.0",
     "idb-pull-blob-store": "^0.5.1",
-    "ipfs-block": "^0.3.0",
-    "ipfs-repo": "^0.9.0",
+    "ipfs-block": "^0.4.0",
+    "ipfs-repo": "^0.10.0",
     "lodash": "^4.15.0",
     "ncp": "^2.0.0",
     "pre-commit": "^1.1.3",
     "rimraf": "^2.5.4",
     "run-series": "^1.1.4"
   },
   "dependencies": {
+    "cids": "^0.2.0",
     "pull-stream": "^3.4.5",
     "run-parallel-limit": "^1.0.3"
   },
@@ -60,4 +61,4 @@
     "Richard Littauer <richard.littauer@gmail.com>",
     "Stephen Whitmore <stephen.whitmore@gmail.com>"
   ]
-}
+}

package.json

@@ -24,62 +24,73 @@ module.exports = class BlockService {
     return this._bitswap != null
   }
 
-  put (block, callback) {
+  // Note: we have to pass the CID, so that bitswap can then use it for
+  // the smart selectors. For now, passing the CID is used so that we know
+  // the right multihash, this means that now we have multiple hashes official
+  // support \o/
+  put (blockAndCID, callback) {
     callback = callback || (() => {})
-    if (!block) {
-      return callback(new Error('Missing block'))
+    if (!blockAndCID) {
+      return callback(new Error('Missing block and CID'))
     }
 
     pull(
-      pull.values([block]),
+      pull.values([
+        blockAndCID
+      ]),
       this.putStream(),
       pull.onEnd(callback)
     )
   }
 
   putStream () {
+    let ps
     if (this.isOnline()) {
-      return this._bitswap.putStream()
+      // NOTE: This will have to change in order for bitswap
+      // to understand CID
+      ps = this._bitswap.putStream()
+    } else {
+      ps = this._repo.blockstore.putStream()
     }
 
-    return this._repo.blockstore.putStream()
+    return pull(
+      pull.map((blockAndCID) => {
+        return {
+          data: blockAndCID.block.data,
+          key: blockAndCID.cid.multihash
+        }
+      }),
+      ps
+    )
   }
 
-  get (key, extension, callback) {
-    if (typeof extension === 'function') {
-      callback = extension
-      extension = undefined
-    }
-
+  get (cid, callback) {
     pull(
-      this.getStream(key, extension),
+      this.getStream(cid),
       pull.collect((err, result) => {
-        if (err) return callback(err)
+        if (err) {
+          return callback(err)
+        }
         callback(null, result[0])
       })
     )
   }
 
-  getStream (key, extension) {
+  getStream (cid) {
     if (this.isOnline()) {
-      return this._bitswap.getStream(key)
+      return this._bitswap.getStream(cid.multihash)
     }
 
-    return this._repo.blockstore.getStream(key, extension)
+    return this._repo.blockstore.getStream(cid.multihash)
   }
 
-  delete (keys, extension, callback) {
-    if (typeof extension === 'function') {
-      callback = extension
-      extension = undefined
-    }
-
-    if (!Array.isArray(keys)) {
-      keys = [keys]
+  delete (cids, callback) {
+    if (!Array.isArray(cids)) {
+      cids = [cids]
     }
 
-    parallelLimit(keys.map((key) => (next) => {
-      this._repo.blockstore.delete(key, extension, next)
+    parallelLimit(cids.map((cid) => (next) => {
+      this._repo.blockstore.delete(cid.multihash, next)
     }), 100, callback)
   }
 }