![]() This reverts commit
|
||
---|---|---|
.. | ||
test | ||
.gitignore | ||
.travis.yml | ||
LICENSE | ||
README.md | ||
localfs.js | ||
package.json |
README.md
VFS Local
VFS is an abstract interface for working with systems. This module is the reference implementation and provides a vfs interface to the local system using node apis. This is also often used in conjuction with vfs-socket
to provide the vfs interface to a remote system over any kind of network socket.
setup(fsOptions) -> vfs
This is the main exports of the module. It's a function that returns a vfs-local instance.
The fsOptions
argument is an object that can contain the following properties:
root
: Root path to mount the vfs. All fs operations are done relative to this root. Access outside this root is not allowed.checkSymlinks
: Normally paths are resolved using pure string manipulation. This options will aditionally realpath any symlinks to get the absolute path on the filesystem. Pratically it prevents you from using symlinks that point outside theroot
.umask
: Default umask for creating files (defaults to 0750)defaultEnv
: A shallow hash of env values to inject into child processes.
vfs.resolve(path, options, callback(err, meta))
This takes a virtual path as path
and returns the resolved path in the real filesystem as meta.path
in the callback.
This function has one option options.alreadyRooted
that tells resolve to not prefix the path with the vfs root.
vfs.stat(path, options, callback(err, stat))
Loads the stat information for a single path entity as stat
in the callback. This is a javascript object with the following fields:
name
: The basename of the file path (eg: file.txt).size
: The size of the entity in bytes.mtime
: The mtime of the file in ms since epoch.mime
: The mime type of the entity. Folders will have a mime that matches/(directory|folder)$/
. This vfs implementation will giveinode/directory
for directories.link
: If the file is a symlink, this property will contain the link data as a string.linkStat
: The stat information for what the link points to.fullPath
: The link stat object will have an additional property that's the resolved path relative to the vfs root.
vfs.readfile(path, options, callback(err, meta))
Open a file as a readable stream.
Options can include:
head
: Set to any truthy value to skip creating the file stream.etag
: Make a conditional request. If the provided etag value matches the entity, themeta
response will skip the stream and instead have a truthynotModified
property.range
: Read only a part of a file. The range value is an object withstart
,end
, and/oretag
. Start and end are byte offsets and inclusive. Etag means to only get the partial if the etag matches. Themeta
object in the response will have apartialContent
property containing an object withstart
,end
, andsize
(total size). Themeta.size
property will be only the size of the bytes in the partial response. If theoptions.range
object is invalidmeta
will containrangeNotSatisfiable
.- Any other options that node's
fs.createReadStream
accepts (likeencoding
)
Meta may include:
stream
: A readable node stream containing the contents.size
: The length of the stream in bytes.mime
: The mime type of the file.etag
: The etag for the file.rangeNotSatisfiable
: The range was bad.partialContent
: The range was successful, this has the range offsets.notModified
: The conditional etag matched.
vfs.readdir(path, options, callback(err, meta))
Read the contents of a directory as a stream of stat objects. The stream in meta.stream
emits vfs stat objects as documented above for the data
events. This is not a byte stream.
Options can include:
head
: Set to any truthy value to skip creating the event stream.etag
: Provide an etag and the function will setmeta.partialContent
to true and skip the stream if it matches.
Meta may include:
stream
: The node stream that emits stat objects.etag
: The weak etag for the directory listing.notModified
: The conditional etag matched.
vfs.mkfile(path, options, callback)
Create or overwrite a file. This has two modes. In one mode, the caller provides a readable stream which is then piped to the filesystem. In the other mode, the callback meta contains a writable stream to the filesystem.
Options can include:
stream
: A readable streaem to be written to the filesystem.parents
: make parent directories as needed- Any other options are passed through to node's
fs.createWriteStream
.
Meta may include:
stream
: If a stream wasn't provided in the options, a writable stream is returned in the meta. This stream will emit "done" when it's done being written to. Any errors will also be emitted on this stream object since the callback will have already fired.
vfs.mkdir(path, options, callback)
Create a directory at path
. Will error with EEXIST
if something is already at the path.
Options can include:
parents
: make parent directories as needed
vfs.rmfile(path, options, callback)
Delete a file at path
.
If options.recursive
is truthy, it will instead shell out to rm -rf
after resolving the path.
vfs.rmdir(path, options, callback)
Delete a directory at path
vfs.rename(path, options, callback)
Rename/move a file or directory. There are two modes depending on the option passed in.
Options can include:
to
: This property is the path to the target, thepath
option will be read as the source.from
: This property is the path of the source, thepath
option will be read as the target.
vfs.copy(path, options, callback)
Copy a file. There are two modes depending on the option passed in.
Options can include:
to
: This property is the path to the new file, thepath
option will be read as the source.from
: This property is the path of the source, thepath
option will be read as the new file.
vfs.symlink(path, options, callback)
Create a special symlink file at path
. The symlink data will be the value of options.target
. No translation of the link data is done. It's taken literally.
vfs.watch(path, options, callback)
Wrapper around node's fs.watch
and fs.watchFile
.
If options.file
is truthy, then fs.watchFile
is used. Otherwise fs.watch
is used. The watcher will be at meta.watcher
. For consistency, watchFile
objects will have a close()
method added that internally calls fs.unwatchFile
for the original path.
vfs.connect(port, options, callback)
Make a TCP connection and return the duplex stream as meta.stream
.
Options can include:
retries
: Number of times to retry connecting. Defaults to 5.retryDelay
: The delay between retrieson ms. Defaults to 50.
vfs.spawn(executablePath, options, callback)
Spawns a child process and returns a process object complete with three stdio streams. Wraps node's child_process.spawn
.
The executablePath
is a pre-resolved path. It will not get prefixed. So if you want a relative path within the vfs root, use vfs.resolve()
.
Options can include:
args
: An array of args to pass to the executable.stdoutEncoding
: The encoding to use on the stdout stream.stderrEncoding
: The encoding to use on the stderr stream.- Any other options you want to pass through to node's
child_process.spawn
(env
, ...)
Meta will contain:
process
: The child process. This will havestdin
,stdout
, andstderr
stream properties s as well as emit some events itself.
vfs.execFile(executablePath, options, callback)
Execute a process and buffers the output till the process exist. Don't use this on anything that will output substantial data or run for a long time. Wraps node's child_process.execFile
.
The options are the same as vfs.spawn()
.
Meta will contain:
stdout
: The buffered stdout data.stderr
: The buffered stderr data.
vfs.on(event, handler, callback)
Listen for custom vfs events. event
is a string identifier for the event type. handler
is a function that will get called every time the event is emitted. callback
will be called once the registration is complete. This is required since vfs is usually used over some async socket transport.
vfs.off(event, handler, callback)
Remove an event handler. The arguments are the same as vfs.on
, but remove the listener instead of registering it.
vfs.emit(event, value, callback)
Emit an event to all listening handlers. The callback means that the event was sent to all handlers, but they may not have received it yet if their transport is slower than yours.
vfs.extend(name, options, callback)
This API is provided to extend the capabilities of vfs. This is useful for when the vfs is on a remote filesystem and you want to run some custom node code there.
See the unit tests for docs.
TODO: document this better
vfs.unextend(name, options, callback)
Remove an extension by name.
vfs.use(name, options, callback)
Get a reference to an existing vfs extension api.