[![NPM version](http://img.shields.io/npm/v/justo-fs.svg)](https://www.npmjs.org/package/justo-fs)
[![Build Status](https://travis-ci.org/justojs/justo-fs.svg)](https://travis-ci.org/justojs/justo-fs)
[![Dependency Status](https://david-dm.org/justojs/justo-fs.svg)](https://david-dm.org/justojs/justo-fs)
[![devDependency Status](https://david-dm.org/justojs/justo-fs/dev-status.svg)](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);
```