Share your code. npm Orgs help your team discover, share, and reuse code. Create a free org »

    @zouloux/filespublic

    Files

    Files is a NodeJS file management helper with a deadly simple API, with the power of glob and fs-extra. Used in Solidify framework to handle files easily inside NodeJS.

    Philosophy

    This package is meant to do powerful files operations with a simple API, inside NodeJS applications. All methods will not throw anything if there is something wrong, so it will not break your running server.

    Targeted files which does not exists are just ignored, the same way JQuery target DOM nodes.

    Typescript

    By default, console logs are enabled to show you what this package does. A Typescript definition file is along the main Javasript file. It's all automatic if you use Typescript.

    Colors

    If you install the colors npm package, you'll have nice logs. Colors is not a dependency so the bundle stays light if you don't need colors.

    Documentation

    The best documentation are bellow usage and the Typescript definition file.

    Usage

    Target files and folders

    Target an existing file
    • Files.getFiles('path/to-my-file.txt')
    Target an existing folder
    • Files.getFolders('path/to-my-file')
    Target a file or a folder
    • Files.any('path/to-a-thing')
    Target a file or a folder which does not exist yet
    • Files.new('path/to-not-existing-file.txt')
    • Files.new('path/to-not-existing-folder')
    Target all files inside a folder
    • Files.getFiles('folder/*')
    Target all folders inside a folder
    • Files.getFolders('folder/*')
    Target all files and folders inside a folder
    • Files.any('folder/*')
    Target all images inside a folder
    • Files.getFiles('folder/*.+(jpg|jpeg|png|gif)')
    Target files that have an extension and are inside sub-folders of a folder
    • Files.getFiles('folder/*/*.*')
    Target all images wherever they are inside a sub-folder
    • Files.getFiles('folder/**/*.+(jpg|jpeg|png|gif)')
    Target all files wherever they are inside a sub-folder but do not target images
    • Files.getFiles('folder/**/*.!(jpg|jpeg|png|gif)')

    Browse files, folders and globs

    Targeted files
    • Files.getFiles('*').files

    Returns an array of targeted existing files as strings.

    Browse a list
    • Files.getFiles('*').all( file => console.log(file) )

    Will browse through existing files. Here, file is a string, not a Files object.

    Show glob used to target files or folders
    • Files.getFiles('*').glob

    Will return '*' as a string.

    • Files.new('not-existing-yet-file.txt').glob

    Will return 'not-existing-yet-file.txt' as a string.

    Check if a file exists
    • Files.getFiles('folder/*.txt).exists()

    Will return true if there is a txt file inside the folder. In fact, it will just check that files.length is more than 0.

    Manage files and folders

    Delete a file
    • Files.getFiles('my-file.txt').delete()

    Be careful with this method ! Will show deleted files in console if verbose is not disabled. If file does not exists, nothing will happen. Check files.length to now how many files are deleted.

    Delete files and folders inside a folder
    • Files.any('folder/*').delete()
    Move a file
    • Files.getFiles('my-existing-file.txt').moveTo('my-directory/')

    Note the trailing slash. This is important here otherwise the file will be renamed.

    Rename a file
    • Files.getFiles('my-existing-file.txt').moveTo('my-renamed-file.txt')

    No trailing slash here, so this is a renaming.

    Copy files into a new folder
    • Files.getFiles('input/files-*').copyTo('output/')
    Copy a file
    • Files.getFiles('file-a.txt').copyTo('file-b.txt')

    File content

    Read a file
    • Files.getFiles('my-file.txt').read()

    Will return file content as string

    Write a new file
    • Files.new('my-new-file.txt').write('hello !')
    Override an existing file
    • Files.getFiles('my-existing-file').write('hello !')
    Append a line to a file
    • Files.any('existing-or-not.log').append('new log line')
    Append content to a file without new line
    • Files.any('existing-or-not.log').append('new log part', false)
    Alter content of a file
    Files.getFiles('file.txt').alter( fileContent =>
    {
        // Replace words and save the file
        return fileContent.replace(/to-replace/, 'replaced');
    });
    Alter JSON content
    Files.getFiles('package.json').alterJSON( packageObject =>
    {
        packageObject.version = '0.1.0';
        packageObject.name = 'project-name';
        packageObject.author = 'author';
        return packageObject;
    });

    Combine !

    Rename several files
    Files.getFiles('input/*.jpg').all(
        (file, index) => Files.any( file ).moveTo(`output/${index}.jpg`)
    );

    TODO : Other examples.

    Verbose

    Enable or disable logs

    Files.setVerbose( true / false )

    Common issues with API

    Single files operations

    You will face problems if you try to do single files operation on multiple targeted files.

    Single file methods :

    • read
    • write
    • append
    • alter
    • alterJSON

    Those methods uses the glob (which is here '*') and not the files list, because the file may not exist yet.

    Example :

    • Files.getFiles('*').write('new file content')

    This will not work, because this method is not usable on several files at once.

    Multiple files to one file destination

    Methods :

    • copyTo
    • moveTo

    Those methods will target one file as destination if there is no trailing slash on destination path.

    Example : Copying several files to a single file

    • Files.getFiles('input/*').copyTo('output')

    Without trailing slash, only the last file targeted will be renamed as 'output' This is surely not what you want !

    Example : Moving several files to a single file

    • Files.getFiles('input/*').moveTo('output')

    Same as above

    install

    npm i @zouloux/files

    Downloadsweekly downloads

    6

    version

    0.6.0

    license

    MIT

    repository

    githubgithub

    last publish

    collaborators

    • avatar