Spec MFS Actions

SPEC/FILES.md

@@ -539,6 +539,252 @@ pull(
 
 A great source of [examples][] can be found in the tests for this API.
 
+#### `cp`
+
+> Mutable File System specific. Copy files.
+
+##### `Go` **WIP**
+
+##### `JavaScript` - ipfs.files.cp([from, to], [callback])
+
+Where:
+
+- `from` is the path of the source object to copy.
+- `to` is the path of the destination object to copy to.
+
+`callback` must follow the `function (err) {}` signature, where `err` is an Error if the operation was not successful.
+
+If no `callback` is passed, a promise is returned.
+
+**Example:**
+
+```JavaScript
+ipfs.files.cp(['/src-file', '/dst-file'], (err) => {
+  if (err) {
+    console.error(err)
+  }
+})
+```
+
+#### `mkdir`
+
+> Mutable File System specific. Make a directory.
+
+##### `Go` **WIP**
+
+##### `JavaScript` - ipfs.files.mkdir(path, [options, callback])
+
+Where:
+
+- `path` is the path to the directory to make.
+- `options` is an optional Object that might contain the following keys:
+  - `parents` is a Boolean value to decide whether or not to make the parent directories if they don't exist.
+
+`callback` must follow the `function (err) {}` signature, where `err` is an Error if the operation was not successful.
+
+If no `callback` is passed, a promise is returned.
+
+**Example:**
+
+```JavaScript
+ipfs.files.mkdir('/my/beautiful/directory', (err) => {
+  if (err) {
+    console.error(err)
+  }
+})
+```
+
+#### `stat`
+
+> Mutable File System specific. Get file or directory status.
+
+##### `Go` **WIP**
+
+##### `JavaScript` - ipfs.files.stat(path, [options, callback])
+
+Where:
+
+- `path` is the path to the directory to make.
+- `options` is an optional Object that might contain the following keys:
+  - `hash` is a Boolean value to return only the hash.
+  - `size` is a Boolean value to return only the size.
+
+`callback` must follow the `function (err, stat) {}` signature, where `err` is an Error if the operation was not successful and `stat` is an Object with the following keys:
+
+- `hash` is a string with the hash.
+- `size` is an integer with the size in Bytes.
+- `cumulativeSize` is an integer with the cumulative size in Bytes.
+- `blocks` is an integer indicating the number of blocks.
+- `type` is a string that can be either `directory` or `file`.
+
+If no `callback` is passed, a promise is returned.
+
+**Example:**
+
+```JavaScript
+ipfs.files.stat('/file.txt', (err, stats) => {
+  console.log(stats)
+})
+
+// {
+//   hash: 'QmXmJBmnYqXVuicUfn9uDCC8kxCEEzQpsAbeq1iJvLAmVs',
+//   size: 60,
+//   cumulativeSize: 118,
+//   blocks: 1,
+//   type: 'file'
+// }
+```
+
+#### `rm`
+
+> Remove a file or directory.
+
+##### `Go` **WIP**
+
+##### `JavaScript` - ipfs.files.rm(path, [options, callback])
+
+Where:
+
+- `path` is the path of the object to remove.
+- `options` is an optional Object that might contain the following keys:
+  - `recursive` is a Boolean value to decide whether or not to remove directories recursively.
+
+`callback` must follow the `function (err) {}` signature, where `err` is an Error if the operation was not successful.
+
+If no `callback` is passed, a promise is returned.
+
+**Example:**
+
+```JavaScript
+// To remove a file
+ipfs.files.mkdir('/my/beautiful/file.txt', (err) => {
+  if (err) {
+    console.error(err)
+  }
+})
+
+// To remove a directory
+ipfs.files.mkdir('/my/beautiful/directory', { recursive: true }, (err) => {
+  if (err) {
+    console.error(err)
+  }
+})
+```
+
+#### `read`
+
+> Mutable File System specific. Read a file.
+
+##### `Go` **WIP**
+
+##### `JavaScript` - ipfs.files.read(path, [options, callback])
+
+Where:
+
+- `path` is the path of the object to read.
+- `options` is an optional Object that might contain the following keys:
+  - `offset` is an Integer with the byte offset to begin reading from.
+  - `count` is an Integer with the maximum number of bytes to read.
+
+`callback` must follow the `function (err, buf) {}` signature, where `err` is an Error if the operation was not successful and `buf` is a Buffer with the contents of `path`.
+
+If no `callback` is passed, a promise is returned.
+
+**Example:**
+
+```JavaScript
+ipfs.files.read('/hello-world', (err, buf) => {
+  console.log(buf.toString())
+})
+
+// Hello, World!
+```
+
+#### `write`
+
+> Mutable File System specific. Write to a file.
+
+##### `Go` **WIP**
+
+##### `JavaScript` - ipfs.files.write(path, content, [options, callback])
+
+Where:
+
+- `path` is the path of the object to write.
+- `content` can be:
+  - a Buffer instance.
+  - a Path (caveat: will only work in Node.js).
+- `options` is an optional Object that might contain the following keys:
+  - `offset` is an Integer with the byte offset to begin writing at.
+  - `create` is a Boolean to indicate to create the file if it doesn't exist.
+  - `truncate` is a Boolean to indicate if the file should be truncated to size 0 before writing.
+  - `count` is an Integer with the maximum number of bytes to read.
+
+`callback` must follow the `function (err) {}` signature, where `err` is an Error if the operation was not successful.
+
+If no `callback` is passed, a promise is returned.
+
+**Example:**
+
+```JavaScript
+ipfs.files.write('/hello-world', Buffer.from('Hello, world!'), (err) => {
+  console.log(err)
+})
+```
+
+#### `mv`
+
+> Mutable File System specific. Move files.
+
+##### `Go` **WIP**
+
+##### `JavaScript` - ipfs.files.cp([from, to], [callback])
+
+Where:
+
+- `from` is the path of the source object to move.
+- `to` is the path of the destination object to move to.
+
+`callback` must follow the `function (err) {}` signature, where `err` is an Error if the operation was not successful.
+
+If no `callback` is passed, a promise is returned.
+
+**Example:**
+
+```JavaScript
+ipfs.files.mv(['/src-file', '/dst-file'], (err) => {
+  if (err) {
+    console.error(err)
+  }
+})
+```
+
+#### `flush`
+
+> Mutable File System specific. Flush a given path's data to the disk
+
+##### `Go` **WIP**
+
+##### `JavaScript` - ipfs.files.cp([path, callback])
+
+Where:
+
+- `path` is the path to flush. Default is `/`.
+
+`callback` must follow the `function (err) {}` signature, where `err` is an Error if the operation was not successful.
+
+If no `callback` is passed, a promise is returned.
+
+**Example:**
+
+```JavaScript
+ipfs.files.flush('/', (err) => {
+  if (err) {
+    console.error(err)
+  }
+})
+```
+
 [examples]: https://github.com/ipfs/interface-ipfs-core/blob/master/src/files.js
 [b]: https://www.npmjs.com/package/buffer
 [rs]: https://www.npmjs.com/package/readable-stream