File System

/**
 * Cross-platform file system interface
 */
interface FileSystem {
  /** Read file contents as Buffer */
  readFile(filePath: FilePath): Promise<Buffer>;
  /** Read file contents as string with encoding */
  readFile(filePath: FilePath, encoding: Encoding): Promise<string>;
  /** Read file contents synchronously as Buffer */
  readFileSync(filePath: FilePath): Buffer;
  /** Read file contents synchronously as string */
  readFileSync(filePath: FilePath, encoding: Encoding): string;
  
  /** Write file contents */
  writeFile(filePath: FilePath, contents: Buffer | string, options?: ?FileOptions): Promise<void>;
  /** Copy file from source to destination */
  copyFile(source: FilePath, destination: FilePath, flags?: number): Promise<void>;
  
  /** Get file statistics */
  stat(filePath: FilePath): Promise<Stats>;
  /** Get file statistics synchronously */
  statSync(filePath: FilePath): Stats;
  /** Get file statistics without following symlinks */
  lstat(filePath: FilePath): Promise<Stats>;
  /** Get file statistics synchronously without following symlinks */
  lstatSync(filePath: FilePath): Stats;
  
  /** Read directory contents */
  readdir(path: FilePath): Promise<Array<string>>;
  /** Read directory contents with file types */
  readdir(path: FilePath, opts: {withFileTypes: true}): Promise<Array<Dirent>>;
  /** Read directory contents synchronously */
  readdirSync(path: FilePath): Array<string>;
  /** Read directory contents synchronously with file types */
  readdirSync(path: FilePath, opts: {withFileTypes: true}): Array<Dirent>;
  
  /** Create symbolic link */
  symlink(target: FilePath, path: FilePath): Promise<void>;
  /** Delete file */
  unlink(path: FilePath): Promise<void>;
  /** Resolve real path of symlink */
  realpath(path: FilePath): Promise<FilePath>;
  /** Resolve real path of symlink synchronously */
  realpathSync(path: FilePath): FilePath;
  /** Read symbolic link target */
  readlink(path: FilePath): Promise<FilePath>;
  /** Read symbolic link target synchronously */
  readlinkSync(path: FilePath): FilePath;
  
  /** Check if file or directory exists */
  exists(path: FilePath): Promise<boolean>;
  /** Check if file or directory exists synchronously */
  existsSync(path: FilePath): boolean;
  
  /** Create directory recursively */
  mkdirp(path: FilePath): Promise<void>;
  /** Remove directory and contents recursively */
  rimraf(path: FilePath): Promise<void>;
  /** Copy directory recursively */
  ncp(source: FilePath, destination: FilePath): Promise<void>;
  
  /** Create readable stream */
  createReadStream(path: FilePath, options?: ?FileOptions): Readable;
  /** Create writable stream */
  createWriteStream(path: FilePath, options?: ?FileOptions): Writable;
  
  /** Get current working directory */
  cwd(): FilePath;
  /** Change current working directory */
  chdir(dir: FilePath): void;
  
  /** Watch directory for changes */
  watch(
    dir: FilePath,
    fn: (err: ?Error, events: Array<Event>) => void,
    opts: WatchOptions
  ): AsyncSubscription;
  
  /** Get events since last call */
  getEventsSince(
    dir: FilePath,
    snapshot: FilePath,
    opts: WatchOptions
  ): Promise<Array<Event>>;
  
  /** Write atomic snapshot of directory state */
  writeSnapshot(
    dir: FilePath, 
    snapshot: FilePath,
    opts: WatchOptions
  ): Promise<void>;
  
  /** Find first ancestor file matching name */
  findAncestorFile(
    filenames: Array<string>,
    from: FilePath,
    root: FilePath
  ): Promise<?FilePath>;
  
  /** Find node_modules package */
  findNodeModule(moduleName: string, from: FilePath): Promise<?FilePath>;
  
  /** Find first file matching patterns */
  findFirstFile(filePaths: Array<FilePath>): Promise<?FilePath>;
}

/**
 * File statistics interface
 */
