fs-magic

💾 An extended, promisified fs drop-in-replacement for Node.js >=7.6

Showing:

Popularity

Downloads/wk

454

GitHub Stars

1

Maintenance

Last Commit

6mos ago

Contributors

2

Package

Dependencies

2

License

MIT

Type Definitions

Tree-Shakeable

No?

Categories

Readme

Build Status

fs-magic

An extended, promisified fs drop-in-replacement for Node.js >=7.6

Features

  • All asynchronous fs functions are and converted into promises with async-magic
  • Lot of extended functions are added
  • Designed to run with the pure power of native Promise, await and async function
  • No backward compatibility layer
  • OS Support for POSIX and Win Platforms (as of v1.3.0)
  • Streams, Streams, Streams - all file operations are stream-based!

Addons

  • copy Just copy a file (stream based)
  • bulkCopy Copy multiple files/directories in once
  • mkdirp Create directories recursivly
  • scandir List all files + directories of given directory recursivly
  • rmrf Removes all files of a given directory recursivly
  • exists Custom exists function to test file existence
  • isFile Check if item is a file
  • isDirectory Check if item is a directory
  • isSymlink Check if item is a symlink
  • isSocket Check if item is a socket
  • isFileOfType Check if item is of specific type
  • FileInputStream Open a new fileReadStream
  • FileOutputStream Write stream to destination file
  • untar Extracting .tar archives using tar-stream
  • untgz Extracting gzip compressed .tar archives
  • gzip Compress a file
  • gunzip Decompress a file
  • sha1file SHA1 File Checksum
  • sha256file SHA256 File Checksum
  • sha384file SHA384 File Checksum
  • sha512file SHA512 File Checksum
  • md5file MD5 File Checksum
  • checksum Generic File Checksum
  • statx Silent stat (returns false in case of ENOENT)

Promisified FS API

The following asynchronous fs methods are promisified and exposed within the fs-magic object. All synchronous functions are ignored because there is no need for them anymore - use await!

  • access
  • appendFile
  • chmod
  • chown
  • close
  • fchmod
  • fchown
  • fdatasync
  • fstat
  • fsync
  • ftruncate
  • futimes
  • lchown
  • link
  • lstat
  • mkdir
  • mkdtemp
  • open
  • read
  • readFile
  • readdir
  • readlink
  • realpath
  • rename
  • rmdir
  • stat
  • symlink
  • truncate
  • unlink
  • utimes
  • write
  • writeFile

General Usage

const _fsm = require('fs-magic');

// wraper 
(async function(){
    // get stats
    const stats= await _fsm.fstat('myfile.js');

    // does the file exists ?
    console.log(await _fsm.exists('myfile.js'));

    // copy a file, set chmod to 0640
    await _fsm.copy('test1.js', 'test2.js', 0o640);

    // create directory stucture at once
    await _fsm.mkdirp('my/custom/dir/1/2/3', 0o777, true);

    // use fs methods
    await _fsm.rmdir('mydir');
})();

fs-magic::copy

Description: Copy a single file

Syntax: copy(sourcefile:string, destinationfile:string, mode:int=null)

Example:

// copy a file, set chmod to 0640
await _fsm.copy('test1.js', 'test2.js', 0o640);

fs-magic::bulkCopy

Description: Copy multiple files at once

Syntax: bulkCopy(srcset:Array, createDestinationDirs:boolean=true, defaultFilemode:int=0o750, defaultDirmode:int=0o777)

Example:

// list of files to copy
const srcset = [
    ['source/file1.js', 'destination/subdir/file1.js', 0o644],
    ['source/file2.js', 'destination/subdir/file2.js', 0o644],
    ['source/file3.js', 'destination/subdir/x/file3.js', 0o644],
    ['source/file4.js', 'destination/subdir/x/file4.js', 0o644],
];

// copy files + create destination directories
await _fsm.bulkCopy(srcset, true);

fs-magic::mkdirp

Description: Create a directories recusivly

Syntax: mkdirp(directory:string, mode:int=0o777, recursive:boolean=false)

Example:

// create directory stucture at once
await _fsm.mkdirp('my/custom/dir/1/2/3', 0o777, true);

fs-magic::scandir

Description: List all files + directories of given directory recursivly (optional)

Syntax: scandir(directory:string, recursive:boolean=true, absolutePaths:boolean=false)

Example:

// get file + directory list of all files. Use absolute output paths
const [files, dirs] = await _fs.scandir('project/modules', true, true);

fs-magic::rmrf

Description: Removes all files of a given directory recursivly

Syntax: rmrf(directory:string)

Note: For security reasons, this function does not accept the file system root / or a directory within it like /etc as input

Example:

// remove a project folder
await _fs.rmrf('projects/js1');

fs-magic::exists

Description: Check if a file/directory/link exists

Syntax: exists(filedir:string)

Example:

// does the file exists ?
console.log(await _fsm.exists('myfile.js'));

fs-magic::isFile

Description: Check if a item is of type file

Syntax: isFile(filesystemItem:string)

Example:

// is a file ?
console.log(await _fsm.isFile('myfile.js'));

