si-file v1.1.12
si-file
A general-purpose File object to assist with any project, using Promises for asynchronous operations.
It uses the Bluebird implementation of Promises.
File queue
Behind the scenes, the si-file
object uses a Promise-based queue system for all asynchronous operations, so that all read/write/delete operations requested on a particular file path are guaranteed to execute in the order in which they were requested. Between different files there is no such guarantee. This applies to the file path, not the particular si-file
instance, so multiple instances of a single path will share the same file queue.
Basic usage
Instantiation
For basic instantiation, simply require the library and pass in the file path as a constructor parameter.
var File = require('si-file');
var file = new File('dir/myFile.txt');
Encoding Type
You may optionally specify the file encoding type as a second parameter, which will be used for all read/write operations.
If you do not specify an encoding then utf8
will be used by default.
var file = new File('dir/myFile.txt', 'ascii');
Node supports the following encoding types:
utf-8
(orutf8
)ascii
base64
binary
hex
ucs-2
(orucs2
,utf16le
, orutf-16le
)
File Properties
An si-file
object has several read-only properties that expose path information. Use file.path
to get the full path of the file, as passed into the constructor.
You can also use file.name
get the filename only, without the directory (but including the file extension, if applicable).
var file = new File('dir/myFile.txt');
file.path === 'dir/myFile.txt'; // true
file.name === 'myFile.txt'; // true
file.ext === 'txt'; // true
You can also use dir
to get a new si-file
object representing the parent directory of the current file, or null
if the file is at the root level (i.e. has no parent directory).
file.dir.name === 'dir'; // true
To see whether the si-file
object actually exists on the filesystem, use file.exists()
or file.existsSync()
.
file.exists().then(function(doesExist) {
if (doesExist) {
// file exists
}
});
if (file.existsSync()) {
// file exists
}
Other methods are available to distinguish between folders and files.
file.isDirectory().then(function(isDirectory) {
if (isDirectory) {
// the directory exists
}
});
file.isFile().then(function(isFile) {
if (isFile) {
// the file exists (and it's not a directory)
}
});
To create a directory use file.mkdir()
. If the directory already exists it will return a successful promise, but if a file exists of the same name then it will return a failed promise.
Reading
Async
The asynchronous methods return Promises of the requested data.
file.read().then(function(fileData) {
// file has been read; fileData is the full contents
}).catch(function(err) {
// handle any errors
});
file.readLines().then(function(fileDataLines) {
// file has been read; fileDataLines is an array of its lines
});
Synchronous
The read methods are also available in synchronous forms, using file.readSync()
and file.readLinesSync()
.
Writing
Use file.write()
to write data asynchronously. Optionally pass options as a second parameter.
file.write("some data").then(function() {
// file is written
});
You can also write a single line, which will append the system-appropriate line ending (\n
or \r\n
) to the end of the given string, if it does not already end with that character. Any existing line endings within the string are preserved.
file.writeLine("some data").then(function() {
// file is written
});
Appending
You can also use file.append()
and file.appendLine()
, which work like their "write" counterparts except that they append the data to the given file rather than overwriting the entire file.
File Deletion
file.delete().then(function() {
// file is deleted
});
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago