layer-fs

An in-memory friendly, synchronous overlay filesystem.

layer-fs composes two fs-like objects:

• upper: the writable layer
• lower: the read-only baseline

Reads prefer upper and fall back to lower. Writes use copy-up: if the target only exists in lower, it is copied into upper first, then the write is applied to upper. Deletions are represented via a tombstone set so that lower entries can be hidden without being removed.

Install

npm i layer-fs

Usage

import fs from "node:fs";
import { Volume, createFsFromVolume } from "memfs";
import { createOverlayFs } from "layer-fs";

const lower = createFsFromVolume(new Volume());
const upper = fs; // or another fs-like implementation

lower.writeFileSync("/hello.txt", "from-lower");

const overlay = createOverlayFs(upper, lower);

// Read falls back to lower
console.log(overlay.readFileSync("/hello.txt", "utf8"));

// Write triggers copy-up (lower stays unchanged)
overlay.writeFileSync("/hello.txt", "from-upper");
console.log(upper.readFileSync("/hello.txt", "utf8"));
console.log(lower.readFileSync("/hello.txt", "utf8"));

API

The returned overlay object exposes:

• upperFs, lowerFs, tombstone
• existsSync, readFileSync, writeFileSync, appendFileSync
• statSync, lstatSync, readdirSync, readlinkSync
• mkdirSync, unlinkSync, rmSync, rmdirSync, renameSync, linkSync, symlinkSync

Behavior Notes

• Tombstones: unlinkSync / rmSync / rmdirSync add tombstones so the corresponding lower paths become invisible in the overlay view.
• Symlinks: write-path operations resolve symlinks and may copy-up symlinks from lower to upper to preserve semantics.
• Hardlinks: best-effort handling to keep hardlink semantics when copying up from lower.
• readdirSync({ recursive: true }): follows Node.js v24+ conventions for returned entries and options compatibility.

Development

npm test
npm run build

License

MIT. See LICENSE.