File Operations

/**
 * Represents files stored in memory as strings or buffers
 */
class FileBlob implements File {
  type: 'FileBlob';
  mode: number;
  data: string | Buffer;
  contentType: string | undefined;

  constructor(options: FileBlobOptions);
  static fromStream(options: FromStreamOptions): Promise<FileBlob>;
  toStream(): NodeJS.ReadableStream;
}

interface FileBlobOptions {
  mode?: number;
  contentType?: string;
  data: string | Buffer;
}

interface FromStreamOptions {
  mode?: number;
  contentType?: string;
  stream: NodeJS.ReadableStream;
}

import { FileBlob } from "@vercel/build-utils";

// Create from string data
const jsFile = new FileBlob({
  data: "console.log('Hello World');",
  contentType: "application/javascript"
});

// Create from buffer
const bufferFile = new FileBlob({
  data: Buffer.from("Binary data here"),
  mode: 0o644
});

// Create from stream
const streamFile = await FileBlob.fromStream({
  stream: someReadableStream,
  contentType: "text/plain"
});

// Convert to stream for processing
const stream = jsFile.toStream();

/**
 * References files on the filesystem
 */
class FileFsRef implements File {
  type: 'FileFsRef';
  mode: number;
  fsPath: string;
  contentType: string | undefined;

  constructor(options: FileFsRefOptions);
  static fromFsPath(options: FileFsRefOptions): Promise<FileFsRef>;
  static fromStream(options: FromStreamOptions): Promise<FileFsRef>;
  toStream(): NodeJS.ReadableStream;
  toStreamAsync(): Promise<NodeJS.ReadableStream>;
}

interface FileFsRefOptions {
  mode?: number;
  contentType?: string;
  fsPath: string;
}

interface FromStreamOptions {
  mode: number;
  contentType?: string;
  stream: NodeJS.ReadableStream;
  fsPath: string;
}

import { FileFsRef } from "@vercel/build-utils";

// Create from existing file
const ref = await FileFsRef.fromFsPath({
  fsPath: "/path/to/source.js"
});

// Create from stream and save to filesystem
const savedRef = await FileFsRef.fromStream({
  mode: 0o644,
  stream: inputStream,
  fsPath: "/tmp/saved-file.js"
});

// Get file stream
const stream = ref.toStream();

/**
 * References files stored remotely with digest-based identification
 */
class FileRef implements File {
  type: 'FileRef';
  mode: number;
  digest: string;
  contentType: string | undefined;
  private mutable: boolean;

  constructor(options: FileRefOptions);
  toStream(): NodeJS.ReadableStream;
  toStreamAsync(): Promise<NodeJS.ReadableStream>;
}

interface FileRefOptions {
  mode?: number;
  digest: string;
  contentType?: string;
  mutable?: boolean;
}

import { FileRef } from "@vercel/build-utils";

// Create remote file reference
const remoteFile = new FileRef({
  digest: "sha:24be087eef9fac01d61b30a725c1a10d7b45a256",
  contentType: "application/javascript"
});

// Create mutable remote file reference
const mutableFile = new FileRef({
  digest: "sha+ephemeral:24be087eef9fac01d61b30a725c1a10d7b45a256",
  mutable: true,
  mode: 0o644
});

// Stream remote file content
const stream = remoteFile.toStream();

/**
 * Downloads files to filesystem with support for incremental updates
 * @param files - Files to download
 * @param basePath - Destination directory path
 * @param meta - Metadata for optimization (dev mode, file changes)
 * @returns Promise resolving to downloaded file references
 */
function download(files: Files, basePath: string, meta?: Meta): Promise<DownloadedFiles>;

interface DownloadedFiles {
  [filePath: string]: FileFsRef;
}

import { download, FileBlob } from "@vercel/build-utils";

const files = {
  "index.js": new FileBlob({ data: "console.log('hello');" }),
  "package.json": new FileBlob({ data: JSON.stringify({ name: "app" }) })
};

// Download all files
const downloaded = await download(files, "/tmp/build");

// Download with development optimizations
const devDownloaded = await download(files, "/tmp/build", {
  isDev: true,
  filesChanged: ["index.js"], // Only download changed files
  filesRemoved: ["old-file.js"] // Remove deleted files
});

/**
 * Checks if file mode represents symbolic link
 * @param mode - File mode number
 * @returns True if mode represents symbolic link
 */
function isSymbolicLink(mode: number): boolean;

import { isSymbolicLink } from "@vercel/build-utils";

const fileMode = 0o120644; // Symbolic link mode
if (isSymbolicLink(fileMode)) {
  console.log("This is a symbolic link");
}

/**
 * Pattern matching for files
 * @param pattern - Glob pattern to match
 * @param opts - Glob options or base path string
 * @param mountpoint - Optional mount point
 * @returns Promise resolving to matched files
 */
function glob(pattern: string, opts: GlobOptions | string, mountpoint?: string): Promise<FsFiles>;

interface FsFiles {
  [filePath: string]: FileFsRef;
}

type GlobOptions = {
  cwd?: string;
  dot?: boolean;
  ignore?: string | string[];
  follow?: boolean;
  realpath?: boolean;
  absolute?: boolean;
};

import { glob } from "@vercel/build-utils";

// Find all JavaScript files
const jsFiles = await glob("**/*.js", "/src");

// Find files with options
const files = await glob("**/*.{js,ts}", {
  cwd: "/project/src",
  ignore: ["**/*.test.js", "node_modules/**"]
});

// Find with dot files included
const allFiles = await glob("**/*", {
  cwd: "/project",
  dot: true
});

/**
 * Gets a writable directory path
 * @returns Promise resolving to writable directory path
 */
function getWriteableDirectory(): Promise<string>;

import { getWriteableDirectory } from "@vercel/build-utils";

// Get temporary directory for build operations
const tempDir = await getWriteableDirectory();
console.log(tempDir); // "/tmp/vercel-build-abc123"

/**
 * Renames files/directories
 * @param files - Files to rename
 * @param renameMap - Mapping of old to new names
 * @returns Promise resolving to renamed files
 */
function rename(files: Files, renameMap: { [oldName: string]: string }): Promise<Files>;

import { rename, FileBlob } from "@vercel/build-utils";

const files = {
  "old-name.js": new FileBlob({ data: "console.log('hello');" }),
  "dir/old.txt": new FileBlob({ data: "content" })
};

// Rename files
const renamed = await rename(files, {
  "old-name.js": "new-name.js",
  "dir/old.txt": "dir/new.txt"
});

/**
 * Converts stream to buffer
 * @param stream - Readable stream
 * @returns Promise resolving to buffer
 */
function streamToBuffer(stream: NodeJS.ReadableStream): Promise<Buffer>;

import { streamToBuffer, FileBlob } from "@vercel/build-utils";

const file = new FileBlob({ data: "Hello World" });
const stream = file.toStream();
const buffer = await streamToBuffer(stream);
console.log(buffer.toString()); // "Hello World"

/**
 * Reads configuration files
 * @param filePath - Path to config file
 * @returns Promise resolving to parsed config
 */
function readConfigFile(filePath: string): Promise<any>;

import { readConfigFile } from "@vercel/build-utils";

// Read JSON config
const packageJson = await readConfigFile("/project/package.json");

// Read YAML config  
const yamlConfig = await readConfigFile("/project/.github/workflows/ci.yml");

// Read TOML config
const tomlConfig = await readConfigFile("/project/Cargo.toml");

interface File {
  type: string;
  mode: number;
  contentType?: string;
  toStream: () => NodeJS.ReadableStream;
  fsPath?: string;
}

interface Files {
  [filePath: string]: File;
}