Merge pull request #26 from ipfs/add

Interface for files.add

Author: daviddias

README.md

@@ -25,7 +25,7 @@ interface-ipfs-core API.
 
 ![](/img/badge.png)
 
-# How to use the battery tests
+# How to use the battery of tests
 
 ## Node.js
 
@@ -55,6 +55,97 @@ test.all(common)
 
 A valid (read: that follows this interface) IPFS core implementation, must expose the following API.
 
+## Files
+
+### `add`
+
+> Add files and data to IPFS.
+
+##### `Go` **WIP**
+
+##### `JavaScript` - ipfs.files.add(data, [callback])
+
+Where `data` may be
+
+- an array of objects, each of the form
+```js
+{
+  path: '/tmp/myfile.txt',
+  content: (Buffer or Readable stream)
+}
+```
+- a `Buffer` instance
+- a `Readable` stream
+
+`callback` must follow `function (err, res) {}` signature, where `err` is an
+error if the operation was not successful. `res` will be an array of
+
+```js
+{
+  path: '/tmp/myfile.txt',
+  node: DAGNode
+}
+```
+
+If no `callback` is passed, a promise is returned.
+
+Example:
+```js
+var files = [
+  {
+    path: '/tmp/myfile.txt',
+    content: (Buffer or Readable stream)
+  }
+]
+ipfs.files.add(files, function (err, files) {
+  // 'files' will be an array of objects
+})
+```
+
+
+### `createAddStream`
+
+> Add files and data to IPFS using a transform stream.
+
+##### `Go` **WIP**
+
+##### `JavaScript` - ipfs.files.createAddStream([callback])
+
+Provides a Transform stream, where objects can be written of the forms
+
+```js
+{
+  path: '/tmp/myfile.txt',
+  content: (Buffer or Readable stream)
+}
+```
+
+`callback` must follow `function (err, stream) {}` signature, where `err` is an
+error if the operation was not successful. `stream` will be a Transform stream,
+to which tuples like the above two object formats can be written and [DAGNode][]
+objects will be outputted.
+
+If no `callback` is passed, a promise is returned.
+
+```js
+ipfs.files.createAddStream(function (err, stream) {
+  stream.on('data', function (file) {
+    // 'file' will be of the form
+    // {
+    //   path: '/tmp/myfile.txt',
+    //   node: DAGNode
+    // }
+  })
+
+  stream.write({path: <path to file>, content: <buffer or readable stream>})
+  // write as many as you want
+
+  stream.end()
+})
+```
+
+
+
 ## Object
 
 ### `object.new`

package.json

@@ -2,8 +2,8 @@
   "name": "interface-ipfs-core",
   "version": "0.1.5",
   "description": "A test suite and interface you can use to implement a IPFS core interface.",
-  "main": "test/index.js",
-  "jsnext:main": "test/index.js",
+  "main": "lib/index.js",
+  "jsnext:main": "src/index.js",
   "scripts": {
     "test": "exit(0)",
     "build": "aegir-build node",
@@ -28,9 +28,12 @@
   },
   "homepage": "https://github.com/ipfs/interface-ipfs-core#readme",
   "dependencies": {
+    "bl": "^1.1.2",
     "bs58": "^3.0.0",
     "chai": "^3.5.0",
-    "ipfs-merkle-dag": "^0.6.0"
+    "detect-node": "^2.0.3",
+    "ipfs-merkle-dag": "^0.6.0",
+    "readable-stream": "1.1.13"
   },
   "devDependencies": {
     "aegir": "^3.2.0"
@@ -39,4 +42,4 @@
     "David Dias <[email protected]>",
     "Friedel Ziegelmayer <[email protected]>"
   ]
-}
+}