interface Stats {
  /** File size in bytes */
  size: number;
  /** Last access time */
  atime: Date;
  /** Last modified time */
  mtime: Date;
  /** Creation time */
  ctime: Date;
  /** Birth time (creation on some systems) */
  birthtime: Date;
  /** Device ID */
  dev: number;
  /** Inode number */
  ino: number;
  /** File mode */
  mode: number;
  /** Number of hard links */
  nlink: number;
  /** User ID */
  uid: number;
  /** Group ID */
  gid: number;
  /** Device ID for special files */
  rdev: number;
  /** Block size for I/O */
  blksize: number;
  /** Number of blocks allocated */
  blocks: number;
  
  /** Check if this is a file */
  isFile(): boolean;
  /** Check if this is a directory */
  isDirectory(): boolean;
  /** Check if this is a symbolic link */
  isSymbolicLink(): boolean;
  /** Check if this is a block device */
  isBlockDevice(): boolean;
  /** Check if this is a character device */
  isCharacterDevice(): boolean;
  /** Check if this is a FIFO */
  isFIFO(): boolean;
  /** Check if this is a socket */
  isSocket(): boolean;
}

/**
 * Directory entry with file type information
 */
interface Dirent {
  /** Entry name */
  name: string;
  
  /** Check if this is a file */
  isFile(): boolean;
  /** Check if this is a directory */
  isDirectory(): boolean;
  /** Check if this is a symbolic link */
  isSymbolicLink(): boolean;
  /** Check if this is a block device */
  isBlockDevice(): boolean;
  /** Check if this is a character device */
  isCharacterDevice(): boolean;
  /** Check if this is a FIFO */
  isFIFO(): boolean;
  /** Check if this is a socket */
  isSocket(): boolean;
}

/**
 * File operation options
 */
interface FileOptions {
  /** File mode permissions */
  mode?: number;
  /** File encoding */
  encoding?: Encoding;
  /** File flags */
  flag?: string;
}

/**
 * Directory reading options
 */
interface ReaddirOptions {
  /** Include file type information */
  withFileTypes?: boolean;
  /** Encoding for file names */
  encoding?: Encoding;
}

/**
 * File encoding types
 */
type Encoding = 
  | 'ascii'
  | 'utf8' 
  | 'utf-8'
  | 'utf16le'
  | 'ucs2'
  | 'ucs-2'
  | 'base64'
  | 'base64url'
  | 'latin1'
  | 'binary'
  | 'hex';

/**
 * File watching options
 */
interface WatchOptions {
  /** Ignore patterns */
  ignore?: Array<FilePath>;
  /** Include patterns */
  include?: Array<FilePath>;
}

/**
 * File system event
 */
interface Event {
  /** Event type */
  type: 'create' | 'update' | 'delete';
  /** File path that changed */
  path: FilePath;
}

/**
 * Async subscription for cleanup
 */
interface AsyncSubscription {
  /** Unsubscribe from events */
  unsubscribe(): Promise<void>;
}

/**
 * Build cache interface
 */
interface Cache {
  /** Ensure cache is ready */
  ensure(): Promise<void>;
  
  /** Check if key exists in cache */
  has(key: string): Promise<boolean>;
  /** Get cached value */
  get<T>(key: string): Promise<?T>;
  /** Set cached value */
  set(key: string, value: mixed): Promise<void>;
  
  /** Get cached value as stream */
  getStream(key: string): Readable;
  /** Set cached value from stream */
  setStream(key: string, stream: Readable): Promise<void>;
  
  /** Get cached blob */
  getBlob(key: string): Promise<Buffer>;
  /** Set cached blob */
  setBlob(key: string, contents: Buffer | string): Promise<void>;
  
  /** Check if large blob exists */
  hasLargeBlob(key: string): Promise<boolean>;
  /** Get large cached blob */
  getLargeBlob(key: string): Promise<Buffer>;
  /** Set large cached blob */
  setLargeBlob(
    key: string, 
    contents: Buffer | string, 
    options?: {signal?: AbortSignal}
  ): Promise<void>;
  /** Delete large cached blob */
  deleteLargeBlob(key: string): Promise<void>;
  
  /** Get cached buffer (legacy) */
  getBuffer(key: string): Promise<?Buffer>;
  
