unionfs

You can use the exported ufs instance to layer multiple file systems. The order of .use() calls determines the priority: file systems added later will shadow or overlay those added earlier if they contain the same paths.

unionfs works with any object that implements the standard fs API, such as memfs (in-memory), linkfs (path redirection), or memory-fs.

import { ufs } from 'unionfs';
import { fs as fs1 } from 'memfs';
import * as fs2 from 'fs';

// Layer fs1 on top of fs2
ufs.use(fs1).use(fs2);

// Operations on ufs will now search through the layered file systems
ufs.readFileSync(/* ... */);

Install the unionfs package using npm to enable the creation of a unioned file system from multiple fs-compatible objects.

npm install --save unionfs

This example demonstrates how to combine multiple memfs volumes and a memory-fs instance into a single unified file system interface.

import * as fs from 'fs';
import { Volume } from 'memfs';
import * as MemoryFileSystem from 'memory-fs';
import { ufs } from 'unionfs';

const vol1 = Volume.fromJSON({ '/memfs-1': '1' });
const vol2 = Volume.fromJSON({ '/memfs-2': '2' });

const memoryFs = new MemoryFileSystem();
memoryFs.writeFileSync('/memory-fs', '3');

// Layering the file systems
ufs.use(fs).use(vol1).use(vol2).use(memoryFs);

console.log(ufs.readFileSync('/memfs-1', 'utf8')); // 1
console.log(ufs.readFileSync('/memfs-2', 'utf8')); // 2
console.log(ufs.readFileSync('/memory-fs', 'utf8')); // 3

Instead of using the singleton ufs instance, you can instantiate your own Union class to manage isolated sets of file systems.

import { Union } from 'unionfs';

var ufs1 = new Union();
ufs1.use(fs).use(vol);

var ufs2 = new Union();
ufs2.use(fs).use(/*...*/);

The watch() method allows you to monitor file changes across all attached filesystems. It returns a proxy object that, when a method is called on it, executes that method on all active watchers collected from the underlying filesystems.

const watchers = ufs.watch('path/to/file');
// Calling a method on the returned proxy calls it on all underlying watchers
watchers.close();

The use() method adds a filesystem implementing the IFS interface to the Union stack. Filesystems added later are searched first (they are pushed to the end of the internal array, but the search logic iterates from the end of the array to the beginning, effectively treating the most recently added filesystem as the highest priority).

const ufs = new Union();
ufs.use(fs1).use(fs2);

The Union class implements a wide range of standard Node.js fs methods by delegating to the underlying IFS implementations. These include:

• Synchronous Methods: existsSync, readdirSync, and others from fs-monkey/lib/util/lists.
• Asynchronous (Callback) Methods: Standard fs callback-style methods.
• Promise-based Methods: Methods available on fs.promises (e.g., access, copyFile, mkdir, readFile, writeFile, etc.).
• Special Methods: watch, watchFile, unwatchFile, createReadStream, and createWriteStream which have custom union logic.

If you need multiple independent union file system instances, you can instantiate the Union class directly. The resulting instance implements IUnionFs.

import { Union } from 'unionfs';

const myUnion = new Union();
myUnion.use(fs1);
myUnion.use(fs2);

When an operation fails across the entire filesystem stack, the Union instance throws an error that implements the IUnionFsError interface. This error includes a prev property, allowing you to traverse the chain of errors encountered in each filesystem.

export interface IUnionFsError extends Error {
  prev?: IUnionFsError | null;
}