# Browser FS API reference

> Exports of @anymux/browser-fs.

Source: https://anymux-docs.n.yatsyk.com/docs/browser-fs/jsdoc

## Classes

### BrowserFileSystemImplementation

```ts
class BrowserFileSystemImplementation
```

- `constants: FSConstants`
- `constructor(options?: { encoding?: string; }): BrowserFileSystemImplementation`
- `getInfo(): BrowserFsInfo | null` — Get serializable information about this file system instance
- `setInfo(info: BrowserFsInfo): void` — Set serializable information for this file system instance
- `initialize(options?: { id?: string; startIn?: FileSystemHandle | "desktop" | "documents" | "downloads" | "music" | "pictures" | "videos"; mode?: "read" | "readwrite"; }): Promise<void>` — Initialize the file system by requesting a directory from the user
- `initializeWithHandle(handle: FileSystemDirectoryHandle, fsInfo: BrowserFsInfo): Promise<void>` — Initialize file system with an existing directory handle
- `readFile(path: string, options?: { encoding?: BufferEncoding; flag?: string; } | BufferEncoding): Promise<Buffer | string>`
- `writeFile(path: string, data: Buffer | string | Uint8Array, options?: { encoding?: BufferEncoding; mode?: number; flag?: string; }): Promise<void>`
- `mkdir(path: string, options?: { recursive?: boolean; mode?: number; }): Promise<string | undefined>`
- `readdir(path: string, options?: { encoding?: BufferEncoding; withFileTypes?: false; recursive?: boolean; }): Promise<string[]>`
- `readdir(path: string, options: { encoding?: BufferEncoding; withFileTypes: true; recursive?: boolean; }): Promise<Dirent[]>`
- `readdir(path: string, options?: { encoding?: BufferEncoding; withFileTypes?: boolean; recursive?: boolean; }): Promise<string[] | Dirent[]>`
- `exists(path: string): Promise<boolean>`
- `stat(path: string, options?: { bigint?: false; }): Promise<Stats>`
- `stat(path: string, options: { bigint: true; }): Promise<BigIntStats>`
- `stat(path: string, options?: { bigint?: boolean; }): Promise<Stats | BigIntStats>`
- `unlink(path: string): Promise<void>`
- `rmdir(path: string, options?: { recursive?: boolean; }): Promise<void>`
- `init(options?: { encoding?: string; handle?: FileSystemDirectoryHandle; id?: string; name?: string; rootPath?: string; }): Promise<void>`
- `appendFile(path: string, data: Buffer | string | Uint8Array, options?: { encoding?: BufferEncoding; mode?: number; flag?: string; }): Promise<void>`
- `copyFile(src: string, dest: string, mode?: number): Promise<void>`
- `lstat(path: string, options?: { bigint?: false; }): Promise<Stats>`
- `lstat(path: string, options: { bigint: true; }): Promise<BigIntStats>`
- `lstat(path: string, options?: { bigint?: boolean; }): Promise<Stats | BigIntStats>`
- `rename(oldPath: string, newPath: string): Promise<void>`
- `access(path: string, mode?: number): Promise<void>`
- `rm(path: string, options?: { force?: boolean; maxRetries?: number; recursive?: boolean; retryDelay?: number; }): Promise<void>`
- `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(prefix: string, options?: { encoding?: BufferEncoding; }): Promise<string>`
- `opendir(path: string, options?: { encoding?: BufferEncoding; bufferSize?: number; recursive?: boolean; }): Promise<IDir>`
- `open(path: string, flags?: string | number, mode?: number): Promise<IFileHandle>`
- `realpath(path: string, options?: { encoding?: BufferEncoding; }): Promise<string>`
- `statfs(path: string, options?: { bigint?: false; }): Promise<StatFs>`
- `statfs(path: string, options: { bigint: true; }): Promise<BigIntStatFs>`
- `statfs(path: string, options?: { bigint?: boolean; }): Promise<StatFs | BigIntStatFs>`
- `lutimes(path: string, atime: string | number | Date, mtime: string | number | Date): Promise<void>`
- `lchown(path: string, uid: number, gid: number): Promise<void>`
- `lchmod(path: string, mode: string | number): Promise<void>`
- `truncate(path: string, len?: number): Promise<void>`
- `utimes(path: string, atime: string | number | Date, mtime: string | number | Date): Promise<void>`
- `chmod(path: string, mode: string | number): Promise<void>`
- `chown(path: string, uid: number, gid: number): Promise<void>`
- `readlink(path: string, options?: { encoding?: BufferEncoding; }): Promise<string>`
- `symlink(target: string, path: string, type?: "dir" | "file" | "junction"): Promise<void>`
- `link(existingPath: string, newPath: string): Promise<void>`
- `isImplemented(feature: string): boolean`
- `createReadStream(path: string, options?: { encoding?: BufferEncoding; start?: number; end?: number; }): ReadStream`
- `createWriteStream(path: string, options?: { encoding?: BufferEncoding; flags?: string; mode?: number; }): WriteStream`
- `watch(path: string, options?: { encoding?: BufferEncoding; persistent?: boolean; recursive?: boolean; }): FSWatcher`

### BrowserFileSystemFactory

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.

```ts
class BrowserFileSystemFactory
```

- `getInstance(): BrowserFileSystemFactory` — Get the singleton instance of the factory
- `debugDumpDatabase(): Promise<void>` — Debug method to dump database contents for diagnostics
- `getAllHandleInfos(): Promise<BrowserFsHandleInfo[]>` — Get all stored handle info objects
- `updateLastAccessed(id: string): Promise<void>` — Update the last accessed timestamp for a handle
- `saveHandleWithId(id: string, name: string, fs: BrowserFileSystemImplementation): Promise<BrowserFsHandleInfo>` — Save a file system with a specified ID
- `removeHandle(id: string): Promise<void>` — Remove a handle from storage
- `createFromPicker(options?: { encoding?: string; }, pickerOptions?: { id?: string; name?: string; startIn?: FileSystemHandle | "desktop" | "documents" | "downloads" | "music" | "pictures" | "videos"; mode?: "read" | "readwrite"; }): Promise<[BrowserFileSystemImplementation, BrowserFsHandleInfo]>` — Create a browser file system by showing a directory picker to the user
- `createFromHandleInfo(id: string, options?: { encoding?: string; }): Promise<BrowserFileSystemImplementation | null>` — Create a browser file system from a previously saved handle

### HandleStore

Storage for file system handles to avoid requesting permissions repeatedly

```ts
class HandleStore
```

- `setRootHandle(handle: FileSystemDirectoryHandle): void`
- `getRootHandle(): FileSystemDirectoryHandle | null`
- `getHandle(path: string): FileSystemHandle | undefined`
- `setHandle(path: string, handle: FileSystemHandle): void`
- `removeHandle(path: string): void`
- `clear(): void`

### FileSystemAccessAPI

```ts
class FileSystemAccessAPI
```

- `constants: FSConstants`
- `constructor(options?: { encoding?: string; }): BrowserFileSystemImplementation`
- `getInfo(): BrowserFsInfo | null` — Get serializable information about this file system instance
- `setInfo(info: BrowserFsInfo): void` — Set serializable information for this file system instance
- `initialize(options?: { id?: string; startIn?: FileSystemHandle | "desktop" | "documents" | "downloads" | "music" | "pictures" | "videos"; mode?: "read" | "readwrite"; }): Promise<void>` — Initialize the file system by requesting a directory from the user
- `initializeWithHandle(handle: FileSystemDirectoryHandle, fsInfo: BrowserFsInfo): Promise<void>` — Initialize file system with an existing directory handle
- `readFile(path: string, options?: { encoding?: BufferEncoding; flag?: string; } | BufferEncoding): Promise<Buffer | string>`
- `writeFile(path: string, data: Buffer | string | Uint8Array, options?: { encoding?: BufferEncoding; mode?: number; flag?: string; }): Promise<void>`
- `mkdir(path: string, options?: { recursive?: boolean; mode?: number; }): Promise<string | undefined>`
- `readdir(path: string, options?: { encoding?: BufferEncoding; withFileTypes?: false; recursive?: boolean; }): Promise<string[]>`
- `readdir(path: string, options: { encoding?: BufferEncoding; withFileTypes: true; recursive?: boolean; }): Promise<Dirent[]>`
- `readdir(path: string, options?: { encoding?: BufferEncoding; withFileTypes?: boolean; recursive?: boolean; }): Promise<string[] | Dirent[]>`
- `exists(path: string): Promise<boolean>`
- `stat(path: string, options?: { bigint?: false; }): Promise<Stats>`
- `stat(path: string, options: { bigint: true; }): Promise<BigIntStats>`
- `stat(path: string, options?: { bigint?: boolean; }): Promise<Stats | BigIntStats>`
- `unlink(path: string): Promise<void>`
- `rmdir(path: string, options?: { recursive?: boolean; }): Promise<void>`
- `init(options?: { encoding?: string; handle?: FileSystemDirectoryHandle; id?: string; name?: string; rootPath?: string; }): Promise<void>`
- `appendFile(path: string, data: Buffer | string | Uint8Array, options?: { encoding?: BufferEncoding; mode?: number; flag?: string; }): Promise<void>`
- `copyFile(src: string, dest: string, mode?: number): Promise<void>`
- `lstat(path: string, options?: { bigint?: false; }): Promise<Stats>`
- `lstat(path: string, options: { bigint: true; }): Promise<BigIntStats>`
- `lstat(path: string, options?: { bigint?: boolean; }): Promise<Stats | BigIntStats>`
- `rename(oldPath: string, newPath: string): Promise<void>`
- `access(path: string, mode?: number): Promise<void>`
- `rm(path: string, options?: { force?: boolean; maxRetries?: number; recursive?: boolean; retryDelay?: number; }): Promise<void>`
- `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(prefix: string, options?: { encoding?: BufferEncoding; }): Promise<string>`
- `opendir(path: string, options?: { encoding?: BufferEncoding; bufferSize?: number; recursive?: boolean; }): Promise<IDir>`
- `open(path: string, flags?: string | number, mode?: number): Promise<IFileHandle>`
- `realpath(path: string, options?: { encoding?: BufferEncoding; }): Promise<string>`
- `statfs(path: string, options?: { bigint?: false; }): Promise<StatFs>`
- `statfs(path: string, options: { bigint: true; }): Promise<BigIntStatFs>`
- `statfs(path: string, options?: { bigint?: boolean; }): Promise<StatFs | BigIntStatFs>`
- `lutimes(path: string, atime: string | number | Date, mtime: string | number | Date): Promise<void>`
- `lchown(path: string, uid: number, gid: number): Promise<void>`
- `lchmod(path: string, mode: string | number): Promise<void>`
- `truncate(path: string, len?: number): Promise<void>`
- `utimes(path: string, atime: string | number | Date, mtime: string | number | Date): Promise<void>`
- `chmod(path: string, mode: string | number): Promise<void>`
- `chown(path: string, uid: number, gid: number): Promise<void>`
- `readlink(path: string, options?: { encoding?: BufferEncoding; }): Promise<string>`
- `symlink(target: string, path: string, type?: "dir" | "file" | "junction"): Promise<void>`
- `link(existingPath: string, newPath: string): Promise<void>`
- `isImplemented(feature: string): boolean`
- `createReadStream(path: string, options?: { encoding?: BufferEncoding; start?: number; end?: number; }): ReadStream`
- `createWriteStream(path: string, options?: { encoding?: BufferEncoding; flags?: string; mode?: number; }): WriteStream`
- `watch(path: string, options?: { encoding?: BufferEncoding; persistent?: boolean; recursive?: boolean; }): FSWatcher`

### default

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.

```ts
class default
```

- `getInstance(): BrowserFileSystemFactory` — Get the singleton instance of the factory
- `debugDumpDatabase(): Promise<void>` — Debug method to dump database contents for diagnostics
- `getAllHandleInfos(): Promise<BrowserFsHandleInfo[]>` — Get all stored handle info objects
- `updateLastAccessed(id: string): Promise<void>` — Update the last accessed timestamp for a handle
- `saveHandleWithId(id: string, name: string, fs: BrowserFileSystemImplementation): Promise<BrowserFsHandleInfo>` — Save a file system with a specified ID
- `removeHandle(id: string): Promise<void>` — Remove a handle from storage
- `createFromPicker(options?: { encoding?: string; }, pickerOptions?: { id?: string; name?: string; startIn?: FileSystemHandle | "desktop" | "documents" | "downloads" | "music" | "pictures" | "videos"; mode?: "read" | "readwrite"; }): Promise<[BrowserFileSystemImplementation, BrowserFsHandleInfo]>` — Create a browser file system by showing a directory picker to the user
- `createFromHandleInfo(id: string, options?: { encoding?: string; }): Promise<BrowserFileSystemImplementation | null>` — Create a browser file system from a previously saved handle

## Functions

### isFileSystemAccessAPISupported

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

```ts
isFileSystemAccessAPISupported(): boolean
```

### checkCapabilities

Checks if the File System Access API has specific capabilities

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

### pathToHandles

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

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

### createBuffer

Create a Buffer from an ArrayBuffer

```ts
createBuffer(arrayBuffer: ArrayBuffer): Buffer
```

### convertToRelativePath

Convert an absolute path to a path relative to the root

```ts
convertToRelativePath(path: string): string
```

### createLogger

```ts
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

Create a complete Stats object for browser filesystem

```ts
createStatsObject(options: CreateStatsOptions): Stats
```

### createDirentObject

Create a Dirent object for browser filesystem

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

### initializeDatabase

Initialize IndexedDB for storing directory handles

```ts
initializeDatabase(): Promise<IDBDatabase>
```

### saveDirectoryHandle

Save a directory handle to IndexedDB

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

### getDirectoryHandle

Retrieve a handle from IndexedDB

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

### getAllHandleInfos

Get all stored handle info objects

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

### updateLastAccessedTimestamp

Update the last accessed timestamp for a handle

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

### removeDirectoryHandle

Remove a handle from storage

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

### getFullHandleInfo

Get the full handle info record from IndexedDB

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

## Types

### BrowserFsInfo

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

### BrowserFsHandleInfo

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

## Constants

### browserFsInfoSchema

```ts
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

```ts
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

```ts
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

```ts
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; }
```