Fast, rule based, file system transformations.
fs-transform is fairly straight forward, here's an example that
illustrates its core features:
// 1. Require the transformer classvar Transformer = ;// 2. Define an array of transform rulesvar rules =// 2.1 Copy filesaction: 'copy'source: 'source/file'dest: 'dest/file'// 2.2 Rename filesaction: 'rename'source: 'source/file'dest: 'dest/file'// 2.3 Exclude files from all subsequent searchesaction: 'exclude'files: 'A.txt' 'B.dmg'// 2.4 Search and Replace in Files// Note: this is applied globally to all files in the root directoryaction: 'replace'search: 'foo'replace: 'bar'// Use `exclude` property to define a set of files to exclude for this// search and replaceexclude:'another/file''a/dir/';// Execute the transformation on the given root directory (/root/path)Transformer;
fs-transform ships with three basic transform rule implementations, or
actions, they are:
copy- Copies a file
rename- Renames a file
replace- Performs a global search and replace (without regex)
If you need custom transformations, you can easily add them by using a
Transformer instance, like so:
var Transformer = ;// 1. Instantiate a new transformer with a root directory and rulesvar transformer = '/root/dir' rules;// 2. Add a custom rule action implementationtransformer;
The library is fairly intelligent about when and how to apply transforms. For instance, if you attempt to perform a rename but the source file doesn't exist the library will skip that rule and issue a warning.
After a transformation completes you can access all of the warnings generated by the library like so:
Below is a complete listing of the warnings that can be generated during a transform pass, by rule type:
Copy & Rename
Copy and rename perform the same checks and have the same behavior when issuing warnings. The warnings, in order of precedence, are:
'Missing source file.'- if the
rule.sourcewas not a string.
'Missing destination file.'- if the
rule.destwas not a string.
'Source file does not exist.'- if the given path to the source file did not exist on the filesystem.
'Overwriting destination file.'- if the given destination file exists and has been overwritten by the operation.
'Search pattern not specified.'- The given
rule.searchwas not a string.
'Replacement not specified.'- The given
rule.replacewas not a string.
'Excludes not supplied as an array, omitting.'- The given
rule.excludewas given, but it was not an array, and will thus be ignored.
'Search did not return any results.'- The given
rule.searchcould not be found in any file under the root directory.
'Unused exclude.'- An exclude was given that was never used to exclude a file from the search.
'All results were excluded.'- The given set of excludes ended up removing all of the files from the search results.
fs-transform performs all of its work in a temporary directory so it can
gracefully fail if an error occurs (leaving the root directory as it was before
the transforms were applied).
For further safety you can perform transformations in "dry run mode". Using it is rather simple:
fs-transform allows you to get a full recursive diff between the root
before transformations were applied, and the root after. Here's an example of
how to get the full text diff:
If you'd like to contribute to the library please abide by the following rules:
- Make sure to compile and read the jsdoc documentation (run
npm run doc, then open'doc/index.html' in a browser).
- Ensure all existing tests pass (run
- If you add new functionality, please add new tests and ensure 100% coverage.
- Make sure you handle all warning corner-cases (see the source for examples of how the existing actions)
- Update the jsdoc if you make changes to the any of the method behaviors.
- Please submit a PR that clearly defines the purpose of your contributions