README and API improvements.

Author: hackergrrl

README.md

@@ -1,12 +1,90 @@
 IPFS Data Importing
 ===================
 
+> Import data into an IPFS DAG Service.
+
 [![](https://img.shields.io/badge/made%20by-Protocol%20Labs-blue.svg?style=flat-square)](http://ipn.io)
 [![](https://img.shields.io/badge/freenode-%23ipfs-blue.svg?style=flat-square)](http://webchat.freenode.net/?channels=%23ipfs)
 [![Build Status](https://travis-ci.org/ipfs/js-ipfs-data-importing.svg?style=flat-square)](https://travis-ci.org/ipfs/js-ipfs-data-importing)
 ![](https://img.shields.io/badge/coverage-%3F-yellow.svg?style=flat-square)
 [![Dependency Status](https://david-dm.org/ipfs/js-ipfs-data-importing.svg?style=flat-square)](https://david-dm.org/ipfs/js-ipfs-data-importing)
 [![js-standard-style](https://img.shields.io/badge/code%20style-standard-brightgreen.svg?style=flat-square)](https://github.com/feross/standard)
 
-> JavaScript implementation of the layout and chunking mechanisms used by IPFS
+## Example
+
+Let's create a little directory to import:
+```sh
+$ cd /tmp
+$ mkdir foo
+$ echo 'hello' > foo/bar
+$ echo 'warld' > foo/quux
+```
+
+And write the importing logic:
+```js
+// Dependencies to create a DAG Service (where the dir will be imported into)
+var memStore = require('abstract-blob-store')
+var ipfsRepo = require('ipfs-repo')
+var ipfsBlocks = require('ipfs-blocks')
+var ipfsMerkleDag = require('ipfs-merkle-dag')
+
+var repo = new ipfsRepo('', { stores: memStore })
+var blocks = new ipfsBlocks.BlockService(repo)
+var dag = new ipfsMerkleDag.DAGService(blocks)
+
+
+var ipfsData = require('ipfs-data-importing')
+
+// Import /tmp/foo
+ipfsData.import('/tmp/foo', dag, {
+  recursive: true
+}, done)
+
+// A root DAG Node is received upon completion
+function done (err, rootStat) {
+  if (err) { throw err }
+  console.log(rootStat)
+}
+```
+
+When run, the stat of root DAG Node is outputted:
+
+```
+{ Hash: <Buffer 12 20 bd e2 2b 57 3f 6f bd 7c cc 5a 11 7f 28 6c a2 9a 9f c0 90 e1 d4 16 d0 5f 42 81 ec 0c 2a 7f 7f 93>,
+  Size: 59843,
+  Name: 'foo' }
+```
+
+## API
+
+```js
+var importer = require('ipfs-data-importing')
+```
+
+### importer.import(target, dagService, opts, cb)
+
+`target` can be a `string`, `Buffer`, or `Stream`. When it's a string, the file
+or directory structure rooted on the filesystem at `target` is imported, with
+the hierarchy preserved. If a Buffer or Stream, a single DAG node will be
+imported representing the buffer or stream's contents.
+
+Uses the [DAG Service](https://github.com/vijayee/js-ipfs-merkle-dag/) instance
+`dagService`. Accepts the following `opts`:
+
+- `recursive`: whether to recurse into directories. Defaults to `false`.
+
+Calls the callback `cb(err, stat)` on completion or error, where `stat` is an
+object with the `Hash`, `Size`, and `Name` of the root
+[`DAGNode`](https://github.com/vijayee/js-ipfs-merkle-dag/).
+
+## install
+
+With [npm](https://npmjs.org/) installed, run
+
+```
+$ npm install ipfs-data-importing
+```
+
+## license
 
+ISC

src/index.js

@@ -12,15 +12,20 @@ exports = module.exports
 const CHUNK_SIZE = 262144
 
 // Use a layout + chunkers to convert a directory (or file) to the layout format
-exports.import = function (options, callback) {
-  // options.path : what to import
-  // options.buffer : import a buffer
-  // options.filename : optional file name for buffer
-  // options.stream : import a stream
+exports.import = (dagService, options, callback) => {
+  if (typeof options === 'function') { callback = options; options = {} }
+  if (!dagService) { return callback(new Error('no dag service provided')) }
+
   // options.recursive : follow dirs
   // options.chunkers : obj with chunkers to each type of data, { default: dumb-chunker }
-  // options.dag-service : instance of block service
-  const dagService = options.dagService
+  // options.path : import a file hierarchy from a path
+  // options.stream : import a stream
+  // options.buffer : import a buffer
+
+  // TODO: make first param be 'target' and check type to decide how to import
+  // path
+  // stream
+  // buffer
 
   if (options.buffer) {
     if (!Buffer.isBuffer(options.buffer)) {
@@ -219,13 +224,10 @@ exports.import = function (options, callback) {
           if (err) {
             return log.err(err)
           }
-          // an optional file name provided
-          const fileName = options.filename
 
           callback(null, {
             Hash: parentNode.multihash(),
-            Size: parentNode.size(),
-            Name: fileName
+            Size: parentNode.size()
           }) && cb()
         })
       }))
@@ -241,8 +243,7 @@ exports.import = function (options, callback) {
 
         callback(null, {
           Hash: fileNode.multihash(),
-          Size: fileNode.size(),
-          Name: options.filename
+          Size: fileNode.size()
         })
       })
     }

tests/test-import.js

@@ -54,10 +54,7 @@ describe('layout: importer', function () {
   })
 
   it('import a small file', (done) => {
-    importer.import({
-      path: small,
-      dagService: ds
-    }, function (err, stat) {
+    importer.import(small, ds, function (err, stat) {
       expect(err).to.not.exist
       ds.get(stat.Hash, (err, node) => {
         expect(err).to.not.exist
@@ -72,10 +69,7 @@ describe('layout: importer', function () {
   })
 
   it('import a big file', (done) => {
-    importer.import({
-      path: big,
-      dagService: ds
-    }, function (err, stat) {
+    importer.import(big, ds, function (err, stat) {
       expect(err).to.not.exist
       ds.get(stat.Hash, (err, node) => {
         expect(err).to.not.exist
@@ -120,9 +114,7 @@ describe('layout: importer', function () {
   })
 
   it('import a small directory', (done) => {
-    importer.import({
-      path: dirSmall,
-      dagService: ds,
+    importer.import(dirSmall, ds, {
       recursive: true
     }, function (err, stats) {
       expect(err).to.not.exist
@@ -149,9 +141,7 @@ describe('layout: importer', function () {
   })
 
   it('import a big directory', (done) => {
-    importer.import({
-      path: dirBig,
-      dagService: ds,
+    importer.import(dirBig, ds, {
       recursive: true
     }, function (err, stats) {
       expect(err).to.not.exist
@@ -178,9 +168,7 @@ describe('layout: importer', function () {
   })
 
   it('import a nested directory', (done) => {
-    importer.import({
-      path: dirNested,
-      dagService: ds,
+    importer.import(dirNested, ds, {
       recursive: true
     }, function (err, stats) {
       expect(err).to.not.exist
@@ -225,8 +213,7 @@ describe('layout: importer', function () {
     var buf = fs.readFileSync(path.join(__dirname, '/test-data/1.2MiB.txt'))
     importer.import({
       buffer: buf,
-      dagService: ds,
-      filename: 'Test.txt'
+      dagService: ds
     }, function (err, stat) {
       expect(err).to.not.exist
       ds.get(stat.Hash, (err, node) => {