memfs

What is memfs?

The memfs npm package is an in-memory filesystem that mimics the Node.js fs module. It allows you to create an ephemeral file system that resides entirely in memory, without touching the actual disk. This can be useful for testing, mocking, and various other scenarios where you don't want to perform I/O operations on the real file system.

What are memfs's main functionalities?

Creating and manipulating files

This feature allows you to create, read, and write files in memory as if you were using the native fs module.

const { Volume } = require('memfs');
const vol = new Volume();
vol.writeFileSync('/hello.txt', 'Hello, World!');
const content = vol.readFileSync('/hello.txt', 'utf8');
console.log(content); // Outputs: Hello, World!

Directory operations

This feature enables you to create directories, list their contents, and perform other directory-related operations, all in memory.

const { Volume } = require('memfs');
const vol = new Volume();
vol.mkdirSync('/mydir');
vol.writeFileSync('/mydir/file.txt', 'My file content');
const files = vol.readdirSync('/mydir');
console.log(files); // Outputs: ['file.txt']

Linking and symlinking

This feature allows you to create hard links and symbolic links, mimicking the behavior of links on a real file system.

const { Volume } = require('memfs');
const vol = new Volume();
vol.writeFileSync('/original.txt', 'Content of original');
vol.linkSync('/original.txt', '/link.txt');
vol.symlinkSync('/original.txt', '/symlink.txt');
const linkContent = vol.readFileSync('/link.txt', 'utf8');
const symlinkContent = vol.readlinkSync('/symlink.txt');
console.log(linkContent); // Outputs: Content of original
console.log(symlinkContent); // Outputs: /original.txt

File system watching

This feature provides the ability to watch for changes in the file system, similar to fs.watch in the native fs module.

const { Volume } = require('memfs');
const vol = new Volume();
const fs = vol.promises;

async function watchExample() {
  await fs.writeFile('/watched.txt', 'Initial content');
  fs.watch('/watched.txt', (eventType, filename) => {
    console.log(`Event type: ${eventType}; File: ${filename}`);
  });
  await fs.writeFile('/watched.txt', 'Updated content');
}

watchExample();

Other packages similar to memfs

mock-fs

mock-fs is a package that provides a mock file system for Node.js. It is similar to memfs in that it allows you to create an in-memory file system for testing purposes. However, mock-fs overrides the native fs module, while memfs provides a separate file system instance.

unionfs

unionfs is a package that can combine multiple file systems into a single cohesive file system interface. It can be used with memfs to overlay an in-memory file system on top of the real file system, providing a way to mix real and virtual file system operations.

fs-mock

fs-mock is another in-memory file system module for Node.js. It offers similar functionality to memfs, allowing you to mock the fs module for testing. It differs in API and implementation details, and the choice between fs-mock and memfs may come down to personal preference or specific use-case requirements.

README

memfs 2.0

In-memory file-system with Node's fs API.

• 100% of Node's fs API implemented, see API Status
• Stores files in memory, in Buffers
• Throws same* errors as Node.js
• Has concept of i-nodes
• Implements hard links
• Implements soft links (aka symlinks, symbolic links)
• More testing coming soon*
• Permissions may* be implemented in the future
• Can be used in browser, see memfs-webpack

Install:

npm install --save memfs

Usage:

import {fs} from 'memfs';

fs.writeFileSync('/hello.txt', 'World!');
fs.readFileSync('/hello.txt', 'utf8'); // World!

Create a file system from a plain JSON:

import {fs, vol} from 'memfs';

const json = {
    './README.md': '1',
    './src/index.js': '2',
    './node_modules/debug/index.js': '3',
};
vol.fromJSON(json, '/app');

fs.readFileSync('/app/README.md', 'utf8'); // 1
vol.readFileSync('/app/src/index.js', 'utf8'); // 2

Export to JSON:

vol.writeFileSync('/script.sh', '#! /bin/bash');
vol.toJSON(); // {"/script.sh": "#! /bin/bash"}

Use it for testing:

vol.writeFileSync('/foo', 'bar');
expect(vol.toJSON()).to.eql({"/foo": "bar"});

See also

Other filesystem goodies:

