JarCastingnode-fs-updater
Repeatedly write an in-memory directory tree to disk, with incremental updating.
Installation
This package requires Node version 6.0.0 or newer.
npm install --save fs-updater
Usage
let FSUpdater = require("fs-updater");
let { File, Directory, DirectoryIndex } = FSUpdater;
// output_dir must either be an empty directory or not exist at all
let fsUpdater = new FSUpdater('./output_dir')
Let's create the following directory structure, where -> indicates a symlink (or a copy on Windows):
output_dir
├── file -> /path/to/some/file
├── dir1/ -> /path/to/some/dir
└── dir2/
└── another_file -> /path/to/another/file
let dir = new DirectoryIndex([
['file', new File('/path/to/some/file')],
['dir1', new Directory('/path/to/some/dir')],
['dir2', new DirectoryIndex([
['another_file', new File('/path/to/another/file')]
])]
]);
// Write it to ./output_dir
fsUpdater.update(dir);
Now let's create an updated similar directory structure:
.
├── file -> /path/to/some/file
└── dir1/ -> /path/to/some/dir
dir = new DirectoryIndex([
['file', new File('/path/to/some/file')],
['dir1', new Directory('/path/to/some/dir')]
]);
// Now update output_dir incrementally
fsUpdater.update(dir);
Object re-use
It is recommended that you rebuild all your File, Directory and DirectoryIndex objects from scratch each time you call fsUpdater.update. If you re-use objects, the following rules apply:
First, do not mutate the objects that you pass into FSUpdater, or their sub-objects. That is, after calling fsUpdater.update(dir), you must no longer call dir.set(...).
Second, you may re-use unchanged File, Directory and DirectoryIndex objects only if you know that the file contents they point to recursively have not changed. This is typically only the case if they point into directories that you control, and if those directories in turn contain no symlinks to outside directories under the user's control.
For example, this is always OK:
let file = new String('/the/file');
fsUpdater.update(new DirectoryIndex([
['file', file]
]);
// Create new File object with identical path
file = new String('/the/file');
fsUpdater.update(new DirectoryIndex([
['file', file]
]);
But this is only OK if the contents of /the/file have not changed between calls to .update:
let file = new String('/the/file');
fsUpdater.update(new DirectoryIndex([
['file', file]
]);
// Re-use the File object
fsUpdater.update(new DirectoryIndex([
['file', file]
]);
Reference
-
FSUpdater: An object used to repeatedly update an output directory.-
new FSUpdater(outputPath, options): Create a newFSUpdaterobject. TheoutputPathmust be an empty directory or absent.It is important that the
FSUpdaterhas exclusive access to theoutputPathdirectory.FSUpdater.prototype.updatecalls rimraf, which can be dangerous in the presence of symlinks if unexpected changes have been made to theoutputPathdirectory.options.canSymlink(boolean): If true, use symlinks; if false, copy files and use junctions. Ifnull(default), auto-detect. -
FSUpdater.prototype.update(directory): Update theoutputPathdirectory to mirror the contents of thedirectoryobject, which is either aDirectoryIndex(an in-memory directory) or aDirectory(a directory on disk).Important note: You may re-use
Fileobjects contained in theDirectoryIndexbetween repeated calls to.update()only if the file contents have not changed. Similarly, you may re-useDirectoryIndexandDirectoryobjects only if no changes have been made to the directory or any files or subdirectories recursively, including those reachable through symlinks.
-
-
FSUpdater.DirectoryIndex: A subclass of Map representing an in-memory directory; see the documentation there.DirectoryIndexobjects map file names (stringprimitives, without paths) toDirectoryIndex,DirectoryorFileobjects. -
FSUpdater.Directory: A directory on disk. Think of this as an in-memory symlink to a directory.-
new Directory(path): Create a newDirectoryobject pointing to the directory atpath. -
Directory.prototype.valueOf(): Return thepath. -
Directory.prototype.getIndexSync(): Read the physical directory and return aDirectoryIndex. TheDirectoryIndexobject is cached between repeated calls togetIndexSync().
-
-
FSUpdater.File: Represents a file on disk. Think of this as an in-memory symlink.-
new File(path): Create a newFileobject pointing to the file atpath. -
File.prototype.valueOf(): Return thepath.
-
-
FSUpdater.makeFSObject(path): Return aFileorDirectoryobject, depending on the file type on disk. This function follows symlinks.
Contributing
Clone this repo and run the tests like so:
npm install
npm test
Issues and pull requests are welcome. If you change code, be sure to re-run npm test. Oftentimes it's useful to add or update tests as well.
