API proposal for ipfs.files.add

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

@@ -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.0.4"