README

fs-filesysteminfo

The fs-filesysteminfo module, fsi, wraps the native Node.js File System and Path API into a File System Object (FSO) model, which facilitates an object-based approach for working with directories and files. Inspired by the .NET file system libraries.

Getting Started

Install the module with: npm install fs-filesysteminfo --save

Overview

The fs-filesysteminfo NodeJS module, fsi , exposes three classes (objects) for working with the filesystem: FileSystemInfo, DirectoryInfo, and FileInfo. DirectoryInfo and FileInfo are subclasses of the FileSystemInfo class, both expose instance methods for working with directories and files, respectively.

All fsi objects are instantiated with a path {String}. An exception is thrown if the path length is zero or if path is null or undefined. A path used to construct the object can be relative or absolute, and the path does not need to exist. If a relative path is used, it will be resolved relative to the current process.cwd().

Usage

var fsi = require('fs-filesysteminfo');

Class: FileSystemInfo

The base class for the FileInfo and DirectoryInfo objects. Create a FileSystemInfo object by instantiating the fsi FileSystemInfo class.

Constructor: FileSystemInfo(`path`)

path {String} A string specifying the path on which to create the FileSystemInfo object.

var fsiObj = new fsi.FileSystemInfo('temp');  //If temp is an existing file or directory then fsiObj.exists === true otherwise false

Properties: FileSystemInfo

Name	Type	Description
originalPath	{String}	The value that was used to construct the object.
fullName	{String}	Gets the full path of the directory or file.
name	{String}	Gets the last portion of a path. Similar to the Unix basename command.
extension	{String}	Gets the extension of the path, from the last '.' to end of string in the last portion of the path. If there is no '.' in the last portion of the path or the first character of it is '.', then it returns an empty string.
status	{Object}	An object composed of properties specific to the `FileSystemInfo` instance. This information is obtained by using Node's `fs.statSync` method.
flags	{Object}	An object containing the following {Boolean} properties: `isDirectory`, `isFile`, `isBlockDevice`, `isCharacterDevice`, `isFIFO`, `isSocket`, and `isSymbolicLink`.
exists	{Boolean}	Gets a value indicating whether the directory or file exists.
fileSystemPermissions	{FileSystemPermissions}	An object that contains information about the permissions (file system) of the current `FileSystemInfo` instance.

Methods: FileSystemInfo

Name	Type	Description
getType	{String}	Returns the type name of the current instance.
refresh	void	Refreshes the state of the current instance.

Remarks: FileSystemInfo

To determine if the FileSystemInfo instance is a file or a directory, use the following:

if (fsiObj.exists) {
    var fflags = fsiObj.flags
    var isDirecory = fflags.isDirectory;
    var isFile = fflags.isFile;
}

Class: DirectoryInfo

Create a DirectoryInfo object by instantiating the fsi DirectoryInfo class.

Constructor: DirectoryInfo(`path`)

path {String} A string specifying the path on which to create the DirectoryInfo object.

var fsiObj = new fsi.DirectoryInfo('temp');  //If temp is an existing directory then fsiObj.exists === true otherwise false

Properties: DirectoryInfo

Name	Type	Description
parent	{DirectoryInfo}	Gets the parent directory of the current instance.

Methods: DirectoryInfo

