Repeatedly write an in-memory directory tree to disk, with incremental updating.
This package requires Node version 6.0.0 or newer.
npm install --save fs-updater
let FSUpdater = ;let File Directory DirectoryIndex = FSUpdater;// output_dir must either be an empty directory or not exist at alllet 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 ='file' '/path/to/some/file''dir1' '/path/to/some/dir''dir2''another_file' '/path/to/another/file';// Write it to ./output_dirfsUpdater;
Now let's create an updated similar directory structure:
. ├── file -> /path/to/some/file └── dir1/ -> /path/to/some/dir
dir ='file' '/path/to/some/file''dir1' '/path/to/some/dir';// Now update output_dir incrementallyfsUpdater;
It is recommended that you rebuild all your
DirectoryIndex objects from scratch each time you call
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
Second, you may re-use unchanged
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 = '/the/file';fsUpdater
But this is only OK if the contents of
/the/file have not changed between
let file = '/the/file';fsUpdater
FSUpdater: An object used to repeatedly update an output directory.
new FSUpdater(outputPath, options): Create a new
outputPathmust be an empty directory or absent.
It is important that the
FSUpdaterhas exclusive access to the
FSUpdater.prototype.updatecalls rimraf, which can be dangerous in the presence of symlinks if unexpected changes have been made to the
options.canSymlink(boolean): If true, use symlinks; if false, copy files and use junctions. If
FSUpdater.prototype.update(directory): Update the
outputPathdirectory to mirror the contents of the
directoryobject, which is either a
DirectoryIndex(an in-memory directory) or a
Directory(a directory on disk).
Important note: You may re-use
Fileobjects contained in the
DirectoryIndexbetween repeated calls to
.update()only if the file contents have not changed. Similarly, you may re-use
Directoryobjects 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) to
FSUpdater.Directory: A directory on disk. Think of this as an in-memory symlink to a directory.
new Directory(path): Create a new
Directoryobject pointing to the directory at
Directory.prototype.valueOf(): Return the
Directory.prototype.getIndexSync(): Read the physical directory and return a
DirectoryIndexobject is cached between repeated calls to
FSUpdater.File: Represents a file on disk. Think of this as an in-memory symlink.
new File(path): Create a new
Fileobject pointing to the file at
File.prototype.valueOf(): Return the
FSUpdater.makeFSObject(path): Return a
Directoryobject, depending on the file type on disk. This function follows symlinks.
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.