Browser FS API reference

Classes

BrowserFileSystemImplementation

class

class BrowserFileSystemImplementation

constants

property

constants: FSConstants

constructor

constructor(options?: { encoding?: string; }): BrowserFileSystemImplementation

getInfo

method

Get serializable information about this file system instance

getInfo(): BrowserFsInfo | null

setInfo

method

Set serializable information for this file system instance

setInfo(info: BrowserFsInfo): void

initialize

method

Initialize the file system by requesting a directory from the user

initialize(options?: { id?: string; startIn?: FileSystemHandle | "desktop" | "documents" | "downloads" | "music" | "pictures" | "videos"; mode?: "read" | "readwrite"; }): Promise<void>

initializeWithHandle

method

Initialize file system with an existing directory handle

initializeWithHandle(handle: FileSystemDirectoryHandle, fsInfo: BrowserFsInfo): Promise<void>

readFile

method

readFile(path: string, options?: { encoding?: BufferEncoding; flag?: string; } | BufferEncoding): Promise<Buffer | string>

writeFile

method

writeFile(path: string, data: Buffer | string | Uint8Array, options?: { encoding?: BufferEncoding; mode?: number; flag?: string; }): Promise<void>

mkdir

method

mkdir(path: string, options?: { recursive?: boolean; mode?: number; }): Promise<string | undefined>

readdir

method

readdir(path: string, options?: { encoding?: BufferEncoding; withFileTypes?: false; recursive?: boolean; }): Promise<string[]>

readdir

method

readdir(path: string, options: { encoding?: BufferEncoding; withFileTypes: true; recursive?: boolean; }): Promise<Dirent[]>

readdir

method

readdir(path: string, options?: { encoding?: BufferEncoding; withFileTypes?: boolean; recursive?: boolean; }): Promise<string[] | Dirent[]>

exists

method

exists(path: string): Promise<boolean>

stat

method

stat(path: string, options?: { bigint?: false; }): Promise<Stats>

stat

method

stat(path: string, options: { bigint: true; }): Promise<BigIntStats>

stat

method

stat(path: string, options?: { bigint?: boolean; }): Promise<Stats | BigIntStats>

unlink

method

unlink(path: string): Promise<void>

rmdir

method

rmdir(path: string, options?: { recursive?: boolean; }): Promise<void>

init

method

init(options?: { encoding?: string; handle?: FileSystemDirectoryHandle; id?: string; name?: string; rootPath?: string; }): Promise<void>

appendFile

method

appendFile(path: string, data: Buffer | string | Uint8Array, options?: { encoding?: BufferEncoding; mode?: number; flag?: string; }): Promise<void>

copyFile

method

copyFile(src: string, dest: string, mode?: number): Promise<void>

lstat

method

lstat(path: string, options?: { bigint?: false; }): Promise<Stats>

lstat

method

lstat(path: string, options: { bigint: true; }): Promise<BigIntStats>

lstat

method

lstat(path: string, options?: { bigint?: boolean; }): Promise<Stats | BigIntStats>

rename

method

rename(oldPath: string, newPath: string): Promise<void>

access

method

access(path: string, mode?: number): Promise<void>

rm

method

rm(path: string, options?: { force?: boolean; maxRetries?: number; recursive?: boolean; retryDelay?: number; }): Promise<void>

cp

method

cp(src: string, dest: string, options?: { dereference?: boolean; errorOnExist?: boolean; filter?: (src: string, dest: string) => boolean | Promise<boolean>; force?: boolean; mode?: number; preserveTimestamps?: boolean; recursive?: boolean; verbatimSymlinks?: boolean; }): Promise<void>

mkdtemp

method

mkdtemp(prefix: string, options?: { encoding?: BufferEncoding; }): Promise<string>

opendir

method

opendir(path: string, options?: { encoding?: BufferEncoding; bufferSize?: number; recursive?: boolean; }): Promise<IDir>

open

method

open(path: string, flags?: string | number, mode?: number): Promise<IFileHandle>

realpath

method

realpath(path: string, options?: { encoding?: BufferEncoding; }): Promise<string>

statfs

method

statfs(path: string, options?: { bigint?: false; }): Promise<StatFs>

statfs

method

statfs(path: string, options: { bigint: true; }): Promise<BigIntStatFs>

statfs

method

statfs(path: string, options?: { bigint?: boolean; }): Promise<StatFs | BigIntStatFs>

lutimes

method

lutimes(path: string, atime: string | number | Date, mtime: string | number | Date): Promise<void>

lchown

method

lchown(path: string, uid: number, gid: number): Promise<void>

lchmod

method

lchmod(path: string, mode: string | number): Promise<void>

truncate

method

truncate(path: string, len?: number): Promise<void>

utimes

method

utimes(path: string, atime: string | number | Date, mtime: string | number | Date): Promise<void>

chmod

method

chmod(path: string, mode: string | number): Promise<void>

chown

method

chown(path: string, uid: number, gid: number): Promise<void>

readlink

method

readlink(path: string, options?: { encoding?: BufferEncoding; }): Promise<string>

symlink

method

symlink(target: string, path: string, type?: "dir" | "file" | "junction"): Promise<void>

link

method

link(existingPath: string, newPath: string): Promise<void>

isImplemented

method

isImplemented(feature: string): boolean

createReadStream

method

createReadStream(path: string, options?: { encoding?: BufferEncoding; start?: number; end?: number; }): ReadStream

createWriteStream

method

createWriteStream(path: string, options?: { encoding?: BufferEncoding; flags?: string; mode?: number; }): WriteStream

watch

method

watch(path: string, options?: { encoding?: BufferEncoding; persistent?: boolean; recursive?: boolean; }): FSWatcher

BrowserFileSystemFactory

class

Factory for creating BrowserFileSystemImplementation instances This factory provides methods to create file systems either by showing a directory picker to the user or by reusing a previously saved handle.

class BrowserFileSystemFactory

getInstance

method

Get the singleton instance of the factory

getInstance(): BrowserFileSystemFactory

debugDumpDatabase

method

Debug method to dump database contents for diagnostics

debugDumpDatabase(): Promise<void>

getAllHandleInfos

method

Get all stored handle info objects

getAllHandleInfos(): Promise<BrowserFsHandleInfo[]>

updateLastAccessed

method

Update the last accessed timestamp for a handle

updateLastAccessed(id: string): Promise<void>

saveHandleWithId

method

Save a file system with a specified ID

saveHandleWithId(id: string, name: string, fs: BrowserFileSystemImplementation): Promise<BrowserFsHandleInfo>

removeHandle

method

Remove a handle from storage

removeHandle(id: string): Promise<void>

createFromPicker

method

Create a browser file system by showing a directory picker to the user

createFromPicker(options?: { encoding?: string; }, pickerOptions?: { id?: string; name?: string; startIn?: FileSystemHandle | "desktop" | "documents" | "downloads" | "music" | "pictures" | "videos"; mode?: "read" | "readwrite"; }): Promise<[BrowserFileSystemImplementation, BrowserFsHandleInfo]>

createFromHandleInfo

method

Create a browser file system from a previously saved handle

createFromHandleInfo(id: string, options?: { encoding?: string; }): Promise<BrowserFileSystemImplementation | null>

HandleStore

class

Storage for file system handles to avoid requesting permissions repeatedly

class HandleStore

setRootHandle

method

setRootHandle(handle: FileSystemDirectoryHandle): void

getRootHandle

method

getRootHandle(): FileSystemDirectoryHandle | null

getHandle

method

getHandle(path: string): FileSystemHandle | undefined

setHandle

method

setHandle(path: string, handle: FileSystemHandle): void

removeHandle

method

removeHandle(path: string): void

clear

method

clear(): void

FileSystemAccessAPI

class

class FileSystemAccessAPI

constants

property

constants: FSConstants

constructor

constructor(options?: { encoding?: string; }): BrowserFileSystemImplementation

getInfo

method

Get serializable information about this file system instance

getInfo(): BrowserFsInfo | null

setInfo

method

Set serializable information for this file system instance

setInfo(info: BrowserFsInfo): void

initialize

method

Initialize the file system by requesting a directory from the user

initialize(options?: { id?: string; startIn?: FileSystemHandle | "desktop" | "documents" | "downloads" | "music" | "pictures" | "videos"; mode?: "read" | "readwrite"; }): Promise<void>

initializeWithHandle

method

Initialize file system with an existing directory handle

initializeWithHandle(handle: FileSystemDirectoryHandle, fsInfo: BrowserFsInfo): Promise<void>

readFile

method

readFile(path: string, options?: { encoding?: BufferEncoding; flag?: string; } | BufferEncoding): Promise<Buffer | string>

writeFile

method

writeFile(path: string, data: Buffer | string | Uint8Array, options?: { encoding?: BufferEncoding; mode?: number; flag?: string; }): Promise<void>

mkdir

method

mkdir(path: string, options?: { recursive?: boolean; mode?: number; }): Promise<string | undefined>

readdir

method

readdir(path: string, options?: { encoding?: BufferEncoding; withFileTypes?: false; recursive?: boolean; }): Promise<string[]>

readdir

method

readdir(path: string, options: { encoding?: BufferEncoding; withFileTypes: true; recursive?: boolean; }): Promise<Dirent[]>

readdir

method

readdir(path: string, options?: { encoding?: BufferEncoding; withFileTypes?: boolean; recursive?: boolean; }): Promise<string[] | Dirent[]>

exists

method

exists(path: string): Promise<boolean>

stat

method

stat(path: string, options?: { bigint?: false; }): Promise<Stats>

stat

method

stat(path: string, options: { bigint: true; }): Promise<BigIntStats>

stat

method

stat(path: string, options?: { bigint?: boolean; }): Promise<Stats | BigIntStats>

unlink

method

unlink(path: string): Promise<void>

rmdir

method

rmdir(path: string, options?: { recursive?: boolean; }): Promise<void>

init

method

init(options?: { encoding?: string; handle?: FileSystemDirectoryHandle; id?: string; name?: string; rootPath?: string; }): Promise<void>

appendFile

method

appendFile(path: string, data: Buffer | string | Uint8Array, options?: { encoding?: BufferEncoding; mode?: number; flag?: string; }): Promise<void>

copyFile

method

copyFile(src: string, dest: string, mode?: number): Promise<void>

lstat

method

lstat(path: string, options?: { bigint?: false; }): Promise<Stats>

lstat

method

lstat(path: string, options: { bigint: true; }): Promise<BigIntStats>

lstat

method

lstat(path: string, options?: { bigint?: boolean; }): Promise<Stats | BigIntStats>

rename

method

rename(oldPath: string, newPath: string): Promise<void>

access

method

access(path: string, mode?: number): Promise<void>

rm

method

rm(path: string, options?: { force?: boolean; maxRetries?: number; recursive?: boolean; retryDelay?: number; }): Promise<void>

cp

method

cp(src: string, dest: string, options?: { dereference?: boolean; errorOnExist?: boolean; filter?: (src: string, dest: string) => boolean | Promise<boolean>; force?: boolean; mode?: number; preserveTimestamps?: boolean; recursive?: boolean; verbatimSymlinks?: boolean; }): Promise<void>

mkdtemp

method

mkdtemp(prefix: string, options?: { encoding?: BufferEncoding; }): Promise<string>

opendir

method

opendir(path: string, options?: { encoding?: BufferEncoding; bufferSize?: number; recursive?: boolean; }): Promise<IDir>

open

method

open(path: string, flags?: string | number, mode?: number): Promise<IFileHandle>

realpath

method

realpath(path: string, options?: { encoding?: BufferEncoding; }): Promise<string>

statfs

method

statfs(path: string, options?: { bigint?: false; }): Promise<StatFs>

statfs

method

statfs(path: string, options: { bigint: true; }): Promise<BigIntStatFs>

statfs

method

statfs(path: string, options?: { bigint?: boolean; }): Promise<StatFs | BigIntStatFs>

lutimes

method

lutimes(path: string, atime: string | number | Date, mtime: string | number | Date): Promise<void>

lchown

method

lchown(path: string, uid: number, gid: number): Promise<void>

lchmod

method

lchmod(path: string, mode: string | number): Promise<void>

truncate

method

truncate(path: string, len?: number): Promise<void>

utimes

method

utimes(path: string, atime: string | number | Date, mtime: string | number | Date): Promise<void>

chmod

method

chmod(path: string, mode: string | number): Promise<void>

chown

method

chown(path: string, uid: number, gid: number): Promise<void>

readlink

method

readlink(path: string, options?: { encoding?: BufferEncoding; }): Promise<string>

symlink

method

symlink(target: string, path: string, type?: "dir" | "file" | "junction"): Promise<void>

link

method

link(existingPath: string, newPath: string): Promise<void>

isImplemented

method

isImplemented(feature: string): boolean

createReadStream

method

createReadStream(path: string, options?: { encoding?: BufferEncoding; start?: number; end?: number; }): ReadStream

createWriteStream

method

createWriteStream(path: string, options?: { encoding?: BufferEncoding; flags?: string; mode?: number; }): WriteStream

watch

method

watch(path: string, options?: { encoding?: BufferEncoding; persistent?: boolean; recursive?: boolean; }): FSWatcher

default

class

class default

getInstance

method

Get the singleton instance of the factory

getInstance(): BrowserFileSystemFactory

debugDumpDatabase

method

Debug method to dump database contents for diagnostics

debugDumpDatabase(): Promise<void>

getAllHandleInfos

method

Get all stored handle info objects

getAllHandleInfos(): Promise<BrowserFsHandleInfo[]>

updateLastAccessed

method

Update the last accessed timestamp for a handle

updateLastAccessed(id: string): Promise<void>

saveHandleWithId

method

Save a file system with a specified ID

saveHandleWithId(id: string, name: string, fs: BrowserFileSystemImplementation): Promise<BrowserFsHandleInfo>

removeHandle

method

Remove a handle from storage

removeHandle(id: string): Promise<void>

createFromPicker

method

Create a browser file system by showing a directory picker to the user

createFromPicker(options?: { encoding?: string; }, pickerOptions?: { id?: string; name?: string; startIn?: FileSystemHandle | "desktop" | "documents" | "downloads" | "music" | "pictures" | "videos"; mode?: "read" | "readwrite"; }): Promise<[BrowserFileSystemImplementation, BrowserFsHandleInfo]>

createFromHandleInfo

method

Create a browser file system from a previously saved handle

createFromHandleInfo(id: string, options?: { encoding?: string; }): Promise<BrowserFileSystemImplementation | null>

Functions

isFileSystemAccessAPISupported

function

Checks if the File System Access API is available in the current browser

isFileSystemAccessAPISupported(): boolean

checkCapabilities

function

Checks if the File System Access API has specific capabilities

checkCapabilities(): { directoryHandle: boolean; fileHandle: boolean; writableFileStream: boolean; }

pathToHandles

function

Convert a path to parent directory handle and file/directory name

pathToHandles(rootHandle: FileSystemDirectoryHandle, path: string, createParents?: boolean): Promise<{ parent: FileSystemDirectoryHandle; name: string; }>

createBuffer

function

Create a Buffer from an ArrayBuffer

