Wondering what’s next for npm?Check out our public roadmap! »

    fs-magic

    2.1.3 • Public • Published

    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'));

    fs-magic::isSymlink

    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

    Install

    npm i fs-magic

    DownloadsWeekly Downloads

    467

    Version

    2.1.3

    License

    MIT

    Unpacked Size

    34 kB

    Total Files

    33

    Last publish

    Collaborators

    • avatar