typescript-virtual-container 0.1.0

package/src/types/vfs.ts

@@ -0,0 +1,81 @@
+/** Supported virtual node kinds. */
+export type VfsNodeType = "file" | "directory";
+
+/** Shared metadata fields available on file and directory stats. */
+export interface VfsBaseNode {
+	/** Node name without parent path. */
+	name: string;
+	/** Absolute normalized node path. */
+	path: string;
+	/** POSIX-like mode bits. */
+	mode: number;
+	/** Node creation timestamp. */
+	createdAt: Date;
+	/** Last update timestamp. */
+	updatedAt: Date;
+}
+
+/** Stat shape returned for file nodes. */
+export interface VfsFileNode extends VfsBaseNode {
+	type: "file";
+	/** True when file content stored as gzip bytes. */
+	compressed: boolean;
+	/** Stored byte length (compressed when compressed=true). */
+	size: number;
+}
+
+/** Stat shape returned for directory nodes. */
+export interface VfsDirectoryNode extends VfsBaseNode {
+	type: "directory";
+	/** Number of direct children in directory. */
+	childrenCount: number;
+}
+
+/** Union of file and directory stat responses. */
+export type VfsNodeStats = VfsFileNode | VfsDirectoryNode;
+
+/** Optional behavior flags for writeFile operations. */
+export interface WriteFileOptions {
+	/** POSIX-like mode to apply on create or overwrite. */
+	mode?: number;
+	/** Store content compressed with gzip. */
+	compress?: boolean;
+}
+
+/** Optional behavior flags for remove operations. */
+export interface RemoveOptions {
+	/** Allow deleting non-empty directory trees. */
+	recursive?: boolean;
+}
+
+/** Base snapshot node schema used for archive serialization. */
+export interface VfsSnapshotBaseNode {
+	name: string;
+	mode: number;
+	/** ISO-8601 creation timestamp. */
+	createdAt: string;
+	/** ISO-8601 update timestamp. */
+	updatedAt: string;
+}
+
+/** Serialized snapshot shape for file nodes. */
+export interface VfsSnapshotFileNode extends VfsSnapshotBaseNode {
+	type: "file";
+	compressed: boolean;
+	/** Base64-encoded raw file bytes. */
+	contentBase64: string;
+}
+
+/** Serialized snapshot shape for directory nodes. */
+export interface VfsSnapshotDirectoryNode extends VfsSnapshotBaseNode {
+	type: "directory";
+	children: VfsSnapshotNode[];
+}
+
+/** Union of serialized snapshot node variants. */
+export type VfsSnapshotNode = VfsSnapshotFileNode | VfsSnapshotDirectoryNode;
+
+/** Top-level serialized filesystem snapshot. */
+export interface VfsSnapshot {
+	root: VfsSnapshotDirectoryNode;
+}

package/src/vfs/archive.ts

