VFileSys

A lightweight package for manipulating an in-memory unix-like virtual file systems (vfs).

Install

npm install vfilesys

Usage

Requiring the module:

const VirtualFileSystem = require('vfilesys')

Initializing a new VFS:

const vfs = new VirtualFileSystem()

Creating files:

vfs.write('/some/file.txt', 'My data')

Exporting a generated VFS:

vfs.export('./somewhere/backup.json', 'json')

Importing a previously created VFS:

vfs.import('./somewhere/other-backup.json')

Creating a virtual copy of a real directory:

vfs.virtualize('./somewhere/')

API Reference:

vfs.exists(path)

vfs.exists(path: string): boolean

Verifies the existence of a file under the selected virtual file system.

vfs.isFile(path)

vfs.isFile(path: string): boolean

Verifies whether an item in the virtual file system exists and is a file.

vfs.isDirectory(path)

vfs.isDirectory(path: string): boolean

Verifies whether an item in the virtual file system exists and is a directory.

vfs.isEmptyDirectory(path)

vfs.isEmptyDirectory(path: string): boolean

Verifies whether an item in the virtual file system exists and is an empty directory.

vfs.read(path, encoding)

vfs.read(path: string, encoding?: string): buffer|string

Reads a file and returns its contents. If 'encoding' is not specified, returns data as a buffer.

vfs.stats(path)

vfs.stats(path: string): StatusObject

Returns the an instance of StatusObject from a file.

vfs.write(path, data)

vfs.write(path: string, data?: string|buffer): <VirtualFileSystem>

Writes data to a vfs file, and returns the vfs instance for method chaining.

vfs.append(path, data)

vfs.append(path: string, data?: string|buffer): <VirtualFileSystem>

Appends data to a vfs file, and returns the vfs instance for method chaining.

vfs.remove(path)

vfs.remove(path: string): <VirtualFileSystem>

Removes a file, and returns the vfs instance for method chaining.

vfs.readdir(path [, options])

vfs.readdir(path: string, [options: object]): array

Options include:

• recurse: boolean (default: false)
  • If set to true, returns a list of all items, including subdirectories and files on them
• absolutePaths: boolean (default: true)
  • If set to false, return relative paths to the called path
• withFileTypes: boolean (default: false)
  • If set to true return VirtualFileSystem.VDirent object instead of filenames

vfs.listdir(path)

vfs.listdir(path: string): array

Reads and returns the contents of a directory and subdirectories. (Behaves similar to vfs.readdir with option 'recurse' enabled.

vfs.mkdir(path)

vfs.mkdir(path: string): <VirtualFileSystem>

Creates a directory (filling path gaps) and returns the vfs instance for method chaining.

vfs.rmdir(path [, force])

vfs.rmdir(path: string, [force: boolean]: <VirtualFileSystem>

Removes a directory. To remove a filled directory and its items, 'force' must be enabled.

vfs.copy(path, newpath)

vfs.copy(path: string, newpath: string): <VirtualFileSystem>

Copies a file instance from one place to another, keeping status.

vfs.move(path, newpath)

vfs.move(path: string, newpath: string): <VirtualFileSystem>

Moves a file instance from one place to another, keeping status, UUID, and creation time.

vfs.virtualize(rpath, vpath [, options])

vfs.virtualize('C:\\Users\\someone\\somewhere', '/virtualized')

Takes a real path as rpath and creates a virtualized copy of its contents in vfs under the specified vpath location.

Options include:

• recurse: boolean (default: true)
  • If enabled, and rpath points to a directory, subcontents will be copied.
• copyctime: boolean (default: false)
  • If enabled, causes creation time of files to be copied into the virtual envirsonment.

vfs.export(file [, exportType])

vfs.export(file: string, exportType: string('json' | 'pop')): string

Exports a JSON or POP representation of the virtual file system and also returns it.

If file is set to null, the exported version will not be saved, only returned.

The exportType parameter must be one of 'json' or 'pop', and controls the output format.

The 'pop' export format stands for 'filesystem population format', and is a minimal representation of a vfs, containing only filename and contents of entries. While, the 'json' export format includes all data of each file entry, including path, data, uuid, and ctime.

vfs.import(file)

vfs.import(file: string): <VirtualFileSystem>

Imports a previously exported JSON representation of a virtual file system into the current vfs. Conflicting entries will be overriden by the newly imported version. This method can only import instances exported with vfs.export in 'JSON' mode. For importing 'pop' files, see vfs.build documentation.

vfs.build(file)

vfs.build(file: string): <VirtualFileSystem>

Imports a previously exported POP representation of a virtual file system into the current vfs. Conflicting entries will be overriden by the newly imported version. This method can only import instances exported with vfs.export in 'POP' mode. For importing 'JSON' files, see vfs.import documentation.

As 'pop' exports of vfs instances contain minimal information, the ctime and uuid of files is not kept, and will be recreated.