fs-jetpack
This is an attempt to make comprehensive, higher level API for node's fs library, which will be fun to use (see "Neat tricks fs-jetpack knows" as a starter).
Installation
npm install fs-jetpack
Usage
var jetpack = requite('fs-jetpack');
API
API has the same set of synchronous and asynchronous methods. All async methods are promise based (so no callbacks folks, promises instead).
Commonly used naming convention in node world is reversed in this library. Asynchronous methods are those with "Async" suffix, all methods without "Async" in the name are synchronous. Reason behind this is that it gives very nice look to blocking API, and promise based non-blocking code is verbose anyway, so one more word is not much of a difference. Also it just feels right to me. When you see "Async" word you are 100% sure this method is returning promise, and when you don't see it, you are 100% sure this method retuns immediately (and possibly blocks).
try {
jetpack.dir('foo');
} catch (err) {
}
jetpack.dirAsync('foo')
.then(function () {
}, function (err) {
});
Methods:
- append(path, data, [options])
- copy(from, to, [options])
- createReadStream(path, [options])
- createWriteStream(path, [options])
- cwd([path...])
- dir(path, [criteria])
- exists(path)
- file(path, [criteria])
- inspect(path, [options])
- inspectTree(path, [options])
- list(path, [useInspect])
- move(from, to)
- path(parts...)
- read(path, [returnAs], [options])
- remove(path, [options])
- rename(path, newName)
- write(path, data, [options])
append(path, data, [options])
also appendAsync(path, data, [options])
Appends given data to the end of file. If file (or any parent directory) doesn't exist, creates it (or them).
parameters:
path
the path to file.
data
data to append (could be String
or Buffer
).
options
(optional) Object
with possible fields:
mode
if the file doesn't exist yet, will be created with given mode. Value could be number (eg. 0700
) or string (eg. '700'
).
returns:
Nothing.
copy(from, to, [options])
also copyAsync(from, to, [options])
Copies given file or directory (with everything inside).
parameters:
from
path to location you want to copy.
to
path to destination location, where the copy should be placed.
options
(optional) additional options for customization. Is an Object
with possible fields:
overwrite
(default: false
) Whether to overwrite destination path if it exists. For directories, source directory is merged with destination directory, so files in destination which are not present in the source, will remain intact.only
(Array
of globs) will copy only items matching any of specified glob patterns (read more).allBut
(Array
of globs) will copy everything except items matching any of specified glob patterns (read more). If only
was also specified this field is ignored.
returns:
Nothing.
examples:
jetpack.copy('file.txt', 'somwhere/file.txt', { overwrite: true });
jetpack.copy('my_dir', 'somewhere/my_dir', { only: ['*.jpg'] });
jetpack.copy('my_dir', 'somewhere/my_dir', { allBut: ['my_dir/logs'] });
createReadStream(path, [options])
Just an alias to vanilla fs.createReadStream.
createWriteStream(path, [options])
Just an alias to vanilla fs.createWriteStream.
cwd([path...])
Returns Current Working Directory (CWD) for this instance of jetpack, or creates new jetpack object with given path as its internal CWD.
Note: fs-jetpack never changes value of process.cwd()
, the CWD we are talking about here is internal value inside every jetpack instance.
parameters:
path...
(optional) path (or many path parts) to become new CWD. Could be absolute, or relative. If relative path given new CWD will be resolved basing on current CWD of this jetpack instance.
returns:
If path
not specified, returns CWD path of this jetpack object. For main instance of fs-jetpack it is always process.cwd()
.
If path
specified, returns new jetpack object (totally the same thing as main jetpack). The new object resolves paths according to its internal CWD, not the global one (process.cwd()
).
examples:
console.log(process.cwd());
console.log(jetpack.cwd());
var jetParent = jetpack.cwd('..');
console.log(jetParent.cwd());
jetParent.dir('four');
var jetParentParent = jetParent.cwd('..');
console.log(jetParentParent.cwd());
var sillyCwd = jetpack.cwd('a', 'b', 'c');
console.log(sillyCwd.cwd());
dir(path, [criteria])
also dirAsync(path, [criteria])
Ensures that directory on given path meets given criteria. If any criterium is not met it will be after this call.
parameters:
path
path to directory to examine.
criteria
(optional) criteria to be met by the directory. Is an Object
with possible fields:
exists
(default: true
) whether directory should exist or not. If set to true
and path
contains many nested, nonexistent directories all of them will be created.empty
(default: false
) whether directory should be empty (no other files or directories inside). If set to true
and directory contains any files or subdirectories all of them will be deleted. If exists = false
this field is ignored.mode
ensures directory has specified mode. If not set and directory already exists, current mode will be preserved. Value could be number (eg. 0700
) or string (eg. '700'
).
returns:
New CWD context with directory specified in path
as CWD.
Or undefined
if exists
was set to false
.
examples:
jetpack.dir('new_dir');
jetpack.dir('/my_stuff/some_dir', { exists: false });
jetpack.dir('empty_dir', { empty: true, mode: '700' });
jetpack
.dir('main_dir')
.dir('sub_dir');
exists(path)
also existsAsync(path)
Checks whether something exists on given path
. This method returns values more specyfic than true/false
to protect from errors like "I was expecting directory, but it was a file".
returns:
false
if path doesn't exist."dir"
if path is a directory."file"
if path is a file."other"
if none of the above.
file(path, [criteria])
also fileAsync(path, [criteria])
Ensures that file meets given criteria. If any criterium is not met it will be after this call.
parameters:
path
path to file to examine.
criteria
(optional) criteria to be met by the file. Is an Object
with possible fields:
exists
(default: true
) whether file should exist or not.empty
(default: false
) whether file should be empty. If exists = false
this field is ignored.content
(String
, Buffer
, Object
or Array
) sets file content. If Object
or Array
given to this parameter the output will be JSON. If exists = false
, or empty = true
this field is ignored.jsonIndent
(defaults to 0) if writing JSON data this tells how many spaces should one indentation have.mode
ensures file has specified mode. If not set and file already exists, current mode will be preserved. Value could be number (eg. 0700
) or string (eg. '700'
).
returns:
Jetpack object you called this method on (self).
examples:
jetpack.file('something.txt');
jetpack.file('not_something.txt', { exists: false });
jetpack.file('hello.txt', { mode: '777', content: 'Hello World!' });
inspect(path, [options])
also inspectAsync(path, [options])
Inspects given path (replacement for fs.stat).
parameters:
path
path to inspect.
options
(optional). Possible values:
checksum
if specified will return checksum of inspected file. Possible values are strings 'md5'
or 'sha1'
. If given path is directory this field is ignored and omited.
returns:
null
if given path doens't exist.
Otherwise Object
of structure:
{
name: "my_dir",
type: "file",
size: 123,
md5: '900150983cd24fb0d6963f7d28e17f72'
}
inspectTree(path, [options])
also inspectTreeAsync(path, [options])
Calls inspect recursively on given path so it creates tree of all directories and sub-directories inside it.
parameters:
path
the path to inspect.
options
(optional). Possible values:
checksum
if specified will also calculate checksum of every item in the tree. Possible values are strings 'md5'
or 'sha1'
. Checksums for directories are calculated as checksum of all children' checksums plus their filenames (see example below).
returns:
null
if given path doesn't exist.
Otherwise tree of inspect objects like:
{
name: 'my_dir',
type: 'dir',
size: 123,
md5: '11c68d9ad988ff4d98768193ab66a646',
children: [
{
name: 'empty',
type: 'dir',
size: 0,
md5: null,
children: []
},{
name: 'file.txt',
type: 'file',
size: 123,
md5: '900150983cd24fb0d6963f7d28e17f72'
}
]
}
list(path, [useInspect])
also listAsync(path, [useInspect])
Lists the contents of directory.
parameters:
path
path to directory you would like to list.
useInspect
(optional) the type of data this call should return. Possible values:
false
(default) returns just a list of filenames (the same as fs.readdir()
)true
performs inspect on every item in directory, and returns array of those objectsobject
if object has been passed to this parameter, it is treated as options
parameter for inspect method, and will alter returned inspect objects
returns:
Array
of strings or objects depending on call properies. Or null
if given path doesn't exist.
move(from, to)
also moveAsync(from, to)
Moves given path to new location.
parameters:
from
path to directory or file you want to move.
to
path where the thing should be moved.
returns:
Nothing.
path(parts...)
Returns path resolved to internal CWD of this jetpack object.
parameters:
parts
strings to join and resolve as path (as many as you like).
returns:
Resolved path as string.
examples:
jetpack.cwd();
jetpack.path();
jetpack.path('three');
jetpack.path('..', 'four');
read(path, [returnAs], [options])
also readAsync(path, [returnAs], [options])
Reads content of file. If file on given path doesn't exist returns null
instead of throwing ENOENT
error.
parameters:
path
path to file.
returnAs
(optional) how the content of file should be returned. Is a string with possible values:
'utf8'
(default) content will be returned as UTF-8 String.'buf'
content will be returned as Buffer.'json'
content will be returned as parsed JSON object.'jsonWithDates'
content will be returned as parsed JSON object, and date strings in ISO format will be automatically turned into Date objects.
options
(optional) is an object with possible fields:
safe
if set to true
the file will be read in "safe mode".
returns:
File content in specified format, or null
if file doesn't exist.
remove(path, [options])
also removeAsync(path, [options])
Deletes given path, no matter what it is (file or directory).
parameters:
path
path to file or directory you want to remove.
options
(optional) additional conditions to removal process. Is an object with possible fields:
only
(Array
of globs) will delete only items matching any of specified glob patterns (read more on that).allBut
(Array
of globs) will delete everything except items matching any of specified glob patterns (read more on that). If only
was also specified this field is ignored.
returns:
Nothing.
examples:
jetpack.remove('my_work/notes.txt');
jetpack.remove('my_work/important_stuff');
jetpack.remove('my_app', { only: [ '*.log', 'temp' ] });
jetpack.remove('my_app', { allBut: [ 'my_app/user_data' ] });
rename(path, newName)
also renameAsync(path, newName)
Renames given file or directory.
parameters:
path
path to thing you want to change name.
newName
new name for this thing (not full path, just a name).
returns:
Nothing.
write(path, data, [options])
also writeAsync(path, data, [options])
Writes data to file.
parameters:
path
path to file.
content
data to be written. This could be String
, Buffer
, Object
or Array
(if last two used, the data will be outputed into file as JSON).
options
(optional) Object
with possible fields:
jsonIndent
(defaults to 0) if writing JSON data this tells how many spaces should one indentation have.safe
if set to true
the file will be written in "safe mode".
returns:
Nothing.
Neat tricks fs-jetpack knows
Every jetpack instance has its independent, internal CWD
So you can create many jetpack objects and work on directories in a little more object-oriented fashion.
var src = jetpack.cwd('path/to/source');
var dest = jetpack.cwd('path/to/destination');
src.copy('foo.txt', dest.path('bar.txt'));
Files creation in declarative style
You can create whole tree of directories and files in declarative style.
jetpack
.dir('foo')
.file('foo.txt', { content: 'Hello...' })
.file('bar.txt', { content: '...world!' })
.cwd('..')
.dir('bar')
.file('foo.txt', { content: 'Wazup?' });
jetpack
.dirAsync('foo')
.then(function (dir) {
return dir.fileAsync('foo.txt', { content: 'Hello...' });
})
.then(function (dir) {
return dir.fileAsync('bar.txt', { content: '...world!' });
.then(function (dir) {
return dir.cwd('..').dirAsync('bar');
})
.then(function (dir) {
dir.fileAsync('foo.txt', { content: 'Wazup?' });
});
Hides ENOENT from you as much as possible
"ENOENT, no such file or directory" is the most annoying error when working with file system, and fs-jetpack does 2 things to save you the hassle:
- For wrte/creation operations, if any of parent directories doesn't exist, jetpack will just create them as well.
- For read/inspect operations, if file or directory doesn't exist,
null
is returned instead of throwing.
Filtering things to copy/remove with "globs"
Copy and remove have option for blacklisting and whitelisting things inside directory which will be affected by the operation. For instance:
jetpack.copy('foo', 'foo1', { allBut: ['*.pdf'] });
jetpack.copy('foo', 'foo2', { only: ['*.pdf'] });
"Safe" file overwriting
It is not fully safe to just overwrite existing file with new content. If process will crash during the operation, you are basically srewed. The old file content is lost, because you overwritten it. And the new file is empty or written only partially. Fs-jetpack has built-in "safe mode", which helps you get rid of this issue. Under the hood it works as follows...
Let's assume there's already file.txt
with content Hello world!
on disk, and we want to update it to Hello universe!
.
jetpack.write('file.txt', { safe: true, content: 'Hello universe!' });
Above line will perform tasks as follows:
- Write
Hello universe!
to file.txt.__new__
(so we didn't owerwrite the original file). - Move
file.txt
(with Hello world!
) to file.txt.__bak__
, so it can serve as a backup. - Move
file.txt.__new__
to file.txt
, where we wanted it to be on the first place. - Delete
file.txt.__bak__
, because it is no longer needed.
Thanks to that the backup of old data is reachable all the time, until we are 100% sure the new data has been successfuly written to disk.
For this to work, read operation have to be aware of the backup file.
jetpack.read('file.txt', { safe: true });
Above read will do:
- Read
file.txt
- If step 1 failed, try to read
file.txt.__bak__
. - If step 2 failed as well, we are sure there is no such file.
The whole process is performed automatically for you by simply adding safe: true
to call options of write and read methods.