Core Filesystem Operations

/**
 * Core filesystem provider interface with all CRUD operations
 */
interface FileSystemProvider {
  /** Provider capability flags indicating supported operations */
  readonly capabilities: FileSystemProviderCapabilities;
  
  /** Event fired when provider capabilities change */
  readonly onDidChangeCapabilities: Event<void>;
  
  /** Event fired when watched files change */
  readonly onDidChangeFile: Event<readonly FileChange[]>;
  
  /** Event fired when file watching encounters errors */
  readonly onFileWatchError: Event<void>;
  
  /** Watch for file system changes */
  watch(resource: URI, opts: WatchOptions): Disposable;
  
  /** Get file/directory metadata and statistics */
  stat(resource: URI): Promise<Stat>;
  
  /** Create directory, including parent directories if needed */
  mkdir(resource: URI): Promise<void>;
  
  /** Read directory contents as name/type pairs */
  readdir(resource: URI): Promise<[string, FileType][]>;
  
  /** Delete file or directory */
  delete(resource: URI, opts: FileDeleteOptions): Promise<void>;
  
  /** Rename/move file or directory */
  rename(from: URI, to: URI, opts: FileOverwriteOptions): Promise<void>;
  
  /** Copy file or directory (optional capability) */
  copy?(from: URI, to: URI, opts: FileOverwriteOptions): Promise<void>;
  
  /** Read entire file contents as binary data (optional capability) */
  readFile?(resource: URI): Promise<Uint8Array>;
  
  /** Write binary data to file with options (optional capability) */
  writeFile?(resource: URI, content: Uint8Array, opts: FileWriteOptions): Promise<void>;
}

enum FileSystemProviderCapabilities {
  FileReadWrite = 2,
  FileOpenReadWriteClose = 4,
  FileReadStream = 16,
  FileFolderCopy = 8,
  PathCaseSensitive = 1024,
  Readonly = 2048,
  Trash = 4096
}

/**
 * Complete file metadata with type information
 */
interface FileStat extends BaseStat {
  /** True if this represents a file */
  isFile: boolean;
  
  /** True if this represents a directory */
  isDirectory: boolean;
  
  /** True if this represents a symbolic link */
  isSymbolicLink: boolean;
  
  /** True if this resource is read-only */
  isReadonly: boolean;
  
  /** Child file stats for directories (when resolved) */
  children?: FileStat[];
}

interface BaseStat {
  /** File system resource URI */
  resource: URI;
  
  /** File name (last segment of path) */
  name: string;
  
  /** File size in bytes (optional) */
  size?: number;
  
  /** Last modification time in millis from Unix epoch (optional) */
  mtime?: number;
  
  /** Creation time in millis from Unix epoch (optional) */
  ctime?: number;
  
  /** Unique identifier representing current state (optional) */
  etag?: string;
}

enum FileType {
  Unknown = 0,
  File = 1,
  Directory = 2,
  SymbolicLink = 64
}

enum FilePermission {
  Readonly = 1
}

/**
 * Collection of file changes with filtering and query methods
 */
interface FileChangesEvent {
  /** Array of all file changes in this event */
  readonly changes: readonly FileChange[];
  
  /** Check if event contains changes for a specific resource */
  contains(resource: URI, type?: FileChangeType): boolean;
  
  /** Check if event affects a specific resource or its children */
  affects(resource: URI, type?: FileChangeType): boolean;
  
  /** Get all added file changes */
  getAdded(): FileChange[];
  
  /** Get all updated file changes */
  getUpdated(): FileChange[];
  
  /** Get all deleted file changes */
  getDeleted(): FileChange[];
}

interface FileChange {
  /** Type of change (added, updated, deleted) */
  readonly type: FileChangeType;
  
  /** Resource that changed */
  readonly resource: URI;
}

enum FileChangeType {
  UPDATED = 0,
  ADDED = 1,
  DELETED = 2
}

