fs-transform
Fast, rule based, file system transformations.
Basic Usage
Using 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 files action: 'copy' source: 'source/file' dest: 'dest/file' // 2.2 Rename files action: 'rename' source: 'source/file' dest: 'dest/file' // 2.3 Exclude files from all subsequent searches action: 'exclude' files: 'A.txt' 'B.dmg' // 2.4 Search and Replace in Files // Note: this is applied globally to all files in the root directory action: 'replace' search: 'foo' replace: 'bar' // Use `exclude` property to define a set of files to exclude for this // search and replace exclude: 'another/file' 'a/dir/' ; // Execute the transformation on the given root directory (/root/path)Transformer;
Rule Actions
fs-transform
ships with three basic transform rule implementations, or
actions, they are:
copy
- Copies a filerename
- Renames a filereplace
- 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;
Warnings
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:
Transformer;
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 therule.source
was not a string.'Missing destination file.'
- if therule.dest
was 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.
Replace
'Search pattern not specified.'
- The givenrule.search
was not a string.'Replacement not specified.'
- The givenrule.replace
was not a string.'Excludes not supplied as an array, omitting.'
- The givenrule.exclude
was given, but it was not an array, and will thus be ignored.'Search did not return any results.'
- The givenrule.search
could 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.
Dry Runs
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:
Transformer;
Generating Diffs
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:
Transformer;
Contributing
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
npm test
). - 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
License
MIT