/vfs

Virtual File Systems with a node fs-like API

Primary LanguageJavaScript

vfs

A virtual filesystem that works like fs

Build Status CircleCI

Introduction

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.

Currently implemented

  • 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    -    -    -

Creating a new VFS

  • Subclass vfs.base
  • Override
    • _stat
    • _readdir

API

vfs.base

Base class of all vfs

Provides default implementations for some api methods.

(static) NODE_TYPES

Types a vfs.Node can have.

Currently:

  • Directory
  • SymbolicLink

(static) capabilities

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

  • @return {Set} set of available methods

vfs.api

Interface of all vfs

Constructor

use(pluginClass, pluginOptions)

Enable a plugin

stat(path, options, callback)

Get metadata about a node in the vfs.

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

mkdir(path, mode, callback)

Create a directory

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

init()

Initialize the filesystem.

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

end()

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

sync(options)

Sync the filesystem.

createReadStream(path, options)

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

createWriteStream(path, options)

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

readFile(path, options, callback)

@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

writeFile(path, data, options, callback)

@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

unlink(path, options, 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}

mkdirRecursive(path, cb)

mkdir -p

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

copyFile(from, to, options, cb)

Copy file, possibly across different VFS.

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

getdir(dir, options, callback)

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

find(path, callback)

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

du(path, callback)

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

readdir(path, options, callback)

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

nextFile(path, options, callback)

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

Events

Events: ready
Events: sync
Events: error
Events: end

vfs.Node

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

Class representing file metadata

Constructor

  • @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}

Properties

vfs

Parent vfs instance, e.g. a file

path

Absolute, normalized path of the node within the vfs

mtime

Date of last modification

mode
mimetype

MIME type of this node

%root

See path.parse(path)

%dir

See path.parse(path)

%base

See path.parse(path)

%ext

See path.parse(path)

%name

See path.parse(path)

CompressionUtils

(static) hasDecompressor(format)

Whether a decompression format is supported

(static) getDecompressor(format)

Instantiate a decompression stream @memberof util

PathUtils

Enhancing path

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

(static) removeTrailingSep(path)

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

(static) removeLeadingSep(path)

Remove leading separators (slashes) from path.

StreamUtils

(static) createReadableWrapper()

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

ReadableWrapper

TODO

wrapStream(stream)

TODO