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

Commit 889e63f

Browse files
achingbrainachingbrain
committed
docs: remove array arguments and document missing options
closes #262
1 parent 352c2dd commit 889e63f

File tree

1 file changed

+114
-73
lines changed

1 file changed

+114
-73
lines changed

‎SPEC/FILES.md

Lines changed: 114 additions & 73 deletions
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@
1616
* [lsPullStream](#lspullstream)
1717
* [files.cp](#filescp)
1818
* [files.mkdir](#filesmkdir)
19-
* [files.stat](#filesmkdir)
19+
* [files.stat](#filesstat)
2020
* [files.rm](#filesrm)
2121
* [files.read](#filesread)
2222
* [files.readReadableStream](#filesreadreadablestream)
@@ -590,28 +590,49 @@ A great source of [examples][] can be found in the tests for this API.
590590

591591
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.
592592

593-
594593
#### `files.cp`
595594

596595
> Copy files.
597596
598597
##### `Go` **WIP**
599598

600-
##### `JavaScript` - ipfs.files.cp([from, to], [callback])
599+
##### `JavaScript` - ipfs.files.cp(...from, to, [options], [callback])
601600

602601
Where:
603602

604-
- `from` is the path of the source file to copy.
605-
- `to` is the path of the destination file to copy to.
603+
- `from` is the path(s) of the source to copy. It might be:
604+
- An existing MFS path (e.g. `/my-dir/my-file.txt`)
605+
- An IPFS path (e.g. `/ipfs/QmWGeRAEgtsHW3ec7U4qW2CyVy7eA2mFRVbk1nb24jFyks`)
606+
- `to` is the path of the destination to copy to
607+
- `options` is an optional Object that might contain the following keys:
608+
- `parents` is a Boolean value to decide whether or not to make the parent directories if they don't exist (default: false)
609+
- `format` is what type of nodes to write any newly created directories as (default: `dag-pb`)
610+
- `hashAlg` is which algorithm to use when creating CIDs for newly created directories (default: `sha2-256`)
611+
- `flush` is a Boolean value to decide whether or not to immediately flush MFS changes to disk (default: true)
612+
- `callback` is an optional function with the signature `function (error) {}`, where `error` may be an Error that occured if the operation was not successful
613+
614+
If there are multiple sources, `to` will be treated as a directory, otherwise it will be treated as the same type as `from`.
606615

607-
`callback` must follow the `function (err) {}` signature, where `err` is an Error if the operation was not successful.
616+
If `from` is an IPFS path, and an MFS path exists with the same name, the IPFS path will be chosen.
608617

609618
If no `callback` is passed, a promise is returned.
610619

611620
**Example:**
612621

613622
```JavaScript
614-
ipfs.files.cp(['/src-file', '/dst-file'], (err) => {
623+
ipfs.files.cp('/src-file', '/dst-file', (err) => {s
624+
if (err) {
625+
console.error(err)
626+
}
627+
})
628+
629+
ipfs.files.cp('/src-dir', '/dst-dir', (err) => {s
630+
if (err) {
631+
console.error(err)
632+
}
633+
})
634+
635+
ipfs.files.cp('/src-file1', '/src-file2', '/dst-dir', (err) => {
615636
if (err) {
616637
console.error(err)
617638
}
@@ -624,15 +645,17 @@ ipfs.files.cp(['/src-file', '/dst-file'], (err) => {
624645
625646
##### `Go` **WIP**
626647

627-
##### `JavaScript` - ipfs.files.mkdir(path, [options, callback])
648+
##### `JavaScript` - ipfs.files.mkdir(path, [options], [callback])
628649

629650
Where:
630651

631-
- `path` is the path to the directory to make.
652+
- `path` is the path to the directory to make
632653
- `options` is an optional Object that might contain the following keys:
633-
- `parents` is a Boolean value to decide whether or not to make the parent directories if they don't exist.
634-
635-
`callback` must follow the `function (err) {}` signature, where `err` is an Error if the operation was not successful.
654+
- `parents` is a Boolean value to decide whether or not to make the parent directories if they don't exist (default: false)
655+
- `format` is what type of nodes to write any newly created directories as (default: `dag-pb`)
656+
- `hashAlg` is which algorithm to use when creating CIDs for newly created directories (default: `sha2-256`)
657+
- `flush` is a Boolean value to decide whether or not to immediately flush MFS changes to disk (default: true)
658+
- `callback` is an optional function with the signature `function (error) {}`, where `error` may be an Error that occured if the operation was not successful
636659

637660
If no `callback` is passed, a promise is returned.
638661

@@ -652,27 +675,25 @@ ipfs.files.mkdir('/my/beautiful/directory', (err) => {
652675
653676
##### `Go` **WIP**
654677

655-
##### `JavaScript` - ipfs.files.stat(path, [options, callback])
678+
##### `JavaScript` - ipfs.files.stat(path, [options], [callback])
656679

657680
Where:
658681

659-
- `path` is the path to the directory to stat.
682+
- `path` is the path to the file or directory to stat
660683
- `options` is an optional Object that might contain the following keys:
661-
- `hash` is a Boolean value to return only the hash.
662-
- `size` is a Boolean value to return only the size.
663-
- `withLocal` is a Boolean value to compute the amount of the dag that is local, and if possible the total size.
664-
665-
`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:
666-
667-
- `hash` is a string with the hash.
668-
- `size` is an integer with the size in Bytes.
669-
- `cumulativeSize` is an integer with the cumulative size in Bytes.
670-
- `blocks` is an integer indicating the number of blocks.
671-
- `type` is a string that can be either `directory` or `file`.
672-
- `withLocality` is a boolean to indicate if locality information are present.
673-
- `local` is a boolean to indicate if the queried dag is fully present locally.
674-
- `sizeLocal` is an integer indicating the cumulative size of the data present locally.
675-
684+
- `hash` is a Boolean value to return only the hash (default: false)
685+
- `size` is a Boolean value to return only the size (default: false)
686+
- `withLocal` is a Boolean value to compute the amount of the dag that is local, and if possible the total size (default: false)
687+
- `callback` is an optional function with the signature `function (error, stats) {}`, where `error` may be an Error that occured if the operation was not successful and `stat` is an Object with the following keys:
688+
689+
- `hash` is a string with the hash
690+
- `size` is an integer with the file size in Bytes
691+
- `cumulativeSize` is an integer with the size of the DAGNodes making up the file in Bytes
692+
- `type` is a string that can be either `directory` or `file`
693+
- `blocks` if `type` is `directory`, this is the number of files in the directory. If it is `file` it is the number of blocks that make up the file
694+
- `withLocality` is a boolean to indicate if locality information are present
695+
- `local` is a boolean to indicate if the queried dag is fully present locally
696+
- `sizeLocal` is an integer indicating the cumulative size of the data present locally
676697

677698
If no `callback` is passed, a promise is returned.
678699

@@ -698,15 +719,14 @@ ipfs.files.stat('/file.txt', (err, stats) => {
698719
699720
##### `Go` **WIP**
700721

701-
##### `JavaScript` - ipfs.files.rm(path, [options, callback])
722+
##### `JavaScript` - ipfs.files.rm(...paths, [options], [callback])
702723

703724
Where:
704725

705-
- `path` is the path of the file to remove.
726+
- `paths` are one or more paths to remove
706727
- `options` is an optional Object that might contain the following keys:
707-
- `recursive` is a Boolean value to decide whether or not to remove directories recursively.
708-
709-
`callback` must follow the `function (err) {}` signature, where `err` is an Error if the operation was not successful.
728+
- `recursive` is a Boolean value to decide whether or not to remove directories recursively (default: false)
729+
- `callback` is an optional function with the signature `function (error) {}`, where `error` may be an Error that occured if the operation was not successful
710730

711731
If no `callback` is passed, a promise is returned.
712732

@@ -720,6 +740,13 @@ ipfs.files.rm('/my/beautiful/file.txt', (err) => {
720740
}
721741
})
722742

743+
// To remove multiple files
744+
ipfs.files.rm('/my/beautiful/file.txt', '/my/other/file.txt', (err) => {
745+
if (err) {
746+
console.error(err)
747+
}
748+
})
749+
723750
// To remove a directory
724751
ipfs.files.rm('/my/beautiful/directory', { recursive: true }, (err) => {
725752
if (err) {
@@ -738,19 +765,20 @@ ipfs.files.rm('/my/beautiful/directory', { recursive: true }, (err) => {
738765

739766
Where:
740767

741-
- `path` is the path of the file to read.
768+
- `path` is the path of the file to read and must point to a file
742769
- `options` is an optional Object that might contain the following keys:
743-
- `offset` is an Integer with the byte offset to begin reading from.
744-
- `count` is an Integer with the maximum number of bytes to read.
745-
746-
`callback` must follow the `function (err, buf) {}` signature, where `err` is an Error if the operation was not successful and `buf` is a [`Buffer`][b] with the contents of `path`.
770+
- `offset` is an Integer with the byte offset to begin reading from (default: 0)
771+
- `length` is an Integer with the maximum number of bytes to read (default: Read to end of stream)
772+
- `callback` is an optional function with the signature `function (error, buffer) {}`, where `error` may be an Error that occured if the operation was not successful and `buffer` is a [`Buffer`][b] with the contents of `path`
747773

748774
If no `callback` is passed, a promise is returned.
749775

776+
N.b. this method is likely to result in high memory usage, you should use [files.readReadableStream](#filesreadreadablestream) or [files.readPullStream](#filesreadpullstream) instead where possible.
777+
750778
**Example:**
751779

752780
```JavaScript
753-
ipfs.files.read('/hello-world', (err, buf) => {
781+
ipfs.files.read('/hello-world', (error, buf) => {
754782
console.log(buf.toString('utf8'))
755783
})
756784

@@ -767,10 +795,10 @@ ipfs.files.read('/hello-world', (err, buf) => {
767795

768796
Where:
769797

770-
- `path` is the path of the file to read.
798+
- `path` is the path of the file to read and must point to a file
771799
- `options` is an optional Object that might contain the following keys:
772-
- `offset` is an Integer with the byte offset to begin reading from.
773-
- `count` is an Integer with the maximum number of bytes to read.
800+
- `offset` is an Integer with the byte offset to begin reading from (default: 0)
801+
- `length` is an Integer with the maximum number of bytes to read (default: Read to end of stream)
774802

775803
Returns a [`ReadableStream`][rs] with the contents of `path`.
776804

@@ -793,10 +821,10 @@ stream.on('data', (buf) => console.log(buf.toString('utf8')))
793821

794822
Where:
795823

796-
- `path` is the path of the file to read.
824+
- `path` is the path of the file to read and must point to a file
797825
- `options` is an optional Object that might contain the following keys:
798-
- `offset` is an Integer with the byte offset to begin reading from.
799-
- `count` is an Integer with the maximum number of bytes to read.
826+
- `offset` is an Integer with the byte offset to begin reading from (default: 0)
827+
- `length` is an Integer with the maximum number of bytes to read (default: Read to end of stream)
800828

801829
Returns a [`PullStream`][ps] with the contents of `path`.
802830

@@ -818,24 +846,23 @@ pull(
818846
819847
##### `Go` **WIP**
820848

821-
##### `JavaScript` - ipfs.files.write(path, content, [options, callback])
849+
##### `JavaScript` - ipfs.files.write(path, content, [options], [callback])
822850

823851
Where:
824852

825-
- `path` is the path of the file to write.
853+
- `path` is the path of the file to write
826854
- `content` can be:
827855
- a [`Buffer`][b]
828856
- a [`PullStream`][ps]
829857
- a [`ReadableStream`][rs]
830858
- a [`Blob`][blob] (caveat: will only work in the browser)
831859
- a string path to a file (caveat: will only work in Node.js)
832860
- `options` is an optional Object that might contain the following keys:
833-
- `offset` is an Integer with the byte offset to begin writing at.
834-
- `create` is a Boolean to indicate to create the file if it doesn't exist.
835-
- `truncate` is a Boolean to indicate if the file should be truncated to size 0 before writing.
836-
- `count` is an Integer with the maximum number of bytes to read.
837-
838-
`callback` must follow the `function (err) {}` signature, where `err` is an Error if the operation was not successful.
861+
- `offset` is an Integer with the byte offset to begin writing at (default: 0)
862+
- `create` is a Boolean to indicate to create the file if it doesn't exist (default: false)
863+
- `truncate` is a Boolean to indicate if the file should be truncated after writing all the bytes from `content` (default: false)
864+
- `length` is an Integer with the maximum number of bytes to read (default: Read all bytes from `content`)
865+
- `callback` is an optional function with the signature `function (error) {}`, where `error` may be an Error that occured if the operation was not successful
839866

840867
If no `callback` is passed, a promise is returned.
841868

@@ -853,21 +880,39 @@ ipfs.files.write('/hello-world', Buffer.from('Hello, world!'), (err) => {
853880
854881
##### `Go` **WIP**
855882

856-
##### `JavaScript` - ipfs.files.mv([from, to], [callback])
883+
##### `JavaScript` - ipfs.files.mv(...from, to, [options], [callback])
857884

858885
Where:
859886

860-
- `from` is the path of the source file to move.
861-
- `to` is the path of the destination file to move to.
887+
- `from` is the path(s) of the source to move
888+
- `to` is the path of the destination to move to
889+
- `options` is an optional Object that might contain the following keys:
890+
- `parents` is a Boolean value to decide whether or not to make the parent directories if they don't exist (default: false)
891+
- `format` is what type of nodes to write any newly created directories as (default: `dag-pb`)
892+
- `hashAlg` is which algorithm to use when creating CIDs for newly created directories (default: `sha2-256`)
893+
- `flush` is a Boolean value to decide whether or not to immediately flush MFS changes to disk (default: true)
894+
- `callback` is an optional function with the signature `function (error) {}`, where `error` may be an Error that occured if the operation was not successful
862895

863-
`callback` must follow the `function (err) {}` signature, where `err` is an Error if the operation was not successful.
896+
If there are multiple sources, `to` will be treated as a directory, otherwise it will be treated as the same type as `from`.
864897

865898
If no `callback` is passed, a promise is returned.
866899

867900
**Example:**
868901

869902
```JavaScript
870-
ipfs.files.mv(['/src-file', '/dst-file'], (err) => {
903+
ipfs.files.mv('/src-file', '/dst-file', (err) => {
904+
if (err) {
905+
console.error(err)
906+
}
907+
})
908+
909+
ipfs.files.mv('/src-dir', '/dst-dir', (err) => {
910+
if (err) {
911+
console.error(err)
912+
}
913+
})
914+
915+
ipfs.files.mv('/src-file1', '/src-file2', '/dst-dir', (err) => {
871916
if (err) {
872917
console.error(err)
873918
}
@@ -880,13 +925,12 @@ ipfs.files.mv(['/src-file', '/dst-file'], (err) => {
880925
881926
##### `Go` **WIP**
882927

883-
##### `JavaScript` - ipfs.files.flush([path, callback])
928+
##### `JavaScript` - ipfs.files.flush([...paths], [callback])
884929

885930
Where:
886931

887-
- `path` is the path to flush. Default is `/`.
888-
889-
`callback` must follow the `function (err) {}` signature, where `err` is an Error if the operation was not successful.
932+
- `paths` are an optional string paths to flush (default: `/`)
933+
- `callback` is an optional function with the signature `function (error) {}`, where `error` may be an Error that occured if the operation was not successful
890934

891935
If no `callback` is passed, a promise is returned.
892936

@@ -906,20 +950,17 @@ ipfs.files.flush('/', (err) => {
906950
907951
##### `Go` **WIP**
908952

909-
##### `JavaScript` - ipfs.files.ls([path, options, callback])
953+
##### `JavaScript` - ipfs.files.ls([path], [callback])
910954

911955
Where:
912956

913-
- `path` is the path to show listing for. Defaults to `/`.
914-
- `options` is an optional Object that might contain the following keys:
915-
- `l` is a Boolean value o use long listing format.
916-
917-
`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:
957+
- `path` is an optional string to show listing for (default: `/`)
958+
- `callback` is an optional function with the signature `function (error, files) {}`, where `error` may be an Error that occured if the operation was not successful and `files` is an array containing Objects that contain the following keys:
918959

919-
- `name` which is the file's name.
920-
- `type` which i the object's type (`directory` or `file`).
921-
- `size` the size of the file in bytes.
922-
- `hash` the hash of the file.
960+
- `name` which is the file's name
961+
- `type` which i the object's type (`directory` or `file`)
962+
- `size` the size of the file in bytes
963+
- `hash` the hash of the file
923964

924965
If no `callback` is passed, a promise is returned.
925966

0 commit comments

Comments
 (0)