@kba/vfs-adapter-sftp v0.1.0

vfs

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)

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             X    X    X    X    X   
rmdir                -    X    -    -    -   
_urlForNode          -    -    -    -    -   
promisify            -    -    -    -    -   

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
  • @param {number} options.directoriesFirst=false
• @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-adapter-tar

ReadableWrapper

TODO

wrapStream(stream)

TODO