Name	Type	Description	Remarks
create([mode], callback)	void	Creates the directory if it does not already exist. `mode` defaults to the octal representation `0777`.	`callback`: {Function} `(error, result)` where `result` is the `DirectoryInfo` instance and `this` in the `callback` context is equal to the original `DirectoryInfo` instance that invoked the `create()` method. `mode`: a {String} or a non-octal {Integer} (an octal representation) (e.g. '777', 777, and '0777' are all equivalent however, 0777 is not). `mode` is automatically converted to the proper integer equivalent (e.g. '777' will become 511) before it is passed on to native Node filesystem methods.
createSync([mode])	{DirectoryInfo}	Synchronous version of `create()`. Returns the calling {DirectoryInfo} instance.
createSubdirectory(path, [mode], callback)	void	Creates a subdirectory or subdirectories on the specified `path` if it does not exist. The specified `path` is relative to the current instance. `mode` defaults to `0777`. If multiple paths are specified (via path separator), and they do not exist, they will be created. Example: /tmp/test1/test2	`callback`: {Function} `(error, result)` where `result` is the `DirectoryInfo` instance of the deepest subdirectory and `this` in the `callback` context is equal to the original `DirectoryInfo` instance that invoked the `createSubdirectory()` method. `callback` is called upon creation of the deepest subdirectory.
createSubdirectorySync(path, [mode])	{DirectoryInfo}	Synchronous version of `createSubdirectory()`. Returns a new `DirectoryInfo` instance of the deepest subdirectory.	An exception is thrown if the `path` length is zero or if `path` is `null` or `undefined`.
delete([recursive], callback)	void	Permanently deletes the instance directory. If `recursive` is true, the directory and all its contents are deleted. If `recursive` is `false` and the directory is not empty, an exception is thrown. `recursive` defaults to `false`.	`callback`: {Function} `(error)` where `this` in the `callback` context is equal to the original `DirectoryInfo` instance that invoked the `delete()` method. `callback` is called once the directory (and optionally its contents) are deleted.
deleteSync([recursive])	void	Synchronous version of `delete()`.	If `recursive` is `false` and the directory is not empty, an exception is thrown. `recursive` defaults to `false`.
enumerateFileSystemInfos({opts}, callback)	void	Iterates the contents of the current `DirectoryInfo` instance. `opts` is an object that utilizes the following properties: `opts.fnFilter`: a {Function(`fsname`)} that determines whether the current item in the enumeration is included in the output {Array} if the function evaluates to `true` where `fsname` is the name of the current filesystem item. `opts.recursive`: a {Boolean} that indicates whether subdirectories will be recursively searched. The default value is `false`.	`callback`: {Function} `(error, result)` where `result` is an `Array<FileSystemInfo>` ({DirectoryInfo} and/or {FileInfo} objects comprised of the instance directory contents) and `this` in the `callback` context is equal to the original `DirectoryInfo` instance that invoked the `enumerateFileSystemInfos()` method. `callback` is called after all items have been iterated.
enumerateFileSystemInfosSync({opts})	{Array<FileSystemInfo>}	Synchronous version of `enumerateFileSystemInfos()`. Returns an {Array} of {DirectoryInfo} and/or {FileInfo} objects comprised of the current directory contents.

Remarks: DirectoryInfo

Look for additional methods to be added in future releases.

create a subdirectory from a DirectoryInfo instance:

var fsiObj = new fsi.DirectoryInfo('currentDir');
var subDir = fsiObj.createSubdirectorySync('subDir','777'); //Create a subdirectory with readable, writable, and executable permissions

Enumeration examples:

var fsiObj = new fsi.DirectoryInfo('currentDir');
var directoryContentsArr1 = fsiObj.enumerateFileSystemInfosSyncSync({fnFilter: '', recursive: true}); //Return all filesystem objects (recursively including all subdirectories and files)
var directoryContentsArr2 = fsiObj.enumerateFileSystemInfosSync({fnFilter: function (fsname) { return /^\..*$/.test(fsname); }, recursive: true}); //Return all filesystem objects (recursively including all subdirectories and files) whose name starts with a dot (.)
var pathnamesArr = directoryContentsArr2.map(function (e) { return e.fullName; }); //Generate an array of absolute paths

Class: FileInfo

Create a FileInfo object by instantiating the fsi FileInfo class.

Constructor: FileInfo(`path`)

path {String} A string specifying the path on which to create the FileInfo object.

var fsiObj = new fsi.FileInfo('temp');  //If temp is an existing file then fsiObj.exists === true otherwise false

Properties: FileInfo

Name	Type	Description
parent	{DirectoryInfo}	Gets the parent directory of the current instance.

