@powerlines/plugin-webpack 0.5.132 → 0.5.134

package/dist/powerlines/src/lib/fs/vfs.mjs

@@ -0,0 +1,828 @@
+import { replacePathTokens } from "../../plugin-utils/paths.mjs";
+import { FileSystem } from "../../../schemas/fs.mjs";
+import { extendLog } from "../logger.mjs";
+import { normalizeGlobPatterns, normalizeId, normalizePath } from "./helpers.mjs";
+import { FileSystemStorageAdapter } from "./storage/file-system.mjs";
+import { VirtualStorageAdapter } from "./storage/virtual.mjs";
+import { LogLevelLabel } from "@storm-software/config-tools/types";
+import { joinPaths } from "@stryke/path/join-paths";
+import { toArray } from "@stryke/convert/to-array";
+import { getResolutionCombinations, resolve, resolveSync } from "@stryke/fs/resolve";
+import { appendPath } from "@stryke/path/append";
+import { replacePath } from "@stryke/path/replace";
+import { isSetObject } from "@stryke/type-checks/is-set-object";
+import { isSetString } from "@stryke/type-checks/is-set-string";
+import { isString } from "@stryke/type-checks/is-string";
+import { findFileName, findFilePath, hasFileExtension } from "@stryke/path/file-path-fns";
+import { existsSync } from "@stryke/fs/exists";
+import { murmurhash } from "@stryke/hash/murmurhash";
+import { getUnique } from "@stryke/helpers/get-unique";
+import { isParentPath } from "@stryke/path/is-parent-path";
+import { isAbsolutePath } from "@stryke/path/is-type";
+import { create } from "flat-cache";
+import * as capnp from "@stryke/capnp";
+import { readFileBuffer, readFileBufferSync, writeFileBuffer } from "@stryke/fs/buffer";
+import { prettyBytes } from "@stryke/string-format/pretty-bytes";
+import { isRegExp } from "@stryke/type-checks/is-regexp";
+import { Blob } from "node:buffer";
+import { fileURLToPath } from "node:url";
+import { format, resolveConfig } from "prettier";
+
+//#region ../powerlines/src/lib/fs/vfs.ts
+/**
+* Represents a virtual file system (VFS) that stores files and their associated metadata in virtual memory.
+*
+* @remarks
+* This class provides methods to manage virtual files, check their existence, retrieve their content, and manipulate the virtual file system. It allows for efficient file management and retrieval without relying on the actual file system.
+*/
+var VirtualFileSystem = class VirtualFileSystem {
+	/**
+	* A map of virtual file IDs to their associated metadata.
+	*/
+	#metadata;
+	/**
+	* A map of virtual file IDs to their underlying file paths.
+	*/
+	#ids;
+	/**
+	* A map of underlying file paths to their virtual file IDs.
+	*/
+	#paths;
+	/**
+	* The unified volume that combines the virtual file system with the real file system.
+	*
+	* @remarks
+	* This volume allows for seamless access to both virtual and real files.
+	*/
+	#storage = { "": new FileSystemStorageAdapter() };
+	/**
+	* A cache for module resolution results.
+	*/
+	#resolverCache;
+	/**
+	* Indicator specifying if the virtual file system (VFS) is disposed
+	*/
+	#isDisposed = false;
+	/**
+	* The context of the virtual file system.
+	*/
+	#context;
+	/**
+	* The file system's logging function.
+	*/
+	#log;
+	/**
+	* Normalizes a given module id by resolving it against the built-ins path.
+	*
+	* @param id - The module id to normalize.
+	* @returns The normalized module id.
+	*/
+	#normalizeId(id) {
+		let normalized = id;
+		if (isParentPath(normalized, this.#context.builtinsPath)) normalized = replacePath(normalized, this.#context.builtinsPath);
+		return normalizeId(normalized, this.#context.config.output.builtinPrefix);
+	}
+	/**
+	* Normalizes a given path by resolving it against the project root, workspace root, and built-ins path.
+	*
+	* @param path - The path to normalize.
+	* @returns The normalized path.
+	*/
+	#normalizePath(path) {
+		return normalizePath(path.includes("{") || path.includes("}") ? replacePathTokens(this.#context, path) : path, this.#context.builtinsPath, this.#context.config.output.builtinPrefix);
+	}
+	/**
+	* Builds a regular expression from a string pattern for path matching.
+	*
+	* @param path - The string pattern to convert.
+	* @returns A regular expression for matching paths.
+	*/
+	#buildRegex(path) {
+		const token = "::GLOBSTAR::";
+		return /* @__PURE__ */ new RegExp(`^${this.#normalizePath(path).replace(/\*\*/g, token).replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, "[^/]*").replace(/\?/g, "[^/]").replace(new RegExp(token, "g"), ".*")}$`);
+	}
+	/**
+	* Gets the storage adapter and relative key for a given key.
+	*
+	* @remarks
+	* The `key` can be either a path or a storage adapter name.
+	*
+	* @param key - The key to get the storage adapter for.
+	* @returns The storage adapter and relative key for the given key.
+	*/
+	#getStorage(key) {
+		const found = Object.entries(this.#storage).find(([, adapter]) => adapter.name === key || adapter.preset && adapter.preset.toLowerCase() === key?.toLowerCase());
+		if (found) return {
+			base: found[0],
+			relativeKey: "",
+			adapter: found[1]
+		};
+		const path = this.resolveSync(this.#normalizePath(key)) || key;
+		for (const base of Object.keys(this.#storage).filter(Boolean).sort().reverse()) if (isParentPath(path, base)) return {
+			base,
+			relativeKey: replacePath(path, base),
+			adapter: this.#storage[base]
+		};
+		return {
+			base: "",
+			relativeKey: path,
+			adapter: this.#storage[""]
+		};
+	}
+	/**
+	* Gets all storage adapters that match a given base key.
+	*
+	* @param base - The base key to match storage adapters against.
+	* @param includeParent - Whether to include parent storage adapters.
+	* @returns An array of storage adapters that match the given base key.
+	*/
+	#getStorages(base = "", includeParent = false) {
+		return Object.keys(this.#storage).sort().reverse().filter((key) => isParentPath(key, base) || includeParent && isParentPath(base, key)).map((key) => ({
+			relativeBase: base.length > key.length ? base.slice(key.length) : void 0,
+			base: key,
+			adapter: this.#storage[key]
+		}));
+	}
+	/**
+	* Creates a virtual file system (VFS) that is backed up to a Cap'n Proto message buffer.
+	*
+	* @param context - The context of the virtual file system, typically containing options and logging functions.
+	* @returns A promise that resolves to a new virtual file system instance.
+	*/
+	static async create(context) {
+		if (!context.config.skipCache && existsSync(joinPaths(context.dataPath, "fs.bin"))) {
+			const buffer = await readFileBuffer(joinPaths(context.dataPath, "fs.bin"));
+			const fs = new capnp.Message(buffer, false).getRoot(FileSystem);
+			const result = new VirtualFileSystem(context, fs);
+			if (fs._hasStorage() && fs.storage.length > 0) await Promise.all(fs.storage.values().map(async (file) => {
+				await result.write(file.path, file.code);
+			}));
+		}
+		return new VirtualFileSystem(context, new capnp.Message().initRoot(FileSystem));
+	}
+	/**
+	* Synchronously creates a virtual file system (VFS) that is backed up to a Cap'n Proto message buffer.
+	*
+	* @param context - The context of the virtual file system, typically containing options and logging functions.
+	* @returns A new virtual file system instance.
+	*/
+	static createSync(context) {
+		if (!context.config.skipCache && existsSync(joinPaths(context.dataPath, "fs.bin"))) {
+			const buffer = readFileBufferSync(joinPaths(context.dataPath, "fs.bin"));
+			const fs = new capnp.Message(buffer, false).getRoot(FileSystem);
+			const result = new VirtualFileSystem(context, fs);
+			if (fs._hasStorage() && fs.storage.length > 0) fs.storage.values().map((file) => {
+				result.writeSync(file.path, file.code);
+			});
+		}
+		return new VirtualFileSystem(context, new capnp.Message().initRoot(FileSystem));
+	}
+	/**
+	* A map of file ids to their metadata.
+	*/
+	get metadata() {
+		return new Proxy(this.#metadata, { get: (target, prop) => {
+			return target[this.#normalizeId(prop)];
+		} });
+	}
+	/**
+	* A map of file paths to their module ids.
+	*/
+	get ids() {
+		return new Proxy(this.#paths, { get: (target, prop) => {
+			return target[this.#normalizePath(prop)];
+		} });
+	}
+	/**
+	* A map of module ids to their file paths.
+	*/
+	get paths() {
+		return new Proxy(this.#paths, { get: (target, prop) => {
+			return target[this.#normalizeId(prop)];
+		} });
+	}
+	/**
+	* Gets the resolver cache.
+	*/
+	get resolverCache() {
+		if (!this.#resolverCache) this.#resolverCache = create({
+			cacheId: "module-resolution",
+			cacheDir: this.#context.cachePath,
+			ttl: 3600 * 1e3,
+			lruSize: 5e3,
+			persistInterval: 100
+		});
+		return this.#resolverCache;
+	}
+	/**
+	* Creates a new instance of the {@link VirtualFileSystem}.
+	*
+	* @param context - The context of the virtual file system, typically containing options and logging functions.
+	* @param fs - A buffer containing the serialized virtual file system data.
+	*/
+	constructor(context, fs) {
+		this.#context = context;
+		if (isSetObject(this.#context.config.output.storage)) this.#storage = {
+			...this.#storage,
+			...this.#context.config.output.storage
+		};
+		this.#storage.virtual ??= new VirtualStorageAdapter({ base: "/_virtual" });
+		if (this.#context.config.output.storage !== "fs") {
+			this.#storage[this.#context.artifactsPath] ??= new VirtualStorageAdapter({ base: this.#context.artifactsPath });
+			this.#storage[this.#context.builtinsPath] ??= new VirtualStorageAdapter({ base: this.#context.builtinsPath });
+			this.#storage[this.#context.entryPath] ??= new VirtualStorageAdapter({ base: this.#context.entryPath });
+		}
+		this.#metadata = {};
+		if (fs._hasMetadata()) {
+			this.#metadata = fs.metadata.values().reduce((ret, metadata) => {
+				ret[metadata.id] = {
+					id: metadata.id,
+					type: metadata.type,
+					timestamp: metadata.timestamp || Date.now(),
+					properties: metadata._hasProperties() ? metadata.properties.values().reduce((ret$1, item) => {
+						ret$1[item.key] = item.value;
+						return ret$1;
+					}, {}) : {}
+				};
+				return ret;
+			}, {});
+			if (context.config.skipCache !== true) Object.entries(this.#metadata).filter(([, value]) => value.type === "entry").forEach(([id, value]) => {
+				this.#context.entry ??= [];
+				this.#context.entry.push({
+					file: id,
+					name: value.properties.name,
+					output: value.properties.output,
+					input: value.properties["input.file"] ? {
+						file: value.properties["input.file"],
+						name: value.properties["input.name"]
+					} : void 0
+				});
+			});
+		}
+		this.#ids = {};
+		this.#paths = {};
+		if (fs._hasIds()) {
+			this.#ids = fs.ids.values().reduce((ret, identifier) => {
+				ret[identifier.path] ??= identifier.id;
+				return ret;
+			}, {});
+			this.#paths = fs.ids.values().reduce((ret, identifier) => {
+				ret[identifier.id] ??= identifier.path;
+				return ret;
+			}, {});
+		}
+		this.#log = extendLog(this.#context.log, "file-system");
+	}
+	/**
+	* Asynchronously checks if a file exists in the virtual file system (VFS).
+	*
+	* @param path - The path to the file.
+	* @returns A promise that resolves to `true` if the file exists, otherwise `false`.
+	*/
+	async exists(path) {
+		const { relativeKey, adapter } = this.#getStorage(path);
+		return adapter.exists(relativeKey);
+	}
+	/**
+	* Synchronously checks if a file exists in the virtual file system (VFS).
+	*
+	* @param path - The path to the file.
+	* @returns `true` if the file exists, otherwise `false`.
+	*/
+	existsSync(path) {
+		const { relativeKey, adapter } = this.#getStorage(path);
+		return adapter.existsSync(relativeKey);
+	}
+	/**
+	* Checks if a file is virtual in the virtual file system (VFS).
+	*
+	* @param path - The path to the file.
+	* @returns `true` if the file is virtual, otherwise `false`.
+	*/
+	isVirtual(path) {
+		const resolved = this.resolveSync(path);
+		if (!resolved) return false;
+		return this.#getStorage(resolved)?.adapter?.name === "virtual";
+	}
+	/**
+	* Checks if a path is a directory in the virtual file system (VFS).
+	*
+	* @param path - The path to check.
+	* @returns `true` if the path is a directory, otherwise `false`.
+	*/
+	isDirectorySync(path) {
+		const resolved = this.resolveSync(path);
+		if (!resolved) return false;
+		return !!(this.existsSync(resolved) && this.#getStorage(resolved)?.adapter?.isDirectorySync(resolved));
+	}
+	/**
+	* Checks if a path is a directory in the virtual file system (VFS).
+	*
+	* @param path - The path to check.
+	* @returns `true` if the path is a directory, otherwise `false`.
+	*/
+	async isDirectory(path) {
+		const resolved = await this.resolve(path);
+		if (!resolved) return false;
+		return !!(await this.exists(resolved) && await this.#getStorage(resolved)?.adapter?.isDirectory(resolved));
+	}
+	/**
+	* Checks if a path is a file in the virtual file system (VFS).
+	*
+	* @param path - The path to check.
+	* @returns `true` if the path is a file, otherwise `false`.
+	*/
+	isFileSync(path) {
+		const resolved = this.resolveSync(path);
+		if (!resolved) return false;
+		return this.#getStorage(resolved)?.adapter?.isFileSync(resolved) ?? false;
+	}
+	/**
+	* Checks if a path is a file in the virtual file system (VFS).
+	*
+	* @param path - The path to check.
+	* @returns `true` if the path is a file, otherwise `false`.
+	*/
+	async isFile(path) {
+		const resolved = await this.resolve(path);
+		if (!resolved) return false;
+		return await this.#getStorage(resolved)?.adapter?.isFile(resolved) ?? false;
+	}
+	/**
+	* Lists files in a given path.
+	*
+	* @param path - The path to list files from.
+	* @returns An array of file names in the specified path.
+	*/
+	listSync(path) {
+		return getUnique(this.#getStorages(path, true).map((storage) => storage.adapter.listSync(storage.relativeBase ? storage.base ? appendPath(storage.relativeBase, storage.base) : storage.relativeBase : storage.base)).flat());
+	}
+	/**
+	* Lists files in a given path.
+	*
+	* @param path - The path to list files from.
+	* @returns An array of file names in the specified path.
+	*/
+	async list(path) {
+		return getUnique((await Promise.all(this.#getStorages(path, true).map(async (storage) => storage.adapter.list(storage.relativeBase ? storage.base ? appendPath(storage.relativeBase, storage.base) : storage.relativeBase : storage.base)))).flat());
+	}
+	/**
+	* Removes a file in the virtual file system (VFS).
+	*
+	* @param path - The path to create the directory at.
+	*/
+	async remove(path) {
+		const normalizedPath = this.#normalizePath(path);
+		this.#log(LogLevelLabel.TRACE, `Removing file: ${normalizedPath}`);
+		const { relativeKey, adapter } = this.#getStorage(normalizedPath);
+		if (hasFileExtension(normalizedPath)) await adapter.remove(relativeKey);
+		else await adapter.clear(relativeKey);
+		const id = this.#ids[normalizedPath];
+		if (id && this.#metadata[id]) {
+			delete this.#metadata[id];
+			delete this.#ids[normalizedPath];
+			delete this.#paths[id];
+		}
+	}
+	/**
+	* Removes a file in the virtual file system (VFS).
+	*
+	* @param path - The path to create the directory at.
+	*/
+	removeSync(path) {
+		const normalizedPath = this.#normalizePath(path);
+		this.#log(LogLevelLabel.TRACE, `Removing file: ${normalizedPath}`);
+		const { relativeKey, adapter } = this.#getStorage(normalizedPath);
+		if (hasFileExtension(normalizedPath)) adapter.removeSync(relativeKey);
+		else adapter.clearSync(relativeKey);
+		const id = this.#ids[normalizedPath];
+		if (id && this.#metadata[id]) {
+			delete this.#metadata[id];
+			delete this.#ids[normalizedPath];
+			delete this.#paths[id];
+		}
+	}
+	/**
+	* Glob files in the virtual file system (VFS) based on the provided pattern(s).
+	*
+	* @param patterns - A pattern (or multiple patterns) to use to determine the file paths to return
+	* @returns An array of file paths matching the provided pattern(s)
+	*/
+	async glob(patterns) {
+		const results = [];
+		for (const pattern of normalizeGlobPatterns(this.#context.workspaceConfig.workspaceRoot, patterns)) {
+			const normalized = this.#normalizePath(pattern);
+			if (!/[*?[\]{}]/.test(normalized) && !normalized.includes("**")) {
+				if (this.isDirectorySync(normalized)) results.push(...await this.list(normalized));
+				else {
+					const resolved = await this.resolve(normalized);
+					if (resolved && !results.includes(resolved)) results.push(resolved);
+				}
+				continue;
+			}
+			const absPattern = isAbsolutePath(normalized) ? normalized : this.#normalizePath(joinPaths(this.#context.workspaceConfig.workspaceRoot, normalized));
+			const firstGlobIdx = absPattern.search(/[*?[\]{}]/);
+			const baseDir = firstGlobIdx === -1 ? findFilePath(absPattern) : absPattern.slice(0, Math.max(0, absPattern.lastIndexOf("/", firstGlobIdx)));
+			await Promise.all((await this.list(baseDir && isAbsolutePath(baseDir) ? baseDir : this.#context.workspaceConfig.workspaceRoot)).map(async (file) => {
+				if (this.#buildRegex(absPattern).test(file)) {
+					const resolved = this.resolveSync(file);
+					if (resolved && !results.includes(resolved)) results.push(resolved);
+				}
+			}));
+		}
+		return results;
+	}
+	/**
+	* Synchronously glob files in the virtual file system (VFS) based on the provided pattern(s).
+	*
+	* @param patterns - A pattern (or multiple patterns) to use to determine the file paths to return
+	* @returns An array of file paths matching the provided pattern(s)
+	*/
+	globSync(patterns) {
+		const results = [];
+		for (const pattern of normalizeGlobPatterns(this.#context.workspaceConfig.workspaceRoot, patterns)) {
+			const normalized = this.#normalizePath(pattern);
+			if (!/[*?[\]{}]/.test(normalized) && !normalized.includes("**")) {
+				if (this.isDirectorySync(normalized)) results.push(...this.listSync(normalized));
+				else {
+					const resolved = this.resolveSync(normalized);
+					if (resolved && !results.includes(resolved)) results.push(resolved);
+				}
+				continue;
+			}
+			const absPattern = isAbsolutePath(normalized) ? normalized : this.#normalizePath(joinPaths(this.#context.workspaceConfig.workspaceRoot, normalized));
+			const firstGlobIdx = absPattern.search(/[*?[\]{}]/);
+			const baseDir = firstGlobIdx === -1 ? findFilePath(absPattern) : absPattern.slice(0, Math.max(0, absPattern.lastIndexOf("/", firstGlobIdx)));
+			const files = this.listSync(baseDir && isAbsolutePath(baseDir) ? baseDir : this.#context.workspaceConfig.workspaceRoot);
+			for (const file of files) if (this.#buildRegex(absPattern).test(file)) {
+				const resolved = this.resolveSync(file);
+				if (resolved && !results.includes(resolved)) results.push(resolved);
+			}
+		}
+		return results;
+	}
+	/**
+	* Copies a file from one path to another in the virtual file system (VFS).
+	*
+	* @param srcPath - The source path to copy
+	* @param destPath - The destination path to copy to
+	*/
+	async copy(srcPath, destPath) {
+		const src = srcPath instanceof URL ? fileURLToPath(srcPath) : srcPath;
+		const dest = destPath instanceof URL ? fileURLToPath(destPath) : destPath;
+		if (!isSetString(src) && (!isSetObject(src) || !isSetString(src.input)) || !isSetString(dest)) return;
+		const sourceStr = isString(src) ? src : src.input ? src.input : this.#context.workspaceConfig.workspaceRoot;
+		const source = await this.resolve(sourceStr);
+		if (!source) return;
+		if (this.isDirectorySync(source) || isSetString(src) && src.includes("*") || isSetObject(src) && isSetString(src.glob)) await Promise.all((await this.glob(src)).map(async (file) => {
+			return this.copy(file, appendPath(replacePath(file, sourceStr), dest));
+		}));
+		else {
+			const content = await this.read(source);
+			if (content !== void 0) await this.write(this.#normalizePath(dest), content, { skipFormat: true });
+		}
+	}
+	/**
+	* Synchronously copies a file from one path to another in the virtual file system (VFS).
+	*
+	* @param srcPath - The source path to copy
+	* @param destPath - The destination path to copy to
+	*/
+	copySync(srcPath, destPath) {
+		const src = srcPath instanceof URL ? fileURLToPath(srcPath) : srcPath;
+		const dest = destPath instanceof URL ? fileURLToPath(destPath) : destPath;
+		if (!isSetString(src) && (!isSetObject(src) || !isSetString(src.input)) || !isSetString(dest)) return;
+		const sourceStr = isString(src) ? src : src.input ? src.input : this.#context.workspaceConfig.workspaceRoot;
+		const source = this.resolveSync(sourceStr);
+		if (!source) return;
+		if (this.isDirectorySync(source) || isSetString(src) && src.includes("*") || isSetObject(src) && isSetString(src.glob)) this.globSync(src).map((file) => {
+			return this.copySync(file, appendPath(findFilePath(replacePath(file, sourceStr)), dest));
+		});
+		else {
+			const content = this.readSync(source);
+			if (content !== void 0) this.writeSync(this.#normalizePath(hasFileExtension(dest) ? dest : appendPath(findFileName(source), dest)), content, { skipFormat: true });
+		}
+	}
+	/**
+	* Moves a file (or files) from one path to another in the virtual file system (VFS).
+	*
+	* @param srcPath - The source path to move
+	* @param destPath - The destination path to move to
+	*/
+	async move(srcPath, destPath) {
+		if (hasFileExtension(srcPath)) {
+			await this.copy(srcPath, destPath);
+			await this.remove(srcPath);
+		} else await Promise.all((await this.list(srcPath)).map(async (file) => {
+			await this.copy(file, destPath);
+			await this.remove(file);
+		}));
+	}
+	/**
+	* Synchronously moves a file (or files) from one path to another in the virtual file system (VFS).
+	*
+	* @param srcPath - The source path to move
+	* @param destPath - The destination path to move to
+	*/
+	moveSync(srcPath, destPath) {
+		if (hasFileExtension(srcPath)) {
+			this.copySync(srcPath, destPath);
+			this.removeSync(srcPath);
+		} else this.listSync(srcPath).forEach((file) => {
+			this.copySync(file, destPath);
+			this.removeSync(file);
+		});
+	}
+	/**
+	* Asynchronously reads a file from the virtual file system (VFS).
+	*
+	* @param path - The path or ID of the file to read.
+	* @returns A promise that resolves to the contents of the file as a string, or undefined if the file does not exist.
+	*/
+	async read(path) {
+		const filePath = await this.resolve(path);
+		if (!filePath) return;
+		const { relativeKey, adapter } = this.#getStorage(filePath);
+		this.#log(LogLevelLabel.TRACE, `Reading ${adapter.name} file: ${filePath}`);
+		return await adapter.get(relativeKey) ?? void 0;
+	}
+	/**
+	* Synchronously reads a file from the virtual file system (VFS).
+	*
+	* @param path - The path or ID of the file to read.
+	* @returns The contents of the file as a string, or undefined if the file does not exist.
+	*/
+	readSync(path) {
+		const filePath = this.resolveSync(path);
+		if (!filePath) return;
+		const { relativeKey, adapter } = this.#getStorage(filePath);
+		this.#log(LogLevelLabel.TRACE, `Reading ${adapter.name} file: ${filePath}`);
+		return adapter.getSync(relativeKey) ?? void 0;
+	}
+	/**
+	* Writes a file to the virtual file system (VFS).
+	*
+	* @param path - The path to the file.
+	* @param data - The contents of the file.
+	* @param options - Optional parameters for writing the file.
+	* @returns A promise that resolves when the file is written.
+	*/
+	async write(path, data = "", options = {}) {
+		let code = data;
+		if (!options.skipFormat) {
+			const resolvedConfig = await resolveConfig(this.#normalizePath(path));
+			if (resolvedConfig) code = await format(data, {
+				absolutePath: this.#normalizePath(path),
+				...resolvedConfig
+			});
+		}
+		const { relativeKey, adapter } = this.#getStorage(options.storage || path);
+		this.#log(LogLevelLabel.TRACE, `Writing ${this.#normalizePath(relativeKey)} to ${adapter.name === "virtual" ? "the virtual file system" : adapter.name === "file-system" ? "the local file system" : adapter.name} (size: ${prettyBytes(new Blob(toArray(code)).size)})`);
+		const id = options?.meta?.id || this.#normalizeId(relativeKey);
+		this.#metadata[id] = {
+			variant: "normal",
+			timestamp: Date.now(),
+			...options.meta ?? {}
+		};
+		this.#paths[id] = this.#normalizePath(relativeKey);
+		this.#ids[this.#normalizePath(relativeKey)] = id;
+		return adapter.set(relativeKey, code);
+	}
+	/**
+	* Synchronously writes a file to the virtual file system (VFS).
+	*
+	* @param path - The file to write.
+	* @param data - The contents of the file.
+	* @param options - Optional parameters for writing the file.
+	*/
+	writeSync(path, data = "", options = {}) {
+		const { relativeKey, adapter } = this.#getStorage(options.storage || path);
+		this.#log(LogLevelLabel.TRACE, `Writing ${this.#normalizePath(relativeKey)} file to ${adapter.name === "virtual" ? "the virtual file system" : adapter.name === "file-system" ? "the local file system" : adapter.name} (size: ${prettyBytes(new Blob(toArray(data)).size)})`);
+		const id = options?.meta?.id || this.#normalizeId(relativeKey);
+		this.#metadata[id] = {
+			variant: "normal",
+			timestamp: Date.now(),
+			...options.meta ?? {}
+		};
+		this.#paths[id] = this.#normalizePath(relativeKey);
+		this.#ids[this.#normalizePath(relativeKey)] = id;
+		return adapter.setSync(relativeKey, data);
+	}
+	/**
+	* Synchronously creates a directory at the specified path.
+	*
+	* @param dirPath - The path of the directory to create.
+	*/
+	mkdirSync(dirPath) {
+		return this.#getStorage(dirPath)?.adapter?.mkdirSync(dirPath);
+	}
+	/**
+	* Creates a directory at the specified path.
+	*
+	* @param path - The path of the directory to create.
+	*/
+	async mkdir(path) {
+		return this.#getStorage(path)?.adapter?.mkdir(path);
+	}
+	/**
+	* Retrieves the metadata of a file in the virtual file system (VFS).
+	*
+	* @param pathOrId - The path or ID of the file to retrieve metadata for.
+	* @returns The metadata of the file, or undefined if the file does not exist.
+	*/
+	getMetadata(pathOrId) {
+		const resolved = this.resolveSync(pathOrId);
+		if (resolved && this.metadata[resolved]) return this.metadata[resolved];
+	}
+	/**
+	* Resolves a given module ID using the configured aliases.
+	*
+	* @remarks
+	* This function can be used to map module IDs to different paths based on the alias configuration.
+	*
+	* @param id - The module ID to resolve.
+	* @returns The resolved module ID - after applying any configured aliases (this will be the same as the input ID if no aliases match).
+	*/
+	resolveAlias(id) {
+		let path = id;
+		if (this.#context.config.build.alias) {
+			if (Array.isArray(this.#context.config.build.alias) && this.#context.config.build.alias.length > 0) {
+				const found = this.#context.config.build.alias.filter((alias) => isSetString(alias.find) && (alias.find === path || path.startsWith(`${alias.find}/`)) || isRegExp(alias.find) && alias.find.test(path));
+				if (found.length > 0) {
+					const alias = found.reduce((ret, current) => {
+						return (isSetString(ret.find) ? ret.find.length : isRegExp(ret.find) ? ret.find.source.length : 0) > (isSetString(current.find) ? current.find.length : isRegExp(current.find) ? current.find.source.length : 0) ? ret : current;
+					});
+					if (isSetString(alias.find)) path = path.replace(/* @__PURE__ */ new RegExp(`^${alias.find}`), alias.replacement);
+					else if (isRegExp(alias.find)) path = path.replace(alias.find, alias.replacement);
+				}
+			} else if (isSetObject(this.#context.config.build.alias)) {
+				const found = Object.keys(this.#context.config.build.alias).filter((key) => key === path || path.startsWith(`${key}/`));
+				if (found.length > 0) {
+					const alias = found.reduce((ret, current) => {
+						return ret.length > current.length ? ret : current;
+					});
+					path = path.replace(/* @__PURE__ */ new RegExp(`^${alias}`), this.#context.config.build.alias[alias]);
+				}
+			}
+		}
+		return path;
+	}
+	/**
+	* A helper function to resolve modules in the virtual file system (VFS).
+	*
+	* @remarks
+	* This function can be used to resolve modules relative to the project root directory.
+	*
+	* @example
+	* ```ts
+	* const resolved = await context.resolvePath("some-module", "/path/to/importer");
+	* ```
+	*
+	* @param id - The module to resolve.
+	* @param importer - An optional path to the importer module.
+	* @param options - Additional resolution options.
+	* @returns A promise that resolves to the resolved module path.
+	*/
+	async resolve(id, importer, options = {}) {
+		let path = id;
+		if (path.includes("{") || path.includes("}")) path = replacePathTokens(this.#context, path);
+		if (options.skipAlias !== true) path = this.resolveAlias(path);
+		if (isAbsolutePath(path)) return path;
+		const resolverCacheKey = murmurhash({
+			path: this.#normalizeId(path),
+			importer,
+			options
+		});
+		let result;
+		if (!this.#context.config.skipCache) {
+			result = this.resolverCache.get(resolverCacheKey);
+			if (result) return result;
+		}
+		result = this.paths[this.#normalizeId(path)];
+		if (!result) {
+			const paths = options.paths ?? [];
+			if (importer && !paths.includes(importer)) paths.push(importer);
+			paths.push(this.#context.workspaceConfig.workspaceRoot);
+			paths.push(appendPath(this.#context.config.projectRoot, this.#context.workspaceConfig.workspaceRoot));
+			paths.push(appendPath(this.#context.config.sourceRoot, this.#context.workspaceConfig.workspaceRoot));
+			paths.push(...Object.keys(this.#context.tsconfig?.options?.paths ?? {}).filter((tsconfigPath) => path.startsWith(tsconfigPath.replace(/\*$/, ""))).map((tsconfigPath) => this.#context.tsconfig?.options?.paths?.[tsconfigPath]).flat().filter(Boolean).map((tsconfigPath) => appendPath(tsconfigPath, this.#context.workspaceConfig.workspaceRoot)));
+			for (const combination of getResolutionCombinations(path, { paths })) {
+				const { relativeKey, adapter } = this.#getStorage(combination);
+				if (await adapter.exists(relativeKey)) {
+					result = combination;
+					break;
+				}
+			}
+			if (!result) try {
+				result = await resolve(path, {
+					...options,
+					paths
+				});
+			} catch {}
+		}
+		if (result && !this.#context.config.skipCache) this.resolverCache.set(resolverCacheKey, result);
+		return result;
+	}
+	/**
+	* A synchronous helper function to resolve modules using the Jiti resolver
+	*
+	* @remarks
+	* This function can be used to resolve modules relative to the project root directory.
+	*
+	* @example
+	* ```ts
+	* const resolvedPath = context.resolveSync("some-module", "/path/to/importer");
+	* ```
+	*
+	* @param id - The module to resolve.
+	* @param importer - An optional path to the importer module.
+	* @param options - Additional resolution options.
+	* @returns The resolved module path.
+	*/
+	resolveSync(id, importer, options = {}) {
+		let path = id;
+		if (path.includes("{") || path.includes("}")) path = replacePathTokens(this.#context, path);
+		if (options.skipAlias !== true) path = this.resolveAlias(path);
+		if (isAbsolutePath(path)) return path;
+		let result;
+		if (!this.#context.config.skipCache) {
+			result = this.resolverCache.get(this.#normalizeId(path));
+			if (result) return result;
+		}
+		result = this.paths[this.#normalizeId(path)];
+		if (!result) {
+			const paths = options.paths ?? [];
+			if (importer && !paths.includes(importer)) paths.push(importer);
+			paths.push(this.#context.workspaceConfig.workspaceRoot);
+			paths.push(appendPath(this.#context.config.projectRoot, this.#context.workspaceConfig.workspaceRoot));
+			paths.push(appendPath(this.#context.config.sourceRoot, this.#context.workspaceConfig.workspaceRoot));
+			paths.push(...Object.keys(this.#context.tsconfig?.options?.paths ?? {}).filter((tsconfigPath) => path.startsWith(tsconfigPath.replace(/\*$/, ""))).map((tsconfigPath) => this.#context.tsconfig?.options?.paths?.[tsconfigPath]).flat().filter(Boolean).map((tsconfigPath) => appendPath(tsconfigPath, this.#context.workspaceConfig.workspaceRoot)));
+			for (const combination of getResolutionCombinations(path, { paths })) {
+				const { relativeKey, adapter } = this.#getStorage(combination);
+				if (adapter.existsSync(relativeKey)) {
+					result = combination;
+					break;
+				}
+			}
+			if (!result) try {
+				result = resolveSync(path, {
+					...options,
+					paths
+				});
+			} catch {}
+		}
+		if (result && !this.#context.config.skipCache) this.resolverCache.set(this.#normalizeId(path), result);
+		return result;
+	}
+	/**
+	* Disposes of the virtual file system (VFS) by saving its state to disk.
+	*/
+	async dispose() {
+		if (!this.#isDisposed) {
+			this.#isDisposed = true;
+			this.#log(LogLevelLabel.DEBUG, "Disposing virtual file system...");
+			await this.remove(joinPaths(this.#context.dataPath, "fs.bin"));
+			const message = new capnp.Message();
+			const fs = message.initRoot(FileSystem);
+			const paths = await this.list();
+			const storage = fs._initStorage(paths.length);
+			await Promise.all(paths.map(async (path, index) => {
+				const code = await this.read(path);
+				const fd = storage.get(index);
+				fd.path = path;
+				fd.code = code || "";
+			}));
+			const ids = fs._initIds(Object.keys(this.ids).length);
+			Object.entries(this.ids).filter(([, path]) => path).forEach(([id, path], index) => {
+				const fileId = ids.get(index);
+				fileId.id = id;
+				fileId.path = path;
+			});
+			const metadata = fs._initMetadata(Object.keys(this.metadata).length);
+			Object.entries(this.metadata).filter(([, value]) => value).forEach(([id, value], index) => {
+				const fileMetadata = metadata.get(index);
+				fileMetadata.id = id;
+				fileMetadata.type = value.type;
+				fileMetadata.timestamp = value.timestamp ?? BigInt(Date.now());
+				if (value.properties) {
+					const props = fileMetadata._initProperties(Object.keys(value.properties).length);
+					Object.entries(value.properties).filter(([, val]) => isSetString(val)).forEach(([key, val], index$1) => {
+						const prop = props.get(index$1);
+						prop.key = key;
+						prop.value = val;
+					});
+				}
+			});
+			await writeFileBuffer(joinPaths(this.#context.dataPath, "fs.bin"), message.toArrayBuffer());
+			if (!this.#context.config.skipCache) this.#resolverCache.save(true);
+			await Promise.all(this.#getStorages().map(async (storage$1) => storage$1.adapter.dispose()));
+			this.#log(LogLevelLabel.TRACE, "Virtual file system has been disposed.");
+		}
+	}
+	async [Symbol.asyncDispose]() {
+		return this.dispose();
+	}
+};
+
+//#endregion
+export { VirtualFileSystem };