• spyfs - spies on filesystem actions
• unionfs - creates a union of multiple filesystem volumes
• linkfs - redirects filesystem paths
• fs-monkey - monkey-patches Node's fs module and require function
• libfs - real filesystem (that executes UNIX system calls) implemented in JavaScript

Create as many filesystem volumes as you need:

import {Volume} from 'memfs';

const vol = Volume.fromJSON({'/foo': 'bar'});
vol.readFileSync('/foo'); // bar

const vol2 = Volume.fromJSON({'/foo': 'bar 2'});
vol2.readFileSync('/foo'); // bar 2

Use memfs together with unionfs to create one filesystem from your in-memory volumes and the real disk filesystem:

import * as fs from 'fs';
import {ufs} from 'unionfs';

ufs
    .use(fs)
    .use(vol);

ufs.readFileSync('/foo'); // bar

Use fs-monkey to monkey-patch Node's require function:

import {patchRequire} from 'fs-monkey';

vol.writeFileSync('/index.js', 'console.log("hi world")');
patchRequire(vol);
require('/index'); // hi world

Dependencies

This package depends on the following Node modules: buffer, events, streams, path.

It also uses process and setImmediate globals, but mocks them, if not available.

Reference

vol vs fs

This package exports vol and fs objects which both can be used for filesystem operations but are slightly different.

import {vol, fs} from 'memfs';

vol is an instance of Volume constructor, it is the default volume created for your convenience. fs is an fs-like object created from vol using createFsFromVolume(vol), see reference below.

All contents of the fs object are also exported individually, so you can use memfs just like you would use the fs module:

import {readFileSync, F_OK, ReadStream} from 'memfs';

Volume Constructor

Volume is a constructor function for creating new volumes:

import {Volume} from 'memfs';
const vol = new Volume;

Volume implements all Node's filesystem methods:

vol.writeFileSync('/foo', 'bar');

But it does not hold constants and its methods are not bound to vol:

vol.F_OK; // undefined

A new volume can be create using the Volume.fromJSON convenience method:

const vol = Volume.fromJSON({
    '/app/index.js': '...',
    '/app/package.json': '...',
});

It is just a shorthand for vol.fromJSON, see below.

Volume instance vol

vol.fromJSON(json[, cwd])

Adds files from a flat json object to the volume vol. The cwd argument is optional and is used to compute absolute file paths, if a file path is given in a relative form.

Note: To remove all existing files, use vol.reset() method.

vol.fromJSON({
    './index.js': '...',
    './package.json': '...',
}, '/app');

vol.mountSync(cwd, json)

Legacy method, which is just an alias for vol.fromJSON.

vol.toJSON([paths[, json[, isRelative]]])

Exports the whole contents of the volume recursively to a flat JSON object.

paths is an optional argument that specifies one or more paths to be exported. If this argument is omitted, the whole volume is exported. paths can be an array of paths. A path can be a string, Buffer or an URL object.

json is an optional object parameter which will be populated with the exported files.

isRelative is boolean that specifies if returned paths should be relative.

Note: JSON contains only files, empty folders will be absent.

vol.reset()

Removes all files from the volume.

vol.fromJSON({'/index.js': '...'});
vol.toJSON(); // {'/index.js': '...' }
vol.reset();
vol.toJSON(); // {}

vol.mkdirp(path, callback)

Creates a directory tree recursively. path specifies a directory to create and can be a string, Buffer, or an URL object. callback is called on completion and may receive only one argument - an Error object.

vol.mkdirpSync(path)

A synchronous version of vol.mkdirp(). This method throws.

createFsFromVolume(vol)

Returns an fs-like object created from a Volume instance vol.

import {createFsFromVolume, Volume} from 'memfs';

const vol = new Volume;
const fs = createFsFromVolume(vol);

The idea behind the fs-like object is to make it identical to the one you get from require('fs'). Here are some things this function does:

• Binds all methods, so you can do:

const {createFileSync, readFileSync} = fs;

• Adds constants fs.constants, fs.F_OK, etc.

Relative paths

If you work with absolute paths, you should get what you expect from memfs.