fs-magic::isDirectory

Description: Check if a item is of type directory

Syntax: isDirectory(filesystemItem:string)

Example:

// is a directory ?
console.log(await _fsm.isDirectory('/var/log'));

fs-magic::isSocket

Description: Check if a item is of type socket

Syntax: isSocket(filesystemItem:string)

Example:

// is a socket ?
console.log(await _fsm.isSocket('/var/run/phpfpm.sock'));

Description: Check if a item is of type symlink

Syntax: isSymlink(filesystemItem:string)

Example:

// is a symlink ?
console.log(await _fsm.isSymlink('/etc/motd'));

fs-magic::isFileOfType

Description: Check if a item is of specific type

Syntax: isFileOfType(filename:string, condition:function)

Example:

// check if node is socket
async function isSocket(filename){
    return await _fsm.isFileOfType(filename, (stats) => stats.isSocket());
};

fs-magic::FileInputStream

Description: Open a fileStream for read

Syntax: FileInputStream(sourcefile:string)

Example:

const _fsm = require('fs-magic');

// copy source file to destination (override it)
async function copy(src, dst, mode=null){
    // open file input stream
    const istream = await _fsm.FileOutputStream(src);

    // write stream content to file
    return _fsm.FileOutputStream(istream, dst, mode);
}

fs-magic::FileOutputStream

Description: Writes given stream into file

Syntax: FileOutputStream(readstream:stream, destinationFilename:string, mode:int=false)

Example:

const _fsm = require('fs-magic');
const _fetch = require('node-fetch');

// fetch remote content
const response = await _fetch('http://example.org/file.gz');

// write stream content to file
await _fsm.FileOutputStream(response.body, dst, mode);

fs-magic::untar

Description: Extracts contents of a .tar archive into given directory using tar-stream

Syntax: untar(inputstream:stream, destinationDirectory:string)

Example:

const _fetch = require('node-fetch');
const _fsm = require('fs-magic');

// fetch remote content
const response = await _fetch('http://example.org/file.tar');

// unpack into currrent directory
let items = await _fsm.untar(response.body, '.');

fs-magic::untgz

Description: Extracts contents of a gzip compressed .tar.gz archive into given directory using tar-stream

Syntax: untgz(inputstream:stream, destinationDirectory:string)

Example:

const _fetch = require('node-fetch');

// fetch remote content
const response = await _fetch('http://example.org/file.tar.gz');

// unpack into currrent directory
let items = await _fsm.untgz(response.body, '.');

fs-magic::gzip

Description: Compresses a file

Syntax: gzip(input:{string, stream}, destinationFilename:string)

Example:

// compress a file
await _fsm.gzip('./file.txt', './file.gz');

fs-magic::gunzip

Description: Decompresses a file

Syntax: gunzip(input:{string, stream}, destinationFilename:string)

Example:

// decompress a file
await _fsm.gunzip('./file.gz', './my-file.txt');
// fetch content
const response = await _fetch('http://example.org/file.gz');

// decompress a stream
await _fsm.gunzip(response.body, './file.txt');

fs-magic::checksum

Description: Generic File Checksum

Syntax: checksum(filename:string, algorithm:string='sha256', outputFormat:string='hex')

Example:

// sha384 checksum as base64
const sum = await _fsm.checksum('./file.txt', 'sha384', 'base64');

fs-magic::sha1file

Description: SHA1 File Checksum

Syntax: sha1file(filename:string, outputFormat:string='hex')

Example:

// sha1 checksum as hex
const sum = await _fsm.sha1file('./file.txt');

fs-magic::sha256file

Description: SHA256 File Checksum

Syntax: sha256file(filename:string, outputFormat:string='hex')

Example:

// sha256 checksum as hex
const sum = await _fsm.sha256file('./file.txt');

fs-magic::sha384file

Description: SHA384 File Checksum

Syntax: sha384file(filename:string, outputFormat:string='hex')

Example:

// sha384 checksum as buffer
const sum = await _fsm.sha384file('./file.txt', 'raw');

fs-magic::sha512file

Description: SHA512 File Checksum

Syntax: sha512file(filename:string, outputFormat:string='hex')

Example:

// sha512 checksum as base64
const sum = await _fsm.sha512file('./file.txt', 'base64');

fs-magic::statx

Description: Extended stat function. The function retuns false in case of ENOENT error (file not found)

Syntax: statx(filesystemItem:string)

Example:

// get file stats ?
const stats = await _fsm.statx('/var/log/unknown_file.log');

if (stats !== false){
    console.log(stats);
}

Any Questions ? Report a Bug ? Enhancements ?

Please open a new issue on GitHub

License

fs-magic is OpenSource and licensed under the Terms of The MIT License

Rate & Review

Great Documentation0
Easy to Use0
Performant0
Highly Customizable0
Bleeding Edge0
Responsive Maintainers0
Poor Documentation0
Hard to Use0
Slow0
Buggy0
Abandoned0
Unwelcoming Community0
100
No reviews found
Be the first to rate

Alternatives

No alternatives found

Tutorials

No tutorials found
Add a tutorial