A virtual filesystem that works like fs

• Introduction
• Currently implemented
• Creating a new VFS
• API
  • vfs.base
    • (static) NODE_TYPES
    • (static) capabilities
  • vfs.api
    • Constructor
    • use(pluginClass, pluginOptions)
    • stat(path, options, callback)
    • mkdir(path, mode, callback)
    • init()
    • end()
    • sync(options)
    • createReadStream(path, options)
    • createWriteStream(path, options)
    • readFile(path, options, callback)
    • writeFile(path, data, options, callback)
    • unlink(path, options, cb)
    • mkdirRecursive(path, cb)
    • copyFile(from, to, options, cb)
    • getdir(dir, options, callback)
    • find(path, callback)
    • du(path, callback)
    • readdir(path, options, callback)
    • nextFile(path, options, callback)
    • Events
      • Events: ready
      • Events: sync
      • Events: error
      • Events: end
  • vfs.Node
    • Constructor
    • Properties
      • vfs
      • path
      • mtime
      • mode
      • mimetype
      • %root
      • %dir
      • %base
      • %ext
      • %name
  • CompressionUtils
    • (static) hasDecompressor(format)
    • (static) getDecompressor(format)
  • PathUtils
    • (static) removeTrailingSep(path)
    • (static) removeLeadingSep(path)
  • StreamUtils
    • (static) createReadableWrapper()
    • ReadableWrapper
      • wrapStream(stream)

A virtual file system is an interface to some data with the semantics of a file system (directory hierarchy, files, metadata) and the mechanics of the Node.JS fs module.

• file - a VFS that mirrors the local filesystem
• zip - a VFS on top of ZIP content
• tar - a VFS on top of tarball content (compressions: gzip, bzip2, xz)

                    zip  file tar  ar   sftp 
stat                 X    X    X    X    X   
mkdir                -    X    -    -    -   
createReadStream     X    X    X    X    X   
createWriteStream    -    X    -    -    -   
readFile             X    X    X    X    X   
writeFile            X    X    -    -    -   
unlink               X    X    -    -    -   
mkdirRecursive       -    X    -    -    -   
copyFile             X    X    -    -    -   
getdir               X    X    X    X    X   
find                 X    X    X    X    X   
du                   X    X    X    X    X   
readdir              X    X    X    X    X   
nextFile             -    -    -    -    -   
rmdir                -    X    -    -    -   

• Subclass vfs.base
• Override
  • _stat
  • _readdir

Base class of all vfs

Provides default implementations for some api methods.

Types a vfs.Node can have.

Currently:

• Directory
• SymbolicLink

Lists the capabilities of a VFS, i.e. which methods are available

• @return {Set} set of available methods

Interface of all vfs

Enable a plugin

Get metadata about a node in the vfs.

• @param {String} path absolute path to the file
• @param {Function} callback error or {@link Node}

Create a directory

• @param {string} path absolute path to the folder
• @param {errorCallback} cb
• @see fs#mkdir

Initialize the filesystem.

By default only calls #sync and emits ready on sync}

Un-initialize the filesystem, e.g. disconnect a client.

Sync the filesystem.

See fs.createReadStream Create a ReadableStream from a file @param {string} path absolute path to the file

Create a WritableStream to a file

See fs.createWriteStream. @param {string} path absolute path to the file @callback readFileCallback @param {Error} err @param {Buffer|String} data the file data as a buffer or stream

@see {@link https://nodejs.org/api/fs.html#fs_fs_readfile_file_options_callback fs#readFile}

• @param {string} path absolute path to the file
• @param {object} options
• @param {object} options.encoding=undefined Encoding of the data. Setting this will return a String
• @param {readFileCallback} cb

@see {@link https://nodejs.org/api/fs.html#fs_fs_writefile_file_data_options_callback fs#writeFile}

• @param {string} path absolute path to the file
• @param {object} options
• @param {function(err)} cb

@param {string} path absolute path to the folder @param {errorCallback} cb @see {@link https://nodejs.org/api/fs.html#fs_fs_unlink_path_callback fs#unlink}

mkdir -p

@param {string} path absolute path to the folder to create @param {errorCallback} cb

Copy file, possibly across different VFS.

@param {string|Node} from @param {string|Node} to @param {errorCallback} cb

Get directory contents as {@link Node} objects. Essentially a shortcut for {@link api#stat} applied to {@link api#getdir}.

• @param {string} dir
• @param {object} options
  • @param {Node} options.parent=null
  • @param {string} options.sortBy=null
  • @param {number} options.sortDir=-1
• @return {function(err, nodes)} cb

List recursive folder contents @param path string path @param cb function (err, files)

Recursive size of a node. @param {string} path absolute path to the file

List the nodes in a folder. @see fs#readdir.

• @param {string} path absolute path to the folder
• @param {function(err, filenames)} callback
  • @param {Error} err
  • @param {array} filenames list of relative path names in this folder

Find the next file starting from path

• @param {string} path absolute path to the file
• @param {object} options
  • @param {boolean} delta Offset. Set to negative to get previous file. Default: +1
  • @param {function(path)} whitelistFn Consider only paths for which this fn returns true
  • @param {function(path)} blacklistFn Discard all paths for which this fn returns true
  • @param {String} wrapStrategy What to do when hitting a directory boundary
    • throw Throw an error when files are exhausted
    • wrap Jump from beginning to end / vice versa (Default)
    • jump Jump to first file in next folder / last file in previous folder
• @param {function(err, nextPath)} callback
  • @param {Error} err
  • @param {array} filenames list of relative path names in this folder

new fsvfs.Node({path: "/...", vfs: vfsInstance})

Class representing file metadata

• @param {object} options Options that will be passed
• @param {string} options.path Absolute path to the node
• @param {fsvfs} options.vfs Instance of a {@link fsvfs}

Parent vfs instance, e.g. a file

Absolute, normalized path of the node within the vfs

Date of last modification

MIME type of this node

See path.parse(path)

See path.parse(path)

See path.parse(path)

See path.parse(path)

See path.parse(path)

Whether a decompression format is supported

Instantiate a decompression stream @memberof util

Enhancing path

const PathUtils = require('@kba/vfs-util-path')
PathUtils.removeTrailingSep('/foo/') // '/foo'
// or
const {removeTrailingSep} = require('@kba/vfs-util-path')
removeTrailingSep('/foo/') // '/foo'

Remove trailing separators (slashes) from path. @param {boolean} keepRoot Whether to remove or keep a single root slash

Remove leading separators (slashes) from path.

Wraps another ReadableStream to allow synchronously returning a stream that will become readable only later.

const {createReadableWrapper} = require('@kba/vfs-util-stream')
const readable = createReadableWrapper()
// TODO, see vfs-tar

TODO

TODO