File System Operations

/**
 * Check if a file or directory exists
 * @param file - Path to check
 * @returns Promise resolving to true if exists, false otherwise
 */
function exists(file: string): Promise<boolean>;

/**
 * Get file stats or null if file doesn't exist
 * @param file - Path to stat
 * @returns Promise resolving to Stats object or null
 */
function statOrNull(file: string): Promise<Stats | null>;

/**
 * Remove file if it exists, otherwise do nothing
 * @param file - Path to file to remove
 * @returns Promise resolving when operation completes
 */
function unlinkIfExists(file: string): Promise<void>;

import { exists, statOrNull, unlinkIfExists } from "builder-util";

// Check if file exists
if (await exists("/path/to/file.txt")) {
  console.log("File exists");
}

// Get file stats safely
const stats = await statOrNull("/path/to/file.txt");
if (stats) {
  console.log("File size:", stats.size);
  console.log("Is directory:", stats.isDirectory());
}

// Remove file if it exists
await unlinkIfExists("/tmp/cache.tmp");

/**
 * Copy a file from source to destination
 * @param src - Source file path
 * @param dest - Destination file path
 * @param isEnsureDir - Whether to create destination directory if needed
 * @returns Promise resolving when copy completes
 */
function copyFile(src: string, dest: string, isEnsureDir?: boolean): Promise<any>;

/**
 * Copy or hard link a file with advanced options
 * @param src - Source file path
 * @param dest - Destination file path
 * @param stats - Optional file stats to avoid re-reading
 * @param isUseHardLink - Function determining whether to use hard links
 * @param exDevErrorHandler - Handler for cross-device link errors
 * @returns Promise resolving when operation completes
 */
function copyOrLinkFile(
  src: string,
  dest: string,
  stats?: Stats | null,
  isUseHardLink?: boolean,
  exDevErrorHandler?: (() => boolean) | null
): Promise<any>;

import { copyFile, copyOrLinkFile, USE_HARD_LINKS } from "builder-util";

// Simple file copy
await copyFile("/source/file.txt", "/dest/file.txt", true);

// Copy with hard link preference
await copyOrLinkFile(
  "/source/large-file.bin",
  "/dest/large-file.bin",
  null,
  USE_HARD_LINKS
);

/**
 * Copy entire directory with advanced options
 * @param src - Source directory path
 * @param destination - Destination directory path
 * @param options - Copy options including filters and transformers
 * @returns Promise resolving when copy completes
 */
function copyDir(
  src: string, 
  destination: string, 
  options?: CopyDirOptions
): Promise<any>;

/**
 * Calculate total size of a directory
 * @param dirPath - Directory path to measure
 * @returns Promise resolving to size in bytes
 */
function dirSize(dirPath: string): Promise<number>;

/**
 * Walk directory tree and collect file paths
 * @param initialDirPath - Starting directory path
 * @param filter - Optional filter function for files
 * @param consumer - Optional consumer for processing files during walk
 * @returns Promise resolving to array of file paths
 */
function walk(
  initialDirPath: string, 
  filter?: Filter | null, 
  consumer?: FileConsumer
): Promise<Array<string>>;

import { copyDir, dirSize, walk } from "builder-util";

// Copy directory with filtering
await copyDir("/source/project", "/dest/project", {
  filter: (file, stat) => {
    // Skip node_modules and .git directories
    return !file.includes("node_modules") && !file.includes(".git");
  },
  isUseHardLink: () => true // Use hard links when possible
});

// Calculate directory size
const size = await dirSize("/large/directory");
console.log(`Directory size: ${size} bytes`);

// Walk directory and collect TypeScript files
const tsFiles = await walk("/project/src", (file, stat) => {
  return stat.isFile() && file.endsWith(".ts");
});
console.log("TypeScript files:", tsFiles);

// Walk with custom processing
await walk("/project", null, {
  consume(file, fileStat, parent, siblingNames) {
    if (fileStat.isFile() && file.endsWith(".js")) {
      console.log("Found JS file:", file);
    }
  }
});

/**
 * File copier with transformation capabilities
 */
class FileCopier {
  isUseHardLink: boolean;
  
  constructor(
    isUseHardLinkFunction?: () => boolean,
    transformer?: FileTransformer
  );
  
  copy(src: string, dest: string, stat: Stats | undefined): Promise<void>;
}

/**
 * File transformer for copy operations
 */
class CopyFileTransformer {
  constructor(afterCopyTransformer: AfterCopyFileTransformer);
}

import { FileCopier, CopyFileTransformer } from "builder-util";

// Create file copier with transformation
const copier = new FileCopier(
  () => true, // Use hard links
  async (file) => {
    // Transform .env files
    if (file.endsWith(".env")) {
      return new CopyFileTransformer(async (copiedFile) => {
        // Process after copying
        console.log("Processed env file:", copiedFile);
        return true;
      });
    }
    return null;
  }
);

// Copy file with transformation
await copier.copy("/source/app.env", "/dest/app.env", undefined);

interface CopyDirOptions {
  filter?: Filter;
  transformer?: FileTransformer;
  isUseHardLink?: () => boolean;
}

type Filter = (file: string, stat: FilterStats) => boolean;

interface FilterStats extends Stats {
  moduleName?: string;
  moduleRootPath?: string;
  moduleFullFilePath?: string;
  relativeLink?: string;
  linkRelativeToFile?: string;
}

type FileTransformer = (
  file: string
) => Promise<null | string | Buffer | CopyFileTransformer> | null | string | Buffer | CopyFileTransformer;

type AfterCopyFileTransformer = (file: string) => Promise<boolean>;

interface FileConsumer {
  consume(file: string, fileStat: Stats, parent: string, siblingNames: Array<string>): any;
  isIncludeDir?: boolean;
}

interface Link {
  readonly link: string;
  readonly file: string;
}

const MAX_FILE_REQUESTS: number;
const DO_NOT_USE_HARD_LINKS: () => false;
const USE_HARD_LINKS: () => true;

import { copyDir } from "builder-util";

// Copy only source files, excluding build artifacts
await copyDir("/project", "/backup", {
  filter: (file, stat) => {
    const isSourceFile = /\.(ts|js|json|md)$/.test(file);
    const isBuildArtifact = file.includes("/dist/") || file.includes("/build/");
    return stat.isDirectory() || (isSourceFile && !isBuildArtifact);
  }
});

import { copyDir, USE_HARD_LINKS } from "builder-util";

// Efficiently copy large directories using hard links
await copyDir("/source/assets", "/dest/assets", {
  isUseHardLink: USE_HARD_LINKS,
  filter: (file, stat) => !file.includes(".tmp")
});

import { walk, dirSize } from "builder-util";

// Analyze project structure
const allFiles = await walk("/project");
const sourceFiles = allFiles.filter(f => /\.(ts|js)$/.test(f));
const totalSize = await dirSize("/project");

console.log(`Project has ${sourceFiles.length} source files`);
console.log(`Total size: ${totalSize} bytes`);