Nocturnally Psychologizing Millipede

    fs-updater

    1.0.4 • Public • Published

    node-fs-updater

    Build Status Build status

    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 new FSUpdater object. The outputPath must be an empty directory or absent.

        It is important that the FSUpdater has exclusive access to the outputPath directory. FSUpdater.prototype.update calls rimraf, which can be dangerous in the presence of symlinks if unexpected changes have been made to the outputPath directory.

        options.canSymlink (boolean): If true, use symlinks; if false, copy files and use junctions. If null (default), auto-detect.

      • FSUpdater.prototype.update(directory): Update the outputPath directory to mirror the contents of the directory object, which is either a DirectoryIndex (an in-memory directory) or a Directory (a directory on disk).

        Important note: You may re-use File objects contained in the DirectoryIndex between repeated calls to .update() only if the file contents have not changed. Similarly, you may re-use DirectoryIndex and Directory objects 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.

      DirectoryIndex objects map file names (string primitives, without paths) to DirectoryIndex, Directory or File objects.

    • FSUpdater.Directory: A directory on disk. Think of this as an in-memory symlink to a directory.

      • new Directory(path): Create a new Directory object pointing to the directory at path.

      • Directory.prototype.valueOf(): Return the path.

      • Directory.prototype.getIndexSync(): Read the physical directory and return a DirectoryIndex. The DirectoryIndex object is cached between repeated calls to getIndexSync().

    • FSUpdater.File: Represents a file on disk. Think of this as an in-memory symlink.

      • new File(path): Create a new File object pointing to the file at path.

      • File.prototype.valueOf(): Return the path.

    • FSUpdater.makeFSObject(path): Return a File or Directory object, 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.

    Keywords

    Install

    npm i fs-updater

    DownloadsWeekly Downloads

    114,869

    Version

    1.0.4

    License

    MIT

    Unpacked Size

    14.8 kB

    Total Files

    5

    Last publish

    Collaborators

    • joliss