@zouloux/files

Files is a NodeJS file management helper with a deadly simple API, with the power of glob and fs-extra.

Usage no npm install needed!

<script type="module">
  import zoulouxFiles from 'https://cdn.skypack.dev/@zouloux/files';
</script>

README

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