@powerlines/core 0.14.5 → 0.15.1

package/dist/lib/vfs.mjs

@@ -0,0 +1,1102 @@
+import { format } from "./utilities/format.mjs";
+import { replacePathTokens } from "../plugin-utils/paths.mjs";
+import "../plugin-utils/index.mjs";
+import { DEFAULT_EXTENSIONS } from "../constants/extensions.mjs";
+import { FileSystem } from "../schemas/fs.mjs";
+import { FileSystemStorageAdapter } from "../storage/file-system.mjs";
+import { VirtualStorageAdapter } from "../storage/virtual.mjs";
+import { existsSync } from "@stryke/fs/exists";
+import { appendPath } from "@stryke/path/append";
+import { findFileExtensionSafe, findFileName, findFilePath, hasFileExtension } from "@stryke/path/file-path-fns";
+import { replaceExtension, 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 { toArray } from "@stryke/convert/to-array";
+import { isSet } from "@stryke/type-checks/is-set";
+import { getUnique } from "@stryke/helpers/get-unique";
+import { isRegExp } from "@stryke/type-checks/is-regexp";
+import { joinPaths } from "@stryke/path/join";
+import { isAbsolutePath } from "@stryke/path/is-type";
+import { isParentPath } from "@stryke/path/is-parent-path";
+import { murmurhash } from "@stryke/hash";
+import { getResolutionCombinations, resolve, resolveSync } from "@stryke/fs/resolve";
+import { prettyBytes } from "@stryke/string-format/pretty-bytes";
+import * as capnp from "@stryke/capnp";
+import { readFileBuffer, readFileBufferSync, writeFileBuffer } from "@stryke/fs/buffer";
+import { correctPath, stripStars } from "@stryke/path/correct-path";
+import { globToRegex } from "@stryke/path/glob-to-regex";
+import { slash } from "@stryke/path/slash";
+import { match } from "bundle-require";
+import { create } from "flat-cache";
+import { Blob } from "node:buffer";
+import { fileURLToPath } from "node:url";
+
+//#region src/lib/vfs.ts
+function toFilePath(path) {
+	return correctPath(slash(path?.toString() || ".").replace(/^file:\/\//, ""));
+}
+/**
+* Checks if a given file id is valid based on the specified prefix.
+*
+* @param id - The file ID to check.
+* @param prefix - The prefix to use for built-in files. Default is "powerlines".
+* @returns `true` if the file ID is valid, otherwise `false`.
+*/
+function isValidId(id, prefix = "powerlines") {
+	return id.replace(/^\\0/, "").startsWith(`${prefix.replace(/:$/, "")}`);
+}
+/**
+* Formats a file id by removing the file extension and prepended runtime prefix.
+*
+* @param id - The file ID to format.
+* @param prefix - The prefix to use for built-in files. Default is "powerlines".
+* @returns The formatted file ID.
+*/
+function normalizeId(id, prefix = "powerlines") {
+	return replaceExtension(toFilePath(id)).replace(/^\\0/, "").replace(/^powerlines:/, "").replace(new RegExp(`^${prefix.replace(/:$/, "")}:`), "");
+}
+/**
+* Normalizes a given path by resolving it against the project root, workspace root, and built-ins path.
+*
+* @param path - The path to normalize.
+* @param builtinsPath - The path to built-in files.
+* @param prefix - The prefix to use for built-in files. Default is "powerlines".
+* @returns The normalized path.
+*/
+function normalizePath(path, builtinsPath, prefix = "powerlines") {
+	if (!isSetString(path)) {
+		if (!isString(path)) throw new Error("Path type must be a string or a file descriptor");
+		throw new Error("Path cannot be empty");
+	}
+	return isAbsolutePath(path) ? path : isValidId(toFilePath(path), prefix) ? normalizeId(toFilePath(path), prefix).replace(new RegExp(`^${prefix.replace(/:$/, "")}:`), builtinsPath) : toFilePath(path);
+}
+/**
+* Normalizes glob patterns by resolving them against the workspace root.
+*
+* @param workspaceRoot - The root directory of the workspace.
+* @param patterns - The glob patterns to normalize.
+* @returns An array of normalized glob patterns.
+*/
+function normalizeGlobPatterns(workspaceRoot, patterns) {
+	return getUnique(toArray(patterns).map((pattern) => {
+		if (isSetObject(pattern) && (isSetString(pattern.input) || isSetString(pattern.glob))) return joinPaths(pattern.input || workspaceRoot, pattern.glob || "**/*");
+		else if (!isSetString(pattern)) return;
+		return pattern;
+	}).filter(isSetString));
+}
+/**
+* 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 underlying file paths to their virtual file IDs.
+	*/
+	#ids;
+	/**
+	* A map of virtual file IDs to their underlying file paths.
+	*/
+	#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;
+	/**
+	* 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 logger client utility.
+	*/
+	#logger;
+	/**
+	* 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.framework?.name ?? "powerlines");
+	}
+	/**
+	* 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) {
+		if (!isSetString(path)) {
+			if (!isString(path)) throw new Error("Path type must be a string or a file descriptor");
+			throw new Error("Path cannot be empty");
+		}
+		return normalizePath(path.includes("{") || path.includes("}") ? replacePathTokens(this.#context, path) : path, this.#context.builtinsPath, this.#context.config.framework?.name ?? "powerlines");
+	}
+	/**
+	* 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, preset) {
+		const path = this.resolveSync(this.#normalizePath(key)) || key;
+		for (const base of Object.keys(this.#storage).filter(Boolean).sort().reverse()) if ((path === base || isParentPath(path, base)) && (!preset || this.#storage[base]?.preset?.toLowerCase() === preset.toLowerCase())) return {
+			base,
+			relativeKey: replacePath(path, base),
+			adapter: this.#storage[base]
+		};
+		if (!preset || this.#storage[""]?.preset?.toLowerCase() === preset.toLowerCase()) return {
+			base: "",
+			relativeKey: path,
+			adapter: this.#storage[""]
+		};
+		this.#storage[path] = preset === "virtual" ? new VirtualStorageAdapter(this.#context, { base: path }) : new FileSystemStorageAdapter(this.#context, { base: path });
+		return {
+			base: path,
+			relativeKey: "",
+			adapter: this.#storage[path]
+		};
+	}
+	/**
+	* 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) {
+		const baseKey = this.resolveSync(base) || base;
+		return Object.keys(this.#storage).sort().reverse().filter((key) => isParentPath(key, baseKey) || includeParent && isParentPath(baseKey, key) || baseKey.includes("*") && (isParentPath(stripStars(baseKey), key) || globToRegex(replaceExtension(baseKey)).test(key))).map((key) => ({
+			relativeBase: baseKey.length > key.length ? baseKey.slice(key.length) : void 0,
+			base: key,
+			adapter: this.#storage[key]
+		}));
+	}
+	/**
+	* 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.
+	*/
+	#innerResolve = async (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) && (!options.isFile || !await this.isDirectory(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 (!isSetString(result)) {
+			const paths = options.paths ?? [];
+			if (importer && !paths.includes(importer)) paths.push(importer);
+			if (!importer) {
+				paths.push(this.#context.config.cwd);
+				paths.push(appendPath(this.#context.config.root, this.#context.config.cwd));
+				paths.push(appendPath(joinPaths(this.#context.config.root, "src"), this.#context.config.cwd));
+			}
+			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.config.cwd)));
+			for (const combination of getResolutionCombinations(path, { paths: getUnique(paths) })) {
+				const { relativeKey, adapter } = this.#getStorage(combination);
+				if (await adapter.exists(relativeKey)) {
+					result = combination;
+					break;
+				}
+			}
+			if (!isSetString(result)) try {
+				result = await resolve(path, {
+					...options,
+					paths
+				});
+			} catch {}
+		}
+		if (isSetString(result)) {
+			if (!this.#context.config.skipCache) this.resolverCache.set(this.#normalizeId(path), 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.
+	*/
+	#innerResolveSync = (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) && (!options.isFile || !this.isDirectorySync(path))) return path;
+		let result;
+		if (!this.#context.config.skipCache) {
+			result = this.resolverCache.get(this.#normalizeId(path));
+			if (isSetString(result)) return result;
+		}
+		result = this.paths[this.#normalizeId(path)];
+		if (!isSetString(result)) {
+			const paths = options.paths ?? [];
+			if (importer && !paths.includes(importer)) paths.push(importer);
+			if (!importer) {
+				paths.push(this.#context.config.cwd);
+				paths.push(appendPath(this.#context.config.root, this.#context.config.cwd));
+				paths.push(appendPath(joinPaths(this.#context.config.root, "src"), this.#context.config.cwd));
+			}
+			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.config.cwd)));
+			for (const combination of getResolutionCombinations(path, { paths })) {
+				const { relativeKey, adapter } = this.#getStorage(combination);
+				if (adapter.existsSync(relativeKey)) {
+					result = combination;
+					break;
+				}
+			}
+			if (!isSetString(result)) try {
+				result = resolveSync(path, {
+					...options,
+					paths
+				});
+			} catch {}
+		}
+		if (isSetString(result)) {
+			if (!this.#context.config.skipCache) this.resolverCache.set(this.#normalizeId(path), result);
+			return result;
+		}
+	};
+	/**
+	* 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) {
+		context.debug("Starting virtual file system (VFS) initialization processes...");
+		let result;
+		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);
+			result = new VirtualFileSystem(context, fs);
+			if (fs._hasStorage() && fs.storage.length > 0) await Promise.all(fs.storage.values().map(async (file) => {
+				if (file.path && file.code) {
+					let id;
+					if (fs._hasIds()) id = fs.ids.find((fileId) => fileId.path === file.path);
+					let metadata;
+					if (fs._hasMetadata()) metadata = fs.metadata.find((meta) => meta.id === result.#normalizeId(id?.id ?? file.path));
+					await result.write(file.path, file.code, { meta: {
+						id: result.#normalizeId(id?.id ?? metadata?.id ?? file.path),
+						type: metadata?.type || "normal",
+						properties: metadata?._hasProperties() ? metadata?.properties.values().reduce((ret, kvp) => {
+							ret[kvp.key] = kvp.value;
+							return ret;
+						}, {}) : void 0,
+						timestamp: metadata?.timestamp
+					} });
+				}
+			}));
+		} else result = new VirtualFileSystem(context, new capnp.Message().initRoot(FileSystem));
+		result.#logger.debug("Successfully completed virtual file system (VFS) initialization.");
+		return result;
+	}
+	/**
+	* 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) {
+		context.debug("Starting virtual file system (VFS) initialization processes...");
+		let result;
+		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);
+			result = new VirtualFileSystem(context, fs);
+			if (fs._hasStorage() && fs.storage.length > 0) fs.storage.values().forEach((file) => {
+				if (file.path && file.code) {
+					let id;
+					if (fs._hasIds()) id = fs.ids.find((fileId) => fileId.path === file.path);
+					let metadata;
+					if (fs._hasMetadata()) metadata = fs.metadata.find((meta) => meta.id === result.#normalizeId(id?.id ?? file.path));
+					result.writeSync(file.path, file.code, { meta: {
+						id: result.#normalizeId(id?.id ?? metadata?.id ?? file.path),
+						type: metadata?.type,
+						properties: metadata?._hasProperties() ? metadata?.properties.values().reduce((ret, kvp) => {
+							ret[kvp.key] = kvp.value;
+							return ret;
+						}, {}) : void 0,
+						timestamp: metadata?.timestamp
+					} });
+				}
+			});
+		} else result = new VirtualFileSystem(context, new capnp.Message().initRoot(FileSystem));
+		result.#logger.debug("Successfully completed virtual file system (VFS) initialization.");
+		return result;
+	}
+	/**
+	* A map of file ids to their metadata.
+	*/
+	get metadata() {
+		return new Proxy(this.#metadata, {
+			get: (target, prop) => {
+				return target[this.#normalizeId(prop)];
+			},
+			set: (target, prop, value) => {
+				target[this.#normalizeId(prop)] = value;
+				return true;
+			},
+			deleteProperty: (target, prop) => {
+				delete target[this.#normalizeId(prop)];
+				return true;
+			},
+			has: (target, prop) => {
+				return this.#normalizeId(prop) in target;
+			},
+			ownKeys: (target) => {
+				return getUnique(Reflect.ownKeys(target).map((key) => this.#normalizeId(key)));
+			}
+		});
+	}
+	/**
+	* A map of file paths to their module ids.
+	*/
+	get ids() {
+		return new Proxy(this.#ids, {
+			get: (target, prop) => {
+				return target[this.#normalizePath(prop)];
+			},
+			set: (target, prop, value) => {
+				target[this.#normalizePath(prop)] = value;
+				return true;
+			},
+			deleteProperty: (target, prop) => {
+				delete target[this.#normalizePath(prop)];
+				return true;
+			},
+			has: (target, prop) => {
+				return this.#normalizePath(prop) in target;
+			},
+			ownKeys: (target) => {
+				return getUnique(Reflect.ownKeys(target).map((key) => this.#normalizePath(key)));
+			}
+		});
+	}
+	/**
+	* A map of module ids to their file paths.
+	*/
+	get paths() {
+		return new Proxy(this.#paths, {
+			get: (target, prop) => {
+				return this.#normalizeId(prop) in target ? target[this.#normalizeId(prop)] : void 0;
+			},
+			set: (target, prop, value) => {
+				target[this.#normalizeId(prop)] = value;
+				return true;
+			},
+			deleteProperty: (target, prop) => {
+				delete target[this.#normalizeId(prop)];
+				return true;
+			},
+			has: (target, prop) => {
+				return this.#normalizeId(prop) in target;
+			},
+			ownKeys: (target) => {
+				return getUnique(Reflect.ownKeys(target).map((key) => this.#normalizeId(key)));
+			}
+		});
+	}
+	/**
+	* Gets the resolver cache.
+	*/
+	get resolverCache() {
+		if (!this.#resolverCache) this.#resolverCache = create({
+			cacheId: "module-resolution",
+			cacheDir: this.#context.cachePath,
+			ttl: 2.5 * 60 * 1e3,
+			lruSize: 8e3,
+			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;
+		this.#storage = { "": new FileSystemStorageAdapter(context) };
+		if (isSetObject(this.#context.config.output.storage)) this.#storage = {
+			...this.#storage,
+			...this.#context.config.output.storage
+		};
+		this.#storage.virtual ??= new VirtualStorageAdapter(context, { base: "/_virtual" });
+		this.#storage[this.#context.config.output.path] ??= new FileSystemStorageAdapter(context, { base: this.#context.config.output.path });
+		if (this.#context.config.output.copy && this.#context.config.output.copy.path) this.#storage[this.#context.config.output.copy.path] ??= new FileSystemStorageAdapter(context, { base: this.#context.config.output.copy.path });
+		if (this.#context.config.output.storage !== "fs") {
+			this.#storage[this.#context.artifactsPath] ??= new VirtualStorageAdapter(context, { base: this.#context.artifactsPath });
+			this.#storage[this.#context.builtinsPath] ??= new VirtualStorageAdapter(context, { base: this.#context.builtinsPath });
+			this.#storage[this.#context.entryPath] ??= new VirtualStorageAdapter(context, { 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, item) => {
+					ret[item.key] = item.value;
+					return ret;
+				}, {}) : {}
+			};
+			return ret;
+		}, {});
+		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.#logger = context.extendLogger({ category: "fs" });
+	}
+	/**
+	* 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.
+	* @param importer - An optional path to the importer module.
+	* @param options - Additional resolution options.
+	* @returns `true` if the file is virtual, otherwise `false`.
+	*/
+	isVirtual(path, importer, options) {
+		const resolved = this.resolveSync(path, importer, options);
+		if (!isSetString(resolved)) {
+			if (isSet(resolved)) throw new Error(`Resolved path is not a string: ${String(resolved)}`);
+			return false;
+		}
+		return this.#getStorage(resolved)?.adapter?.preset === "virtual" || resolved.startsWith(`${this.#context.config.framework?.name ?? "powerlines"}:`) || path.startsWith(`${this.#context.config.framework?.name ?? "powerlines"}:`);
+	}
+	/**
+	* Checks if a path is a directory in the virtual file system (VFS).
+	*
+	* @param path - The path to check.
+	* @param importer - An optional path to the importer module.
+	* @param options - Additional resolution options.
+	* @returns `true` if the path is a directory, otherwise `false`.
+	*/
+	isDirectorySync(path, importer, options) {
+		const resolved = this.resolveSync(path, importer, options);
+		if (!isSetString(resolved)) {
+			if (isSet(resolved)) throw new Error(`Resolved path is not a string: ${String(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.
+	* @param importer - An optional path to the importer module.
+	* @param options - Additional resolution options.
+	* @returns `true` if the path is a directory, otherwise `false`.
+	*/
+	async isDirectory(path, importer, options) {
+		const resolved = await this.resolve(path, importer, options);
+		if (!isSetString(resolved)) {
+			if (isSet(resolved)) throw new Error(`Resolved path is not a string: ${String(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.
+	* @param importer - An optional path to the importer module.
+	* @param options - Additional resolution options.
+	* @returns `true` if the path is a file, otherwise `false`.
+	*/
+	isFileSync(path, importer, options) {
+		const resolved = this.resolveSync(path, importer, options);
+		if (!isSetString(resolved)) {
+			if (isSet(resolved)) throw new Error(`Resolved path is not a string: ${String(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.
+	* @param importer - An optional path to the importer module.
+	* @param options - Additional resolution options.
+	* @returns `true` if the path is a file, otherwise `false`.
+	*/
+	async isFile(path, importer, options) {
+		const resolved = await this.resolve(path, importer, options);
+		if (!isSetString(resolved)) {
+			if (isSet(resolved)) throw new Error(`Resolved path is not a string: ${String(resolved)}`);
+			return false;
+		}
+		return await this.#getStorage(resolved)?.adapter?.isFile(resolved) ?? false;
+	}
+	/**
+	* Checks if a file Id must be resolved by the virtual file system (VFS).
+	*
+	* @remarks
+	* Examples of file Ids that would be considered virtual include:
+	* - Ids that start with the framework specific prefix (e.g. `powerlines:`)
+	* - Ids that match a configured alias for virtual modules (returned true from {@link VirtualFileSystemInterface.isVirtual})
+	*
+	* @param path - The path or id of the file.
+	* @param importer - An optional path to the importer module, used for resolving the file path.
+	* @param options - Additional options for resolving the file path.
+	* @returns `true` if the file is virtual, otherwise `false`.
+	*/
+	isResolvableId(path, importer, options) {
+		return path.startsWith(`${this.#context.config.framework?.name ?? "powerlines"}:`) || this.isVirtual(path, importer, options) || this.isAlias(path) || this.isTsconfigPath(path);
+	}
+	/**
+	* 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) {
+		let resolvedPath = path;
+		if (resolvedPath.includes("*")) {
+			this.#logger.warn(`Invoking "listSync" with a glob pattern is not supported. It is likely you meant to use "globSync". Path: ${path}`);
+			resolvedPath = stripStars(resolvedPath);
+		}
+		return getUnique(this.#getStorages(resolvedPath, true).map((storage) => storage.adapter.listSync(storage.relativeBase ? storage.base ? appendPath(storage.relativeBase, storage.base) : storage.relativeBase : storage.base)).flat().filter(Boolean));
+	}
+	/**
+	* 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) {
+		let resolvedPath = path;
+		if (resolvedPath.includes("*")) {
+			this.#logger.warn(`Invoking "list" with a glob pattern is not supported. It is likely you meant to use "glob". Path: ${path}`);
+			resolvedPath = stripStars(resolvedPath);
+		}
+		return getUnique((await Promise.all(this.#getStorages(resolvedPath, true).map(async (storage) => storage.adapter.list(storage.relativeBase ? storage.base ? appendPath(storage.relativeBase, storage.base) : storage.relativeBase : storage.base)))).flat().filter(Boolean));
+	}
+	/**
+	* 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.#logger.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.#logger.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.config.cwd, 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);
+			}
+			else {
+				const absPattern = isAbsolutePath(normalized) ? normalized : this.#normalizePath(appendPath(normalized, this.#context.config.cwd));
+				await Promise.all((await this.list(stripStars(absPattern))).map(async (file) => {
+					if (globToRegex(absPattern).test(file)) {
+						const resolved = await this.resolve(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.config.cwd, 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);
+			}
+			else {
+				const absPattern = isAbsolutePath(normalized) ? normalized : this.#normalizePath(appendPath(normalized, this.#context.config.cwd));
+				const files = this.listSync(stripStars(absPattern));
+				for (const file of files) if (globToRegex(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.config.cwd;
+		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.config.cwd;
+		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, void 0, { isFile: true });
+		if (!filePath || !this.existsSync(filePath)) return;
+		const { adapter } = this.#getStorage(filePath);
+		this.#logger.trace(`Reading ${adapter.name} file: ${filePath}`);
+		return await adapter.get(filePath) ?? 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, void 0, { isFile: true });
+		if (!filePath || !this.existsSync(filePath)) return;
+		const { adapter } = this.#getStorage(filePath);
+		this.#logger.trace(`Reading ${adapter.name} file: ${filePath}`);
+		return adapter.getSync(filePath) ?? 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 = {}) {
+		const meta = options.meta ?? {};
+		const resolvedPath = await this.resolve(this.#normalizePath(path)) || path;
+		const { relativeKey, adapter } = this.#getStorage(resolvedPath, options.storage);
+		this.#logger.trace(`Writing ${resolvedPath} 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)})`);
+		let code = data;
+		try {
+			if (!options.skipFormat) code = await format(this.#context, resolvedPath, data);
+		} catch (err) {
+			if (DEFAULT_EXTENSIONS.includes(findFileExtensionSafe(resolvedPath, { fullExtension: true }))) this.#logger.warn(`Failed to format file ${resolvedPath} before writing: ${err.message}`);
+			code = data;
+		}
+		this.#logger.trace(`Writing ${resolvedPath} 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 = this.#normalizeId(meta.id || resolvedPath);
+		this.metadata[id] = {
+			type: "normal",
+			timestamp: Date.now(),
+			...this.metadata[id] ?? {},
+			...meta
+		};
+		this.paths[id] = resolvedPath;
+		this.ids[resolvedPath] = 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 meta = options.meta ?? {};
+		const resolvedPath = this.resolveSync(this.#normalizePath(path)) || path;
+		const { relativeKey, adapter } = this.#getStorage(resolvedPath, options.storage);
+		this.#logger.trace(`Writing ${resolvedPath} 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 = this.#normalizeId(meta.id || resolvedPath);
+		this.metadata[id] = {
+			type: "normal",
+			timestamp: Date.now(),
+			...this.metadata[id] ?? {},
+			...meta
+		};
+		this.paths[id] = resolvedPath;
+		this.ids[resolvedPath] = 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.resolve.alias) {
+			if (Array.isArray(this.#context.config.resolve.alias) && this.#context.config.resolve.alias.length > 0) {
+				const found = this.#context.config.resolve.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(new RegExp(`^${alias.find}`), alias.replacement);
+					else if (isRegExp(alias.find)) path = path.replace(alias.find, alias.replacement);
+				}
+			} else if (isSetObject(this.#context.config.resolve.alias)) {
+				const found = Object.keys(this.#context.config.resolve.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(new RegExp(`^${alias}`), this.#context.config.resolve.alias[alias]);
+				}
+			}
+		}
+		return path;
+	}
+	/**
+	* Checks if a given module ID is an alias.
+	*
+	* @remarks
+	* This function can be used to determine if a module ID matches any configured aliases.
+	*
+	* @param id - The module ID to check.
+	* @returns A boolean indicating whether the module ID is an alias.
+	*/
+	isAlias(id) {
+		const path = id;
+		if (this.#context.config.resolve.alias) {
+			if (Array.isArray(this.#context.config.resolve.alias) && this.#context.config.resolve.alias.length > 0) return this.#context.config.resolve.alias.filter((alias) => isSetString(alias.find) && (alias.find === path || path.startsWith(`${alias.find}/`)) || isRegExp(alias.find) && alias.find.test(path)).length > 0;
+			else if (isSetObject(this.#context.config.resolve.alias)) return Object.keys(this.#context.config.resolve.alias).filter((key) => key === path || path.startsWith(`${key}/`)).length > 0;
+		}
+		return false;
+	}
+	/**
+	* Checks if a given module ID is a tsconfig path.
+	*
+	* @remarks
+	* This function can be used to determine if a module ID matches any configured tsconfig paths.
+	*
+	* @param id - The module ID to check.
+	* @returns A boolean indicating whether the module ID is a tsconfig path.
+	*/
+	isTsconfigPath(id) {
+		return !!(this.#context.tsconfig.options.paths && Object.keys(this.#context.tsconfig.options.paths).length > 0 && match(id, this.#context.resolvePatterns));
+	}
+	/**
+	* 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 = {}) {
+		const origResult = await this.#innerResolve(id, importer, options);
+		if (origResult && options.isFile && await this.isDirectory(origResult)) {
+			const indexResult = await this.resolve(joinPaths(origResult, "index"), importer, options);
+			if (indexResult) return indexResult;
+			if (!hasFileExtension(origResult)) for (const ext of DEFAULT_EXTENSIONS) {
+				const extResult = await this.resolve(`${origResult}.${ext}`, importer, options);
+				if (extResult) return extResult;
+			}
+			return;
+		}
+		return origResult;
+	}
+	/**
+	* 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 = {}) {
+		const origResult = this.#innerResolveSync(id, importer, options);
+		if (origResult && options.isFile && this.isDirectorySync(origResult)) {
+			const indexResult = this.resolveSync(joinPaths(origResult, "index"), importer, options);
+			if (indexResult) return indexResult;
+			if (!hasFileExtension(origResult)) for (const ext of DEFAULT_EXTENSIONS) {
+				const extResult = this.resolveSync(`${origResult}.${ext}`, importer, options);
+				if (extResult) return extResult;
+			}
+			return;
+		}
+		return origResult;
+	}
+	/**
+	* Disposes of the virtual file system (VFS) by saving its state to disk.
+	*/
+	async dispose() {
+		if (!this.#isDisposed) {
+			this.#isDisposed = true;
+			this.#logger.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 storage = fs._initStorage(Object.keys(this.#paths).length);
+			await Promise.all(Object.values(this.#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(([, id]) => id).forEach(([path, id], 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 ?? 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) => {
+						const prop = props.get(index);
+						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) => storage.adapter.dispose()));
+			this.#logger.trace("Virtual file system has been disposed.");
+		}
+	}
+	/**
+	* Asynchronously disposes of the virtual file system (VFS) by saving its state to disk.
+	*
+	* @remarks
+	* This method is automatically called when the VFS instance is used within a `using` block, or can be manually invoked to ensure that the VFS state is saved and resources are cleaned up properly.
+	*/
+	async [Symbol.asyncDispose]() {
+		return this.dispose();
+	}
+};
+
+//#endregion
+export { VirtualFileSystem };
+//# sourceMappingURL=vfs.mjs.map