Justo-fs NPM | npm.io

Simple object-oriented file system API.

Proudly made with ♥ in Valencia, Spain, EU.

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: