File Operations

/**
 * Represents a file on the filesystem.
 * A File instance can be created for any path, and does not need to exist during creation.
 */
class File implements Blob {
  /**
   * Creates an instance of a file
   * @param uris An array of string URIs, File instances, and Directory instances
   */
  constructor(...uris: (string | File | Directory)[]);
  
  /** File URI - read-only but may change after move operations */
  readonly uri: string;
  /** File name including extension */
  readonly name: string;
  /** File extension (e.g., '.png') */
  readonly extension: string;
  /** Directory containing the file */
  readonly parentDirectory: Directory;
  /** Whether the file exists and can be accessed */
  exists: boolean;
  /** File size in bytes, 0 if file doesn't exist */
  size: number;
  /** MD5 hash of the file, null if file doesn't exist */
  md5: string | null;
  /** Last modification time in milliseconds since epoch */
  modificationTime: number | null;
  /** Creation time in milliseconds since epoch */
  creationTime: number | null;
  /** MIME type of the file */
  type: string;
}

/**
 * Retrieves text content from the file asynchronously
 * @returns Promise resolving to file contents as string
 */
text(): Promise<string>;

/**
 * Retrieves text content from the file synchronously
 * @returns File contents as string
 */
textSync(): string;

/**
 * Retrieves file content as base64 synchronously
 * @returns Base64 string
 */
base64(): string;

/**
 * Retrieves file content as base64 synchronously
 * @returns Base64 string
 */
base64Sync(): string;

/**
 * Retrieves byte content of the entire file asynchronously
 * @returns Promise resolving to Uint8Array
 */
bytes(): Promise<Uint8Array<ArrayBuffer>>;

/**
 * Retrieves byte content of the entire file synchronously
 * @returns Uint8Array containing file bytes
 */
bytesSync(): Uint8Array;

import { File, Paths } from "expo-file-system";

const file = new File(Paths.document, "example.txt");

// Read as text
const content = await file.text();
console.log(content);

// Read as base64 (useful for images)
const base64 = await file.base64();
console.log(`data:image/png;base64,${base64}`);

// Read as bytes for binary processing
const bytes = await file.bytes();
console.log(`File size: ${bytes.length} bytes`);

// Synchronous reading (be careful with large files)
if (file.exists) {
  const quickRead = file.textSync();
  console.log(quickRead);
}

/**
 * Writes content to the file
 * @param content String or byte array content to write
 */
write(content: string | Uint8Array): void;

/**
 * Creates a file with optional configuration
 * @param options File creation options
 */
create(options?: FileCreateOptions): void;

interface FileCreateOptions {
  /** Whether to create intermediate directories if they don't exist */
  intermediates?: boolean;
  /** Whether to overwrite the file if it exists */
  overwrite?: boolean;
}

import { File, Paths } from "expo-file-system";

const file = new File(Paths.document, "data.txt");

// Write text content
file.write("Hello, World!");

// Write binary content
const binaryData = new Uint8Array([0x48, 0x65, 0x6c, 0x6c, 0x6f]);
file.write(binaryData);

// Create file with intermediate directories
const nestedFile = new File(Paths.document, "nested", "subdirs", "file.txt");
nestedFile.create({ intermediates: true });
nestedFile.write("Content in nested directory");

// Safe overwrite
const existingFile = new File(Paths.document, "existing.txt");
existingFile.create({ overwrite: true });
existingFile.write("Overwritten content");

/**
 * Copies a file to a new location
 * @param destination Target directory or file path
 */
copy(destination: Directory | File): void;

/**
 * Moves a file to a new location, updating the uri property
 * @param destination Target directory or file path
 */
move(destination: Directory | File): void;

/**
 * Renames a file in the same directory
 * @param newName New file name including extension
 */
rename(newName: string): void;

/**
 * Deletes the file
 * @throws Error if file doesn't exist or cannot be deleted
 */
delete(): void;

import { File, Directory, Paths } from "expo-file-system";

const sourceFile = new File(Paths.document, "source.txt");
const backupDir = new Directory(Paths.document, "backup");

// Copy file to backup directory
sourceFile.copy(backupDir);

// Move file to different location
const archiveDir = new Directory(Paths.document, "archive");
sourceFile.move(archiveDir);

// Rename file
sourceFile.rename("renamed-source.txt");

// Delete file
if (sourceFile.exists) {
  sourceFile.delete();
}

/**
 * Retrieves detailed file metadata
 * @param options Options for metadata retrieval
 * @returns File information object
 */
info(options?: InfoOptions): FileInfo;

interface InfoOptions {
  /** Whether to calculate and return MD5 hash */
  md5?: boolean;
}

interface FileInfo {
  /** Whether the file exists */
  exists: boolean;
  /** File URI */
  uri?: string;
  /** File size in bytes */
  size?: number;
  /** Last modification time in milliseconds since epoch */
  modificationTime?: number;
  /** Creation time in milliseconds since epoch */
  creationTime?: number;
  /** MD5 hash if requested */
  md5?: string;
}

import { File, Paths } from "expo-file-system";

const file = new File(Paths.document, "document.pdf");

// Get basic file info
const info = file.info();
console.log(`File exists: ${info.exists}`);
console.log(`File size: ${info.size} bytes`);

// Get file info with MD5 hash
const detailedInfo = file.info({ md5: true });
console.log(`MD5 checksum: ${detailedInfo.md5}`);

// Check modification time
if (info.modificationTime) {
  const lastModified = new Date(info.modificationTime);
  console.log(`Last modified: ${lastModified.toISOString()}`);
}

/**
 * Opens a file handle for streaming operations
 * @returns FileHandle for low-level read/write operations
 * @throws Error if file doesn't exist or cannot be opened
 */
open(): FileHandle;

/**
 * Creates a readable stream for the file
 * @returns ReadableStream for streaming file content
 */
readableStream(): ReadableStream<Uint8Array>;

/**
 * Creates a writable stream for the file
 * @returns WritableStream for streaming content to file
 */
writableStream(): WritableStream<Uint8Array>;

import { File, Paths } from "expo-file-system";

const largeFile = new File(Paths.document, "large-video.mp4");

// Stream reading large file
const readableStream = largeFile.readableStream();
const reader = readableStream.getReader();

while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  // Process chunk of data
  console.log(`Processing ${value.length} bytes`);
}

// Stream writing to file
const writableStream = largeFile.writableStream();
const writer = writableStream.getWriter();

for (const chunk of dataChunks) {
  await writer.write(new Uint8Array(chunk));
}
await writer.close();

/**
 * Returns file content as ArrayBuffer
 * @returns Promise resolving to ArrayBuffer
 */
arrayBuffer(): Promise<ArrayBuffer>;

/**
 * Returns a readable stream of the file content
 * @returns ReadableStream of Uint8Array chunks
 */
stream(): ReadableStream<Uint8Array<ArrayBuffer>>;

/**
 * Creates a new Blob containing a subset of the file data
 * @param start Starting byte position
 * @param end Ending byte position
 * @param contentType MIME type for the new blob
 * @returns New Blob with sliced content
 */
slice(start?: number, end?: number, contentType?: string): Blob;

import { File, Paths } from "expo-file-system";

const imageFile = new File(Paths.document, "photo.jpg");

// Use as Blob for web APIs
const arrayBuffer = await imageFile.arrayBuffer();
const blob = new Blob([arrayBuffer], { type: "image/jpeg" });

// Create thumbnail by slicing first 1KB
const headerSlice = imageFile.slice(0, 1024, "image/jpeg");

// Stream processing
const stream = imageFile.stream();
const response = new Response(stream);
const processedData = await response.json();