/**
 * File operation event information
 */
interface FileOperationEvent {
  /** Type of operation performed */
  readonly operation: FileOperation;
  
  /** Target resource */
  readonly target: URI;
  
  /** Source resource (for move/copy operations) */
  readonly source?: URI;
}

enum FileOperation {
  CREATE,
  DELETE,
  MOVE,
  COPY
}

interface FileWriteOptions {
  /** Whether to create file if it doesn't exist */
  create?: boolean;
  
  /** Whether to overwrite existing file */
  overwrite?: boolean;
  
  /** Whether to unlock readonly files */
  unlock?: boolean;
  
  /** Atomic write operations */
  atomic?: boolean;
}

interface FileDeleteOptions {
  /** Delete recursively for directories */
  recursive?: boolean;
  
  /** Move to trash instead of permanent deletion */
  useTrash?: boolean;
}

interface FileOverwriteOptions {
  /** Whether to overwrite existing target */
  overwrite?: boolean;
}

interface WatchOptions {
  /** Whether to watch recursively */
  recursive?: boolean;
  
  /** Glob patterns to exclude from watching */
  excludes?: string[];
}

/**
 * Provider with streaming capabilities for large files
 */
interface FileSystemProviderWithOpenReadWriteCloseCapability extends FileSystemProvider {
  /** Open file for reading/writing */
  open(resource: URI, opts: FileOpenOptions): Promise<number>;
  
  /** Close previously opened file */
  close(fd: number): Promise<void>;
  
  /** Read data from opened file */
  read(fd: number, pos: number, data: Uint8Array, offset: number, length: number): Promise<number>;
  
  /** Write data to opened file */  
  write(fd: number, pos: number, data: Uint8Array, offset: number, length: number): Promise<number>;
}

interface FileOpenOptions {
  /** Open for read access */
  read?: boolean;
  
  /** Open for write access */
  write?: boolean;
  
  /** Create file if it doesn't exist */
  create?: boolean;
}

/**
 * Stream file content with transformations
 */
function readFileIntoStream<T>(
  provider: FileSystemProviderWithOpenReadWriteCloseCapability,
  resource: URI,
  target: WriteableStream<T>,
  transformer: DataTransformer<BinaryBuffer, T>,
  options: CreateReadStreamOptions,
  token: CancellationToken
): Promise<void>;

interface CreateReadStreamOptions extends FileReadStreamOptions {
  /** Size of each read chunk */
  bufferSize?: number;
  
  /** Total bytes to read */
  length?: number;
  
  /** Starting position for reading */
  position?: number;
}

import { FileSystemProvider, FileStat, URI } from "@theia/filesystem/lib/common";

// Basic file operations
const provider: FileSystemProvider = container.get(FileSystemProvider);

// Read file contents
const content = await provider.readFile(URI.parse('file:///path/to/file.txt'));
const text = content.toString();

// Write file contents  
const data = new TextEncoder().encode('Hello World');
await provider.writeFile(URI.parse('file:///path/to/output.txt'), data, {
  create: true,
  overwrite: true
});

// Get file metadata
const stat = await provider.stat(URI.parse('file:///path/to/file.txt'));
console.log(`File size: ${stat.size} bytes`);
console.log(`Last modified: ${new Date(stat.mtime)}`);
console.log(`Is file: ${stat.isFile}`);

// List directory contents
const entries = await provider.readdir(URI.parse('file:///path/to/directory'));
for (const [name, type] of entries) {
  console.log(`${name}: ${FileType[type]}`);
}

// Watch for changes
const watcher = provider.watch(URI.parse('file:///path/to/watch'), {
  recursive: true,
  excludes: ['node_modules/**', '.git/**']
});

provider.onDidChangeFile(changes => {
  for (const change of changes) {
    console.log(`${FileChangeType[change.type]}: ${change.resource.toString()}`);
  }
});

// Clean up watcher
watcher.dispose();