typescript-virtual-container 1.2.3 → 1.2.5

package/src/VirtualFileSystem/index.ts

@@ -1,435 +1,655 @@
 import { EventEmitter } from "node:events";
-import * as fs from "node:fs";
+import * as fsSync from "node:fs";
 import * as path from "node:path";
 import { gunzipSync, gzipSync } from "node:zlib";
+import type {
+	InternalDirectoryNode,
+	InternalFileNode,
+	InternalNode,
+} from "./internalTypes";
+import { getNode, getParentDirectory, normalizePath } from "./path";
 import type {
 	RemoveOptions,
 	VfsNodeStats,
+	VfsSnapshot,
+	VfsSnapshotDirectoryNode,
+	VfsSnapshotFileNode,
+	VfsSnapshotNode,
 	WriteFileOptions,
 } from "../types/vfs";
-import type { PerfLogger } from "../utils/perfLogger";
-import { createPerfLogger } from "../utils/perfLogger";
-import { normalizePath } from "./path";
+
+// ── Persistence options ───────────────────────────────────────────────────────
 
 /**
- * In-memory virtual filesystem with tar.gz mirror persistence.
+ * "memory" — pure in-memory, no disk I/O (default).
  *
- * Paths are normalized to POSIX-like absolute paths. Use
- * {@link VirtualFileSystem.restoreMirror} on startup and
- * {@link VirtualFileSystem.flushMirror} to persist pending changes.
+ * "fs"     — mirrors the VFS tree to a directory on the host filesystem.
+ *             `snapshotPath` must be set to the directory where the JSON
+ *             snapshot file will be read/written.
  */
