Skip to content
This repository was archived by the owner on Mar 10, 2020. It is now read-only.

Commit 7431098

Browse files
hacdiasdaviddias
hacdias
authored and
daviddias
committedJan 25, 2018
feat: spec MFS Actions (#206)
1 parent 910c028 commit 7431098

File tree

3 files changed

+727
-2
lines changed

3 files changed

+727
-2
lines changed
 

‎SPEC/FILES.md

+293-1
Original file line numberDiff line numberDiff line change
@@ -387,6 +387,7 @@ pull(
387387

388388
A great source of [examples][] can be found in the tests for this API.
389389

390+
390391
#### `ls`
391392

392393
> Lists a directory from IPFS that is addressed by a valid IPFS Path.
@@ -427,7 +428,7 @@ If no `callback` is passed, a promise is returned.
427428
```JavaScript
428429
const validCID = 'QmQ2r6iMNpky5f1m4cnm3Yqw8VSvjuKpTcK1X7dBR1LkJF'
429430

430-
ipfs.files.ls(validCID, function (err, files) {
431+
ipfs.ls(validCID, function (err, files) {
431432
files.forEach((file) => {
432433
console.log(file.path)
433434
})
@@ -539,6 +540,297 @@ pull(
539540

540541
A great source of [examples][] can be found in the tests for this API.
541542

543+
--------------------------------------------------------------------------------------------------
544+
--------------------------------------------------------------------------------------------------
545+
546+
Mutable File System
547+
===================
548+
549+
The Mutable File System (MFS) is a virtual file system on top of IPFS that exposes a Unix like API over a virtual directory. It enables users to write and read from paths without having to worry about updating the graph. It enables things like [ipfs-blob-store](https://github.com/ipfs/ipfs-blob-store) to exist.
550+
551+
552+
#### `cp`
553+
554+
> Copy files.
555+
556+
##### `Go` **WIP**
557+
558+
##### `JavaScript` - ipfs.files.cp([from, to], [callback])
559+
560+
Where:
561+
562+
- `from` is the path of the source object to copy.
563+
- `to` is the path of the destination object to copy to.
564+
565+
`callback` must follow the `function (err) {}` signature, where `err` is an Error if the operation was not successful.
566+
567+
If no `callback` is passed, a promise is returned.
568+
569+
**Example:**
570+
571+
```JavaScript
572+
ipfs.files.cp(['/src-file', '/dst-file'], (err) => {
573+
if (err) {
574+
console.error(err)
575+
}
576+
})
577+
```
578+
579+
#### `mkdir`
580+
581+
> Make a directory.
582+
583+
##### `Go` **WIP**
584+
585+
##### `JavaScript` - ipfs.files.mkdir(path, [options, callback])
586+
587+
Where:
588+
589+
- `path` is the path to the directory to make.
590+
- `options` is an optional Object that might contain the following keys:
591+
- `parents` is a Boolean value to decide whether or not to make the parent directories if they don't exist.
592+
593+
`callback` must follow the `function (err) {}` signature, where `err` is an Error if the operation was not successful.
594+
595+
If no `callback` is passed, a promise is returned.
596+
597+
**Example:**
598+
599+
```JavaScript
600+
ipfs.files.mkdir('/my/beautiful/directory', (err) => {
601+
if (err) {
602+
console.error(err)
603+
}
604+
})
605+
```
606+
607+
#### `stat`
608+
609+
> Get file or directory status.
610+
611+
##### `Go` **WIP**
612+
613+
##### `JavaScript` - ipfs.files.stat(path, [options, callback])
614+
615+
Where:
616+
617+
- `path` is the path to the directory to make.
618+
- `options` is an optional Object that might contain the following keys:
619+
- `hash` is a Boolean value to return only the hash.
620+
- `size` is a Boolean value to return only the size.
621+
622+
`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:
623+
624+
- `hash` is a string with the hash.
625+
- `size` is an integer with the size in Bytes.
626+
- `cumulativeSize` is an integer with the cumulative size in Bytes.
627+
- `blocks` is an integer indicating the number of blocks.
628+
- `type` is a string that can be either `directory` or `file`.
629+
630+
If no `callback` is passed, a promise is returned.
631+
632+
**Example:**
633+
634+
```JavaScript
635+
ipfs.files.stat('/file.txt', (err, stats) => {
636+
console.log(stats)
637+
})
638+
639+
// {
640+
// hash: 'QmXmJBmnYqXVuicUfn9uDCC8kxCEEzQpsAbeq1iJvLAmVs',
641+
// size: 60,
642+
// cumulativeSize: 118,
643+
// blocks: 1,
644+
// type: 'file'
645+
// }
646+
```
647+
648+
#### `rm`
649+
650+
> Remove a file or directory.
651+
652+
##### `Go` **WIP**
653+
654+
##### `JavaScript` - ipfs.files.rm(path, [options, callback])
655+
656+
Where:
657+
658+
- `path` is the path of the object to remove.
659+
- `options` is an optional Object that might contain the following keys:
660+
- `recursive` is a Boolean value to decide whether or not to remove directories recursively.
661+
662+
`callback` must follow the `function (err) {}` signature, where `err` is an Error if the operation was not successful.
663+
664+
If no `callback` is passed, a promise is returned.
665+
666+
**Example:**
667+
668+
```JavaScript
669+
// To remove a file
670+
ipfs.files.mkdir('/my/beautiful/file.txt', (err) => {
671+
if (err) {
672+
console.error(err)
673+
}
674+
})
675+
676+
// To remove a directory
677+
ipfs.files.mkdir('/my/beautiful/directory', { recursive: true }, (err) => {
678+
if (err) {
679+
console.error(err)
680+
}
681+
})
682+
```
683+
684+
#### `read`
685+
686+
> Read a file.
687+
688+
##### `Go` **WIP**
689+
690+
##### `JavaScript` - ipfs.files.read(path, [options, callback])
691+
692+
Where:
693+
694+
- `path` is the path of the object to read.
695+
- `options` is an optional Object that might contain the following keys:
696+
- `offset` is an Integer with the byte offset to begin reading from.
697+
- `count` is an Integer with the maximum number of bytes to read.
698+
699+
`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`.
700+
701+
If no `callback` is passed, a promise is returned.
702+
703+
**Example:**
704+
705+
```JavaScript
706+
ipfs.files.read('/hello-world', (err, buf) => {
707+
console.log(buf.toString())
708+
})
709+
710+
// Hello, World!
711+
```
712+
713+
#### `write`
714+
715+
> Write to a file.
716+
717+
##### `Go` **WIP**
718+
719+
##### `JavaScript` - ipfs.files.write(path, content, [options, callback])
720+
721+
Where:
722+
723+
- `path` is the path of the object to write.
724+
- `content` can be:
725+
- a Buffer instance.
726+
- a Path (caveat: will only work in Node.js).
727+
- `options` is an optional Object that might contain the following keys:
728+
- `offset` is an Integer with the byte offset to begin writing at.
729+
- `create` is a Boolean to indicate to create the file if it doesn't exist.
730+
- `truncate` is a Boolean to indicate if the file should be truncated to size 0 before writing.
731+
- `count` is an Integer with the maximum number of bytes to read.
732+
733+
`callback` must follow the `function (err) {}` signature, where `err` is an Error if the operation was not successful.
734+
735+
If no `callback` is passed, a promise is returned.
736+
737+
**Example:**
738+
739+
```JavaScript
740+
ipfs.files.write('/hello-world', Buffer.from('Hello, world!'), (err) => {
741+
console.log(err)
742+
})
743+
```
744+
745+
#### `mv`
746+
747+
> Move files.
748+
749+
##### `Go` **WIP**
750+
751+
##### `JavaScript` - ipfs.files.mv([from, to], [callback])
752+
753+
Where:
754+
755+
- `from` is the path of the source object to move.
756+
- `to` is the path of the destination object to move to.
757+
758+
`callback` must follow the `function (err) {}` signature, where `err` is an Error if the operation was not successful.
759+
760+
If no `callback` is passed, a promise is returned.
761+
762+
**Example:**
763+
764+
```JavaScript
765+
ipfs.files.mv(['/src-file', '/dst-file'], (err) => {
766+
if (err) {
767+
console.error(err)
768+
}
769+
})
770+
```
771+
772+
#### `flush`
773+
774+
> Flush a given path's data to the disk
775+
776+
##### `Go` **WIP**
777+
778+
##### `JavaScript` - ipfs.files.flush([path, callback])
779+
780+
Where:
781+
782+
- `path` is the path to flush. Default is `/`.
783+
784+
`callback` must follow the `function (err) {}` signature, where `err` is an Error if the operation was not successful.
785+
786+
If no `callback` is passed, a promise is returned.
787+
788+
**Example:**
789+
790+
```JavaScript
791+
ipfs.files.flush('/', (err) => {
792+
if (err) {
793+
console.error(err)
794+
}
795+
})
796+
```
797+
798+
#### `ls`
799+
800+
> List directories in the local mutable namespace.
801+
802+
##### `Go` **WIP**
803+
804+
##### `JavaScript` - ipfs.files.ls([path, options, callback])
805+
806+
Where:
807+
808+
- `path` is the path to show listing for. Defaults to `/`.
809+
- `options` is an optional Object that might contain the following keys:
810+
- `l` is a Boolean value o use long listing format.
811+
812+
`callback` must follow `function (err, files) {}` signature, where `err` is an error if the operation was not successful. `files` is an array containing Objects that contain the following keys:
813+
814+
- `name` which is the file's name.
815+
- `type` which i the object's type (`directory` or `file`).
816+
- `size` the size of the file in bytes.
817+
- `hash` the hash of the file.
818+
819+
If no `callback` is passed, a promise is returned.
820+
821+
**Example:**
822+
823+
```JavaScript
824+
ipfs.files.ls('/screenshots', function (err, files) {
825+
files.forEach((file) => {
826+
console.log(file.name)
827+
})
828+
})
829+
830+
// 2018-01-22T18:08:46.775Z.png
831+
// 2018-01-22T18:08:49.184Z.png
832+
```
833+
542834
[examples]: https://github.com/ipfs/interface-ipfs-core/blob/master/src/files.js
543835
[b]: https://www.npmjs.com/package/buffer
544836
[rs]: https://www.npmjs.com/package/readable-stream

‎src/files.js

+7-1
Original file line numberDiff line numberDiff line change
@@ -18,8 +18,9 @@ const through = require('through2')
1818
const path = require('path')
1919
const bl = require('bl')
2020
const isNode = require('detect-node')
21+
const mfs = require('./mfs')
2122

22-
module.exports = (common) => {
23+
const tests = (common) => {
2324
describe('.files', function () {
2425
this.timeout(40 * 1000)
2526

@@ -982,3 +983,8 @@ module.exports = (common) => {
982983
})
983984
})
984985
}
986+
987+
module.exports = (common) => {
988+
tests(common)
989+
mfs(common)
990+
}

0 commit comments

Comments
 (0)