@@ -0,0 +1,74 @@
+import { promises as fs } from "node:fs";
+import * as tarStream from "tar-stream";
+import type { VfsSnapshot } from "../types/vfs";
+
+export async function archiveExists(archivePath: string): Promise<boolean> {
+	try {
+		await fs.access(archivePath);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+export async function createTarBuffer(snapshotJson: string): Promise<Buffer> {
+	const pack = tarStream.pack();
+	const chunks: Buffer[] = [];
+
+	const finished = new Promise<Buffer>((resolve, reject) => {
+		pack.on("data", (chunk: Buffer) => chunks.push(Buffer.from(chunk)));
+		pack.on("error", reject);
+		pack.on("end", () => resolve(Buffer.concat(chunks)));
+	});
+
+	pack.entry(
+		{ name: "snapshot.json", mode: 0o600 },
+		snapshotJson,
+		(error?: Error | null) => {
+			if (error) {
+				return;
+			}
+
+			pack.finalize();
+		},
+	);
+
+	return finished;
+}
+
+export async function readSnapshotFromTar(
+	tarBuffer: Buffer,
+): Promise<VfsSnapshot> {
+	return new Promise<VfsSnapshot>((resolve, reject) => {
+		const extract = tarStream.extract();
+		let snapshotText = "";
+		let found = false;
+
+		extract.on("entry", (header, stream, next) => {
+			if (header.name === "snapshot.json") {
+				found = true;
+				stream.on("data", (chunk: Buffer) => {
+					snapshotText += chunk.toString("utf8");
+				});
+				stream.on("end", next);
+				stream.resume();
+				return;
+			}
+
+			stream.resume();
+			stream.on("end", next);
+		});
+
+		extract.on("finish", () => {
+			if (!found) {
+				reject(new Error("snapshot.json missing from archive"));
+				return;
+			}
+
+			resolve(JSON.parse(snapshotText) as VfsSnapshot);
+		});
+
+		extract.on("error", reject);
+		extract.end(tarBuffer);
+	});
+}

package/src/vfs/internalTypes.ts

@@ -0,0 +1,19 @@
+export type InternalNode = InternalFileNode | InternalDirectoryNode;
+
+interface InternalBaseNode {
+	name: string;
+	mode: number;
+	createdAt: Date;
+	updatedAt: Date;
+}
+
+export interface InternalFileNode extends InternalBaseNode {
+	type: "file";
+	content: Buffer;
+	compressed: boolean;
+}
+
+export interface InternalDirectoryNode extends InternalBaseNode {
+	type: "directory";
+	children: Map<string, InternalNode>;
+}

package/src/vfs/path.ts

@@ -0,0 +1,74 @@
+import * as path from "node:path";
+import type { InternalDirectoryNode, InternalNode } from "./internalTypes";
+
+export function normalizePath(rawPath: string): string {
+	if (!rawPath || rawPath.trim() === "") {
+		return "/";
+	}
+
+	const normalized = path.posix.normalize(
+		rawPath.startsWith("/") ? rawPath : `/${rawPath}`,
+	);
+	return normalized === "" ? "/" : normalized;
+}
+
+export function splitPath(normalizedPath: string): string[] {
+	return normalizedPath.split("/").filter(Boolean);
+}
+
+export function getNode(
+	root: InternalDirectoryNode,
+	targetPath: string,
+): InternalNode {
+	const normalized = normalizePath(targetPath);
+	if (normalized === "/") {
+		return root;
+	}
+
+	const parts = splitPath(normalized);
+	let current: InternalNode = root;
+
+	for (const part of parts) {
+		if (current.type !== "directory") {
+			throw new Error(`Path '${normalized}' does not exist.`);
+		}
+
+		const next = current.children.get(part);
+		if (!next) {
+			throw new Error(`Path '${normalized}' does not exist.`);
+		}
+		current = next;
+	}
+
+	return current;
+}
+
+export function getParentDirectory(
+	root: InternalDirectoryNode,
+	targetPath: string,
+	createIfMissing: boolean,
+	createPath: (pathToCreate: string) => void,
+): { parent: InternalDirectoryNode; name: string } {
+	const normalized = normalizePath(targetPath);
+	if (normalized === "/") {
+		throw new Error("Root path has no parent directory.");
+	}
+
+	const parentPath = path.posix.dirname(normalized);
+	const name = path.posix.basename(normalized);
+
+	if (!name) {
+		throw new Error(`Invalid path '${targetPath}'.`);
+	}
+
+	if (createIfMissing) {
+		createPath(parentPath);
+	}
+
+	const parentNode = getNode(root, parentPath);
+	if (parentNode.type !== "directory") {
+		throw new Error(`Parent path '${parentPath}' is not a directory.`);
+	}
+
+	return { parent: parentNode, name };
+}

package/src/vfs/snapshot.ts

@@ -0,0 +1,84 @@
+import type {
+	VfsSnapshot,
+	VfsSnapshotDirectoryNode,
+	VfsSnapshotNode,
+} from "../types/vfs";
+import type { InternalDirectoryNode, InternalNode } from "./internalTypes";
+
+function serializeNode(node: InternalNode): VfsSnapshotNode {
+	if (node.type === "file") {
+		return {
+			type: "file",
+			name: node.name,
+			mode: node.mode,
+			createdAt: node.createdAt.toISOString(),
+			updatedAt: node.updatedAt.toISOString(),
+			compressed: node.compressed,
+			contentBase64: node.content.toString("base64"),
+		};
+	}
+
+	return serializeDirectory(node);
+}
+
+function serializeDirectory(
+	node: InternalDirectoryNode,
+): VfsSnapshotDirectoryNode {
+	return {
+		type: "directory",
+		name: node.name,
+		mode: node.mode,
+		createdAt: node.createdAt.toISOString(),
+		updatedAt: node.updatedAt.toISOString(),
+		children: Array.from(node.children.values()).map((child) =>
+			serializeNode(child),
+		),
+	};
+}
+
+function deserializeNode(node: VfsSnapshotNode): InternalNode {
+	if (node.type === "file") {
+		return {
+			type: "file",
+			name: node.name,
+			mode: node.mode,
+			createdAt: new Date(node.createdAt),
+			updatedAt: new Date(node.updatedAt),
+			content: Buffer.from(node.contentBase64, "base64"),
+			compressed: node.compressed,
+		};
+	}
+
+	return deserializeDirectory(node);
+}
+
+function deserializeDirectory(
+	node: VfsSnapshotDirectoryNode,
+): InternalDirectoryNode {
+	return {
+		type: "directory",
+		name: node.name,
+		mode: node.mode,
+		createdAt: new Date(node.createdAt),
+		updatedAt: new Date(node.updatedAt),
+		children: new Map<string, InternalNode>(
+			node.children.map((child) => [child.name, deserializeNode(child)]),
+		),
+	};
+}
+
+export function createSnapshot(root: InternalDirectoryNode): VfsSnapshot {
+	return { root: serializeDirectory(root) };
+}
+
+export function applySnapshot(
+	rootTarget: InternalDirectoryNode,
+	snapshot: VfsSnapshot,
+): void {
+	const root = deserializeDirectory(snapshot.root);
+	rootTarget.name = root.name;
+	rootTarget.mode = root.mode;
+	rootTarget.createdAt = root.createdAt;
+	rootTarget.updatedAt = root.updatedAt;
+	rootTarget.children = root.children;
+}

package/src/vfs/tree.ts

@@ -0,0 +1,34 @@
+import type { InternalDirectoryNode } from "./internalTypes";
+
+function walkTree(
+	node: InternalDirectoryNode,
+	indent: string,
+	lines: string[],
+): void {
+	const entries = Array.from(node.children.entries()).sort(([a], [b]) =>
+		a.localeCompare(b),
+	);
+
+	entries.forEach(([name, child], index) => {
+		const isLast = index === entries.length - 1;
+		const branch = isLast ? "`-- " : "|-- ";
+		const nextIndent = indent + (isLast ? "    " : "|   ");
+
+		if (child.type === "file") {
+			lines.push(`${indent}${branch}${name}${child.compressed ? " [gz]" : ""}`);
+			return;
+		}
+
+		lines.push(`${indent}${branch}${name}/`);
+		walkTree(child, nextIndent, lines);
+	});
+}
+
+export function renderTree(
+	node: InternalDirectoryNode,
+	rootLabel: string,
+): string {
+	const lines: string[] = [rootLabel];
+	walkTree(node, "", lines);
+	return lines.join("\n");
+}

package/tsconfig.json

@@ -0,0 +1,31 @@
+{
+  "compilerOptions": {
+    // Environment setup & latest features
+    "lib": ["ESNext"],
+    "target": "ESNext",
+    "module": "Preserve",
+    "moduleDetection": "force",
+    "jsx": "react-jsx",
+    "allowJs": true,
+
+    // Bundler mode
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "noEmit": true,
+
+    // Best practices
+    "strict": true,
+    "skipLibCheck": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true,
+
+    // Some stricter flags (disabled by default)
+    "noUnusedLocals": false,
+    "noUnusedParameters": false,
+    "noPropertyAccessFromIndexSignature": false,
+
+    "types": ["node"]
+  }
+}