You can also use relative paths but the gotcha is that then memfs needs to somehow resolve those relative paths to absolute paths. memfs will use the value of process.cwd() to resolve the absolute paths. The problem is that process.cwd() specifies the current working directory of your on-disk filesystem and you will probably not have that directory available in memfs.

The best solution is to always use absolute paths. Alternatively, you can use mkdirp method to recursively create the current working directory in your volume:

vol.mkdirpSync(process.cwd());

Or, you can set the current working directory to /, which is one folder that exists in all your memfs volumes:

process.chdir('/');

API Status

All of the Node's fs API is implemented. Some error messages may be inaccurate. File permissions are currently not implemented (you have access to any file), basically fs.access() is a no-op.

• Constants
• FSWatcher
• ReadStream
• WriteStream
• Stats
• access(path[, mode], callback)
  • Does not check permissions
• accessSync(path[, mode])
  • Does not check permissions
• appendFile(file, data[, options], callback)
• appendFileSync(file, data[, options])
• chmod(path, mode, callback)
• chmodSync(path, mode)
• chown(path, uid, gid, callback)
• chownSync(path, uid, gid)
• close(fd, callback)
• closeSync(fd)
• createReadStream(path[, options])
• createWriteStream(path[, options])
• exists(path, callback)
• existsSync(path)
• fchmod(fd, mode, callback)
• fchmodSync(fd, mode)
• fchown(fd, uid, gid, callback)
• fchownSync(fd, uid, gid)
• fdatasync(fd, callback)
• fdatasyncSync(fd)
• fstat(fd, callback)
• fstatSync(fd)
• fsync(fd, callback)
• fsyncSync(fd)
• ftruncate(fd[, len], callback)
• ftruncateSync(fd[, len])
• futimes(fd, atime, mtime, callback)
• futimesSync(fd, atime, mtime)
• lchmod(path, mode, callback)
• lchmodSync(path, mode)
• lchown(path, uid, gid, callback)
• lchownSync(path, uid, gid)
• link(existingPath, newPath, callback)
• linkSync(existingPath, newPath)
• lstat(path, callback)
• lstatSync(path)
• mkdir(path[, mode], callback)
• mkdirSync(path[, mode])
• mkdtemp(prefix[, options], callback)
• mkdtempSync(prefix[, options])
• open(path, flags[, mode], callback)
• openSync(path, flags[, mode])
• read(fd, buffer, offset, length, position, callback)
• readSync(fd, buffer, offset, length, position)
• readdir(path[, options], callback)
• readdirSync(path[, options])
• readFile(path[, options], callback)
• readFileSync(path[, options])
• readlink(path[, options], callback)
• readlinkSync(path[, options])
• realpath(path[, options], callback)
• realpathSync(path[, options])
  • Caching not implemented
• rename(oldPath, newPath, callback)
• renameSync(oldPath, newPath)
• rmdir(path, callback)
• rmdirSync(path)
• stat(path, callback)
• statSync(path)
• symlink(target, path[, type], callback)
• symlinkSync(target, path[, type])
• truncate(path[, len], callback)
• truncateSync(path[, len])
• unlink(path, callback)
• unlinkSync(path)
• utimes(path, atime, mtime, callback)
• utimesSync(path, atime, mtime)
• watch(filename[, options][, listener])
• watchFile(filename[, options], listener)
• unwatchFile(filename[, listener])
• write(fd, buffer[, offset[, length[, position]]], callback)
• write(fd, string[, position[, encoding]], callback)
• writeFile(file, data[, options], callback)
• writeFileSync(file, data[, options])
• writeSync(fd, buffer[, offset[, length[, position]]])
• writeSync(fd, string[, position[, encoding]])

License

This is free and unencumbered software released into the public domain.

Anyone is free to copy, modify, publish, use, compile, sell, or distribute this software, either in source code form or as a compiled binary, for any purpose, commercial or non-commercial, and by any means.

In jurisdictions that recognize copyright laws, the author or authors of this software dedicate any and all copyright interest in the software to the public domain. We make this dedication for the benefit of the public at large and to the detriment of our heirs and successors. We intend this dedication to be an overt act of relinquishment in perpetuity of all present and future rights to this software under copyright law.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

For more information, please refer to http://unlicense.org/