justo-fs
Version:
Simple object-oriented file system API.
532 lines (361 loc) • 10.5 kB
Markdown
[](https://www.npmjs.org/package/justo-fs)
[](https://travis-ci.org/justojs/justo-fs)
[](https://david-dm.org/justojs/justo-fs)
[](https://david-dm.org/justojs/justo-fs#info=devDependencies)
Simple object-oriented file system API.
*Proudly made with ♥ in Valencia, Spain, EU.*
## Table of contents
1. [Files](#files)
2. [Directories](#directories)
3. [Entries](#entries)
## Files
The `File` class represents a file.
### Constructors
To create a `File` instance, we can use the following constructors:
```
File(...path)
```
Example:
```
f = new File("/my/dir/file.txt");
f = new File("/my/dir", "file.txt");
```
### Attributes
To get file info, we can use the following attributes:
```
path : string //the file path
name : string //the file name
ext : string //the file extension
parent : Dir //the parent directory
parentPath : string //the parent directory path
size : number //the file size in bytes
times : object //the times: modified, change, access, creation
uid : number //the owner UID
gid : number //the group GID
```
#### Renaming the file
To rename a file, we have to use the `name` property.
If the new name contains a path, the method raises an error
Examples:
```
var f = new File("/my/dir", "file.txt");
f.name = "file.old"; //ok
f.name = "dir/file.old"; //error
```
When the file is renamed, the instance references to the new path:
```
f = new File("/my/dir", "file.txt");
console.log(f.name); //file.txt
f.name = "file.old";
console.log(f.name); //now: file.old
```
#### Changing the owner UID
To change the owner UID, we can use the `chown()` method or the `uid` property:
```
uid : number
chown(uid : number, gid ?: number)
```
Example:
```
f.uid = 123;
f.chown(123);
```
#### Changing the group UID
To change the group UID, we can use the `chown()` method or the `gid` property:
```
gid : number
chown(uid : number, gid : number)
```
Example:
```
f.uid = 123;
f.gid = 321;
f.chown(123, 321);
```
### Replacing partial path
To replace a partial path, we can use the `replace()` method:
```
replacePath(path) : string
```
Example:
```
var f = new File("/my/dir/file.txt");
var path = f.replacePath("/my/dir"); //path = "/file.txt" and f = "/my/dir/file.txt"
var path = f.replacePath("/my/dir/"); //path = "file.txt" and f = "/my/dir/file.txt"
```
### chmod()
To change the file mode, we can use the `chmod()` method:
```
chmod(mode : number|string)
```
Example:
```
file.chmod("777");
```
### Content
To get the content, we can use the properties: `text`, `json` or `yaml`.
#### text
To read/set the contents as a string:
```
get text() : string
set text(text : string)
```
Example:
```
var f = new File("/my/dir", "file.txt");
console.log(f.text);
f.text = "the new content";
```
#### json
To read/set the content as a JSON object:
```
get json() : object
set json(obj : object)
```
Example:
```
var f = new File("/my/dir", "file.json");
console.log(f.json.x);
f.json = {x: 1, y: 2};
```
#### yaml
To read/set the content as a YAML object:
```
get yaml() : object
set yaml(obj : object)
```
### exists()
Checks whether the entry exists and it is a file:
```
exists() : boolean
```
If the entry exists but it is not a file, it returns false.
### create()
Creates the file:
```
create() : boolean
create(opts) : boolean
```
The method returns if the file has been created.
The `opts` parameter can have the following properties:
- `overwrite` (boolean). Must the file be overwritten whether it exists? `true`, yep; `false`, nope. Default: `true`.
- `content` (string or object). The file content. If an object is passed, this is transformed to JSON.
Examples:
```
f = new File("/my/dir", "file.txt");
f.create();
f.create({overwrite: false});
f.create({overwrite: false, content: "The content."});
f.create({overwrite: false, content: {x: 1, y: 2}});
```
### createFrom()
Creates the file using as content the concatenated content of the specified files:
```
createFrom(files : string[], opts : object = {header: "", separator: "", footer: ""})
```
The options can be:
- `header` (string). Text at the beginning of the file.
- `separator` (string). Text between files.
- `footer` (string). Text at the end of the file.
Example:
```
f = new File("/my/dir", "file.txt");
f.createFrom(["/my/dir/a.txt", "/my/dir/b.txt"], {separator: "\n\n"});
```
### appendText()
Appends a text at the end of the file or a given number of line:
```
f.appendText(text : string)
f.appendText(text : string, ln : number)
f.appendText(text : string, opts : {line: number, type: "start|end"})
```
### remove()
Removes the file:
```
remove()
```
### truncate()
Truncates the file:
```
truncate()
```
### copyTo()
Copies the file:
```
copyTo(...path)
```
If the `path` parameter ends with `/`, the method copies the file to the specified
directory using as name the file name; otherwise, the file is copied to the specified
path. For example:
```
var f = new File("/my/dir", "file.txt");
f.copyTo("/my/new/dir/"); //copy to /my/new/dir/file.txt
f.copyTo("/my/dir/file.old"); //copy to /my/dir/file.old
f.copyTo("/my/dir", "file.old"); //copy to /my/dir/file.old
```
### moveTo()
Moves the file to another location:
```
moveTo(...path)
```
If the `path` parameter ends with `/`, the file is moved to the specified directory.
Example:
```
var f = new File("/my/dir/file.txt");
f.moveTo("/my/other/dir/"); //move to /my/other/dir/file.txt
f.moveTo("/my/other/dir/file.old"); //move to /my/other/dir/file.old
f.moveTo("/my/other/dir", "file.old"); //move to /my/other/dir/file.old
```
After the operation, the file will reference to the new path.
## Directories
The `Dir` class represents a directory.
### Constructors
To create a `Dir` instance, we can use the following constructors:
```
Dir(...path)
```
Example:
```
d = new Dir("/my/dir");
d = new Dir("/my/dir", "subdir");
```
### Attributes
To get directory info, we can use the following attributes:
```
path : string //the directory path
name : string //the directory name
parent : Dir //the parent directory
parentPath : string //the parent directory path
times : object //the times: modified, change, access, creation
entries : Entry[] //the directory entries
files : File[] //the directory files
uid : number //the owner UID
gid : number //the group GID
```
### hasEntries()
Check whether the directory has entries:
```
hasEntries() : boolean
```
### Entry names
Return the entry names:
```
//files and dirs
getEntryNames() : string[]
//only files
getFileNames() : string[]
getFileNames(opts : object) : string[]
//only dirs
getDirNames() : string[]
getDirNames(opts : object) : string[]
```
Options:
- `ext` (boolean). Used to indicate if the extension must be returned. Default value: `true`.
- `ignore` (string or string[]). Entries to ignore/skip.
### file() and dir()
If we need to get an entry as `File` or `Dir`, we can use:
```
file(subpath : string) : File
dir(subpath : string) : Dir
```
Example:
```
var dir = new Dir("/dir");
dir.file("file.txt"); //new File(dir.path, "file.txt");
dir.dir("dir"); //new Dir(dir.path, "dir");
```
### Renaming directory
Similar to files, using the `name` property.
### Changing UID and GID
Similar to files, using `uid`, `gid` or `chown()`.
We can also indicate `recurse` as option; for example:
```
dir.chown(1, 1, {recurse: true});
```
### Temporary directory
To know the temporary directory, we can use the static attribute:
```
TMP_DIR : string
```
We can use the `TMP` alias.
Example:
```
dir = new Dir(Dir.TMP_DIR, "mydir");
dir = new Dir(Dir.TMP, "mydir");
```
### create()
Creates the directory:
```
create() : boolean
```
The method returns if the directory has been created.
Example:
```
dir = new Dir(Dir.TMP_DIR, "mydir");
dir.create();
```
### createTmpDir()
Create a temporary directory:
```
createTmpDir() : Dir
createTmpDir(subdir : string) : Dir
```
This method is similar to:
```
//Dir.createTmpDir()
dir = new Dir(Dir.TMP, Date.now().toString());
dir.create();
//Dir.createTmpDir(subdir)
dir = new Dir(Dir.TMP, subdir);
dir.create();
```
### remove()
Removes the directory:
```
remove()
```
### exists()
Checks whether the entry exists and it is a directory:
```
exists() : boolean
```
If the entry exists but it is not a directory, it returns false.
### copyTo()
Copy the directory:
```
copyTo(...path : string[])
copyTo({path : string, ignore : string})
copyTo({path : string, ignore : string[]})
```
Example:
```
dir = new Dir("app/");
dir.copyTo({path: "dist/", ignore: "app/styles/"})
```
### moveTo()
Similar to files.
## Entries
The `justo-fs` package contains several functions for several tasks, independently
of the entry type:
```
exists(...path) : boolean
entry(...path) : File|Dir|undefined
remove(...path)
copy(src, dst, opts)
rename(from : string, to : string) : boolean
chown(path : string, owner : number, group ?: number, opts ?: object)
chmod(path : string, mode : number|string)
```
The `exists()` function returns whether an entry (file or directory) exists.
The `entry()` function returns an entry as `File` or `Dir`. If the entry doesn't existe,
it returns `undefined`.
The `remove()` function removes an entry.
The `copy()` function copies a source to destination. `opts`:
- `force` (boolean). Don't throw error if nonexistent.
- `ignore` (string or string[]). Ignore the entries.
The `rename()` function renames an entry.
The `chown()` function changes the owner and the group.
The `chmod()` function changes the mode.
```
entry(src).copyTo(dst);
```