The File Engine provides file system operations and utilities for reading and writing documentation files.
Singleton class providing file system operations for documentation generation.
/**
* File system operations engine
* Uses singleton pattern - access via FileEngine.getInstance() or default export
*/
class FileEngine {
/**
* Get singleton instance of FileEngine
* @returns FileEngine instance
*/
static getInstance(): FileEngine;
/**
* Read file asynchronously
* @param filepath - Path to file to read
* @returns Promise resolving to file contents as string
*/
get(filepath: string): Promise<string>;
/**
* Read file synchronously
* @param filepath - Path to file to read
* @returns File contents as string
*/
getSync(filepath: string): string;
/**
* Write file asynchronously
* @param filepath - Path to file to write
* @param contents - Content to write to file
* @returns Promise resolving when write is complete
*/
write(filepath: string, contents: string): Promise<void>;
/**
* Write file synchronously
* @param filepath - Path to file to write
* @param contents - Content to write to file
*/
writeSync(filepath: string, contents: string): void;
/**
* Check if file exists synchronously
* @param filepath - Path to file to check
* @returns True if file exists
*/
existsSync(filepath: string): boolean;
}Usage Examples:
import FileEngine from "@compodoc/compodoc";
// Read file asynchronously
const content = await FileEngine.get("./README.md");
console.log(content);
// Read file synchronously
const packageJson = FileEngine.getSync("./package.json");
const package = JSON.parse(packageJson);
// Write file asynchronously
await FileEngine.write("./output/index.html", "<html>...</html>");
// Write file synchronously
FileEngine.writeSync("./output/data.json", JSON.stringify(data));
// Check if file exists
if (FileEngine.existsSync("./tsconfig.json")) {
console.log("TypeScript config found");
}Core file system operations provided by the File Engine.
/**
* Read operations for accessing file content
*/
interface ReadOperations {
/**
* Asynchronous file reading
* @param filepath - Absolute or relative path to file
* @returns Promise<string> with file contents
* @throws Error if file cannot be read
*/
get(filepath: string): Promise<string>;
/**
* Synchronous file reading
* @param filepath - Absolute or relative path to file
* @returns string with file contents
* @throws Error if file cannot be read
*/
getSync(filepath: string): string;
}
/**
* Write operations for creating/updating files
*/
interface WriteOperations {
/**
* Asynchronous file writing
* @param filepath - Absolute or relative path for output file
* @param contents - String content to write
* @returns Promise<void> resolving when write completes
* @throws Error if file cannot be written
*/
write(filepath: string, contents: string): Promise<void>;
/**
* Synchronous file writing
* @param filepath - Absolute or relative path for output file
* @param contents - String content to write
* @throws Error if file cannot be written
*/
writeSync(filepath: string, contents: string): void;
}
/**
* File system utilities
*/
interface FileSystemUtilities {
/**
* Synchronous file existence check
* @param filepath - Path to check
* @returns boolean indicating if file exists
*/
existsSync(filepath: string): boolean;
}Error handling patterns for file operations.
/**
* File operation error types
*/
interface FileEngineErrors {
/**
* File not found error
*/
ENOENT: "File or directory not found";
/**
* Permission denied error
*/
EACCES: "Permission denied";
/**
* Invalid file path error
*/
EINVAL: "Invalid file path";
/**
* Disk full error
*/
ENOSPC: "No space left on device";
}Usage Examples:
// Error handling with async operations
try {
const content = await FileEngine.get("./missing-file.txt");
} catch (error) {
if (error.code === 'ENOENT') {
console.log("File not found");
} else {
console.error("Unexpected error:", error);
}
}
// Error handling with sync operations
try {
const content = FileEngine.getSync("./config.json");
return JSON.parse(content);
} catch (error) {
console.error("Failed to read config:", error.message);
return {};
}
// Safe file existence check before operations
if (FileEngine.existsSync("./optional-config.json")) {
const config = await FileEngine.get("./optional-config.json");
// Process config
}Common patterns used by Compodoc for file operations.
/**
* Common file reading patterns used in Compodoc
*/
interface CommonFilePatterns {
/**
* Read and parse JSON file
* @param filepath - Path to JSON file
* @returns Parsed JSON object
*/
readJson(filepath: string): Promise<any>;
/**
* Read and parse JSON file synchronously
* @param filepath - Path to JSON file
* @returns Parsed JSON object
*/
readJsonSync(filepath: string): any;
/**
* Write JSON data to file
* @param filepath - Output file path
* @param data - Data to stringify and write
* @returns Promise resolving when complete
*/
writeJson(filepath: string, data: any): Promise<void>;
/**
* Read markdown file
* @param filepath - Path to markdown file
* @returns Markdown content string
*/
readMarkdown(filepath: string): Promise<string>;
/**
* Write HTML file with proper structure
* @param filepath - Output HTML file path
* @param content - HTML content
* @returns Promise resolving when complete
*/
writeHtml(filepath: string, content: string): Promise<void>;
}Implementation Examples:
// JSON file operations
const readJson = async (filepath: string) => {
const content = await FileEngine.get(filepath);
return JSON.parse(content);
};
const writeJson = async (filepath: string, data: any) => {
const content = JSON.stringify(data, null, 2);
await FileEngine.write(filepath, content);
};
// Markdown operations
const readMarkdown = async (filepath: string) => {
return await FileEngine.get(filepath);
};
// HTML operations with proper structure
const writeHtml = async (filepath: string, content: string) => {
await FileEngine.write(filepath, content);
};
// Usage in Compodoc context
const packageData = await readJson("./package.json");
const readme = await readMarkdown("./README.md");
await writeHtml("./docs/index.html", renderedHtml);Extended functionality for directory operations (though not directly in FileEngine, commonly used patterns).
/**
* Directory operation patterns commonly used with FileEngine
*/
interface DirectoryPatterns {
/**
* Ensure directory exists before writing files
* @param dirpath - Directory path to create if needed
*/
ensureDir(dirpath: string): Promise<void>;
/**
* Copy directory recursively
* @param source - Source directory
* @param destination - Destination directory
*/
copyDir(source: string, destination: string): Promise<void>;
/**
* List files in directory with pattern matching
* @param dirpath - Directory to list
* @param pattern - Optional glob pattern
*/
listFiles(dirpath: string, pattern?: string): Promise<string[]>;
}