file-assistant
v1.3.1
Published
This is a stable and tested file-system package to create, copy, move, merge and overwrite files and folders, to empty folders and to write, modify or append content to the files, according to the given [Array] or JSON structure instructions.
Downloads
99
Maintainers
Readme
Description
file-assistant
is a module that creates, copies or moves the folders and files into the specified path or modifies the files' content according to the given [Array] structure object
(or .json
file path) instructions.
- Any bugs found? Give me to know on [email protected] or on Github
The Idea
- Create the abstract
structure object
of the folders and files, that you want to create or use to modify the existing folders and files structure. - Pass your
structure object
as the argument throughfile-assistant
function - It will execute all the instructions (create, copy, move, remove, merge, modify, overwrite files and folders and overwrite or append content to the files).
Features
const fileAssistant = require('file-assistant');
The fileAssistant
contains 4 methods:
fileAssistant
to handle the folders and files due to thestructure object
[see below]fileAssistant.structurize
to automatically generate thestructure object
for the elements of the given folder path [see below]fileAssistant.compare
to compare the differences between two folders (which elements are extraneous, missing and already existing) [see below]fileAssistant.ensureDir
to create the folders chain recursively [see below]
List of contents:
- Common tips
- Installation
- Tests
- Usage
- Parameters
- Errors
Structure object
fileAssistant.structurize
methodfileAssistant.compare
methodfileAssistant.ensureDir
method- Samples
OMG list
If you are confused by the excess of the description, there is a list of common tips:
Files handling:
- I just want to create some empty files [tip]
- I just want to create some empty file (or replace the existing file with the new empty one) [tip]
- I want to copy the file and paste it in the destination folder [tip]
- I want to copy the file and paste it in the destination folder (or replace the file if it already exists there) [tip]
- I want to cut the file and paste it in the destination folder [tip]
- I want to cut the file and paste it in the destination folder (or replace the file if it already exists there) [tip]
- I want to append some extra content to the existing file [tip]
- I want to overwrite the content of the existing file with the new content [tip]
- I want to take the content from one file and append it to another file [tip]
- I want to take the content from one file and overwrite another file's content with it [tip]
Folders handling:
- I just want to create empty folder [tip]
- I want to create the folder with some files and subfolders [tip]
- I want to empty the existing folder [tip]
- I want to empty the existing folder and then add new files and folders there [tip]
- I want to add some extra files and folders to the existing folder [tip]
- I want to replace some files in the existing folder [tip]
- I want to copy the folder with its contents and paste it in the destination folder [tip]
- I want to copy the folder with its contents and paste it in the destination folder (or replace the folder with its all contents if it already exists there) [tip]
- I want to cut the folder with its contents and paste it in the destination folder [tip]
- I want to cut the folder with its contents and paste it in the destination folder (or replace the folder with its all contents if it already exists there) [tip]
- I want to copy only the missing files and subfolders from one folder to another [tip]
- I want to copy the missing files and subfolders from one folder to another (and replace the already existing files there) [tip]
Installation
npm install file-assistant
Tests
> git clone https://github.com/devrafalko/file-assistant
> cd file-assistant
> npm install
> npm test
# or
> npm test deep
Usage
fileAssistant(root,structure,done[,each])
const fileAssistant = require('file-assistant');
const root = './dist',
const structure = [
{file:'index.html'},
{file:'styles.css', copy:'./styles/main.css'}
];
fileAssistant(root, structure, done, each);
function done(o){
console.log(o.error);
console.log(o.files);
console.log(o.dirs);
}
function each(o){
console.log(o.success);
console.log(o.item);
console.log(o.relative);
console.log(o.from);
}
root
[String]
- It should indicate the [String] folder path where the elements specified in the
structure
object should be handled. - If the
root
directory does not exist, it is created. - If there is some problem with the
root
, the Error is passed throughdone
callback.
structure
[Array|String]
- The [Array]
structure
argument should contain the list of files and folders and specify the actions that should be undertaken for them in theroot
folder. [See below] - The [String]
structure
argument should indicate the path to the.json
file that contain the list of files and folders and specify the actions that should be undertaken for them in theroot
folder. [See below] - See how to create the valid
structure object
or just follow the instructions passed throughdone
callbackerror
property.
You can also generate the
structure object
(and.json
file containing that structure) for the chosen folder withfileAssistant.structurize
method.
done
[Function]
- This is the callback function
- It is fired once when all folders and files are (un)successfully created or if some error has occured.
- The one [Object] argument is passed through
done
callback function with the following properties:root
Returns the [String]root
path argument passed through the module functionerror
Returns [Error] if something went wrong and the continuation of creating folders and files was aborted, eg. if thestructure
argument is invalid. Otherwise returnsnull
. See also how the errors are handled.dirs
Returns the [Object] object of the following properties:success
[Array] list of the absolute paths of all created/copied/moved/merged/overwritten folders.warning
[Array] list of the absolute paths of all intentionally aborted actions on folders (eg. if the folder was not overwritten, as intended)failure
[Array] list of the absolute paths of all unsuccessful actions on folders (eg. if the folder was inaccessible)
files
Returns the [Object] object of the following properties:success
[Array] list of the absolute paths of all created/copied/moved/overwritten/modified files.warning
[Array] list of the absolute paths of all intentionally aborted actions on files (eg. if the file was not overwritten, as intended)failure
[Array] list of the absolute paths of all unsuccessful actions on files (eg. if the file was inaccessible)
unrecognized
Returns the [Object] object of the following properties:failure
[Array] list of the absolute paths of all elements that the access was denied for
each
[Function] (optional)
- This is the callback function
- It is fired for each file and folder separately when the action for the file or folder is (un)successfully done.
- The one [Object] argument is passed through
each
callback function with the following properties:success
Returns [String] message, about the successful action. Otherwise returnsnull
.
eg.'The given content was successfully appended to the "script.js" file.'
.warning
Returns [String] message, about the aborted or not-fully-done action. Otherwise returnsnull
.
eg.'The already existing folder "components/footer" could not be overwritten by the newly created folder, due to the "overwrite" property settings.'
.failure
Returns [String] message, about the failed action. Otherwise returnsnull
.
eg.'The item of the path "modules/locked.js" is inaccessible and could not be moved into the "dist/script.js" path.'
.item
Returns [String]'file'
for file element,'dir'
for folder element or'unrecognized'
when the access to the element was denied.action
Returns the [String] action undertaken:overwritten
Returns [Boolean]true
if the file or folder has been overwritten. Otherwise returnsfalse
.modified
Returns [Boolean]true
if thebeforeWrite
property was used and thefile
was created/overwritten with the modified content. Otherwise returnsfalse.
from
Returns the [String] path to the element from which the file, folder or content was copied, moved or merged (when the propertycopy
,move
,merge
orwriteFrom
was defined in thestructure object
). Returnsnull
if the file or folder was created or modified (when the propertycontents
,write
or none property was defined in thestructure object
).absolute
Returns [String] absolute path to the current element.relative
Returns [String] relative path to the current element.root
Returns the [String]root
path argument passed through the module function.
Handling errors
- The one and only rule that you have to respect is to keep the
done
callback function as a third parameter in thefileAssistant
module function execution, otherwise theTypeError
will be thrown. - Any other errors will be then passed through the
done
callback function, so your app would not collapse. - If you run the
fileAssistant
module function with an incorrectroot
orstructure
arguments, you are informed in thedone
callback function about that, so you can follow these instructions to create a validstructure object
. - Any failures of files and folders handling are passed through the
done
andeach
callback functions aswarning
andfailure
properties. - The failed action of one element does not abort the actions for subsequent files and folders. The
fileAssistant
module tries to execute as many actions as possible, then returns results indone
callback function (and each single time ineach
callback function as well).
Structure object
Comparison of structure object
and the final folders and files structure
Assuming that you want to generate the following folders and files structure in the ./dist
path:
dist
├ scripts
│ ├ index.js
│ └ ajax.js
├ styles
│ ├ css
│ │ ├ layout.css
│ │ └ media.css
│ └ scss
│ └ mixins.scss
└ templates
├ main.html
├ menubar.html
├ login.html
└ contact.html
use this javascript syntax:
const fileAssistant = require('file-assistant');
const destination = './dist';
const structure = [
{dir:'scripts', contents:[
{file:'index.js'},
{file:'ajax.js'}
]},
{dir:'styles', contents:[
{dir:'css', contents:[
{file:'layout.css'},
{file:'media.css'}
]},
{dir:'scss', contents:[
{file:'mixins.scss'}
]}
]},
{dir:'templates', contents:[
{file:'header.html'},
{file:'navbar.html'}
]}
];
fileAssistant(destination, structure, (done)=>{/*...*/}, (each)=>{/*...*/});
JSON structure object
The structure object
can be stored in the JSON file.
[
{"dir":"scripts", "contents":[
{"file":"index.js"},
{"file":"ajax.js"}
]}
]
and then loaded in the structure
parameter:
const fileAssistant = require('file-assistant');
const destination = './dist';
const structure = './templates/structure.json';
fileAssistant(destination, structure, (done)=>{/*...*/}, (each)=>{/*...*/});
or in the contents
property inside of the structure
object:
const fileAssistant = require('file-assistant');
const destination = './dist';
const structure = [
{dir:'styles'},
{dir:'scripts', contents:'./templates/structure.json'}
];
fileAssistant(destination, structure, (done)=>{/*...*/}, (each)=>{/*...*/});
or even loaded in another .json
file:
[
{"dir":"scripts", "contents":[
{"file":"index.js"},
{"file":"ajax.js"}
]},
{"dir":"scripts", "contents":"./templates/scripts.json"}
]
You can also generate the
structure object
(and.json
file containing that structure) for the chosen folder withfileAssistant.structurize
method.
structure object
Properties:
Each [Object] Item of [Array] scope can contain the following properties:
file
Type: [String]
Default: undefined
Description:
- Indicates the name (and extension) of new file, eg.
'index.html'
,'ajax.js'
. - If you want to overwrite the existing file with the new one, use
overwrite
property. - Each Item must contain at least either
file
ordir
property. Item cannot contain bothdir
andfile
property. They exclude each other. Usedir
to create folder orfile
to create a file. - Avoid using slashes in the value of
dir
andfile
properties. In order to create subfolders, usecontents
property. (See how thestructure object
tree should be built)
Sample:
{file:'style.css'}
It creates a newstyle.css
file with empty content in the specifiedroot
path.- See also the samples list
dir
Type: [String]
Default: undefined
Description:
- Indicates the name of new folder, eg.
'styles'
,'modules'
- If you want to overwrite the existing folder with the new one, use
overwrite
property. - Each Item must contain at least either
file
ordir
property. Item cannot contain bothdir
andfile
property. They exclude each other. Usedir
to create folder orfile
to create a file. - Avoid using slashes in the value of
dir
andfile
properties. In order to create subfolders, usecontents
property. (See how thestructure object
tree should be built)
Sample:
{dir:'prod'}
It creates a new emptyprod
folder in the specifiedroot
path.- See also the samples list
contents
content
is also valid
Type: [Array|String]
Default: undefined
Target: dir
Description:
- The
contents
property defines thedir
(local)structure object
, that should be created in thedir
folder. - The
contents
property can indicate the [Array] object that contains thestructure object
that should be created in the defineddir
folder. - The
contents
property can also indicate the [String] path to the.json
file that contains thestructure object
that should be created in the defineddir
folder. - If you want to overwrite the existing folder with the new one (and its
contents
elements), useoverwrite
property. - Item cannot contain
move
,copy
,merge
,contents
,write
andwriteFrom
properties at the same time. They exclude each other.
You can also generate the
structure object
(and.json
file containing that structure) for the chosen folder withfileAssistant.structurize
method.
move
Type: [String]
Default: undefined
Target: file
|dir
Description:
- When the
file
property is specified in the Item, themove
property indicates the path to the file that should be moved to the path of the definedfile
property. - When the
dir
property is specified in the Item, themove
property indicates the path to the folder that should be moved (with its all contents) to the path of the defineddir
property. - If you want to overwrite the existing file or folder by the
move
one, useoverwrite
property. - Mind, that the path value of the
move
property is not relative to theroot
. It is recommended to use the paths related to the__dirname
or the absolute paths. - Item cannot contain
move
,copy
,merge
,contents
,write
andwriteFrom
properties at the same time. They exclude each other.
Sample
{file:'style.css', move:'./dist/main.css'}
It cuts the./dist/main.css
file and pastes it into the specifiedroot
path asstyle.css
file.{dir:'prod', move:'./dist'}
It cuts thedist
folder with its all contents and pastes it into the specifiedroot
path asprod
folder.- See also the samples list
copy
Type: [String]
Default: undefined
Target: file
|dir
Description:
- When the
file
property is specified in the Item, thecopy
property indicates the path to the file that should be copied to the path of the definedfile
property. - When the
dir
property is specified in the Item, thecopy
property indicates the path to the folder that should be copied (with its all contents) to the path of the defineddir
property. - If you want to overwrite the existing file or folder by the
copy
one, useoverwrite
property. - Mind, that the path value of the
copy
property is not relative to theroot
path. It is recommended to use the paths related to the__dirname
or the absolute paths. - Item cannot contain
move
,copy
,merge
,contents
,write
andwriteFrom
properties at the same time. They exclude each other.
Sample:
{file:'style.css', copy:'./dist/main.css'}
It copies the./dist/main.css
file and pastes it into the specifiedroot
path asstyle.css
file.{dir:'prod', copy:'./dist'}
It copies adist
folder with its all contents and pastes it into the specifiedroot
path asprod
folder.- See also the samples list
merge
Type: [String]
Default: undefined
Target: dir
Description:
- It indicates the [String] path to the folder which contents should be merged with the contents of the existing
dir
folder. - If the
dir
folder does not exist, the contents are just copied to the path of the defineddir
property. - If you want to overwrite the existing files by the
merge
ones, useoverwrite
property. - Item cannot contain
move
,copy
,merge
,contents
,write
andwriteFrom
properties at the same time. They exclude each other.
Sample:
{dir:'prod', merge:'./dist'}
- It copies a
dist
folder with its all contents and pastes it into the specifiedroot
path asprod
folder. Ifprod
folder already exists, its contents are merged with the contents of./dist
folder. - See also the samples list
write
Type: [String]
Default: undefined
Target: file
Description:
- The
write
property indicates the [String] content that should be used as the content of the newfile
. - If you want to overwrite the already existing file's content rather than append this content, use
overwrite
property. - Item cannot contain
move
,copy
,merge
,contents
,write
andwriteFrom
properties at the same time. They exclude each other.
Sample:
{file:'style.css', write:'body{margin:0px}'}
It creates a newstyle.css
file in the specifiedroot
path with thebody{margin:0px}
content.- See also the samples list
writeFrom
writefrom
is also valid
Type: [String]
Default: undefined
Target: file
Description:
- The
data
property indicates the [String] path to the file, which content should be used as the content of the newfile
. - If you want to overwrite the already existing file's content rather than append this content, use
overwrite
property. - Item cannot contain
move
,copy
,merge
,contents
,write
andwriteFrom
properties at the same time. They exclude each other.
Sample:
{file:'style.css', writeFrom:'./dist/main.css'}
It creates a newstyle.css
file in the specifiedroot
path with the content read from the./dist/main.css
file.- See also the samples list
beforeWrite
beforewrite
is also valid
Type: [Function]
Default: undefined
Target: file
Description:
- This property allows to modify the content for the
file
before this file is created/overwritten. - This property can be used in combination with the following properties:
write
: the value content is taken and passed through thebeforeWrite
functionwriteFrom
,copy
,move
: the content is read from the file and passed through thebeforeWrite
function- Mind that if the
beforeWrite
property is used in combination withwrite
orwriteFrom
andoverwrite
:true
properties, the new modified content is appended to thefile
rather than overwrite the current content.
- If the [Function]
beforeWrite
is defined, this function is executed with the following arguments:- [0]
content
: It gives the access to the (utf8) content taken fromwrite
,writeFrom
,move
orcopy
- [1]
resolve
This is callback function. When the new content is already modified, callresolve
to continue the process of handling files and folder by thefile-assistant
package. Remember to pass [String|Buffer]modified
data throughresolve
callback function:resolve(modified)
, othwerwise the action will be failed for this file. - [2]
reject
This is callback function. If something went wrong with modifying the content and you want to abort the action of creating the file with the new modified content, callreject
callback function. Then theeach
callback will be called withfailure
message. The additional [String]message
can be passed throughreject
callback function. It will be appended to theeach
callbackfailure
message:reject(message)
- [0]
- The origin
write
,writeFrom
,move
orcopy
file's content is not affected by this function. The modified content is used only to modify thefile
content.
const fileAssistant = require('file-assistant');
const destination = './prod';
const structure = [
{file:'data.txt', writeFrom:'./dist/data.txt', beforeWrite:parseData}
];
fileAssistant(destination, structure, (done)=>{/*...*/}, (each)=>{/*...*/});
function parseData(getData, resolve, reject){
//getData is the utf-8 content taken from './dist/data.txt' file
if(getData.length>100) {
reject('The text is too long!');
} else {
const modifiedData = getData.toUpperCase();
resolve(modifiedData);
}
}
overwrite
Type: [Boolean]
Default: false
Target: file
|dir
Description: It is useful, if the file or folder that you are about to create, move, copy, merge or modify already exists in the specified path. If the file or folder does not exist, the effect will be the same regardless the overwrite
property is used with true
or false
value (or undefined).
- if
overwrite
istrue
, it removes the existing file or folder and creates the new one, according to thestructure
options - if
overwrite
isfalse
(default), it does not remove the existing file or folder, instead of that:
This is how it behaves in words of its syllable:
1. Assume that the style.css
file already exists in the destination root
path:
{file:'style.css', overwrite:true}
- It removes the existing
style.css
file and replaces it with the new emptystyle.css
file.
{file:'style.css', overwrite:false}
- The action for this existing file is aborted. The existing
style.css
file is not removed and the newstyle.css
is not created. - The
each
warning
property will warn you about aborted action and thesuccess
property will benull
.
{file:'style.css', copy:'./dist/main.css', overwrite:true}
- It removes the existing
style.css
file and replaces it with the copied./dist/main.css
file.
{file:'style.css', copy:'./dist/main.css', overwrite:false}
- The action for this existing file is aborted. The existing
style.css
file is not removed and the./dist/main.css
file is not copied/pasted. - The
each
warning
property will warn you about aborted action and thesuccess
property will benull
.
{file:'style.css', move:'./dist/main.css', overwrite:true}
- It removes the existing
style.css
file and replaces it with the cut./dist/main.css
file.
{file:'style.css', move:'./dist/main.css', overwrite:false}
- The action for this existing file is aborted. The existing
style.css
file is not removed and the./dist/main.css
file is not cut/pasted. - The
each
warning
property will warn you about aborted action and thesuccess
property will benull
.
{file:'style.css', write:'body{margin:0px}', overwrite:true}
- It replaces the content of the existing
style.css
file with the newbody{margin:0px}
content.
{file:'style.css', write:'body{margin:0px}', overwrite:false}
- It appends the new
body{margin:0px}
content at the end of the content of the existingstyle.css
file.
{file:'style.css', writeFrom:'./dist/main.css', overwrite:true}
- It replaces the content of the existing
style.css
file with the content read from the./dist/main.css
file.
{file:'style.css', writeFrom:'./dist/main.css', overwrite:false}
- It appends the content read from the
./dist/main.css
file at the end of the content of the existingstyle.css
file.
2. Assume that the prod
folder already exists in the destination root
path:
{dir:'prod', overwrite:true}
- It removes the existing
prod
folder and replaces it with the new emptyprod
folder. - If the
contents
property is defined in the Item with subfolders and subfiles specified, it also creates all of them inside of the newprod
folder.
{dir:'prod', overwrite:false}
- The action for this existing folder is aborted. The existing
prod
folder is not removed and the newprod
folder is not created. - The
each
warning
property will warn you about aborted action and thesuccess
property will benull
. - If the
contents
property is defined in the Item with subfolders and subfiles specified, the action for them is undertaken according to their ownoverwrite
setting.
In the following sample, if the prod
folder already exists, it is not removed and replaced by the new prod
folder with all its contents (it keeps its all current contents). The styles.css
and index.html
have their own overwrite
property. If the styles.css
file already exists, it is replaced by the new styles.css
file. If the index.html
file already exists, it is not replaced by the new index.html
file.
const structure = [
{dir:'prod', overwrite:false, contents:[
{file:'styles.css', overwrite:true},
{file:'index.html', overwrite:false}
]}
];
{dir:'prod', copy:'./dist', overwrite:true}
- It removes the existing
prod
folder and replaces it with the copieddist
folder with all its contents.
{dir:'prod', copy:'./dist', overwrite:false}
- The action for this existing folder is aborted. The existing
prod
folder is not removed and thedist
folder is not copied/pasted. - The
each
warning
property will warn you about aborted action and thesuccess
property will benull
.
{dir:'prod', move:'./dist', overwrite:true}
- It removes the existing
prod
folder, and replaces it by the cutdist
folder with all its contents.
{dir:'prod', move:'./dist', overwrite:false}
- The action for this existing folder is aborted. The existing
prod
folder is not removed and thedist
folder is not cut/pasted. - The
each
warning
property will warn you about aborted action and thesuccess
property will benull
.
{dir:'prod', merge:'./dist', overwrite:true}
- The following steps are taken:
- it compares the structure of
dist
folder and the structure ofprod
folder - all the files and folders that do not exist in the
prod
folder are copied fromdist
folder into it - all the folders that already exist in the
prod
folder are not removed and are not replaced by theirdist
equivalents - only the files that already exist in the
prod
folder (and all its subfolders) are removed and are replaced by theirdist
equivalents (of the same relative path).
- it compares the structure of
#The './dist' folder to be merged:
dist
├ scripts
│ ├ index.js
│ └ ajax.js
└ styles
└ sayout.css
#Already existed 'prod' folder:
prod
├ scripts
│ ├ index.js
│ └ utils.js
└ templates
└ login.html
#After merge process:
prod
├ scripts
│ ├ index.js //this file had already existed and was replaced by './dist/scripts/index.js'
│ ├ ajax.js
│ └ utils.js
├ templates
│ └ login.html
└ styles
└ sayout.css
{dir:'prod', merge:'./dist', overwrite:false}
- The following steps are taken:
- it compares the structure of
dist
folder and the structure ofprod
folder - all the files and folders that do not exist in the
prod
folder are copied fromdist
folder into it - all the folders that already exist in the
prod
folder are not removed and are not replaced by theirdist
equivalents - the files that already exist in the
prod
folder (and all its subfolders) are not removed and are not replaced by theirdist
equivalents (of the same relative path). Instead of that:
- it compares the structure of
#The './dist' folder to be merged:
dist
├ scripts
│ ├ index.js
│ └ ajax.js
└ styles
└ sayout.css
#Already existed 'prod' folder:
prod
├ scripts
│ ├ index.js
│ └ utils.js
└ templates
└ login.html
#After merge process:
prod
├ scripts
│ ├ index.js //this file had already existed and the action was aborted
│ ├ ajax.js
│ └ utils.js
├ templates
│ └ login.html
└ styles
└ sayout.css
fileAssistant.structurize(path[,json],callback)
Description
It converts the given path
folder's contents into the abstract [Array] structure object
representation of it. You can for example modify the returned object and/or use it as the structure
parameter, to create the files and folders due to this returned structure object
.
Parameters
path
[String]
- It indicates the [String] path to the folder, which content will be structurized into the [Array]
structure object
representation.
json
[String] (optional)
- If specified, it should indicate the [String] path, where the
.json
file with the returned [Array]structure object
should be created. - If the specified path does not exist, it is created.
- If the specified file name extension is omitted or is not
.json
, the correct extension is automatically appended. - If the specified file already exists, it is replaced by the new one.
callback
[Function]
- The
callback
function is executed after the operation is done. - The two arguments are passed through the
callback
function:[0]
[Error] object, if thepath
orjson
paths are invalid, inaccessible, etc. Otherwise it returnsnull
.[1]
[Array]structure object
representing the structure of the givenpath
folder.
The ./dist folder to be structurized:
dist
├ scripts
│ ├ index.js
│ └ ajax.js
└ styles
└ layout.css
The returned [Array] object representation of the given ./dist
folder's contents:
const folder = './dist';
const json = './dist/structure.json';
fileAssistant.structurize(folder,json,(err,data)=>{
console.log(data);
/*
[
{dir:'scripts', contents:[
{file:'index.js'},
{file:'ajax.js'}
]},
{dir:'styles', contents:[
{file:'layout.css'}
]}
]
*/
});
fileAssistant.compare(model,compared,[config,]callback)
Description
It compares the paths of model
and compared
folders contents and returns the information about the differences.
According to the given information, you can generate the
structure object
and use it to create, copy, move or modify files or folders.
Parameters
model
[String]
- It indicates the [String] path to the folder, which contents will be used as the model, that
compared
folder should match.
compared
[String]
- It indicates the [String] path to the folder, which elements are compared with the elements of the
model
folder.
config
[Object]
- if omitted, the parameters are set to their default values; All the elements of all levels are compared.
- You can configure the
compare
method with the following [Object]config
's properties:depth
[Number|null] (default:null)
It indicates how deep thecompare
function should explore the folders in the givenmodel
andcompared
directories.
If set tonull
(default) - it compares all subfiles and subfolders of all levels of themodel
andcompared
directories.
If set to 1 - it compares only the one level ofmodel
andcompared
elements; eg../styles
,./index.html
.
If set to 2 - it compares two levels ofmodel
andcompared
elements; eg../styles/css
,./scripts/ajax.js
.
etc.exclude
[Array|String] (default:[])
It indicates the folders' and files' paths that should be ignored and not compared.
If the folder is indicated, neither the folder nor its contents will be compared.
When [String], it can indicate the one path to ignore, eg"./bin"
.
When [Array], it can indicate more than one path to ignore, eg.["./node_modules", "./bin"]
.
The given paths must be relative to themodel
andcompared
paths, otherwise they will be not recognized.
You can ignore needless paths, eg.'./node_modules'
or'./.git'
to make thecompare
module faster.
callback
[Function]
- The
callback
function is executed after the operation is done. - The two arguments are passed through the
callback
function:[0]
[Error] object, if themodel
orcompared
paths are invalid, inaccessible, etc. Otherwise it returnsnull
.[1]
[Object] object with the following properties:model
Returns the [String] absolute path to themodel
foldercompared
Returns the [String] absolute path to thecompared
folderdirs
missing
Returns the [Array] list of the relative paths to the folders that exist in themodel
folder, but do not exist in thecompared
folderexisting
Returns the [Array] list of the relative paths to the folders that exist both in themodel
folder andcompared
folderextraneous
Returns the [Array] list of the relative paths to the folders that exist in thecompared
folder, but do not exist in themodel
folder
files
missing
Returns the [Array] list of the relative paths to the files that exist in themodel
folder, but do not exist in thecompared
folderexisting
Returns the [Array] list of the relative paths to the files that exist both in themodel
folder andcompared
folderextraneous
Returns the [Array] list of the relative paths to the files that exist in thecompared
folder, but do not exist in themodel
folder
inaccessible
Returns the [Array] list of all elements that the access was denied for.
const model = './dist';
const compared = './prod';
fileAssistant.compare(model,compared,(err,data)=>{
console.log(err);
console.log(data.dirs.missing);
console.log(data.files.extraneous);
});
fileAssistant.ensureDir(path,callback)
Description
It creates the folders chain recursively.
If the folder (or its subfolder) already exists it is neither removed nor overwritten.
Parameters
path
[String]
- It defines the [String] path of the folder, that should be created
- The path can be either absolute or relative
- The path may specify the one folder or the chain of the folders:
'./dist'
'./dist/modules/es6/libs'
callback
[String]
- It is called when the folder(s) are created.
- It returns one error argument:
null
if the folder(s) have been successfully created, otherwise [Error]
Samples
Create empty file, but prevent creating the file, if it already exists
const fileAssistant = require('file-assistant');
const destination = './prod';
const structure = [
{file:'styles.css', overwrite:false},
{file:'index.html'} //overwrite:false is default, it can be omitted
];
fileAssistant(destination, structure, (done)=>{/*...*/}, (each)=>{/*...*/});
Overwrite the existing file with the new (empty) one
const fileAssistant = require('file-assistant');
const destination = './prod';
const structure = [
{file:'styles.css', overwrite:true},
{file:'index.html', overwrite:true}
];
fileAssistant(destination, structure, (done)=>{/*...*/}, (each)=>{/*...*/});
Copy the file, but prevent copying the file, if it already exists
const fileAssistant = require('file-assistant');
const destination = './prod';
const structure = [
{file:'readme.md', copy:'./templates/docs.txt', overwrite:false}
{file:'LICENSE', copy:'./templates/mit-license.txt'} //overwrite:false is default, it can be omitted
];
fileAssistant(destination, structure, (done)=>{/*...*/}, (each)=>{/*...*/});
Overwrite the existing file with the copied one
const fileAssistant = require('file-assistant');
const destination = './prod';
const structure = [
{file:'styles.css', overwrite:true},
{file:'index.html', overwrite:true}
];
fileAssistant(destination, structure, (done)=>{/*...*/}, (each)=>{/*...*/});
Move the file, but prevent moving the file, if it already exists
const fileAssistant = require('file-assistant');
const destination = './prod';
const structure = [
{file:'styles.css', move:'./dist/bundled.css', overwrite:false},
{file:'main.js', move:'./dist/bundled.js'} //overwrite:false is default, it can be omitted
];
fileAssistant(destination, structure, (done)=>{/*...*/}, (each)=>{/*...*/});
Overwrite the existing file with the moved one
const fileAssistant = require('file-assistant');
const destination = './prod';
const structure = [
{file:'styles.css', move:'./dist/bundled.css', overwrite:true},
{file:'main.js', move:'./dist/bundled.js', overwrite:true}
];
fileAssistant(destination, structure, (done)=>{/*...*/}, (each)=>{/*...*/});
Create the new file with the given content or append a new content to the existing file
const fileAssistant = require('file-assistant');
const destination = './prod';
const structure = [
{file:'styles.css', write:'body:{box-sizing:border-box}', overwrite:false}
];
fileAssistant(destination, structure, (done)=>{/*...*/}, (each)=>{/*...*/});
Create the new file with the given content or overwrite the existing file's content with the given one
const fileAssistant = require('file-assistant');
const destination = './prod';
const htmlTemplate =
`<html>
<head></head>
<body></body>
</html>`;
const structure = [
{file:'index.html', write:htmlTemplate, overwrite:true}
];
fileAssistant(destination, structure, (done)=>{/*...*/}, (each)=>{/*...*/});
Append a new content given from another file to the existing file
const fileAssistant = require('file-assistant');
const destination = './prod';
const structure = [
{file:'styles.css', writeFrom:'./templates/reset.css', overwrite:false}
];
fileAssistant(destination, structure, (done)=>{/*...*/}, (each)=>{/*...*/});
Overwrite the existing file's content with the new one, given from another file
const fileAssistant = require('file-assistant');
const destination = './prod';
const structure = [
{file:'index.html', writeFrom:'./templates/html-template.html', overwrite:true}
];
fileAssistant(destination, structure, (done)=>{/*...*/}, (each)=>{/*...*/});
Create empty folder
const fileAssistant = require('file-assistant');
const destination = './prod';
const structure = [
{dir:'lib', overwrite:false},
{dir:'src'} //overwrite:false is default, it can be omitted
];
fileAssistant(destination, structure, (done)=>{/*...*/}, (each)=>{/*...*/});
Create folder with contents
const fileAssistant = require('file-assistant');
const destination = './prod';
const structure = [
{dir:'lib', overwrite:false},
{dir:'src', contents:[
{dir:'styles'},
{dir:'scripts'},
{dir:'tests'}
]} //overwrite:false is default, it can be omitted
];
fileAssistant(destination, structure, (done)=>{/*...*/}, (each)=>{/*...*/});
Replace the existing folder with the new empty folder
const fileAssistant = require('file-assistant');
const destination = './prod';
const structure = [
{dir:'temp', overwrite:true}
];
fileAssistant(destination, structure, (done)=>{/*...*/}, (each)=>{/*...*/});
Replace the existing folder with the new folder with some contents
const fileAssistant = require('file-assistant');
const destination = './prod';
const structure = [
{dir:'src', contents:[
{dir:'styles', contents:[
{file:'styles.css'}
]},
{dir:'scripts'},
{dir:'tests'}
], overwrite:true}
];
fileAssistant(destination, structure, (done)=>{/*...*/}, (each)=>{/*...*/});
Add some files to the existing folder, but prevent replacing the existing files
const fileAssistant = require('file-assistant');
const destination = './prod';
const structure = [
{dir:'styles', contents:[
{file:'styles.css', overwrite:false},
{file:'reset.css', overwrite:false}
]},
], overwrite:false}
];
fileAssistant(destination, structure, (done)=>{/*...*/}, (each)=>{/*...*/});
Add some files to the existing folder and replace already existing files there
const fileAssistant = require('file-assistant');
const destination = './prod';
const structure = [
{dir:'styles', contents:[
{file:'styles.css', overwrite:true},
{file:'reset.css', overwrite:true}
]},
], overwrite:false}
];
fileAssistant(destination, structure, (done)=>{/*...*/}, (each)=>{/*...*/});
Copy the folder with its contents, but prevent replacing the existing folder
const fileAssistant = require('file-assistant');
const destination = './prod';
const structure = [
{dir:'styles', copy:'./dist/styles', overwrite:false}
];
fileAssistant(destination, structure, (done)=>{/*...*/}, (each)=>{/*...*/});
Copy the folder and replace the existing folder with all its contents
const fileAssistant = require('file-assistant');
const destination = './prod';
const structure = [
{dir:'styles', copy:'./dist/styles', overwrite:true}
];
fileAssistant(destination, structure, (done)=>{/*...*/}, (each)=>{/*...*/});
Move the folder with its contents, but prevent replacing the existing folder
const fileAssistant = require('file-assistant');
const destination = './prod';
const structure = [
{dir:'styles', move:'./dist/styles', overwrite:false}
];
fileAssistant(destination, structure, (done)=>{/*...*/}, (each)=>{/*...*/});
Move the folder and replace the existing folder with all its contents
const fileAssistant = require('file-assistant');
const destination = './prod';
const structure = [
{dir:'styles', move:'./dist/styles', overwrite:true}
];
fileAssistant(destination, structure, (done)=>{/*...*/}, (each)=>{/*...*/});
Merge the files, but prevent replacing the existing files
const fileAssistant = require('file-assistant');
const destination = './dist';
const structure = [
{dir:'lib', merge:'./project/modules', overwrite:false}
];
fileAssistant(destination, structure, (done)=>{/*...*/}, (each)=>{/*...*/});
Merge the files and replace the already existing files
const fileAssistant = require('file-assistant');
const destination = './project';
const structure = [
{dir:'prod', merge:'./project/dist', overwrite:true}
];
fileAssistant(destination, structure, (done)=>{/*...*/}, (each)=>{/*...*/});