Methods: FileInfo

Name	Type	Description	Remarks
create([opts], callback)	void	Creates a zero byte (empty) file. `opts` is an object with the following defaults: { `ensure`:`false`, `mode`:`'777'`, overwrite: `true` }. `mode`: the file mode, a {String} or a non-octal {Integer} (an octal representation) (e.g. '777', 777, and '0777' are all equivalent however, 0777 is not). If `ensure` is `true` and the destination directory does not exist, the directory will be created. If `overwrite` is `true` and the destination file already exists, it will be overwritten.	`callback`: {Function} `(error)` where `this` in the `callback` context is equal to the original `FileInfo` instance that invoked the `create()` method. `mode` is automatically converted to the proper integer equivalent (e.g. '777' will become 511) before it is passed on to native Node filesystem method.
createSync([opts])	{FileInfo}	Synchronous version of `create()`. Returns the calling {FileInfo} instance.
delete()	void	Permanently deletes the instance file.	`callback`: {Function} `(error)` where `this` in the `callback` context is equal to the original `FileInfo` instance that invoked the `delete()` method.
deleteSync()	void	Synchronous version of `delete()`.

Remarks: FileInfo

Look for additional methods to be added in future releases.

Class (Private): FileSystemPermissions

A class that contains properties related to roles and each roles' (file system) permissions for directories and files. This class is scoped within the context of the library (private) and is not exposed via exports.

Properties: FileSystemPermissions

Name	Type	Description
owner	{Object}	The file system permissions specific to the `owner` role. `canRead`, `canWrite`, and `canExecute` (all of `Boolean` type).
group	{Object}	The file system permissions specific to the `group` role. `canRead`, `canWrite`, and `canExecute` (all of `Boolean` type).
otherUsers	{Object}	The file system permissions specific to the `otherUsers` role. `canRead`, `canWrite`, and `canExecute` (all of `Boolean` type).
octalFileSystemModeString	{String}	A valid file system octal string representation. Examples of valid values include: `0777`, `777`, `0`, `466`, etc.

Methods: FileSystemPermissions

Name	Type	Description
getType	{String}	Returns the type name of the current instance.
refresh	void	Refreshes the state of the current instance.
toRoleBinaryRepresentationString	{String}	Returns the binary representation of the permissions string.
toRoleLetterRepresentationString	{String}	Returns the 9 bit Linux-style permissions string.

Remarks: FileSystemPermissions

Given the following:

var fsiObj = new _fsi.DirectoryInfo('./tmp'); // an existing directory to create new subdirectories with varying permissions

var subdirectoryArr = [
    { name: 'tmp1', mode: '777' },
    { name: 'tmp2', mode: '775' },
    { name: 'tmp3', mode: '666' },
    { name: 'tmp4', mode: '444' }
];

subdirectoryArr.forEach(function (subdirectory) {
    var newSubdirectory = fsiObj.createSubdirectorySync(subdirectory.name, subdirectory.mode);

    var nsp = newSubdirectory.fileSystemPermissions;

    nsp['subdirectoryName', subdirectory.name];

    nsp['toRoleBinaryRepresentationString()'] = nsp.toRoleBinaryRepresentationString();

    nsp['toRoleLetterRepresentationString()'] = nsp.toRoleLetterRepresentationString();

    var outputResult = JSON.stringify(nsp);

    console.log('\n' + outputResult + '\n');
});

The resulting output is:

