@mojule/vfs
v1.1.0
Published
Virtual file system built on mojule tree
Downloads
12
Readme
vfs
Virtual file system built on mojule tree
Important: this documentation is out of date and needs to be updated. However, the tests are up to date and provide examples for usage.
Install
npm install @mojule/vfs
Example
const Vfs = require( '@mojule/vfs' )
const tree = Vfs.virtualize( 'some/path' )
console.log( tree.serialize() )
const virtualFile = Vfs.createFile( 'hello.txt', 'Hello, World!', 'utf8' )
const virtualDirectory = Vfs.createDirectory( 'text' )
virtualDirectory.appendChild( virtualFile )
virtualDirectory.actualize( 'some/path' )
Plugins
vfs has the same API as mojule tree but with the following plugins:
createFile
Creates a file node. The arguments are the same as fs.writeFile:
Vfs.createFile( filename, data, encoding )
encoding
is optional, but if included should be a
valid node.js encoding type
If encoding
is omitted, it will assume 'utf8'
if data
is a string, or if
data
is a Buffer, a JSON buffer representation or an array of
bytes it will assume convert data
to a buffer.
// { type: 'Buffer', data: [ 1, 2, 3 ] }
const jsonObj = JSON.parse( JSON.stringify( Buffer.from( [ 1, 2, 3 ] ) ) )
const text1 = Vfs.createFile( 'hello.txt', 'hello' )
const text2 = Vfs.createFile( 'hello.txt', 'hello', 'utf8' )
const data1 = Vfs.createFile( 'hello.bin', [ 1, 2, 3 ] )
const data2 = Vfs.createFile( 'hello.bin', Buffer.from( [ 1, 2, 3 ] ) )
const data3 = Vfs.createFile( 'hello.bin', jsonObj )
createDirectory
Creates a directory node
Vfs.createDirectory( filename )
const hello = Vds.createDirectory( 'hello' )
const world = Vfs.createFile( 'world.txt', 'world' )
hello.append( world )
actualize
Writes a vfs tree to disk, then calls callback with the error if one occured
node.actualize( targetPath, callback )
The directories and files in your virtual file system will be written under
targetPath
- node.js will throw an error if any of the files or directories
already exist, so you may want to clear it out first if this may be the case.
const hello = Vds.createDirectory( 'hello' )
const world = Vfs.createFile( 'world.txt', 'world' )
hello.append( world )
hello.actualize( './temp', err => {
if( err ) return console.error( err )
console.log( 'wrote vfs to ./temp' )
})
atPath
Gets the node at a given path in the tree. Overrides the base atPath to match
paths that match those provided by getPath
, see below for more information
const hello = Vds.createDirectory( 'hello' )
const world = Vfs.createFile( 'world.txt', 'world' )
hello.append( world )
const target = hello.atPath( 'hello/world.txt' )
// true
console.log( world === target )
getPath
Overrides the base getPath to return paths that map 1:1 to a file system - eg
the slug for the root node will be included in the path, unlike the default
implementation in which it is instead implied. Unlike the base getPath, does
not take a separator - posix style paths eg /
are used.
const hello = Vds.createDirectory( 'hello' )
const world = Vfs.createFile( 'world.txt', 'world' )
hello.append( world )
// 'hello/world.txt'
console.log( world.getPath() )
isEmpty
Overrides the default implementation, and returns true
for nodes with
nodeType
of file
, false
for nodes with nodeType
of directory
If you try to add a child node to a file
it will throw
const hello = Vds.createDirectory( 'hello' )
const world = Vfs.createFile( 'world.txt', 'world' )
// false
console.log( hello.isEmpty() )
// true
console.log( world.isEmpty() )
isValue
Overrides the default implementation, which simply returns true
if the node's
value
is an object, and only returns true if the combination of nodeType
,
filename
, data
, encoding
etc. are all correct. Constructing nodes with
Vfs.createFile
and Vfs.createDirectory
is suggested to help ensure that this
is the case. Used internally to throw whenever you attempt to set the value or
any of its properties to something invalid.
const nodeValue1 = {
nodeType: 'file',
filename: 'hello.txt',
data: 'hello'
}
// true
console.log( Vfs.isValue( nodeValue1 ) )
const nodeValue2 = {
nodeType: 'file',
filename: 'temp/hello.txt',
data: 'hello'
}
// false - file name contains a reserved character, /
console.log( Vfs.isValue( nodeValue2 ) )
nodeType
Overridden from the default (always returns the string 'node'
) to return
the nodeType
property of the node's value
object - will always be either
file
or directory
const hello = Vds.createDirectory( 'hello' )
const world = Vfs.createFile( 'world.txt', 'world' )
// 'directory'
console.log( hello.nodeType() )
// 'file'
console.log( world.nodeType() )
serializer
Serializes to and from a compact representation suitable for storing as JSON etc
serialize
Serialize the current node
const hello = Vds.createDirectory( 'hello' )
const world = Vfs.createFile( 'world.txt', 'world' )
const serialized = hello.serialize()
{
"hello/world.txt": "world"
}
deserialize
Deserializes the object to a vfs tree
const data = {
"hello/world.txt": "world"
}
const hello = Vfs.deserialize( data )
const world = hello.firstChild()
// 'directory'
console.log( hello.nodeType() )
// 'file'
console.log( world.nodeType() )
slug
Overridden from the default to always returns the file or directory's name. Used by getPath.
const hello = Vds.createDirectory( 'hello' )
const world = Vfs.createFile( 'world.txt', 'world' )
// 'hello'
console.log( hello.slug() )
// 'world.txt'
console.log( world.slug() )
virtualize
Reads a file or directory from disk and creates a vfs tree. The callback takes an error if one occurred and the tree if successful.
Vfs.virtualize( sourcePath, callback )
Vfs.virtualize( 'some/path', ( err, tree ) => {
if( err ) return console.error( err )
console.log( tree.serialize() )
})
registerText
Registers a text extension with vfs - files with this extension will be treated as text when encoding is not specified and no matching mime type can be found
Vfs.registerText( '.mmon' )
// true
console.log( Vfs.isTextExtension( '.mmon' ) )