file-js

Abstract representation of a pathname

• Installation
• Features
• Demo
• Usage
• API
• Instance methods
• Test
• Contributing

Installation

npm install --save file-js

Features

• File glob matching
• File listings
• File locking
• Assert file permissions
• Supports promises
• Supports synchronous and asynchronous methods

Coming soon

• File matching with regular expressions
• Create temp files
• Create directories via .mkdir and .mkdirp
• Assert existence of files via .exists()
• Watch file
• Change permissions
• Rename
• Support file URI
• Support for callbacks

Usage

const File = require('file-js');

const file = File.create('myFile');
file.getList()
  then((files) => {
    files.each(console.log);
  });

const file = File.create('myDirectory');
if (file.isDirectorySync()) {
  console.log('processing directory');
}

Type checking

const pathname = File.create('myFile');
if (pathname.isFile()) {
  console.log(`process ${pathname}`)
}

List files for a directory

Synchronously list files:

const dir = File.create('myDirectory');
const files = dir.getListSync()

console.log(files.forEach(console.log));

Asynchronously list files:

const dir = File.create('myDirectory');
dir.getList().each(console.log);

File locking

Perform operations on a file whilst locked:

const fs = require('fs');
const file = File.create('myFile');

file.withLock(() => {
  file.isWritable((w_ok) => {
    if (w_ok) {
      fs.writeFileSync(file.getAbsolutePath(), 'my data\n');
    }
  });
});

Check permissions

Check that a pathname has write permission:

const file = File.create('myFile');
file.isWritable((isWritable) => {
  if (isWritable) {
    console.log(`Able to write to ${file.getName()}`);
  }  
});

Check that a pathname is executable:

const file = File.create('myFile');
file.isExecutable((isExecutable) => {
  if (isExecutable) {
    console.log(`Able to execute ${file.getName()}`);
  }
});

Pathname changes and access

Get the last time a pathname was modified:

const file = File.create('myFile');
const lastModified = file.lastModifiedSync();

console.log(`${file.getName()} was last modified on ${lastModified}`);

Get the last time a pathname was accessed:

const file = File.create('myFile');
const lastAccessed = file.lastAccessedSync();

console.log(`${file.getName()} was last accessed on ${lastAccessed}`);

File size

Check a file is less than 1k:

const file = File.create('myFile');
if (file.sizeSync() < 1024) {
  console.log(`${file.getName()} < 1k`);
}

Supports callbacks

Get list of files for a directory:

const dir = File.create('myDir');
dir.getList((err, files) => {
  if (err) return console.error(err);

  console.log(files);
});

API

Static methods

File.create() -> File

Parameters - None

Returns

Returns a File instance.

Instance methods

.getList() -> Promise

Parameters

• None

Returns

• If the Promise fulfils, the fulfilment value is an array of files in the directory or null if it's a file

.getListSync() -> Promise

Synchronous version of .getList()

.isDirectory() -> Promise

Parameters

• None

Returns

• If the Promise fulfils, the fulfilment value is is a boolean indicating if the pathname is a directory

.isDirectorySync() -> Promise

Synchronous version of .isDirectory()

.isFile() -> Promise

Parameters

• None

Returns

• If the Promise fulfils, the fulfilment value is is a boolean indicating if the pathname is a file

.isFileSync() -> Promise

Synchronous version of .isFile()

.isHidden() -> Promise

Parameters

• None

Returns

• If the Promise fulfils, the fulfilment value is is a boolean indicating if the pathname is hidden

.isHiddenSync() -> Promise

Synchronous version of .isHidden()

.isMatch(globPattern) -> Promise

Parameters

• None

Returns

• If the Promise fulfils, the fulfilment value is is a boolean indicating if the pathname matches globPattern

.isMatchSync() -> Promise

Synchronous version of .isMatch()

.lastAccessed() -> Promise

Parameters

• None

Returns

• If the Promise fulfils, the fulfilment value is is a datetime when the file was last accessed

.lastAccessedSync() -> Promise

Synchronous version of .lastAccessed()

.lastModified() -> Promise

Parameters

• None

Returns

• If the Promise fulfils, the fulfilment value is is a datetime when the file was last modified

.lastModifiedSync() -> Promise

Synchronous version of .lastModified()

.size() -> Promise

Parameters

• None

Returns

• If the Promise fulfils, the fulfilment value is is the size of the file in bytes

.sizeSync() -> Promise

Synchronous version of .size()

.isWritable() -> Promise

Parameters

• None

Returns

• If the Promise fulfils, the fulfilment value is true is the file has write permissions

.isWritableSync() -> Promise

Synchronous version of .isWritable()

.isReadable() -> Promise

Parameters

• None

Returns

• If the Promise fulfils, the fulfilment value is true is the file has read permissions

.isReadableSync() -> Promise

Synchronous version of .isReadable()

.isExecutable() -> Promise

Parameters

• None

Returns

• If the Promise fulfils, the fulfilment value is true is the file is executable

.isExecutableSync() -> Promise

Synchronous version of .isExecutable()

.getName() -> String

Parameters

• None

Returns

• pathname as a string associated with the object

Test

npm test

To generate a test coverage report:

npm run coverage

Contributing

• If you're unsure if a feature would make a good addition, you can always create an issue first.
• We aim for 100% test coverage. Please write tests for any new functionality or changes.
• Any API changes should be fully documented.
• Make sure your code meets our linting standards. Run npm run lint to check your code.
• Maintain the existing coding style. There are some settings in .jsbeautifyrc to help.
• Be mindful of others when making suggestions and/or code reviewing.