{
    "subdirectoryName": "tmp1",
    "octalFileSystemModeString": "0777",
    "owner": { "canRead": true, "canWrite": true, "canExecute": true, "letterFormat": "rwx", "binaryFormat": "111" },
    "group": { "canRead": true, "canWrite": true, "canExecute": true, "letterFormat": "rwx", "binaryFormat": "111" },
    "otherUsers": { "canRead": true, "canWrite": true, "canExecute": true, "letterFormat": "rwx", "binaryFormat": "111" },
    "toRoleBinaryRepresentationString()": "111111111",
    "toRoleLetterRepresentationString()": "rwxrwxrwx"
}
{
    "subdirectoryName": "tmp2",
    "octalFileSystemModeString": "0775",
    "owner": { "canRead": true, "canWrite": true, "canExecute": true, "letterFormat": "rwx", "binaryFormat": "111" },
    "group": { "canRead": true, "canWrite": true, "canExecute": true, "letterFormat": "rwx", "binaryFormat": "111" },
    "otherUsers": { "canRead": true, "canWrite": false, "canExecute": true, "letterFormat": "r-x", "binaryFormat": "101" },
    "toRoleBinaryRepresentationString()": "111111101",
    "toRoleLetterRepresentationString()": "rwxrwxr-x"
}
{
    "subdirectoryName": "tmp3",
    "octalFileSystemModeString": "0666",
    "owner": { "canRead": true, "canWrite": true, "canExecute": false, "letterFormat": "rw-", "binaryFormat": "110" },
    "group": { "canRead": true, "canWrite": true, "canExecute": false, "letterFormat": "rw-", "binaryFormat": "110" },
    "otherUsers": { "canRead": true, "canWrite": true, "canExecute": false, "letterFormat": "rw-", "binaryFormat": "110" },
    "toRoleBinaryRepresentationString()": "110110110",
    "toRoleLetterRepresentationString()": "rw-rw-rw-"
}
{
    "subdirectoryName": "tmp4",
    "octalFileSystemModeString": "0444",
    "owner": { "canRead": true, "canWrite": false, "canExecute": false, "letterFormat": "r--", "binaryFormat": "100" },
    "group": { "canRead": true, "canWrite": false, "canExecute": false, "letterFormat": "r--", "binaryFormat": "100" },
    "otherUsers": { "canRead": true, "canWrite": false, "canExecute": false, "letterFormat": "r--", "binaryFormat": "100" },
    "toRoleBinaryRepresentationString()": "100100100",
    "toRoleLetterRepresentationString()": "r--r--r--"
}

TODO

Continue adding functionality and tests.
Add a DirectoryInfo.clean() and cleanSync() method to remove directory content without removing the directory itself.

Contributing

In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code using Grunt.

fs-filesysteminfo

Usage no npm install needed!

README

fs-filesysteminfo

Getting Started

Overview

Usage

Class: FileSystemInfo

Constructor: FileSystemInfo(`path`)

Properties: FileSystemInfo

Methods: FileSystemInfo

Remarks: FileSystemInfo

Class: DirectoryInfo

Constructor: DirectoryInfo(`path`)

Properties: DirectoryInfo

Methods: DirectoryInfo

Remarks: DirectoryInfo

Class: FileInfo

Constructor: FileInfo(`path`)

Properties: FileInfo

Methods: FileInfo

Remarks: FileInfo

Class (Private): FileSystemPermissions

Properties: FileSystemPermissions

Methods: FileSystemPermissions

Remarks: FileSystemPermissions

TODO

Contributing

License

Usage no npm install needed!

README

fs-filesysteminfo

Getting Started

Overview

Usage

Class: FileSystemInfo

Constructor: FileSystemInfo(path)

Properties: FileSystemInfo

Methods: FileSystemInfo

Remarks: FileSystemInfo

Class: DirectoryInfo

Constructor: DirectoryInfo(path)

Properties: DirectoryInfo

Methods: DirectoryInfo

Remarks: DirectoryInfo

Class: FileInfo

Constructor: FileInfo(path)

Properties: FileInfo

Methods: FileInfo

Remarks: FileInfo

Class (Private): FileSystemPermissions

Properties: FileSystemPermissions

Methods: FileSystemPermissions

Remarks: FileSystemPermissions

TODO

Contributing

License

Constructor: FileSystemInfo(`path`)

Constructor: DirectoryInfo(`path`)

Constructor: FileInfo(`path`)