FileManager#

The FileManager module provides a unified interface for interacting with the file system in Scripting. It serves as the primary API for accessing local files, iCloud files, App Group shared storage, and performing common file operations such as reading, writing, copying, moving, deleting, zipping, and unzipping.

#Core Properties

#FileManager.scriptsDirectory: string

Returns the directory path where script files are stored within the Scripting app.

#FileManager.isiCloudEnabled: boolean

Indicates whether iCloud is enabled for the user. Returns false if:

• The user is not logged into iCloud, or
• iCloud permissions have not been granted to the Scripting app.

#FileManager.iCloudDocumentsDirectory: string

Returns the path to the iCloud Documents directory. Throws an error if iCloud is disabled. Always check isiCloudEnabled before calling.

#FileManager.appGroupDocumentsDirectory: string

Returns the path to the shared App Group Documents directory. Files stored here are not accessible in the Files app, but scripts running inside Widgets can access them.

#FileManager.documentsDirectory: string

Returns the path to the local Documents directory. Files stored here are visible in the Files app. Widgets cannot access files in this directory.

#FileManager.temporaryDirectory: string

Returns the path to the system temporary directory. Files stored here may be removed automatically by the system.

#iCloud File Management

#FileManager.isFileStoredIniCloud(filePath: string): boolean

Checks whether the specified file is stored in iCloud.

#FileManager.isiCloudFileDownloaded(filePath: string): boolean

Checks whether an iCloud-stored file has been downloaded to the device.

#FileManager.downloadFileFromiCloud(filePath: string): Promise<boolean>

Downloads an iCloud file to the device.

Example:

if (FileManager.isiCloudEnabled) {
  const file = FileManager.iCloudDocumentsDirectory + "/data.json";
  const success = await FileManager.downloadFileFromiCloud(file);
}

#FileManager.getShareUrlOfiCloudFile(path: string, expiration?: number): string

Generates a shareable download URL for an iCloud file.

This call may throw an error. Use try-catch for error handling.

#Directory and File Operations

All operations are available in both asynchronous and synchronous forms. Synchronous methods block execution; asynchronous versions are recommended for most use cases.

#Create Directory

#createDirectory(path: string, recursive?: boolean): Promise<void>

#createDirectorySync(path: string, recursive?: boolean): void

#Create Symbolic Link

#createLink(path: string, target: string): Promise<void>

#createLinkSync(path: string, target: string): void

Creates a symbolic link at path pointing to target.

#Copy File

#copyFile(path: string, newPath: string): Promise<void>

#copyFileSync(path: string, newPath: string): void

#Read Directory

#readDirectory(path: string, recursive?: boolean): Promise<string[]>

#readDirectorySync(path: string, recursive?: boolean): string[]

Enumerates the contents of a directory and optionally recurses into subdirectories.

#Check Existence

#exists(path: string): Promise<boolean>

#existsSync(path: string): boolean

Checks whether a file or directory exists.

#File Bookmarks

Bookmarks allow persistent access to user-authorized external files or folders.

#Determine File Type

#File Reading and Writing

Supports three data formats: string, Uint8Array, and Data.

#Read File

#Write File

Existing files will be overwritten.

#Append to File

If the file or its parent directory does not exist, it will be created automatically.

#File Information and Management

#stat(path: string): Promise<FileStat>

#statSync(path: string): FileStat

Returns a FileStat object for the file or directory. If the path is a symbolic link, the resolved target is reported.

#rename / renameSync

Moves or renames a file or directory.

#remove / removeSync

Removes a file or directory. Directories are removed recursively.

#Compression and Extraction

#zip(srcPath: string, destPath: string, shouldKeepParent?: boolean): Promise<void>

#zipSync(srcPath: string, destPath: string, shouldKeepParent?: boolean): void

Creates a zip archive from a file or directory.

#unzip(srcPath: string, destPath: string): Promise<void>

#unzipSync(srcPath: string, destPath: string): void

Extracts a zip archive to the specified destination.

Example:

const docs = FileManager.documentsDirectory;

await FileManager.zip(docs + "/MyScript", docs + "/MyScript.zip");
await FileManager.unzip(docs + "/MyScript.zip", docs + "/Output");

#Utility Methods

#mimeType(path: string): string

Returns the MIME type of the file based on its extension.

#destinationOfSymbolicLink(path: string): string

Returns the destination of a symbolic link.

#Types

#FileStat

type FileStat = {
  creationDate: number;
  modificationDate: number;
  type: string; // "file" | "directory" | "link" | "unixDomainSock" | "pipe" | "notFound"
  size: number;
};