  /** Refresh cache state */
  refresh(): void;
}

/**
 * File creation invalidation types
 */
type FileCreateInvalidation = 
  | GlobInvalidation 
  | FileInvalidation 
  | FileAboveInvalidation;

/**
 * Glob pattern invalidation
 */
interface GlobInvalidation {
  type: 'glob';
  glob: Glob;
}

/**
 * Specific file invalidation
 */
interface FileInvalidation {
  type: 'file';
  filePath: FilePath;
}

/**
 * Ancestor file invalidation
 */
interface FileAboveInvalidation {
  type: 'file-above';
  fileName: string;
  aboveFilePath: FilePath;
}

import type { FileSystem, Cache, WatchOptions } from '@parcel/types';

// Basic file operations
async function processFiles(fs: FileSystem) {
  // Read file contents
  const buffer = await fs.readFile('/path/to/file.js');
  const text = await fs.readFile('/path/to/file.js', 'utf8');
  
  // Write processed contents
  const processed = transformCode(text);
  await fs.writeFile('/path/to/output.js', processed);
  
  // Check file existence
  if (await fs.exists('/path/to/config.json')) {
    const config = await fs.readFile('/path/to/config.json', 'utf8');
    console.log('Config:', JSON.parse(config));
  }
  
  // Get file statistics
  const stats = await fs.stat('/path/to/file.js');
  console.log(`File size: ${stats.size} bytes`);
  console.log(`Modified: ${stats.mtime}`);
}

// Directory operations
async function processDirectory(fs: FileSystem) {
  // Create directory
  await fs.mkdirp('/path/to/new/dir');
  
  // Read directory contents
  const files = await fs.readdir('/path/to/dir');
  console.log('Files:', files);
  
  // Read with file types
  const entries = await fs.readdir('/path/to/dir', { withFileTypes: true });
  for (const entry of entries) {
    if (entry.isFile()) {
      console.log(`File: ${entry.name}`);
    } else if (entry.isDirectory()) {
      console.log(`Directory: ${entry.name}`);
    }
  }
  
  // Copy directory
  await fs.ncp('/source/dir', '/dest/dir');
}

// File watching
async function watchFiles(fs: FileSystem) {
  const watchOptions: WatchOptions = {
    ignore: ['node_modules/**', '*.log'],
    include: ['src/**/*.{js,ts,jsx,tsx}']
  };
  
  const subscription = fs.watch('/project/root', (err, events) => {
    if (err) {
      console.error('Watch error:', err);
      return;
    }
    
    for (const event of events) {
      console.log(`${event.type}: ${event.path}`);
      
      if (event.type === 'create' && event.path.endsWith('.js')) {
        console.log('New JavaScript file created');
      }
    }
  }, watchOptions);
  
  // Later: cleanup
  await subscription.unsubscribe();
}

// Cache operations
async function useCache(cache: Cache) {
  const cacheKey = 'processed-file-hash123';
  
  // Check if cached
  if (await cache.has(cacheKey)) {
    const cached = await cache.get(cacheKey);
    console.log('Using cached result:', cached);
    return cached;
  }
  
  // Process and cache
  const result = await expensiveProcessing();
  await cache.set(cacheKey, result);
  
  // Cache large blobs
  const largeBuffer = generateLargeAsset();
  await cache.setLargeBlob('large-asset-key', largeBuffer);
  
  return result;
}

// File utilities
async function findProjectFiles(fs: FileSystem) {
  // Find package.json
  const packageJson = await fs.findAncestorFile(
    ['package.json'],
    '/project/src/components',
    '/project'
  );
  
  if (packageJson) {
    console.log('Found package.json at:', packageJson);
  }
  
  // Find node_modules package
  const lodashPath = await fs.findNodeModule('lodash', '/project/src');
  if (lodashPath) {
    console.log('Found lodash at:', lodashPath);
  }
  
  // Find first existing config file
  const configFile = await fs.findFirstFile([
    '/project/.parcelrc',
    '/project/parcel.config.js',
    '/project/parcel.config.json'
  ]);
  
  if (configFile) {
    console.log('Using config:', configFile);
  }
}