-const perf: PerfLogger = createPerfLogger("VirtualFileSystem");
-
-class VirtualFileSystem extends EventEmitter {
-	private readonly mirrorRoot: string;
+export type VfsPersistenceMode = "memory" | "fs";
 
-	private ensureMirrorRoot(): void {
-		fs.mkdirSync(this.mirrorRoot, { recursive: true, mode: 0o755 });
-	}
-
-	private resolveFsPath(targetPath: string): string {
-		const normalized = normalizePath(targetPath);
-		const relativePath = normalized.slice(1);
-		const resolved = path.resolve(this.mirrorRoot, relativePath || ".");
-		const relative = path.relative(this.mirrorRoot, resolved);
+export interface VfsOptions {
+	/**
+	 * Persistence mode.
+	 * - `"memory"` (default): no disk access, snapshot via `toSnapshot()`.
+	 * - `"fs"`: auto-save JSON snapshot to `snapshotPath` on every
+	 *   `flushMirror()` call, and restore from it on `restoreMirror()`.
+	 */
+	mode?: VfsPersistenceMode;
+	/**
+	 * Directory used by `"fs"` mode.
+	 * The snapshot file will be written to `<snapshotPath>/vfs-snapshot.json`.
+	 * Required when `mode` is `"fs"`.
+	 */
+	snapshotPath?: string;
+}
 
-		if (relative.startsWith("..") || path.isAbsolute(relative)) {
-			throw new Error(`Invalid path '${targetPath}'.`);
-		}
+// ── VirtualFileSystem ─────────────────────────────────────────────────────────
 
-		return resolved;
-	}
+/**
+ * In-memory virtual filesystem with optional JSON-snapshot persistence.
+ *
+ * **Memory mode** (default) — all state lives in a fast recursive tree.
+ * Use `toSnapshot()` / `fromSnapshot()` / `importSnapshot()` for serialisation.
+ *
+ * **FS mode** — same in-memory tree, but `restoreMirror()` loads a JSON
+ * snapshot from disk and `flushMirror()` writes it back.  This gives you
+ * persistent VFS state across process restarts without any real POSIX filesystem
+ * semantics leaking through.
+ *
+ * @example
+ * ```ts
+ * // Pure in-memory (default)
+ * const vfs = new VirtualFileSystem();
+ *
+ * // With disk persistence
+ * const vfs = new VirtualFileSystem({ mode: "fs", snapshotPath: "./data" });
+ * await vfs.restoreMirror(); // load from disk (no-op if no snapshot yet)
+ * // ... use vfs ...
+ * await vfs.flushMirror();  // persist to disk
+ * ```
+ */
+class VirtualFileSystem extends EventEmitter {
+	private root: InternalDirectoryNode;
+	private readonly mode: VfsPersistenceMode;
+	private readonly snapshotFile: string | null;
 
-	private detectGzipFile(targetPath: string): boolean {
-		const fd = fs.openSync(targetPath, "r");
-		try {
-			const header = Buffer.alloc(2);
-			const bytesRead = fs.readSync(fd, header, 0, 2, 0);
-			return bytesRead === 2 && header[0] === 0x1f && header[1] === 0x8b;
-		} finally {
-			fs.closeSync(fd);
+	constructor(options: VfsOptions = {}) {
+		super();
+		this.mode = options.mode ?? "memory";
+		if (this.mode === "fs") {
+			if (!options.snapshotPath) {
+				throw new Error(
+					'VirtualFileSystem: "snapshotPath" is required when mode is "fs".',
+				);
+			}
+			this.snapshotFile = path.resolve(
+				options.snapshotPath,
+				"vfs-snapshot.json",
+			);
+		} else {
+			this.snapshotFile = null;
 		}
+		this.root = this.makeDir("", 0o755);
 	}
 
-	private computeDiskUsageBytes(targetPath: string): number {
-		const stats = fs.statSync(targetPath);
-		if (stats.isFile()) {
-			return stats.size;
-		}
+	// ── Internal helpers ──────────────────────────────────────────────────────
 
-		let total = 0;
-		for (const entry of fs.readdirSync(targetPath)) {
-			total += this.computeDiskUsageBytes(path.join(targetPath, entry));
-		}
-		return total;
+	private makeDir(name: string, mode: number): InternalDirectoryNode {
+		const now = new Date();
+		return {
+			type: "directory",
+			name,
+			mode,
+			createdAt: now,
+			updatedAt: now,
+			children: new Map(),
+		};
 	}
 
-	private renderTreeLines(targetPath: string, label: string): string {
-		const lines = [label];
-
-		const walk = (currentPath: string, prefix: string): void => {
-			const entries = fs
-				.readdirSync(currentPath, { withFileTypes: true })
-				.map((entry) => entry.name)
-				.sort((left, right) => left.localeCompare(right));
-
-			for (let i = 0; i < entries.length; i += 1) {
-				const name = entries[i]!;
-				const isLast = i === entries.length - 1;
-				const connector = isLast ? "└── " : "├── ";
-				const nextPrefix = `${prefix}${isLast ? "    " : "│   "}`;
-				const entryPath = path.join(currentPath, name);
-				const isDirectory = fs.statSync(entryPath).isDirectory();
-
-				lines.push(`${prefix}${connector}${name}`);
-				if (isDirectory) {
-					walk(entryPath, nextPrefix);
-				}
-			}
+	private makeFile(
+		name: string,
+		content: Buffer,
+		mode: number,
+		compressed: boolean,
+	): InternalFileNode {
+		const now = new Date();
+		return {
+			type: "file",
+			name,
+			content,
+			mode,
+			compressed,
+			createdAt: now,
+			updatedAt: now,
 		};
-
-		walk(targetPath, "");
-		return lines.join("\n");
 	}
 
-	/**
-	 * Creates a virtual filesystem instance.
-	 *
-	 * @param baseDir Base directory used to resolve mirror archive location.
-	 */
-	constructor(baseDir: string = process.cwd()) {
-		super();
-		perf.mark("constructor");
-		this.mirrorRoot = path.resolve(baseDir, ".vfs", "mirror");
+	private mkdirRecursive(targetPath: string, mode: number): void {
+		const normalized = normalizePath(targetPath);
+		if (normalized === "/") return;
+		const parts = normalized.split("/").filter(Boolean);
+		let current = this.root;
+		let builtPath = "";
+		for (const part of parts) {
+			builtPath += `/${part}`;
+			let child = current.children.get(part);
+			if (!child) {
+				child = this.makeDir(part, mode);
+				current.children.set(part, child);
+				this.emit("dir:create", { path: builtPath, mode });
+			} else if (child.type !== "directory") {
+				throw new Error(
+					`Cannot create directory '${builtPath}': path is a file.`,
+				);
+			}
+			current = child as InternalDirectoryNode;
+		}
 	}
 
+	// ── Persistence ───────────────────────────────────────────────────────────
+
 	/**
-	 * Restores filesystem state from mirror archive.
+	 * In `"fs"` mode: reads the JSON snapshot from disk and hydrates the tree.
+	 * Silently succeeds when the snapshot file does not exist yet.
 	 *
-	 * If archive does not exist or cannot be read, creates fresh mirror file.
+	 * In `"memory"` mode: no-op (kept for API compatibility).
 	 */
 	public async restoreMirror(): Promise<void> {
-		perf.mark("restoreMirror");
-		this.ensureMirrorRoot();
+		if (this.mode !== "fs" || !this.snapshotFile) return;
+
+		if (!fsSync.existsSync(this.snapshotFile)) return;
+
+		try {
+			const raw = fsSync.readFileSync(this.snapshotFile, "utf8");
+			const snapshot: VfsSnapshot = JSON.parse(raw);
+			this.root = this.deserializeDir(snapshot.root, "");
+			this.emit("snapshot:restore", { path: this.snapshotFile });
+		} catch (err) {
+			// Corrupt or unreadable snapshot — start fresh and warn
+			console.warn(
+				`[VirtualFileSystem] Could not restore snapshot from ${this.snapshotFile}:`,
+				err instanceof Error ? err.message : String(err),
+			);
+		}
 	}
 
 	/**
-	 * Persists current filesystem state to mirror archive.
+	 * In `"fs"` mode: serialises the in-memory tree to a JSON snapshot on disk.
+	 * The directory is created if it does not exist.
 	 *
-	 * No-op when nothing changed and archive already exists.
+	 * In `"memory"` mode: emits `"mirror:flush"` and returns (no disk write).
 	 */
 	public async flushMirror(): Promise<void> {
-		perf.mark("flushMirror");
-		this.ensureMirrorRoot();
-		this.emit("mirror:flush");
+		if (this.mode !== "fs" || !this.snapshotFile) {
+			this.emit("mirror:flush");
+			return;
+		}
+
+		const dir = path.dirname(this.snapshotFile);
+		fsSync.mkdirSync(dir, { recursive: true });
+		const snapshot = this.toSnapshot();
+		fsSync.writeFileSync(this.snapshotFile, JSON.stringify(snapshot), "utf8");
+		this.emit("mirror:flush", { path: this.snapshotFile });
 	}
 
-	/**
-	 * Creates directory and any missing parent directories.
-	 *
-	 * @param targetPath Absolute or relative path to directory.
-	 * @param mode POSIX-like mode bits for new directories.
-	 */
+	/** Returns the current persistence mode. */
+	public getMode(): VfsPersistenceMode {
+		return this.mode;
+	}
+
+	/** Returns the snapshot file path used in `"fs"` mode, or `null`. */
+	public getSnapshotPath(): string | null {
+		return this.snapshotFile;
+	}
+
+	// ── Public filesystem API ─────────────────────────────────────────────────
+
+	/** Creates a directory (and any missing parents). */
 	public mkdir(targetPath: string, mode: number = 0o755): void {
-		perf.mark("mkdir");
-		this.ensureMirrorRoot();
-		const fsPath = this.resolveFsPath(targetPath);
-		if (fs.existsSync(fsPath) && !fs.statSync(fsPath).isDirectory()) {
+		const normalized = normalizePath(targetPath);
+		const existing = (() => {
+			try {
+				return getNode(this.root, normalized);
+			} catch {
+				return null;
+			}
+		})();
+		if (existing && existing.type !== "directory") {
 			throw new Error(
-				`Cannot create directory '${normalizePath(targetPath)}': path is a file.`,
+				`Cannot create directory '${normalized}': path is a file.`,
 			);
 		}
-		fs.mkdirSync(fsPath, { recursive: true, mode });
-		this.emit("dir:create", { path: normalizePath(targetPath), mode });
+		this.mkdirRecursive(normalized, mode);
 	}
 
 	/**
-	 * Writes UTF-8 text or binary content into file.
-	 *
+	 * Writes UTF-8 text or binary content into a file.
 	 * Parent directories are created when missing.
-	 *
-	 * @param targetPath Destination file path.
-	 * @param content File content as string or Buffer.
-	 * @param options Optional write behavior (mode, compression).
 	 */
 	public writeFile(
 		targetPath: string,
 		content: string | Buffer,
 		options: WriteFileOptions = {},
 	): void {
-		perf.mark("writeFile");
-		this.ensureMirrorRoot();
 		const normalized = normalizePath(targetPath);
-		const fsPath = this.resolveFsPath(normalized);
-		const parentPath = path.dirname(fsPath);
-		fs.mkdirSync(parentPath, { recursive: true, mode: 0o755 });
+		const { parent, name } = getParentDirectory(
+			this.root,
+			normalized,
+			true,
+			(p) => this.mkdirRecursive(p, 0o755),
+		);
+
+		const existing = parent.children.get(name);
+		if (existing?.type === "directory") {
+			throw new Error(
+				`Cannot write file '${normalized}': path is a directory.`,
+			);
+		}
 
 		const rawContent = Buffer.isBuffer(content)
 			? content
 			: Buffer.from(content, "utf8");
 		const shouldCompress = options.compress ?? false;
 		const storedContent = shouldCompress ? gzipSync(rawContent) : rawContent;
-
-		if (fs.existsSync(fsPath) && fs.statSync(fsPath).isDirectory()) {
-			throw new Error(
-				`Cannot write file '${normalized}': path is a directory.`,
+		const mode = options.mode ?? 0o644;
+
+		if (existing) {
+			const f = existing as InternalFileNode;
+			f.content = storedContent;
+			f.compressed = shouldCompress;
+			f.mode = mode;
+			f.updatedAt = new Date();
+		} else {
+			parent.children.set(
+				name,
+				this.makeFile(name, storedContent, mode, shouldCompress),
 			);
 		}
 
-		fs.writeFileSync(fsPath, storedContent);
-		fs.chmodSync(fsPath, options.mode ?? 0o644);
 		this.emit("file:write", { path: normalized, size: storedContent.length });
 	}
 
 	/**
-	 * Reads file content as UTF-8 text.
-	 *
-	 * Compressed files are transparently decompressed.
-	 *
-	 * @param targetPath Path to file.
-	 * @returns UTF-8 string content.
+	 * Reads file content as a UTF-8 string.
+	 * Gzip-compressed files are transparently decompressed.
 	 */
 	public readFile(targetPath: string): string {
-		perf.mark("readFile");
-		this.ensureMirrorRoot();
-		const fsPath = this.resolveFsPath(targetPath);
-		if (!fs.existsSync(fsPath) || !fs.statSync(fsPath).isFile()) {
+		const normalized = normalizePath(targetPath);
+		const node = getNode(this.root, normalized);
+		if (node.type !== "file") {
 			throw new Error(`Cannot read '${targetPath}': not a file.`);
 		}
+		const f = node as InternalFileNode;
+		const raw = f.compressed ? gunzipSync(f.content) : f.content;
+		this.emit("file:read", { path: normalized, size: raw.length });
+		return raw.toString("utf8");
+	}
 
-		const stored = fs.readFileSync(fsPath);
-		const raw = this.detectGzipFile(fsPath) ? gunzipSync(stored) : stored;
+	/** Reads file content as a Buffer (decompresses if needed). */
+	public readFileRaw(targetPath: string): Buffer {
 		const normalized = normalizePath(targetPath);
+		const node = getNode(this.root, normalized);
+		if (node.type !== "file") {
+			throw new Error(`Cannot read '${targetPath}': not a file.`);
+		}
+		const f = node as InternalFileNode;
+		const raw = f.compressed ? gunzipSync(f.content) : f.content;
 		this.emit("file:read", { path: normalized, size: raw.length });
-		return raw.toString("utf8");
+		return raw;
 	}
 
-	/**
-	 * Checks whether node exists at path.
-	 *
-	 * @param targetPath Node path.
-	 * @returns True when file or directory exists.
-	 */
+	/** Returns true when a file or directory exists at path. */
 	public exists(targetPath: string): boolean {
-		perf.mark("exists");
 		try {
-			const fsPath = this.resolveFsPath(targetPath);
-			return fs.existsSync(fsPath);
+			getNode(this.root, normalizePath(targetPath));
+			return true;
 		} catch {
 			return false;
 		}
 	}
 
-	/**
-	 * Updates mode bits for file or directory.
-	 *
-	 * @param targetPath Node path.
-	 * @param mode New POSIX-like mode.
-	 */
+	/** Updates mode bits on a node. */
 	public chmod(targetPath: string, mode: number): void {
-		perf.mark("chmod");
-		const fsPath = this.resolveFsPath(targetPath);
-		if (!fs.existsSync(fsPath)) {
-			throw new Error(`Path '${normalizePath(targetPath)}' does not exist.`);
-		}
-		fs.chmodSync(fsPath, mode);
+		getNode(this.root, normalizePath(targetPath)).mode = mode;
 	}
 
-	/**
-	 * Returns metadata for file or directory.
-	 *
-	 * @param targetPath Node path.
-	 * @returns Typed stat object based on node type.
-	 */
+	/** Returns metadata for a file or directory. */
 	public stat(targetPath: string): VfsNodeStats {
-		perf.mark("stat");
-		this.ensureMirrorRoot();
 		const normalized = normalizePath(targetPath);
-		const fsPath = this.resolveFsPath(normalized);
-
-		if (!fs.existsSync(fsPath)) {
-			throw new Error(`Path '${normalized}' does not exist.`);
-		}
-
-		const stats = fs.statSync(fsPath);
-		const mode = stats.mode & 0o777;
+		const node = getNode(this.root, normalized);
 		const name = normalized === "/" ? "" : path.posix.basename(normalized);
-
-		if (stats.isFile()) {
+		if (node.type === "file") {
+			const f = node as InternalFileNode;
 			return {
 				type: "file",
 				name,
 				path: normalized,
-				mode,
-				createdAt: stats.birthtime,
-				updatedAt: stats.mtime,
-				compressed: this.detectGzipFile(fsPath),
-				size: stats.size,
+				mode: f.mode,
+				createdAt: f.createdAt,
+				updatedAt: f.updatedAt,
+				compressed: f.compressed,
+				size: f.content.length,
 			};
 		}
-
+		const d = node as InternalDirectoryNode;
 		return {
 			type: "directory",
 			name,
 			path: normalized,
-			mode,
-			createdAt: stats.birthtime,
-			updatedAt: stats.mtime,
-			childrenCount: fs.readdirSync(fsPath).length,
+			mode: d.mode,
+			createdAt: d.createdAt,
+			updatedAt: d.updatedAt,
+			childrenCount: d.children.size,
 		};
 	}
 
-	/**
-	 * Lists direct children names of directory.
-	 *
-	 * @param dirPath Directory path, defaults to root.
-	 * @returns Sorted child names.
-	 */
+	/** Lists direct children names of a directory (sorted). */
 	public list(dirPath: string = "/"): string[] {
-		perf.mark("list");
-		const fsPath = this.resolveFsPath(dirPath);
-		if (!fs.existsSync(fsPath) || !fs.statSync(fsPath).isDirectory()) {
+		const normalized = normalizePath(dirPath);
+		const node = getNode(this.root, normalized);
+		if (node.type !== "directory") {
 			throw new Error(`Cannot list '${dirPath}': not a directory.`);
 		}
-
-		return fs.readdirSync(fsPath).sort();
+		return Array.from((node as InternalDirectoryNode).children.keys()).sort();
 	}
 
-	/**
-	 * Renders ASCII tree view of directory hierarchy.
-	 *
-	 * @param dirPath Directory path, defaults to root.
-	 * @returns Multi-line tree string.
-	 */
+	/** Renders ASCII tree view of a directory hierarchy. */
 	public tree(dirPath: string = "/"): string {
-		perf.mark("tree");
-		const fsPath = this.resolveFsPath(dirPath);
-		if (!fs.existsSync(fsPath) || !fs.statSync(fsPath).isDirectory()) {
+		const normalized = normalizePath(dirPath);
+		const node = getNode(this.root, normalized);
+		if (node.type !== "directory") {
 			throw new Error(`Cannot render tree for '${dirPath}': not a directory.`);
 		}
+		const label = dirPath === "/" ? "/" : path.posix.basename(normalized);
+		return this.renderTreeLines(node as InternalDirectoryNode, label);
+	}
 
-		const rootLabel =
-			dirPath === "/" ? "/" : path.posix.basename(normalizePath(dirPath));
-		return this.renderTreeLines(fsPath, rootLabel);
+	private renderTreeLines(dir: InternalDirectoryNode, label: string): string {
+		const lines = [label];
+		const entries = Array.from(dir.children.keys()).sort();
+		for (let i = 0; i < entries.length; i++) {
+			const name = entries[i]!;
+			const child = dir.children.get(name)!;
+			const isLast = i === entries.length - 1;
+			const connector = isLast ? "└── " : "├── ";
+			const nextPrefix = isLast ? "    " : "│   ";
+			lines.push(`${connector}${name}`);
+			if (child.type === "directory") {
+				const sub = this.renderTreeLines(child as InternalDirectoryNode, "")
+					.split("\n")
+					.slice(1)
+					.map((l) => `${nextPrefix}${l}`);
+				lines.push(...sub);
+			}
+		}
+		return lines.join("\n");
 	}
 
-	/**
-	 * Computes total stored file bytes under a path.
-	 *
-	 * File usage is based on in-memory stored bytes, including compressed
-	 * payload size when files are marked as compressed.
-	 *
-	 * @param targetPath File or directory path to measure, defaults to root.
-	 * @returns Total byte usage for file content under target path.
-	 */
+	/** Computes total stored bytes under a path. */
 	public getUsageBytes(targetPath: string = "/"): number {
-		perf.mark("getUsageBytes");
-		const fsPath = this.resolveFsPath(targetPath);
-		if (!fs.existsSync(fsPath)) {
-			throw new Error(`Path '${normalizePath(targetPath)}' does not exist.`);
+		return this.computeUsage(getNode(this.root, normalizePath(targetPath)));
+	}
+
+	private computeUsage(node: InternalNode): number {
+		if (node.type === "file") return (node as InternalFileNode).content.length;
+		let total = 0;
+		for (const child of (node as InternalDirectoryNode).children.values()) {
+			total += this.computeUsage(child);
 		}
-		return this.computeDiskUsageBytes(fsPath);
+		return total;
 	}
 
-	/**
-	 * Compresses file content with gzip and flags node as compressed.
-	 *
-	 * @param targetPath Path to file.
-	 */
+	/** Compresses a file's content with gzip in place. */
 	public compressFile(targetPath: string): void {
-		perf.mark("compressFile");
-		const fsPath = this.resolveFsPath(targetPath);
-		if (!fs.existsSync(fsPath) || !fs.statSync(fsPath).isFile()) {
+		const node = getNode(this.root, normalizePath(targetPath));
+		if (node.type !== "file")
 			throw new Error(`Cannot compress '${targetPath}': not a file.`);
+		const f = node as InternalFileNode;
+		if (!f.compressed) {
+			f.content = gzipSync(f.content);
+			f.compressed = true;
+			f.updatedAt = new Date();
 		}
+	}
 
-		if (!this.detectGzipFile(fsPath)) {
-			const content = fs.readFileSync(fsPath);
-			fs.writeFileSync(fsPath, gzipSync(content));
+	/** Decompresses a gzip-compressed file in place. */
+	public decompressFile(targetPath: string): void {
+		const node = getNode(this.root, normalizePath(targetPath));
+		if (node.type !== "file")
+			throw new Error(`Cannot decompress '${targetPath}': not a file.`);
+		const f = node as InternalFileNode;
+		if (f.compressed) {
+			f.content = gunzipSync(f.content);
+			f.compressed = false;
+			f.updatedAt = new Date();
 		}
 	}
 
 	/**
-	 * Decompresses gzip-compressed file content.
-	 *
-	 * @param targetPath Path to file.
+	 * Creates a symbolic link.
+	 * The link node is stored with mode `0o120777` (POSIX symlink convention).
 	 */
-	public decompressFile(targetPath: string): void {
-		perf.mark("decompressFile");
-		const fsPath = this.resolveFsPath(targetPath);
-		if (!fs.existsSync(fsPath) || !fs.statSync(fsPath).isFile()) {
-			throw new Error(`Cannot decompress '${targetPath}': not a file.`);
-		}
+	public symlink(targetPath: string, linkPath: string): void {
+		const normalizedLink = normalizePath(linkPath);
+		const normalizedTarget = targetPath.startsWith("/")
+			? normalizePath(targetPath)
+			: targetPath;
+		const { parent, name } = getParentDirectory(
+			this.root,
+			normalizedLink,
+			true,
+			(p) => this.mkdirRecursive(p, 0o755),
+		);
+		const symNode: InternalFileNode = {
+			type: "file",
+			name,
+			content: Buffer.from(normalizedTarget, "utf8"),
+			mode: 0o120777,
+			compressed: false,
+			createdAt: new Date(),
+			updatedAt: new Date(),
+		};
+		parent.children.set(name, symNode);
+		this.emit("symlink:create", {
+			link: normalizedLink,
+			target: normalizedTarget,
+		});
+	}
 
-		if (this.detectGzipFile(fsPath)) {
-			const content = fs.readFileSync(fsPath);
-			fs.writeFileSync(fsPath, gunzipSync(content));
+	/** Returns true when the path is a symbolic link node. */
+	public isSymlink(targetPath: string): boolean {
+		try {
+			const node = getNode(this.root, normalizePath(targetPath));
+			return node.type === "file" && node.mode === 0o120777;
+		} catch {
+			return false;
 		}
 	}
 
 	/**
-	 * Removes file or directory node.
-	 *
-	 * @param targetPath Path to remove.
-	 * @param options Removal options, including recursive delete.
+	 * Resolves a symlink chain up to `maxDepth` hops.
+	 * Throws when the chain is too long (circular links).
 	 */
-	public remove(targetPath: string, options: RemoveOptions = {}): void {
-		perf.mark("remove");
-		const normalized = normalizePath(targetPath);
-		if (normalized === "/") {
-			throw new Error("Cannot remove root directory.");
-		}
-		const fsPath = this.resolveFsPath(normalized);
-
-		if (!fs.existsSync(fsPath)) {
-			throw new Error(`Path '${normalized}' does not exist.`);
+	public resolveSymlink(linkPath: string, maxDepth = 8): string {
+		let current = normalizePath(linkPath);
+		for (let depth = 0; depth < maxDepth; depth++) {
+			try {
+				const node = getNode(this.root, current);
+				if (node.type === "file" && node.mode === 0o120777) {
+					const target = (node as InternalFileNode).content.toString("utf8");
+					current = target.startsWith("/")
+						? target
+						: normalizePath(
+								path.posix.join(path.posix.dirname(current), target),
+							);
+					continue;
+				}
+			} catch {
+				break;
+			}
+			return current;
 		}
+		throw new Error(`Too many levels of symbolic links: ${linkPath}`);
+	}
 
-		const stats = fs.statSync(fsPath);
-		if (stats.isDirectory() && !options.recursive) {
-			const entries = fs.readdirSync(fsPath);
-			if (entries.length > 0) {
+	/** Removes a file or directory node. */
+	public remove(targetPath: string, options: RemoveOptions = {}): void {
+		const normalized = normalizePath(targetPath);
+		if (normalized === "/") throw new Error("Cannot remove root directory.");
+		const node = getNode(this.root, normalized);
+		if (node.type === "directory") {
+			const dir = node as InternalDirectoryNode;
+			if (!options.recursive && dir.children.size > 0) {
 				throw new Error(
 					`Directory '${normalized}' is not empty. Use recursive option.`,
 				);
 			}
 		}
-
-		if (stats.isDirectory()) {
-			fs.rmSync(fsPath, { recursive: options.recursive ?? false });
-		} else {
-			fs.rmSync(fsPath);
-		}
+		const { parent, name } = getParentDirectory(
+			this.root,
+			normalized,
+			false,
+			() => {},
+		);
+		parent.children.delete(name);
+		this.emit("node:remove", { path: normalized });
 	}
 
-	/**
-	 * Moves or renames node to destination path.
-	 *
-	 * @param fromPath Existing source path.
-	 * @param toPath Destination path.
-	 */
+	/** Moves or renames a node. */
 	public move(fromPath: string, toPath: string): void {
-		perf.mark("move");
 		const fromNormalized = normalizePath(fromPath);
 		const toNormalized = normalizePath(toPath);
-
 		if (fromNormalized === "/" || toNormalized === "/") {
 			throw new Error("Cannot move root directory.");
 		}
+		const node = getNode(this.root, fromNormalized);
+		if (this.exists(toNormalized)) {
+			throw new Error(`Destination '${toNormalized}' already exists.`);
+		}
+		this.mkdirRecursive(path.posix.dirname(toNormalized), 0o755);
+		const { parent: destParent, name: destName } = getParentDirectory(
+			this.root,
+			toNormalized,
+			false,
+			() => {},
+		);
+		const { parent: srcParent, name: srcName } = getParentDirectory(
+			this.root,
+			fromNormalized,
+			false,
+			() => {},
+		);
+		srcParent.children.delete(srcName);
+		node.name = destName;
+		destParent.children.set(destName, node);
+	}
 
-		const fromFsPath = this.resolveFsPath(fromNormalized);
-		const toFsPath = this.resolveFsPath(toNormalized);
+	// ── Snapshot serialisation ─────────────────────────────────────────────────
 
-		if (!fs.existsSync(fromFsPath)) {
-			throw new Error(`Path '${fromNormalized}' does not exist.`);
-		}
+	/**
+	 * Exports the entire filesystem as a JSON-serialisable snapshot.
+	 *
+	 * Works regardless of the persistence mode. Useful for test fixtures,
+	 * manual backups, or passing VFS state between processes.
+	 */
+	public toSnapshot(): VfsSnapshot {
+		return { root: this.serializeDir(this.root) };
+	}
 
-		if (fs.existsSync(toFsPath)) {
-			throw new Error(`Destination '${toNormalized}' already exists.`);
+	private serializeDir(dir: InternalDirectoryNode): VfsSnapshotDirectoryNode {
+		const children: VfsSnapshotNode[] = [];
+		for (const child of dir.children.values()) {
+			children.push(
+				child.type === "file"
+					? this.serializeFile(child as InternalFileNode)
+					: this.serializeDir(child as InternalDirectoryNode),
+			);
 		}
+		return {
+			type: "directory",
+			name: dir.name,
+			mode: dir.mode,
+			createdAt: dir.createdAt.toISOString(),
+			updatedAt: dir.updatedAt.toISOString(),
+			children,
+		};
+	}
+
+	private serializeFile(file: InternalFileNode): VfsSnapshotFileNode {
+		return {
+			type: "file",
+			name: file.name,
+			mode: file.mode,
+			createdAt: file.createdAt.toISOString(),
+			updatedAt: file.updatedAt.toISOString(),
+			compressed: file.compressed,
+			contentBase64: file.content.toString("base64"),
+		};
+	}
+
+	/**
+	 * Creates a new `VirtualFileSystem` instance (memory mode) from a snapshot.
+	 *
+	 * @example
+	 * ```ts
+	 * const vfs = VirtualFileSystem.fromSnapshot(savedSnapshot);
+	 * ```
+	 */
+	public static fromSnapshot(snapshot: VfsSnapshot): VirtualFileSystem {
+		const vfs = new VirtualFileSystem();
+		vfs.root = vfs.deserializeDir(snapshot.root, "");
+		return vfs;
+	}
+
+	/**
+	 * Replaces the current filesystem state with the content of a snapshot.
+	 * The persistence mode is preserved.
+	 *
+	 * @example
+	 * ```ts
+	 * vfs.importSnapshot(savedSnapshot);
+	 * ```
+	 */
+	public importSnapshot(snapshot: VfsSnapshot): void {
+		this.root = this.deserializeDir(snapshot.root, "");
+		this.emit("snapshot:import");
+	}
 
-		fs.mkdirSync(path.dirname(toFsPath), { recursive: true, mode: 0o755 });
-		fs.renameSync(fromFsPath, toFsPath);
+	private deserializeDir(
+		snap: VfsSnapshotDirectoryNode,
+		name: string,
+	): InternalDirectoryNode {
+		const dir: InternalDirectoryNode = {
+			type: "directory",
+			name,
+			mode: snap.mode,
+			createdAt: new Date(snap.createdAt),
+			updatedAt: new Date(snap.updatedAt),
+			children: new Map(),
+		};
+		for (const child of snap.children) {
+			if (child.type === "file") {
+				const f = child as VfsSnapshotFileNode;
+				dir.children.set(f.name, {
+					type: "file",
+					name: f.name,
+					mode: f.mode,
+					createdAt: new Date(f.createdAt),
+					updatedAt: new Date(f.updatedAt),
+					compressed: f.compressed,
+					content: Buffer.from(f.contentBase64, "base64"),
+				});
+			} else {
+				const sub = this.deserializeDir(
+					child as VfsSnapshotDirectoryNode,
+					child.name,
+				);
+				dir.children.set(child.name, sub);
+			}
+		}
+		return dir;
 	}
 }