createBuffer(arrayBuffer: ArrayBuffer): Buffer

convertToRelativePath

function

Convert an absolute path to a path relative to the root

convertToRelativePath(path: string): string

createLogger

function

createLogger(prefix: string, color: string): { info: (message: string, ...args: any[]) => void; error: (message: string, ...args: any[]) => void; warn: (message: string, ...args: any[]) => void; debug: (message: string, ...args: any[]) => void; table: (data: any, message?: string) => void; }

createStatsObject

function

Create a complete Stats object for browser filesystem

createStatsObject(options: CreateStatsOptions): Stats

createDirentObject

function

Create a Dirent object for browser filesystem

createDirentObject(name: string, kind: "file" | "directory"): Dirent

initializeDatabase

function

Initialize IndexedDB for storing directory handles

initializeDatabase(): Promise<IDBDatabase>

saveDirectoryHandle

function

Save a directory handle to IndexedDB

saveDirectoryHandle(db: IDBDatabase, id: string, name: string, handle: FileSystemDirectoryHandle, path?: string): Promise<BrowserFsHandleInfo>

getDirectoryHandle

function

Retrieve a handle from IndexedDB

getDirectoryHandle(db: IDBDatabase, id: string): Promise<FileSystemDirectoryHandle | null>

getAllHandleInfos

function

Get all stored handle info objects

getAllHandleInfos(db: IDBDatabase): Promise<BrowserFsHandleInfo[]>

updateLastAccessedTimestamp

function

Update the last accessed timestamp for a handle

updateLastAccessedTimestamp(db: IDBDatabase, id: string): Promise<void>

removeDirectoryHandle

function

Remove a handle from storage

removeDirectoryHandle(db: IDBDatabase, id: string): Promise<void>

getFullHandleInfo

function

Get the full handle info record from IndexedDB

getFullHandleInfo(db: IDBDatabase, id: string): Promise<{ id: string; name: string; path?: string; handle: FileSystemDirectoryHandle; lastAccessed: number; version: string; } | null>

Types

BrowserFsInfo

type

type BrowserFsInfo = { version?: "1.0.0"; id?: string; name?: string; rootPath?: string; }

BrowserFsHandleInfo

type

type BrowserFsHandleInfo = { version?: "1.0.0"; path?: string; id?: string; name?: string; lastAccessed?: number; }

Constants

browserFsInfoSchema

const

const browserFsInfoSchema: z.ZodObject<{ version: z.ZodLiteral<"1.0.0">; id: z.ZodString; name: z.ZodString; rootPath: z.ZodOptional<z.ZodString>; }, "strip", z.ZodTypeAny, { version?: "1.0.0"; id?: string; name?: string; rootPath?: string; }, { version?: "1.0.0"; id?: string; name?: string; rootPath?: string; }>

browserFsHandleInfoSchema

const

const browserFsHandleInfoSchema: z.ZodObject<{ version: z.ZodLiteral<"1.0.0">; id: z.ZodString; name: z.ZodString; path: z.ZodOptional<z.ZodString>; lastAccessed: z.ZodNumber; }, "strip", z.ZodTypeAny, { version?: "1.0.0"; path?: string; id?: string; name?: string; lastAccessed?: number; }, { version?: "1.0.0"; path?: string; id?: string; name?: string; lastAccessed?: number; }>

implementationLogger

const

const implementationLogger: { info: (message: string, ...args: any[]) => void; error: (message: string, ...args: any[]) => void; warn: (message: string, ...args: any[]) => void; debug: (message: string, ...args: any[]) => void; table: (data: any, message?: string) => void; }

factoryLogger

const

const factoryLogger: { info: (message: string, ...args: any[]) => void; error: (message: string, ...args: any[]) => void; warn: (message: string, ...args: any[]) => void; debug: (message: string, ...args: any[]) => void; table: (data: any, message?: string) => void; }